IBM Cloud Code Engine CLI

Run these commands to manage the entities that make up IBM Cloud® Code Engine. For more information about Code Engine, see Getting started with Code Engine.

To run IBM Cloud Code Engine commands, use ibmcloud code-engine or ibmcloud ce.

Prerequisites

Install the IBM Cloud CLI.
Install the Code Engine CLI by running the following command:
```
ibmcloud plugin install code-engine
```

Application commands

An application, or app, runs your code to serve HTTP requests. In addition to traditional HTTP requests, IBM Cloud® Code Engine also supports applications that use WebSockets as their communications protocol. The number of running instances of an app are automatically scaled up or down (to zero) based on incoming requests and your configuration settings. An app contains one or more revisions. A revision represents an immutable version of the configuration properties of the app. Each update of an app configuration property creates a new revision of the app.

You must be within the context of a project before you use application commands.

For more information about working with apps, see Deploying applications.

You can use either application or app in your application commands. To see CLI help for the application commands, run ibmcloud ce app -h.

To manage application revisions, see the ibmcloud ce revision commands.

`ibmcloud ce application bind`

Bind an IBM Cloud service instance to an application.

ibmcloud ce application bind --name APP_NAME (--service-instance SI_NAME | --service-instance-id SI_ID)  [--no-wait] [--prefix PREFIX] [--quiet] [--role ROLE] [--service-credential SERVICE_CREDENTIAL] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--name, -n: The name of the application to bind. This value is required.
--no-wait, --nw: Bind the service instance and do not wait for the service binding to be ready. If you specify the no-wait option, the service binding creation is started and the command exits without waiting for it to complete. Use the app get command to check the application bind status. This value is optional. The default value is false.
--prefix, -p: A prefix for environment variables that are created for this service binding. Must contain only uppercase letters, numbers, and underscores (_), and cannot start with a number. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--role, -r: The name of a service role for the new service credential that is created for this service binding. Valid values include Reader, Writer, Manager, or a service-specific role. The option defaults to Manager or the first role provided by the service if Manager is not supported. This option is ignored if --service-credential is specified. This value is optional.
--service-credential, --sc: The name of an existing service credential to use for this service binding. If you do not specify a service instance credential, new credentials are generated during the bind action. This value is optional.
--service-instance, --si: The name of an existing IBM Cloud service instance to bind to the application. This value is optional.
--service-instance-id, --siid: The GUID of an existing IBM Cloud service instance to bind to the application. This value is optional.
--wait, -w: Bind the service instance and wait for the service binding to be ready. If you specify the --wait option, the application bind waits for a maximum time in seconds, as set by the --wait-timeout option, for the app bind to complete successfully. If the app bind is not completed successfully or fails within the specified --wait-timeout period, the command fails. This value is optional. The default value is true.
--wait-timeout, --wto: The length of time in seconds to wait for the service binding to be ready. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 300.

Example

In this example, bind your IBM Cloud Object Storage service instance called my-object-storage to your application called myapp.

ibmcloud ce application bind --name myapp --service-instance my-object-storage

Example output

Binding service instance...
Waiting for service binding to become ready...
Status: Pending (Processing Resource)
Status: Pending (Processing Resource)
Status: Creating service binding
Status: Creating service binding
Status: Ready
Waiting for application revision to become ready...
Traffic is not yet migrated to the latest revision.
Ingress has not yet been reconciled.
Waiting for load balancer to be ready
OK

`ibmcloud ce application create`

Create an application.

ibmcloud ce application create --name APP_NAME ((--image IMAGE_REF | (--build-source SOURCE [--image IMAGE_REF])) [--argument ARGUMENT] [--build-commit BUILD_COMMIT] [--build-context-dir BUILD_CONTEXT_DIR] [--build-dockerfile BUILD_DOCKERFILE] [--build-git-repo-secret BUILD_GIT_REPO_SECRET] [--build-size BUILD_SIZE] [--build-strategy BUILD_STRATEGY] [--build-timeout BUILD_TIMEOUT] [--cluster-local] [--command COMMAND] [--concurrency CONCURRENCY] [--concurrency-target CONCURRENCY_TARGET] [--cpu CPU] [--env ENV] [--env-from-configmap ENV_FROM_CONFIGMAP] [--env-from-secret ENV_FROM_SECRET] [--ephemeral-storage EPHEMERAL_STORAGE] [--force] [--max-scale MAX_SCALE] [--memory MEMORY] [--min-scale MIN_SCALE] [--mount-configmap MOUNT_CONFIGMAP] [--mount-secret MOUNT_SECRET] [--no-cluster-local] [--no-wait] [--output OUTPUT] [--port PORT] [--probe-live PROBE_LIVE] [--probe-ready PROBE_READY] [--quiet] [--registry-secret REGISTRY_SECRET] [--request-timeout REQUEST_TIMEOUT] [--revision-name REVISION_NAME] [--scale-down-delay SCALE_DOWN_DELAY] [--service-account SERVICE_ACCOUNT] [--user USER] [--visibility VISIBILITY] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

-n, --name

The name of the application. Use a name that is unique within the project.

The name must begin with a lowercase letter.
The name must end with a lowercase alphanumeric character.
The name must be 63 characters or fewer and can contain lowercase letters, numbers, and hyphens (-).

This value is required.

--argument, --arg, -a

Set arguments for the application. Specify one argument per --argument option; for example, -a argA -a argB. This value overrides the default values that are specified within the container image. This value is optional.

--build-commit, --commit, --bcm, --cm, --revision

The commit, tag, or branch in the source repository to pull. The build commit option is allowed only if the --build-source option is set. This value is optional.

--build-context-dir, --context-dir, --bcdr, --cdr

The directory in the repository that contains the buildpacks file or the Dockerfile. The build context directory option is allowed only if the --build-source option is set. This value is optional.

--build-dockerfile, --dockerfile, --bdf, --df

The path to the Dockerfile. Specify this option only if the name is other than Dockerfile. The build dockerfile option is allowed only if the --build-source option is set. This value is optional. The default value is Dockerfile.

--build-git-repo-secret, --git-repo-secret, --bgrs, --grs, --repo

The name of the SSH secret, which contains the credentials to access the private repository that contains the source code to build your container image. To create this SSH secret, use the secret create --format SSH command. An SSH secret is also used as a Git repository access secret. This option is allowed only if the --build-source option is set to the URL of a Git repository. This value is optional.

--build-size, --size, --bsz, --sz

The size for the build, which determines the amount of resources used. Valid values are small, medium, large, xlarge, and xxlarge. For details, see Determining the size of the build. The build size option is allowed only if the --build-source option is set. This value is optional. The default value is medium.

--build-source, --source, --bsrc, --src

The URL of the Git repository or the path to local source that contains your source code; for example https://github.com/IBM/CodeEngine or .. This value is optional.

--build-strategy, --strategy, --bstr, --str

The strategy to use for building the image. Valid values are dockerfile and buildpacks. The build strategy option is allowed only if the --build-source option is set. If not specified, the build strategy is determined by Code Engine if --build-source is specified and the source is on your local machine. This value is optional. The default value is dockerfile.

--build-timeout, --bto

The amount of time, in seconds, that can pass before the build must succeed or fail. The build timeout option is allowed only if the --build-source option is set. This value is optional. The default value is 600.

--cluster-local, --cl

Deploy the application with a project-only endpoint. Setting a project-only endpoint means that your app is not accessible from the public internet and network access is only possible from other Code Engine components that are running in the same project. This value is optional. The default value is false.

--command, --cmd, -c

Set commands for the application. Specify one command per --command option; for example, --cmd cmdA --cmd cmdB. This value overrides the default command that is specified within the container image. This value is optional.

--concurrency, --cn

The maximum number of requests that can be processed concurrently per instance. This value is optional. The default value is 100.

--concurrency-target, --ct

The threshold of concurrent requests per instance at which one or more additional instances are created. Use this value to scale up instances based on concurrent number of requests. If --concurrency-target is not specified, this option defaults to the value of the --concurrency option. This value is optional. The default value is 0.

--cpu

The amount of CPU set for the instance of the application. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 1.

--env, -e

Set environment variables in the application. Must be in NAME=VALUE format. This action adds a new environment variable or overrides an existing environment variable. Specify one environment variable per --env option; for example, --env envA=A --env envB=B. This value is optional.

--env-cm, --env-from-configmap

Set environment variables from the key-value pairs that are stored in this configmap by using one of the following ways:

To add environment variables for all keys in a configmap that is named configmapName, use the value configmapName. You can modify the environment variable names by specifying a prefix when referencing the configmap. To specify a prefix, use the value PREFIX=CONFIGMAP_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_CONFIGMAP>. For example, to set the prefix for all variable names of keys in configmap configmapName to CUSTOM_, use the value CUSTOM_=configmapName. If the configmap configmapName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a configmap that is named configmapName, use the value configmapName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a configmap that is named configmapName, use the value configmapName:myKey=key1.

This value is optional.

--env-sec, --env-from-secret

Set environment variables from the key-value pairs that are stored in a secret by using one of the following ways:

To add environment variables for all keys in a secret that is named secretName, use the value secretName. You can modify the environment variable names by specifying a prefix when referencing the secret. To specify a prefix, use the value PREFIX=SECRET_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_SECRET>. For example, to set the prefix for all variable names of keys in secret secretName to CUSTOM_, use the value CUSTOM_=secretName. If the secret secretName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a secret that is named secretName, use the value secretName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a secret that is named secretName, use the value secretName:myKey=key1.

This value is optional.

--ephemeral-storage, --es

The amount of ephemeral storage to set for the instance of the application. Use M for megabytes or G for gigabytes. This value is optional. The default value is 400M.

--force, -f

Do not verify the existence of specified configmap and secret references. Configmap references are specified with the --env-from-configmap or --mount-configmap options. Secret references are specified with the --env-from-secret, --mount-secret or --registry-secret options. This value is optional. The default value is false.

--image, -i

The name of the image that is used for this application. The format is REGISTRY/NAMESPACE/REPOSITORY:TAG where REGISTRY and TAG are optional. If REGISTRY is not specified, the default is docker.io. If TAG is not specified, the default is latest. The image option is required if the --build-source option is not specified. This value is optional.

--max-scale, --max, --maxscale

The maximum number of instances that can be used for this application. If you set this value to 0, the application scales as needed. The application scaling is limited only by the instances per the resource quota for the project of your application. See Limits and quotas for Code Engine. This value is optional. The default value is 10.

--memory, -m

The amount of memory set for the instance of the application. Use M for megabytes or G for gigabytes. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 4G.

--min-scale, --min, --minscale

The minimum number of instances that can be used for this application. This option is useful to ensure that no instances are running when not needed. This value is optional. The default value is 0.

--mount-configmap, --mount-cm

Add the contents of a configmap to the file system of your application container by providing a mount directory and the name of a configmap, with the format MOUNT_DIRECTORY=CONFIGMAP_NAME. Each mounted configmap must use a unique mount directory. For each key-value pair in the configmap, a file is added to the specified mount directory where the filename is the key and the contents of the file is the value of the key-value pair. Specify one mount configuration per --mount-configmap option; for example, --mount-configmap /etc/config-a=config-a --mount-configmap /etc/config-b=config-b. This value is optional.

--mount-secret, --mount-sec

Add the contents of a secret to the file system of your application container by providing a mount directory and the name of a secret, with the format MOUNT_DIRECTORY=SECRET_NAME. Each mounted secret must use a unique mount directory. For each key-value pair in the secret, a file is added to the specified mount directory where the filename is the key and the contents of the file is the value of the key-value pair. Specify one mount configuration per --mount-secret option; for example, --mount-secret /etc/secret-a=secret--a --mount-secret /etc/secret-b=secret-b. This value is optional.

--no-cluster-local, --ncl

Deploy the application with a public endpoint. The application deploys such that it can receive requests from the public internet or from components within the Code Engine project. This value is optional. The default value is true.

--no-wait, --nw

Create the application and do not wait for the application to be ready. If you specify the --no-wait option, the application create begins and does not wait. Use the app get command to check the application status. This value is optional. The default value is false.

--output, -o

Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, jsonpath-as-json=JSONPATH_EXPRESSION, url, and project-url. Use jsonpath to specify the path to an element of the JSON output. This value is optional.

--port, -p

The port where the application listens. The format is [NAME:]PORT, where [NAME:] is optional. If [NAME:] is specified, valid values are h2c, or http1. When [NAME:] is not specified or is http1, the port uses HTTP/1.1. When [NAME:] is h2c, the port uses unencrypted HTTP/2. By default, Code Engine assumes apps listen for incoming connections on port 8080. If your application needs to listen on a port other than port 8080, use --port to specify the port. This value is optional.

--probe-live, --pl

Configure the liveness probe for this application in NAME=VALUE format. Valid options for NAME are: type, port, path, interval, initial-delay, timeout, failure-threshold. This option can be specified multiple times. The type property is required and valid values are tcp and http. For example, --probe-live type=tcp --probe-live port=8080. For more information about working with probes, For more information about working with probes, see Configuring probes for your app. This value is optional.

--probe-ready, --pr

Configure the readiness probe for this application in NAME=VALUE format. Valid options for NAME are: type, port, path, interval, initial-delay, timeout, failure-threshold. This option can be specified multiple times. The type property is required and valid values are tcp and http. For example, --probe-ready type=tcp --probe-ready port=8080. For more information about working with probes, For more information about working with probes, see Configuring probes for your app. This value is optional.

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--registry-secret, --rs

The name of the registry secret. The registry secret is used to authenticate with a private registry when you download the container image. This value is optional.

--request-timeout, --rt, --timeout, -t

The amount of time in seconds that can pass before requests made to the application must succeed or fail. This value is optional. The default value is 300.

--rn, --revision-name

The name of the revision. Use a name that is unique within the application.

The name can contain lowercase letters, numbers, and hyphens (-).
The name must end with a lowercase alphanumeric character.
The fully qualified revision name must be in the format, Name_of_application-Name of revision.
The fully qualified revision name must be 63 characters or fewer.

This value is optional.

--scale-down-delay, --sdd

The amount of time in seconds that must pass at reduced concurrency before the application is scaled down. An increase of the number of concurrent requests causes an application to scale up. If the number of requests drops (reduced concurrency), the specified amount of time for this option determines how long the reduced concurrency needs to persist, before the application is scaled down. By default, the application will be scaled down immediately, if reduced concurrency is detected. This value is optional. The default value is 0.

--service-account, --sa

The name of the service account. A service account provides an identity for processes that run in an instance. For built-in service accounts, you can use the shortened names manager, none, reader, and writer. You can also use the full names that are prefixed with the Kubernetes Config Context, which can be determined with the project current command. This value is optional.

--user, -u

The user ID (UID) that is used to run the application. This value overrides any user ID that is set in the application Dockerfile. The ID must conform to the operating system requirements of the container. This value is optional. The default value is 0.

--visibility, -v

The visibility for the application. Valid values are public, private, and project. Setting a visibility of public means that your app can receive requests from the public internet or from components within the Code Engine project. Setting a visibility of private means that your app is not accessible from the public internet and network access is only possible from other IBM Cloud using Virtual Private Endpoints (VPE) or Code Engine components that are running in the same project. Visibility can only be private if the project supports application private visibility. Setting a visibility of project means that your app is not accessible from the public internet and network access is only possible from other Code Engine components that are running in the same project. This value is optional.

--wait, -w

Create the application and wait for the application to be ready. If you specify the --wait option, the application create waits for a maximum time in seconds, as set by the --wait-timeout option, for the application to become ready. If the application is not ready within the specified wait-timeout period, the application create fails. This value is optional. The default value is true.

--wait-timeout, --wto

The length of time in seconds to wait for the application to be ready. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

ibmcloud ce application create --name myapp --image icr.io/codeengine/hello

Example output

Creating application 'myapp'...
[...]
Run `ibmcloud ce application get -n 'myapp'` to check the application status.
OK

https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud

When you run ibmcloud ce application get -n 'myapp' to check the application status, the URL for your application is displayed.

`ibmcloud ce application delete`

Delete an application.

ibmcloud ce application delete --name APPLICATION_NAME [--force] [--ignore-not-found] [--no-wait] [--quiet] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--name, -n: The name of the application. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--no-wait, --nw: Delete the application and do not wait for the application to be deleted. If you specify the no-wait option, the application delete begins and does not wait. Use the app get command to check the application status. This value is optional. The default value is true.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--wait, -w: Delete the application and wait for the application to be deleted. If you specify the --wait option, the application delete waits for a maximum time in seconds, as set by the --wait-timeout option, for the application to become deleted. If the application is not deleted within the specified --wait-timeout period, the application delete fails. This value is optional. The default value is false.
--wait-timeout, --wto: The length of time in seconds to wait for the application to be deleted. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

ibmcloud ce application delete --name myapp -f

Example output

Deleted application 'myapp'

`ibmcloud ce application events`

Display the system events of application instances. System events are retained up to 60 minutes.

ibmcloud ce application events (--instance APP_INSTANCE | --application APP_NAME) [--output OUTPUT] [--quiet]

Command Options

--application, --app, -a, --name, -n: Display the events of all the instances of the specified application. This value is required if --instance is not specified.
--instance, -i: The name of a specific application instance. Use the app get command to find the instance name. This value is required if --application is not specified.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

The following example displays the system event information for all the instances of a specified application.

ibmcloud ce application events --application myapp

Example output

Getting events for all instances of application 'myapp'...
OK

myapp-atfte-1-deployment-6b49c5fb85-kf4m2:
    Type    Reason     Age  Source                Messages
    Normal  Scheduled  31s  default-scheduler     Successfully assigned 4svg40kna19/myapp-atfte-1-deployment-6b49c5fb85-kf4m2 to 10.240.0.15
    Normal  Pulling    29s  kubelet, 10.240.0.15  Pulling image "icr.io/codeengine/hello@sha256:f0dc03250736a7b40a66ee70fee94fc470e08c864197aa2140054fee6ca9f9d6"
    Normal  Pulled     24s  kubelet, 10.240.0.15  Successfully pulled image "icr.io/codeengine/hello@sha256:f0dc03250736a7b40a66ee70fee94fc470e08c864197aa2140054fee6ca9f9d6" in 4.907426108s
    Normal  Created    24s  kubelet, 10.240.0.15  Created container user-container
    Normal  Started    24s  kubelet, 10.240.0.15  Started container user-container
    Normal  Pulled     24s  kubelet, 10.240.0.15  Container image "icr.io/obs/codeengine/knative-serving/queue-39be6f1d08a095bd076a71d288d295b6:v0.20.0-rc1@sha256:8988bea781130827b3e1006e6e5e7f49094343a5505c1927bb832be3470455f6" already present on machine
    Normal  Created    23s  kubelet, 10.240.0.15  Created container queue-proxy
    Normal  Started    23s  kubelet, 10.240.0.15  Started container queue-proxy

Example of system event information for specified instance of an app

The following example displays the system event information for a specified instance of an app. Use the app get command to display details about your app, including the running instances of the app.

ibmcloud ce application events --instance myapp-li17x-1-deployment-69fd57bcb6-sr9tl

Example output of system event information for specified instance of an app

Getting events for application instance 'myapp-li17x-1-deployment-69fd57bcb6-sr9tl'...
OK

myapp-li17x-1-deployment-69fd57bcb6-sr9tl:
    Type     Reason     Age                    Source                Messages
    Normal   Scheduled  6m40s                  default-scheduler     Successfully assigned 4svg40kna19/myapp-li17x-1-deployment-69fd57bcb6-sr9tl to 10.240.64.6
    Normal   Pulling    6m39s                  kubelet, 10.240.64.6  Pulling image "icr.io/codeengine/hello@sha256:f0dc03250736a7b40a66ee70fee94fc470e08c864197aa2140054fee6ca9f9d6"
    Normal   Pulled     6m36s                  kubelet, 10.240.64.6  Successfully pulled image "icr.io/codeengine/hello@sha256:f0dc03250736a7b40a66ee70fee94fc470e08c864197aa2140054fee6ca9f9d6"
    Normal   Created    6m34s                  kubelet, 10.240.64.6  Created container user-container
    Normal   Started    6m33s                  kubelet, 10.240.64.6  Started container user-container
    Normal   Pulled     6m33s                  kubelet, 10.240.64.6  Container image "icr.io/obs/codeengine/knative-serving/queue-39be6f1d08a095bd076a71d288d295b6:v0.19.0-rc3@sha256:9cb525af53896afa6b5210b5ac56a893cf85b6cd013a61cb6503a005e40c5c6f" already present on machine
    Normal   Created    6m33s                  kubelet, 10.240.64.6  Created container queue-proxy
    Normal   Started    6m32s                  kubelet, 10.240.64.6  Started container queue-proxy
    [...]

`ibmcloud ce application get`

Display the details of an application.

ibmcloud ce application get --name APPLICATION_NAME [--output OUTPUT] [--quiet] [--show-all-revisions]

Command Options

--name, -n: The name of the application. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, jsonpath-as-json=JSONPATH_EXPRESSION, url, and project-url. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--show-all-revisions, -r: Show all revisions for this application. If not specified, only revisions which are configured to receive traffic are shown. This value is optional. The default value is false.

Example

ibmcloud ce application get --name myapp

Example output

Run 'ibmcloud ce application events -n myapp' to get the system events of the application instances.
Run 'ibmcloud ce application logs -f -n myapp' to follow the logs of the application instances.
OK

Name:          myapp
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:                31m
Created:            2021-09-09T14:01:02-04:00
URL:                https://myapp.abcdabcdabc.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.abcdabcdabc.svc.cluster.local
Console URL:        https://cloud.ibm.com/codeengine/project/us-south/01234567-abcd-abcd-abcd-abcdabcd1111/application/myapp/configuration
Status Summary:     Application deployed successfully  

Environment Variables:    
  Type     Name             Value  
  Literal  CE_API_BASE_URL  https://api.us-south.codeengine.cloud.ibm.com  
  Literal  CE_APP           myapp  
  Literal  CE_DOMAIN        us-south.codeengine.appdomain.cloud  
  Literal  CE_PROJECT_ID    abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
  Literal  CE_REGION        us-south  
  Literal  CE_SUBDOMAIN     abcdabcdab  
Image:                  icr.io/codeengine/helloworld  
Resource Allocation:      
  CPU:                1  
  Ephemeral Storage:  400M  
  Memory:             4G  

Revisions:     
  myapp-00001:    
    Age:                42s  
    Latest:             true  
    Traffic:            100%  
    Image:              icr.io/codeengine/helloworld (pinned to 1cee99)  
    Running Instances:  1  

Runtime:       
  Concurrency:       100  
  Maximum Scale:     10  
  Minimum Scale:     0  
  Scale Down Delay:  0  
  Timeout:           300  

Conditions:    
  Type                 OK    Age  Reason  
  ConfigurationsReady  true  25s    
  Ready                true  12s    
  RoutesReady          true  12s    

Events:        
  Type    Reason   Age  Source              Messages  
  Normal  Created  44s  service-controller  Created Configuration "myapp"  
  Normal  Created  43s  service-controller  Created Route "myapp"  

Instances:     
  Name                                    Revision     Running  Status   Restarts  Age  
  myapp-00001-deployment-d59b87654-xkqh7  myapp-00001  3/3      Running  0         43s

`ibmcloud ce application list`

List all applications in a project.

ibmcloud ce application list [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce app list --sort-by age

Example output

Listing all applications...
OK

Name           Status  URL                                                                    Latest                 Age   Conditions  Reason
myapptestapp2  Ready   https://myapptestapp2.4svg40kna19.us-south.codeengine.appdomain.cloud  myapptestapp2-emy0q-1  52s   3 OK / 3
myapptestapp1  Ready   https://myapptestapp1.4svg40kna19.us-south.codeengine.appdomain.cloud  myapptestapp1-ps4ca-1  104s  3 OK / 3
myapp-e        Ready   https://myapp-e.4svg40kna19.us-south.codeengine.appdomain.cloud        myapp-e-gx6xa-1        12m   3 OK / 3
myappd         Ready   https://myappd.4svg40kna19.us-south.codeengine.appdomain.cloud         myappd-lxjxm-1         13m   3 OK / 3
myappc         Ready   https://myappc.4svg40kna19.us-south.codeengine.appdomain.cloud         myappc-qffan-1         14m   3 OK / 3
myappb         Ready   https://myappb.4svg40kna19.us-south.codeengine.appdomain.cloud         myappb-i3hw3-1         15m   3 OK / 3
myapp          Ready   https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud          myapp-jmxwd-1          17m   3 OK / 3

`ibmcloud ce application logs`

Display the logs of application instances.

ibmcloud ce application logs (--instance APP_INSTANCE | --application APP_NAME) [--all-containers] [--follow] [--output OUTPUT] [--quiet] [--raw] [--tail TAIL] [--timestamps]

Command Options

--all-containers, --all: Display the logs of all containers of the specified application instances. This value is optional. The default value is false.
--application, --app, -a, --name, -n: Display the logs of all the instances of the specified application. This value is required if --instance is not specified.
--follow, -f: Follow the logs of application instances. Use this option to stream logs of application instances. If you specify the --follow option, you must enter Ctrl+C to terminate this log command. This value is optional. The default value is false.
--instance, -i: The name of a specific application instance. Use the app get command to find the instance name. This value is required if --application is not specified.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--raw, -r: Display logs without instance and container labels. This value is optional. The default value is false.
--tail, -t: Limit the display of logs of containers of the specified application instances to a maximum number of recent lines per container. For example, to display the last 3 lines of the logs of the containers of the specified application instances, specify --tail 3. If this option is not specified, all lines of the logs of the containers of the specified application instances are displayed. This value is optional. The default value is -1.
--timestamps, --ts: Include timestamps on each line in the log output. This value is optional. The default value is false.

Example

The following example displays the logs of a specific instance of an app. Use the app get command to obtain the name of the app instances.

ibmcloud ce application logs --instance myapp-zhk9x-1-deployment-6f955f5cc5-abcde

Example output

Getting logs for application instance 'myapp-zhk9x-1-deployment-6f955f5cc5-abcde'...
OK

myapp-zhk9x-1-deployment-6f955f5cc5-abcde:
Server running at http://0.0.0.0:8080/

Example of logs of all instances of an app

The following example displays the logs of all the instances of an app.

ibmcloud ce application logs --app myapp

Example output of logs of all instances of an app

Getting application 'myapp'...
Getting revisions for application 'myapp'...
Getting instances for application 'myapp'...
Getting logs for all instances of application 'myapp'...
OK

myapp-zhk9x-1-deployment-6f955f5cc5-abcde:
Server running at http://0.0.0.0:8080/

`ibmcloud ce application restart`

Restart running application instances.

ibmcloud ce application restart (--instance APP_INSTANCE | --application APP_NAME) [--quiet]

Command Options

--application, --app, -a, --name, -n: Restart all the running instances of the specified application. This value is required if --instance is not specified.
--instance, -i: The name of a specific application instance. Use the app get command to find the instance name. This value is required if --application is not specified.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce application restart --name myapp

Example output

Restarting all running instances of application 'myapp'...
OK

`ibmcloud ce application unbind`

Unbind IBM Cloud service instances from an application.

ibmcloud ce application unbind --name APP_NAME (--binding BINDING_NAME | --all) [--quiet]

Command Options

--name, -n: The name of the application to unbind. This value is required.
--all, -A: Unbinds all service instances for this application. This value is required if --binding is not specified. The default value is false.
--binding, -b: The name of the binding to unbind. Run ibmcloud ce app get -n APP_NAME to view binding names. This value is required if --all is not specified.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

In this example, remove all bindings from your application called myapp.

ibmcloud ce application unbind --name myapp --all

Example output

Removing service bindings...
OK

`ibmcloud ce application update`

Update an application. Updating your application creates a revision. When calls are made to the application, traffic is routed to the revision.

ibmcloud ce application update --name APP_NAME [--argument ARGUMENT] [--arguments-clear] [--build-clear] [--build-commit BUILD_COMMIT] [--build-commit-clear] [--build-context-dir BUILD_CONTEXT_DIR] [--build-dockerfile BUILD_DOCKERFILE] [--build-git-repo-secret BUILD_GIT_REPO_SECRET] [--build-git-repo-secret-clear] [--build-size BUILD_SIZE] [--build-source BUILD_SOURCE] [--build-strategy BUILD_STRATEGY] [--build-timeout BUILD_TIMEOUT] [--cluster-local] [--command COMMAND] [--commands-clear] [--concurrency CONCURRENCY] [--concurrency-target CONCURRENCY_TARGET] [--cpu CPU] [--env ENV] [--env-from-configmap ENV_FROM_CONFIGMAP] [--env-from-configmap-rm ENV_FROM_CONFIGMAP_RM] [--env-from-secret ENV_FROM_SECRET] [--env-from-secret-rm ENV_FROM_SECRET_RM] [--env-rm ENV_RM] [--ephemeral-storage EPHEMERAL_STORAGE] [--force] [--image IMAGE] [--max-scale MAX_SCALE] [--memory MEMORY] [--min-scale MIN_SCALE] [--mount-configmap MOUNT_CONFIGMAP] [--mount-rm MOUNT_RM] [--mount-secret MOUNT_SECRET] [--no-cluster-local] [--no-wait] [--output OUTPUT] [--port PORT] [--probe-live PROBE_LIVE] [--probe-live-clear] [--probe-ready PROBE_READY] [--probe-ready-reset] [--quiet] [--rebuild] [--registry-secret REGISTRY_SECRET] [--registry-secret-clear] [--request-timeout REQUEST_TIMEOUT] [--revision-name REVISION_NAME] [--scale-down-delay SCALE_DOWN_DELAY] [--service-account SERVICE_ACCOUNT] [--service-account-clear] [--user USER] [--visibility VISIBILITY] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--name, -n

The name of the application. This value is required.

--argument, --arg, -a

Set arguments for the application. Specify one argument per --argument option; for example, -a argA -a argB. This value is optional.

--arguments-clear, --ac

Clear application arguments. This value is optional. The default value is false.

--build-clear, --bc

Remove the association of a build from this application. The build clear option is allowed only if your app currently has an associated build. This value is optional. The default value is false.

--build-commit, --commit, --bcm, --cm, --revision

The commit, tag, or branch in the source repository to pull. The build commit option is allowed only if the --build-source option is set to the URL of a Git repository on this app update command, or your application currently has an associated build from a Git repository source. This value is optional.

--build-commit-clear, --commit-clear, --bcmc, --cmc

Clear the commit, tag, or branch in the source repository to pull. The commit clear option is allowed if your application currently has an associated build. This value is optional. The default value is false.

--build-context-dir, --context-dir, --bcdr, --cdr

The directory in the repository that contains the buildpacks file or the Dockerfile. The build context directory option is allowed if the --build-source option is set on this app update command, or your application currently has an associated build. This value is optional.

--build-dockerfile, --dockerfile, --bdf, --df

The path to the Dockerfile. Specify this option only if the name is other than Dockerfile. The build dockerfile option is allowed only if the --build-source option is set on this app update command, or your application currently has an associated build. This value is optional. The default value is Dockerfile.

--build-git-repo-secret, --git-repo-secret, --bgrs, --grs, --repo

--build-git-repo-secret-clear, --git-repo-secret-clear, --bgrsc, --grsc

Clear the SSH secret. This option is allowed if your application currently has an associated build. This value is optional. The default value is false.

--build-size, --size, --bsz, --sz

The size for the build, which determines the amount of resources used. Valid values are small, medium, large, xlarge, and xxlarge. For details, see Determining the size of the build. The build size option is allowed only if the --build-source option is set on this app update command, or your application currently has an associated build. This value is optional. The default value is medium.

--build-source, --source, --bsrc, --src

The URL of the Git repository or the path to local source that contains your source code; for example https://github.com/IBM/CodeEngine or .. This value is optional.

--build-strategy, --strategy, --bstr, --str

The strategy to use for building the image. Valid values are dockerfile and buildpacks. The build strategy option is allowed only if the --build-source option is set on this app update command, or your application currently has an associated build. If not specified, the build strategy is determined by Code Engine if --build-source is specified and the source is on your local machine. This value is optional. The default value is dockerfile.

--build-timeout, --bto

The amount of time, in seconds, that can pass before the build must succeed or fail. The build timeout option is allowed only if the --build-source option is set on this app update command, or your application currently has an associated build. This value is optional. The default value is 600.

--cluster-local, --cl

--command, --cmd, -c

--commands-clear, --cc

Clear application commands. This value is optional. The default value is false.

--concurrency, --cn

The maximum number of requests that can be processed concurrently per instance. This value is optional. The default value is 0.

--concurrency-target, --ct

--cpu

The amount of CPU set for the instance of the application. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 0.

--env, -e

--env-cm, --env-from-configmap

Set environment variables from the key-value pairs that are stored in this configmap by using one of the following ways:

To add environment variables for all keys in a configmap that is named configmapName, use the value configmapName. You can modify the environment variable names by specifying a prefix when referencing the configmap. To specify a prefix, use the value PREFIX=CONFIGMAP_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_CONFIGMAP>. For example, to set the prefix for all variable names of keys in configmap configmapName to CUSTOM_, use the value CUSTOM_=configmapName. If the configmap configmapName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a configmap that is named configmapName, use the value configmapName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a configmap that is named configmapName, use the value configmapName:myKey=key1.

This value is optional.

--env-from-configmap-rm, --env-cm-rm

Remove environment variable references to full configmaps by using the configmap name. To remove individual key references to configmaps, use the --env-rm option. This option can be specified multiple times. This value is optional.

--env-sec, --env-from-secret

Set environment variables from the key-value pairs that are stored in a secret by using one of the following ways:

To add environment variables for all keys in a secret that is named secretName, use the value secretName. You can modify the environment variable names by specifying a prefix when referencing the secret. To specify a prefix, use the value PREFIX=SECRET_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_SECRET>. For example, to set the prefix for all variable names of keys in secret secretName to CUSTOM_, use the value CUSTOM_=secretName. If the secret secretName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a secret that is named secretName, use the value secretName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a secret that is named secretName, use the value secretName:myKey=key1.

This value is optional.

--env-from-secret-rm, --env-sec-rm

Remove environment variable references to full secrets by using the secret name. To remove individual key references to secrets, use the --env-rm option. This option can be specified multiple times. This value is optional.

--env-rm

Remove environment variable references to the key of a key-value pair in a configmap or secret. To remove individual key references and literal values, specify the name of the key. This option can be specified multiple times. This value is optional.

--ephemeral-storage, --es

The amount of ephemeral storage to set for the instance of the application. Use M for megabytes or G for gigabytes. This value is optional.

--force, -f

--image, -i

--max-scale, --max, --maxscale

--memory, -m

The amount of memory set for the instance of the application. Use M for megabytes or G for gigabytes. For valid values, see Supported memory and CPU combinations. This value is optional.

--min-scale, --min, --minscale

The minimum number of instances that can be used for this application. This value is optional. The default value is 0.

--mount-configmap, --mount-cm

--mount-rm

Remove the contents of a configmap or secret from the file system of your application container by specifying the directory where the configmap or secret is mounted. Specify one mount directory per --mount-rm option; for example, --mount-rm /etc/configmap-a --mount-rm /etc/secret-b. This value is optional.

--mount-secret, --mount-sec

--no-cluster-local, --ncl

--no-wait, --nw

Update the application and do not wait for the application to be ready. If you specify the no-wait option, the application update begins and does not wait. Use the app get command to check the application status. This value is optional. The default value is false.

--output, -o

--port, -p

--probe-live, --pl

--probe-live-clear, --plr

Remove the liveness probe. This option is allowed only if your app currently has a liveness probe. This value is optional. The default value is false.

--probe-ready, --pr

--probe-ready-reset, --prr

Resets the readiness probe to the default configuration. This value is optional. The default value is false.

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--rebuild

Rebuild image from source. The rebuild option is allowed if your application currently has an associated build. This value is optional. The default value is false.

--registry-secret, --rs

The name of the registry secret. The registry secret is used to authenticate with a private registry when you download the container image. This value is optional.

--registry-secret-clear, --rsc

Clear the registry secret. This value is optional. The default value is false.

--request-timeout, --rt, --timeout, -t

The amount of time in seconds that can pass before requests made to the application must succeed or fail. This value is optional. The default value is 0.

--rn, --revision-name

The name of the revision. Use a name that is unique within the application.

The name can contain lowercase letters, numbers, and hyphens (-).
The name must end with a lowercase alphanumeric character.
The fully qualified revision name must be in the format, Name_of_application-Name of revision.
The fully qualified revision name must be 63 characters or fewer.

This value is optional.

--scale-down-delay, --sdd

--service-account, --sa

--service-account-clear, --sac

Clear the service account. This value is optional. The default value is false.

--user, -u

--visibility, -v

--wait, -w

Update the application and wait for the application to be ready. If you specify the --wait option, the application update waits for a maximum time in seconds, as set by the --wait-timeout option, for the application to become ready. If the application is not ready within the specified --wait-timeout period, the application create fails. This value is optional. The default value is true.

--wait-timeout, --wto

The length of time in seconds to wait for the application to be updated. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

ibmcloud ce application update --name myapp --image icr.io/codeengine/hello

Example output

Updating application 'myapp' to latest revision.
[...]
Run 'ibmcloud ce application get -n myapp' to check the application status.
OK

https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud

Build commands

A build, or image build, is a mechanism that you can use to create a container image from your source code. Code Engine supports building from a Dockerfile and Cloud Native Buildpacks. Use build commands to create, display details, update, and delete build configurations. After you create a build configuration, one or more buildrun commands can be submitted based on the build configuration.

You must be within the context of a project before you use build commands.

For more information about working with builds, see Building a container image.

You can use either build or bd in your build commands. To see CLI help for the build commands, run ibmcloud ce build -h.

`ibmcloud ce build create`

Create a build.

ibmcloud ce build create --name BUILD_NAME [--build-type BUILD_TYPE] [--commit COMMIT] [--context-dir CONTEXT_DIR] [--dockerfile DOCKERFILE] [--force] [--git-repo-secret GIT_REPO_SECRET] [--image IMAGE] [--output OUTPUT] [--quiet] [--registry-secret REGISTRY_SECRET] [--size SIZE] [--source SOURCE] [--strategy STRATEGY] [--timeout TIMEOUT]

Command Options

-n, --name

The name of the build. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 63 characters or fewer and can contain lowercase alphanumeric characters and hyphens (-).

This value is required.

--build-type, --bt

The type of build. Valid values are git and local. If the type of build is local, then the --source, --commit, and --git-repo-secret options are not valid. This value is optional. The default value is git.

--commit, --cm, --revision

The commit, tag, or branch in the source repository to pull. The commit option is allowed if the --build-type option is git and not allowed if the --build-type option is local. This value is optional.

--context-dir, --cdr

The directory in the repository that contains the buildpacks file or the Dockerfile. This value is optional.

--dockerfile, --df

The path to the Dockerfile. Specify this option only if the name is other than Dockerfile. This value is optional. The default value is Dockerfile.

--force, -f

Do not verify the existence of specified secret references. Secret references are specified with the --get-repo-secret or --registry-secret options. This value is optional. The default value is false.

--git-repo-secret, --grs, --repo, -r

The name of the SSH secret, which contains the credentials to access the private repository that contains the source code to build your container image. To create this SSH secret, use the secret create --format SSH command. An SSH secret is also used as a Git repository access secret. This option is allowed if the --build-type option is git and not allowed if the --build-type option is local. This value is optional.

--image, -i

The location of the image registry. The format is REGISTRY/NAMESPACE/REPOSITORY:TAG where TAG is optional. If TAG is not specified, the default is latest. This value is optional.

--output, -o

Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--registry-secret, --rs

The registry secret that is used to access the registry. You can add the registry secret by running the registry create command. This value is optional.

--size, --sz

--source, --src

The URL of the Git repository that contains your source code; for example https://github.com/IBM/CodeEngine. The source option is required if the --build-type option is git and not allowed if the --build-type option is local. This value is optional.

--strategy, --str

--timeout, --to

The amount of time, in seconds, that can pass before the build must succeed or fail. This value is optional. The default value is 600.

Example

The following example creates a build configuration file called helloworld-build from a source Dockerfile, that is located in https://github.com/IBM/CodeEngine within the hello directory in the main branch, with dockerfile strategy and medium size. When this build is submitted, the container image that is built is stored in a Container Registry instance at us.icr.io/mynamespace/codeengine-helloworld that is accessed by using an image registry secret called myregistry.

ibmcloud ce build create --name helloworld-build --source https://github.com/IBM/CodeEngine  --context-dir /hello --commit main --strategy dockerfile --size medium --image us.icr.io/mynamespace/codeengine-helloworld --registry-secret myregistry

Example output

Creating build helloworld-build...
OK

`ibmcloud ce build delete`

Delete a build.

ibmcloud ce build delete --name BUILD_NAME [--force] [--ignore-not-found] [--quiet]

Command Options

--name, -n: The name of the build. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce build delete --name helloworld-build

Example output

Are you sure you want to delete build helloworld-build? [y/N]> y
Deleting build 'helloworld-build'...
OK

`ibmcloud ce build get`

Display the details of a build.

ibmcloud ce build get --name BUILD_NAME [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the build. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce build get --name helloworld-build

Example output

Getting build 'helloworld-build'
OK

Name:          helloworld-build
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           15s
Created:       2021-03-14T14:48:19-05:00  
Status:        Succeeded 
Reason:        all validations succeeded

Last Build Run:
  Name:     helloworld-build-run
  Age:      39d
  Created:  2021-09-30T15:19:33-04:00

Image:              us.icr.io/mynamespace/codeengine-helloworld
Registry Secret:    myregistry
Build Strategy:     dockerfile-medium
Timeout:            10m0s
Source:             https://github.com/IBM/CodeEngine
Commit:             main
Context Directory:  /hello
Dockerfile:         Dockerfile 

Build Runs:
  Name                  Status                              Image                                        Age
  helloworld-build-run  All Steps have completed executing  us.icr.io/mynamespace/codeengine-helloworld  39d

`ibmcloud ce build list`

List all builds in a project.

ibmcloud ce build list [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce build list

Example output

Listing builds...
OK

Name                    Status     Reason                     Image                                               Build Strategy     Age    Last Build Run Name                        Last Build Run Age
myhellobuild           Succeeded  all validations succeeded  us.icr.io/mynamespace/codeengine-codeengine-200      dockerfile-medium  160d   myhellobuild-run-4xdnb                    160d
hello-build-5ckgs      Succeeded  all validations succeeded  us.icr.io/mynamespace/codeengine-codeengine-51       dockerfile-medium  39d    helloapp3-build-5ckgs-run-210803-2129500   39d
hello-build-pmg6v      Succeeded  all validations succeeded  us.icr.io/mynamespace/codeengine-codeengine-4f       dockerfile-medium  40d    hellooapp2-build-pmg6v-run-210802-2112310  40d
helloworld-build       Succeeded  all validations succeeded  us.icr.io/mynamespace/codeengine-helloworld          dockerfile-medium  39d    helloworld-build-run                       39d

`ibmcloud ce build update`

Update a build.

ibmcloud ce build update --name BUILD_NAME [--commit COMMIT] [--commit-clear] [--context-dir CONTEXT_DIR] [--dockerfile DOCKERFILE] [--force] [--git-repo-secret GIT_REPO_SECRET] [--git-repo-secret-clear] [--image IMAGE] [--output OUTPUT] [--quiet] [--registry-secret REGISTRY_SECRET] [--size SIZE] [--source SOURCE] [--strategy STRATEGY] [--timeout TIMEOUT]

Command Options

--name, -n: The name of the build. This value is required.
--commit, --cm, --revision: The commit, tag, or branch in the source repository to pull. This value is optional.
--commit-clear, --cmc: Clear the commit, tag, or branch in the source repository to pull. This value is optional. The default value is false.
--context-dir, --cdr: The directory in the repository that contains the buildpacks file or the Dockerfile. This value is optional.
--dockerfile, --df: The path to the Dockerfile. Specify this option only if the name is other than Dockerfile. This value is optional. The default value is Dockerfile.
--force, -f: Do not verify the existence of specified secret references. Secret references are specified with the --get-repo-secret or --registry-secret options. This value is optional. The default value is false.
--git-repo-secret, --grs, --repo, -r: The name of the SSH secret, which contains the credentials to access the private repository that contains the source code to build your container image. To create this SSH secret, use the secret create --format SSH command. An SSH secret is also used as a Git repository access secret. This value is optional.
--git-repo-secret-clear, --grsc: Clear the SSH secret. This value is optional. The default value is false.
--image, -i: The location of the image registry. The format is REGISTRY/NAMESPACE/REPOSITORY:TAG where TAG is optional. If TAG is not specified, the default is latest. This value is optional.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--registry-secret, --rs: The name of the registry secret. The registry secret is used to authenticate with a private registry when you download the container image. This value is optional.
--size, --sz: The size for the build, which determines the amount of resources used. Valid values are small, medium, large, xlarge, and xxlarge. For details, see Determining the size of the build. This value is optional.
--source, --src: The URL of the Git repository that contains your source code; for example https://github.com/IBM/CodeEngine. This value is optional.
--strategy, --str: The strategy to use for building the image. For applications and jobs, valid values are dockerfile and buildpacks. For functions, valid values have the format codebundle-[RUNTIME-ID]. For example, if you want to build a code bundle for your function with the runtime ID nodejs-18, use codebundle-nodejs-18 as the build strategy. You can find the ID of any supported functions runtime by running the ibmcloud ce fn runtimes command. This value is optional.
--timeout, --to: The amount of time, in seconds, that can pass before the build must succeed or fail. This value is optional. The default value is 600.

Example

ibmcloud ce build update --name helloworld-build --source https://github.com/IBM/CodeEngine  --context-dir /hello --commit main --timeout 900

Example output

Updating build helloworld-build...
OK

Buildrun commands

You must be within the context of a project before you use buildrun commands.

For more information about working with builds and build runs, see Building a container image.

You can use either buildrun or br in your buildrun commands. To see CLI help for the buildrun commands, run ibmcloud ce br -h.

`ibmcloud ce buildrun cancel`

Cancel a build run.

ibmcloud ce buildrun cancel --name BUILDRUN_NAME [--quiet]

Command Options

--name, -n: The name of the build run. This value is required.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce buildrun cancel --name mybuildrun

Example output

Cancelling build run 'mybuildrun'...
OK

`ibmcloud ce buildrun delete`

Delete a build run.

ibmcloud ce buildrun delete (--name BUILDRUN_NAME | --build BUILD_NAME) [--force] [--ignore-not-found] [--quiet]

Command Options

--build, -b: Use this option to delete all build runs of the specified build. The --build option is required, if you do not specify the --name value. This value is optional.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--name, -n: The name of the build run. The --name option is required, if you do not specify the --build value. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce buildrun delete --name mybuildrun

Example output

Are you sure you want to delete build run mybuildrun? [y/N]> y
Deleting build run 'mybuildrun'...
OK

`ibmcloud ce buildrun events`

Display the system events of a build run. System events are retained up to 60 minutes.

ibmcloud ce buildrun events --buildrun BUILDRUN_NAME [--output OUTPUT] [--quiet]

Command Options

--buildrun, -b, --br, --name, -n: The name of the build run. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

This example displays the system event information for a build run.

ibmcloud ce buildrun events --buildrun mybuildrun

Example output

Getting build run 'mybuildrun'...
Getting instances of build run 'mybuildrun'...
Getting events for build run 'mybuildrun'...
OK

mybuildrun-l4mr2-pod-89z4t:
    Type    Reason     Age  Source                  Messages
    Normal  Scheduled  33s  default-scheduler       Successfully assigned 4svg40kna19/mybuildrun-l4mr2-pod-89z4t to 10.240.128.97
    Normal  Pulled     31s  kubelet, 10.240.128.97  Container image "gcr.io/distroless/base@sha256:92720b2305d7315b5426aec19f8651e9e04222991f877cae71f40b3141d2f07e" already present on machine
    Normal  Created    31s  kubelet, 10.240.128.97  Created container working-dir-initializer
    Normal  Started    31s  kubelet, 10.240.128.97  Started container working-dir-initializer
    Normal  Pulled     30s  kubelet, 10.240.128.97  Container image "icr.io/obs/codeengine/tekton-pipeline/entrypoint-bff0a22da108bc2f16c818c97641a296:v0.20.1-rc2@sha256:19ec0672b5e84a4c5939c6ece6fa69efbce0d38479baf35ce894cf1c67f7e435" already present on machine
    Normal  Created    30s  kubelet, 10.240.128.97  Created container place-tools
    Normal  Started    29s  kubelet, 10.240.128.97  Started container place-tools
    Normal  Pulled     28s  kubelet, 10.240.128.97  Container image "gcr.io/distroless/base@sha256:92720b2305d7315b5426aec19f8651e9e04222991f877cae71f40b3141d2f07e" already present on machine
    Normal  Created    28s  kubelet, 10.240.128.97  Created container step-create-dir-image-l7lf2
    Normal  Created    25s  kubelet, 10.240.128.97  Created container step-git-source-source-46fm7
    Normal  Pulled     25s  kubelet, 10.240.128.97  Container image "icr.io/obs/codeengine/tekton-pipeline/git-init-4874978a9786b6625dd8b6ef2a21aa70:v0.20.1-rc2@sha256:5febfb32459a114b7beafdc593770a0f692a09d874ac6b59ce85507844641cdf" already present on machine
    Normal  Started    25s  kubelet, 10.240.128.97  Started container step-create-dir-image-l7lf2
    Normal  Started    24s  kubelet, 10.240.128.97  Started container step-git-source-source-46fm7
    Normal  Pulled     24s  kubelet, 10.240.128.97  Container image "icr.io/obs/codeengine/kaniko/executor:v1.3.0-rc1" already present on machine
    Normal  Created    24s  kubelet, 10.240.128.97  Created container step-build-and-push
    Normal  Started    24s  kubelet, 10.240.128.97  Started container step-build-and-push
    Normal  Pulled     24s  kubelet, 10.240.128.97  Container image "icr.io/obs/codeengine/tekton-pipeline/imagedigestexporter-6e7c518e6125f31761ebe0b96cc63971:v0.20.1-rc2@sha256:21b3120ce9b930b4eb1359eb20a3109e3a6643e9d2777ef9694efb033367e57c" already present on machine
    Normal  Created    24s  kubelet, 10.240.128.97  Created container step-image-digest-exporter-gnbrp
    Normal  Started    23s  kubelet, 10.240.128.97  Started container step-image-digest-exporter-gnbrp

`ibmcloud ce buildrun get`

Display the details of a build run.

ibmcloud ce buildrun get --name BUILDRUN_NAME [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the build run. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce buildrun get --name mybuildrun

Example output

Getting build run 'mybuildrun'...
Run 'ibmcloud ce buildrun events -n mybuildrun' to get the system events of the build run.
Run 'ibmcloud ce buildrun logs -f -n mybuildrun' to follow the logs of the build run.
OK

Name:          mybuildrun
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           21m  
Created:       2021-03-14T14:50:13-05:00  

Summary:       Succeeded  
Status:        Succeeded  
Reason:        All Steps have completed executing  
Source:          
  Commit Branch:  main  
  Commit SHA:     abcdeb88263442e28af6ae26d2082dea1d6abcde  
  Commit Author:  myauthor  
Image Digest:  sha256:522488ca3b54eb65f8c1e609a7b27c08558d08166fe062e7dde6838d4a609d61  

Image:  us.icr.io/mynamespace/test

`ibmcloud ce buildrun list`

List all build runs in a project.

ibmcloud ce buildrun list [--build BUILD] [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--build, -b: Use this option to only display build runs from the specified build. This value is optional.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce buildrun list

Example output

Listing builds...
OK

Name                                  Status     Build Name        Age
helloworld-build-run                  Succeeded  helloworld-build  5d22h
mybuildrun                            Succeeded  helloworld-build  7m23s
mybuildrun2                           Succeeded  helloworld-build  3m4s

`ibmcloud ce buildrun logs`

Display the logs of a build run.

ibmcloud ce buildrun logs --buildrun BUILDRUN_NAME [--follow] [--output OUTPUT] [--quiet] [--raw] [--tail TAIL] [--timestamps]

Command Options

--buildrun, -b, --br, --name, -n: The name of the build run. This value is required.
--follow, -f: Follow the logs of the build run. Use this option to stream logs of the build run. If you specify the --follow option, you must enter Ctrl+C to terminate this log command. This value is optional. The default value is false.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--raw, -r: Display logs without instance and container labels. This value is optional. The default value is false.
--tail, -t: Limit the display of logs of containers of the specified build run to a maximum number of recent lines per container. For example, to display the last 3 lines of the logs of the containers of the specified build run, specify --tail 3. If this option is not specified, all lines of the logs of the containers of the specified build run are displayed. This value is optional. The default value is -1.
--timestamps, --ts: Include timestamps on each line in the log output. This value is optional. The default value is false.

Example

ibmcloud ce buildrun logs --name mybuildrun

Example output

Getting build run 'mybuildrun'...
Getting instances of build run 'mybuildrun'...
Getting logs for build run 'mybuildrun'...
OK

mybuildrun-v2mb8-pod-tlzdx/step-git-source-source-g2kbf:
{"level":"info","ts":1614089507.7123275,"caller":"git/git.go:165","msg":"Successfully cloned https://github.com/IBM/CodeEngine @ 433e2b8d6529e4a55f5e0f72d3772a79602a5ee8 (grafted, HEAD, origin/main) in path /workspace/source"}
{"level":"info","ts":1614089509.0128207,"caller":"git/git.go:203","msg":"Successfully initialized and updated submodules in path /workspace/source"}

mybuildrun-v2mb8-pod-tlzdx/step-build-and-push:
INFO[0000] Retrieving image manifest node:12-alpine
INFO[0000] Retrieving image node:12-alpine
INFO[0001] Retrieving image manifest node:12-alpine
INFO[0001] Retrieving image node:12-alpine
INFO[0001] Built cross stage deps: map[]
INFO[0001] Retrieving image manifest node:12-alpine
INFO[0001] Retrieving image node:12-alpine
INFO[0002] Retrieving image manifest node:12-alpine
INFO[0002] Retrieving image node:12-alpine
INFO[0002] Executing 0 build triggers
INFO[0002] Unpacking rootfs as cmd RUN npm install requires it.
INFO[0006] RUN npm install
INFO[0006] Taking snapshot of full filesystem...
INFO[0008] cmd: /bin/sh
INFO[0008] args: [-c npm install]
INFO[0008] Running: [/bin/sh -c npm install]
npm WARN saveError ENOENT: no such file or directory, open '/package.json'
npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN enoent ENOENT: no such file or directory, open '/package.json'
npm WARN !invalid#2 No description
npm WARN !invalid#2 No repository field.
npm WARN !invalid#2 No README data
npm WARN !invalid#2 No license field.

up to date in 0.27s
found 0 vulnerabilities

INFO[0010] Taking snapshot of full filesystem...
INFO[0010] COPY server.js .
INFO[0010] Taking snapshot of files...
INFO[0010] EXPOSE 8080
INFO[0010] cmd: EXPOSE
INFO[0010] Adding exposed port: 8080/tcp
INFO[0010] CMD [ "node", "server.js" ]

mybuildrun-v2mb8-pod-tlzdx/step-image-digest-exporter-hcvmf:
2021/02/23 14:11:43 warning: unsuccessful cred copy: ".docker" from "/tekton/creds" to "/tekton/home": unable to open destination: open /tekton/home/.docker/config.json: permission denied
{"severity":"INFO","timestamp":"2021-02-23T14:12:05.65581098Z","caller":"logging/config.go:115","message":"Successfully created the logger.","logging.googleapis.com/labels":{},"logging.googleapis.com/sourceLocation":{"file":"github.com/tektoncd/pipeline/vendor/knative.dev/pkg/logging/config.go","line":"115","function":"github.com/tektoncd/pipeline/vendor/knative.dev/pkg/logging.newLoggerFromConfig"}}
{"severity":"INFO","timestamp":"2021-02-23T14:12:05.655937558Z","caller":"logging/config.go:116","message":"Logging level set to: info","logging.googleapis.com/labels":{},"logging.googleapis.com/sourceLocation":{"file":"github.com/tektoncd/pipeline/vendor/knative.dev/pkg/logging/config.go","line":"116","function":"github.com/tektoncd/pipeline/vendor/knative.dev/pkg/logging.newLoggerFromConfig"}}

`ibmcloud ce buildrun submit`

Submit a build run.

ibmcloud ce buildrun submit (--build BUILD_NAME [--name NAME]) | (--name NAME [--commit COMMIT] [--context-dir CONTEXT_DIR] [--dockerfile DOCKERFILE] [--git-repo-secret GIT_REPO_SECRET] [--registry-secret REGISTRY_SECRET] [--size SIZE] [--strategy STRATEGY]) [--image IMAGE] [--no-wait] [--output OUTPUT] [--quiet] [--service-account SERVICE_ACCOUNT] [--source SOURCE] [--timeout TIMEOUT] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--build, -b, --bd

The name of the build configuration to use. This value is optional.

--commit, --cm, --revision

The commit, tag, or branch in the source repository to pull. The build commit option is allowed if the --source option is set to the URL of a Git repository and not allowed if the --source option is not set to the URL of a Git repository. This value is optional.

--context-dir, --cdr

The directory in the repository that contains the buildpacks file or the Dockerfile. The build context directory option is allowed if the --build option is not set and not allowed if the --build option is set. This value is optional.

--dockerfile, --df

The path to the Dockerfile. Specify this option only if the name is other than Dockerfile. The build dockerfile option is allowed if the --build option is not set and not allowed if the --build option is set. This value is optional. The default value is Dockerfile.

--git-repo-secret, --grs, --repo, -r

--image, -i

The location of the image registry. The format is REGISTRY/NAMESPACE/REPOSITORY:TAG where TAG is optional. If TAG is not specified, the default is latest. This value is optional.

-n, --name

The name of the build run. Use a name that is unique within the project. If the --build option is set, the name option is optional. If the --build option is not set, the name option is required.

The name must begin and end with a lowercase alphanumeric character.
The name must be 63 characters or fewer and can contain lowercase alphanumeric characters and hyphens (-).

This value is optional.

--no-wait, --nw

Submit the build run and do not wait for this build run to complete. If you specify the --no-wait option, the build run submit begins and does not wait. Use the buildrun get command to check the build run status. This value is optional. The default value is true.

--output, -o

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--registry-secret, --rs

The name of the registry secret. The registry secret is used to authenticate with a private registry when you download the container image. The registry secret option is allowed if the --build option is not set and not allowed if the --build option is set. This value is optional.

--service-account, --sa

--size, --sz

The size for the build, which determines the amount of resources used. Valid values are small, medium, large, xlarge, and xxlarge. For details, see Determining the size of the build. The build size option is allowed if the --build option is not set and not allowed if the --build option is set. This value is optional. The default value is medium.

--source, --src

The URL of the Git repository or the path to local source that contains your source code; for example https://github.com/IBM/CodeEngine or .. If the --build option is set, the source option is required if the --build-type option on the related build is local and not allowed if the --build-type option on the related build is git. If the --build option is not set, the source option is optional. This value is optional. The default value is ..

--strategy, --str

The strategy to use for building the image. For applications and jobs, valid values are dockerfile and buildpacks. For functions, valid values have the format codebundle-[RUNTIME-ID]. For example, if you want to build a code bundle for your function with the runtime ID nodejs-18, use codebundle-nodejs-18 as the build strategy. You can find the ID of any supported functions runtime by running the ibmcloud ce fn runtimes command. The build strategy option is allowed if the --build option is not set and not allowed if the --build option is set. If not specified, the build strategy is determined by Code Engine if --source is specified and the source is on your local machine. This value is optional. The default value is dockerfile.

--timeout, --to

The amount of time, in seconds, that can pass before the build run must succeed or fail. This value is optional. The default value is 600.

--wait, -w

Submit the build run and wait for this build run to complete. If you specify the --wait option, the build run submit waits for a maximum time in seconds, as set by the --wait-timeout option, for the build run to complete. If the build run is not completed within the specified --wait-timeout period, the build run submit fails. This value is optional. The default value is false.

--wait-timeout, --wto

The length of time in seconds to wait for this build run to complete. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

The following command submits a build run called mybuildrun and uses the build configuration file called helloworld-build.

ibmcloud ce buildrun submit --name mybuildrun --build helloworld-build

Example output

Submitting build run 'mybuildrun'...
Run 'ibmcloud ce buildrun get -n mybuildrun' to check the build run status.
OK

Configmap commands

A configmap provides a method to include non-sensitive data information to your deployment. By referencing values from your configmap as environment variables, you can decouple specific information from your deployment and keep your app, job, or function portable. A configmap contains information in key-value pairs. Use configmap commands to create, display details, update, and delete configmaps.

You must be within the context of a project before you use configmap commands.

For more information about working with configmaps, see Working with configmaps.

You can use either configmap or cm in your configmap commands. To see CLI help for the configmap commands, run ibmcloud ce configmap -h.

`ibmcloud ce configmap create`

Create a configmap.

ibmcloud ce configmap create --name CONFIGMAP_NAME (--from-env-file FILE | --from-file FILE | --from-file KEY=FILE | --from-literal KEY=VALUE) [--output OUTPUT] [--quiet]

Command Options

-n, --name

The name of the configmap. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 253 characters or fewer and can contain lowercase letters, numbers, periods (.), and hyphens (-).

This value is required.

--from-env-file, -e

Create a configmap from a file which contains one or more lines that match the format KEY=VALUE. You must provide the path to the file as a value. Each line from the specified file is added as a key-value pair. Any lines in the specified file that are empty or begin with # are ignored. This value is required if --from-literal or --from-file is not specified.

--from-file, -f

Create a configmap from a file. You must provide the path to the file as a value. This value is required if --from-literal or --from-env-file is not specified.

--from-literal, -l

Create a configmap from a key-value pair. Must be in KEY=VALUE format. This value is required if --from-file or --from-env-file is not specified. This option can be specified multiple times.

--output, -o

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

The following example creates a configmap that is named configmap-fromliteral with two key pair values: color=blue and size=large.

ibmcloud ce configmap create --name configmap-fromliteral --from-literal color=blue --from-literal size=large

Example output

Creating Configmap 'configmap-fromliteral'...
OK
Run 'ibmcloud ce configmap get -n configmap-fromliteral' to see more details.

Example of a configmap with values from multiple files

The following example creates a configmap that is named configmap-fromfile with values from multiple files.

ibmcloud ce configmap create --name configmap-fromfile  --from-file ./color.txt --from-file ./size.txt

Example output of a configmap with values from multiple files

Creating configmap 'configmap-fromfile'...
OK
Run 'ibmcloud ce configmap get -n configmap-fromfile' to see more details.

`ibmcloud ce configmap delete`

Delete a configmap.

ibmcloud ce configmap delete --name CONFIGMAP_NAME [--force] [--ignore-not-found] [--quiet]

Command Options

--name, -n: The name of the configmap. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce configmap delete --name configmap-fromliteral -f

Example output

Deleting Configmap 'configmap-fromliteral'...
OK

`ibmcloud ce configmap get`

Display the details of a configmap.

ibmcloud ce configmap get --name CONFIGMAP_NAME [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the configmap. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce configmap get --name configmap-fromliteral

Example output

Getting configmap 'configmap-fromliteral'...
OK

Name:          configmap-fromliteral
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           21s
Created:       2021-03-01T13:50:56-05:00

Data:
---
color: blue
size: large

`ibmcloud ce configmap list`

List all configmaps in a project.

ibmcloud ce configmap list [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce configmap list

Example output

Listing Configmaps...
Name                    Data   Age
configmap-fromfile      2      19m13s
configmap-fromliteral   2      16m12s

`ibmcloud ce configmap update`

Update a configmap.

ibmcloud ce configmap update --name CONFIGMAP_NAME (--from-env-file FILE | --from-file FILE | --from-file KEY=FILE | --from-literal KEY=VALUE | --rm KEY) [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the configmap. This value is required.
--from-env-file, -e: Update a configmap from a file which contains one or more lines that match the format KEY=VALUE. You must provide the path to the file as a value. Each line from the specified file is added as a key-value pair. Any lines in the specified file that are empty or begin with # are ignored. This value is required if --from-literal or --from-file is not specified. This option can be specified multiple times.
--from-file, -f: Update a configmap from a file. You must provide the path to the file as a value. This value is required if --from-literal or --from-env-file is not specified. This option can be specified multiple times.
--from-literal, -l: Update a configmap from a key-value pair. Must be in KEY=VALUE format. This value is required if --from-file or or --from-env-fileis not specified. This option can be specified multiple times.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--rm: Remove an individual key-value pair in a configmap by specifying the name of the key. This option can be specified multiple times. This value is optional.

Example

The following example updates a configmap that is named configmap-fromliteral with a username and password value pair.

ibmcloud ce configmap update --name configmap-fromliteral --from-literal username=devuser --from-literal password='A!B99c$D1Def'

Example output

Updating configmap 'configmap-fromliteral'...
OK
Run 'ibmcloud ce configmap get -n configmap-fromliteral' to see more details.

Example of a configmap with values from a file

The following example updates a configmap that is named configmap-fromfile with values from a file.

ibmcloud ce configmap update --name configmap-fromfile  --from-file ./username.txt --from-file ./password.txt

Example output of a configmap with values from a file

Updating configmap 'configmap-fromfile'...
OK
Run 'ibmcloud ce configmap get -n configmap-fromfile' to see more details.

Domainmapping commands

Domain mappings provide the URL route to your Code Engine applications within a project. With Code Engine, these mappings are automatically created, by default, whenever you deploy an application. However, you can map your own custom domain to a Code Engine application to route requests from your custom URL to your application with Code Engine. Use domainmapping commands to create, display details, update, and delete domain mappings.

When you set a custom domain mapping in Code Engine, you define a 1-to-1 mapping between your fully qualified domain name (FQDN) and a Code Engine application in your project. To configure and work with custom domain mappings in the CLI, use the domainmapping commands.

You must be within the context of a project before you use domainmapping commands.

For more information about working with domain mappings, see Configuring custom domain mappings for your app.

You can use either domainmapping or dm in your configmap commands. To see CLI help for the domainmapping commands, run ibmcloud ce domainmapping -h.

`ibmcloud ce domainmapping create`

Create a custom domain mapping.

ibmcloud ce domainmapping create --domain-name DOMAIN_NAME [--target-type TARGET_TYPE] --tls-secret SECRET_NAME [--quiet]

Command Options

--domain-name, --dn, -n, --name: Specify the name of the domain mapping. This name must be a valid fully qualified domain name (FQDN). For example, www.example.com. This value is required.
--target, -t: The name of the target application or function. This value is required.
--target-type, --type: The type of the target. Valid values are application or function. This value is required.
--tls-secret, --secret, --tls: Specify a TLS secret that contains the certificate including all its intermediate certificates and the corresponding private key for the domain mapping. The certificate must be signed by a trusted, public certificate authority (CA). Self-signed certificates are not supported. This value is required.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

The following example creates a custom domain mapping between the Code Engine myapp application and the custom domain, www.example.com and uses the TLS secret, mytlssecret.

ibmcloud ce domainmapping create --domain-name www.example.com --target myapp --tls-secret mytlssecret

Example output

OK
Domain mapping successfully created.

`ibmcloud ce domainmapping delete`

Delete a custom domain mapping.

ibmcloud ce domainmapping delete --domain-name DOMAIN_NAME [--force] [--ignore-not-found] [--quiet]

Command Options

--domain-name, --dn, -n, --name: The name of the domain mapping. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce domainmapping delete --name www.example.com -f

Example output

Deleting domain mapping 'www.example.com'...
OK

`ibmcloud ce domainmapping get`

Display the details of a custom domain mapping.

ibmcloud ce domainmapping get --domain-name DOMAIN_NAME [--output OUTPUT] [--quiet]

Command Options

--domain-name, --dn, -n, --name: The name of the domain mapping This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce domainmapping get --name www.example.com

Example output

Getting domainmapping 'www.example.com'...
OK

Domain Name:  www.example.com  
CNAME:        custom.abcdabcdabc.us-south.codeengine.appdomain.cloud  
Target Name:  myapp  
Target Type:  app  
TLS Secret:   mytlssecret  
Status:       ready

`ibmcloud ce domainmapping list`

List domain mappings in a project.

ibmcloud ce domainmapping list [--all] [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--all, -a: Display all domain mappings in a project, including custom and system domain mappings. This value is optional. The default value is false.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

The following example displays a listing of all custom domain mappings.

ibmcloud ce domainmapping list

Example output

Listing domain mappings...
OK

Name              CNAME                                                        Target  Target-Type  Status  Secret Name  Age  
www.example.com   custom.abcdabcdabc.us-south.codeengine.appdomain.cloud       myapp   app          ready   mytlssecret  36m

To view a listing of all domain mappings for your applications, including both the custom domain mappings and any automatically generated system domain mappings, specify the --all option with the ibmcloud ce domainmapping list command.

`ibmcloud ce domainmapping update`

Update a custom domain mapping.

ibmcloud ce domainmapping update --domain-name DOMAIN_NAME --target TARGET_NAME --tls-secret SECRET_NAME [--quiet] [--target-type TARGET_TYPE]

Command Options

--domain-name, --dn, -n, --name: The name of the domain mapping. This value is required.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--target, -t: The name of the target application or function. This value is optional.
--target-type, --type: The type of the target. Valid values are application or function. This value is optional.
--tls-secret, --secret, --tls: Specify a TLS secret that contains the certificate including all its intermediate certificates and the corresponding private key for the domain mapping. The certificate must be signed by a trusted, public certificate authority (CA). Self-signed certificates are not supported. This value is optional.

Example

The following example updates the www.example.com domain mapping to use mytlssecret2 instead of mytlssecret.

ibmcloud ce domainmapping update --domain-name www.example.com --tls-secret mytlssecret2

Example output

Updating domainmapping 'www.example.com'...

Function commands

A function is a stateless code snippet that performs tasks as it is invoked by HTTP requests. With IBM Code Engine functions, you can run your business logic in a scalable and serverless way. IBM Code Engine functions provide an optimized runtime environment to support low latency and rapid scale-out scenarios. Your function code can be written in a managed runtime that includes specific Node.js or Python versions.

You must be within the context of a project before you use function commands.

For more information about working with Functions, see Working with Functions.

`ibmcloud ce function bind`

Bind an IBM Cloud service instance to a function.

ibmcloud ce function bind --name FUNCTION_NAME (--service-instance SI_NAME | --service-instance-id SI_ID) [--no-wait] [--prefix PREFIX] [--quiet] [--role ROLE] [--service-credential SERVICE_CREDENTIAL] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--name, -n: The name of the function to bind. This value is required.
--no-wait, --nw: Bind the service instance and do not wait for the service binding to be ready. If you specify the no-wait option, the service binding creation is started and the command exits without waiting for it to complete. Use the function get command to check the function bind status. This value is optional. The default value is false.
--prefix, -p: A prefix for environment variables that are created for this service binding. Must contain only uppercase letters, numbers, and underscores (_), and cannot start with a number. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--role, -r: The name of a service role for the new service credential that is created for this service binding. Valid values include Reader, Writer, Manager, or a service-specific role. The option defaults to Manager or the first role provided by the service if Manager is not supported. This option is ignored if --service-credential is specified. This value is optional.
--service-credential, --sc: The name of an existing service credential to use for this service binding. If you do not specify a service instance credential, new credentials are generated during the bind action. This value is optional.
--service-instance, --si: The name of an existing IBM Cloud service instance to bind to the function. This value is optional.
--service-instance-id, --siid: The GUID of an existing IBM Cloud service instance to bind to the function. This value is optional.
--wait, -w: Bind the service instance and wait for the service binding to be ready. If you specify the --wait option, the function bind waits for a maximum time in seconds, as set by the --wait-timeout option, for the function bind to complete successfully. If the function bind is not completed successfully or fails within the specified --wait-timeout period, the command fails. This value is optional. The default value is true.
--wait-timeout, --wto: The length of time in seconds to wait for the service binding to be ready. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 300.

Example

ibmcloud ce fn bind --name myfunction --service-instance my-object-storage

Example output

Binding service instance...
Status: Done
OK

`ibmcloud ce function create`

Create a function.

ibmcloud ce function create --name FUNCTION_NAME [--build-commit BUILD_COMMIT] [--build-context-dir BUILD_CONTEXT_DIR] [--build-git-repo-secret BUILD_GIT_REPO_SECRET] [--build-source BUILD_SOURCE] [--build-timeout BUILD_TIMEOUT] [--code-bundle CODE_BUNDLE] [--code-bundle-secret CODE_BUNDLE_SECRET] [--cpu CPU] [--env ENV] [--env-from-configmap ENV_FROM_CONFIGMAP] [--env-from-secret ENV_FROM_SECRET] [--force] [--inline-code INLINE_CODE] [--main MAIN] [--maxexecutiontime MAXEXECUTIONTIME] [--memory MEMORY] [--no-wait] [--output OUTPUT] [--quiet] [--runtime RUNTIME] [--scale-down-delay SCALE_DOWN_DELAY] [--visibility VISIBILITY] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

-n, --name

The name of the function. Use a name that is unique within the project.

The name must begin with a lowercase letter.
The name must end with a lowercase alphanumeric character.
The name must be 63 characters or fewer and can contain lowercase letters, numbers, and hyphens (-).

This value is required.

--runtime, -r

The runtime to use for the function. To find supported runtimes for this region, run ibmcloud ce function runtimes. See Runtimes. This value is required.

--build-commit, --commit, --bcm, --cm, --revision

The commit, tag, or branch in the source repository to pull. This value is optional.

--build-context-dir, --context-dir, --bcdr, --cdr

The directory in the repository that contains the source code for your function. This value is optional.

--build-git-repo-secret, --git-repo-secret, --bgrs, --grs, --repo

The name of the SSH secret, which contains the credentials to access the private repository that contains the source code to build your code bundle image. To create this SSH secret, use the secret create --format SSH command. An SSH secret is also used as a Git repository access secret. This option is allowed only if the --build-source option is set to the URL of a Git repository. This value is optional.

--build-source, --source, --bsrc, --src

The URL of the Git repository or the path to local source that contains your source code; for example https://github.com/IBM/CodeEngine or .. This value is optional.

--build-timeout, --bto

The amount of time, in seconds, that can pass before the build must succeed or fail. This value is optional. The default value is 600.

--code-bundle, --cb

The name of the code-bundle image to use for this function. When build-source is specified, this value is the path to the output image generated by the build push. When build-source is not specified, this value is the path to the existing code bundle image. The format is REGISTRY/NAMESPACE/REPOSITORY:TAG where TAG is optional. If TAG is not specified, the default is latest. This value is optional.

--code-bundle-secret, --cs, --cbs

The name of the registry secret that is used to authenticate with a private registry. You can add the registry secret by running the registry create command. This value is optional.

--cpu

The amount of CPU set for the instance of the function. For valid values see Supported memory and CPU combinations. This value is optional. The default value is 1.

--env, -e

Set environment variables in the function. Must be in NAME=VALUE format. This action adds a new environment variable or overrides an existing environment variable. Specify one environment variable per --env option; for example, --env envA=A --env envB=B. This value is optional.

--env-cm, --env-from-configmap

Set environment variables from the key-value pairs that are stored in this configmap by using one of the following ways.

To add environment variables for all keys in a configmap that is named configmapName, use the value configmapName. You can modify the environment variable names by specifying a prefix when referencing the configmap. To specify a prefix, use the value PREFIX=CONFIGMAP_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_CONFIGMAP>. For example, to set the prefix for all variable names of keys in configmap configmapName to CUSTOM_, use the value CUSTOM_=configmapName. If the configmap configmapName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a configmap that is named configmapName, use the value configmapName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a configmap that is named configmapName, use the value configmapName:myKey=key1.

This value is optional.

--env-sec, --env-from-secret

Set environment variables from the key-value pairs that are stored in a secret by using one of the following ways.

To add environment variables for all keys in a secret that is named secretName, use the value secretName. You can modify the environment variable names by specifying a prefix when referencing the secret. To specify a prefix, use the value PREFIX=SECRET_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_SECRET>. For example, to set the prefix for all variable names of keys in secret secretName to CUSTOM_, use the value CUSTOM_=secretName. If the secret secretName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a secret that is named secretName, use the value secretName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a secret that is named secretName, use the value secretName:myKey=key1.

This value is optional.

--force, -f

Do not verify the existence of specified configmap and secret references. This value is optional. The default value is false.

--inline-code

Specify the path to a file that contains the source code for your function. The code is stored inline with the function. This value is optional.

--main, --fn-main

Specify the name of your main function in the provided source code. This option is required when the name is not main. This value is optional. The default value is main.

--maxexecutiontime, --met

The maximum amount of time in seconds for this function to complete its run. This value is optional. The default value is 60.

--memory, -m

The amount of memory that is set for the function. Use M for megabytes or G for gigabytes. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 4G.

--no-wait, --nw

Do not wait for the build run to complete. This value is optional. The default value is true.

--output, -o

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--scale-down-delay, --sdd

The amount of time in seconds an instance is active after an invocation completes. This option can reduce cold start times. For more information, see Can I keep my function instance alive longer?. This value is optional. The default value is 1.

--visibility, -v

The visibility for the function. Valid values are public, private, and project. Visibility can only be private if the project supports function private visibility. This value is optional. The default value is public.

--wait, -w

Wait for the build run to complete. This value is optional. The default value is true.

--wait-timeout, --wto

The length of time in seconds to wait for the function to be ready. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

ibmcloud ce fn create --name myfunction --build-source main.js --runtime nodejs-18

Example output

Preparing function 'myfunction' for build push...
Creating function 'myfunction'...
Packaging files to upload from source path 'main.js'...
Submitting build run 'myfunction-run-111111-12345678'...
Creating image 'private.stg.icr.io/ce--1a1a1-11c22def3rhz/function-myfunction:12345678-1111-dexla'...
Waiting for build run to complete...
Build run status: 'Running'
Build run completed successfully.
Run 'ibmcloud ce buildrun get -n myfunction-run-111111-12345678' to check the build run status.
Waiting for function 'myfunction' to become ready...
Function 'myfunction' is ready.
OK                                                
Run 'ibmcloud ce function get -n myfunction' to see more details.

https://myfunction.11c22def3rhz.us-south.codeengine.appdomain.cloud

When you run ibmcloud ce fn get -n 'myfunction' to check the function status, the URL for your function is displayed.

`ibmcloud ce function delete`

Delete a function.

ibmcloud ce function delete --name FUNCTION_NAME [--force] [--ignore-not-found] [--quiet]

Command Options

--name, -n: The name of the function. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce fn delete --name myfunction

Example output

Are you sure you want to delete function 'myfunction'? [y/N]> y
Deleting function 'myfunction'...
OK

`ibmcloud ce function get`

Display the details of a function.

ibmcloud ce function get --name FUNCTION_NAME [--output OUTPUT] [--quiet] [--save SAVE]

Command Options

--name, -n: The name of the function. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--save, -s: Save the source source code of the function to the local file system. This option is supported for only functions that were created with inline code. This value is optional.

Example

ibmcloud ce fn get --name myfunction

Example output

Getting function 'myfunction'...
OK

Name:          myfunction  
Project Name:  myproject 
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111 
Age:           6m8s  
Created:       2023-06-22T19:59:51Z
URL:           https://myfunction.11c22def3rhz.us-south.codeengine.appdomain.cloud  
Status:        Ready  

Resources:    
  CPU:                 0.25  
  Memory:              500M  
  Max Execution Time:  60 seconds  

Build Information:    
  Build Run Name:     myfunction-run-111111-12345678 
  Build Type:         local  
  Build Strategy:     codebundle-nodejs-18  
  Timeout:            600  
  Source:             main.js  
                      
  Build Run Summary:  Succeeded  
  Build Run Status:   Succeeded  
  Build Run Reason:   All Steps have completed executing  
  Run 'ibmcloud ce buildrun get -n myfunction-run-111111-12345678' for details.  

Function Code:    
  Runtime:        nodejs-18 (managed)  
  Bundle Secret:  ce-auto-icr-private-us-south  
  Code Bundle:    cr://icr.io/ce--1a1a1-11c22def3rhz/function-myfunction:12345678-1111-dexla 
  Main:           main()

`ibmcloud ce function list`

List all functions in a project.

ibmcloud ce function list [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce fn delete --name myfunction

Example output

Name           Status     URL                                                                    CPU   Memory  Age  
hellofunction  Ready      https://hellofunction.4svg40kna19.us-south.codeengine.appdomain.cloud  0.25  500M    25h  
myfunction     Ready      https://myfun1.4svg40kna19.us-south.codeengine.appdomain.cloud         0.25  1G      8d   
helloworld     Ready      https://myfunction1.4svg40kna19.us-south.codeengine.appdomain.cloud    0.25  1G      16d  
myfunction1    Ready      https://myfunction111.4svg40kna19.us-south.codeengine.appdomain.cloud  0.25  500M    25h  
myfunction3    Ready      https://myfunction41.4svg40kna19.us-south.codeengine.appdomain.cloud   0.25  500M    25h

`ibmcloud ce function runtimes`

List available function runtimes.

ibmcloud ce function runtimes [--all] [--output OUTPUT] [--quiet]

Command Options

--all, -A: Display all runtimes, including deprecated runtimes. This value is optional. The default value is false.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce fn runtimes

Example output

Name         ID           Family  Default  Optimized  
Node.js 18   nodejs-18    nodejs  true     true  
Python 3.11  python-3.11  python  true     true

`ibmcloud ce function unbind`

Unbind IBM Cloud service instances from a function.

ibmcloud ce function unbind --name FUNCTION_NAME (--binding BINDING_NAME | --all) [--quiet]

Command Options

--name, -n: The name of the function to unbind. This value is required.
--all, -A: Unbinds all service instances for this function. This value is required if --binding is not specified. The default value is false.
--binding, -b: The name of the binding to unbind. Run ibmcloud ce function get -n FUNCTION_NAME to view binding names. This value is required if --all is not specified.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce fn unbind --name myfunction --all

Example output

Removing bindings from 'myfunction'...
OK

`ibmcloud ce function update`

Update a function.

ibmcloud ce function update --name FUNCTION_NAME [--build-clear] [--build-commit BUILD_COMMIT] [--build-commit-clear] [--build-context-dir BUILD_CONTEXT_DIR] [--build-git-repo-secret BUILD_GIT_REPO_SECRET] [--build-git-repo-secret-clear] [--build-source BUILD_SOURCE] [--build-timeout BUILD_TIMEOUT] [--code-bundle CODE_BUNDLE] [--code-bundle-secret CODE_BUNDLE_SECRET] [--cpu CPU] [--env ENV] [--env-from-configmap ENV_FROM_CONFIGMAP] [--env-from-configmap-rm ENV_FROM_CONFIGMAP_RM] [--env-from-secret ENV_FROM_SECRET] [--env-from-secret-rm ENV_FROM_SECRET_RM] [--env-rm ENV_RM] [--force] [--inline-code INLINE_CODE] [--main MAIN] [--maxexecutiontime MAXEXECUTIONTIME] [--memory MEMORY] [--no-wait] [--output OUTPUT] [--quiet] [--rebuild] [--runtime RUNTIME] [--scale-down-delay SCALE_DOWN_DELAY] [--visibility VISIBILITY] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--name, -n

Required. The name of the function. This value is required.

--build-clear, --bc

Remove the association of a build from this function. The build clear option is allowed only if your function currently has an associated build. This value is optional. The default value is false.

--build-commit, --commit, --bcm, --cm, --revision

The commit, tag, or branch in the source repository to pull. This value is optional.

--build-commit-clear, --commit-clear, --bcmc, --cmc

Clear the commit, tag, or branch in the source repository to pull. The commit clear option is allowed only if your function currently has an associated build. This value is optional. The default value is false.

--build-context-dir, --context-dir, --bcdr, --cdr

The directory in the repository that contains the source code for your function. This option is allowed only if the --build-source option is set. This value is optional.

--build-git-repo-secret, --git-repo-secret, --bgrs, --grs, --repo

The name of the SSH secret that contains the credentials to access the private repository that contains the source code to build your image. This value is optional.

--build-git-repo-secret-clear, --git-repo-secret-clear, --bgrsc, --grsc

Clear the SSH secret. This option is allowed only if your function currently has an associated build. This value is optional. The default value is false.

--build-source, --source, --bsrc, --src

The URL of the Git repository or the path to local source that contains your source code; for example https://github.com/IBM/CodeEngine or .. This value is optional.

--build-timeout, --bto

The amount of time, in seconds, that can pass before the build must succeed or fail. This value is optional. The default value is 600.

--code-bundle, --cb

--code-bundle-secret, --cs, --cbs

The name of the registry secret that is used to authenticate with a private registry. You can add the registry secret by running the registry create command. This value is optional.

--cpu

The amount of CPU set for the instance of the function. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 1.

--env, -e

--env-cm, --env-from-configmap

Set environment variables from the key-value pairs that are stored in this configmap by using one of the following ways:

To add environment variables for all keys in a configmap that is named configmapName, use the value configmapName. You can modify the environment variable names by specifying a prefix when referencing the configmap. To specify a prefix, use the value PREFIX=CONFIGMAP_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_CONFIGMAP>. For example, to set the prefix for all variable names of keys in configmap configmapName to CUSTOM_, use the value CUSTOM_=configmapName. If the configmap configmapName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a configmap that is named configmapName, use the value configmapName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a configmap that is named configmapName, use the value configmapName:myKey=key1.

This value is optional.

--env-from-configmap-rm, --env-cm-rm

--env-sec, --env-from-secret

Set environment variables from the key-value pairs that are stored in a secret by using one of the following ways:

To add environment variables for all keys in a secret that is named secretName, use the value secretName. You can modify the environment variable names by specifying a prefix when referencing the secret. To specify a prefix, use the value PREFIX=SECRET_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_SECRET>. For example, to set the prefix for all variable names of keys in secret secretName to CUSTOM_, use the value CUSTOM_=secretName. If the secret secretName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a secret that is named secretName, use the value secretName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a secret that is named secretName, use the value secretName:myKey=key1.

This value is optional.

--env-from-secret-rm, --env-sec-rm

--env-rm

--force, -f

--inline-code

Specify the path to a file containing the source code for your function. The code is stored inline with the function. This value is optional.

--main, --fn-main

Specify the name of your main function in the provided source code. This option is required when the name is not main. This value is optional. The default value is main.

--maxexecutiontime, --met

The maximum execution time in seconds for this function to complete its run. This value is optional. The default value is 60.

--memory, -m

--no-wait, --nw

--output, -o

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--rebuild

Rebuild the image from source. The rebuild option is allowed only if your function currently has an associated build. This value is optional. The default value is false.

--runtime, -r

The runtime to use for the function. To find supported runtimes for this region, run ibmcloud ce function runtimes. See Runtimes. This value is optional.

--scale-down-delay, --sdd

--visibility, -v

The visibility for the function. Valid values are public, private, and project. Visibility can only be private if the project supports function private visibility. This value is optional.

--wait, -w

Wait for the build run to complete. This value is optional. The default value is true.

--wait-timeout, --wto

Example

ibmcloud ce fn update --name myfunction --runtime nodejs-18 --build-source main.js

Example output

Preparing function 'myfunction' for build push...
Updating function 'myfunction'...
Packaging files to upload from source path 'main.js'...
Submitting build run 'myfunction-run-111111-12345678'...
Creating image 'icr.io/ce--1a1a1-11c22def3rhz/function-myfunction:12345678-1111-dexla'...
Waiting for build run to complete...
Build run status: 'Running'
Build run completed successfully.
Run 'ibmcloud ce buildrun get -n myfunction-run-111111-12345678' to check the build run status.
Waiting for function 'myfunction' to become ready...
Function 'myfunction' is ready.
OK                                                
Run 'ibmcloud ce function get -n myfunction' to see more details.

https://myfunction.11c22def3rhz.us-south.codeengine.appdomain.cloud

When you run ibmcloud ce fn get -n 'myfunction' to check the function status, the URL for your function is displayed.

Help command

Show help.

`ibmcloud ce help`

Show help.

ibmcloud ce help COMMAND

Job commands

A job runs one or more instances of your executable code in parallel. Unlike applications, which handle HTTP requests, jobs are designed to run one time and exit. When you create a job, you can specify workload configuration information that is used each time that the job is run. Use job commands to create a configuration for your job.

You must be within the context of a project before you use job commands.

For more information about working with jobs, see Running jobs.

To see CLI help for the job commands, run ibmcloud ce job -h.

`ibmcloud ce job bind`

Bind an IBM Cloud service instance to a job.

ibmcloud ce job bind --name JOB_NAME (--service-instance SI_NAME | --service-instance-id SI_ID) [--no-wait] [--prefix PREFIX] [--quiet] [--role ROLE] [--service-credential SERVICE_CREDENTIAL] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--name, -n: The name of the job to bind. This value is required.
--no-wait, --nw: Bind the service instance and do not wait for the service binding to be ready. If you specify the --no-wait option, the service binding creation is started and the command exits without waiting for it to complete. Use the job get command to check the job bind status. This value is optional. The default value is false.
--prefix, -p: A prefix for environment variables that are created for this service binding. Must contain only uppercase letters, numbers, and underscores (_), and cannot start with a number. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--role, -r: The name of a service role for the new service credential that is created for this service binding. Valid values include Reader, Writer, Manager, or a service-specific role. The option defaults to Manager or the first role provided by the service if Manager is not supported. This option is ignored if --service-credential is specified. This value is optional.
--service-credential, --sc: The name of an existing service credential to use for this service binding. If you do not specify a service instance credential, new credentials are generated during the bind action. This value is optional.
--service-instance, --si: The name of an existing IBM Cloud service instance to bind to the job. This value is optional.
--service-instance-id, --siid: The GUID of an existing IBM Cloud service instance to bind to the job. This value is optional.
--wait, -w: Bind the service instance and wait for the service binding to be ready. If you specify the --wait option, the job bind waits for a maximum time in seconds, as set by the --wait-timeout option, for the job bind to complete successfully. If the job bind is not completed successfully or fails within the specified --wait-timeout period, the command fails. This value is optional. The default value is true.
--wait-timeout, --wto: The length of time in seconds to wait for the service binding to be ready. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 300.

Example

In this example, bind your service instance called my-object-storage to your job that is called hello.

ibmcloud ce job bind --name hello --service-instance my-object-storage

Example output

Binding service instance...
Waiting for service binding to become ready...
Status: Pending (Processing Resource)
Status: Pending (Processing Resource)
Status: Creating service binding
Status: Creating service binding
Status: Ready
OK

`ibmcloud ce job create`

Create a job.

ibmcloud ce job create --name JOB_NAME ((--image IMAGE_REF | (--build-source SOURCE [--image IMAGE_REF])) [--argument ARGUMENT] [--array-indices ARRAY_INDICES] [--array-size ARRAY_SIZE] [--build-commit BUILD_COMMIT] [--build-context-dir BUILD_CONTEXT_DIR] [--build-dockerfile BUILD_DOCKERFILE] [--build-git-repo-secret BUILD_GIT_REPO_SECRET] [--build-size BUILD_SIZE] [--build-strategy BUILD_STRATEGY] [--build-timeout BUILD_TIMEOUT] [--command COMMAND] [--cpu CPU] [--env ENV] [--env-from-configmap ENV_FROM_CONFIGMAP] [--env-from-secret ENV_FROM_SECRET] [--ephemeral-storage EPHEMERAL_STORAGE] [--force] [--maxexecutiontime MAXEXECUTIONTIME] [--memory MEMORY] [--mode MODE] [--mount-configmap MOUNT_CONFIGMAP] [--mount-secret MOUNT_SECRET] [--no-wait] [--output OUTPUT] [--quiet] [--registry-secret REGISTRY_SECRET] [--retrylimit RETRYLIMIT] [--service-account SERVICE_ACCOUNT] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

-n, --name

The name of the job. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 63 characters or fewer and can contain lowercase letters, numbers, and hyphens (-).

This value is required.

--argument, --arg, -a

Set arguments for runs of the job. Specify one argument per --argument option; for example, -a argA -a argB. This value is optional.

--array-indices, --ai

Specifies the array indices that are used for runs of the job. Specify the list or range of indices that are separated by hyphens (-) or commas (,); for example, 0,3,6,9 or 1-5,7-8,10. The maximum is 999999. This option can only be specified if the --array-size option is not specified. This value is optional. The default value is 0.

--array-size, --as, --instances, --is

Specifies the number of instances that are used for runs of the job. When you use this option, the system converts to array indices. For example, if you specify instances of 5, the system converts to array-indices of 0 - 4. This option can only be specified if the --array-indices option is not specified. This value is optional. The default value is 1.

--build-commit, --commit, --bcm, --cm, --revision

The commit, tag, or branch in the source repository to pull. The build commit option is allowed only if the --build-source option is set to the URL of a Git repository. This value is optional.

--build-context-dir, --context-dir, --bcdr, --cdr

--build-dockerfile, --dockerfile, --bdf, --df

--build-git-repo-secret, --git-repo-secret, --bgrs, --grs, --repo

--build-size, --size, --bsz, --sz

--build-source, --source, --bsrc, --src

The URL of the Git repository or the path to local source that contains your source code; for example https://github.com/IBM/CodeEngine or .. This value is optional.

--build-strategy, --strategy, --bstr, --str

--build-timeout, --bto

--command, --cmd, -c

Set commands for runs of the job. Specify one command per --command option; for example, --cmd cmdA --cmd cmdB. This value overrides the default command that is specified within the container image. This value is optional.

--cpu

The amount of CPU to set for runs of the job. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 1.

--env, -e

Set environment variables for runs of the job. Must be in NAME=VALUE format. This action adds a new environment variable or overrides an existing environment variable. Specify one environment variable per --env option; for example, --env envA=A --env envB=B. This value is optional.

--env-cm, --env-from-configmap

Set environment variables from the key-value pairs that are stored in this configmap by using one of the following ways:

To add environment variables for all keys in a configmap that is named configmapName, use the value configmapName. You can modify the environment variable names by specifying a prefix when referencing the configmap. To specify a prefix, use the value PREFIX=CONFIGMAP_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_CONFIGMAP>. For example, to set the prefix for all variable names of keys in configmap configmapName to CUSTOM_, use the value CUSTOM_=configmapName. If the configmap configmapName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a configmap that is named configmapName, use the value configmapName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a configmap that is named configmapName, use the value configmapName:myKey=key1.

This value is optional.

--env-sec, --env-from-secret

Set environment variables from the key-value pairs that are stored in a secret by using one of the following ways:

To add environment variables for all keys in a secret that is named secretName, use the value secretName. You can modify the environment variable names by specifying a prefix when referencing the secret. To specify a prefix, use the value PREFIX=SECRET_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_SECRET>. For example, to set the prefix for all variable names of keys in secret secretName to CUSTOM_, use the value CUSTOM_=secretName. If the secret secretName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a secret that is named secretName, use the value secretName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a secret that is named secretName, use the value secretName:myKey=key1.

This value is optional.

--ephemeral-storage, --es

The amount of ephemeral storage to set for runs of the job. Use M for megabytes or G for gigabytes. This value is optional. The default value is 400M.

--force, -f

Do not verify the existence of specified configmap and secret references. Configmap references are specified with the --env-from-configmap option. Secret references are specified with the --env-from-secret or --registry-secret options. This value is optional. The default value is false.

--image, -i

The name of the image that is used for runs of the job. The format is REGISTRY/NAMESPACE/REPOSITORY:TAG where REGISTRY and TAG are optional. If REGISTRY is not specified, the default is docker.io. If TAG is not specified, the default is latest. The image option is required if the --build-source option is not specified. This value is optional.

--maxexecutiontime, --met

The maximum execution time in seconds for runs of the job. This option can only be specified if mode is task. This value is optional. The default value is 7200.

--memory, -m

The amount of memory that is set for runs of the job. Use M for megabytes or G for gigabytes. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 4G.

--mode

The mode for runs of the job. Valid values are task and daemon. In task mode, the maxexecutiontime and retrylimit options apply. In daemon mode, since there is no timeout and failed instances are restarted indefinitely, the --maxexecutiontime and --retrylimit options are not allowed. This value is optional. The default value is task.

--mount-configmap, --mount-cm

Add the contents of a configmap to the file system of runs of the job by providing a mount directory and the name of a configmap, with the format MOUNT_DIRECTORY=CONFIGMAP_NAME. Each mounted configmap must use a unique mount directory. For each key-value pair in the configmap, a file is added to the specified mount directory where the filename is the key and the contents of the file is the value of the key-value pair. Specify one mount configuration per --mount-configmap option; for example, --mount-configmap /etc/config-a=config-a --mount-configmap /etc/config-b=config-b. This value is optional.

--mount-secret, --mount-sec

Add the contents of a secret to the file system of runs of the job by providing a mount directory and the name of a secret, with the format MOUNT_DIRECTORY=SECRET_NAME. Each mounted secret must use a unique mount directory. For each key-value pair in the secret, a file is added to the specified mount directory where the filename is the key and the contents of the file is the value of the key-value pair. Specify one mount configuration per --mount-secret option; for example, --mount-secret /etc/secret-a=secret--a --mount-secret /etc/secret-b=secret-b. This value is optional.

--no-wait, --nw

Do not wait for the build run to complete. If you specify the --no-wait option, the build run begins and does not wait. Use the buildrun get command to check the build run status. The no-wait option is allowed only if the --build-source option is set. This value is optional. The default value is true.

--output, -o

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--registry-secret, --rs

The name of the registry secret. The registry secret is used to authenticate with a private registry when you download the container image. This value is optional.

--retrylimit, -r

The number of times to rerun an instance of the job before the job is marked as failed. An array index of a job is rerun when it gives an exit code other than zero. This option can only be specified if mode is task. This value is optional. The default value is 3.

--service-account, --sa

--wait, -w

Wait for the build run to complete. If you specify the --wait option, the build run waits for a maximum time in seconds, as set by the --wait-timeout option, for the build run to complete. If the build run is not completed within the specified --wait-timeout period, the build run fails. The wait option is allowed only if the --build-source option is set. This value is optional. The default value is false.

--wait-timeout, --wto

The length of time in seconds to wait for the build run to complete. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The wait-timeout option is allowed only if the --build-source option is set. The default value is 600.

Example

The following example uses the container image icr.io/codeengine/firstjob and assigns 2G MB as memory and 1 CPU to the container. For more information about selecting valid memory and CPU values, see Supported memory and CPU combinations.

ibmcloud ce job create --image icr.io/codeengine/firstjob --name hellojob --memory 2G --cpu 1

Example output

Creating job 'hellojob'...
OK

`ibmcloud ce job delete`

Delete a job and its associated job runs.

ibmcloud ce job delete --name JOB_NAME [--force] [--ignore-not-found] [--orphan-job-runs] [--quiet]

Command Options

--name, -n: The name of the job. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--orphan-job-runs, -o: Specify to keep any job runs that are associated with this job configuration. These orphaned job runs must then be deleted separately. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce job delete --name hello

Example output

Are you sure you want to delete job hello? [y/N]> y
Deleting job 'hello'...
OK

When you run the ibmcloud ce job delete command to delete a job, all the submitted job runs that reference this job are also deleted.

`ibmcloud ce job get`

Display the details of a job.

ibmcloud ce job get --name JOB_NAME [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the job. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce job get --name hellojob

Example output

Getting job 'hellojob'...
OK

Name:          hellojob
ID:            abcdabcd-abcd-abcd-abcd-abcdabcd1111
Project Name:  myproj
Project ID:    01234567-abcd-abcd-abcd-abcdabcd2222
Age:           59s
Created:       2021-03-01T15:33:30-05:00

Last Job Run:
  Name:     hellojob-jobrun-abcde
  Age:      32d
  Created:  2021-06-06T13:52:42-04:00

Image:                icr.io/codeengine/firstjob
Resource Allocation:
    CPU:     1
    Memory:  4G

Runtime:
    Mode:                  task
    Array Indices:         0
    Array Size:            1
    Max Execution Time:    7200
    Retry Limit:           3

`ibmcloud ce job list`

List all jobs in a project.

ibmcloud ce job list [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce job list

Example output

Name           Age   Last Job Run Name      Last Job Run Age
demo           110d  demo-jobrun-hkkmx      108d
myjob-envvar   107d
hellojob       7s
myjob          60d   myjob-977v7            58d
testjob        88d   testjob-jobrun-kzxlp   72d

`ibmcloud ce job unbind`

Unbind IBM Cloud service instances from a job to remove existing service bindings.

ibmcloud ce job unbind --name JOB_NAME (--binding BINDING_NAME | --all) [--quiet]

Command Options

--name, -n: The name of the job to unbind. This value is required.
--all, -A: Unbinds all service instances for this job. This value is required if --binding is not specified. The default value is false.
--binding, -b: The name of the binding to unbind. Run ibmcloud ce job get -n JOB_NAME to view binding names. This value is required if --all is not specified.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

In this example, remove all bindings from your job called hello.

ibmcloud ce job unbind --name hello --all

Example output

Removing service bindings...
OK

`ibmcloud ce job update`

Update a job.

ibmcloud ce job update --name JOB_NAME [--argument ARGUMENT] [--arguments-clear] [--array-indices ARRAY_INDICES] [--array-size ARRAY_SIZE] [--build-clear] [--build-commit BUILD_COMMIT] [--build-commit-clear] [--build-context-dir BUILD_CONTEXT_DIR] [--build-dockerfile BUILD_DOCKERFILE] [--build-git-repo-secret BUILD_GIT_REPO_SECRET] [--build-git-repo-secret-clear] [--build-size BUILD_SIZE] [--build-source BUILD_SOURCE] [--build-strategy BUILD_STRATEGY] [--build-timeout BUILD_TIMEOUT] [--command COMMAND] [--commands-clear] [--cpu CPU] [--env ENV] [--env-from-configmap ENV_FROM_CONFIGMAP] [--env-from-configmap-rm ENV_FROM_CONFIGMAP_RM] [--env-from-secret ENV_FROM_SECRET] [--env-from-secret-rm ENV_FROM_SECRET_RM] [--env-rm ENV_RM] [--ephemeral-storage EPHEMERAL_STORAGE] [--force] [--image IMAGE] [--maxexecutiontime MAXEXECUTIONTIME] [--memory MEMORY] [--mode MODE] [--mount-configmap MOUNT_CONFIGMAP] [--mount-rm MOUNT_RM] [--mount-secret MOUNT_SECRET] [--no-wait] [--output OUTPUT] [--quiet] [--rebuild] [--registry-secret REGISTRY_SECRET] [--registry-secret-clear] [--retrylimit RETRYLIMIT] [--service-account SERVICE_ACCOUNT] [--service-account-clear] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--name, -n

The name of the job. This value is required.

--argument, --arg, -a

Set arguments for runs of the job. Specify one argument per --argument option; for example, -a argA -a argB. This value is optional.

--arguments-clear, --ac

Clear job arguments. This value is optional. The default value is false.

--array-indices, --ai

--array-size, --as, --instances, --is

--build-clear, --bc

Remove the association of a build from this job. The build clear option is allowed only if your job currently has an associated build. This value is optional. The default value is false.

--build-commit, --commit, --bcm, --cm, --revision

The commit, tag, or branch in the source repository to pull. The build commit option is allowed only if the --build-source option is set to the URL of a Git repository on this job update command, or your job currently has an associated build from a Git repository source. This value is optional.

--build-commit-clear, --commit-clear, --bcmc, --cmc

Clear the commit, tag, or branch in the source repository to pull. The commit clear option is allowed only if your job currently has an associated build. This value is optional. The default value is false.

--build-context-dir, --context-dir, --bcdr, --cdr

The directory in the repository that contains the buildpacks file or the Dockerfile. The build context directory option is allowed only if the --build-source option is set on this job update command, or your job currently has an associated build. This value is optional.

--build-dockerfile, --dockerfile, --bdf, --df

The path to the Dockerfile. Specify this option only if the name is other than Dockerfile. The build dockerfile option is allowed if the --build-source option is set on this job update command, or your job currently has an associated build. This value is optional. The default value is Dockerfile.

--build-git-repo-secret, --git-repo-secret, --bgrs, --grs, --repo

--build-git-repo-secret-clear, --git-repo-secret-clear, --bgrsc, --grsc

Clear the SSH secret. This option is allowed if your job currently has an associated build. This value is optional. The default value is false.

--build-size, --size, --bsz, --sz

The size for the build, which determines the amount of resources used. Valid values are small, medium, large, xlarge, and xxlarge. For details, see Determining the size of the build. The build size option is allowed only if the --build-source option is set on this job update command, or your job currently has an associated build. This value is optional. The default value is medium.

--build-source, --source, --bsrc, --src

The URL of the Git repository or the path to local source that contains your source code; for example https://github.com/IBM/CodeEngine or .. This value is optional.

--build-strategy, --strategy, --bstr, --str

The strategy to use for building the image. Valid values are dockerfile and buildpacks. The build strategy option is allowed only if the --build-source option is set on this job update command, or your job currently has an associated build. If not specified, the build strategy is determined by Code Engine if --build-source is specified and the source is on your local machine. This value is optional. The default value is dockerfile.

--build-timeout, --bto

The amount of time, in seconds, that can pass before the build must succeed or fail. The build timeout option is allowed only if the --build-source option is set on this job update command, or your job currently has an associated build. This value is optional. The default value is 600.

--command, --cmd, -c

--commands-clear, --cc

Clear job commands. This value is optional. The default value is false.

--cpu

The amount of CPU to set for runs of the job. This value updates any --cpu value that is assigned in the job. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 0.

--env, -e

--env-cm, --env-from-configmap

Set environment variables from the key-value pairs that are stored in this configmap by using one of the following ways:

To add environment variables for all keys in a configmap that is named configmapName, use the value configmapName. You can modify the environment variable names by specifying a prefix when referencing the configmap. To specify a prefix, use the value PREFIX=CONFIGMAP_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_CONFIGMAP>. For example, to set the prefix for all variable names of keys in configmap configmapName to CUSTOM_, use the value CUSTOM_=configmapName. If the configmap configmapName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a configmap that is named configmapName, use the value configmapName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a configmap that is named configmapName, use the value configmapName:myKey=key1.

This value is optional.

--env-from-configmap-rm, --env-cm-rm

--env-sec, --env-from-secret

Set environment variables from the key-value pairs that are stored in a secret by using one of the following ways:

To add environment variables for all keys in a secret that is named secretName, use the value secretName. You can modify the environment variable names by specifying a prefix when referencing the secret. To specify a prefix, use the value PREFIX=SECRET_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_SECRET>. For example, to set the prefix for all variable names of keys in secret secretName to CUSTOM_, use the value CUSTOM_=secretName. If the secret secretName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a secret that is named secretName, use the value secretName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a secret that is named secretName, use the value secretName:myKey=key1.

This value is optional.

--env-from-secret-rm, --env-sec-rm

--env-rm

--ephemeral-storage, --es

The amount of ephemeral storage to set for runs of the job. Use M for megabytes or G for gigabytes. This value is optional.

--force, -f

--image, -i

--maxexecutiontime, --met

The maximum execution time in seconds for runs of the job. This option can only be specified if mode is task. This value is optional. The default value is 7200.

--memory, -m

The amount of memory that is set for runs of the job. Use M for megabytes or G for gigabytes. For valid values, see Supported memory and CPU combinations. This value is optional.

--mode

--mount-configmap, --mount-cm

--mount-rm

Remove the contents of a configmap or secret from the file system of runs of the job by specifying the directory where the configmap or secret is mounted. Specify one mount directory per --mount-rm option; for example, --mount-rm /etc/configmap-a --mount-rm /etc/secret-b. This value is optional.

--mount-secret, --mount-sec

--no-wait, --nw

Do not wait for the build run to complete. If you specify the --no-wait option, the build run begins and does not wait. Use the buildrun get command to check the build run status. The no-wait option is allowed only if the --build-source option is set on this job update command or your job currently has an associated build. This value is optional. The default value is true.

--output, -o

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--rebuild

Rebuild image from source. The rebuild option is allowed if your job currently has an associated build. This value is optional. The default value is false.

--registry-secret, --rs

The name of the registry secret. The registry secret is used to authenticate with a private registry when you download the container image. This value is optional.

--registry-secret-clear, --rsc

Clear the registry secret. This value is optional. The default value is false.

--retrylimit, -r

--service-account, --sa

--service-account-clear, --sac

Clear the service account. This value is optional. The default value is false.

--wait, -w

Wait for the build run to complete. If you specify the --wait option, the build run waits for a maximum time in seconds, as set by the --wait-timeout option, for the build run to complete. If the build run is not completed within the specified --wait-timeout period, the build run fails. The wait option is allowed only if the --build-source option is set on this job update command or your job currently has an associated build. This value is optional. The default value is false.

--wait-timeout, --wto

The length of time in seconds to wait for the build run to complete. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The wait-timeout option is allowed if the --build-source option is set on this job update command or your job currently has an associated build. The default value is 600.

Example

ibmcloud ce job update --name hellojob --cpu 2

Example output

Updating job 'hellojob'...
OK

Jobrun commands

You must be within the context of a project before you use jobrun commands.

For more information about working with jobs and job runs, see Running jobs.

To see CLI help for the jobrun commands, run ibmcloud ce jobrun -h.

`ibmcloud ce jobrun delete`

Delete a job run.

ibmcloud ce jobrun delete (--name JOBRUN_NAME | --job JOB_NAME) [--force] [--ignore-not-found] [--quiet]

Command Options

--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--job, -j: Use this option to delete all job runs of the specified job. The --job option is required, if you do not specify the --name value. This value is optional.
--name, -n: The name of the job run to delete. The --name option is required, if you do not specify the --job value. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce jobrun delete --name myjobrun -f

Example output

Deleting job run 'myjobrun'...
OK

`ibmcloud ce jobrun events`

Display the system events of job run instances. System events are retained up to 60 minutes.

ibmcloud ce jobrun events (--instance JOBRUN_INSTANCE | --jobrun JOBRUN_NAME) [--output OUTPUT] [--quiet]

Command Options

--instance, -i: The name of a specific job run instance. Use the jobrun get command to find the instance name. This value is required if --jobrun is not specified.
--jobrun, -j, --name, -n: Display the events of all the instances of the specified job run. This value is required if --instance is not specified.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

The following example displays the system event information for all the instances of a specified job run.

ibmcloud ce jobrun events --jobrun myjobrun

Example output

Getting jobrun 'myjobrun'...
Getting instances of jobrun 'myjobrun'...
Getting events for all instances of job run 'myjobrun'...
OK

myjobrun-1-0:
    Type     Reason                  Age  Source                  Messages
    Normal   Scheduled               49s  default-scheduler       Successfully assigned 4svg40kna19/myjobrun-1-0 to 10.240.64.136
    [...]
    Normal   Pulling                 34s  kubelet, 10.240.64.136  Pulling image "icr.io/codeengine/testjob"

myjobrun-2-0:
    Type    Reason     Age  Source                  Messages
    Normal  Scheduled  50s  default-scheduler       Successfully assigned 4svg40kna19/myjobrun-2-0 to 10.240.64.131
    Normal  Pulling    48s  kubelet, 10.240.64.131  Pulling image "icr.io/codeengine/testjob"

Example of system event information for specified instance of a job run

You can also display system event information for a specified instance of a job run by using the --instance option with the ibmcloud ce jobrun events command. Use the jobrun get command to display details about your job run, including the running instances of the job run.

ibmcloud ce jobrun events --instance myjobrun-2-0

Example output of system event information for specified instance of a job run

Getting events for job run instance 'myjobrun-2-0'...
OK

myjobrun-2-0:
    Type    Reason     Age    Source                  Messages
    Normal  Scheduled  3m39s  default-scheduler       Successfully assigned 4svg40kna19/myjobrun-2-0 to 10.240.64.131
    Normal  Pulling    3m37s  kubelet, 10.240.64.131  Pulling image "icr.io/codeengine/testjob"
    Normal  Pulled     2m42s  kubelet, 10.240.64.131  Successfully pulled image "icr.io/codeengine/testjob"
    Normal  Created    2m42s  kubelet, 10.240.64.131  Created container myjobrun
    Normal  Started    2m41s  kubelet, 10.240.64.131  Started container myjobrun

`ibmcloud ce jobrun get`

Display the details of a job run.

ibmcloud ce jobrun get --name JOBRUN_NAME [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the job run. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce jobrun get --name myjobrun

Example output

Getting jobrun 'myjobrun'...
Getting instances of jobrun 'myjobrun'...
Getting events of jobrun 'myjobrun'...
Run 'ibmcloud ce jobrun events -n myjobrun' to get the system events of the job run instances.
Run 'ibmcloud ce jobrun logs -f -n myjobrun' to follow the logs of the job run instances.
OK

Name:          myjobrun
[...]
Created:       2021-03-02T10:31:13-05:00

Image:                icr.io/codeengine/firstjob
Resource Allocation:
    CPU:                1
    Ephemeral Storage:  400M
    Memory:             4G

Runtime:
    Mode:                  task
    Array Indices:         1-5 
    Array Size:            5
    JOP_ARRAY_SIZE Value:  5
    Max Execution Time:    7200
    Retry Limit:           3

Status:
    Completed:          2m58s
    Instance Statuses:
        Succeeded:  5
    Conditions:
        Type      Status  Last Probe  Last Transition
    Pending   True    3m55s       3m55s
    Running   True    3m51s       3m51s
    Complete  True    2m58s       2m58s

Events:
    Type     Reason         Age                     Source                Messages
    [...]
    Normal   Updated        3m38s (x23 over 3m56s)  batch-job-controller  Updated JobRun "myjobrun"
    Normal   Updated        3m38s (x22 over 3m56s)  batch-job-controller  Updated JobRun "myjobrun"

Instances:
    Name           Running  Status     Restarts  Age
    myjobrun-1-0  0/1      Succeeded  0         3m58s
    myjobrun-2-0  0/1      Succeeded  0         3m58s
    myjobrun-3-0  0/1      Succeeded  0         3m57s
    myjobrun-4-0  0/1      Succeeded  0         3m58s
    myjobrun-5-0  0/1      Succeeded  0         3m58s

`ibmcloud ce jobrun list`

List all job runs in a project.

ibmcloud ce jobrun list [--job JOB] [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--job, -j: Use this option to only display job runs from the specified job. This value is optional.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce jobrun list

Example output

Listing job runs...
OK

Name                         Failed  Pending  Requested  Running  Succeeded  Unknown  Age
firstjob-jobrun-shnj5        0       0        0          0        1          0        11d
myjob-jobrun-fji48           0       0        0          0        5          0        11d
myjob-jobrun-xeqc8           0       0        0          0        5          0        12d
myjobrun                     0       0        0          0        5          0        7m47s
mytestjob-jobrun-el0o8       0       0        0          0        1          0        11d
testjobrun                   0       0        0          0        5          0        11d

The name of the job run listed indicates the name of the job run and the current revision of the job run.

`ibmcloud ce jobrun logs`

Display the logs of job run instances.

ibmcloud ce jobrun logs (--instance JOBRUN_INSTANCE | --jobrun JOBRUN_NAME) [--follow] [--output OUTPUT] [--quiet] [--raw] [--tail TAIL] [--timestamps]

Command Options

--follow, -f: Follow the logs of job run instances. Use this option to stream logs of job run instances. If you specify the --follow option, you must enter Ctrl+C to terminate this log command. This value is optional. The default value is false.
--instance, -i: The name of a specific job run instance. Use the jobrun get command to find the instance name. This value is required if --jobrun is not specified.
--jobrun, -j, --name, -n: Display the logs of all the instances of the specified job run. This value is required if --instance is not specified.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--raw, -r: Display logs without instance and container labels. This value is optional. The default value is false.
--tail, -t: Limit the display of logs of the specified job run instances to a maximum number of recent lines. For example, to display the last 3 lines of the logs of the specified job run instances, specify --tail 3. If this option is not specified, all lines of the logs of the specified job run instances are displayed. This value is optional. The default value is -1.
--timestamps, --ts: Include timestamps on each line in the log output. This value is optional. The default value is false.

Example

The following example displays the logs of a specific instance of a job run. Use the jobrun get command to obtain the name of the job run instances.

ibmcloud ce jobrun logs --instance myjobrun-3-0

Example output

Getting logs for job run instance 'myjobrun-3-0'...
OK

myjobrun-3-0/myjobrun:
Hi from a batch job! My index is: 3

Example of logs of all instances of a job run

The following example displays the logs of all the instances of a job run.

ibmcloud ce jobrun logs --jobrun myjobrun

Example output of logs of all instances of a job run

Getting logs for all instances of job run 'myjobrun'...
Getting jobrun 'myjobrun'...
Getting instances of jobrun 'myjobrun'...
OK

myjobrun-1-0/myjobrun:
Hi from a batch job! My index is: 1

myjobrun-2-0/myjobrun:
Hi from a batch job! My index is: 2

myjobrun-3-0/myjobrun:
Hi from a batch job! My index is: 3

myjobrun-4-0/myjobrun:
Hi from a batch job! My index is: 4

myjobrun-5-0/myjobrun:
Hi from a batch job! My index is: 5

`ibmcloud ce jobrun restart`

Restart running job run instances.

ibmcloud ce jobrun restart (--instance JOBRUN_INSTANCE | --jobrun JOBRUN_NAME) [--quiet]

Command Options

--instance, -i: The name of a specific job run instance. Use the jobrun get command to find the instance name. This value is required if --jobrun is not specified.
--jobrun, -j, --name, -n: Restart all the running instances of the specified job run. This value is required if --instance is not specified.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce jobrun restart --name myjobrun

Example output

Getting jobrun 'myjobrun'...
Getting instances of jobrun 'myjobrun'...
Restarting all running instances of job run 'myjobrun'...
OK

`ibmcloud ce jobrun resubmit`

Resubmit a job run based on the configuration of a previous job run.

ibmcloud ce jobrun resubmit --jobrun REFERENCED_JOBRUN_NAME [--argument ARGUMENT] [--arguments-clear] [--array-indices ARRAY_INDICES] [--array-size ARRAY_SIZE] [--array-size-var-override ARRAY_SIZE_VAR_OVERRIDE] [--command COMMAND] [--commands-clear] [--cpu CPU] [--env ENV] [--env-from-configmap ENV_FROM_CONFIGMAP] [--env-from-configmap-rm ENV_FROM_CONFIGMAP_RM] [--env-from-secret ENV_FROM_SECRET] [--env-from-secret-rm ENV_FROM_SECRET_RM] [--env-rm ENV_RM] [--ephemeral-storage EPHEMERAL_STORAGE] [--force] [--maxexecutiontime MAXEXECUTIONTIME] [--memory MEMORY] [--mode MODE] [--mount-configmap MOUNT_CONFIGMAP] [--mount-rm MOUNT_RM] [--mount-secret MOUNT_SECRET] [--name NAME] [--no-wait] [--output OUTPUT] [--quiet] [--retrylimit RETRYLIMIT] [--service-account SERVICE_ACCOUNT] [--service-account-clear] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--jobrun, -j

The name of the previous job run that this job run is based on. This value is required.

--argument, --arg, -a

Set arguments for this job run. Specify one argument per --argument option; for example, -a argA -a argB. This value is optional.

--arguments-clear, --ac

Clear job run arguments. This value is optional. The default value is false.

--array-indices, --ai

Specifies the array indices that are used for this job run. Specify the list or range of indices that are separated by hyphens (-) or commas (,); for example, 0,3,6,9 or 1-5,7-8,10. The maximum is 999999. This option can only be specified if the --array-size option is not specified. This value is optional.

--array-size, --as, --instances, --is

Specifies the number of instances that are used for this job run. When you use this option, the system converts to array indices. For example, if you specify instances of 5, the system converts to array-indices of 0 - 4. This option can only be specified if the --array-indices option is not specified. This value is optional. The default value is 0.

--array-size-var-override, --array-size-variable-override, --asvo

Specifies a custom value for the JOB_ARRAY_SIZE environment variable. By default, the JOB_ARRAY_SIZE environment variable is set to either the array-size value or the number of indices specified by array-indices. The value of the JOB_ARRAY_SIZE environment variable does not affect the configured array size. Use this option to enforce a constant array size value for job rerun scenarios, where only some job instances are submitted or resubmitted. This value is optional.

--command, --cmd, -c

Set commands for this job run. Specify one command per --command option; for example, --cmd cmdA --cmd cmdB. This value overrides the default command that is specified within the container image. This value is optional.

--commands-clear, --cc

Clear job run commands. This value is optional. The default value is false.

--cpu

The amount of CPU set for each array index for this job run. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 0.

--env, -e

Set environment variables for this job run. Must be in NAME=VALUE format. This action adds a new environment variable or overrides an existing environment variable. Specify one environment variable per --env option; for example, -e envA -e envB. This value is optional.

--env-cm, --env-from-configmap

Set environment variables from the key-value pairs that are stored in this configmap by using one of the following ways:

To add environment variables for all keys in a configmap that is named configmapName, use the value configmapName. You can modify the environment variable names by specifying a prefix when referencing the configmap. To specify a prefix, use the value PREFIX=CONFIGMAP_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_CONFIGMAP>. For example, to set the prefix for all variable names of keys in configmap configmapName to CUSTOM_, use the value CUSTOM_=configmapName. If the configmap configmapName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a configmap that is named configmapName, use the value configmapName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a configmap that is named configmapName, use the value configmapName:myKey=key1.

This value is optional.

--env-from-configmap-rm, --env-cm-rm

Remove environment variable references to full configmaps by using the configmap name. To remove individual key references to configmaps, use the --env-rm option. This value is optional.

--env-sec, --env-from-secret

Set environment variables from the key-value pairs that are stored in a secret by using one of the following ways:

To add environment variables for all keys in a secret that is named secretName, use the value secretName. You can modify the environment variable names by specifying a prefix when referencing the secret. To specify a prefix, use the value PREFIX=SECRET_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_SECRET>. For example, to set the prefix for all variable names of keys in secret secretName to CUSTOM_, use the value CUSTOM_=secretName. If the secret secretName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a secret that is named secretName, use the value secretName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a secret that is named secretName, use the value secretName:myKey=key1.

This value is optional.

--env-from-secret-rm, --env-sec-rm

--env-rm

--ephemeral-storage, --es

The amount of ephemeral storage for this job run. Use M for megabytes or G for gigabytes. This value is optional.

--force, -f

Do not verify the existence of specified configmap and secret references. Configmap references are specified with the --env-from-configmap option. Secret references are specified with the --env-from-secret option. This value is optional. The default value is false.

--maxexecutiontime, --met

The maximum execution time in seconds for this job run. This option can only be specified if mode is task. This value is optional. The default value is 7200.

--memory, -m

The amount of memory to assign to this job run. Use M for megabytes or G for gigabytes. For valid values, see Supported memory and CPU combinations. This value is optional.

--mode

The mode of the job run. Valid values are task and daemon. In task mode, the maxexecutiontime and retrylimit options apply. In daemon mode, since there is no timeout and failed instances are restarted indefinitely, the maxexecutiontime and retrylimit options are not allowed. This value is optional.

--mount-configmap, --mount-cm

Add the contents of a configmap to the file system of this job run by providing a mount directory and the name of a configmap, with the format MOUNT_DIRECTORY=CONFIGMAP_NAME. Each mounted configmap must use a unique mount directory. For each key-value pair in the configmap, a file is added to the specified mount directory where the filename is the key and the contents of the file is the value of the key-value pair. Specify one mount configuration per --mount-configmap option; for example, --mount-configmap /etc/config-a=config-a --mount-configmap /etc/config-b=config-b. This value is optional.

--mount-rm

Remove the contents of a configmap or secret from the file system of this job run by specifying the directory where the configmap or secret is mounted. Specify one mount directory per --mount-rm option; for example, --mount-rm /etc/configmap-a --mount-rm /etc/secret-b. This value is optional.

--mount-secret, --mount-sec

Add the contents of a secret to the file system of this job run by providing a mount directory and the name of a secret, with the format MOUNT_DIRECTORY=SECRET_NAME. Each mounted secret must use a unique mount directory. For each key-value pair in the secret, a file is added to the specified mount directory where the filename is the key and the contents of the file is the value of the key-value pair. Specify one mount configuration per --mount-secret option; for example, --mount-secret /etc/secret-a=secret--a --mount-secret /etc/secret-b=secret-b. This value is optional.

-n, --name

The name of this job run. This value is required if the referenced job does not have a related job configuration. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 53 characters or fewer and can contain lowercase letters, numbers, and hyphens (-).

This value is optional.

--no-wait, --nw

Resubmit the job run and do not wait for the instances of this job run to complete. If you specify the --no-wait option, the job run resubmit begins and does not wait. Use the jobrun get command to check the job run status. This value is optional. The default value is true.

--output, -o

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--retrylimit, -r

The number of times to rerun an instance of this job run before the job run is marked as failed. An array index of a job run is rerun when it gives an exit code other than zero. This option can only be specified if mode is task. This value is optional. The default value is 3.

--service-account, --sa

--service-account-clear, --sac

Clear the service account. This value is optional. The default value is false.

--wait, -w

Resubmit the job run and wait for the instances of this job run to complete. If you specify the --wait option, the job run resubmit waits for a maximum time in seconds, as set by the --wait-timeout option, for the job run to complete. If the job run is not completed within the specified --wait-timeout period, the job run resubmit fails. This value is optional. The default value is false.

--wait-timeout, --wto

The length of time in seconds to wait for the instances of this job run to complete. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

The following example reruns the myjobrun job run for instances 4-5. The name of the resubmitted job run is myjobresubmit.

ibmcloud ce jobrun resubmit --name myjobresubmit --jobrun myjobrun --array-indices 4-5

Example output

Getting job run 'myjobrun'...
Rerunning job run 'myjobresubmit'...
Run 'ibmcloud ce jobrun get -n myjobresubmit' to check the job run status.
OK

`ibmcloud ce jobrun submit`

Submit a job run based on a job.

ibmcloud ce jobrun submit ((--name JOBRUN_NAME --image IMAGE) | (--job JOB_NAME [--name JOBRUN_NAME])) [--argument ARGUMENT] [--array-indices ARRAY_INDICES] [--array-size ARRAY_SIZE] [--array-size-var-override ARRAY_SIZE_VAR_OVERRIDE] [--command COMMAND] [--cpu CPU] [--env ENV] [--env-from-configmap ENV_FROM_CONFIGMAP] [--env-from-secret ENV_FROM_SECRET] [--ephemeral-storage EPHEMERAL_STORAGE] [--force] [--maxexecutiontime MAXEXECUTIONTIME] [--memory MEMORY] [--mode MODE] [--mount-configmap MOUNT_CONFIGMAP] [--mount-secret MOUNT_SECRET] [--no-wait] [--output OUTPUT] [--quiet] [--registry-secret REGISTRY_SECRET] [--retrylimit RETRYLIMIT] [--service-account SERVICE_ACCOUNT] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--argument, --arg, -a

Set arguments for this job run. Specify one argument per --argument option; for example, -a argA -a argB. This value is optional.

--array-indices, --ai

--array-size, --as, --instances, --is

--array-size-var-override, --array-size-variable-override, --asvo

--command, --cmd, -c

--cpu

The amount of CPU set for each array index for this job run. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 1.

--env, -e

--env-cm, --env-from-configmap

Set environment variables from the key-value pairs that are stored in this configmap by using one of the following ways:

To add environment variables for all keys in a configmap that is named configmapName, use the value configmapName. You can modify the environment variable names by specifying a prefix when referencing the configmap. To specify a prefix, use the value PREFIX=CONFIGMAP_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_CONFIGMAP>. For example, to set the prefix for all variable names of keys in configmap configmapName to CUSTOM_, use the value CUSTOM_=configmapName. If the configmap configmapName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a configmap that is named configmapName, use the value configmapName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a configmap that is named configmapName, use the value configmapName:myKey=key1.

This value is optional.

--env-sec, --env-from-secret

Set environment variables from the key-value pairs that are stored in a secret by using one of the following ways:

To add environment variables for all keys in a secret that is named secretName, use the value secretName. You can modify the environment variable names by specifying a prefix when referencing the secret. To specify a prefix, use the value PREFIX=SECRET_NAME. Each resulting environment variable has the format <PREFIX><NAME_OF_KEY_IN_SECRET>. For example, to set the prefix for all variable names of keys in secret secretName to CUSTOM_, use the value CUSTOM_=secretName. If the secret secretName contains KEY_A, the environment variable name is CUSTOM_KEY_A.
To add environment variables for individual keys, use the format NAME:KEY_A,KEY_B. For example, to add an environment variable for a single key key1 in a secret that is named secretName, use the value secretName:key1. To assign a different name to a referenced key, use the format NAME:NEW_NAME=KEY_A. For example, to add an environment variable named myKey for a single key key1 in a secret that is named secretName, use the value secretName:myKey=key1.

This value is optional.

--ephemeral-storage, --es

The amount of ephemeral storage for this job run. Use M for megabytes or G for gigabytes. This value is optional. The default value is 400M.

--force, -f

--image, -i

The name of the image that is used for this job run. The format is REGISTRY/NAMESPACE/REPOSITORY:TAG where REGISTRY and TAG are optional. If REGISTRY is not specified, the default is docker.io. If TAG is not specified, the default is latest. If you do not specify the --job option, the --name and the --image values are required. This value is optional.

--job, -j

The name of the job configuration. View job configurations with the job list command. If you specify the --job value, you can optionally specify the --name value. If you don't specify the --job value, you must specify the --name and --image values. This value is optional.

--maxexecutiontime, --met

The maximum execution time in seconds for this job run. This option can only be specified if mode is task. This value is optional. The default value is 7200.

--memory, -m

The amount of memory to assign to this job run. Use M for megabytes or G for gigabytes. For valid values, see Supported memory and CPU combinations. This value is optional. The default value is 4G.

--mode

--mount-configmap, --mount-cm

--mount-secret, --mount-sec

-n, --name

The name of this job run. If you do not specify the --job value, then the --name and the --image values are required. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 53 characters or fewer and can contain lowercase letters, numbers, and hyphens (-).

This value is optional.

--no-wait, --nw

Submit the job run and do not wait for the instances of this job run to complete. If you specify the --no-wait option, the job run submit begins and does not wait. Use the jobrun get command to check the job run status. This value is optional. The default value is true.

--output, -o

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--registry-secret, --rs

The name of the registry secret. The registry secret is used to authenticate with a private registry when you download the container image. This value is optional.

--retrylimit, -r

--service-account, --sa

--wait, -w

Submit the job run and wait for the instances of this job run to complete. If you specify the --wait option, the job run submit waits for a maximum time in seconds, as set by the --wait-timeout option, for the job run to complete. If the job run is not completed within the specified --wait-timeout period, the job run submit fails. This value is optional. The default value is false.

--wait-timeout, --wto

Example

ibmcloud ce jobrun submit --name myjobrun --image icr.io/codeengine/firstjob --array-indices 1-5

Example output

Submitting job run 'myjobrun'...
Run 'ibmcloud ce jobrun get -n myjobrun' to check the job run status.
OK

Project commands

Use project commands to create, list, delete, and select a project as the current context.

A project is a grouping of Code Engine entities such as applications, jobs, and builds. A project is based on a Kubernetes namespace. The name of your project must be unique within your IBM Cloud® resource group, user account, and region. Projects are used to manage resources and provide access to its entities.

A project provides the following items.

Provides a unique namespace for entity names.
Manages access to project resources (inbound access).
Manages access to backing services, registries, and repositories (outbound access).
Has an automatically generated certificate for Transport Layer Service (TLS).

For more information about working with projects, see Managing projects.

You can use either project or proj in your project commands. To see CLI help for the project commands, run ibmcloud ce proj -h.

`ibmcloud ce project create`

Create a project.

ibmcloud ce project create --name PROJECT_NAME [--endpoint ENDPOINT] [--no-select] [--no-wait] [--output OUTPUT] [--quiet] [--tag TAG] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

-n, --name

The name of the project. Use a name that is unique to your region. The name must be 128 characters or fewer and can contain:

Any Unicode or alphanumeric character.
Only these special characters: spaces ( ), periods (.), colons (:), underscores (_), and hyphens (-).

This value is required.

--endpoint, -e

The endpoint for the project. Valid values are public and private. If the --endpoint option is not explicitly specified, the behavior is determined by the system. If the IBM Cloud CLI is connected to private.cloud.ibm.com, the Code Engine project behaves as if --endpoint is private. If the IBM Cloud CLI is connected to cloud.ibm.com, the Code Engine project behaves as if --endpoint is public. This value is optional.

--no-select, --ns

Do not select the project as the current context after this project is created. If you do not select this option, the project is automatically selected. This value is optional. The default value is false.

--no-wait, --nw

Create the project and do not wait for the project to be created. If you specify the no-wait option, the project create begins and does not wait. Use the project get command to check the project status. This value is optional. The default value is false.

--output, -o

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--tag, -t

A label to assign to your project. The label must be 128 characters or fewer and can contain letters, numbers, spaces ( ), periods (.), colons (:), underscores (_), and hyphens (-). Specify one label per --tag option; for example, --tag tagA --tag tagB. This value is optional.

--wait, -w

Create the project and wait for the project to be created. If you specify the --wait option, the project create waits for a maximum time in seconds, as set by the --wait-timeout option, for the project to be created. If the project is not created within the specified --wait-timeout period, the project create fails. This value is optional. The default value is true.

--wait-timeout, --wto

The length of time in seconds to wait for the project to be created. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

ibmcloud ce project create --name myproject

Example output

Creating project 'myproject'...
OK

`ibmcloud ce project current`

Display the details of the project that is currently targeted.

ibmcloud ce project current [--output OUTPUT] [--quiet]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce project current

Example output

Getting the current project context...
OK

Name:       myproject
ID:         01234567-abcd-abcd-abcd-abcdabcd1111
Subdomain:  aabon2dfwa0
Domain:     us-south.codeengine.appdomain.cloud
Region:     us-south
Kubectl Context:  4svg40kna19

Kubernetes Config:
Context:             aabon2dfwa0
Environment Variable: export KUBECONFIG=/user/myusername/.bluemix/plugins/code-engine/myproject-01234567-abcd-abcd-abcd-abcdabcd1111.yaml

`ibmcloud ce project delete`

Delete a project.

ibmcloud ce project delete (--name PROJECT_NAME | --id PROJECT_ID) [--force] [--hard] [--no-wait] [--quiet] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--hard: Immediately delete the project. If you do not specify the --hard option, the project can be restored within 7 days by using either the project restore or the reclamation restore command. This value is optional. The default value is false.
--id, --guid: The ID of the project. This value is required if --name is not specified.
--name, -n: The name of the project. This value is required if --id is not specified.
--no-wait, --nw: Delete the project and do not wait for the project to be deleted. If you specify the no-wait option, the project delete begins and does not wait. Use the project get command to check the project status. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--wait, -w: Delete the project and wait for the project to be deleted. If you specify the --wait option, the project delete waits for a maximum time in seconds, as set by the --wait-timeout option, for the project to become deleted. If the project is not deleted within the specified --wait-timeout period, the project delete fails. This value is optional. The default value is true.
--wait-timeout, --wto: The length of time in seconds to wait for the project to be deleted. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

ibmcloud ce project delete --name myproject -f

Example output

Deleting project 'myproject'...
OK

`ibmcloud ce project get`

Display the details of a single project.

ibmcloud ce project get (--name PROJECT_NAME | --id PROJECT_ID) [--output OUTPUT] [--quiet]

Command Options

--id, --guid: The ID of the project. This value is required if --name is not specified.
--name, -n: The name of the project. This value is required if --id is not specified.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce project get --name myproject

Example output

Getting project 'myproject'...
OK

Name:                       myproject
ID:                         abcdabcd-abcd-abcd-abcd-f1de4aab5d5d
Status:                     active
Selected:                   true
Tags:                       tag1, tag2
Region:                     us-south
Resource Group:             default
Service Binding Service ID: ServiceId-1234abcd-abcd-abcd-1111-1a2b3c4d5e6f
Age:                        52d
Created:                    Fri, 15 Jan 2021 13:32:30 -0500
Updated:                    Fri, 15 Jan 2021 13:32:45 -0500

Quotas:
    Category                                  Used      Limit
    App revisions                             1         100
    Apps                                      1         100
    Build runs                                0         100
    Builds                                    0         100
    Configmaps                                2         100
    CPU                                       1.025     64
    Ephemeral storage                         902625Ki  256G
    Instances (active)                        1         250
    Instances (total)                         2         2500
    Job runs                                  1         100
    Jobs                                      1         100
    Memory                                    4400M     256G
    Secrets                                   5         100
    Subscriptions (cron)                      0         100
    Subscriptions (IBM Cloud Object Storage)  0         100

`ibmcloud ce project list`

List all projects.

ibmcloud ce project list [--all-resource-groups] [--output OUTPUT] [--quiet] [--regions REGIONS] [--sort-by SORT_BY]

Command Options

--all-resource-groups, --all: Display projects from all resource groups. By default, projects are only displayed from the current resource group. This value is optional. The default value is false.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--regions, -r: Limit the display of projects to specified regions. Provide the name of one or more regions; for example, us-south,eu-de. This value is optional.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce project list

Example output

Getting projects...
OK

Name             ID                                    Status  Selected  Tags  Region    Resource Group  Age
myproj-eude      09768af4-abcd-abcd-abcd-24674ba90db0  active  false           eu-de     default         27d
myproject        cd09cfe1-abcd-abcd-abcd-0f8a8a1d0ddf  active  true            us-south  default         52d

`ibmcloud ce project restore`

Restore a project.

ibmcloud ce project restore (--name PROJECT_NAME | --id PROJECT_ID) [--no-wait] [--quiet] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--id, --guid: The ID of the project. This value is required if --name is not specified.
--name, -n: The name of the project. This value is required if --id is not specified.
--no-wait, --nw: Restore the project and do not wait for the project to be restored. If you specify the no-wait option, the project restore begins and does not wait. Use the project get command to check the project status. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--wait, -w: Restore the project and wait for the project to be restored. If you specify the --wait option, the project restore waits for a maximum time in seconds, as set by the --wait-timeout option, for the project to be restored. If the project is not restored within the specified --wait-timeout period, the project restore fails. This value is optional. The default value is true.
--wait-timeout, --wto: The length of time in seconds to wait for the project to be restored. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

This example restores the myproject project that is in soft deleted status to an active state. Use the project list command to display a list of all projects with their status.

ibmcloud ce project restore --name myproject

Example output

Restoring project 'myproject'...
OK

`ibmcloud ce project select`

Select a project as the current context. The project must be in active status before it can be selected.

ibmcloud ce project select (--name PROJECT_NAME | --id PROJECT_ID) [--endpoint ENDPOINT] [--kubecfg] [--quiet]

Command Options

--endpoint, -e: The endpoint for the project. Valid values are public and private. If the --endpoint option is not explicitly specified, the behavior is determined by the system. If the IBM Cloud CLI is connected to private.cloud.ibm.com, the Code Engine project behaves as if --endpoint is private. If the IBM Cloud CLI is connected to cloud.ibm.com, the Code Engine project behaves as if --endpoint is public. This value is optional.
--id, --guid: The ID of the project. This value is required if --name is not specified.
--kubecfg, -k: Append the project to the Kubernetes configuration file. You can override the default Kubernetes configuration file by setting the KUBECONFIG environment variable. This value is optional. The default value is false.
--name, -n: The name of the project. This value is required if --id is not specified.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce project select --name myproject

Example output

Selecting project 'myproject'...
OK

`ibmcloud ce project tag`

Manages the tags of a single project.

ibmcloud ce project tag (--name PROJECT_NAME | --id PROJECT_ID) [--quiet] [--tag TAG] [--tag-rm TAG_RM]

Command Options

--id, --guid: The ID of the project. This value is required if --name is not specified.
--name, -n: The name of the project. This value is required if --id is not specified.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--tag, -t: A label to assign to your project. The label must be 128 characters or fewer and can contain letters, numbers, spaces ( ), periods (.), colons (:), underscores (_), and hyphens (-). Specify one label per --tag option; for example, --tag tagA --tag tagB. This value is optional.
--tag-rm, --trm: Remove a label assigned to your project. Specify one label per --tag-rm option; for example, --tag-rm tagA --tag-rm tagB. This value is optional.

Example

ibmcloud ce project tag --name myproject --tag tag1 --tag tag2

Example output

Getting project 'myproject'...
OK

`ibmcloud ce project update`

Update the selected project.

ibmcloud ce project update (--binding-service-id SERVICE_ID_ID | --binding-resource-group RESOURCE_GROUP_NAME | --binding-resource-group-id RESOURCE_GROUP_ID) [--quiet]

Command Options

--binding-resource-group, --brg: The name of a resource group to use for authentication for the service bindings of this project. A service ID is created with Operator and Manager roles for all services in this resource group. Use "*" to specify all resource groups in this account. This value is optional.
--binding-resource-group-id, --brgid: The ID of a resource group to use for authentication for the service bindings of this project. A service ID is created with Operator and Manager roles for all services in this resource group. This value is optional.
--binding-service-id, --bsid: The ID of a service ID to use for authentication for the service bindings of this project. This service ID must have the Operator role and an appropriate service role for one or more service instances, service types, or resource groups. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce project update --binding-service-id ServiceId-1234abcd-abcd-abcd-1111-1a2b3c4d5e6f

Example output

Configuring your project for service bindings...
Creating service binding API key 'my-project-api-key' for service ID 'my-custom-service-id'...
OK

Reclamation commands

Manage Code Engine project reclamations. Projects that are soft-deleted can be restored within 7 days by using the reclamation restore command.

`ibmcloud ce reclamation delete`

Delete a project reclamation.

ibmcloud ce reclamation delete (--name PROJECT_NAME | --id PROJECT_ID) [--force] [--no-wait] [--quiet] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--id, --guid: The ID of the project. This value is required if --name is not specified.
--name, -n: The name of the project. This value is required if --id is not specified.
--no-wait, --nw: Delete the project reclamation and do not wait for the project reclamation to be deleted. If you specify the no-wait option, the project reclamation delete begins and does not wait. Use the reclamation get command to check the project reclamation status. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--wait, -w: Delete the project reclamation and wait for the project reclamation to be deleted. If you specify the --wait option, the project reclamation delete waits for a maximum time in seconds, as set by the --wait-timeout option, for the project reclamation to be deleted. If the project reclamation is not deleted within the specified --wait-timeout period, the project reclamation delete fails. This value is optional. The default value is true.
--wait-timeout, --wto: The length of time in seconds to wait for the project reclamation to be deleted. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

This example permanently deletes the myproject project that is in soft deleted status. By using the --force option with this command, the delete is forced without confirmation. You can use the reclamation list command to display a list of all projects that are in soft deleted status.

ibmcloud ce reclamation delete --name myproject --f

Example output

Hard deleting project 'myproject'...
OK

`ibmcloud ce reclamation get`

Display the details of a single project reclamation.

ibmcloud ce reclamation get (--name PROJECT_NAME | --id PROJECT_ID) [--output OUTPUT] [--quiet]

Command Options

--id, --guid: The ID of the project. This value is required if --name is not specified.
--name, -n: The name of the project. This value is required if --id is not specified.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce reclamation get --name myproject

Example output

Getting project reclamation
OK

Name:                   myproject
Reclamation ID:         abcdabcd-abcd-abcd-abcd-f1de4aab5d5d
Status:                 soft deleted
Region:                 us-south
Resource Group:         default
Age:                    27m
Created:                Thu, 09 Sep 2021 13:24:15 -0400
Updated:                Thu, 09 Sep 2021 13:33:45 -0400
Time to Hard Deletion:  6d23h

`ibmcloud ce reclamation list`

List all project reclamations.

ibmcloud ce reclamation list [--all-resource-groups] [--output OUTPUT] [--quiet] [--regions REGIONS] [--sort-by SORT_BY]

Command Options

--all-resource-groups, --all: Display project reclamations from all resource groups. By default, project reclamations are only displayed from the current resource group. This value is optional. The default value is false.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--regions, -r: Limit the display of project reclamations to specified regions. Provide the name of one or more regions; for example, us-south,eu-de. This value is optional.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce reclamation list

Example output

Getting project reclamations...
OK
Name          ID                                    Reclamation ID                        Status        Region    Resource Group  Age   Time to Hard Deletion
myproject     def218c5-abcd-abcd-abcd-97854c288d76  48e3d7a2-abcd-abcd-abcd-99db7152b8fe  soft deleted  us-south  default         40h   6d23h
myproject2    01f0bc66-abcd-abcd-abcd-3ef7e99f6f69  af2cd017-abcd-abcd-abcd-d32e2bb79136  soft deleted  jp-osa    default         8m58s 2d11h

`ibmcloud ce reclamation restore`

Restore a project reclamation. Projects that are soft-deleted can be restored within 7 days by using the reclamation restore command.

ibmcloud ce reclamation restore (--name PROJECT_NAME | --id PROJECT_ID) [--no-wait] [--quiet] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--id, --guid: The ID of the project. This value is required if --name is not specified.
--name, -n: The name of the project. This value is required if --id is not specified.
--no-wait, --nw: Restore the project reclamation and do not wait for the project reclamation to be restored. If you specify the no-wait option, the project reclamation restore begins and does not wait. Use the reclamation get command to check the project reclamation status. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--wait, -w: Restore the project reclamation and wait for the project reclamation to be restored. If you specify the --wait option, the project reclamation restore waits for a maximum time in seconds, as set by the --wait-timeout option, for the project reclamation to be restored. If the project reclamation is not restored within the specified --wait-timeout period, the project reclamation restore fails. This value is optional. The default value is true.
--wait-timeout, --wto: The length of time in seconds to wait for the project reclamation to be restored. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 600.

Example

This example restores the myproject project that is in soft deleted status to an active state. Use the reclamation list command to display a list of all projects that are in soft deleted status.

ibmcloud ce reclamation restore --name myproject

Example output

Restoring project 'myproject'...
OK

Registry commands

A container registry, or registry, is a service that stores container images. For example, IBM Cloud Container Registry and Docker Hub are container registries. A container registry can be public or private. A container registry that is public does not require credentials to access. In contrast, accessing a private registry does require credentials.

You must be within the context of a project before you use registry commands.

For more information about accessing registries, see Adding access to a private container registry.

To see CLI help for the registry commands, run ibmcloud ce registry -h.

Beginning with CLI version 1.42.0, defining and working with secrets in the CLI is unified under the secret command group. See ibmcloud ce secret commands. Use the --format option to specify the category of secret, such as basic_auth, generic, ssh, tls, or registry. While you can continue to use the registry command group, take advantage of the unified secret command group. To create a secret to access a container registry, use the ibmcloud ce secret create --format registry command. To learn more about working with secrets in Code Engine, see Working with secrets.

`ibmcloud ce registry create`

Create an image registry access secret.

ibmcloud ce registry create --name NAME (--password PASSWORD | --password-from-file PASSWORD_FILE | --password-from-json-file) [--email EMAIL] [--output OUTPUT] [--quiet] [--server SERVER] [--username USERNAME]

Command Options

-n, --name

The name of the image registry access secret. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 253 characters or fewer and can contain lowercase letters, numbers, periods (.), and hyphens (-).

This value is required.

--email, -e

The email address to access the registry server. This value is optional.

--output, -o

--password, -p

The password to access the registry server. If neither --password, nor --password-from-file, nor --password-from-json-file option is specified, then you are prompted for the password. This value is optional.

--password-from-file, --pf

The path to a file containing the password to access the registry server. The first line of the file is used for the password. If neither --password, nor --password-from-file, nor --password-from-json-file option is specified, then you are prompted for the password. This value is optional.

--password-from-json-file, --pfj

The path to a JSON file containing the password to access the registry server. The apikey field is used for the password. If neither --password, nor --password-from-file, nor --password-from-json-file option is specified, then you are prompted for the password. This value is optional.

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--server, -s

The URL of the registry server. This value is optional. The default value is us.icr.io.

--username, -u

The username to access the registry server. This value is optional. The default value is iamapikey.

Example

The following example creates image registry access that is called myregistry to a Container Registry instance that is located at us.icr.io and uses a username of iamapikey and the IAM API key as a password.

ibmcloud ce registry create --name myregistry --server us.icr.io --username iamapikey --password API_KEY

Example output

Creating image registry access secret myregistry...

OK

`ibmcloud ce registry delete`

Delete an image registry access secret.

ibmcloud ce registry delete --name NAME [--force] [--ignore-not-found] [--quiet]

Command Options

--name, -n: The name of the image registry access secret. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce registry delete --name myregistry -f

Example output

Deleting image registry access secret myregistry...

OK

`ibmcloud ce registry get`

Display the details of an image registry access secret.

ibmcloud ce registry get --name NAME [--decode] [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the image registry access secret. This value is required.
--decode, -d: Show the Data output as decoded in the details. If this option is not specified, the Data details are base64-encoded. This value is optional. The default value is false.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce registry get --name myregistry

Example output

Getting image registry access secret myregistry...
OK

Name:        myregistry
Project:     myproject
Project ID:  01234567-abcd-abcd-abcd-abcdabcd1111
Created:     2021-02-23T09:10:01-05:00
Data:
---
.dockerconfigjson: abcdabcdabcdabcdabcdnVzZXJuYW1lIjoiaWFtYXBpa2V5IiwicGFzc3dvcmQiOiJoQllTSTc5Uk8yQUIxSDV3RUs2UzhScV9uNzE4NkQ1eWt1M1FOUk85aFpfaCIsImVtYWlsIjoiYUBiLmMiLCabcdabcdabcdabcdabcdT21oQ1dWTkpOemxTVHpKQlFqRklOWGRGU3paVE9GSnhYMjQzTVRnMlJEVjabcdabcdabcdabcdabcdbG9XbDlvIn19fQ==

`ibmcloud ce registry list`

List all image registry access secrets in a project.

ibmcloud ce registry list [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce registry list

Example output

Listing image registry access secrets...

OK

Name        Age
myregistry  19m22s

`ibmcloud ce registry update`

Update an image registry access secret.

ibmcloud ce registry update --name NAME [--email EMAIL] [--output OUTPUT] [--password PASSWORD] [--password-from-file PASSWORD_FROM_FILE] [--password-from-json-file PASSWORD_FROM_JSON_FILE] [--quiet] [--server SERVER] [--username USERNAME]

Command Options

--name, -n: The name of the image registry access secret. This value is required.
--email, -e: The email address to access the registry server. This value is optional.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--password, -p: The password to access the registry server. This value is optional.
--password-from-file, --pf: The path to a file containing the password to access the registry server. The first line of the file is used for the password. This value is optional.
--password-from-json-file, --pfj: The path to a JSON file containing the password to access the registry server. The apikey field is used for the password. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--server, -s: The URL of the registry server. This value is optional.
--username, -u: The username to access the registry server. This value is optional.

Example

The following example updates a password for the image registry access that is called myregistry.

ibmcloud ce registry update --name myregistry --password NEW_API_KEY

Example output

Getting image registry access secret 'myregistry'...
Updating image registry access secret 'myregistry'...

OK

Repo commands

A code repository, such as GitHub or GitLab, stores source code. With Code Engine, you can add access to a private code repository and then reference that repository from your build.

You must be within the context of a project before you use repo commands.

For more information about accessing repositories, see Accessing private code repositories.

To see CLI help for the repo commands, run ibmcloud ce repo -h.

Beginning with CLI version 1.42.0, defining and working with secrets in the CLI is unified under the secret command group. See ibmcloud ce secret commands. Use the --format option to specify the category of secret, such as basic_auth, generic, ssh, tls, or registry. While you can continue to use the repo command group, take advantage of the unified secret command group. To create a secret to access a service with an SSH key, such as to authenticate to a Git repository like GitHub or GitLab, use the ibmcloud ce secret create --format ssh command. An SSH secret is also used as a Git repository access secret. To learn more about working with secrets in Code Engine, see Working with secrets.

`ibmcloud ce repo create`

Create a Git repository access secret.

ibmcloud ce repo create --name SECRET_NAME --key-path SSH_KEY_PATH --host HOST_ADDRESS [--known-hosts-path KNOWN_HOSTS_PATH] [--output OUTPUT] [--quiet]

Command Options

--host, --ho

The address of the host; for example github.com. This value is required.

--key-path, --kp

The path to your unencrypted SSH private key file. If you use your personal private SSH key, then this file is usually located at $HOME/.ssh/id_rsa (Mac OS or Linux) or at %HOMEPATH%\.ssh\id_rsa (Windows). This value is required.

-n, --name

The name of the Git repository access secret. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 253 characters or fewer and can contain lowercase letters, numbers, periods (.), and hyphens (-).

This value is required.

--known-hosts-path, --khp

The path to your known hosts file. This value is a security feature to ensure that the private key is only used to authenticate at hosts that you previously accessed, specifically, the GitHub or GitLab hosts. This file is usually located at $HOME/.ssh/known_hosts (Mac OS or Linux) or at %HOMEPATH%\.ssh\known_hosts (Windows). This value is optional.

--output, -o

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

The following command creates a Git access secret called github for host github.com and authenticates with an SSH key located at /<filepath>/.ssh/id_rsa, where <filepath> is the path on your system.

ibmcloud ce repo create -n github --key-path /<filepath>/.ssh/id_rsa --host github.com

Example output

Creating Git access secret github...
OK

`ibmcloud ce repo delete`

Delete a Git repository access secret.

ibmcloud ce repo delete --name NAME [--force] [--ignore-not-found] [--quiet]

Command Options

--name, -n: The name of the Git repository access secret. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce repo delete --name github

Example output

Are you sure you want to delete the Git access secret github? [y/N]> y
Deleting Git access secret github...
OK

`ibmcloud ce repo get`

Display the details of a Git repository access secret.

ibmcloud ce repo get --name NAME [--decode] [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the Git repository access secret. This value is required.
--decode, -d: Show the Data output as decoded in the details. If this option is not specified, the Data details are base64-encoded. This value is optional. The default value is false.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce repo get -n github

Example output

Getting Git access secret github...
OK

Name:        github  
Project:     myproject  
Project ID:  01234567-abcd-abcd-abcd-abcdabcd1111 
Age:         30s  
Created:     2021-03-14T14:05:56-05:00  
Host:        github.com

Data:          
---
ssh-privatekey: 
ABCDABCDABCDABCDABCDU1NIIFBSSVZBVEUgS0VZLS0tLS0KYjABCDABCDABCDABCDhrdGRqRUFBQUFBQ21GbGN6STFOaABCDABCDABCDABCDABCDABCDE
...

`ibmcloud ce repo list`

List all Git repository access secrets in a project.

ibmcloud ce repo list [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce repo list

Example output

Listing Git access secrets...
OK

Name    Age  
github  13m0s

`ibmcloud ce repo update`

Update a Git repository access secret.

ibmcloud ce repo update --name SECRET_NAME [--host HOST] [--key-path KEY_PATH] [--known-hosts-path KNOWN_HOSTS_PATH] [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the Git repository access secret. This value is required.
--host, --ho: The address of the host; for example github.com. This value is optional.
--key-path, --kp: The path to your unencrypted SSH private key file. If you use your personal private SSH key, then this file is usually located at $HOME/.ssh/id_rsa (Mac OS or Linux) or at %HOMEPATH%\.ssh\id_rsa (Windows). This value is optional.
--known-hosts-path, --khp: The path to your known hosts file. This value is a security feature to ensure that the private key is only used to authenticate at hosts that you previously accessed, specifically, the GitHub or GitLab hosts. This file is usually located at $HOME/.ssh/known_hosts (Mac OS or Linux) or at %HOMEPATH%\.ssh\known_hosts (Windows). This value is optional.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

The following command updates a Git access secret that is called github to use a new host.

ibmcloud ce repo update  -n github --host NEW_HOST

Example output

Getting Git access secret 'github'...
Updating Git access secret 'github'...
OK

Revision commands

An application, or app, runs your code to serve HTTP requests. In addition to traditional HTTP requests, IBM Cloud® Code Engine also supports applications that use WebSockets as their communications protocol. An app contains one or more revisions. A revision represents an immutable version of the configuration properties of the app. Each update of an app configuration property creates a new revision of the app.

Use revision commands to manage application revisions.

You must be within the context of a project before you use revision commands.

For more information about working with revisions for apps, see Deploying applications.

You can use either revision or rev in your revision commands. To see CLI help for the revision commands, run ibmcloud ce revision -h.

`ibmcloud ce revision delete`

Delete an application revision.

ibmcloud ce revision delete --name REVISION_NAME [--force] [--ignore-not-found] [--quiet]

Command Options

--name, -n: The name of the application revision. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce revision delete -n newapp-mytest-00004 -f

Example output

Deleting application revision 'newapp-mytest-00004'...
OK

`ibmcloud ce revision events`

Display the system events of application revision instances. System events are retained up to 60 minutes.

ibmcloud ce revision events (--instance REVISION_INSTANCE | --revision REVISION_NAME) [--output OUTPUT] [--quiet]

Command Options

--instance, -i: The name of a specific application instance. Use the rev get command to find the instance name. This value is required if --revision is not specified.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--revision, --rev, -r, --name, -n: Display the events of all the instances of the specified application revision. This value is required if --instance is not specified.

Example

ibmcloud ce revision events -n myapp-00001

Example output

Code Engine retains only the latest inactive revision of your application in addition to your active app revision. Older revisions are not retained.

Getting application revision 'newapp-mytest-00002'...
Getting events for all instances of application revision 'newapp-mytest-00002'...
OK

newapp-mytest-00002-deployment-7c87cfbf66-xnwkp:
Type     Reason     Age                Source                Messages
Normal   Scheduled  65s                default-scheduler     Successfully assigned bz8i2yh012p/newapp-mytest-00002-deployment-7c87cfbf66-xnwkp to 10.243.0.60
Normal   Pulling    63s                kubelet, 10.243.0.60  Pulling image "icr.io/codeengine/codeengine@sha256:b3150372958ab68eea5356a8cab31069ca5293c45959d64f6aaabbccddeeff123"
Normal   Created    60s                kubelet, 10.243.0.60  Created container queue-proxy
Normal   Created    60s                kubelet, 10.243.0.60  Created container user-container
Normal   Started    60s                kubelet, 10.243.0.60  Started container user-container
Normal   Pulled     60s                kubelet, 10.243.0.60  Container image "icr.io/obs/codeengine/knative-serving/knative.dev/serving/cmd/queue:v0.20.0-rc11@sha256:3fedfa9d9cdd74e85d11d4167043f13902074946caf415d16ff537620f04931a" already present on machine
Normal   Pulled     60s                kubelet, 10.243.0.60  Successfully pulled image "icr.io/codeengine/codeengine@sha256:b3150372958ab68eea5356a8cab31069ca5293c45959d64f6aaabbccddeeff123" in 2.67237432s
Normal   Started    60s                kubelet, 10.243.0.60  Started container queue-proxy
Normal   Pulling    60s                kubelet, 10.243.0.60  Pulling image "icr.io/obs/codeengine/istio/proxyv2:1.9.1-rc7"
Normal   Pulled     59s                kubelet, 10.243.0.60  Successfully pulled image "icr.io/obs/codeengine/istio/proxyv2:1.9.1-rc7" in 666.211288ms
Normal   Created    59s                kubelet, 10.243.0.60  Created container istio-proxy
Normal   Started    59s                kubelet, 10.243.0.60  Started container istio-proxy

`ibmcloud ce revision get`

Display the details of an application revision.

ibmcloud ce revision get --name REVISION_NAME [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the application revision. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce revision get --name newapp-mytest-00002

Example output

Getting application revision 'newapp-mytest-00002'...
Getting application 'newapp-mytest'...
OK

Name:            newapp-mytest-00002
ID:              abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:    myproject
Project ID:      01234567-abcd-abcd-abcd-abcdabcd1111
Age:             27d
Created:         2021-05-05T11:50:00-04:00
Status Summary:  Revision is ready

Environment Variables:
    Type                      Name               Value
    ConfigMap full reference  mycolorconfigmap 
    Literal                   TARGET             Sunshine
Image:                  icr.io/codeengine/codeengine
Resource Allocation:
    CPU:                1
    Ephemeral Storage:  400M
    Memory:             4G
Port:                   8080

Runtime:
    Concurrency:    100
    Maximum Scale:  10
    Minimum Scale:  0
    Timeout:        300

Conditions:
    Type                OK     Age    Reason
    Active              false  5d22h  NoTraffic : The target is not receiving traffic.
    ContainerHealthy    true   5d22h
    Ready               true   5d22h
    ResourcesAvailable  true   5d22h

`ibmcloud ce revision list`

List all application revisions in a project.

ibmcloud ce revision list [--application APPLICATION] [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--application, --app, -a: Use this option to only display revisions from the specified application. This value is optional.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce revision list

Example output

Code Engine retains only the latest inactive revision of your application in addition to your active app revision. Older revisions are not retained.

Listing all application revisions...
OK

Name                   Application      Status  URL  Latest  Tag  Traffic  Age    Conditions  Reason
myapp-hc3u8-2           myapp            Ready                              16d    3 OK / 4
myapp-hc3u8-3           myapp            Ready        true         100%    2d8h    3 OK / 4  
newapp-mytest-00004     newapp-mytest    Ready                              4d20h  3 OK / 4
newapp-mytest-00005     newapp-mytest    Ready        true         100%     2d20h  3 OK / 4

`ibmcloud ce revision logs`

Display the logs of application revision instances.

ibmcloud ce revision logs (--instance REVISION_INSTANCE | --revision REVISION_NAME) [--all-containers] [--follow] [--output OUTPUT] [--quiet] [--tail TAIL] [--timestamps]

Command Options

--all-containers, --all: Display the logs of all containers of the specified application revision instances. This value is optional. The default value is false.
--follow, -f: Follow the logs of application revision instances. Use this option to stream logs of application revision instances. If you specify the --follow option, you must enter Ctrl+C to terminate this log command. This value is optional. The default value is false.
--instance, -i: The name of a specific application revision instance. Use the revision get command to find the instance name. This value is required if --revision is not specified.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--revision, --rev, -r, --name, -n: Display the logs of all the instances of the specified application revision. This value is required if --instance is not specified.
--tail, -t: Limit the display of logs of containers of the specified application revision instances to a maximum number of recent lines per container. For example, to display the last 3 lines of the logs of the containers of the specified application revision instances, specify --tail 3. If this option is not specified, all lines of the logs of the containers of the specified application revision instances are displayed. This value is optional. The default value is -1.
--timestamps, --ts: Include timestamps on each line in the log output. This value is optional. The default value is false.

Example

ibmcloud ce revision logs -n myapp-00001

Example output

Code Engine retains only the latest inactive revision of your application in addition to your active app revision. Older revisions are not retained.

Getting logs for all instances of application revision 'newapp-mytest-00002'...
Getting application revision 'newapp-mytest-00002'...
OK

newapp-mytest-00002-deployment-7c87cfbf66-xnwkp/user-container:
2021-07-15 20:40:56 Listening on port 8080

Secret commands

A secret provides a method to include sensitive configuration information, such as passwords or SSH keys, to your deployment. By referencing values from your secret, you can decouple sensitive information from your deployment to keep your app, function, or job portable. Anyone who is authorized to your project can also view your secrets; be sure that you know that the secret information can be shared with those users. Secrets contain information in key-value pairs.

You must be within the context of a project before you use secret commands.

For more information about working with secrets, see Working with secrets.

To see CLI help for the secret commands, run ibmcloud ce secret -h.

Beginning with CLI version 1.42.0, defining and working with secrets in the CLI is unified under the secret command group. Use the --format option to specify the category of secret, such as basic_auth, generic, ssh, tls, or registry. The default value for the --format option is generic.

`ibmcloud ce secret create`

Create a secret.

ibmcloud ce secret create --name SECRET_NAME (--from-env-file FILE | --from-file FILE | --from-file KEY=FILE | --from-literal KEY=VALUE) [--cert-chain-file CERT_CHAIN_FILE] [--email EMAIL] [--format FORMAT] [--key-path KEY_PATH] [--known-hosts-path KNOWN_HOSTS_PATH] [--output OUTPUT] [--password PASSWORD] [--password-from-file PASSWORD_FROM_FILE] [--password-from-json-file PASSWORD_FROM_JSON_FILE] [--private-key-file PRIVATE_KEY_FILE] [--quiet] [--server SERVER] [--username USERNAME]

Command Options

--cert-chain-file, --ccf

Specify a file containing the certificate chain provided by your certificate authority for a TLS secret. You must provide the path to the file as a value. This value is required for tls secrets. This value is optional.

--email, --em

The email address to access the registry server for a registry secret. This value applies only for registry secrets. This value is optional.

--format, --fo

The format of the secret. Valid values are basic_auth, generic, registry, ssh, or tls. This value is optional. The default value is generic.

--from-env-file, -e

Create a generic secret from a file which contains one or more lines that match the format KEY=VALUE. You must provide the path to the file as a value. Each line from the specified file is added as a key-value pair. Any lines in the specified file that are empty or begin with # are ignored. This value is required if --from-literal or --from-file is not specified. This option can be specified multiple times. This value applies only for generic secrets.

--from-file, -f

Create a generic secret from a file. You must provide the path to the file as a value. This value is required if --from-literal or --from-env-file is not specified. This option can be specified multiple times. This value applies only for generic secrets.

--from-literal, -l

Create a generic secret from a key-value pair. Must be in KEY=VALUE format. This value is required if --from-file or --from-env-file is not specified. This option can be specified multiple times. This value applies only for generic secrets.

--key-path, --kp

The path to your unencrypted SSH private key file for an SSH secret. If you use your personal private SSH key, then this file is usually located at $HOME/.ssh/id_rsa (Mac OS or Linux) or at %HOMEPATH%\.ssh\id_rsa (Windows). This value is required for ssh secrets. This value is optional.

--known-hosts-path, --khp

The path to your known hosts file for an SSH secret. This value is a security feature to ensure that the private key is only used to authenticate at hosts that you previously accessed, specifically, the GitHub or GitLab hosts. This file is usually located at $HOME/.ssh/known_hosts (Mac OS or Linux) or at %HOMEPATH%\.ssh\known_hosts (Windows). This value applies only for ssh secrets. This value is optional.

-n, --name

The name of the secret. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 253 characters or fewer and can contain lowercase letters, numbers, periods (.), and hyphens (-).

This value is optional.

--output, -o

--password, --pw

The password for a basic auth or registry secret. If neither --password, nor --password-from-file, nor --password-from-json-file option is specified, then you are prompted for the password. This value is required for basic_auth and registry secrets. This value is optional.

--password-from-file, --spf

The path to a file containing the password for a basic auth or registry secret. The first line of the file is used for the password. If neither --password, nor --password-from-file, nor --password-from-json-file option is specified, then you are prompted for the password. You must provide the path to the file as a value. This value is required for basic_auth and registry secrets. This value is optional.

--password-from-json-file, --spfj

The path to a JSON file containing the password for a basic auth or registry secret. The apikey field is used for the password. If neither --password, nor --password-from-file, nor --password-from-json-file option is specified, then you are prompted for the password. You must provide the path to the file as a value. This value is required for basic_auth and registry secrets. This value is optional.

--private-key-file, --pkf

Specify a file containing the private key for a TLS secret that matches the specified certificate chain with the cert-chain-file option. You must provide the path to the file as a value. This value is required for tls secrets. This value is optional.

--quiet, -q

Specify this option to reduce the output of the command. This option applies for basic_auth, generic, registry, ssh, and tls secrets. This value is optional. The default value is false.

--server, -s

The URL of the registry server for a registry secret. This option is required for registry secrets. This value is optional. The default value is us.icr.io.

--username, -u

The username for your basic auth or registry secret. This option is required for basic_auth and registry secrets. This value is optional.

Example of a basic auth secret

A basic auth secret contains a username and password key and is used when you access a service that requires basic HTTP authentication.

To see CLI help for creating a basic auth secret, run ibmcloud ce secret create --format basic_auth.

The following example creates a basic auth secret that is named mysecret-basicauth. This secret contains the username myusername, and the password value is obtained from a file on the local machine. If the password is not provided from a file or a JSON file, then you are prompted to enter the password value.

ibmcloud ce secret create --name mysecret-basicauth --format basic_auth --username myusername --password-from-file ./password.txt

Example output for a basic auth secret

Creating basic_auth secret 'mysecret-basicauth'...
OK

Example of a generic secret

A generic secret stores simple key-value pairs and Code Engine makes no assumptions about the defined key-value pairs nor about the intended use of the secret.

To see CLI help for creating a generic secret, run ibmcloud ce secret create or ibmcloud ce secret create --format generic.

Note that --format generic is the default when you create a secret with the secret create command in the CLI.

The following example creates a generic secret that is named mysecret-generic and the value of this secret is specified for a key-value pair with the --from-literal option.

ibmcloud ce secret create --name mysecret-generic --format generic --from-literal "TARGET=My literal secret"

Example output for a generic secret

Creating generic secret 'mysecret-generic'...
OK

Example of a generic secret with values from a file

The following example creates a secret that is named mysecret-fromfile with values from a file. By using the --from-file option to point to a file, all the contents of the file become the value for the key-value pair.

ibmcloud ce secret create --name mysecret-genericfromfile  --from-file ./value1.txt --from-file ./value2.txt

Example output of a generic secret with values from a file

Creating secret mysecret-genericfromfile...
OK

Example of a registry secret

A registry secret stores credentials to access a container registry.

To see CLI help for creating a registry secret, run ibmcloud ce secret create --format registry.

The following example creates a registry secret that is named mysecret-registry to an IBM Cloud Container Registry instance that is on the us.icr.io registry server and specifies credentials for username and password.

ibmcloud ce secret create --name mysecret-registry --format registry --server us.icr.io --username iamapikey --password API_KEY

Example output for a registry secret

Creating registry secret `mysecret-registry`...
OK

Example of an SSH secret

An SSH secret stores credentials to authenticate to a service with an SSH key; for example, authenticating to a Git repository, such as GitHub or GitLab.

To see CLI help for creating an SSH secret, run ibmcloud ce secret create --format ssh.

The following example creates an SSH secret that is named mysecret-ssh for a host that is included in the known_hosts file, and authenticates with an unencrypted SSH private key file located at /<filepath>/.ssh/<key_name>, where <filepath> is the path on your system. This command requires a name and a key path, and also allows other optional arguments such as the path to the known hosts file.

ibmcloud ce secret create --name mysecret-ssh --format ssh --key-path ~/.ssh/<key_name> --known-hosts-path  ~/.ssh/known_hosts

Example output for an SSH secret

Creating SSH secret `mysecret-ssh`...
OK

Example of a TLS secret

A Transport Layer Security (TLS) secret contains a signed TLS certificate, including all its intermediate certificates, and its corresponding private key from a certificate authority (CA). Use TLS secrets when you work with custom domain mappings.

To see CLI help for creating a TLS secret, run ibmcloud ce secret create --format tls.

The following example creates an TLS secret that is named mysecret-tls. The certificate chain that corresponds to the custom domain is contained in the file certificate.txt and the matching private key file is contained in the file privatekey.txt. Both of these files are located in the root directory of the local workstation.

ibmcloud ce secret create --name mysecret-tls  --format tls  --cert-chain-file certificate.txt --private-key-file privatekey.txt

Example output for a TLS secret

Creating TLS secret `mysecret-tls`...
OK

`ibmcloud ce secret delete`

Delete a secret.

ibmcloud ce secret delete --name SECRET_NAME [--force] [--ignore-not-found] [--quiet]

Command Options

--name, -n: The name of the secret. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce secret delete --name mysecret-genericfromfile -f

Example output

Deleting secret mysecret-genericfromfile...
OK

`ibmcloud ce secret get`

Display the details of a secret.

ibmcloud ce secret get --name SECRET_NAME [--decode] [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the secret. This value is required.
--decode, -d: Show the Data output as decoded in the details. If this option is not specified, the Data details are base64-encoded. This value is optional. The default value is false.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce secret get --name mysecret-basicauth

Example output

Getting secret 'mysecret-basicauth'...
OK

Name:          mysecret-basicauth
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Format:        basic_auth 
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           66s
Created:       2021-03-10T18:44:18-05:00

Data:    
---
password: REDACTED
username: bXl1c2VybmFtZQ==

`ibmcloud ce secret list`

List all secrets in a project.

ibmcloud ce secret list [--all] [--format FORMAT] [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--all, -a: Display all secrets of all formats, including basic_auth, generic, registry, ssh, tls, and other secrets that are not managed by Code Engine. This value is optional. The default value is false.
--format, --fo: Specify this option to filter the display of secrets. Valid values are basic_auth, generic, registry, ssh, and tls. This value is optional.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

This command lists all secrets in a project.

ibmcloud ce secret list

Example output

Listing secrets...
OK

Name                          Format          Data  Age  
ce-auto-icr-private-us-south  registry        4     333d  
ce-auto-private-icr-us-south  registry        4     335d  
myregistry-seccmd             registry        4     3h31m  
mysecret-basicauth            basic_auth      2     7m37s  
mysecret-generic              generic         1     7m7s  
mysecret-genericfromfile      generic         2     2m29s  
mysecret-registry             registry        4     111s  
mysecret-ssh                  ssh_auth        2     42m  
mysecret-tls                  tls             2     3h47m

`ibmcloud ce secret update`

Update a secret.

ibmcloud ce secret update --name SECRET_NAME (--from-env-file FILE | --from-file FILE | --from-file KEY=FILE | --from-literal KEY=VALUE | --rm KEY) [--cert-chain-file CERT_CHAIN_FILE] [--email EMAIL] [--key-path KEY_PATH] [--known-hosts-path KNOWN_HOSTS_PATH] [--output OUTPUT] [--password PASSWORD] [--password-from-file PASSWORD_FROM_FILE] [--password-from-json-file PASSWORD_FROM_JSON_FILE] [--private-key-file PRIVATE_KEY_FILE] [--quiet] [--server SERVER] [--username USERNAME]

Command Options

--name, -n: The name of the secret. This value is required.
--cert-chain-file, --ccf: Specify a file containing the certificate chain provided by your certificate authority for a TLS secret. You must provide the path to the file as a value. This value is optional.
--email, --em: The email address to access the registry server for a registry secret. This value is optional.
--from-env-file, -e: Update a generic secret from a file which contains one or more lines that match the format KEY=VALUE. You must provide the path to the file as a value. Each line from the specified file is added as a key-value pair. Any lines in the specified file that are empty or begin with # are ignored. This value is required if --from-literal or --from-file is not specified.
--from-file, -f: Update a generic secret from a file. You must provide the path to the file as a value. This value is required if --from-literal or --from-env-file is not specified.
--from-literal, -l: Update a generic secret from a key-value pair. Must be in KEY=VALUE format. This value is required if --from-file or --from-env-file is not specified. This option can be specified multiple times.
--key-path, --kp: The path to your unencrypted SSH private key file for an SSH secret. If you use your personal private SSH key, then this file is usually located at $HOME/.ssh/id_rsa (Mac OS or Linux) or at %HOMEPATH%\.ssh\id_rsa (Windows). This value is optional.
--known-hosts-path, --khp: The path to your known hosts file for an SSH secret. This value is a security feature to ensure that the private key is only used to authenticate at hosts that you previously accessed, specifically, the GitHub or GitLab hosts. This file is usually located at $HOME/.ssh/known_hosts (Mac OS or Linux) or at %HOMEPATH%\.ssh\known_hosts (Windows). This value is optional.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--password, --pw: The password for a basic auth or registry secret. If neither --password, nor --password-from-file, nor --password-from-json-file option is specified, then you are prompted for the password. This value is optional.
--password-from-file, --spf: The path to a file containing the password for a basic auth or registry secret. The first line of the file is used for the password. If neither --password, nor --password-from-file, nor --password-from-json-file option is specified, then you are prompted for the password. You must provide the path to the file as a value. This value is optional.
--password-from-json-file, --spfj: The path to a JSON file containing the password for a basic auth or registry secret. The apikey field is used for the password. If neither --password, nor --password-from-file, nor --password-from-json-file option is specified, then you are prompted for the password. You must provide the path to the file as a value. This value is optional.
--private-key-file, --pkf: Specify a file containing the private key for a TLS secret that matches the specified certificate chain with the cert-chain-file option. You must provide the path to the file as a value. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--rm: Remove an individual key-value pair in a generic secret by specifying the name of the key. This option can be specified multiple times. This value is optional.
--server, -s: The URL of the registry server for a registry secret. This value is optional. The default value is us.icr.io.
--username, -u: The username for your basic auth or registry secret. This value is optional.

Example

This example updates a TLS secret with an updated certificate and private key.

ibmcloud ce secret update --name mysecret-tls --cert-chain-file certificate2.txt --private-key-file privatekey2.txt

Example output

Updating secret mysecret-tls..
OK

Subscription cos commands

Oftentimes in distributed environments you want your applications or jobs to react to messages (events) that are generated from other components, which are usually called event producers. With Code Engine, your applications or jobs can receive events of interest by subscribing to event producers. Event information is received as POST HTTP requests for applications and as environment variables for jobs.

The Object Storage event producer generates events as changes are made to the objects in your object storage buckets. For example, as objects are added to a bucket, an application can receive an event and then perform an action based on that change, perhaps consuming that new object.

You must be within the context of a project before you use subscription cos commands.

For more information about working with the IBM Cloud Object Storage subscriptions, see Working with the IBM Cloud Object Storage event producer. See Getting started with subscriptions for more information about working with subscriptions in Code Engine.

You can use either subscription or sub in your subscription cos commands. To see CLI help for the subscription cos command, run ibmcloud ce sub cos -h.

`ibmcloud ce subscription cos create`

Create an IBM Cloud Object Storage event subscription.

ibmcloud ce subscription cos create --name COS_SOURCE_NAME --destination DESTINATION_REF --bucket BUCKET_NAME [--destination-type DESTINATION_TYPE] [--event-type EVENT_TYPE] [--extension EXTENSION] [--force] [--no-wait] [--output OUTPUT] [--path PATH] [--prefix PREFIX] [--quiet] [--suffix SUFFIX] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--bucket, -b

The bucket for events. The destination and the bucket must be in the same region of the project. This value is required.

--destination, -d

The name of the application or job resource that you want to receive events; for example, myapp. If needed, use the --path option to further qualify an app destination. This value is required.

-n, --name

The name of the IBM Cloud Object Storage event subscription. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 253 characters or fewer and can contain lowercase letters, numbers, periods (.), and hyphens (-).

This value is required.

--destination-type, --dt

The type of the destination. Valid values are app and job. This value is optional. The default value is app.

--event-type, -e

The event types to watch. Valid values are delete, write, and all. This value is optional. The default value is all.

--extension, --ext

Set CloudEvents extensions to send to the destination. Must be in NAME=VALUE format. This action adds a new CloudEvents extension or overrides an existing CloudEvent attribute. Specify one extension per --extension option; for example, --ext extA=A --ext extB=B. This value is optional.

--force, -f

Force to create an IBM Cloud Object Storage event subscription. This option skips the validation of the specified destination. This value is optional. The default value is false.

--no-wait, --nw

Create the IBM Cloud Object Storage event subscription and do not wait for the subscription to be ready. If you specify the --no-wait option, the subscription create begins and does not wait. Use the subscription cos get command to check the subscription status. This value is optional. The default value is false.

--output, -o

--path

The path within the destination application where events are forwarded; for example, /events. The default path is the root URL of the destination application. This option can only be specified if destination-type is app. This value is optional.

--prefix, -p

Prefix of the IBM Cloud Object Storage object. This value is optional.

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--suffix, -s

Suffix of the IBM Cloud Object Storage object. Consider the file type of your file when specifying the suffix. This value is optional.

--wait, -w

Create the IBM Cloud Object Storage event subscription and wait for the subscription to be ready. If you specify the --wait option, the subscription create waits for a maximum time in seconds, as set by the --wait-timeout option, for the subscription to become ready. If the subscription is not ready within the specified --wait-timeout period, the IBM Cloud Object Storage event subscription create fails. This value is optional. The default value is true.

--wait-timeout, --wto

The length of time in seconds to wait for the IBM Cloud Object Storage event subscription to be ready. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 15.

Example

The IBM Cloud Object Storage subscription listens for changes to an Object Storage bucket. The following example creates a COS subscription called mycosevent for a bucket called mybucket that is attached to an app called myapp. The --destination-type option specifies the type of the destination which is app or job. For this example, the --destination-type is app, which is the default for this option. The event is sent to the /events path by using the --path option so that the event is sent to https://<base application URL>/events.

ibmcloud ce subscription cos create --name mycosevent --destination myapp --bucket mybucket --destination-type app --path /events

Example output

Creating COS source 'mycosevent'...
Run 'ibmcloud ce subscription cos get -n mycosevent' to check the COS source status.
OK

`ibmcloud ce subscription cos delete`

Delete an IBM Cloud Object Storage event subscription.

ibmcloud ce subscription cos delete --name COS_SOURCE_NAME [--force] [--ignore-not-found] [--no-wait] [--quiet] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--name, -n: The name of the IBM Cloud Object Storage event subscription. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--no-wait, --nw: Delete the IBM Cloud Object Storage event subscription and do not wait for the subscription to be deleted. If you specify the --no-wait option, the subscription delete begins and does not wait. Use the subscription cos get command to check the subscription status. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--wait, -w: Delete the IBM Cloud Object Storage event subscription and wait for the subscription to be deleted. If you specify the --wait option, the subscription delete waits for a maximum time in seconds, as set by the --wait-timeout option, for the subscription to be deleted. This command exits when the subscription is deleted or whenever --wait-timeout is reached, whichever comes first. This value is optional. The default value is true.
--wait-timeout, --wto: The length of time in seconds to wait for the IBM Cloud Object Storage event subscription to be deleted. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 15.

Example

ibmcloud ce subscription cos delete --name mycosevent -f

Example output

Deleting COS source 'mycosevent'...
OK

`ibmcloud ce subscription cos get`

Display the details of an IBM Cloud Object Storage event subscription. Displayed attributes include Name, Destination, Bucket, Event Type, Prefix, Suffix, Ready, and Age. To see specific details, attach | grep <attribute>.

ibmcloud ce subscription cos get --name COS_SOURCE_NAME [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the IBM Cloud Object Storage event subscription. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce subscription cos get --name mycosevent

Example output

Getting COS source 'mycosevent'...
OK

Name:          mycosevent
ID:            abcdefgh-abcd-abcd-abcd-fb6be2347a14  
Project Name:  myproject 
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111  
Age:           12s  
Created:       2021-03-14T13:28:45-05:00  

Destination:  App:myapp
Bucket:       mybucket
EventType:    all 
Ready:        true  

Conditions:    
    Type            OK    Age  Reason  
    CosConfigured   true  10s    
    Ready           true  10s    
    ReadyForEvents  true  10s    
    SinkProvided    true  10s    

Events:        
    Type    Reason          Age  Source                Messages  
    Normal  CosSourceReady  11s  cossource-controller  CosSource is ready

When Ready is true, then the COS subscription is ready to trigger events per changes to the COS bucket.

`ibmcloud ce subscription cos list`

List all IBM Cloud Object Storage event subscriptions in a project.

ibmcloud ce subscription cos list [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce subscription cos list

Example output

Listing COS sources...
OK

Name        Age  Ready  Bucket        EventType  Prefix  Suffix  Destination
mycosevent  20m  true   mycosbucket  all                         http://myapp.2706b22d-676b.svc.cluster.local

`ibmcloud ce subscription cos update`

Update an IBM Cloud Object Storage event subscription.

ibmcloud ce subscription cos update --name COS_SOURCE_NAME [--destination DESTINATION] [--destination-type DESTINATION_TYPE] [--event-type EVENT_TYPE] [--extension EXTENSION] [--extension-rm EXTENSION_RM] [--output OUTPUT] [--path PATH] [--prefix PREFIX] [--quiet] [--suffix SUFFIX]

Command Options

--name, -n: The name of the IBM Cloud Object Storage event subscription. This value is required.
--destination, -d: The name of the application or job resource that you want to receive events; for example, myapp. If needed, use the --path option to further qualify an app destination. This value is optional.
--destination-type, --dt: The type of the destination. Valid values are app and job. This value is optional.
--event-type, -e: The event types to watch. Valid values are delete, write, and all. This value is optional.
--extension, --ext: Set CloudEvents extensions to send to the destination. Must be in NAME=VALUE format. This action adds a new CloudEvents extension or overrides an existing CloudEvent attribute. Specify one extension per --extension option; for example, --ext extA=A --ext extB=B. This value is optional.
--extension-rm, --ext-rm: Remove CloudEvents extensions to send to the destination by specifying the name of the key. Specify one extension per --ext-rm option; for example, --ext-rm extA --ext-rm extB. This value is optional.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--path: The path within the destination application where events are forwarded; for example, /events. The default path is the root URL of the destination application. This option can only be specified if destination-type is app. This value is optional.
--prefix, -p: Prefix of the IBM Cloud Object Storage object. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--suffix, -s: Suffix of the IBM Cloud Object Storage object. Consider the file type (extension) of your file when specifying the suffix. This value is optional.

Example

The following example updates a COS subscription called mycosevent to listen for only write events.

ibmcloud ce subscription cos update --name mycosevent --event-type write

Example output

Updating COS source 'mycosevent'...
Run 'ibmcloud ce subscription cos get -n mycosevent' to check the COS source status.
OK

Subscription cron commands

The cron event producer is based on cron and generates an event at regular intervals. Use a cron event producer when an action needs to be taken at well-defined intervals or at specific times.

You must be within the context of a project before you use subscription cron commands.

For more information about working with the IBM Cloud Object Storage subscriptions, see Working with the Periodic timer (cron) event producer. See Getting started with subscriptions for more information about working with subscriptions in Code Engine.

You can use either subscription or sub in your subscription cron commands. To see CLI help for the subscription cron command, run ibmcloud ce sub cron -h.

`ibmcloud ce subscription cron create`

Create a cron event subscription.

ibmcloud ce subscription cron create --name CRON_SOURCE_NAME  --destination DESTINATION_REF [--content-type CONTENT_TYPE] [--data DATA] [--data-base64 DATA_BASE64] [--destination-type DESTINATION_TYPE] [--extension EXTENSION] [--force] [--no-wait] [--output OUTPUT] [--path PATH] [--quiet] [--schedule SCHEDULE] [--time-zone TIME_ZONE] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--destination, -d

The name of the application or job resource that you want to receive events; for example, myapp. If needed, use the --path option to further qualify an app destination. This value is required.

-n, --name

The name of the cron event subscription. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 253 characters or fewer and can contain lowercase letters, numbers, periods (.), and hyphens (-).

This value is required.

--content-type, --ct

The media type of the --data or --data-base64 option. Examples include application/json, application/x-www-form-urlencoded, text/html, and text/plain. This value is optional.

--da, --data

The data to send to the destination; for example, '{ "message": "Hello world!" }'. If you specify the --data option, do not use the --data-base64 option.

This value is optional.

--data-base64, --db

The base64-encoded data to send to the destination; for example, Q29kZSBFbmdpbmU=. If you specify the --data-base64 option, do not use the --data option. This value is optional.

--destination-type, --dt

The type of the destination. Valid values are app, function and job. This value is optional. The default value is app.

--extension, --ext

--force, -f

Force to create a cron event subscription. This option skips the validation of the specified destination. This value is optional. The default value is false.

--no-wait, --nw

Create the cron event subscription and do not wait for the subscription to be ready. If you specify the --no-wait option, the subscription create begins and does not wait. Use the subscription cron get command to check the subscription status. This value is optional. The default value is false.

--output, -o

--path

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--schedule, -s

Schedule how often the event is triggered, in crontab format. For example, specify '*/2 * * * *' (in string format) for every two minutes. By default, the cron event is triggered every minute and is set to the UTC time zone. To modify the time zone, use the --time-zone option. This value is optional.

--time-zone, --tz

Set the time zone for your cron event; for example, Asia/Tokyo. If you specify the --schedule option, use this option to specify the time zone. For valid time zone values, see the time zones database. This value is optional. The default value is UTC.

--wait, -w

Create the cron event subscription and wait for the subscription to be ready. If you specify the --wait option, the subscription create waits for a maximum time in seconds, as set by the --wait-timeout option, for the subscription to become ready. If the subscription is not ready within the specified --wait-timeout period, the cron event subscription create fails. This value is optional. The default value is true.

--wait-timeout, --wto

The length of time in seconds to wait for the cron event subscription to be ready. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 15.

Example

The following example creates a cron subscription that is called mycronevent that forwards a cron event to a job that is called myjob every 2 minutes.

ibmcloud ce subscription cron create --name mycronevent --destination myjob --schedule '*/2 * * * *' --destination-type job

Example output

Creating cron source 'mycronevent'...
Run 'ibmcloud ce subscription cron get -n mycronevent' to check the cron source status.
OK

`ibmcloud ce subscription cron delete`

Delete a cron event subscription.

ibmcloud ce subscription cron delete --name CRON_SOURCE_NAME [--force] [--ignore-not-found] [--no-wait] [--quiet] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--name, -n: The name of the cron event subscription. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--no-wait, --nw: Delete the cron event subscription and do not wait for the subscription to be deleted. If you specify the --no-wait option, the subscription delete begins and does not wait. Use the subscription cron get command to check the subscription status. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--wait, -w: Delete the cron event subscription and wait for the subscription to be deleted. If you specify the --wait option, the subscription delete waits for a maximum time in seconds, as set by the --wait-timeout option, for the subscription to be deleted. This command exits when the subscription is deleted or whenever --wait-timeout is reached, whichever comes first. This value is optional. The default value is true.
--wait-timeout, --wto: The length of time in seconds to wait for the cron event subscription to be deleted. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 15.

Example

ibmcloud ce subscription cron delete --name mycronevent -f

Example output

Deleting cron source 'mycronevent'...
OK

`ibmcloud ce subscription cron get`

Display details of a cron event subscription.

ibmcloud ce subscription cron get --name CRON_SOURCE_NAME [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the cron event subscription. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce subscription cron get --name mycronevent

Example output

Getting cron source 'mycronevent'...
OK

Name:          mycronevent  
ID:            abcdefgh-abcd-abcd-abcd-fb6be2347a14  
Project Name:  myproject  
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111  
Age:           18s  
Created:       2021-03-14T13:33:53-05:00  

Destination:  App:kapp  
Schedule:     */2 * * * *  
Time Zone:    UTC  
Ready:        true 

Events:    
    Type     Reason           Age                Source                 Messages  
    Normal   FinalizerUpdate  19s                pingsource-controller  Updated "mycronevent" finalizers

When Ready is true, then the cron subscription is ready to trigger events per the specified schedule.

`ibmcloud ce subscription cron list`

List all cron event subscriptions in a project.

ibmcloud ce subscription cron list [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce subscription cron list

Example output

Listing cron sources...
OK

Name         Age  Ready  Destination                                   Schedule     Data
mycronevent  96m  true   http://myapp.cd4200a7-5037.svc.cluster.local  */2 * * * *

`ibmcloud ce subscription cron update`

Update a cron event subscription.

ibmcloud ce subscription cron update --name CRON_SOURCE_NAME [--content-type CONTENT_TYPE] [--data DATA] [--data-base64 DATA_BASE64] [--destination DESTINATION] [--destination-type DESTINATION_TYPE] [--extension EXTENSION] [--extension-rm EXTENSION_RM] [--output OUTPUT] [--path PATH] [--quiet] [--schedule SCHEDULE] [--time-zone TIME_ZONE]

Command Options

--name, -n

The name of the cron event subscription. This value is required.

--content-type, --ct

The media type of the --data or --data-base64 option. Examples include application/json, application/x-www-form-urlencoded, text/html, and text/plain. This value is optional.

--da, --data

The data to send to the destination; for example, '{ "message": "Hello world!" }'. If you specify the --data option, do not use the --data-base64 option.

This value is optional.

--data-base64, --db

The base64-encoded data to send to the destination; for example, Q29kZSBFbmdpbmU=. If you specify the --data-base64 option, do not use the --data option. This value is optional.

--destination, -d

The name of the application or job resource that you want to receive events; for example, myapp. If needed, use the --path option to further qualify an app destination. This value is optional.

--destination-type, --dt

The type of the destination. Valid values are app, function and job. This value is optional.

--extension, --ext

--extension-rm, --ext-rm

Remove CloudEvents extensions to send to the destination by specifying the name of the key. Specify one extension per --ext-rm option; for example, --ext-rm extA --ext-rm extB. This value is optional.

--output, -o

--path

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--schedule, -s

--time-zone, --tz

Example

The following example updates a cron source subscription that is called mycronevent that forwards a cron event to a job that is called myjob every hour.

ibmcloud ce subscription cron update --name mycronevent --destination myjob --schedule '0 * * * *' --destination-type job

Example output

Updating cron source 'mycronevent'...
Run 'ibmcloud ce subscription cron get -n mycronevent' to check the cron source status.
OK

Subscription `kafka` commands

The Kafka event producer watches for new messages to appear in a Kafka instance. When you create a Code Engine Kafka subscription for a set of topics, your app or job receives a separate event for each new message that appears in one of the topics.

You must be within the context of a project before you use subscription kafka commands.

For more information about working with Kafka event subscriptions, see Working with the Kafka event producer. See Getting started with subscriptions for more information about working with subscriptions in Code Engine.

You can use either subscription or sub in your subscription kafka commands. To see CLI help for the subscription commands, run ibmcloud ce sub kafka -h.

`ibmcloud ce subscription kafka create`

Create a Kafka event subscription.

ibmcloud ce subscription kafka create --name KAFKA_SOURCE_NAME --destination DESTINATION_REF --topic TOPIC --broker BROKER [--consumer-group CONSUMER_GROUP] [--destination-type DESTINATION_TYPE] [--extension EXTENSION] [--force] [--no-wait] [--output OUTPUT] [--password PASSWORD] [--path PATH] [--quiet] [--secret SECRET] [--username USERNAME] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--broker, -b

Set a broker in the Kafka source. A broker is a Kafka server to which the consumer connects. This option can be specified multiple times. This value is required.

--destination, -d

The name of the application or job resource that you want to receive events; for example, myapp. If needed, use the --path option to further qualify an app destination. This value is required.

-n, --name

The name of the Kafka event subscription. Use a name that is unique within the project.

The name must begin and end with a lowercase alphanumeric character.
The name must be 253 characters or fewer and can contain lowercase letters, numbers, periods (.), and hyphens (-).

This value is required.

--topic, -t

Set a topic in the Kafka source. Topics are used to filter messages to consume. This option can be specified multiple times. This value is required.

--consumer-group, --cg

The name of the consumer group for events. This value is optional.

--destination-type, --dt

The type of the destination. Valid values are app and job. This value is optional. The default value is app.

--extension, --ext

--force, -f

Force to create a Kafka event subscription. This option skips the validation of the specified destination and secret. This value is optional. The default value is false.

--no-wait, --nw

Create the Kafka event subscription and do not wait for the subscription to be ready. If you specify the --no-wait option, the subscription create begins and does not wait. Use the subscription kafka get command to check the subscription status. This value is optional. The default value is false.

--output, -o

--password, -p

The password that is used to authenticate to the Kafka instance. If you specify the --password option, you must not specify the --secret option. This value is optional.

--path

--quiet, -q

Specify this option to reduce the output of the command. This value is optional. The default value is false.

--secret, -s

The name of the secret that is used to authenticate to the Kafka instance and which includes both username and password keys. If you specify the --secret option, you must not specify the --username or --password options. This value is optional.

--username, -u

The username that is used to authenticate to the Kafka instance. If you specify the --username option, you must specify the --password option and must not specify the --secret option. This value is optional. The default value is token.

--wait, -w

Create the Kafka event subscription and wait for the subscription to be ready. If you specify the --wait option, the subscription create waits for a maximum time in seconds, as set by the --wait-timeout option, for the subscription to become ready. If the subscription is not ready within the specified --wait-timeout period, the Kafka event subscription create fails. This value is optional. The default value is true.

--wait-timeout, --wto

The length of time in seconds to wait for the Kafka event subscription to be ready. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 120.

Example

The following example creates a Kafka event subscription that is called mykafkaevent that forwards a Kafka event to a receiving app that is called kafka-receiver-app. Specify a --broker option for each broker for your topic. The --destination option specifies the Code Engine resource that receives the events. The kafka-subscription-secret provides credentials to access the message broker.

ibmcloud ce subscription kafka create --name mykafkasubscription --destination kafka-receiver-app --secret kafka-subscription-secret --topic kafka-topic1 --broker broker-3-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --broker broker-5-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --broker  broker-0-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --broker broker-1-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --broker broker-4-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --broker broker-2-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093

Example output

Creating Kafka event subscription 'mykafkasubscription'...
Run 'ibmcloud ce subscription kafka get -n mykafkasubscription' to check the Kafka event subscription status.
OK

`ibmcloud ce subscription kafka delete`

Delete a Kafka event subscription.

ibmcloud ce subscription kafka delete --name KAFKA_SOURCE_NAME [--force] [--ignore-not-found] [--no-wait] [--quiet] [--wait] [--wait-timeout WAIT_TIMEOUT]

Command Options

--name, -n: The name of the Kafka event subscription. This value is required.
--force, -f: Force deletion without confirmation. This value is optional. The default value is false.
--ignore-not-found, --inf: If not found, do not fail. This value is optional. The default value is false.
--no-wait, --nw: Delete the Kafka event subscription and do not wait for the subscription to be deleted. If you specify the --no-wait option, the subscription delete begins and does not wait. Use the subscription kafka get command to check the subscription status. This value is optional. The default value is false.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--wait, -w: Delete the Kafka event subscription and wait for the subscription to be deleted. If you specify the --wait option, the subscription delete waits for a maximum time in seconds, as set by the --wait-timeout option, for the subscription to be deleted. This command exits when the subscription is deleted or whenever --wait-timeout is reached, whichever comes first. This value is optional. The default value is true.
--wait-timeout, --wto: The length of time in seconds to wait for the Kafka event subscription to be deleted. This value is required if the --wait option is specified. This value is ignored if the --no-wait option is specified. The default value is 15.

Example

ibmcloud ce subscription kafka delete --name mykafkasubscription -f

Example output

Deleting Kafka event subscription 'mykafkasubscription'...
OK

`ibmcloud ce subscription kafka get`

Display details of a Kafka event subscription.

ibmcloud ce subscription kafka get --name KAFKA_SOURCE_NAME [--output OUTPUT] [--quiet]

Command Options

--name, -n: The name of the Kafka event subscription. This value is required.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce subscription kafka get --name mykafkasubscription

Example output

Getting Kafka event subscription 'mykafkasubscription'...
OK

Name:          mykafkasubscription  
[...]
Destination Type:                 app
Destination:                      kafka-receiver-app2
Brokers:
broker-3-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
broker-5-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
broker-0-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
broker-1-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
broker-4-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
broker-2-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
Consumer Group:                   knative-kafka-source-a4072fe1-1dfa-4470-9d07-bf7a0ff8e340
Topics:
kafka-topic1
Secret key reference (user):      kafka-subscription-secret.username
Secret key reference (password):  kafka-subscription-secret.password
Ready:                            true

Conditions:
Type                     OK    Age  Reason
ConnectionEstablished    true  24s
InitialOffsetsCommitted  true  24s
Ready                    true  24s
Scheduled                true  24s
SinkProvided             true  24s

Events:
Type     Reason           Age  Source                  Messages
Normal   FinalizerUpdate  26s  kafkasource-controller  Updated "mykafkasubscription" finalizers

When Ready is true, then the Kafka subscription is ready to trigger events per the specified schedule.

`ibmcloud ce subscription kafka list`

List all Kafka event subscriptions in a project.

ibmcloud ce subscription kafka list [--output OUTPUT] [--quiet] [--sort-by SORT_BY]

Command Options

--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--sort-by, -s: Specifies the column by which to sort the list. Valid values are name and age. This value is optional. The default value is name.

Example

ibmcloud ce subscription kafka list

Example output

Listing Kafka event subscriptions...
OK

Name                 Age  Ready  Destination Type  Destination          Path  Consumer Group                                             Reason  
mykafkasubscription  94s  true   app               kafka-receiver-app        knative-kafka-source-dc367965-15e4-44f3-bedf-25d453524a68

`ibmcloud ce subscription kafka update`

Update a Kafka event subscription.

ibmcloud ce subscription kafka update --name KAFKA_SOURCE_NAME [--broker BROKER] [--destination DESTINATION] [--destination-type DESTINATION_TYPE] [--extension EXTENSION] [--extension-rm EXTENSION_RM] [--output OUTPUT] [--password PASSWORD] [--path PATH] [--quiet] [--secret SECRET] [--topic TOPIC] [--username USERNAME]

Command Options

--name, -n: The name of the Kafka event subscription. This value is required.
--broker, -b: Set a broker in the Kafka source. A broker is a Kafka server to which the consumer connects. This option can be specified multiple times. This value is optional.
--destination, -d: The name of the application or job resource that you want to receive events; for example, myapp. If needed, use the --path option to further qualify an app destination. This value is optional.
--destination-type, --dt: The type of the destination. Valid values are app and job. This value is optional.
--extension, --ext: Set CloudEvents extensions to send to the destination. Must be in NAME=VALUE format. This action adds a new CloudEvents extension or overrides an existing CloudEvent attribute. Specify one extension per --extension option; for example, --ext extA=A --ext extB=B. This value is optional.
--extension-rm, --ext-rm: Remove CloudEvents extensions to send to the destination by specifying the name of the key. Specify one extension per --ext-rm option; for example, --ext-rm extA --ext-rm extB. This value is optional.
--output, -o: Specifies the format of the command output. Valid values are json, yaml, jsonpath=JSONPATH_EXPRESSION, and jsonpath-as-json=JSONPATH_EXPRESSION. Use jsonpath to specify the path to an element of the JSON output. This value is optional.
--password, -p: The password that is used to authenticate to the Kafka instance. If you specify the --password option, you must not specify the --secret option. This value is optional.
--path: The path within the destination application where events are forwarded; for example, /events. The default path is the root URL of the destination application. This option can only be specified if destination-type is app. This value is optional.
--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.
--secret, -s: The name of the secret that is used to authenticate to the Kafka instance and which includes both username and password keys. If you specify the --secret option, you must not specify the --username or --password options. This value is optional.
--topic, -t: Set a topic in the Kafka source. Topics are used to filter messages to consume. This option can be specified multiple times. This value is optional.
--username, -u: The username that is used to authenticate to the Kafka instance. If you specify the --username option, you must specify the --password option and must not specify the --secret option. This value is optional. The default value is token.

Example

The following example updates a Kafka event subscription to use kafka-topic2 instead of kafka-topic1.

ibmcloud ce subscription kafka update --name mykafkasubscription --topic kafka-topic2

Example output

Updating Kafka event subscription 'mykafkasubscription'...
Run 'ibmcloud ce subscription kafka get -n mykafkasubscription' to check the Kafka event subscription status.
OK

Version command

Display the version of the code-engine command-line interface.

`ibmcloud ce version`

Display the version of the code-engine command-line interface.

ibmcloud ce version [--quiet]

Command Options

--quiet, -q: Specify this option to reduce the output of the command. This value is optional. The default value is false.

Example

ibmcloud ce version

Example output

version:  v1.17.0
commit:   3ab130b746f4784c9ff8d3da7bb05b6e7acda6d5