Skip to content

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Oct 20, 2025

Summary

This PR adds comprehensive documentation for the new certificate trust customization features introduced in Aspire 13, addressing issue #5307.

Changes

  • Created docs/app-host/certificate-trust.md: A comprehensive article documenting how to customize trusted certificates for Executable and Container resources
  • Updated docs/toc.yml: Added the new article to the AppHost section, positioned after "AppHost configuration"

Article Coverage

The new article provides detailed documentation on:

Core Features

  • Certificate Authority Collections: How to create and use custom certificate bundles using AddCertificateAuthorityCollection, WithCertificates, and WithCertificateAuthorityCollection APIs
  • Development Certificate Trust: Automatic trust for ASP.NET Core Development Certificate (enabled by default) and the WithDeveloperCertificateTrust API for per-resource control
  • Certificate Trust Scopes: Four modes (Append, Override, System, None) using the WithCertificateTrustScope API to control how custom certificates interact with default trusted certificates
  • Custom Callbacks: Advanced customization using WithExecutableCertificateTrustCallback and WithContainerCertificateTrustCallback for fine-grained control

Practical Guidance

  • Code examples for each major feature and API
  • Common scenarios including enabling HTTPS telemetry to the dashboard, trusting custom certificates in containers, and configuring Python apps
  • Limitations and considerations (run mode only, language/runtime support variations)
  • Cross-references to related documentation

Example Usage

var builder = DistributedApplication.CreateBuilder(args);

// Create a certificate authority collection
var certBundle = builder.AddCertificateAuthorityCollection("my-bundle")
    .WithCertificates(myCertificates);

// Apply to resources that need to trust these certificates
builder.AddNpmApp("my-project", "../myapp")
    .WithCertificateAuthorityCollection(certBundle);

// Configure trust scope for Python apps
builder.AddPythonModule("api", "./api", "uvicorn")
    .WithCertificateTrustScope(CertificateTrustScope.System);

builder.Build().Run();

Documentation Standards

The article follows all Aspire documentation guidelines:

  • Uses "Aspire" terminology (not ".NET Aspire")
  • Sentence case headings
  • Active voice, second person
  • AI usage disclosed in frontmatter
  • Passes markdownlint validation (0 errors)

Closes #5307

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

@Copilot 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 Copilot AI requested a review from IEvangelist October 20, 2025 15:20
Copilot finished work on behalf of IEvangelist October 20, 2025 15:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants