CertManagerExtensions Methods

AddCertManager(IResourceBuilder<KubernetesEnvironmentResource>, string, string?)extensionIResourceBuilder<CertManagerResource>

Installs cert-manager into the Kubernetes environment and returns a typed CertManagerResource that can host issuer resources.

public static class CertManagerExtensions
{
    public static IResourceBuilder<CertManagerResource> AddCertManager(
        this IResourceBuilder<KubernetesEnvironmentResource> builder,
        string name,
        string? chartVersion = null)
    {
        // ...
    }
}

CertManagerExtensions.cs#L87-L143

Parameters

builderIResourceBuilder<KubernetesEnvironmentResource>The Kubernetes environment resource builder.

namestringThe Aspire resource name for the cert-manager installation. Each call adds a uniquely-named resource to the application model, so multiple Kubernetes environments must each pass distinct names.

chartVersionstring?optionalThe cert-manager Helm chart version to install. Defaults to a pinned version validated against this Aspire build.

Returns

IResourceBuilder<CertManagerResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

Remarks

Internally creates a KubernetesHelmChartResource via KubernetesHelmChartExtensions.AddHelmChart pointed at oci://quay.io/jetstack/charts/cert-manager. The chart is configured with:

crds.enabled = true — installs the cert-manager CRDs ( ClusterIssuer, Certificate, ...) so issuer manifests can be applied immediately afterwards.
config.enableGatewayAPI = true — lets cert-manager watch Gateway API Gateway / HTTPRoute resources for the cluster-issuer annotation.
WithForceConflicts() — works around the AKS Azure Policy add-on mutating cert-manager's ValidatingWebhookConfiguration after install.
WithDestroy() — uninstalls the Helm release on aspire destroy.

Issuer manifests are applied directly via kubectl apply at deploy time (not as part of the Helm release), and are deleted via kubectl delete on aspire destroy before the cert-manager Helm release itself is uninstalled.

To customise additional Helm values, access the underlying chart via CertManagerResource.HelmChart.

AddIssuer(IResourceBuilder<CertManagerResource>, string)extensionIResourceBuilder<CertManagerIssuerResource>

Adds a cert-manager ClusterIssuer to this cert-manager installation.

public static class CertManagerExtensions
{
    public static IResourceBuilder<CertManagerIssuerResource> AddIssuer(
        this IResourceBuilder<CertManagerResource> builder,
        string name)
    {
        // ...
    }
}

CertManagerExtensions.cs#L159-L170

Parameters

builderIResourceBuilder<CertManagerResource>The cert-manager resource builder.

namestringThe Aspire resource name. Also used as the metadata.name of the generated ClusterIssuer, so it must be a valid DNS-1123 label.

Returns

IResourceBuilder<CertManagerIssuerResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

WithAcmeServer(IResourceBuilder<CertManagerIssuerResource>, string, string)extensionIResourceBuilder<CertManagerIssuerResource>

Configures the issuer to use a custom ACME directory endpoint (e.g., a private ACME server such as ZeroSSL or step-ca).

public static class CertManagerExtensions
{
    public static IResourceBuilder<CertManagerIssuerResource> WithAcmeServer(
        this IResourceBuilder<CertManagerIssuerResource> builder,
        string serverUrl,
        string email)
    {
        // ...
    }
}

CertManagerExtensions.cs

Parameters

builderIResourceBuilder<CertManagerIssuerResource>The issuer resource builder.

serverUrlstringThe ACME directory URL (e.g., https://acme.example.com/directory).

emailstringThe contact email registered with the ACME account.

Returns

IResourceBuilder<CertManagerIssuerResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

WithAcmeServer(IResourceBuilder<CertManagerIssuerResource>, string, IResourceBuilder<ParameterResource>)extensionIResourceBuilder<CertManagerIssuerResource>

Configures the issuer to use a custom ACME directory endpoint with a parameterized email.

public static class CertManagerExtensions
{
    public static IResourceBuilder<CertManagerIssuerResource> WithAcmeServer(
        this IResourceBuilder<CertManagerIssuerResource> builder,
        string serverUrl,
        IResourceBuilder<ParameterResource> email)
    {
        // ...
    }
}

CertManagerExtensions.cs

Parameters

builderIResourceBuilder<CertManagerIssuerResource>The issuer resource builder.

serverUrlstringThe ACME directory URL (e.g., https://acme.example.com/directory).

emailIResourceBuilder<ParameterResource>A parameter resource builder whose value is the contact email registered with the ACME account.

Returns

IResourceBuilder<CertManagerIssuerResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

WithHttp01Solver(IResourceBuilder<CertManagerIssuerResource>)extensionIResourceBuilder<CertManagerIssuerResource>

Adds an HTTP-01 ACME challenge solver to the issuer. cert-manager will satisfy the challenge by provisioning a temporary HTTP route at /.well-known/acme-challenge/{token} on the same hostname being validated. This requires the hostname to be publicly reachable on port 80.

public static class CertManagerExtensions
{
    public static IResourceBuilder<CertManagerIssuerResource> WithHttp01Solver(
        this IResourceBuilder<CertManagerIssuerResource> builder)
    {
        // ...
    }
}

CertManagerExtensions.cs#L306-L309

Parameters

builderIResourceBuilder<CertManagerIssuerResource>The issuer resource builder.

Returns

IResourceBuilder<CertManagerIssuerResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

Remarks

HTTP-01 is the right choice for gateways exposed via Azure Application Gateway for Containers (AGC) or any ingress controller that publishes a publicly addressable hostname. Wildcard certificates require a DNS-01 solver, which is not yet supported.

WithLetsEncryptProduction(IResourceBuilder<CertManagerIssuerResource>, string)extensionIResourceBuilder<CertManagerIssuerResource>

Configures the issuer to use the Let's Encrypt production ACME endpoint.

public static class CertManagerExtensions
{
    public static IResourceBuilder<CertManagerIssuerResource> WithLetsEncryptProduction(
        this IResourceBuilder<CertManagerIssuerResource> builder,
        string email)
    {
        // ...
    }
}

CertManagerExtensions.cs

Parameters

builderIResourceBuilder<CertManagerIssuerResource>The issuer resource builder.

emailstringThe contact email registered with the ACME account. Let's Encrypt uses this address for expiry notifications and rate-limit appeals.

Returns

IResourceBuilder<CertManagerIssuerResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

Remarks

Production certificates are subject to strict per-domain rate limits (https://letsencrypt.org/docs/rate-limits/). For development workflows, prefer CertManagerExtensions.WithLetsEncryptStaging which uses untrusted staging certificates with much higher rate limits.

WithLetsEncryptProduction(IResourceBuilder<CertManagerIssuerResource>, IResourceBuilder<ParameterResource>)extensionIResourceBuilder<CertManagerIssuerResource>

Configures the issuer to use the Let's Encrypt production ACME endpoint, with the contact email supplied via a parameter resolved at deploy time.

public static class CertManagerExtensions
{
    public static IResourceBuilder<CertManagerIssuerResource> WithLetsEncryptProduction(
        this IResourceBuilder<CertManagerIssuerResource> builder,
        IResourceBuilder<ParameterResource> email)
    {
        // ...
    }
}

CertManagerExtensions.cs

Parameters

builderIResourceBuilder<CertManagerIssuerResource>The issuer resource builder.

emailIResourceBuilder<ParameterResource>A parameter resource builder whose value is the contact email registered with the ACME account.

Returns

IResourceBuilder<CertManagerIssuerResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

WithLetsEncryptStaging(IResourceBuilder<CertManagerIssuerResource>, string)extensionIResourceBuilder<CertManagerIssuerResource>

Configures the issuer to use the Let's Encrypt staging ACME endpoint. Certificates issued from staging are not trusted by browsers, but the endpoint has much higher rate limits, making it the right choice for development and CI workflows.

public static class CertManagerExtensions
{
    public static IResourceBuilder<CertManagerIssuerResource> WithLetsEncryptStaging(
        this IResourceBuilder<CertManagerIssuerResource> builder,
        string email)
    {
        // ...
    }
}

CertManagerExtensions.cs

Parameters

builderIResourceBuilder<CertManagerIssuerResource>The issuer resource builder.

emailstringThe contact email registered with the ACME account.

Returns

IResourceBuilder<CertManagerIssuerResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

WithLetsEncryptStaging(IResourceBuilder<CertManagerIssuerResource>, IResourceBuilder<ParameterResource>)extensionIResourceBuilder<CertManagerIssuerResource>

Configures the issuer to use the Let's Encrypt staging ACME endpoint, with the contact email supplied via a parameter resolved at deploy time.

public static class CertManagerExtensions
{
    public static IResourceBuilder<CertManagerIssuerResource> WithLetsEncryptStaging(
        this IResourceBuilder<CertManagerIssuerResource> builder,
        IResourceBuilder<ParameterResource> email)
    {
        // ...
    }
}

CertManagerExtensions.cs

Parameters

builderIResourceBuilder<CertManagerIssuerResource>The issuer resource builder.

emailIResourceBuilder<ParameterResource>A parameter resource builder whose value is the contact email registered with the ACME account.

Returns

IResourceBuilder<CertManagerIssuerResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

WithTls(IResourceBuilder<KubernetesGatewayResource>, IResourceBuilder<CertManagerIssuerResource>)extensionIResourceBuilder<KubernetesGatewayResource>

Adds an HTTPS listener to the gateway and wires it to the supplied cert-manager ClusterIssuer. This adds the cert-manager.io/cluster-issuer annotation to the generated Gateway resource, causing cert-manager to provision and renew a certificate for each gateway listener hostname.

public static class CertManagerExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithTls(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        IResourceBuilder<CertManagerIssuerResource> issuer)
    {
        // ...
    }
}

CertManagerExtensions.cs#L335-L352

Parameters

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

issuerIResourceBuilder<CertManagerIssuerResource>The cert-manager ClusterIssuer to issue certificates from.

Returns

IResourceBuilder<KubernetesGatewayResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

Remarks

Equivalent to calling WithTls() followed by WithGatewayAnnotation("cert-manager.io/cluster-issuer", issuer.Resource.Name), but type-safe and refactor-friendly. Throws if the gateway and the issuer's cert-manager installation are not part of the same Kubernetes environment, since cert-manager is per-cluster and would otherwise silently produce an unsatisfiable TLS configuration.