Rest API Examples

This page includes usage examples for OpenShift’s REST API. The examples are presented as curl and jq command calls. The examples are parameterised using environment variables as follows:

Environment variablePurpose

TOKEN

Authentication token for OpenShift. If using X.509 authentication, remove lines referencing $TOKEN and provide a client certificate and key instead. For example, the curl —cert and —key arguments.

ENDPOINT

TCP endpoint of OpenShift API server, such as 127.0.0.1:8443. Without loss of generality, in these examples it is assumed that the API server is presented by HTTPS and that it may be accessed insecurely.

NAMESPACE

Namespace to use for namespaced objects.

To try out the usage examples by copy/paste, first set all of the previously mentioned environment variables, for example:

  1. TOKEN=$(oc whoami -t)
  2. ENDPOINT=$(oc config current-context | cut -d/ -f2 | tr - .)
  3. NAMESPACE=$(oc config current-context | cut -d/ -f1)

Template Instantiation

Templates include one or more objects to be instantiated, as well as optionally specifying parameters to be used at instantiation time. The flow to instantiate a Template using the TemplateInstance API follows:

  1. To set any parameter values (e.g. to override default values specified in the Template or to specify parameter values which have no defaults), create a Secret containing the necessary values.

    1. $ curl -k \
    2.     -X POST \
    3.     -d @- \
    4.     -H "Authorization: Bearer $TOKEN" \
    5.     -H 'Accept: application/json' \
    6.     -H 'Content-Type: application/json' \
    7.     https://$ENDPOINT/api/v1/namespaces/$NAMESPACE/secrets <<'EOF'
    8. {
    9.   "kind": "Secret",
    10.   "apiVersion": "v1",
    11.   "metadata": {
    12.     "name": "secret"
    13.   },
    14.   "stringData": {
    15.     "NAME": "example"
    16.   }
    17. }
    18. EOF

  2. Create a TemplateInstance containing the whole template you want to instantiate, and a reference to the Secret created above.

    1. $ curl -k \
    2.     -X POST \
    3.     -d @- \
    4.     -H "Authorization: Bearer $TOKEN" \
    5.     -H 'Accept: application/json' \
    6.     -H 'Content-Type: application/json' \
    7.     https://$ENDPOINT/apis/template.openshift.io/v1/namespaces/$NAMESPACE/templateinstances <<EOF
    8. {
    9.   "kind": "TemplateInstance",
    10.   "apiVersion": "template.openshift.io/v1",
    11.   "metadata": {
    12.     "name": "templateinstance"
    13.   },
    14.   "spec": {
    15.     "secret": {
    16.       "name": "secret"
    17.     },
    18.     "template": $(curl -k \
    19.                     -H "Authorization: Bearer $TOKEN" \
    20.                     -H 'Accept: application/json' \
    21.                     https://$ENDPOINT/apis/template.openshift.io/v1/namespaces/openshift/templates/cakephp-mysql-example)
    22.   }
    23. }
    24. EOF

  3. Poll the TemplateInstance or watch the TemplateInstance until either the Ready or InstantiateFailure condition types report status True.

    1. $ while ! curl -s -k \
    2.             -H "Authorization: Bearer $TOKEN" \
    3.             -H 'Accept: application/json' \
    4.             https://$ENDPOINT/apis/template.openshift.io/v1/namespaces/$NAMESPACE/templateinstances/templateinstance | \
    5.           jq -e '.status.conditions[] | select(.status == "True") | .type'; do
    6.     sleep 1
    7.   done