Skip to main content
Version: Next

Generate initdata annotations and manifest

This step updates your deployment files with initdata annotations and automatically generates the deployment manifest.

Applicability​

This step is required for all Contrast deployments.

Prerequisites​

  1. Set up cluster
  2. Install CLI
  3. Deploy the Contrast runtime
  4. Add Coordinator to resources
  5. Prepare deployment files
  6. Configure TLS (optional)
  7. Enable GPU support (optional)

How-to​

Run the generate command to add the necessary components to your deployment files. This will add the Contrast Initializer to every workload with the specified contrast-cc runtime class and the Contrast Service Mesh to all workloads that have a specified configuration. After that, it will generate the execution policies, wrap them in initdata documents and add them as annotations to your deployment files. A manifest.json with the reference values of your deployment will be created.

contrast generate --reference-values metal-qemu-snp resources/

On bare-metal SEV-SNP, contrast generate is unable to fill in the MinimumTCB values as they can vary between platforms and CPU models. They will have to be filled in manually.

AMD doesn't provide an accessible way to acquire the latest TCB values for your platform. Visit the AMD SEV developer portal and download the latest firmware package for your processor family. Unpack and inspect the contained release notes, which state the SNP firmware SVN (called SPL (security patch level) in that document). Contact your hardware vendor or BIOS firmware provider for information about the other TCB components

To check the current TCB level of your platform, use the snphost:

snphost show tcb
Reported TCB: TCB Version:
  Microcode:   72
  SNP:         23
  TEE:         0
  Boot Loader: 9
  FMC:         None
Platform TCB: TCB Version:
  Microcode:   72
  SNP:         23
  TEE:         0
  Boot Loader: 9
  FMC:         None

The values listed as Reported TCB to should be greater or equal to the MinimumTCB values in manifest.json. The Platform TCB can be higher than the Reported TCB, in this case, the platform has provisional firmware enrolled. Contrast relies on the committed TCB values, as provisional firmware can be rolled back anytime by the platform operator.

warning

The TCB values observed on the target platform using snphost might not be trustworthy. Your channel to the system or the system itself might be compromised. The deployed firmware could be outdated and vulnerable.

The generate command needs to pull the container images to derive policies. Running generate for the first time can take a while, especially if the images are large. If your container registry requires authentication, you can create the necessary credentials with docker login or podman login. Be aware of the registry authentication limitation on bare metal.

warning

Please be aware that runtime policies currently have some blind spots. For example, they can't guarantee the starting order of containers. See the current limitations for more details.

Running contrast generate for the first time creates some additional files in the working directory:

  • seedshare-owner.pem is required for handling the secret seed and recovering the Coordinator (see Secrets & recovery).
  • workload-owner.pem is required for manifest updates after the initial contrast set.
  • rules.rego and settings.json are the basis for runtime policies.
  • layers-cache.json caches container image layer information for your deployments to speed up subsequent runs of contrast generate.

Fine-tuning initializer injection​

If you don't want the Contrast Initializer to automatically be added to your workloads, there are two ways you can skip the Initializer injection step, depending on how you want to customize your deployment.

--skip-initializer flag​

You can disable the Initializer injection completely by specifying the --skip-initializer flag in the generate command.

contrast generate --reference-values metal-qemu-snp --skip-initializer resources/

skip-initializer annotation​

If you want to disable the Initializer injection for a specific workload with the contrast-cc runtime class, you can do so by adding an annotation to the workload.

metadata: # v1.Pod, v1.PodTemplateSpec
  annotations:
    contrast.edgeless.systems/skip-initializer: "true"

Manual Initializer injection​

When disabling the automatic Initializer injection, you can manually add the Initializer as a sidecar container to your workload before generating the policies. Configure the workload to use the certificates written to the contrast-secrets volumeMount.

# v1.PodSpec
spec:
  initContainers:
    - env:
        - name: COORDINATOR_HOST
          value: coordinator-ready
      image: "ghcr.io/edgelesssys/contrast/initializer:latest"
      name: contrast-initializer
      volumeMounts:
        - mountPath: /contrast
          name: contrast-secrets
  volumes:
    - emptyDir: {}
      name: contrast-secrets

Fine-tuning service mesh injection​

The service mesh is only injected for workload that have a service mesh annotation.

--skip-service-mesh flag​

You can disable the service mesh injection completely by specifying the --skip-service-mesh flag in the generate command.

contrast generate --reference-values metal-qemu-snp --skip-service-mesh resources/

In this case, you can manually add the service mesh sidecar container to your workload before generating the policies, or authenticate peers on the application level.