Init pass at restructuring CoCo TOC

confidential-containers/attestation.rst

@@ -17,12 +17,18 @@
 .. headings # #, * *, =, -, ^, "
 
 
-.. _attestation-overview:
-
 ***********
 Attestation
 ***********
 
+As a :ref:`Security Engineer <coco-persona-security-engineer>`, use this page to understand attestation concepts and stand up a local Trustee instance for testing.
+
+.. note::
+
+   This page gives an overview of attestation and a quickstart for standing up a local attestation backend for testing.
+   You should refer to the upstream `Confidential Containers documentation <https://confidentialcontainers.org/docs/attestation/>`__ for more details on attestation and production deployment.
+   For a full end-to-end attestation workflow, refer to the `NVIDIA NIM Confidential GPU Attestation <https://confidentialcontainers.org/docs/examples/nvidia-nim-confidential-gpu-attestation/>`_ example.
+
 In Confidential Containers, a Trusted Execution Environment (TEE) isolates a workload from the host.
 Attestation is a process that cryptographically proves the state of the guest TEE, including both the CPU and the GPU, to a remote verifier before any secret or sensitive resource is released to the workload.
 Attestation is required for any feature that depends on secrets, including:
@@ -32,16 +38,13 @@ Attestation is required for any feature that depends on secrets, including:
 * Using sealed secrets
 * Requesting secrets directly from workloads
 
-When a workload requires a secret, such as a key to decrypt a container image or model, guest components collect hardware evidence from the active CPU and GPU enclaves. 
-The evidence is sent to the remote verifier to evaluate the evidence against known-good reference values and configured policies, and conditionally releases the requested resource.
-
 Key Concepts
 ============
 
 The following concepts appear throughout this page:
 
-* Confidential Containers (CoCo): The open-source project that implements the cloud-native approach to Confidential Computing. 
-  CoCo uses Kata Containers as the sandbox and Trustee as the attestation framework. 
+* Confidential Containers (CoCo): The open-source project that implements the cloud-native approach to Confidential Computing.
+  CoCo uses Kata Containers as the sandbox and Trustee as the attestation framework.
 * Trusted Execution Environment (TEE): A hardware-isolated environment, such as AMD SEV-SNP, Intel TDX, or an NVIDIA Confidential Computing GPU, that protects code and data in use.
 * Remote attestation: The process of cryptographically proving to a remote party that a TEE is running the expected, untampered software stack before that party releases secrets to it.
 * Trustee: The remote verifier in the Confidential Containers attestation flow. Trustee is composed of three cooperating services:
@@ -52,7 +55,7 @@ The following concepts appear throughout this page:
 * KBS resource: A secret, for example, a key, credential, or token, that Trustee releases to a guest when attestation succeeds. Most resources are addressed by a three-part path: ``<repository>/<type>/<tag>``.
 * Policy: The rule set that Trustee evaluates against verified evidence to decide whether to release a resource. By default, Trustee denies resource requests from clients that have not presented valid TEE evidence.
 
-Refer to the upstream `Confidential Containers documentation <https://confidentialcontainers.org/docs/architecture/design-overview/>`_ for more details on these concepts and attestation best practices.
+Refer to the upstream `Confidential Containers documentation <https://confidentialcontainers.org/docs/architecture/design-overview/>`__ for more details on these concepts and attestation best practices.
 
 Quickstart
 ==========
@@ -64,26 +67,25 @@ The goal is to give you a working local attestation backend and a client to inte
 
 .. note::
 
-   This quickstart is for evaluation only. 
+   This quickstart is for evaluation only.
    Do not use the Trustee instance you stand up here in production.
-   This guide does not deploy a TEE, does not produce real hardware attestation evidence, and does not release any secrets to a workload. 
+   This guide does not deploy a TEE, does not produce real hardware attestation evidence, and does not release any secrets to a workload.
    It only validates that the Trustee components are running and reachable.
 
-   A production attestation workflow depends on your environment and your organization's security policies.
-   Documenting a full attestation workflow is outside the scope of this quickstart.
-   To run attestation against real evidence from a confidential workload, refer to the upstream `Attestation <https://confidentialcontainers.org/docs/attestation/>`_ and `Features <https://confidentialcontainers.org/docs/features>`_ documentation for more information.
+   A full end-to-end attestation workflow depends on your environment and your organization's security requirements.
+   For complete deployment guidance, refer to the upstream `Confidential Containers attestation documentation <https://confidentialcontainers.org/docs/attestation/>`_ and the `NVIDIA NIM Confidential GPU Attestation <https://confidentialcontainers.org/docs/examples/nvidia-nim-confidential-gpu-attestation/>`_ example.
 
 
-What You'll Build
------------------
+What You Will Build
+-------------------
 
 By the end of this quickstart, you will have:
 
 * A local Trustee instance (KBS, Attestation Service, and Reference Value Provider Service) running in Docker containers on ``127.0.0.1:8080``.
 * The ``kbs-client`` command-line tool installed and able to reach your Trustee instance.
 * A sample resource request that exercises the end-to-end request path.
 
-You'll know you're done when ``kbs-client`` can send a request to KBS and receive a response from the Trustee policy engine, even if that response is a policy denial.
+You will know you are done when ``kbs-client`` can send a request to KBS and receive a response from the Trustee policy engine, even if that response is a policy denial.
 A denial in this quickstart is the expected, successful outcome: it confirms that the client reached KBS, the Attestation Service evaluated the request, and policy was applied.
 
 
@@ -103,6 +105,7 @@ Prerequisites
 Step 1: Install Trustee with Docker Compose
 -------------------------------------------
 
+Installing Trustee with Docker Compose is the recommended install path.
 Clone the upstream Trustee repository.
 The repository ships with a ``docker-compose.yml`` that wires KBS, the Attestation Service, and the Reference Value Provider Service together.
 
@@ -129,7 +132,7 @@ Start the Trustee containers in the background.
 .. note::
 
    On first run, ``docker compose up -d`` pulls the KBS, AS, and RVPS images before starting them.
-   This step can take several minutes. The command returns once the containers are starting. The services may need an additional few seconds to become ready to accept requests.
+   This step can take several minutes. The command returns after the containers start. The services may need an additional few seconds to become ready to accept requests.
 
 For details on optional configuration such as the admin keypair, debug logging, and per-service config files, refer to the upstream `Install Trustee in Docker <https://confidentialcontainers.org/docs/attestation/installation/docker/>`_ guide.
 
@@ -164,7 +167,7 @@ A connection refused or no-route error indicates that the containers are not run
 
 .. note::
 
-   It is typically not recommended to curl the KBS endpoints directly unless you are checking connectivity. 
+   It is typically not recommended to curl the KBS endpoints directly unless you are checking connectivity.
    Use the ``kbs-client``, installed in the next step, instead.
 
 
@@ -217,7 +220,7 @@ Step 4: Send a Sample Resource Request
 --------------------------------------
 
 Use ``kbs-client`` to request a resource from your local Trustee.
-The request below uses a placeholder resource path. 
+The request below uses a placeholder resource path.
 You do not need to pre-create the resource for this check.
 The ``get-resource`` endpoint can be used (including inside a TEE), but it will always invoke the sample attester, which generates fake evidence for testing.
 
@@ -247,12 +250,13 @@ If you instead see a connection error, KBS is not reachable. Revisit Step 2.
 Next Steps
 ==========
 
-You now have a working local Trustee instance and a client that can talk to it. For more details, refer to the upstream Confidential Containers documentation:
+You now have a working local Trustee instance and a client that can talk to it. For end-to-end deployment guidance, refer to the upstream Confidential Containers documentation:
 
-* `Attestation <https://confidentialcontainers.org/docs/attestation/>`_ — Trustee architecture, configuration, resources, policies, the client tool, and guidance for production deployment topology, network configuration, and hardening.
-* `Features <https://confidentialcontainers.org/docs/features>`_ — the complete set of Confidential Containers features, including how to wire attestation into real workloads.
+* `NVIDIA NIM Confidential GPU Attestation <https://confidentialcontainers.org/docs/examples/nvidia-nim-confidential-gpu-attestation/>`_: A complete example deploying Trustee, configuring attestation policies, and running a confidential NVIDIA NIM workload with GPU attestation.
+* `Attestation <https://confidentialcontainers.org/docs/attestation/>`_: Trustee architecture, configuration, resources, policies, the client tool, and guidance for production deployment topology, network configuration, and hardening.
+* `Features <https://confidentialcontainers.org/docs/features>`_: The complete set of Confidential Containers features, including how to wire attestation into real workloads.
 
-To shut down the local Trustee instance when you're finished, run the following command from the ``trustee`` repository directory:
+To shut down the local Trustee instance when you are finished, run the following command from the ``trustee`` repository directory:
 
 .. code-block:: console