diff --git a/docs/redirects b/docs/redirects index 8a4f8a0d9..752096278 100644 --- a/docs/redirects +++ b/docs/redirects @@ -1,9 +1,11 @@ admin/resource-validation-webhook.rst getting-started/webhook.rst getting-started/1-configuring-helm.rst getting-started/install.rst getting-started/2-install.rst getting-started/install.rst -getting-started/3-configuring-first-issuer.rst tasks/issuers/index +getting-started/3-configuring-first-issuer.rst tasks/issuers/index.rst +tasks/acme/issuing-certificates.rst tasks/issuers/setup-acme/index.rst +tasks/issuers/setup-acme.rst tasks/issuers/setup-acme/index.rst tutorials/acme/index.rst tasks/acme/index.rst -tutorials/acme/securing-nginx-ingress-with-letsencrypt.rst tutorials/quick-start/index.rst +tutorials/acme/securing-nginx-ingress-with-letsencrypt.rst tutorials/acme/quick-start/index.rst tutorials/ca/creating-ca-issuer.rst tasks/issuers/setup-ca.rst tutorials/ca/index.rst tasks/issuers/setup-ca.rst tutorials/vault/creating-vault-issuers.rst tasks/issuers/setup-vault.rst @@ -20,3 +22,15 @@ admin/upgrading/upgrading-0.2-0.3.rst tasks/upgrading/upgrading-0.2-0.3.rst admin/upgrading/upgrading-0.3-0.4.rst tasks/upgrading/upgrading-0.3-0.4.rst admin/upgrading/upgrading-0.4-0.5.rst tasks/upgrading/upgrading-0.4-0.5.rst admin/upgrading/upgrading-0.5-0.6.rst tasks/upgrading/upgrading-0.5-0.6.rst +tasks/acme/index.rst tasks/issuers/setup-acme/index.rst +tasks/acme/configuring-dns01/index.rst tasks/issuers/setup-acme/dns01/index.rst +tasks/acme/configuring-dns01/acme-dns.rst tasks/issuers/setup-acme/dns01/acme-dns.rst +tasks/acme/configuring-dns01/akamai.rst tasks/issuers/setup-acme/dns01/akamai.rst +tasks/acme/configuring-dns01/azuredns.rst tasks/issuers/setup-acme/dns01/azuredns.rst +tasks/acme/configuring-dns01/cloudflare.rst tasks/issuers/setup-acme/dns01/cloudflare.rst +tasks/acme/configuring-dns01/digitalocean.rst tasks/issuers/setup-acme/dns01/digitalocean.rst +tasks/acme/configuring-dns01/google.rst tasks/issuers/setup-acme/dns01/google.rst +tasks/acme/configuring-dns01/rfc2136.rst tasks/issuers/setup-acme/dns01/rfc2136.rst +tasks/acme/configuring-dns01/route53.rst tasks/issuers/setup-acme/dns01/route53.rst +tasks/acme/configuring-http01.rst tasks/issuers/setup-acme/http01/index.rst +tasks/acme/debugging-failing-orders.rst reference/orders.rst diff --git a/docs/tasks/acme/debugging-failing-orders.rst b/docs/tasks/acme/debugging-failing-orders.rst deleted file mode 100644 index 14e4bb84d..000000000 --- a/docs/tasks/acme/debugging-failing-orders.rst +++ /dev/null @@ -1,14 +0,0 @@ -======================== -Debugging failing Orders -======================== - -This guide is still in the process of being written. - -Please check the :doc:`Order resource reference docs ` to -understand how to debug ACME Orders & Challenges when you are having issues. - -Common problems -=============== - -.. todo:: fill in this section with a new header for each issue that we see - commonly occurring. diff --git a/docs/tasks/acme/index.rst b/docs/tasks/acme/index.rst deleted file mode 100644 index 8d8e4ed6e..000000000 --- a/docs/tasks/acme/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -=================== -ACME specific tasks -=================== - -In order to use the ACME provider, there are a number of required fields. -For your ACME issuer to support the various ACME challenge mechanisms, you may -need to provide some additional configuration on your resource, such as -configuring credentials for a DNS provider or enabling HTTP01 validation. - -.. toctree:: - :maxdepth: 2 - - issuing-certificates - configuring-dns01/index - configuring-http01 - debugging-failing-orders diff --git a/docs/tasks/acme/issuing-certificates.rst b/docs/tasks/acme/issuing-certificates.rst deleted file mode 100644 index 5cc793a07..000000000 --- a/docs/tasks/acme/issuing-certificates.rst +++ /dev/null @@ -1,169 +0,0 @@ -=============================== -Issuing Certificates using ACME -=============================== - -ACME certificates currently require additional configuration on the Certificate -resource that you create in order to determine how to solve the -`ACME challenges`_ that the ACME protocol requires. - -In future releases of cert-manager, this configuration is likely to move off of -the Certificate resource and onto the Issuer resource in order to create a -better separation of concerns. More info can be found on issue `#1450`_. - -.. _`ACME challenges`: https://letsencrypt.org/how-it-works/ -.. _`#1450`: https://github.com/jetstack/cert-manager/pull/1450 - -Configuring Certificates for ACME issuance -========================================== - -In order to issue certificates using the ACME issuer type, you must configure -which ACME challenge provider is used for each domain name you are requesting -a Certificate for. - -This is done by configuring a mapping between domain names and the solver types -that have been configured on the corresponding Issuer resource. - -Using HTTP01 challenges ------------------------ - -In order to use the HTTP01 challenge provider, you must first configure your -Issuer with the appropriate settings described in the :doc:`configuring-http01` -documentation. - -Assuming you've created the same example ACME Issuer with http01 enabled as in -the :doc:`../issuers/setup-acme` guide: - -.. code-block:: yaml - :linenos: - :emphasize-lines: 7-10, 15-16 - - apiVersion: certmanager.k8s.io/v1alpha1 - kind: ClusterIssuer - metadata: - name: letsencrypt-staging - spec: - acme: - # You must replace this email address with your own. - # Let's Encrypt will use this to contact you about expiring - # certificates, and issues related to your account. - email: user@example.com - server: https://acme-staging-v02.api.letsencrypt.org/directory - privateKeySecretRef: - # Secret resource used to store the account's private key. - name: example-issuer-account-key - # Enable the HTTP01 challenge mechanism for this Issuer - http01: {} - -We must configure our Certificate resource with the 'ingress class' that will -be used to solve the ACME HTTP01 challenges: - -.. code-block:: yaml - :linenos: - :emphasize-lines: 14-20 - - apiVersion: certmanager.k8s.io/v1alpha1 - kind: Certificate - metadata: - name: example-com - namespace: default - spec: - secretName: example-com-tls - issuerRef: - name: letsencrypt-staging - commonName: example.com - dnsNames: - - example.com - - www.example.com - acme: - config: - - http01: - ingressClass: nginx - domains: - - example.com - - www.example.com - -.. note:: - If you use 'ingress-gce', aka the GCLB ingress controller, you will need to - modify your Certificate definition to specify the - ``certificate.spec.acme.config.http01.ingress`` field instead of - ``ingressClass``, like so:: - - ... - acme: - config: - - http01: - ingress: name-of-gce-ingress-resource - domains: - - example.com - - www.example.com - -Using DNS01 challenges ------------------------ - -In order to use DNS01 validation, you must first configure your Issuer resource -with credentials and connection information needed to access your DNS -provider's administrative console. - -You can find more information on the different supported DNS providers and how -to configure them in the :doc:`./configuring-dns01/index` documentation. - -The example Issuer on the :doc:`./configuring-dns01/index` page is configured -with credentials for a Google Cloud DNS account: - -.. code-block:: yaml - :linenos: - :emphasize-lines: 7, 13-18 - - apiVersion: certmanager.k8s.io/v1alpha1 - kind: ClusterIssuer - metadata: - name: letsencrypt-staging - spec: - acme: - email: user@example.com - server: https://acme-staging-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: example-issuer-account-key - dns01: - providers: - - name: prod-clouddns - clouddns: - project: my-project - serviceAccountSecretRef: - name: prod-clouddns-svc-acct-secret - key: service-account.json - -In the above example on line 13, you can see we have named this DNS provider -``prod-clouddns``. - -When creating Certificates that intend to utilise this DNS01 provider for -validations, we must remember to include this "provider name" in our -Certificate's spec: - -.. code-block:: yaml - :linenos: - :emphasize-lines: 17 - - apiVersion: certmanager.k8s.io/v1alpha1 - kind: Certificate - metadata: - name: example-com - namespace: default - spec: - secretName: example-com-tls - issuerRef: - name: letsencrypt-staging - commonName: example.com - dnsNames: - - example.com - - www.example.com - acme: - config: - - dns01: - provider: prod-clouddns - domains: - - example.com - - www.example.com - -If you do not specify a provider name, cert-manager will not know how to solve -challenges for your domains and the issuance process **will not succeed**. diff --git a/docs/tasks/index.rst b/docs/tasks/index.rst index 707dace8b..0b4270db2 100644 --- a/docs/tasks/index.rst +++ b/docs/tasks/index.rst @@ -11,6 +11,5 @@ want to configure. issuers/index issuing-certificates/index - acme/index backup-restore-crds upgrading/index diff --git a/docs/tasks/issuers/index.rst b/docs/tasks/issuers/index.rst index ca78bb82b..afc695f53 100644 --- a/docs/tasks/issuers/index.rst +++ b/docs/tasks/issuers/index.rst @@ -72,7 +72,7 @@ Certificate resources. :maxdepth: 2 :caption: Contents: - setup-acme + setup-acme/index setup-ca setup-selfsigned setup-vault diff --git a/docs/tasks/acme/configuring-dns01/acme-dns.rst b/docs/tasks/issuers/setup-acme/dns01/acme-dns.rst similarity index 100% rename from docs/tasks/acme/configuring-dns01/acme-dns.rst rename to docs/tasks/issuers/setup-acme/dns01/acme-dns.rst diff --git a/docs/tasks/acme/configuring-dns01/akamai.rst b/docs/tasks/issuers/setup-acme/dns01/akamai.rst similarity index 100% rename from docs/tasks/acme/configuring-dns01/akamai.rst rename to docs/tasks/issuers/setup-acme/dns01/akamai.rst diff --git a/docs/tasks/acme/configuring-dns01/azuredns.rst b/docs/tasks/issuers/setup-acme/dns01/azuredns.rst similarity index 100% rename from docs/tasks/acme/configuring-dns01/azuredns.rst rename to docs/tasks/issuers/setup-acme/dns01/azuredns.rst diff --git a/docs/tasks/acme/configuring-dns01/cloudflare.rst b/docs/tasks/issuers/setup-acme/dns01/cloudflare.rst similarity index 100% rename from docs/tasks/acme/configuring-dns01/cloudflare.rst rename to docs/tasks/issuers/setup-acme/dns01/cloudflare.rst diff --git a/docs/tasks/acme/configuring-dns01/digitalocean.rst b/docs/tasks/issuers/setup-acme/dns01/digitalocean.rst similarity index 100% rename from docs/tasks/acme/configuring-dns01/digitalocean.rst rename to docs/tasks/issuers/setup-acme/dns01/digitalocean.rst diff --git a/docs/tasks/acme/configuring-dns01/google.rst b/docs/tasks/issuers/setup-acme/dns01/google.rst similarity index 100% rename from docs/tasks/acme/configuring-dns01/google.rst rename to docs/tasks/issuers/setup-acme/dns01/google.rst diff --git a/docs/tasks/acme/configuring-dns01/index.rst b/docs/tasks/issuers/setup-acme/dns01/index.rst similarity index 100% rename from docs/tasks/acme/configuring-dns01/index.rst rename to docs/tasks/issuers/setup-acme/dns01/index.rst diff --git a/docs/tasks/acme/configuring-dns01/rfc2136.rst b/docs/tasks/issuers/setup-acme/dns01/rfc2136.rst similarity index 100% rename from docs/tasks/acme/configuring-dns01/rfc2136.rst rename to docs/tasks/issuers/setup-acme/dns01/rfc2136.rst diff --git a/docs/tasks/acme/configuring-dns01/route53.rst b/docs/tasks/issuers/setup-acme/dns01/route53.rst similarity index 100% rename from docs/tasks/acme/configuring-dns01/route53.rst rename to docs/tasks/issuers/setup-acme/dns01/route53.rst diff --git a/docs/tasks/acme/configuring-http01.rst b/docs/tasks/issuers/setup-acme/http01/index.rst similarity index 100% rename from docs/tasks/acme/configuring-http01.rst rename to docs/tasks/issuers/setup-acme/http01/index.rst diff --git a/docs/tasks/issuers/setup-acme.rst b/docs/tasks/issuers/setup-acme/index.rst similarity index 89% rename from docs/tasks/issuers/setup-acme.rst rename to docs/tasks/issuers/setup-acme/index.rst index 8c7a8f986..054f767b5 100644 --- a/docs/tasks/issuers/setup-acme.rst +++ b/docs/tasks/issuers/setup-acme/index.rst @@ -52,7 +52,7 @@ own email address. solvers: - http01: ingress: - ingressClass: nginx + class: nginx You can then create this resource using ``kubectl apply``: @@ -115,7 +115,7 @@ along with a DNS01 solver that can be used for wildcard certificates: solvers: - http01: ingress: - ingressClass: nginx + class: nginx - dns01: selector: matchLabels: @@ -154,7 +154,7 @@ For example: solvers: - http01: ingress: - ingressClass: nginx + class: nginx - dns01: selector: dnsNames: @@ -172,20 +172,4 @@ the DNS01 challenge solver for ``*.example.com``. It is possible to specify both ``matchLabels`` AND ``dnsNames`` on an ACME solver selector. -HTTP01 configuration -==================== - -For more details on the available options for the ACME HTTP01 solver type, and -for details on compatibility with your own ingress controller, read the -:doc:`Configuring HTTP01 Ingress Provider ` -documentation. - -DNS01 configuration -=================== - -For more details on the available options for the ACME DNS01 solver type, -including a list of supported DNS providers, read the -:doc:`Configuring DNS01 Providers ` -documentation. - .. _`Let's Encrypt staging endpoint`: https://letsencrypt.org/docs/staging-environment/