Deploying and scaling applications

With this tutorial, deploy an application with the Code Engine CLI. The application scales to zero when not in use.

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.

Before you begin

All Code Engine users are required to have a Pay-as-you-Go account. Tutorials might incur costs. Use the Cost Estimator to generate a cost estimate based on your projected usage. For more information, see Code Engine pricing.

Select an image file

This tutorial uses a sample image, icr.io/codeengine/hello, which is a simple Hello World program. The program includes an environment variable TARGET, and prints Hello ${TARGET}. If the environment variable is empty, Hello World is returned. For more information about the code that is used for this example, see hello.

If you have a container image that you want to use, you can replace the image reference in the next step with your own Docker repository, image name, and version.

Creating and deploying an application

Create your application by using the ibmcloud ce application create command. In the following example, use myapp as the name of the application and specify icr.io/codeengine/hello as the image to reference.

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

Example output

Creating application 'myapp'...
[...]
Run 'C:\Program Files\IBM\Cloud\bin\ibmcloud.exe ce application get -n myapp' to check the application status.
OK
https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud

Run the ibmcloud ce application get command to display details about the application, including the URL for the myapp application.

ibmcloud ce application get -n 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:                3m6s
Created:            2021-07-11T06:39:41-05:00
URL:                https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.4svg40kna19.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/hello
Resource Allocation:
CPU:                1
Ephemeral Storage:  400M
Memory:             4G

Revisions:
myapp-huv70-1:
    Age:                3m6s
    Traffic:            100%
    Image:              icr.io/codeengine/hello (pinned to f0dc03)
    Running Instances:  1

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

Conditions:
    Type                 OK    Age  Reason
    ConfigurationsReady  true  52s
    Ready                true  26s
    RoutesReady          true  26s

Events:
Type    Reason   Age   Source              Messages
Normal  Created  3m9s  service-controller  Created Configuration "myapp"
Normal  Created  3m9s  service-controller  Created Route "myapp"

Instances:
Name                                       Revision       Running  Status       Restarts  Age
myapp-huv70-1-deployment-6656cfc796-7gl27  myapp-huv70-1  1/2      Terminating  0         3m9s

Obtain the URL of the application from running the application get command as described in the previous step. To retrieve the URL of the application directly, you can use the --output option and specify the URL format on the application get command. Additionally, you can run the ibmcloud ce application list command to get the application URL.
```
ibmcloud ce application get -n myapp -output url
```
Example output
```
https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud
```
Copy the URL from the previous output and call the application with curl.
```
curl https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud
```
Example output
```
Hello World
```

You successfully deployed and started a Code Engine application!

Updating your application

Update your newly created application by adding an environment variable to return Hello Stranger with the ibmcloud ce application update command.

ibmcloud ce application update --name myapp --env TARGET=Stranger

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

Use the application get command to display details about your app, including the latest revision information.

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:                3m6s
Created:            2021-07-11T06:39:41-05:00
URL:                https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.4svg40kna19.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
    Literal  TARGET           Stranger
Image:                icr.io/codeengine/hello

 Status Summary:  Application deployed successfully

 Environment Variables:
     Type     Name    Value
     Literal  TARGET  Stranger
 Image:                  icr.io/codeengine/hello
 Resource Allocation:
     CPU:                1
     Ephemeral Storage:  400M
     Memory:             4G

 Revisions:
 myapp-00002:
     Age:                54m
     Traffic:            100%
     Image:              icr.io/codeengine/hello (pinned to f0dc03)
     Running Instances:  1

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

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

 Events:
 Type    Reason   Age    Source              Messages
 Normal  Created  4m17s  service-controller  Created Configuration "myapp"
 Normal  Created  4m17s  service-controller  Created Route "myapp"

 Instances:
    Name                                     Revision     Running  Status       Restarts  Age
    myapp-00001-deployment-bf7559548-mxgvq   myapp-00001  2/3      Terminating  0         4m55s
    myapp-00002-deployment-8495f8ccb9-kmc57  myapp-00002  3/3      Running      0         88s

From the output in the Revisions section, you can see the latest application revision of the myapp service. Also, notice that 100% of the traffic to the application is running the latest revision of the app.

Call the application.

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

Example output

Hello Stranger

From the output of this command, you can see the updated app now returns Hello Stranger.

Scaling your application (scale-to-zero and scale-from-zero)

The number of running instances of an application are automatically scaled up or down (to zero) based on incoming workload.

The following example illustrates how to scale your application with the CLI. You can control the maximum and minimum number of running instances of your app by changing the values of the --min-scale and --max-scale options with the application create or application update command.

Call the application.

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

Run the application get command to display the status of your application. Notice the value for Running instances. In this example, the app has 1 running instance.

ibmcloud ce application get --name myapp

Example output

[...]

Name:          myapp
[...]
URL:                https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.4svg40kna19.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
    Literal  TARGET           Stranger
Image:                  icr.io/codeengine/hello

Resource Allocation:
    CPU:                1
    Ephemeral Storage:  400M
    Memory:             4G

Revisions:
myapp-00002:
    Age:                58m
    Traffic:            100%
    Image:              icr.io/codeengine/hello (pinned to f0dc03)
    Running Instances:  1

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

Conditions:
    Type                 OK    Age  Reason
    ConfigurationsReady  true  57m
    Ready                true  57m
    RoutesReady          true  57m

Events:
    Type    Reason   Age    Source              Messages
    Normal  Created  4m17s  service-controller  Created Configuration "myapp"
    Normal  Created  4m17s  service-controller  Created Route "myapp"

Instances:
    Name                                     Revision     Running  Status   Restarts  Age
    myapp-00002-deployment-8495f8ccb9-kmc57  myapp-00002  3/3      Running  0         16m

Run the application get command again and notice that the value for Running instances scaled to zero. When the application is finished running, the number of running instances automatically scales to zero, if the --min-scale option is set to 0, which is the default value.

ibmcloud ce application get -n myapp

Example output

[...]
URL:                https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.4svg40kna19.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
    Literal  TARGET           Stranger
Image:                  icr.io/codeengine/hello

Resource Allocation:
    CPU:                1
    Ephemeral Storage:  400M
    Memory:             4G

Revisions:
myapp-huv70-2
    Age:                13m
    Traffic:            100%
    Image:              icr.io/codeengine/hello (pinned to 548d5c)
    Running Instances:  0

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

Conditions:
    Type                 OK    Age  Reason
    ConfigurationsReady  true  13m
    Ready                true  13m
    RoutesReady          true  13m

Events:
    Type    Reason   Age    Source              Messages
    Normal  Created  4m17s  service-controller  Created Configuration "myapp"
    Normal  Created  4m17s  service-controller  Created Route "myapp"

Instances:
    Name                                       Revision       Running  Status       Restarts  Age
    myapp-00002-deployment-8495f8ccb9-kmc57    myapp-00002    3/3      Running      0         16m

Your application scaled down to zero.

Call the application again to scale from zero.

Run the application get command again and notice that the value for Running instances scaled from zero and information about the instance is displayed.

ibmcloud ce application get -n myapp

Example output

Name:          myapp
[...]
URL:                https://myapp.4svg40kna19.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.4svg40kna19.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
    Literal  TARGET           Stranger
Image:                  icr.io/codeengine/hello

Resource Allocation:
    CPU:                1
    Ephemeral Storage:  400M
    Memory:             4G

Revisions:
myapp-huv70-2:
    Age:                3h11m
    Traffic:            100%
    Image:              icr.io/codeengine/hello (pinned to f0dc03)
    Running Instances:  1

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

Conditions:
    Type                 OK    Age    Reason
    ConfigurationsReady  true  3h10m
    Ready                true  3h10m
    RoutesReady          true  3h10m

Events:
    Type    Reason   Age    Source              Messages
    Normal  Created  4m17s  service-controller  Created Configuration "myapp"
    Normal  Created  4m17s  service-controller  Created Route "myapp"

Instances:
    Name                                     Revision     Running  Status   Restarts  Age
    myapp-00002-deployment-8495f8ccb9-kmc57  myapp-00002  3/3      Running  0         16m

Your application scales back up.

For more information about scaling your app, see Configuring application scaling.

Next steps

After your app deploys, access your app through a URL.
You can create a custom domain mapping and assign it to your app. For more information about deploying apps across multiple regions with a custom domain name, see Configuring a highly available application.
Now that your app is deployed, consider making your apps event-driven. By using event subscriptions, you can trigger your apps by periodic schedules or set your app to react to events such as file uploads or Kafka messages.

After your app is deployed, you can update your deployed app and its referenced code by using any of the following ways, independent of how you created or previously updated your app:

If you have a container image, per the Open Container Initiative (OCI) standard, then you need to provide only a reference to the image, which points to the location of your container registry when you deploy your app. You can deploy your app with an image in a public registry or private registry.

If you created your app by using the app create command and you specified the --build-source option to build the container image from local or repository source, and you want to change your app to point to a different container image, you must first remove the association of the build from your app. For example, run ibmcloud ce application update -n APP_NAME --build-clear. After you remove the association of the build from your app, you can update the app to reference a different image.
If you are starting with source code that resides in a Git repository, you can choose to let Code Engine take care of building the image from your source and deploying the app with a single operation. In this scenario, Code Engine uploads your image to IBM Cloud® Container Registry. To learn more, see Deploying your app from repository source code. If you want more control over the build of your image, then you can choose to build the image with Code Engine before you deploy your app.
If you are starting with source code that resides on a local workstation, you can choose to let Code Engine take care of building the image from your source and deploying the app with a single CLI command. In this scenario, Code Engine uploads your image to IBM Cloud® Container Registry. To learn more, see Deploying your app from local source code with the CLI. If you want more control over the build of your image, then you can choose to build the image with Code Engine before you deploy your app.

For example, you might choose to let Code Engine handle the build of your local source while you evolve the development of your source for the app. Then, after the image is matured, you can update the deployed app to reference the specific image that you want. You can repeat this process as needed.

When you deploy your updated app, the latest version of your referenced container image is downloaded and deployed, unless a tag is specified for the image. If a tag is specified for the image, then the tagged image is used for the deployment.

Looking for more code examples? Check out the Samples for IBM Cloud Code Engine GitHub repo.