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:
-
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. -
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 bece
and thedelegated_refresh_token_expiry
value to be3600
. -
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
This IAM Delegated Refresh Token is specifically valid for Code Engine. Generate this token 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 bece
and thedelegated_refresh_token_expiry
value to be3600
Allowable values: [
text/plain
,application/json
]
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
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