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
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
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. ]
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 ...
oc api-versions to obtain the API version. For example:
$ oc api-versions | grep security.openshift security.openshift.io/v1
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 --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.