Skip to content
Install

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:

  • tunnel mode: Cloudflare serves the certificate for your names. For what it covers, refer to Install Orchard.
  • An sslip.io name: You cannot create the DNS records that DNS-01 needs. Use your own domain.

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.

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.

Create a wildcard record for the app domain that points at your ingress controller:

*.apps.example.com A 203.0.113.10

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.

  1. Create a Secret that holds the token:

    kubectl -n cert-manager create secret generic cloudflare-api-token \
    --from-literal=api-token=<API_TOKEN>
  2. Save the issuer as issuer.yaml:

    apiVersion: cert-manager.io/v1
    kind: ClusterIssuer
    metadata:
    name: letsencrypt-dns01-wildcard
    spec:
    acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
    name: letsencrypt-dns01-wildcard-account
    solvers:
    - dns01:
    cloudflare:
    apiTokenSecretRef:
    name: cloudflare-api-token
    key: api-token

    The chart looks for the name letsencrypt-dns01-wildcard. To use another issuer, set certificates.issuer.name and certificates.issuer.kind.

    To test without using your rate limit, set server to https://acme-staging-v02.api.letsencrypt.org/directory first. Browsers do not trust a staging certificate, so change server back when the test passes.

  3. Apply the issuer, and check that it is ready. READY should be True.

    kubectl apply -f issuer.yaml
    kubectl get clusterissuer letsencrypt-dns01-wildcard

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.

The installer turns off certificates.enabled and gateway.http.enabled. To use a wildcard on an installer host:

  1. Create the issuer as described in step 2. Run each kubectl command with sudo.

  2. In /etc/orchard/values.yaml, change the values that exist and add the others:

    gateway:
    http:
    appWildcardSecretName: wildcard-apps-example-com-tls
    certificates:
    enabled: true
    copyToTenants: true
  3. Apply the change:

    sudo orchardctl update

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.

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-tls

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-tls

Keep 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: ClusterIssuer

Each 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: true to 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 Certificate objects. The chart grants this only in perDatabase mode.
  1. Check that the certificate was issued. READY should be True.

    kubectl -n network get certificate
    kubectl -n network get secret wildcard-apps-example-com-tls
  2. Check that the server has the mapping:

    kubectl -n orchard exec deploy/server -- printenv PLATFORM_WILDCARD_DOMAINS

    The output should be as follows:

    .apps.example.com=wildcard-apps-example-com-tls
  3. 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-tls
    kubectl -n <APP_NAMESPACE> get ingress -o yaml | grep secretName
    curl -vI https://<APP_HOST> 2>&1 | grep -E 'subject:|issuer:'

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-tls
kubectl -n network get certificaterequest,order,challenge
kubectl -n network describe challenge

The 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.