Kubernetes Pod Manifest: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(157 intermediate revisions by the same user not shown)
Line 1: Line 1:
=External=
=External=
 
* https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#pod-v1-core
* https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14/#pod-v1-core


=Internal=
=Internal=
Line 7: Line 6:
* [[ Kubernetes Pod and Container Concepts#Pod_Manifest|Pod and Container Concepts]]
* [[ Kubernetes Pod and Container Concepts#Pod_Manifest|Pod and Container Concepts]]
* [[Kubernetes_Manifests#Common_Elements|Common Manifest Elements]]
* [[Kubernetes_Manifests#Common_Elements|Common Manifest Elements]]
* [[Kubernetes Deployments]]
* [[Kubernetes Mounting Volumes in Pods|Mounting Volumes in Pods]]


=Overview=
=Overview=
[[Kubernetes Workload Resources#Overview|Workload resource]] controllers create pods from [[#Pod_Template|pod templates]].
=Pod Template=
Pod templates are '''specifications''' for creating pods, and they are included in the manifests of the [[#Kubernetes_Workload_Resources|workload resources]]. Modifying the pod template or switching to a new pod template is detected by the workload resource controller, which usually shuts down the current running pods and replaces them with new pods built based on the new template. Each workload resource has its own rules for handling changes in the pod template.


=Example=
=Example=
 
<font size=-1>
  [[Kubernetes_Manifests#apiVersion|apiVersion]]: v1
  [[Kubernetes_Manifests#apiVersion|apiVersion]]: v1
  [[Kubernetes_Manifests#kind|kind]]: Pod
  [[Kubernetes_Manifests#kind|kind]]: Pod
  [[Kubernetes_Manifest_Metadata#Overview|metadata]]:
  [[Kubernetes_Manifest_Metadata#Overview|metadata]]:
   [[Kubernetes_Manifest_Metadata#name|name]]: loop
   [[Kubernetes_Manifest_Metadata#name|name]]: loop
   [[Kubernetes_Manifest_Metadata#labels|labels]]:
   [[#labels|labels]]:
     color: blue
     color: blue
  [[Kubernetes_Manifests#spec|spec]]:
  [[Kubernetes_Manifest_Metadata#annotations|annotations]]:
    ...
  [[#generateName|generateName]]
  [[Kubernetes_Manifests#spec|spec]]
  [[#restartPolicy|restartPolicy]]: Always
  schedulerName: default-scheduler
  terminationGracePeriodSeconds: 120
  [[#serviceAccountName|serviceAccountName]]: 'testServiceAccount'
  [[#dnsPolicy|dnsPolicy]]: ClusterFirst
  <span id='imagePullSecrets_manifest'></span>[[#imagePullSecrets|imagePullSecrets]]:
    - name: myPullSecret1
    - name: myPullSecret2
    ...
  <span id='podSecurityContext_manifest'></span>[[#podSecurityContext|securityContext]]:
    runAsUser: 1000 # integer, not quoted
    runAsGroup: 3000 # integer, not quoted
    runAsNonRoot: true
    fsGroup: 2000
    fsGroupChangePolicy:
    seLinuxOptions:
    seccompProfile:
    supplementalGroups:
    sysctls:
   [[#containers|containers]]:
   [[#containers|containers]]:
   - [[#name|name]]: loop-container
   - [[#name|name]]: loop-container
     [[#image|image]]: docker.io/ovidiufeodorov/loop:latest
     [[#image|image]]: docker.io/ovidiufeodorov/loop:latest
     [[#imagePullPolicy|imagePullPolicy]]: Always
     [[#imagePullPolicy|imagePullPolicy]]: Always
     resources:
     [[#lifecycle|lifecycle]]: [...]
       limits:
    [[#resources|resources]]:
       [[#requests|requests]]:
        memory: '1024Mi'
        cpu: '500m'
      [[#limits|limits]]:
         memory: '4096Mi'
         memory: '4096Mi'
         cpu: '1000m'
         cpu: '1000m'
     terminationMessagePath: /dev/termination-log
     terminationMessagePath: /dev/termination-log
     terminationMessagePolicy: File
     terminationMessagePolicy: File
     ports:
     [[#command|command]]: ...
     - containerPort: 8080
    [[#ports|ports]]:
       protocol: TCP
     - [[#containerPort|containerPort]]: 8080
       [[#protocol|protocol]]: TCP
      [[#port_name|name]]: 'http'
     - containerPort: 8787
     - containerPort: 8787
       protocol: TCP
       protocol: TCP
     env:
     - containerPort: ...
      [[#hostPort|hostPort]]: ....
    [[#env|env]]:
     - name: SOMETHING
     - name: SOMETHING
        value: 'something else'
      value: "something else"
     [[#volumeMounts|volumeMounts]]:
    - name: A_BOOLEAN_VARIABLE
     - [[#volume_name|name]]: 'mount-0'
      value: "true" # must be quoted
       [[#mountPath|mountPath]]: '/data'
     [[Kubernetes_Mounting_Volumes_in_Pods#volumeMounts_Pod_Manifest_Section|volumeMounts]]:
       [[#subPath|subPath]]: 'content'
     - [[Kubernetes_Mounting_Volumes_in_Pods#volume_name|name]]: 'mount-0'
       [[Kubernetes_Mounting_Volumes_in_Pods#mountPath|mountPath]]: '/red'
       [[Kubernetes_Mounting_Volumes_in_Pods#subPath|subPath]]: 'orange'
    [[#readinessProbe|readinessProbe]]:
      # See [[Kubernetes_Container_Probes#Probe_Template|Probe Template]]
    [[#livenessProbe|livenessProbe]]:
      # See [[Kubernetes_Container_Probes#Probe_Template|Probe Template]]
    [[#command|command]]: ['sh', '-c', 'while true; do sleep 2; done;']
    <span id='securityContext_manifest'></span>[[#containerSecurityContext|securityContext]]:
      runAsGroup: 1001 # integer, not quoted
      runAsUser: 1001 # integer, not quoted
      runAsNonRoot: true
      privileged: false
      allowPrivilegeEscalation: false
      readOnlyRootFilesystem: false
      capabilities:
      seLinuxOptions:
      procMount:
      seccompProfile:
  [[#initContainers|initContainers]]:
  - [[#name|name]]: init-container1
    [[#image|image]]: busybox
    [[#command|command]]: ['sh', '-c', 'until nslookup myservice; do echo waiting for myservice; sleep 2; done;']
  <span id='volumes_manifest'></span>[[#volumes|volumes]]:
  - name: mount-0
    hostPath:
      # '/yellow' must contain an 'orange' sub-directory
      path: '/yellow'
  - name: mount-1
    persistentVolumeClaim:
      claimName: pvc1
</font>


=.spec Elements=
=.<tt>metadata</tt> Elements=
==<tt>labels</tt>==
A pod can be tagged with [[Kubernetes_Labels_and_Annotations#Label|labels]]. This section contains labels applied to the pod created based on this template. If the template is part of a [[Kubernetes Deployment Manifest#Overview|deployment manifest]], the section contains the labels applied to pods created by the deployment, and they must match the deployment's [[Kubernetes_Deployment_Manifest#selector|spec.selector]] values.
 
Also see: {{Internal|Kubernetes_Manifest_Metadata#labels|Kubernetes Manifest Metadata &#124; labels}}
 
==<tt>generateName</tt>==
"generateName" can be used to append random characters at the end of the base name, thus generating a unique pod name.
 
=.<tt>spec</tt> Elements=
{{External|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14/#podspec-v1-core}}
{{External|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14/#podspec-v1-core}}


==hostname==
==<tt>hostname</tt>==
Optional field. If not specified, the hostname exposed to the processes running inside the pod will be the name of the pod.
Optional field. If not specified, the hostname exposed to the processes running inside the pod will be the name of the pod.


==restartPolicy==
==<tt>restartPolicy</tt>==
Optional field.
Optional field. See: {{Internal|Kubernetes_Pod_and_Container_Concepts#Container_Restart_Policy|Container Restart Policy}}
 
==<tt>serviceAccountName</tt>==
The name of [[Kubernetes_Pod_and_Container_Concepts#Pod_Service_Account|this pod's service account]]. Note that "serviceAccount" configuration element also exists, but it is deprecated. If not specified, defaults to the pod's namespace default service account.
==<tt>dnsPolicy</tt>==
{{Internal|Kubernetes_DNS_Concepts#Name_Resolution_inside_a_Pod|Name Resolution inside a Pod}}
==<tt>imagePullSecrets</tt>==
{{Internal|Kubernetes_Cluster_Configuration_Concepts#imagePullSecrets|Kubernetes Configuration Concepts &#124; Secrets Required to Pull Images for Pods}}
 
==<span id='podSecurityContext'></span><tt>securityContext</tt>==
{{External|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#podsecuritycontext-v1-core}}
The pod-wide security context, applies to all containers. See: {{Internal|Kubernetes_Security_Concepts#Pod_Security|Pod Security}}
 
==<tt>containers</tt>==
{{External|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#container-v1-core}}
"containers" contains an array with the pod's container definitions.
===<tt>name</tt>===
===<tt>image</tt>===
{{Internal|Kubernetes Container Image Pull Concepts|Kubernetes Container Image Pull Concepts}}
 
===<tt>imagePullPolicy</tt>===
{{External|https://kubernetes.io/docs/concepts/containers/images/}}
{{Internal|Kubernetes Container Image Pull Concepts|Kubernetes Container Image Pull Concepts}}
===<tt>lifecycle</tt>===
{{External|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#lifecycle-v1-core}}
===<tt>volumeMounts</tt>===
{{Internal|Kubernetes Mounting Volumes in Pods|Mounting Volumes in Pods}}
 
===<tt>ports</tt>===
Contains an array specifying the ports exposed by the containers in this pod.
====<tt>containerPort</tt>====
====<tt>protocol</tt>====
====<span id='port_name'></span><tt>name</tt>====
An optional name given to the container port. If declared, it must be a IANA_SVC_NAME and unique within the pod. It can be used in the manifest of the associated service to designate the service's [[Kubernetes_Service_Concepts#Service_Target_Port|target port]].
====<tt>hostPort</tt>====
Binds the container port to a host port.
===<tt>env</tt>===
Contains a list of name/value pairs representing the list of the environment variables to set in the container. In case of boolean variables, declare the boolean values as Strings ("true"/"false"), otherwise the template won't be processed correctly.
===<span id='readinessProbe'></span><span id='livenessProbe'></span><tt>readinessProbe</tt>, <tt>livenessProbe</tt>===
{{Internal|Kubernetes_Container_Probes#Probe_Template|Probe Template}}
 
===<tt>command</tt>===
{{External|https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell}}
 
Optional field. If not present, the docker image's ENTRYPOINT is used. If present, represents the entrypoint array of the container. Not executed within a shell, so if a shell is required, must be specified as below. 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. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not.


==containers==
Example:


===name===
<syntaxhighlight lang='yaml'>
===image===
  ...
  command: ['sh', '-c', 'while true; do echo .; sleep 1; done']
</syntaxhighlight>


===imagePullPolicy===
Each array element is a string, and in the above case, the array element that follows the '-c' element is passed as one string to the shell to be executed.


The value is one of "Always", "Never", "IfNotPresent". Defaults to "Always" if ":latest" tag is specified, or "IfNotPresent" otherwise.
Alternative syntax:


<font color=darkgray>TODO: https://kubernetes.io/docs/concepts/containers/images#updating-images</font>
<syntaxhighlight lang='yaml'>
  ...
  command:
  - /bin/sh
  - -c
  - 'i=0; echo $i'
</syntaxhighlight>


===volumeMounts===
The single quotes are optional, the content that follows "-" will be interpreted as a single string:


Pod volumes to mount into the container's filesystem.
<syntaxhighlight lang='yaml'>
  ...
  command:
  - /bin/sh
  - -c
  - i=0; echo $i
</syntaxhighlight>


====<span id='volume_name'></span>name====
Also see: {{Internal|Dockerfile#ENTRYPOINT_and_CMD|Dockerfile ENTRYPOINT and CMD}}


The identifier of the volume. Must match the name the volume specification was declared under, in the [[#volumes|volumes]] section of the specification.
===<tt>args</tt>===
<font color=darkgray>TODO</font>


====mountPath====
Also see: {{Internal|Dockerfile#ENTRYPOINT_and_CMD|Dockerfile ENTRYPOINT and CMD}}
Specifies the path within the container where the volume will be mounted. Must not contain ':'.


====subPath====
===<tt>resources</tt>===
Specifies the path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root).
====<tt>requests</tt>====
====<tt>limits</tt>====
===<span id='containerSecurityContext'></span><tt>securityContext</tt>===
{{External|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#securitycontext-v1-core}}
The section contains the security options this specific container should run with. See: {{Internal|Kubernetes_Security_Concepts#Pod_Security|Pod Security}}


====readOnly====
==<tt>initContainers</tt>==
The 'initContainers' section has the same schema as the [[#containers|containers]] section, described above. For more details about init containers, see: {{Internal|Kubernetes_Init_Containers#Overview|init Containers}}


==volumes==
==<tt>volumes</tt>==
List of [[#volumes_manifest|volumes]] that can be mounted by containers belonging to the pod. Volumes can be of several types: [[Kubernetes Pod and Container Concepts#Persistent_Volume_Claim|persistent volume claim]], [[Kubernetes Pod and Container Concepts#Host_Path|host path]], etc.

Latest revision as of 23:32, 1 August 2024

External

Internal

Overview

Workload resource controllers create pods from pod templates.

Pod Template

Pod templates are specifications for creating pods, and they are included in the manifests of the workload resources. Modifying the pod template or switching to a new pod template is detected by the workload resource controller, which usually shuts down the current running pods and replaces them with new pods built based on the new template. Each workload resource has its own rules for handling changes in the pod template.

Example

apiVersion: v1
kind: Pod
metadata:
  name: loop
  labels:
    color: blue
  annotations:
    ...
  generateName
spec:  
  restartPolicy: Always
  schedulerName: default-scheduler
  terminationGracePeriodSeconds: 120
  serviceAccountName: 'testServiceAccount'
  dnsPolicy: ClusterFirst
  imagePullSecrets:
    - name: myPullSecret1
    - name: myPullSecret2
    ...
  securityContext:
    runAsUser: 1000 # integer, not quoted
    runAsGroup: 3000 # integer, not quoted
    runAsNonRoot: true
    fsGroup: 2000
    fsGroupChangePolicy:
    seLinuxOptions:
    seccompProfile:
    supplementalGroups:
    sysctls:
  containers:
  - name: loop-container
    image: docker.io/ovidiufeodorov/loop:latest
    imagePullPolicy: Always
    lifecycle: [...]
    resources:
      requests:
        memory: '1024Mi'
        cpu: '500m'
      limits:
        memory: '4096Mi'
        cpu: '1000m'
    terminationMessagePath: /dev/termination-log
    terminationMessagePolicy: File
    command: ...
    ports:
    - containerPort: 8080
      protocol: TCP
      name: 'http'
    - containerPort: 8787
      protocol: TCP
    - containerPort: ...
      hostPort: ....
    env:
    - name: SOMETHING
      value: "something else"
    - name: A_BOOLEAN_VARIABLE
      value: "true" # must be quoted
    volumeMounts:
    - name: 'mount-0'
      mountPath: '/red'
      subPath: 'orange' 
    readinessProbe:
      # See Probe Template
    livenessProbe:
      # See Probe Template
    command: ['sh', '-c', 'while true; do sleep 2; done;']
    securityContext: 
      runAsGroup: 1001 # integer, not quoted
      runAsUser: 1001 # integer, not quoted
      runAsNonRoot: true 
      privileged: false
      allowPrivilegeEscalation: false
      readOnlyRootFilesystem: false
      capabilities:
      seLinuxOptions:
      procMount:
      seccompProfile:
  initContainers:
  - name: init-container1
    image: busybox
    command: ['sh', '-c', 'until nslookup myservice; do echo waiting for myservice; sleep 2; done;']
  volumes:
  - name: mount-0
    hostPath:
      # '/yellow' must contain an 'orange' sub-directory
      path: '/yellow'
  - name: mount-1
    persistentVolumeClaim:
     claimName: pvc1

.metadata Elements

labels

A pod can be tagged with labels. This section contains labels applied to the pod created based on this template. If the template is part of a deployment manifest, the section contains the labels applied to pods created by the deployment, and they must match the deployment's spec.selector values.

Also see:

Kubernetes Manifest Metadata | labels

generateName

"generateName" can be used to append random characters at the end of the base name, thus generating a unique pod name.

.spec Elements

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14/#podspec-v1-core

hostname

Optional field. If not specified, the hostname exposed to the processes running inside the pod will be the name of the pod.

restartPolicy

Optional field. See:

Container Restart Policy

serviceAccountName

The name of this pod's service account. Note that "serviceAccount" configuration element also exists, but it is deprecated. If not specified, defaults to the pod's namespace default service account.

dnsPolicy

Name Resolution inside a Pod

imagePullSecrets

Kubernetes Configuration Concepts | Secrets Required to Pull Images for Pods

securityContext

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#podsecuritycontext-v1-core

The pod-wide security context, applies to all containers. See:

Pod Security

containers

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#container-v1-core

"containers" contains an array with the pod's container definitions.

name

image

Kubernetes Container Image Pull Concepts

imagePullPolicy

https://kubernetes.io/docs/concepts/containers/images/
Kubernetes Container Image Pull Concepts

lifecycle

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#lifecycle-v1-core

volumeMounts

Mounting Volumes in Pods

ports

Contains an array specifying the ports exposed by the containers in this pod.

containerPort

protocol

name

An optional name given to the container port. If declared, it must be a IANA_SVC_NAME and unique within the pod. It can be used in the manifest of the associated service to designate the service's target port.

hostPort

Binds the container port to a host port.

env

Contains a list of name/value pairs representing the list of the environment variables to set in the container. In case of boolean variables, declare the boolean values as Strings ("true"/"false"), otherwise the template won't be processed correctly.

readinessProbe, livenessProbe

Probe Template

command

https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell

Optional field. If not present, the docker image's ENTRYPOINT is used. If present, represents the entrypoint array of the container. Not executed within a shell, so if a shell is required, must be specified as below. 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. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not.

Example:

  ...
  command: ['sh', '-c', 'while true; do echo .; sleep 1; done']

Each array element is a string, and in the above case, the array element that follows the '-c' element is passed as one string to the shell to be executed.

Alternative syntax:

  ...
  command:
  - /bin/sh
  - -c
  - 'i=0; echo $i'

The single quotes are optional, the content that follows "-" will be interpreted as a single string:

  ...
  command:
  - /bin/sh
  - -c
  - i=0; echo $i

Also see:

Dockerfile ENTRYPOINT and CMD

args

TODO

Also see:

Dockerfile ENTRYPOINT and CMD

resources

requests

limits

securityContext

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#securitycontext-v1-core

The section contains the security options this specific container should run with. See:

Pod Security

initContainers

The 'initContainers' section has the same schema as the containers section, described above. For more details about init containers, see:

init Containers

volumes

List of volumes that can be mounted by containers belonging to the pod. Volumes can be of several types: persistent volume claim, host path, etc.