×

 
The OpenShift Enterprise distribution of Kubernetes includes the Kubernetes v1 REST API and the OpenShift v1 REST API. These are RESTful APIs accessible via HTTP(s) on the OpenShift Enterprise master servers.

These REST APIs can be used to manage end-user applications, the cluster, and the users of the cluster.

Authentication

API calls must be authenticated with an access token or X.509 certificate. See Authentication in the Architecture documentation for an overview.

This section highlights the token authentication method. With token authentication, a bearer token must be passed in as an HTTP Authorization header. There are two types of access tokens: session and service account.

Session Tokens

A session token is short-lived, expiring within 24 hours by default. It represents a user. After logging in, the session token may be obtained with the oc whoami command:

$ oc login -u test_user
Using project "test".
$ oc whoami -t
dIAo76N-W-GXK3S_w_KsC6DmH3MzP79zq7jbMQvCOUo

Service Account Tokens

Service account tokens are long-lived tokens. They are JSON Web Token (JWT) formatted tokens and are much longer strings than session tokens. See Using a Service Account’s Credentials Externally for steps on using these tokens to authenticate using the CLI.

A service account token may be obtained with these commands:

  1. Create a service account in the current project (test) named robot:

    $ oc create serviceaccount robot
    serviceaccount "robot" created
  2. Grant a role to the service account. In this example, assign the robot service account in the test project the admin role:

    $ oc policy add-role-to-user admin system:serviceaccounts:test:robot
  3. Describe the service account to discover the secret token name:

    $ oc describe serviceaccount robot
    Name:		robot
    Namespace:	test
    Labels:		<none>
    
    Image pull secrets:	robot-dockercfg-rdrpg
    
    Mountable secrets: 	robot-token-2dsne
                       	robot-dockercfg-rdrpg
    
    Tokens:            	robot-token-2dsne
                       	robot-token-9efwm
  4. Describe the secret token to get the token value:

    $  oc describe secret robot-token-2dsne
    Name:		robot-token-2dsne
    Namespace:	test
    Labels:		<none>
    Annotations:	kubernetes.io/service-account.name=robot,kubernetes.io/service-account.uid=ea70e4c7-0663-11e6-b279-fa163e610e01
    
    Type:	kubernetes.io/service-account-token
    
    Data
    ===
    token:		fyJhbGciOiJSUzI1NiIyInR5cCI2IkpXVCJ9...
    ca.crt:		1070 bytes
    namespace:	8 bytes

The token value may be used as an in an authorization header to authenticate API calls, the CLI or in the docker login command. Service accounts may be created and deleted as needed with the appropriate role(s) assigned. See Authorization in the Architecture documentation for a deeper discussion on roles.

Examples

These examples are provided as a reference to provide quick success making REST API calls. They use insecure methods. In these examples a simple GET call is made to list available resources.

cURL

Example 1. Request (Insecure)
$ curl -X GET -H "Authorization: Bearer <token>" https://openshift.redhat.com:8443/oapi/v1 --insecure
Example 2. Result (Truncated)
{
  "kind": "APIResourceList",
  "groupVersion": "v1",
  "resources": [
    {
      "name": "buildconfigs",
      "namespaced": true,
      "kind": "BuildConfig"
    },
    {
      "name": "buildconfigs/instantiate",
      "namespaced": true,
      "kind": "BuildRequest"
    },
    {
      "name": "buildconfigs/instantiatebinary",
      "namespaced": true,
      "kind": "BinaryBuildRequestOptions"
    },
    {
      "name": "buildconfigs/webhooks",
      "namespaced": true,
      "kind": "Status"
    },
    {
      "name": "builds",
      "namespaced": true,
      "kind": "Build"
    },
    ...
    {
      "name": "subjectaccessreviews",
      "namespaced": true,
      "kind": "SubjectAccessReview"
    },
    {
      "name": "templates",
      "namespaced": true,
      "kind": "Template"
    },
    {
      "name": "useridentitymappings",
      "namespaced": false,
      "kind": "UserIdentityMapping"
    },
    {
      "name": "users",
      "namespaced": false,
      "kind": "User"
    }
  ]
}

Python

Example 3. Interactive Python API Call Using "requests" Module (Insecure)
>>> import requests
>>> url = 'https://openshift.redhat.com:8443/oapi/v1'
>>> headers = {'Authorization': 'Bearer dIAo76N-W-GXK3S_w_KsC6DmH3MzP79zq7jbMQvCOUo'}
>>> requests.get(url, headers=headers, verify=False)
/usr/lib/python2.7/site-packages/requests/packages/urllib3/connectionpool.py:791: InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.org/en/latest/security.html
  InsecureRequestWarning)
<Response [200]>

Docker Login

The OpenShift Enterprise integrated Docker registry must be authenticated using either a user session or service account token. The value of the token must be used as the value for the --password argument. The user and email argument values are ignored:

$ docker login -p <token_value> -u unused -e unused <registry>[:<port>]

Websockets and Watching for Changes

The API is designed to work via the websocket protocol. API requests may take the form of "one-shot" calls to list resources or by passing in query parameter watch=true. When watching an endpoint, changes to the system may be observed through an open endpoint. Using callbacks, dynamic systems may be developed that integrate with the API.

For more information and examples, see the Mozilla Developer Network page on Writing WebSocket client applications.