IBM Cloud API Docs

Introduction

IBM Cloud Code Engine provides a platform to unify the deployment of functions, applications, and pre-built containers to a Kubernetes-based infrastructure, enabling higher productivity and a faster time to market. Code Engine is built on open-source projects such as Kubernetes, Istio, Knative, and Tekton. For more information about custom resource definition methods that are available to use with Code Engine, see API reference.

The curl examples require a bearer token. You can retrieve a token with the following command.

ibmcloud iam oauth-tokens --output json

You can also use jq to get clean output.

token=`ibmcloud iam oauth-tokens --output json | jq .iam_token -r`

These code examples use the client library that is provided for Java.

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>code-engine</artifactId>
    <version>0.3.3</version>
</dependency>

GitHub

These code examples use the client library that is provided for Node.js.

Installation

npm install ibm-code-engine-sdk

GitHub

These code examples use the client library that is provided for Python.

Installation

pip install --upgrade "ibm-code-engine-sdk"

GitHub

These code examples use the client library that is provided for Go.

go get -u github.com/IBM/code-engine-go-sdk

GitHub

Authentication

You can create and manage Identity and Access Management (IAM)-based projects in Code Engine. IAM-based projects are created in resource groups and are managed with IAM access policies.

This API requires IBM Cloud Identity and Access Management (IAM) authentication. You can retrieve your IAM access token by running ibmcloud iam oauth-tokens. You must pass the IAM token in the Authorization header.

For specific information about using IAM with Code Engine APIs, see the API reference.

Endpoint URLs

The endpont URLs are based on the location of the service instance. For example, when Code Engine is hosted in Dallas, TX, the base URL is https://api.us-south.codeengine.cloud.ibm.com.

To find out which URL to use, view the service credentials by clicking the service instance in the Resource list. Use that URL in your requests to Code Engine.

All locations might not support Code Engine. For more information, see Regions.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

HTTP error code Description Recovery
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{project}'. Check that you have the correct access credentials and permissions.
404 Not Found The requested resource could not be found. Check that the namespace ID is correct and try again.
408 Request Timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
500 Internal Server Error IBM Cloud Code Engine is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Methods

Retrieve KUBECONFIG for a specified project.

Returns the KUBECONFIG, similar to the output of kubectl config view --minify=true. There are 2 tokens in the Request Header and a query parameter that you must provide. These values can be generated as follows:

  1. Auth Header Pass the generated IAM Token as the Authorization header from the CLI as token=cat $HOME/.bluemix/config.json | jq .IAMToken -r. Generate the token with the Create an IAM access token for a user or service ID using an API key API.

  2. X-Delegated-Refresh-Token Header Generate an IAM Delegated Refresh Token for Code Engine with the Create an IAM access token and delegated refresh token for a user or service ID API. Specify the receiver_client_ids value to be ce and the delegated_refresh_token_expiry value to be 3600.

  3. Project ID In order to retrieve the Kubeconfig file for a specific Code Engine project, use the CLI to extract the ID id=ibmcloud ce project get -n ${CE_PROJECT_NAME} -o jsonpath={.guid} You must be logged into the account where the project was created to retrieve the ID.

GET /project/{id}/config

Request

Custom Headers

Path Parameters

  • The id of the IBM Cloud Code Engine project

  • token=`cat $HOME/.bluemix/config.json | jq .IAMToken -r`
    refreshToken=`cat $HOME/.bluemix/config.json | jq .IAMRefreshToken -r`
    delegatedRefreshToken=$(curl -X POST 'https://iam.cloud.ibm.com/identity/token'   -H 'Content-Type: application/x-www-form-urlencoded'   -H 'Authorization: Basic Yng6Yng='   -d "grant_type=refresh_token&refresh_token=${refreshToken}&response_type=delegated_refresh_token&receiver_client_ids=ce&delegated_refresh_token_expiry=3600"  | jq .delegated_refresh_token -r)
    id=`ibmcloud ce project get -n ${CE_PROJECT_NAME} -o jsonpath={.guid}`
    curl -H "Authorization: ${token}" -H "X-Delegated-Refresh-Token: ${delegatedRefreshToken}"   https://api.${CE_PROJECT_REGION}.codeengine.cloud.ibm.com/api/v1/project/${id}/config"
  • IamAuthenticator authenticator = new IamAuthenticator(System.getenv("CE_API_KEY"));
    authenticator.setClientIdAndSecret("bx", "bx");
    
    IbmCloudCodeEngine ceClient = new IbmCloudCodeEngine("Code Engine Client", authenticator);
    ceClient.setServiceUrl("https://api." + System.getenv("CE_PROJECT_REGION") + ".codeengine.cloud.ibm.com/api/v1");
    
    URL iamUrl = new URL("https://iam.cloud.ibm.com/identity/token?"
      + "grant_type=urn:ibm:params:oauth:grant-type:apikey&"
      + "response_type=delegated_refresh_token&"
      + "receiver_client_ids=ce&"
      + "delegated_refresh_token_expiry=3600&"
      + "apikey="
      + System.getenv("CE_API_KEY"));
    HttpURLConnection iamConnection = (HttpURLConnection) iamUrl.openConnection();
    iamConnection.setRequestMethod("POST");
    iamConnection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
    BufferedReader iamInput = new BufferedReader(new InputStreamReader(iamConnection.getInputStream()));
    String iamResponse = "";
    String iamInputLine = "";
    while ((iamInputLine = iamInput.readLine()) != null) {
      iamResponse = iamResponse + iamInputLine;
    }
    iamInput.close();
    JSONObject iamJson = new JSONObject(iamResponse);
    String delegatedRefreshToken = iamJson.getString("delegated_refresh_token");
    
    GetKubeconfigOptions options = new GetKubeconfigOptions.Builder()
      .id(System.getenv("CE_PROJECT_ID"))
      .xDelegatedRefreshToken(delegatedRefreshToken)
      .build();
    
    Response<String> kubeConfigResponse = ceClient.getKubeconfig(options).execute();
    String kubeConfigString = kubeConfigResponse.getResult();
    
  • const authenticator = new IamAuthenticator({
      apikey: process.env.CE_API_KEY,
      clientId: 'bx',
      clientSecret: 'bx',
    });
    
    const ceClient = new CodeEngineV1({
      authenticator,
      serviceUrl: `https://api.${process.env.CE_PROJECT_REGION}.codeengine.cloud.ibm.com/api/v1`,
    });
    
    const iamResponse = await axios.post('https://iam.cloud.ibm.com/identity/token', querystring.stringify({
      grant_type: 'urn:ibm:params:oauth:grant-type:apikey',
      apikey: process.env.CE_API_KEY,
      response_type: 'delegated_refresh_token',
      receiver_client_ids: 'ce',
      delegated_refresh_token_expiry: '3600'
    }), {
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      }
    })
    const delegatedRefreshToken = iamResponse.data.delegated_refresh_token;
    
    const configResponse = await ceClient.getKubeconfig({
      xDelegatedRefreshToken: delegatedRefreshToken,
      id: process.env.CE_PROJECT_ID,
    });
    
  • authenticator = IAMAuthenticator(
        apikey=os.environ.get('CE_API_KEY'),
        client_id='bx',
        client_secret='bx',
    )
    
    ce_client = IbmCloudCodeEngineV1(authenticator=authenticator)
    ce_client.set_service_url(
        'https://api.' + os.environ.get('CE_PROJECT_REGION') + '.codeengine.cloud.ibm.com/api/v1'
    )
    
    iam_response = requests.post('https://iam.cloud.ibm.com/identity/token', headers={
        'Content-Type': 'application/x-www-form-urlencoded'
    }, data={
        'grant_type': 'urn:ibm:params:oauth:grant-type:apikey',
        'apikey': os.environ.get('CE_API_KEY'),
        'response_type': 'delegated_refresh_token',
        'receiver_client_ids': 'ce',
        'delegated_refresh_token_expiry': '3600'
    })
    delegated_refresh_token = iam_response.json()['delegated_refresh_token']
    
    kubeconfig_response = ce_client.get_kubeconfig(
        x_delegated_refresh_token=delegated_refresh_token,
        id=os.environ.get('CE_PROJECT_ID'),
    )
    kubeconfig_string = kubeconfig_response.get_result().content
    
  • authenticator := &core.IamAuthenticator{
      ApiKey:       os.Getenv("CE_API_KEY"),
      ClientId:     "bx",
      ClientSecret: "bx",
    }
    
    ceClient, _ := ibmcloudcodeenginev1.NewIbmCloudCodeEngineV1(&ibmcloudcodeenginev1.IbmCloudCodeEngineV1Options{
      Authenticator: authenticator,
      URL:           "https://api." + os.Getenv("CE_PROJECT_REGION") + ".codeengine.cloud.ibm.com/api/v1",
    })
    
    iamRequestData := url.Values{}
    iamRequestData.Set("grant_type", "urn:ibm:params:oauth:grant-type:apikey")
    iamRequestData.Set("apikey", os.Getenv("CE_API_KEY"))
    iamRequestData.Set("response_type", "delegated_refresh_token")
    iamRequestData.Set("receiver_client_ids", "ce")
    iamRequestData.Set("delegated_refresh_token_expiry", "3600")
    client := &http.Client{}
    req, _ := http.NewRequest("POST", "https://iam.cloud.ibm.com/identity/token", strings.NewReader(iamRequestData.Encode()))
    req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
    resp, _ := client.Do(req)
    var iamResponseData map[string]string
    json.NewDecoder(resp.Body).Decode(&iamResponseData)
    delegatedRefreshToken := iamResponseData["delegated_refresh_token"]
    
    projectID := os.Getenv("CE_PROJECT_ID")
    result, _, _ := ceClient.GetKubeconfig(&ibmcloudcodeenginev1.GetKubeconfigOptions{
      XDelegatedRefreshToken: &delegatedRefreshToken,
      ID:           &projectID,
    })
    

Response

Status Code

  • Success. The returned content is the KUBECONFIG information to use for the specific IBM Cloud Code Engine project. The returned value must be stored in a .yaml file and exported as export KUBECONFIG=<path to the .yaml file> for use.

  • Bad request

  • Unauthorized

  • Unauthorized access

  • Internal Server Error

Example responses
  • apiVersion: v1
    clusters:
    - cluster:
        server: https://proxy.us-south.codeengine.cloud.ibm.com
      name: https://proxy.us-south.codeengine.cloud.ibm.com
    contexts:
    - context:
        cluster: https://proxy.us-south.codeengine.cloud.ibm.com
        namespace: some-namespace
        user: some-namespace
      name: some-namespace
    current-context: some-namespace
    kind: Config
    preferences: {}
    users:
    - name: some-namespace
      user:
        auth-provider:
          config:
            client-id: ce
            client-secret: ce
            id-token: a.b.c
            idp-issuer-url: https://iam.cloud.ibm.com/identity
            refresh-token: c.d.e
          name: oidc