Add Aspire.Hosting.Certbot integration for Certbot container support

[Copilot]

Description

Adds Aspire.Hosting.Certbot hosting integration for ACME-based certificate management via Certbot container.

New package: Aspire.Hosting.Certbot

• CertbotResource - Container resource for SSL/TLS certificate provisioning using ACME protocol
• AddCertbot() - Extension method to add Certbot with domain/email parameters (challenge methods must be configured separately)
• WithHttp01Challenge(int? port = 80) - Configures HTTP-01 challenge for domain validation with optional custom port
• WithCertbotCertificate<T>() - Convenience method that mounts certificates volume and calls WaitForCompletion automatically
• CertificatePath - Property exposing the path to the SSL/TLS certificate (fullchain.pem)
• PrivateKeyPath - Property exposing the path to the private key (privkey.pem)
• Shared volume at /etc/letsencrypt for certificate storage
• Pinned to certbot/certbot:v5.1.0
• Works with any ACME-compatible certificate authority (Let's Encrypt, ZeroSSL, etc.)
• Permission fixes automatically applied to allow non-root containers to read certificates

Usage:

var domain = builder.AddParameter("domain");
var email = builder.AddParameter("email");

var certbot = builder.AddCertbot("certbot", domain, email)
    .WithHttp01Challenge();

var myService = builder.AddContainer("myservice", "myimage")
                       .WithCertbotCertificate(certbot);

API Design:

• Challenge methods are opt-in via separate extension methods (WithHttp01Challenge(), future: WithDns01Challenge())
• Port 80 is no longer automatically published - explicitly configured when calling WithHttp01Challenge()
• Permission fixes are always applied automatically to ensure non-root container compatibility
• Args composition centralized in AddCertbot based on configured challenge method for better composition
• Challenge methods configure state, AddCertbot computes args from that state
• WithCertbotCertificate provides simplified API that automatically handles volume mounting and waiting for completion
• Can coexist with WithHttpsCertificate and WithHttpsCertificateConfiguration when used in different execution modes (e.g., Certbot in publish mode, developer certificates locally)
• README follows standard hosting integration guidelines with minimal, focused documentation

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Link to aspire-docs issue (consider using one of the following templates):
      • New (or update) doc-idea template
      • New breaking-change template
      • New diagnostic template
  • No

Original prompt

Add support for a lets encypt integration in Aspire.Hosting.LetsEncrypt. It's going to have cert bot container, see below for a useful configuration. Make sure it follows the pattern of other integrations:

e.g.:

// Let's Encrypt parameters (required when EnableHttps=true)
// Set via: Parameters__domain and Parameters__letsencrypt_email
var domain = builder.AddParameter("domain");
var letsEncryptEmail = builder.AddParameter("letsencrypt-email");

var certbot = builder.AddContainer("certbot", "certbot/certbot")
// Shared volume for certificates - both certbot and YARP mount this
.WithVolume("letsencrypt", "/etc/letsencrypt")
// Port 80 must be published to host for Let's Encrypt to reach the ACME challenge
.WithHttpEndpoint(port: 80, targetPort: 80)
.WithExternalHttpEndpoints()
.WithArgs(context =>
{
context.Args.Add("certonly");
context.Args.Add("--standalone");
context.Args.Add("--non-interactive");
context.Args.Add("--agree-tos");
context.Args.Add("-v");
context.Args.Add("--keep-until-expiring");
// Fix permissions so non-root containers (like YARP) can read the certs
context.Args.Add("--deploy-hook");
context.Args.Add("chmod -R 755 /etc/letsencrypt/live && chmod -R 755 /etc/letsencrypt/archive");
context.Args.Add("--email");
context.Args.Add(letsEncryptEmail.Resource);
context.Args.Add("-d");
context.Args.Add(domain.Resource);
});

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[davidfowl]

cc @danegsta

[davidfowl]

@copilot - Lets expose the Certificate and Private Key as propreties on CertbotResource

[Copilot]

@copilot - Lets expose the Certificate and Private Key as propreties on CertbotResource

Added CertificatePath and PrivateKeyPath properties to CertbotResource in commit 3d6ccad. Both return ReferenceExpression that resolves to the Let's Encrypt certificate paths (/etc/letsencrypt/live/{domain}/fullchain.pem and privkey.pem).

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 13248

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 13248"

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 13248

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 13248"

[mitchdenny]

Wonder whether we should make this Aspire.Hosting.Certbot instead. Rather than being LetsEncrypt brand specific

[danegsta]

Wonder whether we should make this Aspire.Hosting.Certbot instead. Rather than being LetsEncrypt brand specific

Yeah, it'd be nice to have something that'll work with any ACME compatible certificate source.

[danegsta]

I think we're going to have situations where users have multiple certificates (potentially even multiple Certbot certificates) for a resource for different purposes. There might be a server auth (HTTPS) certificate from Let's Encrypt, but also one or more client auth certificates from something like a Vault server on their network.

It's one of the reasons I named the new HTTPS APIs WithServerAuthenticationCertificate to differentiate from future client certificate usage. I think we'll need a similar model for publish time where it's not enough to just have a certificate, we need to consider what it's used for as well.

I'd love to see this integrate with those new APIs so we could do something like:

var certbot = builder.AddCertbot("mydomaincert", "mydomain", "email")
    .RunAsDevelopmentCertificate();

builder.AddYarp("gateway")
    .WithServerAuthenticationCertificate(certbot);

and have everything work at both run and publish.

[danegsta]

In the future we'd be able to have builder.AddKeyVaultCertificate("mycert") with the same conventions.

[davidfowl]

Does let’s encrypt support issuing more than just server certificates?

[davidfowl]

Ah I see we should rename the method

[danegsta]

Not after February 2026 they don't; but Certbot can be used to retrieve certificates from other providers that support the same protocol.

[danegsta]

This would be a great way to provision client certificates from a Vault server on a private network, for example.

[mitchdenny]

Wonder whether we should make this Aspire.Hosting.Certbot instead. Rather than being LetsEncrypt brand specific

Yeah, it'd be nice to have something that'll work with any ACME compatible certificate source.

ZeroSSL etc.

[davidfowl]

Let’s not over engineer the certbot integration. We need concrete implementations to flee out the abstractions. There’s no harm in modeling the concrete container and initially before understanding the abstraction.

See also keycloack and oauth

[davidfowl]

@copilot let’s make this Aspire.Hosting.Certbot

[mitchdenny]

Agree, but I think the right package name is Aspire.Hosting.Certbot because its not actually from LetsEncrypt. But we can make LetsEncrypt the default since that is what everyone normally thinks about.

[Copilot]

@copilot let’s make this Aspire.Hosting.Certbot

Renamed to Aspire.Hosting.Certbot in commit 87bb3cd. Also renamed WithCertbotCertificates to WithServerCertificates and updated all documentation to be ACME-agnostic rather than Let's Encrypt specific.

[danegsta]

I don't think we need to solve all the design problems right away, but we will have to effectively have to duplicate publish and run time certificate config until we do.

I fully expect we'll end up needing something like:

public interface ICertificateResource
{
    ReferenceExpression PemFormatCertificate { get; }
    ReferenceExpression PemFormatKey { get; }
    ReferenceExpression PfxFormatCertificate { get; }
    
}

We'd also need properties to indicate whether a certificate provider can provide the Pfx or Pem format assets (I assume some will only support PFX and others only PEM). But that would be a pattern that we could easily unify with the existing experimental certificate APIs (once we worked out all the other pesky design decisions we'd have to make).

[danegsta]

WithServerAuthenticationCertificateConfiguration was renamed to WithHttpsCertificateConifguration in main. Also, this comment should reference WithHttpsCertificate and WithHttpsDeveloperCertificate instead of the configuration callback API. Instead of telling users they can't use both APIs, we should instruct them not to use both at runtime; it's totally okay to use certbot and WithHttpsCertificate if certbot is only added when running in publish mode.

We should also add a note that the user needs to configure their application manually when using certbot (ideally with an example of configuring something like yarp via environment variables). The example should probably wrap the certbot config in a publish mode check.

[davidfowl]

@copilot implement this feedback

[Copilot]

Updated documentation in commit e6bba87:

• Changed references from WithServerAuthenticationCertificateConfiguration to WithHttpsCertificate and WithHttpsCertificateConfiguration
• Clarified that conflicts only occur at runtime, allowing both APIs to coexist when used in different execution modes
• Added comprehensive example showing publish mode usage with ExecutionContext.IsPublishMode check
• Included manual configuration example using environment variables for YARP

[danegsta]

Only concern I’ve got is whether we should keep the WithCertificateVolume API too (I’m willing to bet we’d end up removing it in the future).

[davidfowl]

@copilot lets remove WithCertificateVolume

[Copilot]

@copilot lets remove WithCertificateVolume

Removed WithCertificateVolume method in commit 2b408c0. Also removed related tests. Now there's only WithCertbotCertificate as the single, simplified API for mounting certificates. All 14 tests passing.

[Copilot]

Pull request overview

This PR adds a new Aspire.Hosting.Certbot hosting integration that provides support for ACME-based SSL/TLS certificate management via the Certbot container. The integration follows the standard Aspire hosting patterns with resource builders, extension methods, and appropriate test coverage.

Key changes:

• New CertbotResource class representing a Certbot container for certificate provisioning
• Extension methods (AddCertbot, WithHttp01Challenge, WithCertbotCertificate) following Aspire's fluent API patterns
• Challenge method configuration through separate extension methods (HTTP-01 initially, with DNS-01 planned for future)
• Comprehensive test coverage including unit tests, manifest validation, and argument null checks

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/Aspire.Hosting.Certbot/Aspire.Hosting.Certbot.csproj	New project file defining the Certbot hosting integration package with appropriate tags and references
src/Aspire.Hosting.Certbot/CertbotResource.cs	Core resource class representing a Certbot container with domain/email parameters and certificate path properties
src/Aspire.Hosting.Certbot/CertbotBuilderExtensions.cs	Extension methods for adding Certbot resources and configuring challenge methods
src/Aspire.Hosting.Certbot/CertbotContainerImageTags.cs	Container image version constants (certbot/certbot:v5.1.0)
src/Aspire.Hosting.Certbot/README.md	User-facing documentation for the integration with usage examples and configuration guidance
tests/Aspire.Hosting.Certbot.Tests/Aspire.Hosting.Certbot.Tests.csproj	Test project configuration
tests/Aspire.Hosting.Certbot.Tests/AddCertbotTests.cs	Comprehensive test suite covering resource creation, annotations, parameters, manifest generation, and edge cases
Aspire.slnx	Solution file updated to include the new projects