Chapter 1. Working with pods

1. Change to the project:

   $ oc project <project-name>

2. Run the following command:

   $ oc get pods

   For example:

   $ oc get pods -n openshift-console

   Example output

   NAME                       READY   STATUS    RESTARTS   AGE
   console-698d866b78-bnshf   1/1     Running   2          165m
   console-698d866b78-m87pm   1/1     Running   2          165m

   Add the -o wide flags to view the pod IP address and the node where the pod is located.

   $ oc get pods -o wide

   Example output

   NAME                       READY   STATUS    RESTARTS   AGE    IP            NODE                           NOMINATED NODE
   console-698d866b78-bnshf   1/1     Running   2          166m   10.128.0.24   ip-10-0-152-71.ec2.internal    <none>
   console-698d866b78-m87pm   1/1     Running   2          166m   10.129.0.23   ip-10-0-173-237.ec2.internal   <none>

1. Run the following command:

   $ oc adm top pods

   For example:

   $ oc adm top pods -n openshift-console

   Example output

   NAME                         CPU(cores)   MEMORY(bytes)
   console-7f58c69899-q8c8k     0m           22Mi
   console-7f58c69899-xhbgg     0m           25Mi
   downloads-594fcccf94-bcxk8   3m           18Mi
   downloads-594fcccf94-kv4p6   2m           15Mi

2. Run the following command to view the usage statistics for pods with labels:

   $ oc adm top pod --selector=''

   You must choose the selector (label query) to filter on. Supports =, ==, and !=.

Procedure (UI)

1. In the OpenShift Container Platform console, navigate to Workloads Pods or navigate to the pod through the resource you want to investigate.

   Note

   Some resources, such as builds, do not have pods to query directly. In such instances, you can locate the Logs link on the Details page for the resource.

2. Select a project from the drop-down menu.
3. Click the name of the pod you want to investigate.
4. Click Logs.

1. Write an object definition JSON file, and specify the data traffic speed using kubernetes.io/ingress-bandwidth and kubernetes.io/egress-bandwidth annotations. For example, to limit both pod egress and ingress bandwidth to 10M/s:

   Limited Pod Object Definition

   {
       "kind": "Pod",
       "spec": {
           "containers": [
               {
                   "image": "openshift/hello-openshift",
                   "name": "hello-openshift"
               }
           ]
       },
       "apiVersion": "v1",
       "metadata": {
           "name": "iperf-slow",
           "annotations": {
               "kubernetes.io/ingress-bandwidth": "10M",
               "kubernetes.io/egress-bandwidth": "10M"
           }
       }
   }

2. Create the pod using the object definition:

   $ oc create -f <file_or_dir_path>

1. Create a Pod spec or edit existing pods to include the system-cluster-critical priority class:

   spec:
     template:
       metadata:
         name: critical-pod
       priorityClassName: system-cluster-critical 1

   1

   Default priority class for pods that should never be evicted from a node.

   Alternatively, you can specify system-node-critical for pods that are important to the cluster but can be removed if necessary.

2. Create the pod:

   $ oc create -f <file-name>.yaml

1. Perform one of the following one of the following:

   • To scale based on the percent of CPU utilization, create a HorizontalPodAutoscaler object for an existing DeploymentConfig object:

     $ oc autoscale dc/<dc-name> \1
       --min <number> \2
       --max <number> \3
       --cpu-percent=<percent> 4

     1

     Specify the name of the DeploymentConfig object. The object must exist.

     2

     Optionally, specify the minimum number of replicas when scaling down.

     3

     Specify the maximum number of replicas when scaling up.

     4

     Specify the target average CPU utilization over all the pods, represented as a percent of requested CPU. If not specified or negative, a default autoscaling policy is used.

   • To scale based on the percent of CPU utilization, create a HorizontalPodAutoscaler object for an existing replication controller:

     $ oc autoscale rc/<rc-name> 1
       --min <number> \2
       --max <number> \3
       --cpu-percent=<percent> 4

     1

     Specify the name of the replication controller. The object must exist.

     2

     Specify the minimum number of replicas when scaling down.

     3

     Specify the maximum number of replicas when scaling up.

     4

     Specify the target average CPU utilization over all the pods, represented as a percent of requested CPU. If not specified or negative, a default autoscaling policy is used.

   • To scale for a specific CPU value, create a YAML file similar to the following for an existing DeploymentConfig object or replication controller:

     1. Create a YAML file similar to the following:

        apiVersion: autoscaling/v2beta2 1
        kind: HorizontalPodAutoscaler
        metadata:
          name: cpu-autoscale 2
          namespace: default
        spec:
          scaleTargetRef:
            apiVersion: v1 3
            kind: ReplicationController 4
            name: example 5
          minReplicas: 1 6
          maxReplicas: 10 7
          metrics: 8
          - type: Resource
            resource:
              name: cpu 9
              target:
                type: AverageValue 10
                averageValue: 500m 11

        1

        Use the autoscaling/v2beta2 API.

        2

        Specify a name for this horizontal pod autoscaler object.

        3

        Specify the API version of the object to scale:

        • For a replication controller, use v1,
        • For a DeploymentConfig object, use apps.openshift.io/v1.

        4

        Specify the kind of object to scale, either ReplicationController or DeploymentConfig.

        5

        Specify the name of the object to scale. The object must exist.

        6

        Specify the minimum number of replicas when scaling down.

        7

        Specify the maximum number of replicas when scaling up.

        8

        Use the metrics parameter for memory utilization.

        9

        Specify cpu for CPU utilization.

        10

        Set to AverageValue.

        11

        Set to averageValue with the targeted CPU value.

     2. Create the horizontal pod autoscaler:

        $ oc create -f <file-name>.yaml

2. Verify that the horizontal pod autoscaler was created:

   $ oc get hpa cpu-autoscale

   Example output

   NAME            REFERENCE                       TARGETS         MINPODS   MAXPODS   REPLICAS   AGE
   cpu-autoscale   ReplicationController/example   173m/500m       1         10        1          20m

1. View the current state of the image-registry deployment:

   $ oc get dc image-registry

   Example output

   NAME             REVISION   DESIRED   CURRENT   TRIGGERED BY
   image-registry   1          3         3         config

2. Autoscale the image-registry DeploymentConfig object:

   $ oc autoscale dc/image-registry --min=5 --max=7 --cpu-percent=75

   Example output

   horizontalpodautoscaler.autoscaling/image-registry autoscaled

3. View the new state of the deployment:

   $ oc get dc image-registry

   There are now 5 pods in the deployment:

   Example output

   NAME             REVISION   DESIRED   CURRENT   TRIGGERED BY
   image-registry   1          5         5         config

1. Create a YAML file for one of the following:

   • To scale for a specific memory value, create a HorizontalPodAutoscaler object similar to the following for an existing DeploymentConfig object or replication controller:

     Example output

     apiVersion: autoscaling/v2beta2 1
     kind: HorizontalPodAutoscaler
     metadata:
       name: hpa-resource-metrics-memory 2
       namespace: default
     spec:
       scaleTargetRef:
         apiVersion: v1 3
         kind: ReplicationController 4
         name: example 5
       minReplicas: 1 6
       maxReplicas: 10 7
       metrics: 8
       - type: Resource
         resource:
           name: memory 9
           target:
             type: AverageValue 10
             averageValue: 500Mi 11
       behavior: 12
         scaleDown:
           stabilizationWindowSeconds: 300
           policies:
           - type: Pods
             value: 4
             periodSeconds: 60
           - type: Percent
             value: 10
             periodSeconds: 60
           selectPolicy: Max

     1

     Use the autoscaling/v2beta2 API.

     2

     Specify a name for this horizontal pod autoscaler object.

     3

     Specify the API version of the object to scale:

     • For a replication controller, use v1,
     • For a DeploymentConfig object, use apps.openshift.io/v1.

     4

     Specify the kind of object to scale, either ReplicationController or DeploymentConfig.

     5

     Specify the name of the object to scale. The object must exist.

     6

     Specify the minimum number of replicas when scaling down.

     7

     Specify the maximum number of replicas when scaling up.

     8

     Use the metrics parameter for memory utilization.

     9

     Specify memory for memory utilization.

     10

     Set the type to AverageValue.

     11

     Specify averageValue and a specific memory value.

     12

     Optional: Specify a scaling policy to control the rate of scaling up or down.

   • To scale for a percentage, create a HorizontalPodAutoscaler object similar to the following:

     Example output

     apiVersion: autoscaling/v2beta2 1
     kind: HorizontalPodAutoscaler
     metadata:
       name: memory-autoscale 2
       namespace: default
     spec:
       scaleTargetRef:
         apiVersion: apps.openshift.io/v1 3
         kind: DeploymentConfig 4
         name: example 5
       minReplicas: 1 6
       maxReplicas: 10 7
       metrics: 8
       - type: Resource
         resource:
           name: memory 9
           target:
             type: Utilization 10
             averageUtilization: 50 11
       behavior: 12
         scaleUp:
           stabilizationWindowSeconds: 180
           policies:
           - type: Pods
             value: 6
             periodSeconds: 120
           - type: Percent
             value: 10
             periodSeconds: 120
           selectPolicy: Max

     1

     Use the autoscaling/v2beta2 API.

     2

     Specify a name for this horizontal pod autoscaler object.

     3

     Specify the API version of the object to scale:

     • For a replication controller, use v1,
     • For a DeploymentConfig object, use apps.openshift.io/v1.

     4

     Specify the kind of object to scale, either ReplicationController or DeploymentConfig.

     5

     Specify the name of the object to scale. The object must exist.

     6

     Specify the minimum number of replicas when scaling down.

     7

     Specify the maximum number of replicas when scaling up.

     8

     Use the metrics parameter for memory utilization.

     9

     Specify memory for memory utilization.

     10

     Set to Utilization.

     11

     Specify averageUtilization and a target average memory utilization over all the pods, represented as a percent of requested memory. The target pods must have memory requests configured.

     12

     Optional: Specify a scaling policy to control the rate of scaling up or down.

2. Create the horizontal pod autoscaler:

   $ oc create -f <file-name>.yaml

   For example:

   $ oc create -f hpa.yaml

   Example output

   horizontalpodautoscaler.autoscaling/hpa-resource-metrics-memory created

3. Verify that the horizontal pod autoscaler was created:

   $ oc get hpa hpa-resource-metrics-memory

   Example output

   NAME                          REFERENCE                       TARGETS         MINPODS   MAXPODS   REPLICAS   AGE
   hpa-resource-metrics-memory   ReplicationController/example   2441216/500Mi   1         10        1          20m

   $ oc describe hpa hpa-resource-metrics-memory

   Example output

   Name:                        hpa-resource-metrics-memory
   Namespace:                   default
   Labels:                      <none>
   Annotations:                 <none>
   CreationTimestamp:           Wed, 04 Mar 2020 16:31:37 +0530
   Reference:                   ReplicationController/example
   Metrics:                     ( current / target )
     resource memory on pods:   2441216 / 500Mi
   Min replicas:                1
   Max replicas:                10
   ReplicationController pods:  1 current / 1 desired
   Conditions:
     Type            Status  Reason              Message
     ----            ------  ------              -------
     AbleToScale     True    ReadyForNewScale    recommended size matches current size
     ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
     ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
   Events:
     Type     Reason                   Age                 From                       Message
     ----     ------                   ----                ----                       -------
     Normal   SuccessfulRescale        6m34s               horizontal-pod-autoscaler  New size: 1; reason: All metrics below target

Procedure

1. In the OpenShift Container Platform web console, click Operators OperatorHub.
2. Choose VerticalPodAutoscaler from the list of available Operators, and click Install.
3. On the Install Operator page, ensure that the Operator recommended namespace option is selected. This installs the Operator in the mandatory openshift-vertical-pod-autoscaler namespace, which is automatically created if it does not exist.
4. Click Install.

5. Verify the installation by listing the VPA Operator components:

   1. Navigate to Workloads Pods.
   2. Select the openshift-vertical-pod-autoscaler project from the drop-down menu and verify that there are four pods running.
   3. Navigate to Workloads Deployments to verify that there are four deployments running.

6. Optional. Verify the installation in the OpenShift Container Platform CLI using the following command:

   $ oc get all -n openshift-vertical-pod-autoscaler

   The output shows four pods and four deplyoments:

   Example output

   NAME                                                    READY   STATUS    RESTARTS   AGE
   pod/vertical-pod-autoscaler-operator-85b4569c47-2gmhc   1/1     Running   0          3m13s
   pod/vpa-admission-plugin-default-67644fc87f-xq7k9       1/1     Running   0          2m56s
   pod/vpa-recommender-default-7c54764b59-8gckt            1/1     Running   0          2m56s
   pod/vpa-updater-default-7f6cc87858-47vw9                1/1     Running   0          2m56s
   
   NAME                  TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
   service/vpa-webhook   ClusterIP   172.30.53.206   <none>        443/TCP   2m56s
   
   NAME                                               READY   UP-TO-DATE   AVAILABLE   AGE
   deployment.apps/vertical-pod-autoscaler-operator   1/1     1            1           3m13s
   deployment.apps/vpa-admission-plugin-default       1/1     1            1           2m56s
   deployment.apps/vpa-recommender-default            1/1     1            1           2m56s
   deployment.apps/vpa-updater-default                1/1     1            1           2m56s
   
   NAME                                                          DESIRED   CURRENT   READY   AGE
   replicaset.apps/vertical-pod-autoscaler-operator-85b4569c47   1         1         1       3m13s
   replicaset.apps/vpa-admission-plugin-default-67644fc87f       1         1         1       2m56s
   replicaset.apps/vpa-recommender-default-7c54764b59            1         1         1       2m56s
   replicaset.apps/vpa-updater-default-7f6cc87858                1         1         1       2m56s

1. Change to the project where the workload object you want to scale is located.

   1. Create a VPA CR YAML file:

      apiVersion: autoscaling.k8s.io/v1
      kind: VerticalPodAutoscaler
      metadata:
        name: vpa-recommender
      spec:
        targetRef:
          apiVersion: "apps/v1"
          kind:       Deployment 1
          name:       frontend 2
        updatePolicy:
          updateMode: "Auto" 3
        resourcePolicy: 4
          containerPolicies:
          - containerName: my-opt-sidecar
            mode: "Off"

      1

      Specify the type of workload object you want this VPA to manage: Deployment, StatefulSet, Job, DaemonSet, ReplicaSet, or ReplicationController.

      2

      Specify the name of an existing workload object you want this VPA to manage.

      3

      Specify the VPA mode:

      • auto to automatically apply the recommended resources on pods associated with the controller. The VPA terminates existing pods and creates new pods with the recommended resource limits and requests.
      • recreate to automatically apply the recommended resources on pods associated with the workload object. The VPA terminates existing pods and creates new pods with the recommended resource limits and requests. The recreate mode should be used rarely, only if you need to ensure that the pods are restarted whenever the resource request changes.
      • initial to automatically apply the recommended resources when pods associated with the workload object are created. The VPA does not update the pods as it learns new resource recommendations.
      • off to only generate resource recommendations for the pods associated with the workload object. The VPA does not update the pods as it learns new resource recommendations and does not apply the recommendations to new pods.

      4

      Optional. Specify the containers you want to opt-out and set the mode to Off.

   2. Create the VPA CR:

      $ oc create -f <file-name>.yaml

      After a few moments, the VPA learns the resource usage of the containers in the pods associated with the workload object.

      You can view the VPA recommendations using the following command:

      $ oc get vpa <vpa-name> --output yaml

      The output shows the recommendations for CPU and memory requests, similar to the following:

      Example output

      ...
      status:
      
      ...
      
        recommendation:
          containerRecommendations:
          - containerName: frontend
            lowerBound: 1
              cpu: 25m
              memory: 262144k
            target: 2
              cpu: 25m
              memory: 262144k
            uncappedTarget: 3
              cpu: 25m
              memory: 262144k
            upperBound: 4
              cpu: 262m
              memory: "274357142"
          - containerName: backend
            lowerBound:
              cpu: 12m
              memory: 131072k
            target:
              cpu: 12m
              memory: 131072k
            uncappedTarget:
              cpu: 12m
              memory: 131072k
            upperBound:
              cpu: 476m
              memory: "498558823"
      
      ...

      1

      lowerBound is the minimum recommended resource levels.

      2

      target is the recommended resource levels.

      3

      upperBound is the highest recommended resource levels.

      4

      uncappedTarget is the most recent resource recommendations.

Procedure

1. In the OpenShift Container Platform web console, click Operators Installed Operators.
2. Switch to the openshift-vertical-pod-autoscaler project.
3. Find the VerticalPodAutoscaler Operator and click the Options menu. Select Uninstall Operator.
4. In the dialog box, click Uninstall.

1. Delete the secret:

   $ oc delete secret <secret_name>

2. Clear the annotations:

   $ oc annotate service <service_name> service.alpha.openshift.io/serving-cert-generation-error-

   $ oc annotate service <service_name> service.alpha.openshift.io/serving-cert-generation-error-num-

1. Obtain the label associated with the static MachineConfigPool CRD for the type of node you want to configure. Perform one of the following steps:

   1. View the machine config:

      # oc describe machineconfig <name>

      For example:

      # oc describe machineconfig 00-worker

      Example output

      Name:         00-worker
      Namespace:
      Labels:       machineconfiguration.openshift.io/role=worker 1

      1 1

      Label required for the Device Manager.

Procedure

1. Create a custom resource (CR) for your configuration change.

   Sample configuration for a Device Manager CR

   apiVersion: machineconfiguration.openshift.io/v1
   kind: KubeletConfig
   metadata:
     name: devicemgr 1
   spec:
     machineConfigPoolSelector:
       matchLabels:
          machineconfiguration.openshift.io: devicemgr 2
     kubeletConfig:
       feature-gates:
         - DevicePlugins=true 3

   1

   Assign a name to CR.

   2

   Enter the label from the Machine Config Pool.

   3

   Set DevicePlugins to 'true`.

2. Create the Device Manager:

   $ oc create -f devicemgr.yaml

   Example output

   kubeletconfig.machineconfiguration.openshift.io/devicemgr created

3. Ensure that Device Manager was actually enabled by confirming that /var/lib/kubelet/device-plugins/kubelet.sock is created on the node. This is the UNIX domain socket on which the Device Manager gRPC server listens for new plug-in registrations. This sock file is created when the Kubelet is started only if Device Manager is enabled.

1. Create one or more priority classes:

   1. Specify a name and value for the priority.
   2. Optionally specify the globalDefault field in the priority class and a description.

2. Create a Pod spec or edit existing pods to include the name of a priority class, similar to the following:

   Sample Pod spec with priority class name

   apiVersion: v1
   kind: Pod
   metadata:
     name: nginx
     labels:
       env: test
   spec:
     containers:
     - name: nginx
       image: nginx
       imagePullPolicy: IfNotPresent
     priorityClassName: high-priority 1

   1

   Specify the priority class to use with this pod.

3. Create the pod:

   $ oc create -f <file-name>.yaml

   You can add the priority name directly to the pod configuration or to a pod template.

Procedure

1. Add labels to a node by using a machine set or editing the node directly:

   • Use a MachineSet object to add labels to nodes managed by the machine set when a node is created:

     1. Run the following command to add labels to a MachineSet object:

        $ oc patch MachineSet <name> --type='json' -p='[{"op":"add","path":"/spec/template/spec/metadata/labels", "value":{"<key>"="<value>","<key>"="<value>"}}]'  -n openshift-machine-api

        For example:

        $ oc patch MachineSet abc612-msrtw-worker-us-east-1c  --type='json' -p='[{"op":"add","path":"/spec/template/spec/metadata/labels", "value":{"type":"user-node","region":"east"}}]'  -n openshift-machine-api

     2. Verify that the labels are added to the MachineSet object by using the oc edit command:

        For example:

        $ oc edit MachineSet abc612-msrtw-worker-us-east-1c -n openshift-machine-api

        Example MachineSet object

        apiVersion: machine.openshift.io/v1beta1
        kind: MachineSet
        
        ....
        
        spec:
        ...
          template:
            metadata:
        ...
            spec:
              metadata:
                labels:
                  region: east
                  type: user-node
        ....

   • Add labels directly to a node:

     1. Edit the Node object for the node:

        $ oc label nodes <name> <key>=<value>

        For example, to label a node:

        $ oc label nodes ip-10-0-142-25.ec2.internal type=user-node region=east

     2. Verify that the labels are added to the node:

        $ oc get nodes -l type=user-node,region=east

        Example output

        NAME                          STATUS   ROLES    AGE   VERSION
        ip-10-0-142-25.ec2.internal   Ready    worker   17m   v1.18.3+002a51f

2. Add the matching node selector a pod:

   • To add a node selector to existing and future pods, add a node selector to the controlling object for the pods:

     Example ReplicaSet object with labels

     kind: ReplicaSet
     
     ....
     
     spec:
     
     ....
     
       template:
         metadata:
           creationTimestamp: null
           labels:
             ingresscontroller.operator.openshift.io/deployment-ingresscontroller: default
             pod-template-hash: 66d5cf9464
         spec:
           nodeSelector:
             beta.kubernetes.io/os: linux
             node-role.kubernetes.io/worker: ''
             type: user-node 1

     1

     Add the node selector.

   • To add a node selector to a specific, new pod, add the selector to the Pod object directly:

     Example Pod object with a node selector

     apiVersion: v1
     kind: Pod
     
     ....
     
     spec:
       nodeSelector:
         region: east
         type: user-node

     Note

     You cannot add a node selector directly to an existing scheduled pod.