Setting up the API

Red Hat OpenShift on IBM Cloud shares the same application programming interface (API) as IBM Cloud Kubernetes Service, so that you can use the same methods to consistently create and manage your community Kubernetes or OpenShift clusters. To use the CLI, see Setting up the CLI.

About the API

The Red Hat OpenShift on IBM Cloud API automates the provisioning and management of IBM Cloud infrastructure resources for your clusters so that your apps have the compute, networking, and storage resources that they need to serve your users.

The API is versioned to support the different infrastructure providers that are available for you to create clusters. For more information, see Overview of Classic and VPC infrastructure providers.

You can use the version two (v2) API to manage both classic and VPC clusters. The v2 API is designed to avoid breaking existing functionality when possible. However, make sure that you review the following differences between the v1 and v2 API.

Scroll for moreScroll for more

Area	v1 API	v2 API
API endpoint prefix	https://containers.cloud.ibm.com/global/v1	https://containers.cloud.ibm.com/global/v2
API reference docs	https://containers.cloud.ibm.com/global/swagger-global-api/	https://containers.cloud.ibm.com/global/swagger-global-api/
API architectural style	Representational state transfer (REST) that focuses on resources that you interact with through HTTP methods such as GET, POST, PUT, PATCH, and DELETE.	Remote procedure calls (RPC) that focus on actions through only GET and POST HTTP methods.
Supported container platforms	Use the Red Hat OpenShift on IBM Cloud API to manage your IBM Cloud infrastructure resources, such as worker nodes, for both community Kubernetes and OpenShift clusters.	Use the Red Hat OpenShift on IBM Cloud v2 API to manage your IBM Cloud infrastructure resources, such as worker nodes, for both community Kubernetes and OpenShift VPC clusters.
Kubernetes API	To use the Kubernetes API to manage Kubernetes resources within the cluster, such as pods or namespaces, see Working with your cluster by using the Kubernetes API.	Same as v1; see Working with your cluster by using the Kubernetes API.
Supported infrastructure providers	classic	vpc and classic The vpc provider is designed to support multiple VPC subproviders. The supported VPC subprovider s are vpc-classic, which corresponds to a VPC cluster for Generation 1 compute resources, and is vpc-gen2, which corresponds to a VPC cluster for Generation 2 compute resources. Provider-specific requests have a path parameter in the URL, such as v2/vpc/createCluster. Some APIs are only available to a particular provider, such as GET vlan for classic or GET vpcs for VPC. Provider-neutral requests can include a provider-specific body parameter that you specify, usually in JSON, such as {"provider": "vpc"}, if we want to return responses for only the specified provider.
GET responses	The GET method for a collection of resources (such as GET v1/clusters) returns the same details for each resource in the list as a GET method for an individual resource (such as GET v1/clusters/{idOrName}).	To return responses faster, the v2 GET method for a collection of resources (such as GET v2/clusters) returns only a subset of information that is detailed in a GET method for an individual resource (such as GET v2/clusters/{idOrName}). Some list responses include a providers property to identify whether the returned item applies to classic or VPC infrastructure. For example, the GET zones list returns some results such as mon01 that are available only in the classic infrastructure provider, while other results such as us-south-01 are available only in the VPC infrastructure provider.
Cluster, worker node, and worker-pool responses	Responses include only information that is specific to the classic infrastructure provider, such as the VLANs in GET cluster and worker responses.	The information that is returned varies depending on the infrastructure provider. For such provider-specific responses, you can specify the provider in your request. For example, VPC clusters do not return VLAN information since they do not have VLANs. Instead, they return subnet and CIDR network information.

Automating cluster deployments with the API

You can use the Red Hat OpenShift on IBM Cloud API to automate the creation, deployment, and management of your OpenShift clusters.

The Red Hat OpenShift on IBM Cloud API requires header information that we must provide in your API request and that can vary depending on the API that we want to use. To determine what header information is needed for your API, see the Red Hat OpenShift on IBM Cloud API documentation.

To authenticate with Red Hat OpenShift on IBM Cloud, we must provide an IBM Cloud Identity and Access Management (IAM) token that is generated with your IBM Cloud credentials and that includes the IBM Cloud account ID where the cluster was created. Depending on the way you authenticate with IBM Cloud, you can choose between the following options to automate the creation of your IBM Cloud IAM token.

You can also use the API swagger JSON file to generate a client that can interact with the API as part of your automation work.

IBM Cloud ID My options

Unfederated ID

Generate an IBM Cloud API key: As an alternative to using the IBM Cloud username and password, you can use IBM Cloud API keys. IBM Cloud API keys are dependent on the IBM Cloud account they are generated for. You cannot combine your IBM Cloud API key with a different account ID in the same IBM Cloud IAM token. To access clusters that were created with an account other than the one your IBM Cloud API key is based on, we must log in to the account to generate a new API key.
IBM Cloud username and password: You can follow the steps in this topic to fully automate the creation of your IBM Cloud IAM access token.

Federated ID

Generate an IBM Cloud API key: IBM Cloud API keys are dependent on the IBM Cloud account they are generated for. You cannot combine your IBM Cloud API key with a different account ID in the same IBM Cloud IAM token. To access clusters that were created with an account other than the one your IBM Cloud API key is based on, we must log in to the account to generate a new API key.
Use a one-time passcode: If you authenticate with IBM Cloud by using a one-time passcode, you cannot fully automate the creation of your IBM Cloud IAM token because the retrieval of your one-time passcode requires a manual interaction with your web browser. To fully automate the creation of your IBM Cloud IAM token, we must create an IBM Cloud API key instead.

IBM Cloud ID	My options
Unfederated ID	Generate an IBM Cloud API key: As an alternative to using the IBM Cloud username and password, you can use IBM Cloud API keys. IBM Cloud API keys are dependent on the IBM Cloud account they are generated for. You cannot combine your IBM Cloud API key with a different account ID in the same IBM Cloud IAM token. To access clusters that were created with an account other than the one your IBM Cloud API key is based on, we must log in to the account to generate a new API key. IBM Cloud username and password: You can follow the steps in this topic to fully automate the creation of your IBM Cloud IAM access token.
Federated ID	Generate an IBM Cloud API key: IBM Cloud API keys are dependent on the IBM Cloud account they are generated for. You cannot combine your IBM Cloud API key with a different account ID in the same IBM Cloud IAM token. To access clusters that were created with an account other than the one your IBM Cloud API key is based on, we must log in to the account to generate a new API key. Use a one-time passcode: If you authenticate with IBM Cloud by using a one-time passcode, you cannot fully automate the creation of your IBM Cloud IAM token because the retrieval of your one-time passcode requires a manual interaction with your web browser. To fully automate the creation of your IBM Cloud IAM token, we must create an IBM Cloud API key instead.

Create your IBM Cloud IAM access token. The body information that is included in your request varies based on the IBM Cloud authentication method that you use.

POST https://iam.cloud.ibm.com/identity/token

Scroll for moreScroll for more

Input parameters	Values
Header	Content-Type: application/x-www-form-urlencoded Authorization: Basic Yng6Yng= Note: Yng6Yng= equals the URL-encoded authorization for the username bx and the password bx.
Body for IBM Cloud username and password	grant_type: password response_type: cloud_iam uaa username: Your IBM Cloud username. password: Your IBM Cloud password. uaa_client_id: cf uaa_client_secret: Note: Add the uaa_client_secret key with no value specified.
Body for IBM Cloud API keys	grant_type: urn:ibm:params:oauth:grant-type:apikey response_type: cloud_iam uaa apikey: Your IBM Cloud API key uaa_client_id: cf uaa_client_secret: Note: Add the uaa_client_secret key with no value specified.
Body for IBM Cloud one-time passcode	grant_type: urn:ibm:params:oauth:grant-type:passcode response_type: cloud_iam uaa passcode: Your IBM Cloud one-time passcode. Run ibmcloud login --sso and follow the instructions in your CLI output to retrieve your one-time passcode by using your web browser. uaa_client_id: cf uaa_client_secret: Note: Add the uaa_client_secret key with no value specified.

Example output for using an API key:

{
"access_token": "<iam_access_token>",
"refresh_token": "<iam_refresh_token>",
"uaa_token": "<uaa_token>",
"uaa_refresh_token": "<uaa_refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1493747503
"scope": "ibm openid"
}

You can find the IBM Cloud IAM token in the access_token field of your API output. Note the IBM Cloud IAM token to retrieve additional header information in the next steps.

Retrieve the ID of the IBM Cloud account that we want to work with. Replace <iam_access_token> with the IBM Cloud IAM token that you retrieved from the access_token field of your API output in the previous step. In your API output, you can find the ID of your IBM Cloud account in the resources.metadata.guid field.

GET https://accounts.cloud.ibm.com/coe/v2/accounts

Input parameters	Values
Headers	Content-Type: application/json Authorization: bearer <iam_access_token> Accept: application/json

Example output:

{
"next_url": null,
"total_results": 5,
"resources": [
    {
        "metadata": {
   "guid": "<account_ID>",
   "url": "/coe/v2/accounts/<account_ID>",
   "created_at": "2016-09-29T02:49:41.842Z",
   "updated_at": "2018-08-16T18:56:00.442Z",
   "anonymousId": "1111a1aa1a1111a1aa11aa11111a1111"
        },
        "entity": {
   "name": "<account_name>",
...

Generate a new IBM Cloud IAM token that includes your IBM Cloud credentials and the account ID that we want to work with.

If you use an IBM Cloud API key, we must use the IBM Cloud account ID the API key was created for. To access clusters in other accounts, log into this account and create an IBM Cloud API key that is based on this account.

POST https://iam.cloud.ibm.com/identity/token

Scroll for moreScroll for more

Input parameters	Values
Header	Content-Type: application/x-www-form-urlencoded Authorization: Basic Yng6Yng= Note: Yng6Yng= equals the URL-encoded authorization for the username bx and the password bx.
Body for IBM Cloud username and password	grant_type: password response_type: cloud_iam uaa username: Your IBM Cloud username. password: Your IBM Cloud password. uaa_client_ID: cf uaa_client_secret: Note: Add the uaa_client_secret key with no value specified. bss_account: The IBM Cloud account ID that you retrieved in the previous step.
Body for IBM Cloud API keys	grant_type: urn:ibm:params:oauth:grant-type:apikey response_type: cloud_iam uaa apikey: Your IBM Cloud API key. uaa_client_ID: cf uaa_client_secret: Note: Add the uaa_client_secret key with no value specified. bss_account: The IBM Cloud account ID that you retrieved in the previous step.
Body for IBM Cloud one-time passcode	grant_type: urn:ibm:params:oauth:grant-type:passcode response_type: cloud_iam uaa passcode: Your IBM Cloud passcode. uaa_client_ID: cf uaa_client_secret: Note: Add the uaa_client_secret key with no value specified. bss_account: The IBM Cloud account ID that you retrieved in the previous step.

Example output:

{
  "access_token": "<iam_token>",
  "refresh_token": "<iam_refresh_token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expiration": 1493747503
}

You can find the IBM Cloud IAM token in the access_token and the refresh token in the refresh_token field of your API output.

List available Red Hat OpenShift on IBM Cloud regions and select the region that we want to work in. Use the IAM access token and refresh token from the previous step to build your header information.

GET https://containers.cloud.ibm.com/v1/regions

Input parameters	Values
Header	Authorization: bearer <iam_token> X-Auth-Refresh-Token: <refresh_token>

Example output:

{
"regions": [
    {
        "name": "ap-north",
        "alias": "jp-tok",
        "cfURL": "api.au-syd.bluemix.net",
        "freeEnabled": false
    },
    {
        "name": "ap-south",
        "alias": "au-syd",
        "cfURL": "api.au-syd.bluemix.net",
        "freeEnabled": true
    },
    {
        "name": "eu-central",
        "alias": "eu-de",
        "cfURL": "api.eu-de.bluemix.net",
        "freeEnabled": true
    },
    {
        "name": "uk-south",
        "alias": "eu-gb",
        "cfURL": "api.eu-gb.bluemix.net",
        "freeEnabled": true
    },
    {
        "name": "us-east",
        "alias": "us-east",
        "cfURL": "api.ng.bluemix.net",
        "freeEnabled": false
    },
    {
        "name": "us-south",
        "alias": "us-south",
        "cfURL": "api.ng.bluemix.net",
        "freeEnabled": true
    }
]
}

List all clusters in the Red Hat OpenShift on IBM Cloud region that you selected. If we want to run Kubernetes API requests against your cluster, make sure to note the id and region of your cluster.

 GET https://containers.cloud.ibm.com/v1/clusters

Input parameters	Values
Header	Authorization: bearer <iam_token> X-Auth-Refresh-Token: <refresh_token> X-Region: <region>

Review the Red Hat OpenShift on IBM Cloud API documentation to find a list of supported APIs.

When you use the API for automation, be sure to rely on the responses from the API, not files within those responses. For example, the Kubernetes configuration file for your cluster context is subject to change, so do not build automation based on specific contents of this file when you use the GET /v1/clusters/{idOrName}/config call.

Working with your cluster by using the Kubernetes API

You can use the Kubernetes API to interact with your cluster in Red Hat OpenShift on IBM Cloud. For authentication details, see IBM Cloud IAM issuer details for RBAC users.

The following instructions require public network access in your cluster to connect to the public service endpoint of your Kubernetes master.

Follow the steps in Automating cluster deployments with the API to retrieve your IBM Cloud IAM access token, refresh token, the ID of the cluster where we want to run Kubernetes API requests, and the Red Hat OpenShift on IBM Cloud region where your cluster is located.

Retrieve an IBM Cloud IAM delegated refresh token.

POST https://iam.cloud.ibm.com/identity/token

Scroll for moreScroll for more

Input parameters	Values
Header	Content-Type: application/x-www-form-urlencoded Authorization: Basic Yng6Yng= Note: Yng6Yng= equals the URL-encoded authorization for the username bx and the password bx. cache-control: no-cache
Body	delegated_refresh_token_expiry: 600 receiver_client_ids: kube response_type: delegated_refresh_token refresh_token: Your IBM Cloud IAM refresh token. grant_type: refresh_token

Example output:

{
 "delegated_refresh_token": <delegated_refresh_token>
}

Retrieve an IBM Cloud IAM ID, IAM access, and IAM refresh token by using the delegated refresh token from the previous step. In your API output, you can find the IAM ID token in the id_token field, the IAM access token in the access_token field, and the IAM refresh token in the refresh_token field.

POST https://iam.cloud.ibm.com/identity/token

Scroll for moreScroll for more

Input parameters	Values
Header	Content-Type: application/x-www-form-urlencoded Authorization: Basic a3ViZTprdWJl Note: a3ViZTprdWJl equals the URL-encoded authorization for the username kube and the password kube. cache-control: no-cache
Body	refresh_token: Your IBM Cloud IAM delegated refresh token. grant_type: urn:ibm:params:oauth:grant-type:delegated-refresh-token

Example output:

{
 "access_token": "<iam_access_token>",
 "id_token": "<iam_id_token>",
 "refresh_token": "<iam_refresh_token>",
 "token_type": "Bearer",
 "expires_in": 3600,
 "expiration": 1553629664,
 "scope": "ibm openid containers-kubernetes"
}

Retrieve the public URL of your Kubernetes master by using the IAM access token, the IAM ID token, the IAM refresh token, and the Red Hat OpenShift on IBM Cloud region that your cluster is in. You can find the URL in the publicServiceEndpointURL of your API output.

GET https://containers.cloud.ibm.com/v1/clusters/<cluster_ID>

Scroll for moreScroll for more

Input parameters	Values
Header	Authorization: Your IBM Cloud IAM access token. X-Auth-Refresh-Token: Your IBM Cloud IAM refresh token. X-Region: The Red Hat OpenShift on IBM Cloud region of your cluster that you retrieved with the GET https://containers.cloud.ibm.com/v1/clusters API in Automating cluster deployments with the API.
Path	<cluster_ID>: The ID of your cluster that you retrieved with the GET https://containers.cloud.ibm.com/v1/clusters API in Automating cluster deployments with the API.

Example output:

{
 "location": "Dallas",
 "dataCenter": "dal10",
 "multiAzCapable": true,
 "vlans": null,
 "worker_vlans": null,
 "workerZones": [
     "dal10"
 ],
 "id": "1abc123b123b124ab1234a1a12a12a12",
 "name": "mycluster",
 "region": "us-south",
 ...
 "publicServiceEndpointURL": "https://c7.us-south.containers.cloud.ibm.com:27078"
}

Run Kubernetes API requests against your cluster by using the IAM ID token that you retrieved earlier. For example, list the Kubernetes version that runs in your cluster.

If you enabled SSL certificate verification in your API test framework, make sure to disable this feature.

GET <publicServiceEndpointURL>/version

Scroll for moreScroll for more

Input parameters	Values
Header	Authorization: bearer <id_token>
Path	<publicServiceEndpointURL>: The publicServiceEndpointURL of your Kubernetes master that you retrieved in the previous step.

Example output:

{
 "major": "1",
 "minor": "1.18.9",
 "gitVersion": "v1.18.9+IKS",
 "gitCommit": "c35166bd86eaa91d17af1c08289ffeab3e71e11e",
 "gitTreeState": "clean",
 "buildDate": "2019-03-21T10:08:03Z",
 "goVersion": "go1.11.5",
 "compiler": "gc",
 "platform": "linux/amd64"
}

Review the Kubernetes API documentation to find a list of supported APIs for the latest Kubernetes version. Make sure to use the API documentation that matches the Kubernetes version of your cluster. If you do not use the latest Kubernetes version, append your version at the end of the URL. For example, to access the API documentation for version 1.12, add v1.12.

Refreshing IBM Cloud IAM access tokens and obtaining new refresh tokens with the API

Every IBM Cloud Identity and Access Management (IAM) access token that is issued via the API expires after one hour. You must refresh your access token regularly to assure access to the IBM Cloud API. You can use the same steps to obtain a new refresh token.

Before beginning, make sure that we have an IBM Cloud IAM refresh token or an IBM Cloud API key that you can use to request a new access token.

Refresh token: Follow the instructions in Automating the cluster creation and management process with the IBM Cloud API.
API key: Retrieve your IBM Cloud API key as follows.
1. From the menu bar, click Manage > Access (IAM).
2. Click the Users page and then select yourself.
3. In the API keys pane, click Create an IBM Cloud API key.
4. Enter a Name and Description for your API key and click Create.
5. Click Show to see the API key that was generated for you.
6. Copy the API key so that you can use it to retrieve your new IBM Cloud IAM access token.

Use the following steps if we want to create an IBM Cloud IAM token or if we want to obtain a new refresh token.

Generate a new IBM Cloud IAM access token by using the refresh token or the IBM Cloud API key.

POST https://iam.cloud.ibm.com/identity/token

Scroll for moreScroll for more

Input parameters	Values
Header	Content-Type: application/x-www-form-urlencoded Authorization: Basic Yng6Yng= Note: Yng6Yng= equals the URL-encoded authorization for the username bx and the password bx.
Body when using the refresh token	grant_type: refresh_token response_type: cloud_iam uaa refresh_token: Your IBM Cloud IAM refresh token. uaa_client_ID: cf uaa_client_secret: bss_account: Your IBM Cloud account ID. Note: Add the uaa_client_secret key with no value specified.
Body when using the IBM Cloud API key	grant_type: urn:ibm:params:oauth:grant-type:apikey response_type: cloud_iam uaa apikey: Your IBM Cloud API key. uaa_client_ID: cf uaa_client_secret: Note: Add the uaa_client_secret key with no value specified.

Example API output:

{
  "access_token": "<iam_token>",
  "refresh_token": "<iam_refresh_token>",
  "uaa_token": "<uaa_token>",
  "uaa_refresh_token": "<uaa_refresh_token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expiration": 1493747503
}

You can find your new IBM Cloud IAM token in the access_token, and the refresh token in the refresh_token field of your API output.

Continue working with the Red Hat OpenShift on IBM Cloud API documentation by using the token from the previous step.

Refreshing IBM Cloud IAM access tokens and obtaining new refresh tokens with the CLI

When you start a new CLI session, or if 24 hours has expired in your current CLI session, we must set the context for your cluster by running ibmcloud oc cluster config --cluster <cluster_name>. When you set the context for your cluster with this command, the kubeconfig file for your OpenShift cluster is downloaded. Additionally, an IBM Cloud Identity and Access Management (IAM) ID token and a refresh token are issued to provide authentication.

ID token: Every IAM ID token that is issued via the CLI expires after one hour. When the ID token expires, the refresh token is sent to the token provider to refresh the ID token. Your authentication is refreshed, and you can continue to run commands against your cluster.

Refresh token: Refresh tokens expire every 30 days. If the refresh token is expired, the ID token cannot be refreshed, and we are not able to continue running commands in the CLI. You can get a new refresh token by running ibmcloud oc cluster config --cluster <cluster_name>. This command also refreshes your ID token.