Skip to content

docs: Update attestation key provisioning - #384

Merged
Jakob-Naucke merged 1 commit into
trusted-execution-clusters:mainfrom
Jakob-Naucke:doc-ak-provision
Oct 28, 2026
Merged

Jakob-Naucke merged 1 commit into
trusted-execution-clusters:mainfrom
Jakob-Naucke:doc-ak-provision

Conversation

@Jakob-Naucke

@Jakob-Naucke Jakob-Naucke commented Oct 16, 2026 •

Copy link
Copy Markdown
Member

according to #202.

Summary by Sourcery

Align attestation key provisioning documentation with the clevis-pin-trustee registration workflow.

Enhancements:

  • Update attestation key provisioning documentation to describe clevis-pin-trustee as the component responsible for generating and registering attestation keys during first boot.
  • Document the Clevis LUKS pin configuration, including machine UUID-based registration and revised certificate parameters.
  • Correct the documented machine registration endpoint path and align the operator architecture with the updated provisioning flow.

Documentation:

  • Revise attestation key provisioning and operator architecture documentation to reflect the clevis-pin-trustee-based registration workflow.

@sourcery-ai

sourcery-ai Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Updates the attestation key provisioning design to document clevis-pin-trustee as the component responsible for AK generation and registration, with examples showing how its configuration is embedded in an Ignition LUKS Clevis pin.

Sequence diagram for first boot attestation key registration

sequenceDiagram
    participant Ignition
    participant Clevis as clevis-pin-trustee
    participant TPM
    participant Registration as RegistrationService

    Ignition->>Clevis: Process trustee pin configuration
    Clevis->>TPM: Check for /var/tpm/ak.pub
    alt AK does not exist
        Clevis->>TPM: Generate AK
        TPM-->>Clevis: Return public AK
        Clevis->>TPM: Save public AK to /var/tpm/ak.pub
    end
    Clevis->>Registration: PUT public AK and platform name
    Registration-->>Clevis: Accept AK registration
    Clevis->>Ignition: Continue first boot LUKS configuration
Loading

File-Level Changes

Change Details Files
Reframe attestation key provisioning from Ignition-native handling to clevis-pin-trustee handling through a Clevis LUKS pin configuration.
  • Rename the configuration section and update the explanatory text to identify the Clevis trustee pin as the provisioning component.
  • Replace the Ignition attestation schema example with an Ignition LUKS/Clevis custom-pin example.
  • Add a nested Clevis attestation configuration example containing the registration URL, certificate, and machine UUID.
  • Update first-boot flow descriptions so AK existence checks, generation, and registration are performed by clevis-pin-trustee.
  • Correct first-boot wording and list numbering, and remove the obsolete registration-flow image reference.
docs/design/attestation_key_provisioning.md

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 6 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/design/attestation_key_provisioning.md" line_range="85" />
<code_context>
    - Public key is extracted and saved to `/var/tpm/ak.pub`
-3. **Network Requirement**: If registration URL is configured, Ignition ensures network connectivity
-4. **Registration Request**: Ignition PUTs the public AK to the registration URL
+1. **Registration Request**: Clevis pin PUTs the public AK to the registration URL
    - the AK public key in PEM format
    - the name of the platform where the machine in running on
</code_context>
<issue_to_address>
**AKs remain unapproved**

When a client follows the documented registration request fields, the request description names a platform instead of the machine UUID, but the registration handler accepts the UUID and the controller matches keys to Machines by UUID. The key remains unmatched and unapproved, so Trustee cannot use it for attestation.

Document the machine UUID as the registration correlation field instead of the platform name.

Also at `docs/design/attestation_key_provisioning.md:87`.
</issue_to_address>

### Comment 2
<location path="docs/design/attestation_key_provisioning.md" line_range="63" />
<code_context>
+          ...
+        },
+        ...
       }
-    }
+    ],
</code_context>
<issue_to_address>
**AKs remain unapproved**

When a user copies the sample UUID or builds the Clevis config from the parameter list without supplying the node's Machine ID, the registration service stores the sample or missing UUID with the AK, so the operator cannot match it to the Machine or approve it for Trustee verification.

Mark the sample UUID as a placeholder and document that each node must supply its matching Machine ID in the required `uuid` field.

Also at `docs/design/attestation_key_provisioning.md:85-87`.
</issue_to_address>

### Comment 3
<location path="docs/design/attestation_key_provisioning.md" line_range="61" />
<code_context>
+      "cert": "-----BEGIN CERTIFICATE-----\nMIIDADCCAeigAwIBAgIUfF36UDMoK8YX+6RN1HxvusgPUgswDQYJKoZIhvcNAQEL\nBQAwGDEWMBQGA1UEAxMNc2VsZnNpZ25lZC1jYTAeFw0yNjEwMTYxNjE1MjBaFw0y\nNzAxMTQxNjE1MjBaMBgxFjAUBgNVBAMTDXNlbGZzaWduZWQtY2EwggEiMA0GCSqG\nSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCwmKhSQJdrgKf+pv2WfDZ43pJMK6dKN317\nO5YflWDqt/xCkRIwdxPAcTGA0dbooA/epzDgbfsU6SHTWclPKg+Uag0KwgzdlPs7\n2uJw25zNnUdA6nLyDqxatbmsHR92Ny9vvmndMmvMQ7cbXpdzXi5asDKLTy3cYyc1\nc0SQ4BMppzvZjuM1BegZXcv7PHlDD+O84Bm+OlRcbdHiZNEUugMqHj/f+NUP43Oh\nGK7xRBx37DLZZvwnm7/5LUR09I4ktSDRKI9qcJawi1OsyLqSYsoKlnN4q+mW/DJ8\n1Hu1jbulTmDXi2PyrsSpYXPdrKrcLtlnHvfKMrxhLj1wBBleLUD7AgMBAAGjQjBA\nMA4GA1UdDwEB/wQEAwICpDAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBSHMhju\nwEhNswW/c6bnSkKRDPug9DANBgkqhkiG9w0BAQsFAAOCAQEAQhgM0PW6Fwwq0BSz\nSKh2bFELqk5J0P37e4g2tivztACcUcV/3UAhKWGKHPjEx8pt7q1K8t3hbB4cBg4R\nLtagoXP+oRlpx6ESz525cxvLUDGAQK3P/q7mc1SwGzd7jtAPgZ+ULLyEvIj3Tki+\nGzZJh2Vasrx8d09K5wiiN5YUrXVArr7GLmQpHuDwqqE1y1Sre/Xo9nD2/LsveFVa\nkTihjRMfmlwR8T5H/za9bDagBSlby+Nhp9mjy5OrsCRcrlCY+31Copq7SA/uGQ14\nXgSIbBbgUgXUJp0UlyfSF64ao6fjSs+KukCIiz2vpPCpsG4Zseru7kx25v3foITF\ntWLvQw==\n-----END CERTIFICATE-----\n",
</code_context>
<issue_to_address>
**HTTPS registration fails**

When a user follows the documented `certificate` parameter name for an HTTPS endpoint using a private CA, the Clevis registration configuration expects `cert`, so the documented `certificate` key leaves the CA unconfigured and TLS certificate verification fails.

Use the same parameter name in the list and example, documenting `cert` consistently.

Also at `docs/design/attestation_key_provisioning.md:62`.
</issue_to_address>

### Comment 4
<location path="docs/design/attestation_key_provisioning.md" line_range="77" />
<code_context>
+## First boot AK Registration Flow

-During firstboot, Ignition handles the AK generation and registration before processing merge/replace directives and LUKS encryption setup.
+During first boot, clevis-pin-trustee handles the AK generation and registration before processing merge/replace directives and LUKS encryption setup.

 ### Process Flow (first boot)
</code_context>
<issue_to_address>
**Registration order is impossible**

When the Clevis registration settings arrive in the first-boot merge response, the Clevis pin cannot read those settings or register the AK until Ignition processes the merge that supplies them, so the documented order reverses the dependency and misleads readers about first-boot registration.

Describe Ignition processing the merge before the Clevis pin registers the AK while processing the merged LUKS configuration.

Also at `docs/design/attestation_key_provisioning.md:78`.
</issue_to_address>

### Comment 5
<location path="docs/design/attestation_key_provisioning.md" line_range="25" />
<code_context>
+## Clevis pin configuration

-The AK registration is configured through Ignition's attestation section. This configuration is provided during the first boot merge process from the registration service.
+The AK registration is configured through the Clevis pin's attestation section. This configuration is provided during the first boot merge process from the registration service.

 ### Configuration Schema
</code_context>
<issue_to_address>
**AK endpoint is placed in the wrong config**

When operators follow the initial-Ignition instruction without configuring the registration address on the cluster, the later instruction to put the endpoint in the initial Ignition config leads operators to configure it there only; the Clevis pin reads its registration settings from the merged LUKS pin config, so the AK is not registered and Trustee never receives it.

Remove the initial-Ignition instruction and state that the registration address must be configured on the cluster so the registration server can include it in the merged Clevis config.
</issue_to_address>

### Comment 6
<location path="docs/design/attestation_key_provisioning.md" line_range="4" />
<code_context>
 ## Overview

-This document describes the attestation key (AK) registration process for confidential clusters. The AK is provisioned and registered during first boot using Ignition's attestation support. The registered AK follows a Trust On First Use (TOFU) model, where the key is trusted upon initial registration and subsequently used by Trustee to verify attestation reports.
+This document describes the attestation key (AK) registration process for confidential clusters. The AK is provisioned and registered during first boot using clevis-pin-trustee's attestation support. The registered AK follows a Trust On First Use (TOFU) model, where the key is trusted upon initial registration and subsequently used by Trustee to verify attestation reports.
</code_context>
<issue_to_address>
**Provisioning ownership conflicts**

When a reader consults both design documents, the operator architecture guide assigns AK checks and generation to Ignition, while the provisioning guide assigns them to clevis-pin-trustee, leaving readers with conflicting provisioning instructions.

Update the operator architecture guide to describe the same AK provisioning ownership as the provisioning guide.

Also at `docs/design/attestation_key_provisioning.md:78`.
</issue_to_address>

Sourcery assessment

Approval pending. 6 findings to address first.

Blocking findings: docs/design/attestation_key_provisioning.md:85, docs/design/attestation_key_provisioning.md:63, docs/design/attestation_key_provisioning.md:61, docs/design/attestation_key_provisioning.md:77, docs/design/attestation_key_provisioning.md:25, and 1 more


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

@Jakob-Naucke
Jakob-Naucke force-pushed the doc-ak-provision branch 3 times, most recently from 7ae9d63 to 38bc0cc Compare October 16, 2026 19:44
according to trusted-execution-clusters#202.

Signed-off-by: Jakob Naucke <jnaucke@redhat.com>
@openshift-ci

openshift-ci Bot commented Oct 28, 2026

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: Jakob-Naucke, SpaceFace02

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@Jakob-Naucke
Jakob-Naucke merged commit 77341d5 into trusted-execution-clusters:main Oct 28, 2026
14 checks passed
@Jakob-Naucke
Jakob-Naucke deleted the doc-ak-provision branch October 28, 2026 09:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants