# CertManagerExtensions Methods

- Package: [Aspire.Hosting.Kubernetes](/reference/api/csharp/aspire.hosting.kubernetes.md)
- Type: [CertManagerExtensions](/reference/api/csharp/aspire.hosting.kubernetes/certmanagerextensions.md)
- Kind: `Methods`
- Members: `10`

Provides extension methods for installing cert-manager into a Kubernetes environment and declaring `ClusterIssuer` resources against it.

## AddCertManager(IResourceBuilder<KubernetesEnvironmentResource>, string, string?)

- Name: `AddCertManager(IResourceBuilder<KubernetesEnvironmentResource>, string, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<CertManagerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/becb48e2d61099e35ae336d527d3875e928d6594/src/Aspire.Hosting.Kubernetes/CertManagerExtensions.cs#L87-L143)

Installs cert-manager into the Kubernetes environment and returns a typed [CertManagerResource](/reference/api/csharp/aspire.hosting.kubernetes/certmanagerresource.md) that can host issuer resources.

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

## Parameters

- `builder` (`IResourceBuilder<KubernetesEnvironmentResource>`)
  The Kubernetes environment resource builder.
- `name` (`string`)
  The 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.
- `chartVersion` (`string?`) `optional`
  The 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](/reference/api/csharp/aspire.hosting.kubernetes/kuberneteshelmchartresource.md) via [KubernetesHelmChartExtensions.AddHelmChart(IResourceBuilder<KubernetesEnvironmentResource>, string, string, string)](/reference/api/csharp/aspire.hosting.kubernetes/kuberneteshelmchartextensions/methods.md#addhelmchart-iresourcebuilder-kubernetesenvironmentresource-string-string-string) 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](/reference/api/csharp/aspire.hosting.kubernetes/certmanagerresource/properties.md#helmchart).

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## AddIssuer(IResourceBuilder<CertManagerResource>, string)

- Name: `AddIssuer(IResourceBuilder<CertManagerResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<CertManagerIssuerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/becb48e2d61099e35ae336d527d3875e928d6594/src/Aspire.Hosting.Kubernetes/CertManagerExtensions.cs#L159-L170)

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

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

## Parameters

- `builder` (`IResourceBuilder<CertManagerResource>`)
  The cert-manager resource builder.
- `name` (`string`)
  The 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.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithAcmeServer(IResourceBuilder<CertManagerIssuerResource>, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<CertManagerIssuerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/becb48e2d61099e35ae336d527d3875e928d6594/src/Aspire.Hosting.Kubernetes/CertManagerExtensions.cs)

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

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

## Parameters

- `builder` (`IResourceBuilder<CertManagerIssuerResource>`)
  The issuer resource builder.
- `serverUrl` (`string`)
  The ACME directory URL (e.g., `https://acme.example.com/directory`).
- `email` (`string`)
  The contact email registered with the ACME account.

## Returns

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithAcmeServer(IResourceBuilder<CertManagerIssuerResource>, string, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<CertManagerIssuerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/becb48e2d61099e35ae336d527d3875e928d6594/src/Aspire.Hosting.Kubernetes/CertManagerExtensions.cs)

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

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

## Parameters

- `builder` (`IResourceBuilder<CertManagerIssuerResource>`)
  The issuer resource builder.
- `serverUrl` (`string`)
  The ACME directory URL (e.g., `https://acme.example.com/directory`).
- `email` (`IResourceBuilder<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.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithHttp01Solver(IResourceBuilder<CertManagerIssuerResource>)

- Name: `WithHttp01Solver(IResourceBuilder<CertManagerIssuerResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<CertManagerIssuerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/becb48e2d61099e35ae336d527d3875e928d6594/src/Aspire.Hosting.Kubernetes/CertManagerExtensions.cs#L306-L309)

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.

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

## Parameters

- `builder` (`IResourceBuilder<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.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithLetsEncryptProduction(IResourceBuilder<CertManagerIssuerResource>, string)

- Name: `WithLetsEncryptProduction(IResourceBuilder<CertManagerIssuerResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<CertManagerIssuerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/becb48e2d61099e35ae336d527d3875e928d6594/src/Aspire.Hosting.Kubernetes/CertManagerExtensions.cs)

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

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

## Parameters

- `builder` (`IResourceBuilder<CertManagerIssuerResource>`)
  The issuer resource builder.
- `email` (`string`)
  The 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/](https://letsencrypt.org/docs/rate-limits/)). For development workflows, prefer [CertManagerExtensions.WithLetsEncryptStaging(IResourceBuilder<CertManagerIssuerResource>, string)](/reference/api/csharp/aspire.hosting.kubernetes/certmanagerextensions/methods.md#withletsencryptstaging-iresourcebuilder-certmanagerissuerresource-string) which uses untrusted staging certificates with much higher rate limits.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithLetsEncryptProduction(IResourceBuilder<CertManagerIssuerResource>, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<CertManagerIssuerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/becb48e2d61099e35ae336d527d3875e928d6594/src/Aspire.Hosting.Kubernetes/CertManagerExtensions.cs)

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

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

## Parameters

- `builder` (`IResourceBuilder<CertManagerIssuerResource>`)
  The issuer resource builder.
- `email` (`IResourceBuilder<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.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithLetsEncryptStaging(IResourceBuilder<CertManagerIssuerResource>, string)

- Name: `WithLetsEncryptStaging(IResourceBuilder<CertManagerIssuerResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<CertManagerIssuerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/becb48e2d61099e35ae336d527d3875e928d6594/src/Aspire.Hosting.Kubernetes/CertManagerExtensions.cs)

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.

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

## Parameters

- `builder` (`IResourceBuilder<CertManagerIssuerResource>`)
  The issuer resource builder.
- `email` (`string`)
  The contact email registered with the ACME account.

## Returns

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithLetsEncryptStaging(IResourceBuilder<CertManagerIssuerResource>, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<CertManagerIssuerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/becb48e2d61099e35ae336d527d3875e928d6594/src/Aspire.Hosting.Kubernetes/CertManagerExtensions.cs)

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

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

## Parameters

- `builder` (`IResourceBuilder<CertManagerIssuerResource>`)
  The issuer resource builder.
- `email` (`IResourceBuilder<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.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithTls(IResourceBuilder<KubernetesGatewayResource>, IResourceBuilder<CertManagerIssuerResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/becb48e2d61099e35ae336d527d3875e928d6594/src/Aspire.Hosting.Kubernetes/CertManagerExtensions.cs#L335-L352)

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.

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

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `issuer` (`IResourceBuilder<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.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.