Explore OpenShift APIs from the command line

An application programming interface (API) defines resources in an application that are available by interacting with it remotely. OpenShift's API is based on the Kubernetes API, with a layer of OpenShift-specific APIs providing extra functionality. Examples of different OpenShift-specific APIs include routes, buildconfigs, and deploymentconfigs.

Kubernetes resources aren't always compatible with OpenShift resources due to OpenShift's additional capabilities. As you transition from a Kubernetes environment to an OpenShift environment, OpenShift adopts your Kubernetes API resources without a problem, but the reverse is not the case.

You can explore APIs from the command line to see how to define resources declaratively using YAML.

Explore the OpenShift API

OpenShift includes onboard documentation by default. The following are examples of the commands you can use to view its API documentation without accessing the internet:

$ oc api-resources

Use grep to filter the results so you can see the difference in API version information between deploymentconfigs (an OpenShift resource) and deployments (a Kubernetes resource):

$ oc api-resources | grep deployment
---
deployments       deploy apps/v1              true Deployment
deploymentconfigs dc     apps.openshift.io/v1 true DeploymentConfig

[ Download the Kubernetes glossary cheat sheet. ]

The NAMESPACED column in the output below depicts some resources with the value true. These resources can be limited to a specific namespace. A resource with a value of false exists for all namespaces, superseding the namespace's limitations.

$ oc api-resources | head -n 5    
---
NAME        SHORTNAMES  APIVERSION NAMESPACED KIND
bindings                v1         true       Binding
componentstatuses  cs   v1         false      ComponentStatus
configmaps         cm   v1         true       ConfigMap
endpoints          ep   v1         true       Endpoints

API versions are especially important when you're working with YAML files. Knowing the version helps you avoid API error messages. Your YAML version must address the version that the API currently provides. To view your API versions, type:

$ oc api-versions

For instance, the example below shows the required API version in a security context constraint (SCC) YAML file, which matches the API version available in my OpenShift installation. This is important to keep track of because an API version could be upgraded later. Should v2 be the only API version available, and your YAML files are addressing v1, your resource won't work as expected.

---
kind: SecurityContextConstraints
apiVersion: security.openshift.io/v1
metadata:
  name: scc-admin
...

Use oc api-versions to obtain the API version. For example:

$ oc api-versions | grep security.openshift                                                                                                                                                                                                               
security.openshift.io/v1

Notice that security.openshift is separated by a dot. Dotted notation allows you to focus on a specific parameter or property for a particular resource. For example, oc explain pod.spec displays the parameters you can use on a pod specification. To get additional specifics on containers and the different properties you can apply, walk through the hierarchy with more dots (for example, oc explain pod.spec.containers).

Explore the APIs

To view the contents of an API in detail, use oc explain:

$ oc explain
$ oc explain --recursive

Based on the information in oc explain, you can define resources in a declarative in YAML.

[ Get this complimentary eBook from Red Hat: Managing your Kubernetes clusters for dummies. ]

Explore the API pod specification

The YAML below shows a kind specification for a pod containing a spec section:

---
apiVersion: v1
kind: Pod
metadata:
  name: mypod
spec:
  containers:
  - name: alpine
    image: alpine:3.9
    command:
    - "sleep"
    - "3600"
…

To get more information about the spec of a particular kind (in this case, a pod), oc explain is the best command to use.

This command shows all the different properties with a description that you can use in your pod:

$ oc explain pod.spec
---
KIND:     Pod
VERSION:  v1

RESOURCE: spec <Object>

DESCRIPTION:
     Specification of the desired behavior of the pod.
     More info: https://git.k8s.io/community/contributors/
     devel/sig-architecture/api-conventions.md#spec-and-status

     PodSpec is a description of a pod.

FIELDS:
   activeDeadlineSeconds	<integer>
     Optional duration in seconds the pod may be active on the
     node relative to StartTime before the system will actively
     try to mark it failed and kill associated containers. Value
     must be a positive integer.

   affinity	<Object>
     If specified, the pod's scheduling constraints

   automountServiceAccountToken	<boolean>
     AutomountServiceAccountToken indicates whether a service
     account token should be automatically mounted.

   containers	<[]Object> -required-
     List of containers belonging to the pod. Containers cannot
     currently be added or removed. There must be at least one
     container in a Pod. Cannot be updated.

   dnsConfig	<Object>
     Specifies the DNS parameters of a pod. Parameters specified
     here will be merged to the generated DNS configuration based
     on DNSPolicy.

   dnsPolicy	<string>
     Set DNS policy for the pod. Defaults to "ClusterFirst".
     Valid values are 'ClusterFirstWithHostNet', 'ClusterFirst',
     'Default' or 'None'. DNS parameters given in DNSConfig will
     be merged with the policy selected with DNSPolicy. To have
     DNS options set along with hostNetwork, you have to specify 
     DNS policy explicitly to 'ClusterFirstWithHostNet'.

This gives all the parameters and properties you can apply in a pod specification. If you are new to Kubernetes or OpenShift, and you're having trouble distinguishing between a pod and a container, the oc explain pod.spec and oc explain pod.spec.containers can reveal the facts for you. Here is an example:

$ oc explain pod.spec.containers
---
KIND:     Pod
VERSION:  v1

RESOURCE: containers <[]Object>

DESCRIPTION:
     List of containers belonging to the pod. Containers 
     cannot currently be added or removed. There must be at
     least one container in a Pod. Cannot be updated.

     A single application container that you want to run 
     within a pod.

FIELDS:
   args	<[]string>
     Arguments to the entrypoint. The docker image's CMD is 
     used if this is not provided. Variable references
     $(VAR_NAME) are expanded using the container's environment.
     If a variable cannot be resolved, the reference in the
     input string will be unchanged. Double $$ are reduced to a
     single $, which allows for escaping the $(VAR_NAME) syntax:
     i.e. "$$(VAR_NAME)" will produce the string literal
     "$(VAR_NAME)". Escaped references will never be expanded,
     regardless of whether the variable exists or not. Cannot be
     updated. More info: https://kubernetes.io/docs/tasks/
     inject-data-application/define-command-argument-container/
     #running-a-command-in-a-shell

   command	<[]string>
     Entrypoint array. Not executed within a shell. The docker
     image's ENTRYPOINT is used if this is not provided.
     Variable references $(VAR_NAME) are expanded using the
     container's environment. If a variable cannot be resolved,
     the reference in the input string will be unchanged.
     Double $$ are reduced to a single $, which allows for
     escaping the $(VAR_NAME) syntax: i.e. "$$(VAR_NAME)" will
     produce the string literal "$(VAR_NAME)".
     Escaped references will never be expanded, regardless of 
     whether the variable exists or not. Cannot be updated.
     More info:
     https://kubernetes.io/docs/tasks/inject-data-application/
     define-command-argument-container/
     #running-a-command-in-a-shell

   env	<[]Object>
     List of environment variables to set in the container.
     Cannot be updated.

Explore even further with oc explain deployment.spec and oc explain deploymentconfigs.spec to see the difference between deployments and deploymentconfigs and display the parameters you can use for deployments and deploymentconfigs.

Note that one is a Kubernetes resource, and the other is an OpenShift-specific resource.

One notable difference is that there are no trigger specifications for deployments, but there are trigger specifications for deploymentconfigs. To view the different parameters that can be defined under the trigger section as part of your declarative YAML files, use:

$ oc explain deploymentconfigs.spec.triggers
---
KIND:     DeploymentConfig
VERSION:  apps.openshift.io/v1

RESOURCE: triggers <[]Object>

DESCRIPTION:
     Triggers determine how updates to a DeploymentConfig
     result in new deployments. If no triggers are defined,
     a new deployment can only occur as a result of an
     explicit client update to the DeploymentConfig with a
     new LatestVersion. If null, defaults to having a config
     change trigger.
     DeploymentTriggerPolicy describes a policy for a single
     trigger that results in a new deployment.

FIELDS:
   imageChangeParams	<Object>
     ImageChangeParams represents the parameters for the
     ImageChange trigger.

   type	<string>
     Type of the trigger

Use the onsite API resource documentation

Just as Linux provides man pages, OpenShift provides documentation defined in its API. This information is important to have available, so you can quickly look up the information you need for your day-to-day OpenShift administration. This approach could save you time in air-gapped, restricted environments.