Skip to content

Add a compatibility matrix #1259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
bpradipt wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Add a compatibility matrix #1259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 122 additions & 0 deletions COMPATIBILITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# Compatibility Matrix

This document tracks compatibility between guest-components and [Trustee](https://github.com/confidential-containers/trustee) (the server-side components including KBS, Attestation Service, and RVPS).

## KBS Protocol Version

Guest-components and Trustee communicate using the KBS (Key Broker Service) protocol. Both sides must use compatible protocol versions.
Copy link
Copy Markdown
Contributor

@mkulke mkulke Jan 8, 2026

Choose a reason for hiding this comment

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

Currently we have no enforced schema for the evidence payload, so if some encoding changes (e.g. because of a bincode update/replacement in GC or in a dependency). a change on the payload would break Trustee interop. Until we have this, it's an aspirational goal, but we cannot really guarantee this.

Copy link
Copy Markdown
Contributor

@mkulke mkulke Jan 14, 2026

Choose a reason for hiding this comment

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

see #1267 we probably want to have something similar at least for the TEEs that have some envelope over binary data.


| Protocol Version | Status | Notes |
|------------------|------------|--------------------------------------------|
| v0.4.0 | Current | Used in CoCo v0.15.0+ |
| v0.3.0 | Deprecated | Legacy, not recommended |

## Release Compatibility

The following table shows tested version combinations. Versions are coordinated through [CoCo umbrella releases](https://github.com/confidential-containers/confidential-containers/tree/main/releases).

| CoCo Release | guest-components | Trustee | KBS Protocol | Release Date |
|--------------|------------------|----------|--------------|--------------|
| v0.17.0 | v0.16.0 | v0.16.0 | v0.4.0 | Nov 2025 |
| v0.16.0 | v0.15.0 | v0.15.0 | v0.4.0 | Oct 2025 |
| v0.15.0 | v0.14.0 | v0.14.0 | v0.4.0 | Sep 2025 |
| v0.14.0 | v0.13.0 | v0.13.0 | v0.4.0 | May 2025 |
| v0.13.0 | v0.12.0 | v0.12.0 | v0.4.0 | Mar 2025 |

**Note:** Using mismatched versions may work but is not tested. For production deployments, use versions from the same CoCo release.
Copy link
Copy Markdown
Member

@Xynnn007 Xynnn007 Jan 8, 2026

Choose a reason for hiding this comment

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

This will not work. There is version check logic https://github.com/confidential-containers/trustee/blob/main/kbs/src/attestation/backend.rs#L220-L227 to assert the versions are the same?


## TEE Platform Support

### Attestation Support Matrix

| TEE Platform | guest-components | Trustee | Architecture | Status |
|--------------------|------------------|----------|--------------|--------------|
| Intel TDX | v0.8.0+ | v0.8.0+ | x86_64 | Stable |
| Intel SGX | v0.7.0+ | v0.7.0+ | x86_64 | Stable |
| AMD SEV-SNP | v0.7.0+ | v0.7.0+ | x86_64 | Stable |
| AMD SEV(-ES) | v0.7.0+ | v0.7.0+ | x86_64 | Stable |
Copy link
Copy Markdown
Member

@fitzthum fitzthum Jan 7, 2026

Choose a reason for hiding this comment

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

Not supported anymore, although I'm not sure if we've ripped the code out of GC yet.

Copy link
Copy Markdown
Member

@wainersm wainersm Jan 9, 2026

Choose a reason for hiding this comment

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

so add a table of retired TEEs?

| Azure TDX vTPM | v0.9.0+ | v0.9.0+ | x86_64 | Stable |
| Azure SNP vTPM | v0.9.0+ | v0.9.0+ | x86_64 | Stable |
| ARM CCA | v0.10.0+ | v0.10.0+ | aarch64 | Experimental |
| IBM Secure Exec | v0.10.0+ | v0.10.0+ | s390x | Stable |
| Hygon CSV | v0.12.0+ | v0.12.0+ | x86_64 | Experimental |
Copy link
Copy Markdown
Member

@Xynnn007 Xynnn007 Jan 8, 2026

Choose a reason for hiding this comment

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

We also have Hygon DCU from v0.15.0

| NVIDIA GPU | v0.15.0+ | v0.15.0+ | x86_64 | Experimental |
Copy link
Copy Markdown
Member

@fitzthum fitzthum Jan 7, 2026

Choose a reason for hiding this comment

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

NVIDIA should be stable now.

Are we missing TPM here?

Copy link
Copy Markdown
Member Author

@bpradipt bpradipt Jan 7, 2026

Choose a reason for hiding this comment

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

Yeah.
Wondering do we need to add this level of details or just leave at GC and Trustee version ? Might become hard to maintain going forward. Wdyt ?


### Feature Flags
Copy link
Copy Markdown
Member

@wainersm wainersm Jan 9, 2026

Choose a reason for hiding this comment

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

This Feature Flags seems more for the guest-component's main documentation than for this compatibility document. I would drop it.


guest-components uses feature flags to enable TEE-specific code. The following table maps TEE platforms to the required build configuration:

| TEE Platform | `TEE_PLATFORM` | Attester Feature Flag |
|--------------------|----------------|-----------------------|
| Intel TDX | `tdx` | `tdx-attester` |
| Intel SGX | (manual) | `sgx-attester` |
Copy link
Copy Markdown
Member

@fitzthum fitzthum Jan 7, 2026

Choose a reason for hiding this comment

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

not sure what manual is

| AMD SEV-SNP | `snp` | `snp-attester` |
| AMD SEV(-ES) + SNP | `amd` | `snp-attester` |
| Azure TDX vTPM | `az-tdx-vtpm` | `az-tdx-vtpm-attester`|
| Azure SNP vTPM | `az-snp-vtpm` | `az-snp-vtpm-attester`|
| Azure CVM vTPM | `az-cvm-vtpm` | Both Azure attesters |
| ARM CCA | `cca` | `cca-attester` |
| IBM Secure Exec | `se` | `se-attester` |

## Component Dependencies
Copy link
Copy Markdown
Member

@wainersm wainersm Jan 9, 2026

Choose a reason for hiding this comment

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

Likewise. That section is more like an internal implementation detail of guest-components.


Trustee embeds certain guest-components crates as dependencies:

| Trustee Component | guest-components Crate | Purpose |
|-----------------------|------------------------|----------------------------------|
| KBS | `kbs_protocol` | Protocol types and client |
| Attestation Service | `kms` | KMS provider implementations |

These dependencies are pinned to specific git revisions in Trustee's `Cargo.toml`. When upgrading, ensure the pinned revision is compatible with your guest-components version.

## Breaking Changes

### v0.15.0+
- KBS configuration format updated
- Token validation changes

### v0.10.0+
- Added support for multiple concurrent attesters
- Changed attestation evidence format for some platforms

### v0.8.0+
- Initial stable KBS protocol v0.4.0
Copy link
Copy Markdown
Member

@fitzthum fitzthum Jan 7, 2026

Choose a reason for hiding this comment

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

This doesn't seem right. v0.4.0 would have been after multi-device attestation (v0.3.0) and init-data plaintext support (v0.4.0)

Copy link
Copy Markdown
Contributor

@mythi mythi Jan 8, 2026

Choose a reason for hiding this comment

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

protocol history details is in this issue confidential-containers/trustee#907


## Testing Compatibility

To verify compatibility between guest-components and Trustee:

1. **Unit Tests**: Run component tests independently
```shell
# In guest-components
cd attestation-agent/kbs_protocol
cargo test
```

2. **Integration Tests**: Use the same CoCo release versions
```shell
# Start Trustee KBS
docker run -p 8080:8080 ghcr.io/confidential-containers/staged-images/kbs:v0.16.0

# Test with guest-components client
cd attestation-agent
cargo test --features kbs
Copy link
Copy Markdown
Member

@fitzthum fitzthum Jan 7, 2026

Choose a reason for hiding this comment

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

Not sure if either of these tests will actually work. I think the unit test will be skipped if the version doesn't match. At least someone should try running this.

Copy link
Copy Markdown
Member

@wainersm wainersm Jan 9, 2026

Choose a reason for hiding this comment

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

I would drop that section from this doc as well.

```

3. **End-to-End**: Deploy using CoCo operator with matched versions

## Reporting Compatibility Issues

If you encounter compatibility issues:

1. Verify you're using versions from the same CoCo release
2. Check the [KBS protocol version](#kbs-protocol-version) matches
3. Open an issue with:
- guest-components version/commit
- Trustee version/commit
- TEE platform
- Error messages

File issues at:
- guest-components: https://github.com/confidential-containers/guest-components/issues
- Trustee: https://github.com/confidential-containers/trustee/issues
10 changes: 10 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,5 +76,15 @@ The ttRPC and gRPC protos can be updated via run
make build-protos
```

## Compatibility

For compatibility information between guest-components and [Trustee](https://github.com/confidential-containers/trustee) (KBS, Attestation Service), see the [Compatibility Matrix](COMPATIBILITY.md).

This includes:
- Release version mappings
- TEE platform support status
- KBS protocol versions
- Breaking changes

## License
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fconfidential-containers%2Fimage-rs.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fconfidential-containers%2Fimage-rs?ref=badge_large)