Certificates

Certificates (cert-manager) issues and renews TLS certificates. It runs cert-manager, and creates the ClusterIssuers your apps name: astro-letsencrypt and astro-letsencrypt-staging for Let's Encrypt, or astro-selfsigned. An app asks for a certificate with a Certificate resource or the cert-manager.io/cluster-issuer annotation on its Ingress, and the certificate lands as a Secret in the app's namespace. Model Serving and the Gateway need it.

When to use it

• You put an image app or a model on your domain. Without an issuer, the deploy is refused with No certificate issuer for this cluster: "Exposing an application on cluster <cluster> needs a ClusterIssuer, and none is configured." With Certificates and a Let's Encrypt issuer, each app's hostname gets a trusted certificate that renews on its own.
• You want one certificate for many apps. The Ingress wildcard certificate is issued by Certificates.
• Your endpoints are private, or not reachable over HTTP from the internet. With a DNS check (dnsSolver), Let's Encrypt checks each name through your DNS zone instead. See How a certificate is checked.
• You run an internal or test cluster. The self-signed issuer gives HTTPS with no public DNS and no ACME account; clients must trust its certificates.
• You run Model Serving or the Gateway. Both need it.

You don't need it when every exposed app ends its own TLS (the Ingress Passthrough mode), when apps are reached only inside the cluster, or when you run your own cert-manager and name its ClusterIssuer (below).

Before you start

• A cluster on Kubernetes 1.33 or newer.
• For Let's Encrypt: an email address for expiry notices.
• For the DNS check outside an EKS cluster AstroPulse created: access to your DNS zone.

In the console

After Version, its steps are Settings, DNS solver and Identity, then Advanced, Resources and Components. DNS solver and Identity apply to the Let's Encrypt issuer types and leave with any other. Review runs the dry run, and Ask Nova at the top of the steps answers about the open step.

1. Open the cluster from the cluster list, select the Add-ons tab, then Install Add-on, and pick Certificates. Keep Install CRDs on unless cert-manager's CRDs are already on the cluster.

   Open zoom view

   Installing Certificates: the version, Install CRDs, availability and resources

   

2. Keep Enable cluster issuer on, pick the Issuer type, and for Let's Encrypt enter the Email.

3. Optional: to check names through your DNS zone, fill in DNS solver: pick the Provider and its zone fields: Hosted zone ID, Project, or Resource group and Subscription ID. Outside an EKS cluster AstroPulse created, the DNS check also needs Identity: pick the Cloud and enter its AWS role ARN, GCP service account or Azure client ID (Give it access to your cloud).

   Open zoom view

   Configure Certificates with the ClusterIssuer on, its type, the ACME contact email and Prove domains with DNS-01

   

4. On Review, the dry run runs by itself; select Continue to deploy once it passes, then Deploy cert-manager.

You should see

The add-on reads Deployed. astroctl infra k8s addons get <cluster> cert-manager reports a tls block: the issuer, whether the HTTP check (http01) and the DNS check (dns01) can issue, and what each still needs.

Open zoom view

The Certificates add-on reading Deployed, with its health check passing

How a certificate is checked

Exposure	With dnsSolver	Without dnsSolver
Ingress	Through DNS (DNS-01). Private ingresses work too	Over HTTP (HTTP-01), only on an ingress reachable from the internet
Gateway	Through DNS (DNS-01)	None for Let's Encrypt; self-signed works

• The DNS check answers certificates labelled platform.astropulse.io/challenge: dns01. AstroPulse puts that label on every exposure it writes: the Gateway's certificate, and the Ingress of model and image applications. A Certificate of your own needs the label too. The DNS check also issues the Ingress wildcard certificate, which Let's Encrypt issues no other way.
• The HTTP check runs a small pod in the application's namespace, with requests and limits of 100m CPU and 128Mi memory, through the Ingress class nginx. A namespace whose minimum is larger refuses that pod and the certificate never issues: use the DNS check, which then covers every application on the cluster.
• LetsEncryptStaging uses Let's Encrypt's staging service, for testing: browsers don't trust its certificates. Each type has its own ClusterIssuer, so switching between them issues the certificates again.

Give it access to your cloud

Only the DNS check calls your cloud: it adds a short-lived TXT record to your zone to prove you own a name, and cert-manager removes it once the check is done. The HTTP check and the self-signed issuer call no cloud. The add-on runs as service account cert-manager in namespace cert-manager; everything below gives DNS permission to that one account.

Cluster	What to do
EKS, created by AstroPulse, zone in Route 53	Nothing. A Route 53 role for this add-on is created with the cluster, limited to the challenge records of your organization's verified domains, and the zone is found by name
EKS, created by AstroPulse, zone elsewhere	Set it up yourself, below
GKE or AKS, created by AstroPulse	Set it up yourself, below
Registered, any cloud	Set it up yourself, below

A dnsSolver with no identity is refused on the dry run, outside an EKS cluster AstroPulse created, so you find out before anything is installed. An identity you write always wins over the automatic one. Certificates has no secretRef: the DNS check runs on a workload identity alone. In the console, set it under Identity. The rules every add-on shares: Cloud access for add-ons.

• EKS: an IAM role that can write TXT records in your hosted zone, named in identity. Let Certificates add DNS challenge records in one Route 53 zone on EKS.
• GKE: a Google service account the cert-manager service account may act as. Let Certificates add DNS challenge records in Cloud DNS on GKE.
• AKS: a managed identity with DNS Zone Contributor on the zone, federated with cert-manager/cert-manager, named by its client ID annotation and the azure.workload.identity/use label. Let Certificates add DNS challenge records in one Azure DNS zone on AKS.

The cluster needs workload identity first: Enable workload identity on your cluster. Keep the grant to the zone (on GKE, to the project that holds your zones): a role that can change one record type in a zone can change the others.

Security: the DNS check signs in with a workload identity, so no DNS key is stored on the cluster or in AstroPulse. The role AstroPulse creates on EKS may write challenge records only under your organization's verified domains. Each certificate's private key stays in its Secret in the application's namespace.

Your own cert-manager

Running cert-manager yourself? Don't install this add-on; the install is refused while another one runs. Name your ClusterIssuer, and exposed applications get their certificates from it:

Terminal

astroctl infra k8s exposure set eks-prod --cluster-issuer my-issuer

Run it in production

Every TLS certificate on the cluster is issued and renewed by it.

• Test on staging first. Let's Encrypt production limits how many certificates you can issue for a domain; the staging issuer doesn't count toward them. See Let's Encrypt rate limits.
• While its webhook is down, new or changed certificates and issuers are refused. The webhook runs 2 copies on a cluster AstroPulse created with 2 or more fixed nodes.
• Uninstalling stops renewal. Certificates it issued keep serving until they expire, then clients reject them. Its definitions stay on the cluster.
• Keys live in the cluster. Each certificate is a Secret in its application's namespace, and the Let's Encrypt account key is a Secret named after its issuer. Back them up with the rest of the cluster's Secrets.

Other ways in

• Nova: ask it, for example "install Certificates on eks-prod with a Let's Encrypt issuer for ops@example.com".
• SDK and API: the same operations, in the API reference.

With astroctl

cert-manager.yaml

apiVersion: platform.astropulse.io/v1
kind: K8sClusterAddon
metadata:
  name: cert-manager
spec:
  clusterName: eks-prod
  configuration:
    certManager:
      issuerType: LetsEncrypt
      email: ops@example.com

Terminal

astroctl infra k8s addons apply -f cert-manager.yaml --dry-run
astroctl infra k8s addons apply -f cert-manager.yaml

To test the DNS check, ask for one certificate with the label. It is a real Let's Encrypt certificate and counts against its rate limits, so delete it afterwards:

dns-check.yaml

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: dns-check
  namespace: default
  labels:
    platform.astropulse.io/challenge: dns01
spec:
  secretName: dns-check-tls
  dnsNames:
    - test.example.com
  issuerRef:
    name: astro-letsencrypt
    kind: ClusterIssuer

Terminal

kubectl apply -f dns-check.yaml
kubectl get certificate dns-check --watch
kubectl delete certificate dns-check

READY turns True within a few minutes. If it stays False, kubectl describe challenge -n default shows the error from your cloud's DNS service.

Settings

Its own settings, under certManager, plus availability and resources.

Install CRDscertManager.installCRDs

Installs cert-manager's CRDs with the add-on. Turn it off only where they are managed separately.

Default

On.

Enable cluster issuercertManager.enableClusterIssuer

Creates AstroPulse's ClusterIssuers. Off installs cert-manager alone, issuing nothing until you add an issuer of your own.

Default

On.

Issuer typecertManager.issuerType

Where certificates come from.

Accepts

LetsEncrypt, LetsEncryptStaging or SelfSigned.

Default

LetsEncrypt once email is set; no issuer before that.

EmailcertManager.email

The address Let's Encrypt registers the account under and sends expiry notices to. Let's Encrypt issues nothing until it is set. Required with a Let's Encrypt type; unused for SelfSigned.

DNS solvercertManager.dnsSolver

Connects the DNS zone Let's Encrypt checks names in: provider (aws, gcp or azure; empty is the cluster's own cloud), and the zone's hostedZoneId (Route 53, optional: empty finds the zone by name), project (Cloud DNS, required) or resourceGroup and subscriptionId (Azure DNS, both required). Needs a Let's Encrypt type.

Default

Off. On an EKS cluster AstroPulse created, an apply that names none stores a Route 53 solver with the cluster's role.

IdentitycertManager.identity

The cloud workload identity the DNS check writes as: serviceAccountAnnotations on cert-manager's service account, and serviceAccountLabels on its pods. Required with dnsSolver, except on an EKS cluster AstroPulse created.

See

Give it access to your cloud

If it's refused

"email is required when issuerType is <issuer>: Let's Encrypt registers the account under it and sends expiry notices there"

Cause

A Let's Encrypt type with no email.

Fix

Enter the Email.

"dnsSolver needs identity.serviceAccountAnnotations on cluster "<cluster>": the DNS-01 solver writes challenge records as cert-manager's own cloud identity ..."

Cause

A DNS check with no identity, on a cluster other than an EKS cluster AstroPulse created.

Fix

Add identity for your zone (Give it access to your cloud), then apply again.

"dnsSolver extends the Let's Encrypt ClusterIssuers: leave enableClusterIssuer on and set issuerType to letsencrypt (the default) or letsencrypt-staging"

Cause

A DNS check with the issuer off, or with SelfSigned.

Fix

Turn Enable cluster issuer on with a Let's Encrypt type, or turn the DNS check off.

"cert-manager's DNS-01 solver answers challenges as the identity AstroPulse created with cluster "<cluster>", which may write challenge records only under your organization's verified domains, and it has none: ..."

Cause

An EKS cluster AstroPulse created, a DNS check, and no verified domain in your organization.

Fix

Add and verify a domain (astroctl domain add, then astroctl domain verify), then apply again.

"dnsSolver.project is required for provider google: the Cloud DNS project holding the zone"

Cause

A Cloud DNS solver with no project.

Fix

Enter the Project under DNS solver.

"dnsSolver.resourceGroup and dnsSolver.subscriptionId are required for provider azure: they locate the Azure DNS zone"

Cause

An Azure DNS solver without both.

Fix

Enter the Resource group and Subscription ID under DNS solver.

"cert-manager is already running on this cluster outside AstroPulse (<namespace>/<name>); AstroPulse installs one owner per brick. ..."

Cause

You already run cert-manager yourself.

Fix

Keep yours and name its ClusterIssuer (Your own cert-manager), or remove it before installing the add-on.

Next

• Automatic HTTPS
• Ingress TLS modes
• DNS Automation