Skip to content

Init pass at restructuring CoCo TOC #385

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
a-mccarthy wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Init pass at restructuring CoCo TOC #385

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2371029
Init pass at restructuring TOC
a-mccarthy Apr 30, 2026
984a9de
troubleshooting improvements, grammer nits
a-mccarthy Jun 12, 2026
431f9be
Clarify install paths between quickstart and detailed isntall guide
a-mccarthy Jun 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 18 additions & 12 deletions confidential-containers/attestation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,18 @@
.. headings # #, * *, =, -, ^, "


.. _attestation-overview:

***********
Attestation
***********

As a :ref:`Security Engineer <coco-persona-security-engineer>`, use this page to understand more about attestation and stand up a local attestation backend for testing.

.. note::

Attestation is not required to configure your cluster to deploy Confidential Containers workloads.
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.

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:
Expand All @@ -32,8 +38,7 @@ 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.
Configure attestation when workloads require a secret, to decrypt a container image or model, or guest components collect hardware evidence from the active CPU and GPU enclaves.

Key Concepts
============
Expand All @@ -52,7 +57,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
==========
Expand All @@ -74,16 +79,16 @@ The goal is to give you a working local attestation backend and a client to inte
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.


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.


Expand All @@ -103,6 +108,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.

Expand All @@ -129,7 +135,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.

Expand Down Expand Up @@ -249,10 +255,10 @@ 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:

* `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.
* `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

Expand Down
Loading
Loading