Request a Let's Encrypt certificate
Request a Let's Encrypt certificate for the domains of a workload, prepare the challenge records, and check the issuance status.
You can request a Let’s Encrypt™ certificate for the domains of a workload from Azion Console, the Azion CLI, or the API. To use a certificate you obtained from another certificate authority instead, refer to Upload a digital certificate.
HTTPS on your own hostname needs a server certificate that covers it, because the default Azion SAN certificate covers only the workload domain and the Azion Custom Domain. With a Let’s Encrypt certificate, Certificate Manager does the certificate work for you. Azion requests the certificate from Let’s Encrypt, completes the challenge that proves you control each hostname, and renews the certificate before it expires. Some older clients cannot validate the chain of a Let’s Encrypt certificate. For which clients, refer to Certificate chain.
An account that runs on API v3 with Domains selects the certificate on each domain instead. For more information, refer to Domains.
Select an interface. The prerequisites and the steps of each task follow your choice.
Prerequisites
- A workload on the production infrastructure whose domains list every hostname the certificate must cover. To list a hostname on a workload, refer to Add a custom domain to a workload.
- A domain your account has permission to use, registered in the Domain Name System (DNS).
- Access to the DNS records of the domain, at your DNS provider or in Edge DNS.
- Access to Azion Console. For more information, refer to How to access Azion Console.
Prepare the DNS records for the challenge
Let’s Encrypt issues the certificate only after it validates every hostname on the request. The challenge you choose decides which DNS records must exist before you send the request:
| Challenge | Console preset | challenge value | What the DNS needs before the request |
|---|---|---|---|
| HTTP-01 | New Let’s Encrypt Certificate (HTTP-01) | http | Every hostname already points to the workload domain |
| DNS-01 | New Let’s Encrypt Certificate (DNS-01) | dns | Nothing when the zone is in Edge DNS. With another DNS provider, one _acme-challenge record per hostname |
With DNS-01 and a zone in Edge DNS, Azion writes the _acme-challenge record into the zone and the challenge completes with no action from you. Choose DNS-01 when a hostname does not point to Azion yet, such as during a move from another provider. For how each challenge validates a hostname, refer to Domain validation.
At your DNS provider, create the records your challenge needs, one row per hostname:
| Name | Type | Value | Create it when |
|---|---|---|---|
Your hostname, such as www.example.com | CNAME | The workload domain, such as <id>.map.azionedge.net | HTTP-01: before the request. DNS-01: before you send traffic to the workload |
_acme-challenge.<your-domain>, such as _acme-challenge.www.example.com | CNAME | <your-domain>.letsencrypt.azion.com, such as www.example.com.letsencrypt.azion.com | DNS-01 with the zone at another DNS provider: before the request |
When Edge DNS holds the zone, create the hostname record there instead. For an apex domain, the record at each kind of provider, and how to check resolution, refer to Point a domain to a workload. For records and zones in Edge DNS, refer to Edge DNS guides and tutorials.
Keep the _acme-challenge record for as long as a workload uses the certificate. Azion renews the certificate 30 days before it expires by running the challenge again, and a deleted record makes the renewal fail.
Request the certificate
A Let’s Encrypt request names the main hostname as the common name and, optionally, other hostnames as alternative names. Every name must belong to a domain your account has permission to use.
To request the certificate with the Azion CLI, run azion create digital-certificate with the lets_encrypt authority. Set --challenge to dns or http, and list any other hostnames in --alternative-names, separated by commas:
The optional --key-algorithm flag takes rsa_2048, rsa_4096, or ecc_384. Azion accepts the request and schedules the issuance, and the new certificate is listed in Certificate Manager with the status pending.
To find the ID of the new certificate, list the certificates of the account:
The output lists each certificate with its ID, NAME, STATUS, TYPE, and MANAGED columns. A Let’s Encrypt certificate has the type edge_certificate, and MANAGED reads true.
A name on the request that your account has no permission for is refused. The Azion CLI prints the refusal as:
For the causes and fixes, refer to Troubleshoot Workloads. A workload cannot list a wildcard hostname, so the Console cannot request a wildcard certificate. To request one with the DNS-01 challenge, refer to Request a Let’s Encrypt certificate with the API.
Bind the certificate to the workload
A certificate protects HTTPS traffic only once a workload names it in its tls.certificate field. The Console preset binds the certificate it requests. A certificate you requested with the Azion CLI or the API needs this binding.
To bind the certificate with the Azion CLI, save a JSON file with the workload ID and the tls object, here as tls.json. The file repeats the workload’s ciphers and minimum_version, where 7 and tls_1_3 are the defaults:
Update the workload with the file:
The command prints the ID of the workload it updated:
A workload change takes several minutes to reach all of Azion’s distributed infrastructure, and requests can receive the old or the new configuration meanwhile. Once the certificate is issued and the change propagates, the certificate reads active and protects HTTPS on the workload’s domains.
Check the issuance status
Azion makes the first attempt to issue the certificate up to 5 minutes after the request. The status field of the certificate shows where the issuance stands.
To check the status with the Azion CLI, describe the certificate:
The output is the certificate as the API returns it. For a Let’s Encrypt certificate, managed is true, authority is lets_encrypt, and challenge is dns or http. Read status, and while it is failed, read the reason in status_detail.
The certificate moves from pending to challenge_verification while the challenge awaits validation. Once Let’s Encrypt issues it, it reads active while a workload names it, and inactive otherwise. When validation fails, it reads failed, and status_detail names the hostname to check, such as An error has occurred while issuing the requested certificate. Please verify the following domains CNAME: www.example.com.
A failed attempt is retried on a schedule, so a record you correct later can still end in an automatic issuance. For the retry schedule, refer to Issuance time and retries. For a certificate that stays pending or turns failed, refer to Troubleshoot Workloads.