Understanding the Kubernetes manifest

Sujith Abdul Rahim
Dec 2, 2019 · 4 min read

The manifest is a specification of a Kubernetes API object in JSON or YAML format. A manifest specifies the desired state of an object that Kubernetes will maintain when you apply the manifest.

We could define the desired state of our application through a set of key:value pair called manifest which further deploys it into the Kubernetes cluster to properly maintain it. That’s awesome, but how do we define these states by going through in-depth or can we write it in a better way? This article will explore more about that.

Let’s take this as an example of a manifest for Nginx deployment into the K8 cluster,

apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
labels:
app: nginx
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.7.9
ports:
- containerPort: 80

As we could see it has 4 main objects such as apiVersion, kind, metadata & spec, but how do we find these objects and where we could get the values corresponding to each object? This is where the role of kubectl api-versions, kubectl api-resources & kubectl explain command comes into play.

Use kubectl api-versions to find out the available list of APIs supported by the cluster,

$ kubectl api-versions | moreadmissionregistration.k8s.io/v1beta1
apiextensions.k8s.io/v1beta1
apiregistration.k8s.io/v1
apiregistration.k8s.io/v1beta1
app.k8s.io/v1beta1
apps/v1
apps/v1beta1
apps/v1beta2
.... much more

kubectl api-resources is a way to get the information about kind , adding kubectl api-resources -o wide provides a detailed output with neat explanation of each kind.

$ kubectl api-resourcesNAME         SHORTNAMES         APIGROUP     NAMESPACED   KIND
daemonsets ds apps true DaemonSet
deployments deploy apps true Deployment
replicasets rs apps true ReplicaSet
----- much more

Now, we could dig more into the APIs and their kind values via kubectl explain ,

$ kubectl explain --api-version=apps/v1 DeploymentKIND: Deployment
VERSION: apps/v1
DESCRIPTION:
Deployment enables declarative updates for Pods and ReplicaSets.
FIELDS:
apiVersion <string>
APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values.
kind <string>
Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase.
metadata <Object>
Standard object metadata.
spec <Object>
Specification of the desired behavior of the Deployment.
status <Object>
Most recently observed status of the Deployment.

We could further go in-depth to view the available options of each field via the formatobject.fields ,

$ kubectl explain --api-version=apps/v1 Deployment.metadata | moreKIND:     Deployment
VERSION: apps/v1
RESOURCE: metadata <Object>
DESCRIPTION:
Standard object metadata. ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.
FIELDS:
name <string>
Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition.
labels <map[string]string>
Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services
----- much more
$ kubectl explain --api-version=apps/v1 Deployment.spec.template | moreKIND: Deployment
VERSION: apps/v1
RESOURCE: template <Object>
DESCRIPTION:
Template describes the pods that will be created. PodTemplateSpec describes the data a pod should have when created from a template
FIELDS:
metadata <Object>
Standard object's metadata.
spec <Object>
Specification of the desired behavior of the pod.
----- much more
$ kubectl explain --api-version=apps/v1 Deployment.spec.template.spec.containers | moreKIND: Deployment
VERSION: apps/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:
name <string> -required-
Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated.
image <string>
Docker image name.Optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets.
ports <[]Object>
List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated.
----- much more

Passing these commands with the --recursive provides a hierarchical view of each object which could further explore it via the same formatobject.fields .

$ kubectl explain --api-version=apps/v1 Deployment --recursive  | moreKIND:     Deployment
VERSION: apps/v1
DESCRIPTION:
Deployment enables declarative updates for Pods and ReplicaSets.
FIELDS:
apiVersion <string>
kind <string>
metadata <Object>
annotations <map[string]string>
clusterName <string>
creationTimestamp <string>
deletionGracePeriodSeconds <integer>
deletionTimestamp <string>
----- much more

Ultimately, the command kubectl explain provides easy access to Kubernetes API documentation which is a great reference for understanding different manifest and guide us to make further modification when needed.

Please don’t forget to hit the clap if you like this piece of information.

Sujith Abdul Rahim

Written by

Product Engineer — DevOps | ~5 min read

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade