Kubernetes YAML files: Pod

Kubernetes YAML files Pod
Kubernetes YAML files Pod

Hello guys! welcome on the second part of the Kubernetes YAML files series, on this article we will discuss the Pod creation YAML file key by key or parameter by parameter, what type of data it could take and what data actually it could take if there is any predefined one. Let’s go!

If you don’t know what is a Kubernetes Pod, you can refer to those articles:

What we should know

First of all, i want you to know that when we run our kubectl create command to assure the creation of our new pod, it’s like we are sending a POST request to the Kubernetes API and exactly to this endpoint:


Note: the Kubernetes API accepts only application/json, application/yaml content types.

Pod YAML file

That request we send to create a new pod have our YAML or JSON file as a body.

The map on the pod YAML file have 4 keys which are:

apiVersion: VALUE
kind: VALUE
metadata: VALUE
spec: VALUE

Each one of those keys can take a specific type of data with a specific keys names of course,

so let’s start by disassembling the pod creation YAML file part by part until we get the big image:

  • apiVersion: 

    apiVersion: v1

    on the most articles around the web that are about creating a pod, no one discussed what is this apiVersion and what it actually means! but i am here to do this so 😀

Simply, Kubernetes uses API groups and that apiVersion is the reference of the group and the version you want to use, for example:

The core group: it’s called the legacy group too and it REST path is /api/v1 and we refer to it by v1 as a value of the apiVersion.

The named groups: represent the other groups and they are under the REST path /apis/GROUP_NAME/VERSION and the two parameters are specified by you with the apiVersion which takes the value GROUP_NAME/VERSION .

You can find a full lists of those groups on the official Kubernetes docs.

  • Kind:

kind: Pod

Simply, it’s the name of the resource or the object we want to create and those resources have a specific names of course and here our resource name is Pod cause we want to create a new Pod. To find out all the objects names supported by Kubernetes, you can run the following command:

[root@ettayeb~]# kubectl api-resources
NAME                              SHORTNAMES       KIND
bindings                                           Binding
componentstatuses                 cs               ComponentStatus
configmaps                        cm               ConfigMap
endpoints                         ep               Endpoints
events                            ev               Event
limitranges                       limits           LimitRange
namespaces                        ns               Namespace
nodes                             no               Node
persistentvolumeclaims            pvc              PersistentVolumeClaim
persistentvolumes                 pv               PersistentVolume
pods                              po               Pod
podtemplates                                       PodTemplate
replicationcontrollers            rc               ReplicationController
resourcequotas                    quota            ResourceQuota
secrets                                            Secret
serviceaccounts                   sa               ServiceAccount
services                          svc              Service
initializerconfigurations                          InitializerConfiguration
mutatingwebhookconfigurations                      MutatingWebhookConfiguration
validatingwebhookconfigurations                    ValidatingWebhookConfiguration
customresourcedefinitions         crd,crds         CustomResourceDefinition
apiservices                                        APIService
controllerrevisions                                ControllerRevision
daemonsets                        ds               DaemonSet
deployments                       deploy           Deployment
replicasets                       rs               ReplicaSet
statefulsets                      sts              StatefulSet
tokenreviews                                       TokenReview
localsubjectaccessreviews                          LocalSubjectAccessReview
selfsubjectaccessreviews                           SelfSubjectAccessReview
selfsubjectrulesreviews                            SelfSubjectRulesReview
subjectaccessreviews                               SubjectAccessReview
horizontalpodautoscalers          hpa              HorizontalPodAutoscaler
cronjobs                          cj               CronJob
jobs                                               Job
brpolices                         br,bp            BrPolicy
clusters                          rcc              Cluster
filesystems                       rcfs             Filesystem
objectstores                      rco              ObjectStore
pools                             rcp              Pool
certificatesigningrequests        csr              CertificateSigningRequest
leases                                             Lease
events                            ev               Event
daemonsets                        ds               DaemonSet
deployments                       deploy           Deployment
ingresses                         ing              Ingress
networkpolicies                   netpol           NetworkPolicy
podsecuritypolicies               psp              PodSecurityPolicy
replicasets                       rs               ReplicaSet
nodes                                              NodeMetrics
pods                                               PodMetrics
networkpolicies                   netpol           NetworkPolicy
poddisruptionbudgets              pdb              PodDisruptionBudget
podsecuritypolicies               psp              PodSecurityPolicy
clusterrolebindings                                ClusterRoleBinding
clusterroles                                       ClusterRole
rolebindings                                       RoleBinding
roles                                              Role
volumes                           rv               Volume
priorityclasses                   pc               PriorityClass
storageclasses                    sc               StorageClass
volumeattachments                                  VolumeAttachment

And as you can see there is the name of objects, their shortnames and the kind which is the value you put on your YAML file.

  • metadata: 

The rules say that if there is a Kind so there is a metadata and it takes a map as value with one key or more (or a nested JSON object of course). The keys on this map are used to identify your pod or object, it simply takes a new map as a value with the following keys in general:

  name: VALUE
  namespace: VALUE
    key: VALUE
    key: VALUE
    key: VALUE
    key: VALUE

Simply the name of your pod or object you want to create and this is the most required key here.


It’s the name of the namespace you want to create your Pod in. the default value of this key is “default” if not added on the YAML file so it will be created on the default namespace.


This key takes a map as value and it’s used to group and categorize the objects you creating. It is intended for an object to object grouping and mapping using selectors. For example, kubernetes service uses the pod labels in its selectors to send traffic to the right pods. We will see more about labels and selectors in the service creation article.


It takes a map as a value too and in general it’s used to add any extra data you want to your object like:

    • Fields managed by a declarative configuration layer. Attaching these fields as annotations distinguishes them from default values set by clients or servers, and from auto-generated fields and fields set by auto-sizing or auto-scaling systems.
    • Build, release, or image information like timestamps, release IDs, git branch, PR numbers, image hashes, and registry address.Pointers to logging, monitoring, analytics, or audit repositories.
    • Client library or tool information that can be used for debugging purposes: for example, name, version, and build information.
    • User or tool/system provenance information, such as URLs of related objects from other ecosystem components.
    • Lightweight rollout tool metadata: for example, config or checkpoints.Phone or pager numbers of persons responsible, or directory entries that specify where that information can be found, such as a team web site.
    • Directives from the end-user to the implementations to modify behavior or engage non-standard features.

Taken from the Kubernetes official docs

  • Spec:

Here is where we declare our Pod or object in general desired state, what we want this object to contain and the characteristics that you want the object to have.

It takes a map as a value and there is a large number of keys that we can add and the most important ones are containers and volumes, it depends on what you want exactly to run.

Here is the full list of keys you can have: Spec map keys

Example of Spec declaration:

    -name: frontend
    image: nginx
    containerPort: 80

Here, we have a fairly minimal definition with a name (frontend), the image on which it’s based (nginx) and one port on which the container will listen internally (80). Here only the name is really required, but in general, if you want it to do anything useful, you’ll need more information.

We can also specify other complex properties, like command to run when the container starts, arguments it should use, a working directory, or whether to pull a new copy of the image every time it’s instantiated.  You can also specify even deeper informations, you can find all the keys you can set here.


This is the end of this article, you got everything you need right now to start playing with pods and their configs so just go and test most of the keys that you can setup for containers and so on to understand better and see the different behaviours that you can setup.

See you on the next article!


Please enter your comment!
Please enter your name here