Assign Pods to Nodes
how to assign a Kubernetes Pod to a particular node in a Kubernetes cluster.
Add a label to a node
#List the nodes in your cluster: kubectl get nodes #The output is similar to this: NAME STATUS AGE VERSION worker0 Ready 1d v1.6.0+fff5156 worker1 Ready 1d v1.6.0+fff5156 worker2 Ready 1d v1.6.0+fff5156 #chose one of your nodes, and add a label to it: #where <your-node-name> is the name of your chosen node. kubectl label nodes <your-node-name> disktype=ssd #Verify that your chosen node has a disktype=ssd label: kubectl get nodes –show-labels #The output is similar to this: #In the preceding output, you can see that the worker0 node has a disktype=ssd label. NAME STATUS AGE VERSION LABELS worker0 Ready 1d v1.6.0+fff5156 ...,disktype=ssd,kubernetes.io/hostname=worker0 worker1 Ready 1d v1.6.0+fff5156 ...,kubernetes.io/hostname=worker1 worker2 Ready 1d v1.6.0+fff5156 ...,kubernetes.io/hostname=worker2
Create a pod that gets scheduled to your chosen node
#List the nodes in your cluster kubectl get nodes #The output is similar to this NAME STATUS AGE VERSION worker0 Ready 1d v1.6.0+fff5156 worker1 Ready 1d v1.6.0+fff5156 worker2 Ready 1d v1.6.0+fff5156 #Chose one of your nodes, and add a label to it #where <your-node-name> is the name of your chosen node. kubectl label nodes <your-node-name> disktype=ssd #Verify that your chosen node has a disktype=ssd label: kubectl get nodes –show-labels #The output is similar to this NAME STATUS AGE VERSION LABELS worker0 Ready 1d v1.6.0+fff5156 ...,disktype=ssd,kubernetes.io/hostname=worker0 worker1 Ready 1d v1.6.0+fff5156 ...,kubernetes.io/hostname=worker1 worker2 Ready 1d v1.6.0+fff5156 ...,kubernetes.io/hostname=worker2 #In the preceding output, you can see that the worker0 node has a disktype=ssd label.
Create a pod that gets scheduled to your chosen node
apiVersion: v1
kind: Pod
metadata:
name: nginx
labels:
env: test
spec:
containers:
- name: nginx
image: nginx
imagePullPolicy: IfNotPresent
nodeSelector:
disktype: ssd
This pod configuration file describes a pod that has a node selector, disktype: ssd.
This means that the pod will get scheduled on a node that has a disktype=ssd label.
#Use the configuration file to create a pod that will get scheduled on your chosen node: kubectl create -f https://k8s.io/docs/tasks/configure-pod-container/pod.yaml #Verify that the pod is running on your chosen node: kubectl get pods --output=wide #The output is similar to this: NAME READY STATUS RESTARTS AGE IP NODE nginx 1/1 Running 0 13s 10.200.0.4 worker0
Configure Pod Initialization
how to use an Init Container to initialize a Pod before an application Container runs.
Create a Pod that has an Init Container
apiVersion: v1
kind: Pod
metadata:
name: init-demo
spec:
containers:
- name: nginx
image: nginx
ports:
- containerPort: 80
volumeMounts:
- name: workdir
mountPath: /usr/share/nginx/html
# These containers are run during pod initialization
initContainers:
- name: install
image: busybox
command:
- wget
- "-O"
- "/work-dir/index.html"
- http://kubernetes.io
volumeMounts:
- name: workdir
mountPath: "/work-dir"
dnsPolicy: Default
volumes:
- name: workdir
emptyDir: {}
In this exercise you create a Pod that has one application Container and one Init Container.
The init container runs to completion before the application container starts.
In the configuration file, you can see that the Pod has a Volume that the init container and the application container share.
The init container mounts the shared Volume at /work-dir,
and the application container mounts the shared Volume at /usr/share/nginx/html.
The init container runs the following command and then terminates:
wget -O /work-dir/index.html http://kubernetes.io
Notice that the init container writes the index.html file in the root directory of the nginx server.
#Create the Pod: kubectl create -f https://k8s.io/docs/tasks/configure-pod-container/init-containers.yaml #Verify that the nginx container is running: kubectl get pod init-demo #The output shows that the nginx container is running: NAME READY STATUS RESTARTS AGE init-demo 1/1 Running 0 1m #Get a shell into the nginx container running in the init-demo Pod: kubectl exec -it init-demo -- /bin/bash #In your shell, send a GET request to the nginx server: root@nginx:~# apt-get update root@nginx:~# apt-get install curl root@nginx:~# curl localhost #The output shows that nginx is serving the web page that was written by the init container: <!Doctype html> <html id="home"> <head> ... "url": "http://kubernetes.io/"}</script> </head> <body> ... <p>Kubernetes is open source giving you the freedom to take advantage ...</p> ...
Attach Handlers to Container Lifecycle Events
how to attach handlers to Container lifecycle events.
Kubernetes supports the postStart and preStop events.
Kubernetes sends the postStart event immediately after a Container is started,
and it sends the preStop event immediately before the Container is terminated.
Define postStart and preStop handlers
apiVersion: v1
kind: Pod
metadata:
name: lifecycle-demo
spec:
containers:
- name: lifecycle-demo-container
image: nginx
lifecycle:
postStart:
exec:
command: ["/bin/sh", "-c", "echo Hello from the postStart handler > /usr/share/message"]
preStop:
exec:
command: ["/usr/sbin/nginx","-s","quit"]
In this exercise, you create a Pod that has one Container.
The Container has handlers for the postStart and preStop events.
In the configuration file, you can see that the postStart command writes a message file to the Container’s /usr/share directory.
The preStop command shuts down nginx gracefully.
This is helpful if the Container is being terminated because of a failure.
#Create the Pod: kubectl create -f https://k8s.io/docs/tasks/configure-pod-container/lifecycle-events.yaml #Verify that the Container in the Pod is running: kubectl get pod lifecycle-demo #Get a shell into the Container running in your Pod: kubectl exec -it lifecycle-demo -- /bin/bash #In your shell, verify that the postStart handler created the message file: root@lifecycle-demo:/# cat /usr/share/message #The output shows the text written by the postStart handler: Hello from the postStart handler
Kubernetes sends the postStart event immediately after the Container is created.
There is no guarantee, however, that the postStart handler is called before the Container’s entrypoint is called.
The postStart handler runs asynchronously relative to the Container’s code, but Kubernetes’ management of the container blocks until the postStart handler completes.
The Container’s status is not set to RUNNING until the postStart handler completes.
Kubernetes sends the preStop event immediately before the Container is terminated.
Kubernetes’ management of the Container blocks until the preStop handler completes, unless the Pod’s grace period expires.
For more details, see Termination of Pods.
Note:
Kubernetes only sends the preStop event when a Pod is terminated.
This means that the preStop hook is not invoked when the Pod is completed.
This limitation is tracked in issue #55087.
Configure a Pod to Use a ConfigMap
ConfigMaps allow you to decouple configuration artifacts from image content to keep containerized applications portable.
This page provides a series of usage examples demonstrating how to create ConfigMaps and configure Pods using data stored in ConfigMaps.
Create a ConfigMap
#Use the kubectl create configmap command to create configmaps from directories, files, or literal values: kubectl create configmap <map-name> <data-source> #<map-name> is the name you want to assign to the ConfigMap #<data-source> is the directory, file, or literal value to draw the data from.
The data source corresponds to a key-value pair in the ConfigMap, where
- key = the file name or the key you provided on the command line, and
- value = the file contents or the literal value you provided on the command line.
You can use kubectl describe or kubectl get to retrieve information about a ConfigMap.
Create ConfigMaps from directories
You can use kubectl create configmap to create a ConfigMap from multiple files in the same directory.
mkdir -p configure-pod-container/configmap/kubectl/ wget https://k8s.io/docs/tasks/configure-pod-container/configmap/kubectl/game.properties -o configure-pod-container/configmap/kubectl/game.properties wget https://k8s.io/docs/tasks/configure-pod-container/configmap/kubectl/ui.properties -o configure-pod-container/configmap/kubectl/ui.properties kubectl create configmap game-config --from-file=configure-pod-container/configmap/kubectl/ #combines the contents of the configure-pod-container/configmap/kubectl/ ls configure-pod-container/configmap/kubectl/ game.properties ui.properties #into the following ConfigMap: kubectl describe configmaps game-config Name: game-config Namespace: default Labels: <none> Annotations: <none> Data ==== game.properties: 158 bytes ui.properties: 83 bytes
The game.properties and ui.properties files in the configure-pod-container/configmap/kubectl/ directory are represented in the data section of the ConfigMap.
kubectl get configmaps game-config -o yaml
apiVersion: v1
data:
game.properties: |
enemies=aliens
lives=3
enemies.cheat=true
enemies.cheat.level=noGoodRotten
secret.code.passphrase=UUDDLRLRBABAS
secret.code.allowed=true
secret.code.lives=30
ui.properties: |
color.good=purple
color.bad=yellow
allow.textmode=true
how.nice.to.look=fairlyNice
kind: ConfigMap
metadata:
creationTimestamp: 2016-02-18T18:52:05Z
name: game-config
namespace: default
resourceVersion: "516"
selfLink: /api/v1/namespaces/default/configmaps/game-config
uid: b4952dc3-d670-11e5-8cd0-68f728db1985
Create ConfigMaps from files
You can use kubectl create configmap to create a ConfigMap from an individual file, or from multiple files.
kubectl create configmap game-config-2 --from-file=configure-pod-container/configmap/kubectl/game.properties kubectl describe configmaps game-config-2 Name: game-config-2 Namespace: default Labels: <none> Annotations: <none> Data ==== game.properties: 158 bytes
You can pass in the --from-file argument multiple times to create a ConfigMap from multiple data sources.
kubectl create configmap game-config-2 --from-file=configure-pod-container/configmap/kubectl/game.properties --from-file=configure-pod-container/configmap/kubectl/ui.properties kubectl describe configmaps game-config-2 Name: game-config-2 Namespace: default Labels: <none> Annotations: <none> Data ==== game.properties: 158 bytes ui.properties: 83 bytes
Use the option --from-env-file to create a ConfigMap from an env-file:
# Env-files contain a list of environment variables.
# These syntax rules apply:
# Each line in an env file has to be in VAR=VAL format.
# Lines beginning with # (i.e. comments) are ignored.
# Blank lines are ignored.
# There is no special handling of quotation marks (i.e. they will be part of the ConfigMap value)).
wget https://k8s.io/docs/tasks/configure-pod-container/configmap/kubectl/game-env-file.properties -o configure-pod-container/configmap/kubectl/game-env-file.properties
cat configure-pod-container/configmap/kubectl/game-env-file.properties
enemies=aliens
lives=3
allowed="true"
# This comment and the empty line above it are ignored
kubectl create configmap game-config-env-file
--from-env-file=configure-pod-container/configmap/kubectl/game-env-file.properties
kubectl get configmap game-config-env-file -o yaml
apiVersion: v1
data:
allowed: '"true"'
enemies: aliens
lives: "3"
kind: ConfigMap
metadata:
creationTimestamp: 2017-12-27T18:36:28Z
name: game-config-env-file
namespace: default
resourceVersion: "809965"
selfLink: /api/v1/namespaces/default/configmaps/game-config-env-file
uid: d9d1ca5b-eb34-11e7-887b-42010a8002b8
When passing --from-env-file multiple times to create a ConfigMap from multiple data sources, only the last env-file is used:
wget https://k8s.io/docs/tasks/configure-pod-container/configmap/kubectl/ui-env-file.properties -o configure-pod-container/configmap/kubectl/ui-env-file.properties
kubectl create configmap config-multi-env-files
--from-env-file=configure-pod-container/configmap/kubectl/game-env-file.properties
--from-env-file=configure-pod-container/configmap/kubectl/ui-env-file.properties
kubectl get configmap config-multi-env-files -o yaml
apiVersion: v1
data:
color: purple
how: fairlyNice
textmode: "true"
kind: ConfigMap
metadata:
creationTimestamp: 2017-12-27T18:38:34Z
name: config-multi-env-files
namespace: default
resourceVersion: "810136"
selfLink: /api/v1/namespaces/default/configmaps/config-multi-env-files
uid: 252c4572-eb35-11e7-887b-42010a8002b8
Define the key to use when creating a ConfigMap from a file
You can define a key other than the file name to use in the data section of your ConfigMap when using the --from-file argument:
kubectl create configmap game-config-3 --from-file=<my-key-name>=<path-to-file>
where <my-key-name> is the key you want to use in the ConfigMap
and <path-to-file> is the location of the data source file you want the key to represent.
kubectl create configmap game-config-3 --from-file=game-special-key=configure-pod-container/configmap/kubectl/game.properties
kubectl get configmaps game-config-3 -o yaml
apiVersion: v1
data:
game-special-key: |
enemies=aliens
lives=3
enemies.cheat=true
enemies.cheat.level=noGoodRotten
secret.code.passphrase=UUDDLRLRBABAS
secret.code.allowed=true
secret.code.lives=30
kind: ConfigMap
metadata:
creationTimestamp: 2016-02-18T18:54:22Z
name: game-config-3
namespace: default
resourceVersion: "530"
selfLink: /api/v1/namespaces/default/configmaps/game-config-3
uid: 05f8da22-d671-11e5-8cd0-68f728db1985
Create ConfigMaps from literal values
You can use kubectl create configmap with the --from-literal argument to define a literal value from the command line:
kubectl create configmap special-config --from-literal=special.how=very --from-literal=special.type=charm
You can pass in multiple key-value pairs.
Each pair provided on the command line is represented as a separate entry in the data section of the ConfigMap.
kubectl get configmaps special-config -o yaml apiVersion: v1 data: special.how: very special.type: charm kind: ConfigMap metadata: creationTimestamp: 2016-02-18T19:14:38Z name: special-config namespace: default resourceVersion: "651" selfLink: /api/v1/namespaces/default/configmaps/special-config uid: dadce046-d673-11e5-8cd0-68f728db1985
Define Pod environment variables using ConfigMap data
Define a Pod environment variable with data from a single ConfigMap
#Define an environment variable as a key-value pair in a ConfigMap:
kubectl create configmap special-config --from-literal=special.how=very
#Assign the special.how value defined in the ConfigMap to the SPECIAL_LEVEL_KEY environment variable in the Pod specification.
kubectl edit pod dapi-test-pod
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: k8s.gcr.io/busybox
command: [ "/bin/sh", "-c", "env" ]
env:
# Define the environment variable
- name: SPECIAL_LEVEL_KEY
valueFrom:
configMapKeyRef:
# The ConfigMap containing the value you want to assign to SPECIAL_LEVEL_KEY
name: special-config
# Specify the key associated with the value
key: special.how
restartPolicy: Never
#Save the changes to the Pod specification. Now, the Pod’s output includes SPECIAL_LEVEL_KEY=very.
Define Pod environment variables with data from multiple ConfigMaps
#As with the previous example, create the ConfigMaps first.
apiVersion: v1
kind: ConfigMap
metadata:
name: special-config
namespace: default
data:
special.how: very
apiVersion: v1
kind: ConfigMap
metadata:
name: env-config
namespace: default
data:
log_level: INFO
#Define the environment variables in the Pod specification.
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: k8s.gcr.io/busybox
command: [ "/bin/sh", "-c", "env" ]
env:
- name: SPECIAL_LEVEL_KEY
valueFrom:
configMapKeyRef:
name: special-config
key: special.how
- name: LOG_LEVEL
valueFrom:
configMapKeyRef:
name: env-config
key: log_level
restartPolicy: Never
#Save the changes to the Pod specification. Now, the Pod’s output includes SPECIAL_LEVEL_KEY=very and LOG_LEVEL=info
Configure all key-value pairs in a ConfigMap as Pod environment variables
Note: This functionality is available to users running Kubernetes v1.6 and later.
#Create a ConfigMap containing multiple key-value pairs.
apiVersion: v1
kind: ConfigMap
metadata:
name: special-config
namespace: default
data:
SPECIAL_LEVEL: very
SPECIAL_TYPE: charm
#Use envFrom to define all of the ConfigMap’s data as Pod environment variables.
#The key from the ConfigMap becomes the environment variable name in the Pod.
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: k8s.gcr.io/busybox
command: [ "/bin/sh", "-c", "env" ]
envFrom:
- configMapRef:
name: special-config
restartPolicy: Never
#Save the changes to the Pod specification. Now, the Pod’s output includes SPECIAL_LEVEL=very and SPECIAL_TYPE=charm.
Use ConfigMap-defined environment variables in Pod commands
You can use ConfigMap-defined environment variables in the command section of the Pod specification using the $(VAR_NAME) Kubernetes substitution syntax.
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: k8s.gcr.io/busybox
command: [ "/bin/sh", "-c", "echo $(SPECIAL_LEVEL_KEY) $(SPECIAL_TYPE_KEY)" ]
env:
- name: SPECIAL_LEVEL_KEY
valueFrom:
configMapKeyRef:
name: special-config
key: SPECIAL_LEVEL
- name: SPECIAL_TYPE_KEY
valueFrom:
configMapKeyRef:
name: special-config
key: SPECIAL_TYPE
restartPolicy: Never
produces the following output in the test-container container:
very charm
Add ConfigMap data to a Volume
As explained in Create ConfigMaps from files,
when you create a ConfigMap using --from-file, the filename becomes a key stored in the data section of the ConfigMap.
The file contents become the key’s value.
apiVersion: v1 kind: ConfigMap metadata: name: special-config namespace: default data: special.level: very special.type: charm
Populate a Volume with data stored in a ConfigMap
Add the ConfigMap name under the volumes section of the Pod specification.
This adds the ConfigMap data to the directory specified as volumeMounts.mountPath (in this case, /etc/config).
The command section references the special.level item stored in the ConfigMap.
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: k8s.gcr.io/busybox
command: [ "/bin/sh", "-c", "ls /etc/config/" ]
volumeMounts:
- name: config-volume
mountPath: /etc/config
volumes:
- name: config-volume
configMap:
# Provide the name of the ConfigMap containing the files you want
# to add to the container
name: special-config
restartPolicy: Never
When the pod runs, the command ("ls /etc/config/") produces the output below:
special.level special.type
Caution: If there are some files in the /etc/config/ directory, they will be deleted.
Add ConfigMap data to a specific path in the Volume
Use the path field to specify the desired file path for specific ConfigMap items.
In this case, the special.level item will be mounted in the config-volume volume at /etc/config/keys.
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: k8s.gcr.io/busybox
command: [ "/bin/sh","-c","cat /etc/config/keys" ]
volumeMounts:
- name: config-volume
mountPath: /etc/config
volumes:
- name: config-volume
configMap:
name: special-config
items:
- key: special.level
path: keys
restartPolicy: Never
When the pod runs, the command ("cat /etc/config/keys") produces the output below
very
Project keys to specific paths and file permissions
You can project keys to specific paths and specific permissions on a per-file basis. The Secrets user guide explains the syntax.
Mounted ConfigMaps are updated automatically
When a ConfigMap already being consumed in a volume is updated, projected keys are eventually updated as well.
Kubelet is checking whether the mounted ConfigMap is fresh on every periodic sync.
However, it is using its local ttl-based cache for getting the current value of the ConfigMap. As a result, the total delay from the moment when the ConfigMap is updated to the moment when new keys are projected to the pod can be as long as kubelet sync period + ttl of ConfigMaps cache in kubelet.
Note: A container using a ConfigMap as a subPath volume will not receive ConfigMap updates.
Understanding ConfigMaps and Pods
The ConfigMap API resource stores configuration data as key-value pairs.
The data can be consumed in pods or provide the configurations for system components such as controllers.
ConfigMap is similar to Secrets, but provides a means of working with strings that don’t contain sensitive information.
Users and system components alike can store configuration data in ConfigMap.
Note:
ConfigMaps should reference properties files, not replace them.
Think of the ConfigMap as representing something similar to the Linux /etc directory and its contents.
For example, if you create a Kubernetes Volume from a ConfigMap, each data item in the ConfigMap is represented by an individual file in the volume.
The ConfigMap’s data field contains the configuration data.
can be simple – like individual properties defined using --from-literal –
or complex – like configuration files or JSON blobs defined using --from-file.
kind: ConfigMap
apiVersion: v1
metadata:
creationTimestamp: 2016-02-18T19:14:38Z
name: example-config
namespace: default
data:
# example of a simple property defined using --from-literal
example.property.1: hello
example.property.2: world
# example of a complex property defined using --from-file
example.property.file: |-
property.1=value-1
property.2=value-2
property.3=value-3
Restrictions
-
You must create a ConfigMap before referencing it in a Pod specification (unless you mark the ConfigMap as “optional”).
-
If you reference a ConfigMap that doesn’t exist, the Pod won’t start.
-
Likewise, references to keys that don’t exist in the ConfigMap will prevent the pod from starting.
-
-
If you use
envFromto define environment variables from ConfigMaps, keys that are considered invalid will be skipped.-
The pod will be allowed to start, but the invalid names will be recorded in the event log (
InvalidVariableNames). -
The log message lists each skipped key.
-
kubectl get events
LASTSEEN FIRSTSEEN COUNT NAME KIND SUBOBJECT TYPE REASON SOURCE MESSAGE
0s 0s 1 dapi-test-pod Pod Warning InvalidEnvironmentVariableNames {kubelet, 127.0.0.1} Keys [1badkey, 2alsobad] from the EnvFrom configMap default/myconfig were skipped since they are considered invalid environment variable names.
-
ConfigMaps reside in a specific namespace. A ConfigMap can only be referenced by pods residing in the same namespace.
-
Kubelet doesn’t support the use of ConfigMaps for pods not found on the API server. This includes pods created via the Kubelet’s –manifest-url flag, –config flag, or the Kubelet REST API.
Note: These are not commonly-used ways to create pods.