examples | ReST API Reference

Template Instantiation

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 variable Purpose

environment variable	Purpose
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.

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:

TOKeN=$(oc whoami -t)
eNDPOINT=$(oc config current-context | cut -d/ -f2 | tr - .)
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:

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.

$ curl -k \
    -X POST \
    -d @- \
    -H "Authorization: Bearer $TOKeN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    https://$eNDPOINT/api/v1/namespaces/$NAMeSPACe/secrets <<'eOF'
{
  "kind": "Secret",
  "apiVersion": "v1",
  "metadata": {
    "name": "secret"
  },
  "stringData": {
    "NAMe": "example"
  }
}
eOF

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

$ curl -k \
    -X POST \
    -d @- \
    -H "Authorization: Bearer $TOKeN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    https://$eNDPOINT/apis/template.openshift.io/v1/namespaces/$NAMeSPACe/templateinstances <<eOF
{
  "kind": "TemplateInstance",
  "apiVersion": "template.openshift.io/v1",
  "metadata": {
    "name": "templateinstance"
  },
  "spec": {
    "secret": {
      "name": "secret"
    },
    "template": $(curl -k \
                    -H "Authorization: Bearer $TOKeN" \
                    -H 'Accept: application/json' \
                    https://$eNDPOINT/apis/template.openshift.io/v1/namespaces/openshift/templates/cakephp-mysql-example)
  }
}
eOF

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

$ while ! curl -s -k \
            -H "Authorization: Bearer $TOKeN" \
            -H 'Accept: application/json' \
            https://$eNDPOINT/apis/template.openshift.io/v1/namespaces/$NAMeSPACe/templateinstances/templateinstance | \
          jq -e '.status.conditions[] | select(.status == "True") | .type'; do
    sleep 1
  done

Rest API examples

Template Instantiation