Add Aspire.Hosting.Certbot integration for Certbot container support

src/Aspire.Hosting.Certbot/CertbotBuilderExtensions.cs

@@ -41,8 +41,7 @@ public static class CertbotBuilderExtensions
     ///     .WithHttp01Challenge();
     ///
     /// var myService = builder.AddContainer("myservice", "myimage")
-    ///                        .WithVolume("letsencrypt", "/etc/letsencrypt")
-    ///                        .WaitForCompletion(certbot);
+    ///                        .WithCertbotCertificate(certbot);
     /// </code>
     /// </example>
     /// </remarks>
@@ -145,6 +144,10 @@ public static IResourceBuilder<CertbotResource> WithHttp01Challenge(
     /// This method adds the certificates volume to the specified container resource,
     /// allowing it to access SSL/TLS certificates obtained by Certbot.
     /// </para>
+    /// <para>
+    /// This method only mounts the volume. Consider using <see cref="WithCertbotCertificate{T}"/> instead,
+    /// which also ensures the container waits for certificate acquisition to complete.
+    /// </para>
     /// <example>
     /// <code lang="csharp">
     /// var domain = builder.AddParameter("domain");
@@ -169,4 +172,47 @@ public static IResourceBuilder<T> WithCertificateVolume<T>(
 
         return builder.WithVolume(CertbotResource.CertificatesVolumeName, mountPath);
     }
+
+    /// <summary>
+    /// Configures the container to use SSL/TLS certificates from a Certbot resource.
+    /// </summary>
+    /// <typeparam name="T">The type of the container resource.</typeparam>
+    /// <param name="builder">The resource builder for the container resource that needs access to the certificates.</param>
+    /// <param name="certbot">The Certbot resource builder.</param>
+    /// <param name="mountPath">The path where the certificates volume should be mounted. Defaults to /etc/letsencrypt.</param>
+    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
+    /// <remarks>
+    /// <para>
+    /// This method mounts the certificates volume and ensures the container waits for the Certbot
+    /// resource to complete certificate acquisition before starting.
+    /// </para>
+    /// <para>
+    /// <strong>Note:</strong> This method may conflict with <c>WithServerAuthenticationCertificateConfiguration</c>
+    /// if both are used on the same resource. Only use one certificate configuration method per resource.
+    /// </para>
+    /// <example>
+    /// <code lang="csharp">
+    /// var domain = builder.AddParameter("domain");
+    /// var email = builder.AddParameter("email");
+    ///
+    /// var certbot = builder.AddCertbot("certbot", domain, email)
+    ///     .WithHttp01Challenge();
+    ///
+    /// var yarp = builder.AddContainer("yarp", "myimage")
+    ///                   .WithCertbotCertificate(certbot);
+    /// </code>
+    /// </example>
+    /// </remarks>
+    public static IResourceBuilder<T> WithCertbotCertificate<T>(
+        this IResourceBuilder<T> builder,
+        IResourceBuilder<CertbotResource> certbot,
+        string mountPath = CertbotResource.CertificatesPath) where T : ContainerResource, IResourceWithWaitSupport
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(certbot);
+
+        return builder
+            .WithVolume(CertbotResource.CertificatesVolumeName, mountPath)
+            .WaitForCompletion(certbot);
+    }
 }

src/Aspire.Hosting.Certbot/README.md

@@ -24,15 +24,15 @@ var certbot = builder.AddCertbot("certbot", domain, email)
     .WithHttp01Challenge();
 
 var myService = builder.AddContainer("myservice", "myimage")
-                       .WithCertificateVolume(certbot)
-                       .WaitForCompletion(certbot);
+                       .WithCertbotCertificate(certbot);
 ```
 
 The certbot container will:
 
 - Obtain certificates for the specified domain using the ACME protocol
 - Store certificates in a shared volume at `/etc/letsencrypt`
 - Use the configured challenge method (e.g., HTTP-01) for domain validation
+- Ensure dependent containers wait for certificate acquisition before starting
 
 ## Configuration
 
@@ -76,12 +76,23 @@ Certificate permissions are automatically set to allow non-root containers to re
 
 ### Sharing Certificates with Other Resources
 
-Use the `WithCertificateVolume` extension method to mount the certificates volume in other containers:
+Use the `WithCertbotCertificate` extension method to configure a container with certificates from Certbot:
 
 ```csharp
 var yarp = builder.AddContainer("yarp", "myimage")
-                  .WithCertificateVolume(certbot)
-                  .WaitForCompletion(certbot);
+                  .WithCertbotCertificate(certbot);
+```
+
+This method automatically:
+- Mounts the certificates volume at `/etc/letsencrypt`
+- Ensures the container waits for certificate acquisition to complete
+
+For more control, you can use `WithCertificateVolume` and `WaitForCompletion` separately:
+
+```csharp
+var myService = builder.AddContainer("myservice", "myimage")
+                       .WithCertificateVolume(certbot)
+                       .WaitForCompletion(certbot);
 ```
 
 Or mount the volume directly:
@@ -92,6 +103,8 @@ var myService = builder.AddContainer("myservice", "myimage")
                        .WaitForCompletion(certbot);
 ```
 
+**Important:** Do not use `WithCertbotCertificate` or `WithCertificateVolume` together with `WithServerAuthenticationCertificateConfiguration` on the same resource, as they may conflict. Choose one certificate configuration method per resource.
+
 ### Certificate Locations
 
 After Certbot obtains certificates, they are available at:
@@ -114,7 +127,7 @@ var privateKeyPath = certbot.Resource.PrivateKeyPath;     // /etc/letsencrypt/li
 
 The Certbot resource does not expose connection properties through `WithReference`. This is because the Certbot resource is a certificate provisioning tool, not a service that other resources connect to.
 
-Instead, use the `WithCertificateVolume` extension method to share certificates with other containers via a mounted volume. See the [Sharing Certificates with Other Resources](#sharing-certificates-with-other-resources) section above for usage examples.
+Instead, use the `WithCertbotCertificate` extension method to configure containers with certificates from Certbot. This method handles mounting the certificates volume and waiting for certificate acquisition. See the [Sharing Certificates with Other Resources](#sharing-certificates-with-other-resources) section above for usage examples.
 
 ## Additional documentation
 

tests/Aspire.Hosting.Certbot.Tests/AddCertbotTests.cs

@@ -282,4 +282,49 @@ public void WithHttp01ChallengeWithCustomPort()
         Assert.Equal(80, endpoint.TargetPort);
         Assert.Equal(8080, endpoint.Port);
     }
+
+    [Fact]
+    public void WithCertbotCertificateAddsVolumeAndWaitAnnotations()
+    {
+        using var builder = TestDistributedApplicationBuilder.Create();
+        var domain = builder.AddParameter("domain");
+        var email = builder.AddParameter("email");
+        var certbot = builder.AddCertbot("certbot", domain, email);
+
+        var container = builder.AddContainer("test", "testimage")
+                               .WithCertbotCertificate(certbot);
+
+        // Check volume annotation
+        var volumes = container.Resource.Annotations.OfType<ContainerMountAnnotation>().ToList();
+        Assert.Single(volumes);
+        var volumeAnnotation = volumes[0];
+        Assert.Equal("letsencrypt", volumeAnnotation.Source);
+        Assert.Equal("/etc/letsencrypt", volumeAnnotation.Target);
+        Assert.Equal(ContainerMountType.Volume, volumeAnnotation.Type);
+
+        // Check wait annotation
+        var waitAnnotations = container.Resource.Annotations.OfType<WaitAnnotation>().ToList();
+        Assert.Single(waitAnnotations);
+        var waitAnnotation = waitAnnotations[0];
+        Assert.Equal(certbot.Resource, waitAnnotation.Resource);
+        Assert.Equal(WaitType.WaitForCompletion, waitAnnotation.WaitType);
+    }
+
+    [Fact]
+    public void WithCertbotCertificateWithCustomMountPath()
+    {
+        using var builder = TestDistributedApplicationBuilder.Create();
+        var domain = builder.AddParameter("domain");
+        var email = builder.AddParameter("email");
+        var certbot = builder.AddCertbot("certbot", domain, email);
+
+        var container = builder.AddContainer("test", "testimage")
+                               .WithCertbotCertificate(certbot, "/custom/certs");
+
+        var volumes = container.Resource.Annotations.OfType<ContainerMountAnnotation>().ToList();
+        Assert.Single(volumes);
+        var volumeAnnotation = volumes[0];
+        Assert.Equal("letsencrypt", volumeAnnotation.Source);
+        Assert.Equal("/custom/certs", volumeAnnotation.Target);
+    }
 }