Update flow.md

pareenaverma · web-flow · commit c431d1da19a7 · 2026-01-06T16:59:17.000-05:00
diff --git a/content/learning-paths/servers-and-cloud-computing/cca-kata/flow.md b/content/learning-paths/servers-and-cloud-computing/cca-kata/flow.md
@@ -8,11 +8,11 @@ weight: 3 # 1 is first, 2 is second, etc.
 layout: "learningpathall"
 ---
 ## Overview
-In this section you will
+In this section you will:
 
-- run the **Trustee services** (AS, KBS, RVPS) and a local docker image registry.
-- publish an encrypted docker image.
-- on **Arm FVP** you will start a confidential container using the encrypted image and confirm that it runs in a **CCA realm**.
+   * Start the Trustee services (AS, KBS, RVPS) along with a local Docker registry.
+   * Publish an encrypted container image to the local registry.
+   * Launch a Confidential Container on the Arm FVP using the encrypted image and verify it runs inside an Arm CCA Realm.
 
 ## Install dependencies
 
@@ -39,7 +39,7 @@ Install Git and Docker packages:
 sudo apt-get install -y git docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
 ```
 
-Add your user name to the Docker group (open a new shell after this so the change takes effect):
+Add your user name to the Docker group (open a new shell afterwards so the change takes effect):
 ``` bash
 sudo usermod -aG docker $USER
 newgrp docker
@@ -52,28 +52,28 @@ Clone the **kata** branch of the **cca-trustee** repository:
 git clone -b kata https://github.com/ArmDeveloperEcosystem/cca-trustee.git
 ```
 
-This repository contains configuration to run Trustee services (KBS, AS, RVPS, keyprovider) with CCA attestation support as a simple cluster. The configuration is based on the recommended settings from [KBS Cluster](https://github.com/confidential-containers/trustee/blob/main/kbs/docs/cluster.md).
+This repository includes a Docker Compose configuration that starts Trustee services (KBS, AS, RVPS, and a key provider) with Arm CCA attestation support as a simple local cluster. The configuration follows the recommended approach described in the Trustee documentation for running a [KBS Cluster](https://github.com/confidential-containers/trustee/blob/main/kbs/docs/cluster.md).
 
-Additional Learning Path–specific changes include:
+This Learning Path also applies a few environment-specific changes, including:
 
-- External Linaro CCA verifier in the AS configuration
+- An external Linaro CCA verifier configured in the Attestation Service (AS)
 
-- Attestation policy with CCA rules
+- An attestation policy containing CCA rules
 
-- An **affirming** resource policy
+- An affirming resource policy
 
-- Docker registry service
+- A local Docker registry service
 
-- A shared Docker network for all containers in this demo
+- A shared Docker network used by all services in this demo
 
-Go into the **cca-trustee** directory and generate a self-signed certificate for the docker registry service:
+Change into the cca-trustee directory and generate a self-signed certificate for the local docker registry:
 ``` bash
 cd cca-trustee
 
 openssl req -x509 -days 365 -config config/registry.cnf -keyout config/registry.key -out config/registry.crt
 ```
 
-Start the Trustee services Docker containers (as detached services):
+Start the Trustee services as detached containers:
 ``` bash { output_lines = "2-9" }
 docker compose up -d
  ✔ Network cca-trustee                                                                         Created
@@ -86,28 +86,26 @@ docker compose up -d
  ✔ Container cca-trustee-kbs-client-1                                                          Created
 ```
 
-While running the demo you can also check logs of the Trustee services in this terminal:
+To view logs while running the demo:
 ``` bash
 docker compose logs <service>
 ```
-Where **service** is either **as**, **kbs** or **rvps**.
+Where <service> is one of as, kbs or rvps.
 
-## Publish an encrypted docker image
+## Publish an encrypted container image
 
-Generate an image encryption key:
+Generate a 32-byte image encryption key:
 ``` bash
 head -c 32 /dev/urandom | openssl enc >image.key
 ```
+Learn more about how the attestation result is used to evaluate the trustworthiness of a CCA realm and how attestation policy gates secrets release in the ["Run an end-to-end Attestation with Arm CCA and Trustee"](/learning-paths/servers-and-cloud-computing/cca-trustee) Learning Path.
 
-Publish the encryption key as a KBS secret resource. This resource can be obtained only with an attestation token with **affirming** status.
-
-Learn more about how the attestation result is used to evaluate the trustworthiness of a CCA realm and how attestation policy gates secrets release in
-["Run an end-to-end Attestation with Arm CCA and Trustee"](/learning-paths/servers-and-cloud-computing/cca-trustee)
+Publish the encryption key as a KBS secret resource. This resource is only released when the requester presents an attestation token with affirming status.
 ``` bash
 ./publish-key.sh
 ```
 
-Encrypt a **busybox** docker image with the published key and push it into the local docker registry with **busybox_encrypted** name:
+Encrypt the **busybox** image using the published key, then push it to the local registry as **busybox_encrypted**:
 ``` bash { output_lines = "2-9" }
 ./encrypt_image.sh
 Encrypting docker://busybox image with busybox_encrypted name
@@ -119,12 +117,12 @@ Writing manifest to image destination
 Inspecting MIMEType of docker://registry:5000/busybox_encrypted image
             "MIMEType": "application/vnd.oci.image.layer.v1.tar+gzip+encrypted",
 ```
-By inspecting MIMEType of the published image you can see that it is encrypted.
+The published image layers use an encrypted OCI layer media type, confirming that the image has been encrypted.
 
 {{% notice Encryption key note %}}
-Annotations data for an encrypted image contains a path to the key which Confidential Containers workload needs to obtain to decrypt the image.
+Encrypted images include annotations that describe where the guest should retrieve the key required for decryption.
 
-You can check it with this command
+You can inspect the key identifier (kid) with:
 ``` bash { output_lines = "4" }
 docker compose exec keyprovider skopeo inspect docker://registry:5000/busybox_encrypted \
  | jq -r '.LayersData[0].Annotations."org.opencontainers.image.enc.keys.provider.attestation-agent"' \
@@ -134,23 +132,21 @@ docker compose exec keyprovider skopeo inspect docker://registry:5000/busybox_en
 {{% /notice %}}
 
 {{% notice Docker image note %}}
-**encrypt_image.sh** uses [skopeo](https://github.com/containers/skopeo) in the Trustee **keyprovider** container to pull, encrypt and push docker images.
-Without parameters it encrypts **busybox** docker image which will be used in this Learning Path.
-You can use this script to encrypt other docker images as well. For example with this command it will encrypt
-**alpine** docker image and push it into the local docker registry with **alpine_encrypted** name.
+**encrypt_image.sh** uses [skopeo](https://github.com/containers/skopeo) inside the Trustee keyprovider container to pull, encrypt, and push images.
+By default it encrypts busybox, which is used throughout this Learning Path. You can also encrypt other images. For example, this command encrypts **alpine** and pushes it as **alpine_encrypted**:
 
 ``` bash
 ./encrypt_image.sh alpine
 ```
 {{% /notice %}}
 
-You have prepared infrastructure and ready to start Confidential Containers in CCA realm.
+At this point, the host-side infrastructure is running and the encrypted image is available from the local registry.
 
 ## Launch an FVP
 
-With the Trustee Services running in one terminal, open up a new terminal in which you will run Confidential Containers.
+With the Trustee services running in one terminal, open a second terminal for the Confidential Containers environment.
 
-Pull the Docker image with the pre-built FVP, and then run the container connected to the same Docker network:
+Pull the pre-built FVP container image and run it on the same Docker network:
 
 ```bash
 docker pull armswdev/cca-learning-path:cca-simulation-with-kata-v3
@@ -159,28 +155,27 @@ docker pull armswdev/cca-learning-path:cca-simulation-with-kata-v3
 docker run --rm -it --network cca-trustee armswdev/cca-learning-path:cca-simulation-with-kata-v3
 ```
 
-Within your running container, launch the **run-cca-fvp.sh** script to run the Arm CCA pre-built binaries on the FVP:
+Inside your running container, launch the `run-cca-fvp.sh` script to run the Arm CCA pre-built binaries on the FVP:
 
 ```bash
 ./run-cca-fvp.sh
 ```
 
-The **run-cca-fvp.sh** script uses the **screen** command to connect to the different UARTs in the FVP.
+The `run-cca-fvp.sh` script uses the `screen` command to connect to the different UARTs in the FVP.
 
-When the host Linux boots, уnter root as the username:
+When the host Linux boots, enter root as the username:
 ```output
 
 Welcome to the CCA host
 host login: root
 (host) #
 ```
 
-## Inject the local docker registry self-signed certificate
+## Inject the local Docker registry certificate
 
-The local docker registry service was deployed with a self-signed certificate.
-To trust this certificate it needs to be added into the CA certificates list in the guest VM image.
+The local registry is configured with a self-signed TLS certificate. To allow the guest VM to trust the registry, add this certificate to the guest image’s CA certificate store.
 
-Inject the local docker repository certificate into the image:
+Inject the registry certificate into the guest filesystem image:
 ``` bash { output_lines = "2-6" }
 inject_registry_cert.sh
 
@@ -192,12 +187,11 @@ inject_registry_cert.sh
 
 ## Calculate Realm Initial Measurement (RIM)
 
-For a successful attestation of your CCA realm you need to provide the Trustee Reference Values Provider Service (RVPS) with a known good reference value.
+To validate the guest during attestation, the Trustee Reference Values Provider Service (RVPS) must be configured with a known-good reference value for the Realm.
 
-In a production environment, the known good reference value is generated using a deployment-specific process.
-This Learning Path includes **rim_calc.sh** script which:
-- Runs qemu-system-aarch64-cca-experimental (used by Kata containers to run a guest VM in Arm CCA realm) to dump Device Tree into a file.
-- Checks Kata shim configuration file for guest VM delpoyment parameters.
+In production, reference values are generated as part of a deployment-specific build and release process. This Learning Path includes a helper script, `rim_calc.sh`, which:
+- Runs qemu-system-aarch64-cca-experimental (used by Kata containers to launch a guest VM inside an Arm CCA realm) to dump the guest Device Tree into a file.
+- Reads the Kata shim configuration to capture guest deployment parameters
 - Uses ["cca-realm-measurements"](https://github.com/veraison/cca-realm-measurements) to calculate the realm initial measurement (RIM).
 
 Run the script:
@@ -216,24 +210,23 @@ Realm Extensible Measurements (REMs) are not used for attestation in this Learni
 
 ## Endorse Realm Initial Measurement (RIM)
 
-In the terminal where you started Trustee services, run **endorse-rim.sh** script with the RIM as a parameter:
+In the terminal where you started Trustee services, run `endorse-rim.sh` and pass the RIM value:
 
 ```bash { output_lines = "2-3" }
 ./endorse-rim.sh "rBD3xqcqqYHrjZ1Tu9aMWqFmwBgwT+NvLxg9jsozZm9rMDhjcaEM5LOQ+qJs+SLdG1jyco33EDuJ8+1/oMdFIQ=="
 
 Reference Values Updated
 ```
 
-## Launch a Confidential container in CCA realm
+## Launch a Confidential Container in an Arm CCA realm
 
-Reduce amount of kernel messages printed to console:
+Reduce the verbosity of kernel messages printed to the console:
 ``` bash
 dmesg -n 4
 ```
 
-Run a confidential container from the **busybox_encrypted** image and check its kernel version and RME kernel messages.
-Because the container is run in CCA realm on emulated environment (Fixed Virtual Platform (FVP)), it will take some time to launch, be patient.
-Depending on the machine you run this Learning Path on it might take between 8 and 15 minutes to run a container.
+Run a Confidential Container from the **busybox_encrypted** image and verify both the kernel version and Arm RME-related kernel messages.
+Because this runs on an emulated platform (Arm FVP), container startup can take several minutes depending on the host machine.
 
 ``` bash { output_lines = "5-9" }
 nerdctl --snapshotter nydus run --runtime io.containerd.kata.v2 \
@@ -247,14 +240,14 @@ RME kernel message:
 [    0.000000] RME: Using RSI version 1.0
 ```
 
-Verify that the FVP kernel version is different to the Confidential Container version:
+Verify that the host kernel version differs from the Confidential Container guest kernel:
 ``` bash { output_lines = "2" }
 uname -a
 Linux host 6.15.0-rc1-g916aeec68dd4 #1 SMP PREEMPT @1764597323 aarch64 GNU/Linux
 ```
 
 {{% notice Nydus snapshotter messages note %}}
-When you run a confidential container you will see messages from Nydus snapshotter when it loads container snapshot.
+When launching a Confidential Container, you may see progress output from the Nydus snapshotter while it prepares the snapshot. For example:
 ```
 registry:5000/busybox_encrypted:latest: resolving      |--------------------------------------|
 elapsed: 0.1 s                          total:   0.0 B (0.0 B/s)
@@ -271,13 +264,12 @@ These messages can be ignored. The docker image will be downloaded by **image-rs
 {{% /notice %}}
 
 {{% notice Failed attestation note %}}
-If you forget to endorse RIM for your environment or make a mistake doing that, then CCA realm attestation would fail.
-In this case you will see an image decryption error when starting a confidential container with an encrypted image.
+If the RIM is not endorsed (or the wrong value is configured), attestation will fail and the guest will be unable to retrieve the decryption key. In this case, container startup fails with an image decryption error:
 ```
 FATA[0189] failed to create shim task: rpc status: Status { code: INTERNAL, message: "[CDH] [ERROR]: Image Pull error: Failed to pull image registry:5000/busybox_encrypted from all mirror/mapping locations or original location: image: registry:5000/busybox_encrypted:latest, error: Errors happened when pulling image: Failed to decrypt layer: Failed to decrypt the image layer, please ensure that the decryption key is placed and correct", details: [], special_fields: SpecialFields { unknown_fields: UnknownFields { fields: None }, cached_size: CachedSize { size: 0 } } }
 ```
 
-By checking KBS logs (in the terminal where you run Trustee services)  you could see that the encryption key couldn't be obtained because of an AS policy:
+Checking the KBS logs (in the terminal running Trustee services) shows the request was denied by policy:
 ``` bash { output_lines = "2-5" }
 docker compose logs kbs
 
@@ -287,18 +279,16 @@ kbs-1  | [2025-12-08T12:25:40Z ERROR kbs::error] PolicyDeny
 ```
 {{% /notice %}}
 
-You have successfully run a confidential container with Arm CCA using an encrypted image.
+You have now successfully launched a Confidential Container in an Arm CCA Realm using an encrypted container image.
 
 {{% notice Unencrypted docker images note %}}
-In this Learning Path environment you can also run confidential containers in Arm CCA realm from any unencrypted docker images.
-Please notice that you need to define the **annotation** parameter so **image-rs** knows where to pull the image from.
-For example:
+In this Learning Path environment, you can also run Confidential Containers from unencrypted images. You still need to set the `io.kubernetes.cri.image-name` annotation so **image-rs** knows where to pull the image from. For example:
 ```
 nerdctl run --runtime io.containerd.kata.v2 --rm -it --annotation io.kubernetes.cri.image-name=alpine:latest alpine sh
 ```
 {{% /notice %}}
 
-You can stop all Trustee containers with:
+Stop all Trustee service containers with:
 ```bash
 docker compose down
 ```
