Set up wildcard certificates
A wildcard certificate covers every generated app URL with one certificate, so a new app does not wait for a certificate of its own before it serves HTTPS. It also keeps a busy instance under Let’s Encrypt’s rate limits. By default, each generated URL gets its own certificate from tenant.certClusterIssuer, and Let’s Encrypt allows 50 certificates for each registered domain per week.
Let’s Encrypt only issues wildcards over a DNS-01 challenge, so you need API access to your DNS provider. This guide uses apps.example.com as the app domain.
You do not need this guide in these cases:
tunnelmode: Cloudflare serves the certificate for your names. For what it covers, refer to Install Orchard.- An
sslip.ioname: You cannot create the DNS records that DNS-01 needs. Use your own domain.
When you need a wildcard
Section titled “When you need a wildcard”Without a wildcard, each URL uses one certificate from Let’s Encrypt’s limits:
| Limit | Value |
|---|---|
| Certificates per registered domain | 50 per 7 days, refilling 1 per 202 minutes |
| Duplicate certificates for the same names | 5 per 7 days |
| New orders per account | 300 per 3 hours |
| Failed validations | 5 per name per hour |
The first limit is shared by every name under the registered domain, so apps.example.com, orchard.example.com, and every generated URL all count against example.com. Past about 50 new URLs a week, use a wildcard.
Prerequisites
Section titled “Prerequisites”- cert-manager installed in the cluster. The installer includes it in
publicandlanmode. - Your own domain, at a DNS provider that cert-manager supports.
- Credentials for your DNS provider.
What the chart renders
Section titled “What the chart renders”| Template | Renders | Condition |
|---|---|---|
certificates.yaml |
A Certificate for *.apps.example.com and apps.example.com in certificates.namespace. |
certificates.enabled, and an app domain is set. |
certificates.yaml |
A Certificate for *.<db domain>, for TLS on public databases. |
certificates.enabled, and wildcards.db.domain is set. |
_helpers.tpl |
PLATFORM_WILDCARD_DOMAINS on the server, which names the Secret to use on each Ingress. |
An app domain or tenant.wildcardDomains is set. |
The chart does not create the issuer.
Orchard routes each app through an Ingress. It does not support Gateway API yet, so gateway.enabled is off by default and the chart renders no Gateway.
1. Point DNS at the cluster
Section titled “1. Point DNS at the cluster”Create a wildcard record for the app domain that points at your ingress controller:
*.apps.example.com A 203.0.113.102. Create a DNS-01 issuer
Section titled “2. Create a DNS-01 issuer”cert-manager supports Cloudflare, Route53, AzureDNS, Google CloudDNS, DigitalOcean, Akamai, ACME-DNS, and RFC2136. For the settings of each provider, refer to the cert-manager DNS-01 documentation.
The following example uses Cloudflare. Create an API token with the Zone > DNS > Edit and Zone > Zone > Read permissions for your zone.
-
Create a Secret that holds the token:
kubectl -n cert-manager create secret generic cloudflare-api-token \--from-literal=api-token=<API_TOKEN> -
Save the issuer as
issuer.yaml:apiVersion: cert-manager.io/v1kind: ClusterIssuermetadata:name: letsencrypt-dns01-wildcardspec:acme:server: https://acme-v02.api.letsencrypt.org/directoryprivateKeySecretRef:name: letsencrypt-dns01-wildcard-accountsolvers:- dns01:cloudflare:apiTokenSecretRef:name: cloudflare-api-tokenkey: api-tokenThe chart looks for the name
letsencrypt-dns01-wildcard. To use another issuer, setcertificates.issuer.nameandcertificates.issuer.kind.To test without using your rate limit, set
servertohttps://acme-staging-v02.api.letsencrypt.org/directoryfirst. Browsers do not trust a staging certificate, so changeserverback when the test passes. -
Apply the issuer, and check that it is ready.
READYshould beTrue.kubectl apply -f issuer.yamlkubectl get clusterissuer letsencrypt-dns01-wildcard
3. Set the chart values
Section titled “3. Set the chart values”Add the following to your values file:
gateway: http: appDomain: apps.example.com appWildcardSecretName: wildcard-apps-example-com-tls
certificates: enabled: true namespace: network copyToTenants: true| Value | Purpose |
|---|---|
appDomain |
The wildcard that the certificate covers. Also sets APP_DOMAIN on the server and PUBLIC_APP_DOMAIN on the frontend. |
appWildcardSecretName |
Moves apps onto the wildcard. Without it, the chart issues the certificate but apps keep per-host certificates. |
certificates.namespace |
Where the certificate is stored. The namespace must exist. With createNamespace: true, the chart creates it. |
copyToTenants |
The server copies the Secret into each namespace with an Ingress that references it. |
If you use server.envFrom, the chart does not set APP_DOMAIN. Add it to your Secret.
If you run a secret replicator, such as reflector, leave copyToTenants as false. Do not use both. Two writers on the same Secret overwrite each other.
Apply the values with helm upgrade. At its next reconcile, the server moves existing generated hosts onto the wildcard Secret. Custom domains keep their own certificates.
cert-manager renews the certificate 15 days before it expires. With copyToTenants on, the server copies the renewed Secret into each namespace.
Installer hosts
Section titled “Installer hosts”The installer turns off certificates.enabled and gateway.http.enabled. To use a wildcard on an installer host:
-
Create the issuer as described in step 2. Run each
kubectlcommand withsudo. -
In
/etc/orchard/values.yaml, change the values that exist and add the others:gateway:http:appWildcardSecretName: wildcard-apps-example-com-tlscertificates:enabled: truecopyToTenants: true -
Apply the change:
sudo orchardctl update
Dashboard settings
Section titled “Dashboard settings”Instance admin > Configuration > Wildcard certificate edits the same mapping. A value that comes from the chart is locked, and the dashboard shows what to change instead. Use this page when you manage the Secret yourself and the chart does not set the value.
Several domains
Section titled “Several domains”For more than one wildcard, or a Secret that you manage yourself, set the mapping directly. It takes precedence over the derived value. The chart only issues certificates for the app domain and the database domain, so you provide the Secret for any other domain.
tenant: wildcardDomains: .apps.example.com=wildcard-apps-tls,.preview.example.com=wildcard-preview-tlsPublic databases
Section titled “Public databases”To use a wildcard for public database connections, name the domain and point the server at the same Secret. The domain must match PUBLIC_DB_DOMAIN on the server.
certificates: wildcards: db: enabled: true domain: db.example.com secretName: wildcard-db-example-com-tls
publicTls: db: sourceSecret: wildcard-db-example-com-tlsKeep the wildcard key out of tenant namespaces
Section titled “Keep the wildcard key out of tenant namespaces”By default the server copies the database wildcard Secret, including its private key, into every namespace that has a public database. Anyone who can exec into a database pod can read the key and impersonate every other database under that wildcard. On an instance with untrusted tenants, switch to one certificate per database:
publicTls: db: mode: perDatabase issuer: name: letsencrypt-dns01-wildcard kind: ClusterIssuerEach public database then gets its own cert-manager Certificate for its own hostname, and the wildcard key stays in certificates.namespace. Consider the following before you switch:
- The issuer must solve DNS-01 for the database domain, and each database counts against the ACME rate limits (50 certificates per registered domain per week for Let’s Encrypt).
- Existing public databases migrate on their own. The server issues the new certificate, points the cluster at it, and removes the copied wildcard Secret from a namespace once no cluster there uses it. Until the certificate is ready, the database keeps serving the wildcard.
- Newly enabled databases serve CNPG’s self-signed certificate until issuance completes, usually a few minutes.
- The per-database certificate covers only the namespace-qualified hostname. Set
publicTls.db.legacyHostnames: trueto keep clients that still use the older<cluster>.<db domain>hostname verifying, with the collision risk described in the chart README. - The server needs permission to create
Certificateobjects. The chart grants this only inperDatabasemode.
4. Verify the certificate
Section titled “4. Verify the certificate”-
Check that the certificate was issued.
READYshould beTrue.kubectl -n network get certificatekubectl -n network get secret wildcard-apps-example-com-tls -
Check that the server has the mapping:
kubectl -n orchard exec deploy/server -- printenv PLATFORM_WILDCARD_DOMAINSThe output should be as follows:
.apps.example.com=wildcard-apps-example-com-tls -
Check an app. Its namespace should have a copy of the Secret, and the subject should be
CN=*.apps.example.com.kubectl -n <APP_NAMESPACE> get secret wildcard-apps-example-com-tlskubectl -n <APP_NAMESPACE> get ingress -o yaml | grep secretNamecurl -vI https://<APP_HOST> 2>&1 | grep -E 'subject:|issuer:'
Troubleshoot the certificate
Section titled “Troubleshoot the certificate”The certificate stays False
Section titled “The certificate stays False”Check each resource in order. The challenge status shows what the DNS provider or Let’s Encrypt returned.
kubectl -n network describe certificate wildcard-apps-example-com-tlskubectl -n network get certificaterequest,order,challengekubectl -n network describe challengeThe Secret is missing from the app namespace
Section titled “The Secret is missing from the app namespace”Check that copyToTenants is on, or that your replicator covers that namespace.
Related resources
Section titled “Related resources”- Use a wildcard certificate - Set the wildcard from the dashboard during instance setup.
- Manage domains and HTTPS - Add custom domains, which keep their own certificates.
- Go to production - Prepare an instance for real users.