Rearrange docs and remove duplicate content
Signed-off-by: James Munnelly <james@munnelly.eu>
This commit is contained in:
James Munnelly
parent
b17f3a6b41
commit
05c9e83af7
@ -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
|
||||
|
||||
@ -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 </reference/orders>` 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.
|
||||
@ -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
|
||||
@ -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**.
|
||||
@ -11,6 +11,5 @@ want to configure.
|
||||
|
||||
issuers/index
|
||||
issuing-certificates/index
|
||||
acme/index
|
||||
backup-restore-crds
|
||||
upgrading/index
|
||||
|
||||
@ -72,7 +72,7 @@ Certificate resources.
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
setup-acme
|
||||
setup-acme/index
|
||||
setup-ca
|
||||
setup-selfsigned
|
||||
setup-vault
|
||||
|
||||
@ -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 </tasks/acme/configuring-http01>`
|
||||
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 </tasks/acme/configuring-dns01/index>`
|
||||
documentation.
|
||||
|
||||
.. _`Let's Encrypt staging endpoint`: https://letsencrypt.org/docs/staging-environment/
|
||||
Loading…
Reference in New Issue
Block a user