Skip to content

docs: update reference value docs and bump sandboxed-policies to 0.2.* #95

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

Merged
butler54 merged 2 commits into from
Jun 2, 2026
Merged

docs: update reference value docs and bump sandboxed-policies to 0.2.* #95

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aafe426
docs: update documentation and bump sandboxed-policies to 0.2.*
butler54 Jun 2, 2026
2401cec
fix: address linter error and update README
butler54 Jun 2, 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
23 changes: 12 additions & 11 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ This file provides rules and context for any AI coding assistant working in this
Use the **first** approach that fits your requirement:

1. **Helm charts** — Declarative Kubernetes resources in `/charts/`, deployed by ArgoCD. Preferred for installing operators, configuring CRDs, and creating Kubernetes resources.
2. **ACM policies** — Red Hat Advanced Cluster Management policies for propagating configuration from hub to spoke clusters and enforcing multi-cluster governance. Reference: `charts/hub/sandbox-policies/templates/`.
2. **ACM policies** — Red Hat Advanced Cluster Management policies for propagating configuration from hub to spoke clusters and enforcing multi-cluster governance. Reference: `validatedpatterns/sandboxed-policies-chart`.
3. **Imperative framework (Ansible)** — Playbooks in `/ansible/`, executed as Kubernetes Jobs on a 10-minute schedule. **Must be idempotent.** Use for API calls, runtime data lookups, and multi-step orchestration that cannot be expressed declaratively. Register playbooks in `clusterGroup.imperative.jobs` as an ordered list.
4. **Out-of-band scripts** — `/scripts/` or `/rhdp/`. Last resort for one-time setup or local development tooling. These are not managed by GitOps.

Expand Down Expand Up @@ -48,32 +48,33 @@ Use the **first** approach that fits your requirement:
├── values-simple.yaml # Cluster group: simple
├── values-baremetal.yaml # Cluster group: baremetal
├── values-trusted-hub.yaml # Cluster group: trusted-hub
├── values-untrusted-spoke.yaml # Cluster group: untrusted-spoke
├── values-spoke.yaml # Cluster group: spoke
└── values-secret.yaml.template # Secrets template (never commit filled-in copy)
```

## Companion Chart Repositories

Several charts in this repository have companion repositories for independent versioning and reuse. Develop and test in this repository first (charts deploy via `path:`), then sync changes to the companion repository.
These charts are published independently and consumed from the `charts.validatedpatterns.io` Helm registry via `chart:` + `chartVersion:` in the values files.

| Local Path | Companion Repository | Purpose |
| Chart Name | Repository | Purpose |
|---|---|---|
| `charts/hub/trustee/` | `trustee-chart` | Trustee / KBS on hub |
| `charts/hub/sandbox-policies/` | `sandboxed-policies-chart` | ACM policies hub → spoke |
| `charts/coco-supported/sandbox/` | `sandboxed-containers-chart` | Sandboxed runtime on spoke |
| `trustee` | `validatedpatterns/trustee-chart` | Trustee / KBS configuration |
| `sandboxed-policies` | `validatedpatterns/sandboxed-policies-chart` | ACM policies hub → spoke |
| `sandboxed-containers` | `validatedpatterns/sandboxed-containers-chart` | Sandboxed runtime on spoke |

Large features may require coordinated changes across multiple companion repos. References are org-agnostic — contributors should fork all relevant repos as needed.
Changes to companion charts require a release (Git tag) before the pattern can consume them. Update the `chartVersion:` field in the values files to pick up new releases.

## Cluster Groups

Set via `main.clusterGroupName` in `values-global.yaml`.

| Cluster Group | Values File | Role | Description |
|---|---|---|---|
| `simple` | `values-simple.yaml` | Hub (single cluster) | All components on one cluster |
| `baremetal` | `values-baremetal.yaml` | Hub (single cluster) | TDX + LVM storage on bare metal |
| `simple` | `values-simple.yaml` | Hub (single cluster) | All components on one Azure cluster |
| `baremetal` | `values-baremetal.yaml` | Hub (single cluster) | TDX/SNP + LVM storage on bare metal |
| `baremetal-gpu` | `values-baremetal-gpu.yaml` | Hub (single cluster) | Bare metal + NVIDIA H100 GPU support |
| `trusted-hub` | `values-trusted-hub.yaml` | Multi-cluster hub | Trustee + ACM policies |
| `untrusted-spoke` | `values-untrusted-spoke.yaml` | Multi-cluster spoke | Sandbox runtime + workloads |
| `spoke` | `values-spoke.yaml` | Multi-cluster spoke | Sandbox runtime + workloads |

## Values File Hierarchy

Expand Down
17 changes: 12 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Confidential containers use hardware-backed Trusted Execution Environments (TEEs

## Topologies

The pattern provides three deployment topologies:
The pattern provides four deployment topologies:

1. **Single cluster** (`simple` clusterGroup) — deploys all components (Trustee, Vault, ACM, sandboxed containers, workloads) in one cluster on Azure. This breaks the RACI separation expected in a remote attestation architecture but simplifies testing and demonstrations.

Expand All @@ -29,6 +29,10 @@ Breaking change from v4. Uses GA releases of the CoCo stack with Kyverno-based i
- **5.0** — Kyverno-based `cc_init_data` injection (replaces MutatingAdmissionPolicy), OSC 1.12 / Trustee 1.1 GA, external chart repositories, self-signed certificates via cert-manager, multi-cluster support via ACM. Requires OCP 4.19.28+.
- **5.1** — Bare metal support for Intel TDX and AMD SEV-SNP via NFD auto-detection. Currently tested on SNO (Single Node OpenShift) configurations only.
- **5.2** — NVIDIA H100 confidential GPU support for bare metal (`baremetal-gpu` clusterGroup). Adds GPU Operator, IOMMU configuration, CC Manager, and sample CUDA workload.
- **5.3** — DRY refactor of trustee and kyverno overrides, Kyverno CRD label fix, pattern infrastructure update.
- **5.4** — Firmware reference values workflow for bare metal attestation via veritas. Adds `collect-firmware-refvals.sh`, RVPS integration, and hardened attestation policy (trustee-chart v0.5.0).
- **5.5** — Trustee-chart v0.7.0 (td_attributes.debug path fix). Unified reference value collection for Azure and bare metal via veritas container.
- **5.6** — Documentation update, sandboxed-policies v0.2.0 (Azure-conditional peer-pods).

### Previous versions

Expand Down Expand Up @@ -62,12 +66,15 @@ Breaking change from v4. Uses GA releases of the CoCo stack with Kyverno-based i
- OpenShift pull secret saved at `~/pull-secret.json` (download from [console.redhat.com](https://console.redhat.com/openshift/downloads))
- Fork the repository — ArgoCD reconciles cluster state against your fork, so changes must be pushed to your remote

### Secrets and PCR setup
### Secrets and reference value setup

These scripts generate the cryptographic material and attestation measurements needed by Trustee and the peer-pod VMs. Run them once before your first deployment.
These scripts generate the cryptographic material and attestation reference values needed by Trustee. Run them once before your first deployment.

1. `bash scripts/gen-secrets.sh` — generates KBS key pairs, PCCS certificates/tokens (for bare metal), and copies `values-secret.yaml.template` to `~/values-secret-coco-pattern.yaml`
2. `bash scripts/get-pcr.sh` — retrieves PCR measurements from the peer-pod VM image and stores them at `~/.coco-pattern/measurements.json` (requires `podman`, `skopeo`, and `~/pull-secret.json`). **Azure only.** Bare metal uses manual PCR collection — see [docs/pcr-reference-values-bare-metal.md](docs/pcr-reference-values-bare-metal.md) for the procedure. Store the measurements at `~/.coco-pattern/measurements.json`.
2. Collect attestation reference values (requires `podman`, `yq`, `jq`, and `~/pull-secret.json`):
- **Azure:** `make collect-azure-refvals` — pulls PCR measurements from the dm-verity image via veritas. Saves to `~/.coco-pattern/measurements.json`.
- **Bare metal:** `make collect-firmware-refvals` — computes firmware measurements from OCP release artifacts via veritas. Saves to `~/.coco-pattern/firmware-reference-values.json`. For bare metal, also uncomment the `firmwareReferenceValues` section in `~/values-secret-coco-pattern.yaml`.
- See [docs/firmware-reference-values.md](docs/firmware-reference-values.md) for detailed workflow and options.
3. Review and customise `~/values-secret-coco-pattern.yaml` — this file is loaded into Vault and provides secrets to the pattern. For bare metal, uncomment the PCCS secrets section and provide your Intel PCS API key.

> **Note:** `gen-secrets.sh` will not overwrite existing secrets. Delete `~/.coco-pattern/` if you need to regenerate.
Expand Down Expand Up @@ -173,4 +180,4 @@ Deployment commands:
- Single cluster: `bash rhdp/wrapper.sh <azure-region>` (e.g. `bash rhdp/wrapper.sh eastasia`)
- Multi-cluster: `bash rhdp/wrapper-multicluster.sh <azure-region>`

The wrapper scripts handle cluster provisioning via `openshift-install`, secret generation, PCR retrieval, and pattern installation.
The wrapper scripts handle cluster provisioning via `openshift-install`, secret generation, reference value collection, and pattern installation.
Loading
Loading