Overview

    You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see

    The OKD 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 OKD master servers.

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

    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 . There are two types of access tokens: session and service account.

    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 command:

    A service account token may be obtained with these commands:

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

      1. $ oc create serviceaccount robot
      2. 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:

    3. Get the token value:

      1. $ oc serviceaccounts get-token robot
      2. eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJpc3YtY2VydCIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJpbWctYnVpbGQtdG9rZW4teG1rMHciLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoiaW1nLWJ1aWxkIiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiYTJmNzM0NWMtNDA4Zi0xMWU3LTg1NTktMDAxYTRhZTBkZjQ1Iiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50Omlzdi1jZXJ0OmltZy1idWlsZCJ9.Xt5cc9k7fucc7ZAYqt6cz6WvyDhbCZcfHXH-Ow6vStI4Gy7dS3qxIewcXFw8-h1_wkLRUYvyVVYDCRIIbmWL68ybzY2ND8FyuQwCOWP-2_vFvm8xmpjFURZwuNv-eGULNwzOfrSCIelqM2ImCYcM3tpbnyMPeW_KoSI4LGKxXZZqBIcpa9Xb0Zr225uhpZJ2tb_ItuqdOXPUC0GZdHbpbCI0I-Yu-IudCRBHZZ_2SlAi3vbJcvmjpXHfaz49enR602S8ztXF4gXG4_lXa0fS5QYtB0lnIv9q8HXzxKioG_P3O1yD1HqdLYXhZaMNDyg1Xm-5hAkfQ4A7UMPgK4a2zg

    The token value may be used in an authorization header to , the CLI or in the . 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.

    These examples provide a quick reference for making successful REST API calls. They use insecure methods. In these examples, a simple GET call is made to list available resources.

    Example 2. Result (Truncated)

    1. {
    2.   "kind": "APIResourceList",
    3.   "groupVersion": "v1",
    4.   "resources": [
    5.     {
    6.       "name": "buildconfigs",
    7.       "kind": "BuildConfig"
    8.     },
    9.     {
    10.       "name": "buildconfigs/instantiate",
    11.       "namespaced": true,
    12.       "kind": "BuildRequest"
    13.     },
    15.       "name": "buildconfigs/instantiatebinary",
    16.       "namespaced": true,
    17.       "kind": "BinaryBuildRequestOptions"
    18.     },
    19.     {
    20.       "name": "buildconfigs/webhooks",
    21.       "namespaced": true,
    22.       "kind": "Status"
    23.     },
    24.     {
    25.       "name": "builds",
    26.       "namespaced": true,
    27.       "kind": "Build"
    28.     },
    29.     {
    30.       "name": "subjectaccessreviews",
    31.       "namespaced": true,
    32.       "kind": "SubjectAccessReview"
    34.     {
    35.       "name": "templates",
    36.       "namespaced": true,
    37.       "kind": "Template"
    38.     },
    39.     {
    40.       "name": "useridentitymappings",
    41.       "namespaced": false,
    42.       "kind": "UserIdentityMapping"
    43.     },
    44.     {
    45.       "name": "users",
    46.       "namespaced": false,
    47.       "kind": "User"
    48.     }
    49.   ]
    50. }

    Example 3. Interactive Python API Call Using “requests” Module (Insecure)

    The OKD integrated Docker registry must be authenticated using either a 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:

      The OpenShift Container Registry allows the users to manipulate the image signatures using its own API. See for more information.

      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 . 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 .