Working with apps in Code Engine

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

If you want to use the Code Engine console, go to Code Engine overview.
If you want to use the CLI, set up your Code Engine CLI environment.
Plan and choose your approach for making your code run as a Code Engine application component.
Ensure that your app follows the 12-factor app methodology.

For security features provided with Code Engine, see Code Engine and security.

Code Engine provides custom resource definition (CRD) methods. For more information, see Serving CRD methods.

Not sure what type of Code Engine workload to create? See Planning for Code Engine.

How do I make my code run as a Code Engine application component?

Whether your code exists as source in a local file or in a Git repository, or your code is a container image that exists in a public or private registry, Code Engine provides you with a streamlined way to run your code as an 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 create and deploy your app. You can deploy your app with an image in a public registry or private registry.
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 create and 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 create and deploy your app.

After your app is deployed, you can also update your deployed app by using any of the preceding ways, independent of how you created or previously updated your app.

When you deploy your application, 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.

The image that is associated with your specific application revision has a unique container registry digest, and Code Engine uses this digest for the life of your application revision. If you create a newer version of an image with the same tag as the original image, the original image is overwritten in the container registry and becomes untagged. The newer image is tagged, and this newer image has a different digest. Your Code Engine application does not use this newer image, because the newer image has a different digest than the image that is referenced by the application revision. Code Engine can still create new instances of the application revision as long as the untagged image, which was referenced originally, still exists. For more information, see Why can't Code Engine pull an image?

The default URL for applications is of the format https://<appname>.<uuid>.<region>.codeengine.appdomain.cloud where appname is the name of your app, uuid is the automatically generated unique identifier, and region is the region in which your Code Engine project resides. The UUID portion of the URL of an application is of the format aaaabbbbccc. The automatically generated application URL persists for the lifecycle of the project for your application.

For more information about endpoints to access applications by region, see Code Engine endpoints for accessing applications.

What do I need to know about ports for apps in Code Engine?

By default, Code Engine assumes that apps listen for incoming connections on port 8080. In addition, Code Engine sets the PORT environment variable to the port value that the application is expected to be listening on. If your app needs to listen on a port other than port 8080, either deploy your app from the console and specify the correct port or use the --port option on the app create command. For more information about environment variables that are set by Code Engine, see Automatically injected environment variables. The following ports are reserved by Code Engine: 8022, 8008, 8012, 9090, 9091, and 15090. Only one port can be exposed as the listening port.

Inbound connections to Code Engine over HTTP on the Internet use port 80. Inbound connections to Code Engine over HTTPS on the Internet use port 443

If a port scan shows more open ports, see Why does my port scan show more open ports than expected?

Considerations for HTTP handling

When you are working with applications (or jobs), it is helpful to be aware of basic HTTP handling in Code Engine.

For incoming application connections that use HTTP, the transport layer security (TLS) aspects are managed automatically by Code Engine outside of the application code. The HTTP Server for the application needs to be concerned about only HTTP connectivity and not HTTPS connectivity. In particular, Code Engine uses Cloud Internet Services (CIS) in IBM Cloud, which is based on CloudFlare, as the intrusion prevention system (IPS) for DNS and DDOS protection on layer 4. In other words, the TCP/IP connection that is established on the IPS is owned and managed by Cloudflare. For more information, see Cloudflare documentation.
Internet connections that are bound for Code Engine applications are automatically redirected to use HTTPS.
Outbound connections from applications to other Code Engine applications are automatically protected by TLS. Code Engine automatically manages this connectivity, so the protocol (or URL) that is used is HTTP and not HTTPS.
Outbound connections from applications to non-Code Engine applications, such as the internet, use HTTP or HTTPS depending on the protocol that is specified in the app code or URL.
Outbound connections from batch jobs use the HTTP or HTTPS protocol that is specified in the job code or URL. This behavior includes connections from batch jobs to Code Engine apps.

Options for visibility for a Code Engine application

With Code Engine, you can determine the right level of visibility for your application by defining the endpoints, or system domain mappings that are available for receiving requests.

Every application has an internal system domain mapping that is visible to all components within the same Code Engine project, but not outside of the project. In addition to the internal system domain mapping, you choose to make the application visible to either the public internet or the IBM Cloud private network.

For public or private visibility, the application is exposed on an HTTPS endpoint. For details about the TLS certificate that is used, see TLS certificates for Code Engine projects.

You can deploy your application with the following visibility levels:

Visibility for applications
Setting	Description
internal (project)	An app with this setting can receive requests from components in the same Code Engine project. Setting an internal (project) 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 within the same Code Engine project. This endpoint is always enabled.
public	An app with this setting is exposed to the internet and your Code Engine project. Setting a public endpoint means that your app can receive requests from the public internet or from components within your Code Engine project. This setting is the default.
private	An app with this setting is exposed to the IBM Cloud private network and your Code Engine project. Setting a private endpoint means that your app is not accessible from the public internet and network access is only possible from other IBM Cloud services by using Virtual Private Endpoints (VPE) or Code Engine components that are running in the same project.

You can set the endpoint settings for visibility of an application from the console or with the CLI when you create and deploy, or update your app.

Deploying your app with a public endpoint

When you deploy an app, by default, the application deploys such that it can receive requests from the public internet or from components within the same Code Engine project. In this case, the app is deployed with a public endpoint.

Deploying your app with a private endpoint

You can set the endpoint visibility for your app such that it is deployed with a private endpoint. Setting a private endpoint means that your app is not accessible from the public internet and network access is only possible from other IBM Cloud services from virtual private endpoints (VPE) or Code Engine components that are running in the same project (cluster-local).

For example, if your solution consists of a component that is running on an IBM Cloud Kubernetes Service Kubernetes cluster within your own virtual private endpoint and you want to access the Code Engine application from the IBM Cloud private network, you can set the visibility of the application to private. When the visibility of the app is set to private, the app is not accessible through the public internet. The application is still accessible from other applications within the project.

You can deploy your application with a private endpoint so that the app is only exposed through the IBM Cloud private network and not exposed to the external internet. The application is still reachable through shared components from within the internal network and the application endpoint needs to be secured.

With the CLI, set the endpoint visibility for your app so that it is deployed with a private endpoint by using the --visibility=private option on the app create or app update command. You can obtain the available URLs for your app that reflect your endpoint definition by using the app get command.

From the console, set the visibility of endpoints for your app by using the Endpoints setting when you create your app. After your app is deployed, you can view and modify these system domain mapping settings on the Domain mappings tab on your application page.

For more information about connecting over private networks, see Using Virtual Private Endpoints with Code Engine.

Deploying your app with a project endpoint

You can set the endpoint visibility for your app such that it is deployed with an internal (project) 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 within the same Code Engine project. This endpoint is always enabled. Applications are still accessible through shared components and therefore need to be secured.

For example, if your solution consists of several applications within a project, you might set up your solution such that only one of those applications is visible from the internet so that it handles incoming traffic. This public-facing application can delegate work to other applications in your solution so that they do not need to be visible from the internet.

With the CLI, set the endpoint visibility for your app so that it is deployed with a project endpoint by using the --visibility=project option on the app create or app update command. You can obtain the available URLs for your app that reflect your endpoint definition by using the app get command.

Options for deploying a Code Engine application

Learn about the options that you can specify when you deploy your app. Note that options can vary between the console and the CLI.

Memory and CPU

When you deploy your app, you can specify the amount of memory and CPU that your app can consume. These amounts can vary, depending on if your app is compute-intensive, memory-intensive, or balanced.

By default, your application is assigned 4 G of memory and 1 vCPU. For more information about selecting memory and CPU, see Supported memory and CPU combinations.

Deploying your app with commands and arguments

You can define commands and arguments for your application to use at run time.

Define commands and arguments for your application by adding the --cmd and --arg options to your app create command.

ibmcloud ce app create --name myapp --image icr.io/codeengine/hello --cmd /myapp --arg --debug

For more information about using cmd and arg, see Defining commands and arguments for your Code Engine workloads.

Creating and running your app with environment variables

You can define and set environment variables as key-value pairs that can be used by your application at run time.

You can define environment variables when you create your application, or when you update an existing application from the console or with the CLI.

For more information about defining environment variables, see Working with environment variables.

Code Engine automatically injects certain environment variables into the app. For more information about automatically injected environment variables, see Automatically injected environment variables.

Creating and running your app when using secrets and configmaps

In Code Engine, secrets and configmaps can be consumed by your application by using environment variables.

Both secrets and configmaps are key-value pairs. When mapped to environment variables, the NAME=VALUE relationships are set such that the name of the environment variable corresponds to the "key" of each entry in those maps, and the value of the environment variable is the "value" of that key.

Your application can use environment variables to fully reference a configmap (or secret) or reference individual keys in a configmap (or secret).

For more information, see referencing secrets by using environment variables and referencing configmaps by using environment variables.

Considerations for application quotas

When you work with applications, functions, and batch jobs, these resources run within the context of a Code Engine project. Resource quotas are defined on a per project basis, and limits apply for applications, functions, and batch jobs.

For more information about Code Engine limits, see Limits and quotas for Code Engine.

Next steps

Now that you are familiar with key concepts of working with Code Engine applications, are you ready to deploy and work with apps? See

For more information about working with apps, see