--- name: codeengine-kubernetes title: Using Kubernetes with Code Engine description: IBM Cloud® Code Engine is designed so that you do not need to interact with the underlying technology it is built upon. However, if you have existing tools that are based on Kubernetes or Knative, you can still use it with Code Engine. Code Engine supports the Kubernetes (and Knative) APIs and their CLI commands. For more information about Knative, see Using Knative with Code Engine. last-updated: 2026-07-08 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/codeengine?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Using Kubernetes with Code Engine {: #kubernetes} IBM Cloud® Code Engine is designed so that you do not need to interact with the underlying technology it is built upon. However, if you have existing tools that are based on Kubernetes or Knative, you can still use it with Code Engine. Code Engine supports the Kubernetes (and Knative) APIs and their CLI commands. For more information about Knative, see [Using Knative with Code Engine](https://cloud.ibm.com/docs/codeengine?topic=codeengine-knative&format=markdown). {: shortdesc} If you decide to use Kubernetes with Code Engine, consider the following information: * Most containers or pods that run on Kubernetes also run on Code Engine. * Kubernetes constructs, such as deployments, run on Code Engine if they do not use cluster-wide capabilities, such as security policies. Code Engine is scoped to what can run in a Kubernetes namespace. Code Engine does not support OpenShift-specific resources or other container orchestration platforms, such as Docker Swarm or Compose Swarm. ## Installing the Kubernetes command-line interface {: #kubernetes-kubectl} To install the Kubernetes CLI, download and install the [`kubectl` CLI](https://kubernetes.io/docs/tasks/tools/){: external}. {: shortdesc} Be sure to add the `kubectl` binary to your system's PATH environment variable. {: tip} ## Interacting with Kubernetes API {: #kubectl-kubeconfig} To interact with your project from the Kubernetes command-line interface, `kubectl`, or with Knative, `kn` you must set up your environment to interact with the Kubernetes API of Code Engine. Before you begin - You must [create your project](https://cloud.ibm.com/docs/codeengine?topic=codeengine-manage-project&format=markdown#create-a-project) and the project must be in `active` status. - Install the [Kubernetes CLI (`kubectl`)](https://kubernetes.io/docs/tasks/tools/) and the [Knative CLI (`kn`)](https://knative.dev/docs/client/install-kn/). You can set up your environment in the following ways. - You can add the `--kubecfg` option to your **`project select`** command. For example, ```txt ibmcloud ce project select --name PROJECT_NAME --kubecfg ``` {: pre} - You can export the `kubeconfig` file directly. Run the **`ibmcloud ce project current`** command to find the project that you are currently targeting. This command also returns the **`export`** command for your `kubeconfig` file. For example, ```txt ibmcloud ce project current ``` {: pre} Example output ```txt 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 ``` {: screen} Then, copy the export command, paste it into your command-line interface, and run it. Verify that your environment is set correctly by running the **`kubectl config`** command. ```txt kubectl config current-context ``` {: pre} If the context is correctly set, the output matches the `Kubectl Context` value of your project. For example, if your `Kubectl Context` value of your project is `4svg40kna19`, the command returns `4svg40kna19`. For more information about Kubernetes and how it works with Code Engine architecture, see [Learning about Code Engine architecture and workload isolation](https://cloud.ibm.com/docs/codeengine?topic=codeengine-architecture&format=markdown). {: important} ## Required access authorities to work with Kubernetes API {: #kubectl-api} After you set up your environment, you can interact with Kubernetes API. You must have the correct level of authority for specific tasks. These roles are set in Identity and access management. See [IBM Cloud service roles](https://cloud.ibm.com/docs/codeengine?topic=codeengine-iam&format=markdown#service). | Resource | Manager role | Writer role | Reader role | | --------- | -------------- | ------------ | ------------ | | `serviceaccounts` | `get`, `list`, `watch` | `get`, `list`, `watch` | None | | `secrets` | `get`, `list`, `watch`, `create`, `delete`, `update`, `patch`, `apply`, `edit` | `get`, `list`, `watch`, `create`, `delete`, `update`, `patch`, `apply`, `edit` | None | | `configmaps` | `get`, `list`, `watch`, `create`, `delete`, `update`, `patch`, `apply`, `edit` | `get`, `list`, `watch`, `create`, `delete`, `update`, `patch`, `apply`, `edit` | None | | `events` | `get`, `list`, `watch` | `get`, `list`, `watch` | None | | `pods/log` | `get`, `list`, `watch` | `get`, `list`, `watch` | `get`, `list`, `watch` | | `pods` | `get`, `list`, `watch`, `create`, `delete`, `patch`, `apply` | `get`, `list`, `watch`, `create`, `delete`, `patch`, `apply` | `get`, `list`, `watch` | | `services` | `get`, `list`, `watch`, `create`, `delete`, `patch`, `apply` | `get`, `list`, `watch`, `create`, `delete`, `patch`, `apply` | `get`, `list`, `watch` | | `pods/exec` | `create` | `create` | None | | `pods/portforward` | `create` | `create` | None | | `pods/attach` | `create` | None | None | | `pods/status` | `get`, `list` | `get`, `list` | None | | `resourcequotas` | `get`, `list`, `watch` | `get`, `list`, `watch` | get, list, watch | | `limitranges` | `get`, `list`, `watch` | `get`, `list`, `watch` | None | | `deployments` | `get`, `list`, `watch`, `create`, `delete`, `patch`, `apply` | `get`, `list`, `watch`, `create`, `delete`, `patch`, `apply` | `get`, `list`, `watch` | | `daemonset` | `get`, `list`, `watch` | `get`, `list`, `watch` | `get`, `list`, `watch` | | `pods.metrics.k8s.io` | list | list | list | {: caption="Kubernetes authorities" caption-side=ottom"} ## Retrieving your Kubernetes configuration {: #kubernetes-getconfig} You can retrieve your Kubernetes configuration with the [REST API](#api-rest) or the [Code Engine CLI](#api-cli). ### Retrieve your Kubernetes configuration with REST API {: #api-rest} To retrieve your Kubernetes configuration with REST API, 1. Authenticate with IBM Cloud® Identity and Access Management (IAM) to receive an IAM access token. 2. Query the IBM Cloud catalog and the IBM Cloud Resource controller to receive a GUID for your project. 3. Use the IBM Cloud Code Engine API to receive a Kubernetes configuration. #### Authenticate with Cloud Identity and Access Management {: #api-iam} [Create your IBM Cloud IAM access token](https://cloud.ibm.com/docs/iam?topic=iam-manapikey&format=markdown) by making a POST request to `https://iam.cloud.ibm.com/identity/token`. #### Determine the GUID of your Code Engine project {: #api-guid} Determine the GUID of your Code Engine project by querying the IBM Cloud catalog and the IBM Cloud. As this GUID does not change, you need to do this step only one time. If you already know your Code Engine project GUID, you can skip this step. To use the Code Engine CLI to discover the GUID of your Code Engine project, complete the following steps. 1. Log in into IBM Cloud and target a region, account, and resource group. ```txt ibmcloud login target -r REGION -c ACCOUNT_ID -g RESOURCE_GROUP ``` {: pre} 2. Run the **`ibmcloud resource`** command. ```txt ibmcloud resource service-instances --service-name codeengine --long ``` {: pre} 3. Identify the service instance that represents your Code Engine project and determine the GUID from the output. To use the REST API to discover the GUID of your Code Engine project, complete the following steps. Before you begin, you must have the `access_token` from the previous step. 1. Use the following IBM Cloud catalog API method: [Returns parent catalog entries](https://cloud.ibm.com/apidocs/resource-catalog/global-catalog#list-catalog-entries){: external}. Example output ```txt curl -X GET \ 'https://globalcatalog.cloud.ibm.com/api/v1?include=*&q=name:codeengine+active:true' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` {: pre} Identify the unique resource ID in the resources list. The field name is `ID` and the JSON path is `resources[].id`. 2. Query the IBM Cloud Resource controller with the IBM Cloud Resource controller API method [Get a list of all resource instances](https://cloud.ibm.com/apidocs/resource-controller/resource-controller#list-resource-instances){: external}. You must have the Code Engine project name, the region that your project resides, and the unique resource ID of Code Engine in the global catalog. Use the name of your Code Engine project as the query parameter. Example output ```txt curl -X GET \ 'https://resource-controller.cloud.ibm.com/v2/resource_instances?name=MY_PROJECT&resource_id=RESOURCE_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` {: pre} 3. Identify the Code Engine project from your region in the result list. Find the `guid` output to use in the next steps. #### Query the IBM Code Engine API {: #api-query-api} Before you begin, you must have the following information. - The `access_token` and `refresh_token` from previous steps. - The `guid` of your Code Engine project. - The region in which your Code Engine project is located. Use the [`get kubeconfig for the specified project`](https://cloud.ibm.com/apidocs/codeengine/v1#get-kubeconfig){: external} Code Engine API method to get the Kubernetes configuration. Example output ```txt curl -X GET \ 'https://resource-controller.cloud.ibm.com/v2/resource_instances?name=MY_PROJECT&resource_id=RESOURCE_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` {: pre} ### Retrieve your Kubernetes configuration with the Code Engine CLI {: #api-cli} 1. Log in into IBM Cloud and target a region, account, and resource group. ```txt ibmcloud login target -r REGION -c ACCOUNT_ID -g RESOURCE_GROUP ``` {: pre} 2. Create your Code Engine project: ```txt ibmcloud ce project create --name PROJECT ``` {: pre} 3. Select your Code Engine project as the current context and append the project to the default Kubernetes configuration file. ```txt ibmcloud ce project select --name PROJECT --kubecfg ``` {: pre} Now you are ready to use **`kubectl`** commands with your project. For more information about using Code Engine APIs, Kubernetes API, and `kubectl`, see the following topics, - [Code Engine API](https://cloud.ibm.com/apidocs/codeengine){: external} - [Kubernetes REST API](https://kubernetes.io/docs/reference/using-api){: external} - [Kubernetes API concepts](https://kubernetes.io/docs/reference/using-api/api-concepts/){: external} - [API client libraries](https://kubernetes.io/docs/reference/#api-client-libraries){: external} - [**`kubectl`** command](https://kubernetes.io/docs/reference/#cli-reference){: external} ## Custom resource definition (CRD) {: #kubernetes-api-crd} The following sections list the custom resource definition methods to use with Code Engine. ### Batch CRD methods {: #api-crd-batch} You can use batch CRDs when [Working with jobs and job runs in Code Engine](https://cloud.ibm.com/docs/codeengine?topic=codeengine-job-plan&format=markdown). | Group | Version | Kind | | --------- | -------- | -------- | | `codeengine.cloud.ibm.com` | v1beta1 | `JobDefinition` | | `codeengine.cloud.ibm.com` | v1beta1 | `JobRun` | {: caption="Batch CRDs for Code Engine" caption-side="bottom"} After you retrieve the Kubernetes configuration, you can view Batch CRD details by using the following methods. 1. Use `kubectl explain --api-version='codeengine.cloud.ibm.com/v1beta1' `. 2. [Download Swagger or `OpenAPI` specification of CRDs](https://kubernetes.io/docs/concepts/overview/kubernetes-api/){: external}. Note that you cannot delete a job run without also deleting any associated pods. Any attempt to delete with the `propagationPolicy=Orphan` option is rejected. ### Function CRD methods {: #api-crd-function} You can use function CRDs when [Working with functions in Code Engine](https://cloud.ibm.com/docs/codeengine?topic=codeengine-fun-work&format=markdown). | Group | Version | Kind | | --------- | -------- | -------- | | `codeengine.cloud.ibm.com` | v1beta1 | `Function` | {: caption="Function CRDs for Code Engine" caption-side="bottom"} ### Serving CRD methods {: #api-crd-serving} You can use serving CRDs when [Working with applications in Code Engine](https://cloud.ibm.com/docs/codeengine?topic=codeengine-application-workloads&format=markdown). | Group | Version | Kind | | --------- | -------- | -------- | | `serving.knative.dev` | v1 | `Configuration` | | `serving.knative.dev` | v1 | `Revision` | | `serving.knative.dev` | v1 | `Route` | | `serving.knative.dev` | v1 | `Service` | {: caption="Serving CRDs for Code Engine" caption-side="bottom"} For more information about these CRDs, see [Knative Serving API Specification](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md){: external}. ### Source-to-image CRD methods {: #api-crd-s2i} You can use source-to-image CRDs when [Working with builds and build runs in Code Engine](https://cloud.ibm.com/docs/codeengine?topic=codeengine-plan-build&format=markdown). | Group | Version | Kind | | --------- | -------- | -------- | | `shipwright.io` | v1beta1 | `Build` | | `shipwright.io` | v1beta1 | `BuildRun` | {: caption="Source-to-image CRDs for Code Engine" caption-side="bottom"} After you retrieve the Kubernetes configuration, you can view the Source-to-image CRD details by using one of the following methods. - Use `kubectl explain --api-version='shipwright.io/v1beta1' `. - [Download the Swagger or `OpenAPI` specification of CRDs](https://kubernetes.io/docs/concepts/overview/kubernetes-api/){: external}. ### Subscription CRD methods {: #api-crd-subscription} You can use subscription CRDs when [Working with with subscriptions in Code Engine](https://cloud.ibm.com/docs/codeengine?topic=codeengine-subscribing-events&format=markdown). | Group | Version | Kind | | --------- | -------- | -------- | | `sources.codeengine.cloud.ibm.com` | v1alpha1 | `CosSource` | | `sources.knative.dev` | v1beta1 | `KafkaSource` | | `sources.knative.dev` | v1 | `PingSource` | {: caption="Subscription CRDs for Code Engine" caption-side="bottom"} After you retrieve the Kubernetes configuration, you can view the Subscription CRD details by using one of the following methods. - Use `kubectl explain --api-version='sources.knative.dev/' `. - [Download the Swagger or `OpenAPI` specification of CRDs](https://kubernetes.io/docs/concepts/overview/kubernetes-api/){: external}.