Solicite um certificado Let's Encrypt com a API
Emita pela Azion API um certificado TLS assinado pela Let's Encrypt com o desafio DNS-01 ou HTTP-01 e depois verifique o status da emissão.
Você pode solicitar um certificado TLS assinado pela Let’s Encrypt™ pela Azion API, validado pelo desafio DNS-01 ou pelo desafio HTTP-01, inclusive um certificado wildcard. Para obter um certificado ao criar um workload no Azion Console, consulte Certificados.
Uma aplicação web servida por HTTPS precisa de um certificado TLS. A Let’s Encrypt emite um certificado gratuitamente, e a Azion automatiza a emissão, a renovação e a desativação dele. A Azion renova o certificado antes que ele expire, desde que as configurações de validação dele continuem válidas e atualizadas. A renovação não precisa de janela de manutenção, e o certificado mantém as cotas, o faturamento e as permissões dele.
Os dois desafios comprovam o controle do hostname de formas diferentes:
| Desafio | Valor de challenge | Como a Let’s Encrypt valida o hostname | Use quando |
|---|---|---|---|
| DNS-01 | dns | Um registro TXT no DNS do domínio | Você controla os registros DNS do domínio, o certificado cobre um domínio wildcard ou você não tem acesso direto ao servidor web |
| HTTP-01 | http | Um arquivo servido para o hostname, respondido por um serviço que a Azion executa | Você não controla os registros DNS e o domínio já aponta para a Azion |
Pré-requisitos
- Um personal token, enviado no header
AuthorizationcomoToken [TOKEN VALUE]. Para criar um, consulte Gerencie um personal token. - O
curlou outro cliente HTTP. - O hostname que o certificado cobre, como
www.example.com. - Para DNS-01 com uma zona hospedada por outro provedor de DNS, o registro CNAME
_acme-challengedo hostname, configurado nesse provedor. Uma zona no Edge DNS não precisa de registro. Para o nome e o valor do registro, consulte Validação de domínio. - Para HTTP-01, o DNS do hostname, e de cada nome alternativo, apontado para a Azion.
- Para um certificado wildcard, a zona do domínio configurada e ativa no Edge DNS.
Solicite um certificado com o desafio DNS-01
Com DNS-01, a Let’s Encrypt valida o hostname por um registro TXT no DNS do domínio. Quando a zona está no Edge DNS, a Azion insere o registro TXT, e você não configura nada. Quando outro provedor de DNS hospeda a zona, configure nele o registro CNAME _acme-challenge do hostname antes de enviar a requisição.
Para solicitar o certificado, envie uma requisição POST para https://api.azion.com/v4/workspace/tls/certificates/request. O corpo JSON da requisição carrega estes campos:
| Campo | Obrigatório | Valor |
|---|---|---|
name | Sim | Um nome para o certificado, como My certificate |
challenge | Sim | dns |
authority | Sim | lets_encrypt |
common_name | Sim | O hostname que o certificado cobre, como www.example.com |
alternative_names | Não | Os outros hostnames que o certificado cobre, ou uma lista vazia, [] |
key_algorithm | Não | rsa_2048, rsa_4096 ou ecc_384; ecc_384 quando omitido |
A API aceita a requisição e retorna o novo certificado com o id dele e um status pendente. Um status pendente significa que a Azion agendou a emissão. O id identifica o certificado quando você verifica o status dele.
Solicite um certificado wildcard
Um nome wildcard, como *.example.com, permite que um certificado cubra os subdomínios abaixo dele, que você não lista um a um. A Azion emite um certificado wildcard somente pelo desafio DNS-01. Quando a zona do domínio está configurada e ativa no Edge DNS, a Azion insere o registro TXT _acme-challenge na zona, e emite e renova o certificado sem nenhuma ação sua. Quando a zona não está ativa no Edge DNS, a validação precisa ser feita manualmente.
A solicitação passa pela API porque um workload não consegue solicitar um nome wildcard. Os domínios dele recusam uma entrada wildcard com The domain does not conform to the format defined in RFC 1035., e o formulário do workload solicita um certificado para esses domínios.
Para solicitar o certificado, envie a requisição DNS-01 com o nome wildcard em common_name:
A API retorna o certificado em data, com o id dele e status definido como pending. Um certificado pode carregar o nome wildcard sozinho ou ao lado de nomes específicos em alternative_names. Um subdomínio que o wildcard cobre, como blog.example.com, não precisa de uma entrada própria.
O certificado cobre os subdomínios, mas o workload que os atende ainda lista cada um deles por completo nos seus domínios, até 50 domínios por workload. Para esse limite, e como aumentá-lo, consulte Limites de Workloads. Para usar o certificado, verifique o status dele e depois vincule-o a esse workload, como as próximas seções descrevem.
Solicite um certificado com o desafio HTTP-01
Com HTTP-01, a Let’s Encrypt valida o hostname por um arquivo servido para ele. O DNS do domínio não precisa de registro TXT. A Azion executa o serviço que responde ao desafio HTTP-01 e conclui o desafio assim que a emissão termina. Este desafio atende a uma conta que gerencia muitos domínios e hostnames.
O hostname precisa apontar para a Azion antes de você enviar a requisição. Quando o certificado tem nomes alternativos, cada um deles precisa apontar para a Azion, ou a emissão falha. A Azion agenda a emissão mesmo quando nenhum workload com o hostname está publicado e ativo.
Para solicitar o certificado, envie uma requisição POST para https://api.azion.com/v4/workspace/tls/certificates/request. O corpo JSON da requisição carrega estes campos:
| Campo | Obrigatório | Valor |
|---|---|---|
name | Sim | Um nome para o certificado, como My certificate |
challenge | Sim | http |
authority | Sim | lets_encrypt |
common_name | Sim | O hostname que o certificado cobre, como www.example.com |
alternative_names | Não | Os outros hostnames que o certificado cobre, ou uma lista vazia, [] |
key_algorithm | Não | rsa_2048, rsa_4096 ou ecc_384; ecc_384 quando omitido |
A API aceita a requisição e retorna o novo certificado com o id dele e um status pendente. Um status pendente significa que a Azion agendou a emissão. O id identifica o certificado quando você verifica o status dele.
Verifique o status da emissão
Depois de uma solicitação de certificado, a Azion valida o hostname e emite o certificado. Para ver em que ponto a emissão está, envie uma requisição GET para https://api.azion.com/v4/workspace/tls/certificates/<certificate-id>, com o id que a solicitação retornou. A resposta retorna o certificado com o status atual dele.
Envie a requisição de novo até que o status mostre que a emissão terminou. Quando a emissão falha, o campo status_detail carrega o motivo, como An error has occurred while issuing the requested certificate. Please verify the following domains CNAME: www.example.com.
Para o significado de cada status, consulte Status. Para as novas tentativas que a Azion faz depois de uma tentativa que falhou, consulte Tempo de emissão e novas tentativas.
Os campos status e status_detail agora informam se a Azion emitiu o certificado ou por que ela não conseguiu emiti-lo.
Use o certificado em um workload
Um certificado protege o tráfego HTTPS assim que um workload o usa. Vincule o certificado emitido ao workload que atende o hostname: o id dele vai no campo tls.certificate do workload. Depois, ajuste as configurações de TLS e de HTTPS desse workload conforme a sua aplicação precisa. Para as configurações de certificado e de protocolo de um workload, consulte Configurações de workload.
Para vincular o certificado pelo Azion Console, pela Azion CLI ou pela API, consulte Vincule o certificado ao workload. No Azion Console, o certificado aparece em My certificates, no campo Digital Certificate do workload, que é exibido enquanto HTTPS support está ativado. Assim que o certificado é emitido e o vínculo se propaga, o certificado fica active, e a Azion o renova antes que ele expire.