From eb92de2577665baad08e73058abbc3f95fa89cf1 Mon Sep 17 00:00:00 2001 From: Max Ehrlich Date: Mon, 13 Aug 2018 13:23:42 -0400 Subject: [PATCH] More in-depth example going with curl and the API directly Signed-off-by: Max Ehrlich --- docs/reference/issuers/acme/dns01.rst | 60 +++++++++++++++++++++------ 1 file changed, 48 insertions(+), 12 deletions(-) diff --git a/docs/reference/issuers/acme/dns01.rst b/docs/reference/issuers/acme/dns01.rst index 411453d45..a05686df3 100644 --- a/docs/reference/issuers/acme/dns01.rst +++ b/docs/reference/issuers/acme/dns01.rst @@ -149,20 +149,20 @@ ACME-DNS acmedns: host: https://acme.example.com - accountsSecretRef: + accountSecretRef: name: acme-dns key: acmedns.json In general, clients to acme-dns perform registration on the users behalf and inform them of the CNAME entries they must create. This is not possible in cert-manager, it is a non-interactive system. Registration must be carried out beforehand and the resulting -credentials JSON uploaded to the cluster as a secret. There are several ways to accomplish this: +credentials JSON uploaded to the cluster as a secret. In this example, we use ``curl`` and the +API endpoints directly. Information about setting up and configuring acme-dns is available on +the `acme-dns project page `_. -1. Using certbot, follow the instructions in the `official certbot hook `_ You can either create a certificate or cancel the process after it informs you of the CNAME record. The resulting `acmedns.json` will be stored in `/etc/letsencrypt` +1. First, register with the acme-dns server, in this example, there is one running at "auth.example.com" -2. Using the `acme-dns client `_ follow the instructions for "Pre-Registration", the location of the accounts JSON file can be specified as an argument. The CNAME record will be printed by the command. - -3. Manually using the API. ``curl -X POST http://auth.example.com/register`` will return a JSON for your registration: + ``curl -X POST http://auth.example.com/register`` will return a JSON with credentials for your registration: .. code-block :: json @@ -174,8 +174,26 @@ credentials JSON uploaded to the cluster as a secret. There are several ways to "allowfrom":[] } + It is strongly recommended to restrict the update endpoint to the IP range of your pods. + This is done at registration time as follows: - Save this JSON to a file with the key as your domain: + ``curl -X POST http://auth.example.com/register -H "Content-Type: application/json" --data '{"allowfrom": ["10.244.0.0/16"]}'`` + + Make sure to update the ``allowfrom`` field to match your cluster configuration. The JSON will now look like + + .. code-block :: json + + { + "username":"eabcdb41-d89f-4580-826f-3e62e9755ef2", + "password":"pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0", + "fulldomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com", + "subdomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf", + "allowfrom":["10.244.0.0/16"] + } + +2. Save this JSON to a file with the key as your domain. You can specify multiple domains with the same credentials + if you like. In our example, the returned credentials can be used to verify ownership of "example.com" and + and "example.org". .. code-block :: json @@ -185,16 +203,34 @@ credentials JSON uploaded to the cluster as a secret. There are several ways to "password":"pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0", "fulldomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com", "subdomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf", - "allowfrom":[] + "allowfrom":["10.244.0.0/16"] + }, + "example.org": { + "username":"eabcdb41-d89f-4580-826f-3e62e9755ef2", + "password":"pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0", + "fulldomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com", + "subdomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf", + "allowfrom":["10.244.0.0/16"] } } - You will need to form the CNAME record manually. In this case it would look like +3. Next update your primary DNS server with CNAME record that will tell the verifier how to locate the challenge TXT + record. This is obtained from the "fulldomain" field in the registration: - ``_acme_challenge.example.com CNAME d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com`` + ``_acme-challenge.example.com CNAME d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com`` + ``_acme-challenge.example.org CNAME d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com`` -In all cases, create a secret from the json file: -``kubectl create secret generic acme-dns --from-file acmedns.json`` + Note that the "name" of the record is always the "_acme-challenge" subdomain, and the "value" of the record matches + exactly the "fulldomain" field from registration. + + At verification time, the domain name ``d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com`` will be a TXT + record that is set to your validation token. When the verifier queries ``_acme-challenge.example.com``, it will + be directed to the correct location by this CNAME record. This proves that you control "example.com" + +4. Create a secret from the credentials json that was saved in step 2, this secret is referenced + in the ``accountSecretRef`` field of your dns01 issuer settings. + + ``kubectl create secret generic acme-dns --from-file acmedns.json`` .. _`Let's Encrypt`: https://letsencrypt.org