Add certificate trust customization article for Aspire 13 #5311

Copilot · 2025-10-20T15:07:50Z

Plan: Create Certificate Trust Customization Article

Based on issue #5307, I created a comprehensive draft article about the new certificate trust customization features in Aspire 13.

Completed Article

The article covers all aspects from issue #5307:

Core Features Documented

Certificate Authority Collections: AddCertificateAuthorityCollection, WithCertificates, WithCertificateAuthorityCollection
Development Certificate Trust: Default behavior and WithDeveloperCertificateTrust API
Certificate Trust Scopes: Append, Override, System, None modes with WithCertificateTrustScope
Custom Configuration: WithCertificateTrustConfiguration for advanced scenarios with unified callback approach
Container Certificate Paths: WithContainerCertificatePaths for container-specific path configuration

Code Examples Included

Creating and using certificate authority collections
Configuring development certificate trust
Each trust scope mode with practical examples
Custom certificate trust configuration with callback using simplified context
Container certificate path customization with WithContainerCertificatePaths
Common scenarios (Dashboard HTTPS, containers, Python apps)

Documentation Standards Met

✅ Follows Microsoft Writing Style Guide
✅ Uses "Aspire" (not ".NET Aspire")
✅ Sentence case headings
✅ Active voice, second person
✅ AI usage disclosed in frontmatter
✅ Passes markdownlint validation (0 errors)
✅ Includes limitations section (run mode only)
✅ Cross-references to related articles (with correct titles)
✅ Early callout that feature only applies at runtime
✅ Documents default trust scopes for different resource types
✅ Uses inline code for API references (no xref for new APIs)

Changes Made

Created docs/app-host/certificate-trust.md - comprehensive article with all features
Updated docs/toc.yml - added article to AppHost section
Fixed cross-reference title to match actual article title
Updated per initial review feedback:
- Added IMPORTANT callout that customization only applies at run time
- Updated API parameter names (trust instead of enabled)
- Changed Import to ImportFromPemFile for better accuracy
- Added documentation of default trust scopes for different resource types
- Updated callback examples with proper context objects and properties
- Changed Python example to show disabling trust (since System is now default)
Updated per PR #12358 feedback:
- Replaced deprecated WithExecutableCertificateTrustCallback and WithContainerCertificateTrustCallback APIs
- Documented new unified WithCertificateTrustConfiguration API with simplified callback approach
- Added documentation for WithContainerCertificatePaths API with all three optional parameters
- Updated callback examples to use simplified context with Arguments, EnvironmentVariables, CertificateBundlePath, and CertificateDirectoriesPath
- Improved explanations of how path value providers work
- Added note about single call requirement for WithContainerCertificatePaths
- Changed introductory text to use singular "callback API" and "callback allows"

The article is ready for review!

Original prompt

Please create a draft article that addresses issue @dotnet/docs-aspire/issues/5307 - the description provides plenty of detail, be sure to consider all of it. You do not need to callout the version that this feature was introduced.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Internal previews

📄 File	🔗 Preview link
docs/app-host/certificate-trust.md	docs/app-host/certificate-trust
docs/toc.yml	docs/toc

Co-authored-by: IEvangelist <[email protected]>

IEvangelist · 2025-10-24T13:55:12Z

Hey @danegsta please have a look at this PR.

docs/app-host/certificate-trust.md

IEvangelist · 2025-10-24T23:47:55Z

Hey @copilot please address all PR feedback.

…nt default scopes Co-authored-by: IEvangelist <[email protected]>

Copilot · 2025-10-24T23:51:43Z

Hey @copilot please address all PR feedback.

All PR feedback has been addressed in commit 6f6d732.

danegsta · 2025-10-25T01:03:09Z

I just opened a PR to simplify the certificate trust callback APIs. Most of the API will be unchanged, but the final section on configuring resources via callbacks will need to be updated.

IEvangelist · 2025-10-27T19:25:05Z

Hey @copilot please consider the dotnet/aspire#12358 as it reworks some of the callback usage. Please update this content and for the new APIs to get a clean build please don't use xref, instead just wrap those APIs as inline code.

Co-authored-by: IEvangelist <[email protected]>

Copilot · 2025-10-27T19:29:56Z

Hey @copilot please consider the dotnet/aspire#12358 as it reworks some of the callback usage. Please update this content and for the new APIs to get a clean build please don't...

Updated the callback examples to reflect the simplified APIs from PR #12358. The callbacks now use async Task, and I've documented all context properties including CustomCertificatesContainerFilePath, CertificatesDirectoryEnvironment, and improved the examples with better comments. Using inline code for API references as requested. Commit 30ab01a

danegsta · 2025-10-28T16:13:02Z

docs/app-host/certificate-trust.md

+
+## Custom certificate trust callbacks
+
+For advanced scenarios, you can specify custom certificate trust behavior using callback APIs. These callbacks allow you to customize how certificates are configured for different resource types.


Suggested change

For advanced scenarios, you can specify custom certificate trust behavior using callback APIs. These callbacks allow you to customize how certificates are configured for different resource types.

For advanced scenarios, you can specify custom certificate trust behavior using a callback API. This callback allow you to customize the command line arguments and environment variables required to configure certificate trust for different resource types.

Updated the introductory text to use singular "callback API" and "callback allows". Commit 9d88625

danegsta · 2025-10-28T16:18:32Z

docs/app-host/certificate-trust.md

+### Executable resource certificate trust
+
+Use `WithExecutableCertificateTrustCallback` to customize certificate trust for executable resources:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+builder.AddExecutable("custom-app", "myapp", ".")
+    .WithExecutableCertificateTrustCallback(async (ctx) =>
+    {
+        // Add a command line argument that must be set to enable custom certificates
+        ctx.CertificateTrustArguments.Add("--use-custom-ca");
+
+        // Add a command line argument that expects the path to a bundle (single file) of the custom CA certificates
+        ctx.CertificateBundleArguments.Add("--ca-file");
+
+        // Add an environment variable that expects the path to a bundle (single file) of the custom CA certificates
+        ctx.CertificateBundleEnvironment.Add("EXTRA_CA_BUNDLE");
+
+        // Add an environment variable that expects the path to a directory containing CA certificates
+        ctx.CertificatesDirectoryEnvironment.Add("EXTRA_CERTS_DIR");
+
+        await Task.CompletedTask;
+    });
+
+builder.Build().Run();
+```
+
+The callback receives an `ExecutableCertificateTrustCallbackAnnotationContext` that provides:
+
+- `Certificates`: The `X509Certificate2Collection` of certificates for this resource.
+- `Scope`: The `CertificateTrustScope` of trust for the resource.
+- `CertificateTrustArguments`: Command line arguments required to enable certificate trust.
+- `CertificateBundleArguments`: Command line arguments that will be combined with the path to the custom certificates bundle.
+- `CertificateBundleEnvironment`: Environment variable names that will be set with the path to the custom certificates bundle.
+- `CertificatesDirectoryEnvironment`: Environment variable names that will be set with paths to directories containing CA certificates to trust.
+
+### Container resource certificate trust
+
+Use `WithContainerCertificateTrustCallback` to customize certificate trust for container resources:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+builder.AddContainer("api", "myimage")
+    .WithContainerCertificateTrustCallback(async (ctx) =>
+    {
+        // Customize the path where custom certificates will be placed in the container
+        // Defaults to /usr/lib/ssl/aspire
+        ctx.CustomCertificatesContainerFilePath = "/custom/certs/path";
+
+        // Override the default container certificate authority bundle paths
+        // This is a list of common certificate paths for various Linux distros by default
+        // You should only need to update this if your container has certificates in non-standard paths
+        ctx.DefaultContainerCertificateAuthorityBundlePaths.Clear();
+        ctx.DefaultContainerCertificateAuthorityBundlePaths.Add("/path/to/custom/certbundle.pem");
+
+        // Override the default container certificates directory paths
+        // By default this is a collection of common certificate directory paths for various Linux distros
+        // You should only need to customize this if your image uses non-standard certificate paths
+        ctx.DefaultContainerCertificatesDirectoryPaths.Clear();
+        ctx.DefaultContainerCertificatesDirectoryPaths.Add("/path/to/custom/certs/dir");
+
+        // Add environment variables that should be set with a path to the additional CA certificates directory as its value
+        // By default this includes "SSL_CERT_DIR" for OpenSSL compatibility
+        ctx.CertificatesDirectoryEnvironment.Add("EXTRA_CERTS");
+
+        await Task.CompletedTask;
+    });
+
+builder.Build().Run();
+```
+
+The callback receives a `ContainerCertificateTrustCallbackAnnotationContext` that provides:
+
+- `Certificates`: The `X509Certificate2Collection` of certificates for this resource.
+- `Scope`: The `CertificateTrustScope` of trust for the resource.
+- `CustomCertificatesContainerFilePath`: The path in the container where custom certificates will be placed (defaults to `/usr/lib/ssl/aspire`).
+- `DefaultContainerCertificateAuthorityBundlePaths`: List of default certificate bundle files in the container that will be replaced in Override mode.
+- `DefaultContainerCertificatesDirectoryPaths`: List of default certificate directories in the container that will be appended to in Append mode.
+- `CertificateTrustArguments`: Command line arguments required to enable certificate trust.
+- `CertificateBundleArguments`: Command line arguments that will be combined with the path to the custom certificates bundle.
+- `CertificateBundleEnvironment`: Environment variable names that will be set with the path to the custom certificates bundle.
+- `CertificatesDirectoryEnvironment`: Environment variable names that will be set with paths to directories containing CA certificates (defaults include `SSL_CERT_DIR` for OpenSSL compatibility).
+
+Default implementations are provided for Node.js, Python, and container resources. Container resources rely on standard OpenSSL configuration options, with default values that support the majority of common Linux distributions. You can override these defaults if necessary.


Both of these sections are outdated and no longer apply to the current implementation. Instead, the new WithCertificateTrustConfiguration API should be documented here.

Replaced the outdated executable and container callback sections with documentation for the new WithCertificateTrustConfiguration API that uses a unified approach with simplified context properties. Commit 9d88625

danegsta · 2025-10-28T16:32:28Z

docs/app-host/certificate-trust.md

+- `CertificatesDirectoryEnvironment`: Environment variable names that will be set with paths to directories containing CA certificates (defaults include `SSL_CERT_DIR` for OpenSSL compatibility).
+
+Default implementations are provided for Node.js, Python, and container resources. Container resources rely on standard OpenSSL configuration options, with default values that support the majority of common Linux distributions. You can override these defaults if necessary.
+


There should probably be a section here on configuring container certificate artifact paths using the WithContainerCertificatePaths API.

The API takes three optional arguments:

customCertificatesDestination takes a string and overrides the base path in the container where custom certificate files are placed. If not set (or set to null) the default path of /usr/lib/ssl/aspire will be used.

defaultCertificateBundlePaths takes a list of strings and overrides the path(s) in the container where a default certificate authority bundle file is located. When the CertificateTrustScope is Override or System, the custom certificate bundle will additionally be written to these paths. If not set (or set to null) a set of default certificate paths for common Linux distributions will be used.

defaultCertificateDirectoryPaths takes a list of strings and overrides the path(s) in the container where individual trusted certificate files are found. When the CertificateTrustScope is Append, these paths will be concatenated with the path to the uploaded certificate artifacts. If not set (or set to null) a set of default certificate paths for common Linux distributions will be used.

All desired paths must be configured in a single call to WithContainerCertificatePaths as only the most recent call to the API is honored.

Hey @copilot please have a look at these comments

Added a new section documenting the WithContainerCertificatePaths API with detailed explanations of all three optional parameters (customCertificatesDestination, defaultCertificateBundlePaths, defaultCertificateDirectoryPaths) and included a note that all desired paths must be configured in a single call. Commit 9d88625

Co-authored-by: IEvangelist <[email protected]>

danegsta · 2025-10-28T18:19:49Z

docs/app-host/certificate-trust.md

+The `WithContainerCertificatePaths` API accepts three optional parameters:
+
+- `customCertificatesDestination`: Overrides the base path in the container where custom certificate files are placed. If not set or set to `null`, the default path of `/usr/lib/ssl/aspire` is used.
+- `defaultCertificateBundlePaths`: Overrides the path(s) in the container where a default certificate authority bundle file is located. When the `CertificateTrustScope` is Override or System, the custom certificate bundle is additionally written to these paths. If not set or set to `null`, a set of default certificate paths for common Linux distributions is used.


@IEvangelist does it feel okay to refer to the default values in this way or would it be better to include a section with the actual values (and the distro they should match)?

Initial plan

ffed840

Copilot AI assigned Copilot and IEvangelist Oct 20, 2025

Copilot started work on behalf of IEvangelist October 20, 2025 15:08 View session

Copilot AI and others added 2 commits October 20, 2025 15:13

Add certificate trust customization article

30afc34

Co-authored-by: IEvangelist <[email protected]>

Fix cross-reference title to match actual article title

babc661

Co-authored-by: IEvangelist <[email protected]>

Copilot AI changed the title ~~[WIP] Create draft article to address issue 5307~~ Add certificate trust customization article for Aspire 13 Oct 20, 2025

Copilot AI requested a review from IEvangelist October 20, 2025 15:20

Copilot finished work on behalf of IEvangelist October 20, 2025 15:20