feat: add centralized trust bundle cert management #2167
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| --- | ||
| title: Central Trust Bundle Management | ||
| sidebar: | ||
| order: 8.1 | ||
| --- | ||
|
|
||
| UDS Core provides a centralized trust bundle management system that automatically builds and distributes certificate trust bundles across the cluster. This system allows you to define a unified trust source that all packages can automatically consume, regardless of whether the trust bundle includes private, public, or DoD-specific Certificate Authority (CA) certificates. | ||
|
|
||
| ## Overview | ||
|
|
||
| The central trust bundle management feature addresses the challenge of maintaining consistent certificate trust chains across environments. Rather than each package independently managing trusted CA configuration, UDS Core provides a standardized mechanism to: | ||
|
|
||
| - **Centrally manage CA certificates**: Define trust bundles in one place through Cluster Configuration | ||
| - **Automatically distribute trust stores**: Generate and distribute trust bundles to all namespaces | ||
| - **Support multiple CA sources**: Include private/custom, DoD, and public CA certificates as needed | ||
|
|
||
| When you configure a trust bundle, UDS Core automatically creates ConfigMaps in each namespace, containing the combined CA certificates in PEM format that applications can mount and use. | ||
|
|
||
| ## Configuration | ||
|
|
||
| Trust bundles are configured during UDS Core deployment using UDS/Zarf variables: | ||
|
|
||
| ### UDS Core Deployment Variables | ||
|
|
||
| | Variable | Description | Default | | ||
| |----------|-------------|---------| | ||
| | `CA_BUNDLE_CERTS` | Base64 encoded CA certs (bundle) in PEM format that UDS Core will inherently trust. At minimum, this must include your Domain CA Cert if using Private PKI for your UDS Core deployment | `""` (empty) | | ||
| | `CA_BUNDLE_INCLUDE_DOD_CERTS` | Include DoD CA certificates in the bundle | `false` | | ||
| | `CA_BUNDLE_INCLUDE_PUBLIC_CERTS` | Include standard public CA certificates in the bundle | `false` | | ||
|
|
||
| :::note[Legacy Support] | ||
| The `CA_CERT` variable is still supported for backwards compatibility but is deprecated. Use `CA_BUNDLE_CERTS` for new deployments. This new variable is also used for Authservice configuration as described in the [trusted CA SSO documentation](/reference/configuration/single-sign-on/trusted-ca). | ||
| ::: | ||
|
|
||
| ### Cluster Trust Bundle Configuration | ||
|
|
||
| The UDS Core trust bundle is configured at deployment time at the cluster level. | ||
|
|
||
| Configure these variables in your `uds-config.yaml` file to set up the trust bundle. For example: | ||
| ```yaml | ||
| variables: | ||
| core: | ||
| CA_BUNDLE_CERTS: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..." # Base64 encoded PEM bundle | ||
| CA_BUNDLE_INCLUDE_DOD_CERTS: "true" # default false | ||
| CA_BUNDLE_INCLUDE_PUBLIC_CERTS: "true" # default false | ||
| ``` | ||
|
|
||
| The above example will build a trust bundle that includes your custom CA certificates, DoD CAs, and public CAs concatted together in PEM format. Both the DoD and Public CAs are packaged with UDS Core. | ||
|
|
||
| ### UDS Package Configuration | ||
|
|
||
| Trust bundle ConfigMaps are automatically deployed in all namespaces that contain a UDS Package CR. You can customize the ConfigMap configuration using the `caBundle` field in your Package CR: | ||
|
|
||
| ```yaml | ||
| apiVersion: uds.dev/v1alpha1 | ||
| kind: Package | ||
| metadata: | ||
| namespace: my-package | ||
| spec: | ||
| caBundle: | ||
| configMap: | ||
| name: uds-trust-bundle # default: uds-trust-bundle - name of the ConfigMap created in the package namespace | ||
| key: ca-bundle.pem # default: ca-bundle.pem - key name inside the ConfigMap | ||
| labels: # default: {} - list of labels to apply to the ConfigMap created | ||
| uds.dev/pod-reload: "true" # apply this label to enable pod reloads on change of this configmap | ||
| annotations: # default: {} - list of annotations to apply to the ConfigMap | ||
| uds.dev/pod-reload-selector: "app=my-app" # annotation to specify which pods to reload on configmap change | ||
| ``` | ||
|
|
||
| The above package CR will create a ConfigMap named `uds-trust-bundle` in the `my-package` namespace with the trust bundle under the key `ca-bundle.pem`. The specified labels and annotations will also be applied to the ConfigMap. | ||
|
|
||
| ### Mounting the Trust Bundle | ||
|
|
||
| Applications can mount the trust bundle ConfigMap into their pods to use the CA certificates for TLS verification. The mount path for the system trust store will depend on the container distribution/application requirements. Common paths include for system trust store replacement: | ||
|
|
||
| - Debian/Ubuntu: `/etc/ssl/certs/ca-certificates.crt` | ||
| - RedHat/CentOS: `/etc/pki/tls/certs/ca-bundle.crt` | ||
|
|
||
| :::caution[Application Trust Store Usage] | ||
| Replacing the system trust store does not always guarantee that your application will use the system trust store. Different programming languages and crypto libraries may have their own trust store locations or use embedded CA certificates. You should consult your application's documentation and crypto package/library to understand where it pulls trusted certificates from. | ||
| ::: | ||
|
|
||
| ## DoD Certs | ||
|
|
||
| UDS Core includes an option to add DoD CA certificates to the trust bundle. When `CA_BUNDLE_INCLUDE_DOD_CERTS` is set to `true`, the standard DoD CA certificates packaged with UDS Core will be included in the trust bundle. | ||
|
|
||
| UDS Core pulls these certs from: [DoD Approved External PKI Trust Chains](https://dl.dod.cyber.mil/wp-content/uploads/pki-pke/zip/unclass-dod_approved_external_pkis_trust_chains.zip) | ||
|
|
||
| You can also see the certs checked into the UDS Core repository source code here: [UDS Core DoD Certificates](https://github.com/defenseunicorns/uds-core/tree/main/certs/dod) | ||
|
|
||
| ## Public Certs | ||
|
|
||
| The UDS Core trust bundle includes a subset of public CA certificates from the Mozilla CA store. UDS Core only includes widely trusted Public CAs that are based out of the United States or are commonly used for global services. | ||
|
|
||
| You can find the full list of public CAs included here [UDS Core Public Trust Config](https://github.com/defenseunicorns/uds-core/blob/main/certs/public/uds-core-public-ca-trust-config.yaml). | ||
|
|
||
| The resulting PEM bundle is here [UDS Core Public CA Bundle](https://github.com/defenseunicorns/uds-core/blob/main/certs/public/ca-bundle.pem). |
|
Contributor
Author
There was a problem hiding this comment. note to self: add a uds docs redirect link for this |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Copyright 2025 Defense Unicorns | ||
| # SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial | ||
|
|
||
| apiVersion: v1 | ||
| kind: ConfigMap | ||
| metadata: | ||
| name: uds-ca-certs | ||
| namespace: pepr-system | ||
| data: | ||
| dodCACerts: "" | ||
|
Contributor
There was a problem hiding this comment. ConfigMap has a limitation to 1 MB. I did some quick math and for a Base64 encoded certs that are quite large (2 KB, 2.72 KB after encoding), we can store around 370 of these. Even though it appears quite large, shall we mention somewhere in the docs that there is certain ceiling there and administrators should be aware of it?
Contributor
Author
There was a problem hiding this comment. Yea, we did some math in the design doc around this. Realistically, we don't imagine users hitting the upper limit on the configmap. We could put a callout in the docs about the upper limit, but I feel it is adding a caution to something that most likely won't happen? I lean towards leaving it out but could be convinced to put it in |
||
| publicCACerts: "" | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Shall we call this out as a breaking change?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We're leaving
CA_CERTaround, just deprecated so I don't think we need to. This removal is just in a CI only config file so not a downstream breaking change here.