# canonical/tdx architecture

> Architecture diagram of the GitHub repository canonical/tdx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/canonical/tdx
- Repository: https://github.com/canonical/tdx

## Overview

##### Project Type and Purpose
- This is an orchestration and tooling project (not a web app) that automates:
– Host OS preparation for Intel TDX
– Trust Domain (TD) image creation and configuration
– Booting TDs via QEMU or libvirt
– GPU passthrough for NVIDIA H100
– Remote attestation (host and guest)
– Package building and testing (snap, deb, CI workflows)
- Intended for system administrators, DevOps engineers, and security researchers who need a repeatable workflow to deploy and validate Intel TDX environments on Ubuntu.

##### File Structure
- Top-level directories:
– .github (CI and issue templates)
– attestation (host & guest attestation scripts)
– gpu-cc (scripts for GPU discovery and VFIO setup)
– guest-tools (create-td-image.sh, setup-tdx-guest.sh, run_td, tdvirsh, XML templates)
– tests (functional, performance, stress tests; QEMU wrapper; Python utilities; snapcraft hooks)
- Key configuration files and build scripts:
– setup-tdx-config (global config for both host & guest)
– Snapcraft.yaml (for snap packaging)
– tox.ini / pytest.ini (test runners)
- Patterns:
– Modular shell-script toolkit for each phase (host, guest, boot, attestation)
– Templates for cloud-init and libvirt XML
– CI pipelines (GitHub Actions, snap hooks)

##### README for Additional Insights
- Confirms the sequence: install host prerequisites → create TD image → boot TD → verify TDX → add GPU → setup attestation → run tests
- External services: Canonical PPA, Intel PCS (PCCS), Intel Tiber Trust Services (Trust Authority API)
- Technologies: bash, Python (tests), Go (trustauthority-cli), QEMU, libvirt, cloud-init, VFIO, Snapcraft

##### Main Components and Their Interactions

A. User/CI Initiation Layer
- Operator / Admin / CI jobs
- GitHub Actions / Snapcraft build triggers

B. Host Orchestration Layer
- setup-tdx-host.sh
- system-report.sh
- check-production.sh
- attestation/setup-attestation-host.sh
- PCCS + QGS services
- BIOS configuration (TDX, SGX, TME)

C. Guest Image Layer
- guest-tools/image: create-td-image.sh (+ cloud-init meta-data templates)
- setup-tdx-guest.sh
- cloud-init processing inside TD image

D. Boot & Runtime Layer
- guest-tools/run_td (QEMU wrapper)
- guest-tools/tdvirsh (libvirt wrapper + XML templates)
- QEMU / libvirt <-> Linux KVM <-> TDX module (kernel)
- VFIO-based GPU passthrough (gpu-cc/h100/setup-gpus.sh + vfio rules)

E. Attestation Layer
- Host side: DCAP libraries → /dev/sgx_* → PCCS, QGS → MPA registration
- Guest side: trustauthority-cli (Go) → Intel Trust Authority API → network

F. Testing & Packaging Layer
- tests/ (pytest suites, checkbox provider, performance scripts)
- tests/snap (snapcraft.yaml + hooks)
- GitHub Actions workflows

G. External Services
- Canonical PPA (apt packages for TDX, DCAP, kernels)
- Intel PCS (PCCS ↔ Intel provisioning)
- Intel Tiber Trust Services (attestation API)
- GitHub (source, CI triggers)

##### Architectural Patterns and Technologies
- Layered orchestration: host setup → guest image → run → attest → test
- Modular CLI scripts and templates
- External configuration via `setup-tdx-config`
- Separation of concerns: host vs. guest vs. external attestation
- Use of industry standards: cloud-init, libvirt XML, VFIO, PSKless APIs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/CI Initiation Layer
    subgraph "User/CI Initiation Layer"
        direction TB
        CI["Operator/Admin/CI Jobs"]:::external
        GHActions["GitHub Actions Trigger"]:::external
    end

    %% Host Orchestration Layer
    subgraph "Host Orchestration Layer"
        direction TB
        HostSetup["setup-tdx-host.sh"]:::host
        SysReport["system-report.sh"]:::host
        ProdCheck["attestation/check-production.sh"]:::host
        HostAttestSetup["attestation/setup-attestation-host.sh"]:::host
        GlobalConfig["setup-tdx-config"]:::host
    end

    %% Guest Image Layer
    subgraph "Guest Image Layer"
        direction TB
        CreateImage["guest-tools/image/create-td-image.sh"]:::guest
        GuestImageSetup["guest-tools/image/setup.sh"]:::guest
        CloudInitMeta["cloud-init meta-data.template"]:::guest
        CloudInitUser["cloud-init user-data.template"]:::guest
        GuestSetup["setup-tdx-guest.sh"]:::guest
    end

    %% Boot & Runtime Layer
    subgraph "Boot & Runtime Layer"
        direction TB
        QEMUWrapper["guest-tools/run_td"]:::host
        LibvirtWrapper["guest-tools/tdvirsh"]:::host
        RegularVMXML["regular_vm.xml.template"]:::host
        TrustDomainXML["trust_domain.xml.template"]:::host
        TrustDomainSBXML["trust_domain-sb.xml.template"]:::host
        BootDirect["guest-tools/direct-boot/boot_direct.sh"]:::host
        BootUKI["guest-tools/direct-boot/boot_uki.sh"]:::host
    end

    %% GPU Passthrough Layer
    subgraph "GPU Passthrough Layer"
        direction TB
        GPUSetup["gpu-cc/h100/setup-gpus.sh"]:::host
        VFIORules["gpu-cc/h100/vfio-passthrough.rules"]:::host
    end

    %% Attestation Layer
    subgraph "Attestation Layer"
        direction TB
        GuestAttestSetup["attestation/setup-attestation-guest.sh"]:::guest
        DumpPCK["attestation/scripts/dump-pckcache.sh"]:::guest
        DumpTCB["attestation/scripts/dump-tcb-info"]:::guest
        JWTDecode["attestation/scripts/jwt-decode.sh"]:::guest
        ReadSEAM["attestation/scripts/read-seamldr-svn.sh"]:::guest
        CheckReg["attestation/scripts/check-registration.sh"]:::guest
    end

    %% Testing & Packaging Layer
    subgraph "Testing & Packaging Layer"
        direction TB
        PytestConfig["tests/pytest.ini + tox.ini"]:::test
        TestSuites["tests/lib, tests/tests, tests/tdtest"]:::test
        SnapPackaging["tests/snap/snapcraft.yaml + hooks"]:::test
        CITestWrappers["tests/checkbox + bin/"]:::test
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PPA["Canonical PPA"]:::external
        IntelPCS["Intel PCS (PCCS)"]:::external
        IntelTA["Intel Tiber Trust Services API"]:::external
        GitHub["GitHub Source & CI"]:::external
    end

    %% Connections
    CI -->|"trigger"| HostSetup
    GHActions -->|runs| HostSetup
    HostSetup -->|reads| GlobalConfig
    HostSetup --> SysReport
    HostSetup --> ProdCheck
    HostSetup --> HostAttestSetup
    HostSetup -->|prepares BIOS & Kernel| QEMUWrapper
    GlobalConfig -.->|provides config| CreateImage
    CreateImage --> CloudInitMeta
    CreateImage --> CloudInitUser
    CreateImage --> GuestImageSetup
    GuestImageSetup --> GuestSetup
    GuestSetup --> QEMUWrapper
    QEMUWrapper --> LibvirtWrapper
    LibvirtWrapper --> RegularVMXML
    LibvirtWrapper --> TrustDomainXML
    LibvirtWrapper --> TrustDomainSBXML
    QEMUWrapper -->|direct boot| BootDirect
    QEMUWrapper -->|direct boot| BootUKI
    GPUSetup --> VFIORules
    VFIORules -->|VFIO passthrough| QEMUWrapper
    QEMUWrapper -->|VFIO| GuestSetup
    GuestSetup --> GuestAttestSetup
    GuestAttestSetup --> DumpPCK
    GuestAttestSetup --> DumpTCB
    GuestAttestSetup --> JWTDecode
    GuestAttestSetup --> ReadSEAM
    GuestAttestSetup --> CheckReg
    DumpPCK --> IntelPCS
    DumpTCB --> IntelPCS
    JWTDecode --> IntelTA
    ReadSEAM --> IntelTA
    CheckReg --> IntelTA
    TestSuites -->|invoke scripts| HostSetup
    TestSuites -->|invoke scripts| GuestSetup
    TestSuites -->|invoke scripts| QEMUWrapper
    PytestConfig --> TestSuites
    SnapPackaging -->|build| GitHub
    CITestWrappers -->|run| TestSuites
    GHActions -->|publishes| SnapPackaging
    GHActions -->|publishes| CITestWrappers

    %% Click Events
    click GHActions "https://github.com/canonical/tdx/blob/main/.github/workflows/create-snap-action.yml"
    click HostSetup "https://github.com/canonical/tdx/blob/main/setup-tdx-host.sh"
    click SysReport "https://github.com/canonical/tdx/blob/main/system-report.sh"
    click ProdCheck "https://github.com/canonical/tdx/blob/main/attestation/check-production.sh"
    click HostAttestSetup "https://github.com/canonical/tdx/blob/main/attestation/setup-attestation-host.sh"
    click GlobalConfig "https://github.com/canonical/tdx/tree/main/setup-tdx-config"
    click CreateImage "https://github.com/canonical/tdx/blob/main/guest-tools/image/create-td-image.sh"
    click GuestImageSetup "https://github.com/canonical/tdx/blob/main/guest-tools/image/setup.sh"
    click CloudInitMeta "https://github.com/canonical/tdx/blob/main/guest-tools/image/cloud-init-data/meta-data.template"
    click CloudInitUser "https://github.com/canonical/tdx/blob/main/guest-tools/image/cloud-init-data/user-data.template"
    click GuestSetup "https://github.com/canonical/tdx/blob/main/setup-tdx-guest.sh"
    click QEMUWrapper "https://github.com/canonical/tdx/tree/main/guest-tools/run_td"
    click LibvirtWrapper "https://github.com/canonical/tdx/tree/main/guest-tools/tdvirsh"
    click RegularVMXML "https://github.com/canonical/tdx/blob/main/guest-tools/regular_vm.xml.template"
    click TrustDomainXML "https://github.com/canonical/tdx/blob/main/guest-tools/trust_domain.xml.template"
    click TrustDomainSBXML "https://github.com/canonical/tdx/blob/main/guest-tools/trust_domain-sb.xml.template"
    click BootDirect "https://github.com/canonical/tdx/blob/main/guest-tools/direct-boot/boot_direct.sh"
    click BootUKI "https://github.com/canonical/tdx/blob/main/guest-tools/direct-boot/boot_uki.sh"
    click GPUSetup "https://github.com/canonical/tdx/blob/main/gpu-cc/h100/setup-gpus.sh"
    click VFIORules "https://github.com/canonical/tdx/blob/main/gpu-cc/h100/vfio-passthrough.rules"
    click GuestAttestSetup "https://github.com/canonical/tdx/blob/main/attestation/setup-attestation-guest.sh"
    click DumpPCK "https://github.com/canonical/tdx/blob/main/attestation/scripts/dump-pckcache.sh"
    click DumpTCB "https://github.com/canonical/tdx/tree/main/attestation/scripts/dump-tcb-info"
    click JWTDecode "https://github.com/canonical/tdx/blob/main/attestation/scripts/jwt-decode.sh"
    click ReadSEAM "https://github.com/canonical/tdx/blob/main/attestation/scripts/read-seamldr-svn.sh"
    click CheckReg "https://github.com/canonical/tdx/blob/main/attestation/scripts/check-registration.sh"
    click PytestConfig "https://github.com/canonical/tdx/blob/main/tests/pytest.ini"
    click PytestConfig "https://github.com/canonical/tdx/blob/main/tox.ini"
    click TestSuites "https://github.com/canonical/tdx/tree/main/tests/lib"
    click TestSuites "https://github.com/canonical/tdx/tree/main/tests/tests"
    click TestSuites "https://github.com/canonical/tdx/tree/main/tests/tdtest"
    click SnapPackaging "https://github.com/canonical/tdx/blob/main/tests/snap/snapcraft.yaml"
    click SnapPackaging "https://github.com/canonical/tdx/tree/main/tests/snap/hooks"
    click CITestWrappers "https://github.com/canonical/tdx/tree/main/tests/checkbox"

    %% Styles
    classDef host fill:#cce5ff,stroke:#4da3ff,stroke-width:1px
    classDef guest fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef external fill:#ffe5cc,stroke:#ff8c1a,stroke-width:1px
    classDef test fill:#f0e6ff,stroke:#b366ff,stroke-width:1px
```
