Image
Explore OpenShift APIs from the command line
Get key details about routes, buildconfigs, deploymentconfigs, and other OpenShift-specific APIs.
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.
Image
Compare methods for running OpenShift's ready-to-use Kubernetes environment on Amazon's public cloud infrastructure.
Image
Go beyond OpenShift's default options to set up custom role-based access control (RBAC) permissions for local and cluster roles.
Image
Sometimes the process to delete Kubernetes namespaces gets hung up, and the command never completes. Here's how to troubleshoot terminating namespaces
Topics:
OpenShift
Kubernetes
Robert Kimani
Robert is a Linux enthusiast and an open source advocate, currently transitioning into a site reliability engineering (SRE) role. Always striving to learn more, he's pursuing Red Hat Certified Architect - Infrastructure path certification. Besides his love for Linux, he believes in helping others More about me