Chapter 3. Configure

Procedure

1. Log in to your OpenShift Container Platform cluster and retrieve the instance ID:

   $ INSTANCE_ID=$(oc get nodes -l 'node-role.kubernetes.io/worker' \
     -o jsonpath='{.items[0].spec.providerID}' | sed 's#[^ ]*/##g')

2. Retrieve the AWS region:

   $ AWS_REGION=$(oc get infrastructure/cluster -o jsonpath='{.status.platformStatus.aws.region}')

3. Retrieve the security group IDs and store them in an array:

   $ AWS_SG_IDS=($(aws ec2 describe-instances --instance-ids ${INSTANCE_ID} \
     --query 'Reservations[*].Instances[*].SecurityGroups[*].GroupId' \
     --output text --region $AWS_REGION))

4. For each security group ID, authorize the peer pods shim to access kata-agent communication, and set up the peer pods tunnel:

   $ for AWS_SG_ID in "${AWS_SG_IDS[@]}"; do \
     aws ec2 authorize-security-group-ingress --group-id $AWS_SG_ID --protocol tcp --port 15150 --source-group $AWS_SG_ID --region $AWS_REGION; \
     aws ec2 authorize-security-group-ingress --group-id $AWS_SG_ID --protocol tcp --port 9000 --source-group $AWS_SG_ID --region $AWS_REGION; \
   done

Procedure

1. Obtain the following values from your AWS instance:

   1. Retrieve and record the instance ID:

      $ INSTANCE_ID=$(oc get nodes -l 'node-role.kubernetes.io/worker' \
        -o jsonpath='{.items[0].spec.providerID}' | sed 's#[^ ]*/##g')

      This is used to retrieve other values for the secret object.

   2. Retrieve and record the AWS region:

      $ AWS_REGION=$(oc get infrastructure/cluster \
        -o jsonpath='{.status.platformStatus.aws.region}') \
        && echo "AWS_REGION: \"$AWS_REGION\""

   3. Retrieve and record the AWS subnet ID:

      $ AWS_SUBNET_ID=$(aws ec2 describe-instances --instance-ids ${INSTANCE_ID} \
        --query 'Reservations[*].Instances[*].SubnetId' --region ${AWS_REGION} \
          --output text) && echo "AWS_SUBNET_ID: \"$AWS_SUBNET_ID\""

   4. Retrieve and record the AWS VPC ID:

      $ AWS_VPC_ID=$(aws ec2 describe-instances --instance-ids ${INSTANCE_ID} \
        --query 'Reservations[*].Instances[*].VpcId' --region ${AWS_REGION} \
          --output text) && echo "AWS_VPC_ID: \"$AWS_VPC_ID\""

   5. Retrieve and record the AWS security group IDs:

      $ AWS_SG_IDS=$(aws ec2 describe-instances --instance-ids ${INSTANCE_ID} \
        --query 'Reservations[*].Instances[*].SecurityGroups[*].GroupId' \
        --region  $AWS_REGION --output json | jq -r '.[][][]' | paste -sd ",") \
          && echo "AWS_SG_IDS: \"$AWS_SG_IDS\""

2. Create a peer-pods-cm.yaml manifest file according to the following example:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: peer-pods-cm
     namespace: openshift-sandboxed-containers-operator
   data:
     CLOUD_PROVIDER: "aws"
     VXLAN_PORT: "9000"
     PROXY_TIMEOUT: "5m"
     PODVM_INSTANCE_TYPE: "t3.medium"
     PODVM_INSTANCE_TYPES: "t2.small,t2.medium,t3.large"
     PODVM_AMI_ID: "<podvm_ami_id>"
     AWS_REGION: "<aws_region>"
     AWS_SUBNET_ID: "<aws_subnet_id>"
     AWS_VPC_ID: "<aws_vpc_id>"
     AWS_SG_IDS: "<aws_sg_ids>"
     TAGS: "key1=value1,key2=value2"
     PEERPODS_LIMIT_PER_NODE: "10"
     ROOT_VOLUME_SIZE: "6"
     DISABLECVM: "true"

   PODVM_INSTANCE_TYPE

   Defines the default instance type that is used if the instance type is not defined in the workload object.

   PODVM_INSTANCE_TYPES

   Specify the allowed instance types, without spaces, for creating the pod. You can define smaller instance types for workloads that need less memory and fewer CPUs or larger instance types for larger workloads.

   PODVM_AMI_ID

   This value is populated when you run the KataConfig CR, using an AMI ID based on your cluster credentials. If you create your own AMI, specify the correct AMI ID.

   TAGS

   You can configure custom tags as key:value pairs for pod VM instances to track peer pod costs or to identify peer pods in different clusters.

   PEERPODS_LIMIT_PER_NODE

   You can increase this value to run more peer pods on a node. The default value is 10.

   ROOT_VOLUME_SIZE

   You can increase this value for pods with larger container images. Specify the root volume size in gigabytes for the pod VM. The default and minimum size is 6 GB.

3. Create the config map by running the following command:

   $ oc create -f peer-pods-cm.yaml

Procedure

1. Create an example-kataconfig.yaml manifest file according to the following example:

   apiVersion: kataconfiguration.openshift.io/v1
   kind: KataConfig
   metadata:
     name: example-kataconfig
   spec:
     enablePeerPods: true
     logLevel: info
   #  kataConfigPoolSelector:
   #    matchLabels:
   #      <label_key>: '<label_value>'

   <label_key>: '<label_value>'

   Optional: If you have applied node labels to install kata-remote on specific nodes, specify the key and value, for example, kata-remote: 'true'.

2. Create the KataConfig CR by running the following command:

   $ oc create -f example-kataconfig.yaml

   The new KataConfig CR is created and installs kata-remote as a runtime class on the worker nodes.

   Wait for the kata-remote installation to complete and the worker nodes to reboot before verifying the installation.

3. Monitor the installation progress by running the following command:

   $ watch "oc describe kataconfig | sed -n /^Status:/,/^Events/p"

   When the status of all workers under kataNodes is installed and the condition InProgress is False without specifying a reason, the kata-remote is installed on the cluster.

4. Verify the daemon set by running the following command:

   $ oc get -n openshift-sandboxed-containers-operator ds/osc-caa-ds

5. Verify the runtime classes by running the following command:

   $ oc get runtimeclass

   +

Procedure

1. Obtain the config map you created for the peer pods:

   $ oc get configmap peer-pods-cm -n openshift-sandboxed-containers-operator -o yaml

2. Check the status stanza of the YAML file.

   If the PODVM_AMI_ID parameter is populated, the pod VM image was created successfully.

Troubleshooting

1. Retrieve the events log by running the following command:

   $ oc get events -n openshift-sandboxed-containers-operator --field-selector involvedObject.name=osc-podvm-image-creation

2. Retrieve the job log by running the following command:

   $ oc logs -n openshift-sandboxed-containers-operator jobs/osc-podvm-image-creation

Procedure

1. Create an initdata.toml file to modify the default policy:

   algorithm = "sha256"
   version = "0.1.0"
   
   [data]
   "aa.toml" = '''
   '''
   
   "policy.rego" = '''
   package agent_policy
   
   default AddARPNeighborsRequest := true
   default AddSwapRequest := true
   default CloseStdinRequest := true
   default CopyFileRequest := true
   default CreateContainerRequest := true
   default CreateSandboxRequest := true
   default DestroySandboxRequest := true
   default GetMetricsRequest := true
   default GetOOMEventRequest := true
   default GuestDetailsRequest := true
   default ListInterfacesRequest := true
   default ListRoutesRequest := true
   default MemHotplugByProbeRequest := true
   default OnlineCPUMemRequest := true
   default PauseContainerRequest := true
   default PullImageRequest := true
   default ReadStreamRequest := false
   default RemoveContainerRequest := true
   default RemoveStaleVirtiofsShareMountsRequest := true
   default ReseedRandomDevRequest := true
   default ResumeContainerRequest := true
   default SetGuestDateTimeRequest := true
   default SignalProcessRequest := true
   default StartContainerRequest := true
   default StartTracingRequest := true
   default StatsContainerRequest := true
   default StopTracingRequest := true
   default TtyWinResizeRequest := true
   default UpdateContainerRequest := true
   default UpdateEphemeralMountsRequest := true
   default UpdateInterfaceRequest := true
   default UpdateRoutesRequest := true
   default WaitProcessRequest := true
   default ExecProcessRequest := false
   default SetPolicyRequest := false
   default WriteStreamRequest := false
   
   default ExecProcessRequest := false
   '''

   The default policy allows all API calls. Adjust the true or false values to customize the policy further based on your needs.

2. Convert the initdata.toml file to a Base64-encoded string by running the following command:

   $ cat initdata.toml | gzip | base64 -w0 > initdata.txt

   Record this string to use in the pod manifest.

3. Add the Base64-encoded initdata string to the my-pod.yaml manifest:

   apiVersion: v1
   kind: Pod
   metadata:
     name: my-pod
     annotations:
       io.katacontainers.config.hypervisor.cc_init_data: <initdata_string>
   spec:
     runtimeClassName: kata-remote
     containers:
     - name: <container_name>
       image: registry.access.redhat.com/ubi9/ubi:latest
       command:
       - sleep
       - "36000"
       securityContext:
         privileged: false
         seccompProfile:
           type: RuntimeDefault

4. Create the pod by running the following command:

   $ oc create -f my-pod.yaml

Procedure

1. Set the NS variable to the namespace where you deploy your peer pods:

   $ NS=<namespace>

2. Copy the pull secret to the peer pod namespace:

   $ oc get secret pull-secret -n openshift-config -o yaml \
     | sed "s/namespace: openshift-config/namespace: ${NS}/" \
     | oc apply -n "${NS}" -f -

   You can use the cluster pull secret, as in this example, or a custom pull secret.

3. Optional: Link the pull secret to the default service account:

   $ oc secrets link default pull-secret --for=pull -n ${NS}

Procedure

1. Create a my-pod-manifest.yaml file according to the following example:

   apiVersion: v1
   kind: Pod
   metadata:
     name: my-pod-manifest
     annotations:
       io.katacontainers.config.hypervisor.image: "<custom_image_id>"
   spec:
     runtimeClassName: kata-remote
     containers:
     - name: <example_container>
       image: registry.access.redhat.com/ubi9/ubi:9.3
       command: ["sleep", "36000"]

2. Create the pod by running the following command:

   $ oc create -f my-pod-manifest.yaml

Procedure

1. Add spec.runtimeClassName: kata-remote to the manifest of each pod-templated workload object as in the following example:

   apiVersion: v1
   kind: <object>
   # ...
   spec:
     runtimeClassName: kata-remote
   # ...

2. Optional: To override the default instance type, add the following annotation with an instance type that is defined in the peer pods config map:

   apiVersion: v1
   kind: <object>
   metadata:
     annotations:
       io.katacontainers.config.hypervisor.machine_type: <instance>
   # ...

3. Optional: To use an automatic instance type, add the following annotations:

   apiVersion: v1
   kind: <Pod>
   metadata:
     annotations:
       io.katacontainers.config.hypervisor.default_vcpus: <vcpus>
       io.katacontainers.config.hypervisor.default_memory: <memory>
   # ...

   The workload will run on an automatic instance type based on the amount of memory available.

4. Apply the changes to the workload object by running the following command:

   $ oc apply -f <object.yaml>

   OpenShift Container Platform creates the workload object and begins scheduling it.