trustee_client
++ +
+
Ansible role for deploying Trustee Guest Components using Podman +Quadlets for confidential virtual machine deployments. The role +downloads quadlet files and configuration files from a GitHub +repository, installs them, and manages them as systemd services. The +role also supports an optional secret registration client for disk key +registration and optional disk encryption for securing additional +storage devices.
+Features
+-
+
- Trustee Client (Quadlet): Deploys Trustee guest +components Attestation Agent(AA), Confidential Data Hub(CDH) and API +Server REST(ASR) using Podman Quadlets from a Github repository +
- Secret Registration Client: Utility script and +service which registers to Secret Registration Server on Trustee Server. +It acquires the encryption key from Trustee and decrypts the designated +disk upon boot +
- Encrypt Disk: Does LUKS2 encryption of the found +empty data disk. The encryption key is provided by Secret Registration +Client. +
Example of setting the variables:
+trustee_client_kbs_url: "https://kbs.example.com"
+trustee_client_kbs_cert_content: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" # or trustee_client_kbs_cert_src: "/path/to/server.crt"
+trustee_client_secret_registration_enabled: true
+trustee_client_encrypt_disk: trueVariables
+trustee_client_trustee_gc
+Whether to deploy Trustee Guest Components using Podman Quadlets
+(packages, quadlet files, /etc/trustee-gc/ configuration,
+and the trustee-gc pod service). When false,
+this part of the role is skipped.
The secret registration client is only deployed when this variable
+and trustee_client_secret_registration_enabled are both
+true.
Default: true
Type: bool
trustee_client_kbs_url
+URL of the Key Broker Service (KBS) used by Trustee Guest Components.
+When non-empty, the role replaces the KBS_URL placeholder
+in the Attestation Agent and Confidential Data Hub
+config.toml files under /etc/trustee-gc/ with
+this value.
If unset (empty string), the bundled placeholder values in those +files are left unchanged.
+Default: ""
Type: string
trustee_client_kbs_cert_content
+PEM-encoded TLS certificate for the KBS server, as a string (for
+example from Ansible Vault). When non-empty, the role replaces the
+KBS_CERT placeholder in the AA and CDH
+config.toml files and writes the certificate to
+/etc/trustee-gc/server.crt.
Use either this variable or trustee_client_kbs_cert_src,
+not both as the primary source; if both are set, explicit content takes
+precedence when it is non-empty.
Default: ""
Type: string
trustee_client_kbs_cert_src
+Path on the control node to a PEM certificate file for the KBS
+server. Used when trustee_client_kbs_cert_content is empty.
+The file is read with lookup('file', ...) and applied like
+trustee_client_kbs_cert_content.
Default: ""
Type: string
trustee_client_secret_registration_enabled
+Whether to install and configure the secret registration client
+(requires Trustee Guest Components; see
+trustee_client_trustee_gc). When true, the
+client can register with the Secret Registration Server and supply disk
+encryption keys when encrypt-disk features use it.
Default: false
Type: bool
trustee_client_encrypt_disk
+Whether to locate an unpartitioned disk, create a LUKS2 encrypted
+volume, and mount it. The encryption key comes from the secret
+registration client when
+trustee_client_secret_registration_enabled is
+true, otherwise from a generated key and TPM binding via
+systemd-cryptenroll (PCR 7).
Default: false
Type: bool
trustee_client_encrypt_disk_mount_point
+Filesystem path where the encrypted disk (mapper device
+trustee_client_encrypted_disk_0) is mounted when
+trustee_client_encrypt_disk is true. The
+directory is created if missing.
Default: "/mnt/encrypted-disk"
Type: string
trustee_client_secure_logging
+If true, suppress potentially sensitive output from
+tasks that handle credentials, secrets, and other sensitive data by
+setting no_log: true on those tasks. This prevents
+passwords, API tokens, private keys, and similar sensitive information
+from appearing in Ansible logs and console output.
If you need to debug issues with credential handling or secret
+management, you can temporarily set
+trustee_client_secure_logging: false to see the full output
+from these tasks. However, be aware that this may expose sensitive
+information in logs, so it should only be used in development or
+troubleshooting scenarios.
Default: true
Type: bool
Example Playbook
+Including an example of how to use your role (for instance, with +variables passed in as parameters) is always nice for users too:
+- name: Deploy Trustee Guest Components using Podman Quadlets
+ hosts: all
+ vars:
+ trustee_client_kbs_url: "https://kbs.example.com"
+ trustee_client_kbs_cert_content: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
+ trustee_client_secret_registration_enabled: true
+ trustee_client_encrypt_disk: true
+ roles:
+ - linux-system-roles.trustee_clientTrustee Client
+The task:
+-
+
- Downloads the Podman Quadlets from designated repo +
- Configures the settings in /etc/trustee-gc/ +
- Enables and starts trustee-gc.pod as a service +
Secret Registration Client
+When enabled, this task:
+-
+
- Sends registration request to Secret Registration Server via HTTPS +to acquire disk encryption keys +
- Requests above disk encryption key upon boot when Encrypt Disk is +enabled to decrypt and mount disk +
Encrypt Disk
+An unpartitioned empty disk must be attached to the target. When +enabled, this task:
+-
+
- Finds the first unpartitioned and unmounted disk +
- Encrypts the disk using a key from either: a. secret key fetched
+using Secret Registration Client (when enabled), or b.
+
systemd-cryptenrollwhich binds to PCR 7
+ - Mounts it at the designated path +
- Sets up automatic unlock and mount either with Secret Registration
+Client service or /etc/crypttab with
+
systemd-cryptenroll
+
License
+Whenever possible, please prefer MIT.
+Author Information
+An optional section for the role authors to include contact +information, or a website (HTML is not allowed).
+