Using Kubernetes with Code Engine

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.

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

To install the Kubernetes CLI, download and install the kubectl CLI.

Be sure to add the kubectl binary to your system's PATH environment variable.

Interacting with Kubernetes API

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 and the project must be in active status.
Install the Kubernetes CLI (kubectl) and the Knative CLI (kn).

You can set up your environment in the following ways.

You can add the --kubecfg option to your project select command. For example,
```
ibmcloud ce project select --name PROJECT_NAME --kubecfg
```

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,

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

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.

kubectl config current-context

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.

Required access authorities to work with Kubernetes 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.

Table 1. Kubernetes authorities
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

Retrieving your Kubernetes configuration

You can retrieve your Kubernetes configuration with the REST API or the Code Engine CLI.

Retrieve your Kubernetes configuration with REST API

To retrieve your Kubernetes configuration with REST API,

Authenticate with IBM Cloud® Identity and Access Management (IAM) to receive an IAM access token.
Query the IBM Cloud catalog and the IBM Cloud Resource controller to receive a GUID for your project.
Use the IBM Cloud Code Engine API to receive a Kubernetes configuration.

Authenticate with Cloud Identity and Access Management

Create your IBM Cloud IAM access token by making a POST request to https://iam.cloud.ibm.com/identity/token.

Determine the GUID of your Code Engine project

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.

Log in into IBM Cloud and target a region, account, and resource group.
```
ibmcloud login target -r REGION -c ACCOUNT_ID -g RESOURCE_GROUP
```

Run the ibmcloud resource command.

ibmcloud resource service-instances --service-name codeengine --long

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.

Use the following IBM Cloud catalog API method: Returns parent catalog entries.

Example output
```
curl -X GET \
  'https://globalcatalog.cloud.ibm.com/api/v1?include=*&q=name:codeengine+active:true' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```
Identify the unique resource ID in the resources list. The field name is ID and the JSON path is resources[].id.
Query the IBM Cloud Resource controller with the IBM Cloud Resource controller API method Get a list of all resource instances. 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
```
curl -X GET \
    'https://resource-controller.cloud.ibm.com/v2/resource_instances?name=MY_PROJECT&resource_id=RESOURCE_ID' \
    -H 'Authorization: Bearer ACCESS_TOKEN'
```
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

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 Code Engine API method to get the Kubernetes configuration.

Example output

curl -X GET \
    'https://resource-controller.cloud.ibm.com/v2/resource_instances?name=MY_PROJECT&resource_id=RESOURCE_ID' \
    -H 'Authorization: Bearer ACCESS_TOKEN'

Retrieve your Kubernetes configuration with the Code Engine CLI

Log in into IBM Cloud and target a region, account, and resource group.
```
ibmcloud login target -r REGION -c ACCOUNT_ID -g RESOURCE_GROUP
```

Create your Code Engine project:

ibmcloud ce project create --name PROJECT

Select your Code Engine project as the current context and append the project to the default Kubernetes configuration file.
```
ibmcloud ce project select --name PROJECT --kubecfg
```

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,

Custom resource definition (CRD)

The following sections list the custom resource definition methods to use with Code Engine.

Batch CRD methods

You can use batch CRDs when Working with jobs and job runs in Code Engine.

Batch CRDs for Code Engine
Group	Version	Kind
`codeengine.cloud.ibm.com`	v1beta1	`JobDefinition`
`codeengine.cloud.ibm.com`	v1beta1	`JobRun`

After you retrieve the Kubernetes configuration, you can view Batch CRD details by using the following methods.

Use kubectl explain --api-version='codeengine.cloud.ibm.com/v1beta1' <Kind>.
Download Swagger or OpenAPI specification of CRDs.

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

You can use function CRDs when Working with functions in Code Engine.

Function CRDs for Code Engine
Group	Version	Kind
`codeengine.cloud.ibm.com`	v1beta1	`Function`

Serving CRD methods

You can use serving CRDs when Working with applications in Code Engine.

Serving CRDs for Code Engine
Group	Version	Kind
`serving.knative.dev`	v1	`Configuration`
`serving.knative.dev`	v1	`Revision`
`serving.knative.dev`	v1	`Route`
`serving.knative.dev`	v1	`Service`

For more information about these CRDs, see Knative Serving API Specification.

Source-to-image CRD methods

You can use source-to-image CRDs when Working with builds and build runs in Code Engine.

Source-to-image CRDs for Code Engine
Group	Version	Kind
`shipwright.io`	v1beta1	`Build`
`shipwright.io`	v1beta1	`BuildRun`

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' <KIND>.
Download the Swagger or OpenAPI specification of CRDs.

Subscription CRD methods

You can use subscription CRDs when Working with with subscriptions in Code Engine.

Subscription CRDs for Code Engine
Group	Version	Kind
`sources.codeengine.cloud.ibm.com`	v1alpha1	`CosSource`
`sources.knative.dev`	v1beta1	`KafkaSource`
`sources.knative.dev`	v1	`PingSource`

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/<VERSION>' <KIND>.
Download the Swagger or OpenAPI specification of CRDs.