Using a dynamic registry reference

Edit online

Defer the container registry specification until deployment time by dynamically overriding the registry URL and pull credentials in the workload contract.

There are cases where the registry is not known when the workload section is pre-encrypted, for example, when the workload provider wants to allow the deployer to use a registry mirror or a private container registry.

Typically, the workload provider embeds a fixed registry URL in the pod descriptor inside the pre-encrypted workload section. For example:

image: docker.io/library/hello-world@sha256:53f1bbee2f52c39e41682ee1d388285290c5c8a76cc92b42687eecf38e0af3f0

In this example:

  • docker.io/library/ is the registry prefix.
  • hello-world is the image identifier.
  • sha256:53f1bbee2f52c39e41682ee1d388285290c5c8a76cc92b42687eecf38e0af3f0 uniquely identifies the image version.

In such cases, it is possible to dynamically override the registry and the pull credentials. This is a coordinated effort between the workload provider and the deployer.

How it works

The workload provider pre-encrypts the workload section without specifying the final registry. The deployer then:

  1. Adds the target registry credentials in the auths section of the workload contract.
  2. Includes a cdh.toml entry in initdata.toml to configure the Confidential Data Hub (CDH) to read the credentials at runtime.
  3. Includes an aa.toml placeholder entry in initdata.toml.
  4. Includes the registry CA certificate under extra_root_certificates in cdh.toml if the registry uses a self-signed or private CA certificate.

Deployer steps

Step 1: Add registry credentials to the workload contract

In the auths section of workload.yaml, specify the target registry and its credentials:

auths:
  <TARGET_REGISTRY_URL>:
    username: <USER_NAME>
    password: <API_KEY_OR_PASSWORD>

Example:

auths:
  icr.io:
    username: iamapikey
    password: <YOUR_API_KEY>

Step 2: Configure initdata.toml with CDH settings

The cdh.toml and aa.toml configurations must be embedded as entries inside initdata.toml. The authenticated_registry_credentials_uri field in cdh.toml tells CDH where to read the pull credentials from the contract at runtime:

algorithm = "sha384"
version = "0.1.0"
[data]
"contract.yaml" = '''${encrypted_contract}'''
"cdh.toml" = '''
socket = "unix:///run/confidential-containers/cdh.sock"

[kbc]
name = "offline_fs_kbc"
url = "http://example.io:8080"

[image]
authenticated_registry_credentials_uri = "file:///etc/auth.json"
'''
"aa.toml" = '''
'''

Step 3: Add extra root certificates for private registries

If the target registry uses a self-signed or private CA certificate, you must extract the certificate and include it under extra_root_certificates in the cdh.toml entry:

  1. Extract the certificate from the registry: 
    echo | openssl s_client -showcerts -connect <REGISTRY_HOST>:<PORT> 2>/dev/null | openssl x509 -outform PEM > registry-cert.pem
  2. Store the certificate content in a variable: 
    export REGISTRY_CERT=$(cat registry-cert.pem)
  3. Include it in the cdh.toml entry of initdata.toml: 
    [image]
authenticated_registry_credentials_uri = "file:///etc/auth.json"
extra_root_certificates = ["""
${REGISTRY_CERT}
"""]
Tip: You can add multiple PEM certificates as separate entries in the extra_root_certificates list.

Contract structure

The final contract at deployment time contains the pre-encrypted workload section (with auths) from the workload provider and the encrypted env section from the deployer:

workload: contract-basic.<ENCRYPTED_WORKLOAD>
env: contract-basic.<ENCRYPTED_ENV>

The workload section does not need to be re-encrypted. The deployer assembles the final initdata.toml with the cdh.toml and aa.toml entries to complete the deployment.

Responsibility split

The following table summarises who is responsible for each part:

Persona Responsibility
Workload provider Pre-encrypts the workload section with a placeholder or known image digest. Does not embed final registry credentials.
Deployer Adds target registry credentials in auths. Embeds cdh.toml (with authenticated_registry_credentials_uri) and aa.toml as entries in initdata.toml. Includes the registry CA certificate under extra_root_certificates when the registry uses a self-signed or private CA certificate.