# Set up wildcard certificates > Issue one certificate for every generated Orchard app URL with a cert-manager DNS-01 issuer and the Helm chart. Source: https://docs.orchard.hackclub.com/operate/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](/start/install/). - **An `sslip.io` name:** You cannot create the DNS records that DNS-01 needs. Use your own domain. ## 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 - cert-manager installed in the cluster. The installer includes it in `public` and `lan` mode. - Your own domain, at a [DNS provider that cert-manager supports](https://cert-manager.io/docs/configuration/acme/dns01/). - Credentials for your DNS provider. ## 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 `*.`, 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 Create a wildcard record for the app domain that points at your ingress controller: ```txt *.apps.example.com A 203.0.113.10 ``` ## 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](https://cert-manager.io/docs/configuration/acme/dns01/). 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: ```bash kubectl -n cert-manager create secret generic cloudflare-api-token \ --from-literal=api-token= ``` 2. Save the issuer as `issuer.yaml`: ```yaml apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: letsencrypt-dns01-wildcard spec: acme: server: https://acme-v02.api.letsencrypt.org/directory email: you@example.com 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`. ```bash kubectl apply -f issuer.yaml kubectl get clusterissuer letsencrypt-dns01-wildcard ``` ## 3. Set the chart values Add the following to your values file: ```yaml 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](https://github.com/emberstack/kubernetes-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 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: ```yaml gateway: http: appWildcardSecretName: wildcard-apps-example-com-tls certificates: enabled: true copyToTenants: true ``` 3. Apply the change: ```bash sudo orchardctl update ``` ### 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 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. ```yaml tenant: wildcardDomains: .apps.example.com=wildcard-apps-tls,.preview.example.com=wildcard-preview-tls ``` ### Public databases To use a wildcard for [public database connections](/data/databases/#public-access), name the domain and point the server at the same Secret. The domain must match `PUBLIC_DB_DOMAIN` on the server. ```yaml 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 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: ```yaml 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 `.` 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. ## 4. Verify the certificate 1. Check that the certificate was issued. `READY` should be `True`. ```bash kubectl -n network get certificate kubectl -n network get secret wildcard-apps-example-com-tls ``` 2. Check that the server has the mapping: ```bash kubectl -n orchard exec deploy/server -- printenv PLATFORM_WILDCARD_DOMAINS ``` The output should be as follows: ```txt .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`. ```bash kubectl -n get secret wildcard-apps-example-com-tls kubectl -n get ingress -o yaml | grep secretName curl -vI https:// 2>&1 | grep -E 'subject:|issuer:' ``` ## Troubleshoot the certificate ### The certificate stays `False` Check each resource in order. The challenge status shows what the DNS provider or Let's Encrypt returned. ```bash 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 Check that `copyToTenants` is on, or that your replicator covers that namespace. ## Related resources - [Use a wildcard certificate](/operate/finishing-setup/#use-a-wildcard-certificate) - Set the wildcard from the dashboard during instance setup. - [Manage domains and HTTPS](/deploy/domains/) - Add custom domains, which keep their own certificates. - [Go to production](/operate/production/) - Prepare an instance for real users.