weiguoqiang/cert-manager
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

1:1 copy the dns & http validation docs

Browse Source
This commit is contained in:
James Munnelly 2018-04-11 16:43:26 +01:00
parent 14dc0a2e0c
commit eb45d46c7e
5 changed files with 361 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/issuers/acme/dns01.rst
View File

@ -33,6 +33,8 @@ it is also possible to have multiple instances of the same DNS provider on a
single Issuer (e.g. two clouddns accounts could be set, each with their own
name).
.. _supported-dns01-providers:
*************************
Supported DNS01 providers
*************************

6
docs/reference/issuers/ca/index.rst
View File

@ -7,3 +7,9 @@ CA Configuration
CA Issuers issue certificates signed from a X509 signing keypair, stored in a
secret in the Kubernetes API server.
You can find user guides on using the CA Issuer in the :doc:`CA Issuer tutorials
section </tutorials/ca/index>`.
.. todo::
Expand out CA Issuer reference documentation

176
docs/tutorials/acme/dns-validation.rst Normal file
View File

@ -0,0 +1,176 @@
================================================
Issuing an ACME certificate using DNS validation
================================================
.. todo::
This guide needs rewriting to be clearer, splitting into sections and
potentially rewriting altogether.
cert-manager can be used to obtain certificates from a CA using the ACME_ protocol.
The ACME protocol supports various challenge mechanisms which are used to prove
ownership of a domain so that a valid certificate can be issued for that domain.
One such challenge mechanism is DNS-01. With a DNS-01 challenge, you prove
ownership of a domain by proving you control its DNS records.
This is done by creating a TXT record with specific content that proves you
have control of the domains DNS records.
The following Issuer defines the necessary information to enable DNS validation.
You can read more about the Issuer resource in the :doc:`Issuer reference docs </reference/issuers/index>`.
.. code-block:: yaml
:linenos:
apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
name: letsencrypt-staging
namespace: default
spec:
acme:
server: https://acme-staging.api.letsencrypt.org/directory
email: user@example.com
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsencrypt-staging
# ACME DNS-01 provider configurations
dns01:
# Here we define a list of DNS-01 providers that can solve DNS challenges
providers:
- name: prod-dns
clouddns:
# A secretKeyRef to a google cloud json service account
serviceAccountSecretRef:
name: clouddns-service-account
key: service-account.json
# The project in which to update the DNS zone
project: gcloud-prod-project
- name: cf-dns
cloudflare:
email: user@example.com
# A secretKeyRef to a cloudflare api key
apiKeySecretRef:
name: cloudflare-api-key
key: api-key.txt
We have specified the ACME server URL for Let's Encrypt's `staging environment`_.
The staging environment will not issue trusted certificates but is used to
ensure that the verification process is working properly before moving to
production. Let's Encrypt's production environment imposes much stricter
`rate limits`_, so to reduce the chance of you hitting those limits it is
highly recommended to start by using the staging environment. To move to
production, simply create a new Issuer with the URL set to
``https://acme-v01.api.letsencrypt.org/directory``.
The first stage of the ACME protocol is for the client to register with the
ACME server. This phase includes generating an asymmetric key pair which is
then associated with the email address specified in the Issuer. Make sure to
change this email address to a valid one that you own. It is commonly used to
send expiry notices when your certificates are coming up for renewal. The
generated private key is stored in a Secret named ``letsencrypt-staging``.
The ``dns01`` stanza contains a list of DNS-01 providers that can be used to
solve DNS challenges. Our Issuer defines two providers. This gives us a choice
of which one to use when obtaining certificates.
More information about the DNS provider configuration, including a list of
supported providers, can be found :ref:`in the dns01 reference docs <supported-dns01-providers>`.
Once we have created the above Issuer we can use it to obtain a certificate.
.. code-block:: yaml
:linenos:
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:
- www.example.com
acme:
config:
- dns01:
provider: prod-dns
domains:
- example.com
- dns01:
provider: cf-dns
domains:
- www.example.com
The Certificate resource describes our desired certificate and the possible
methods that can be used to obtain it. You can learn more about the Certificate
resource in the :doc:`reference docs </reference/certificates>`.
If the certificate is obtained successfully, the resulting key pair will be
stored in a secret called ``example-com-tls`` in the same namespace as the Certificate.
The certificate will have a common name of ``example.com`` and the
`Subject Alternative Names `_ (SANs) will be ``example.com`` and ``www.example.com``.
In our Certificate we have referenced the ``letsencrypt-staging`` Issuer above.
The Issuer must be in the same namespace as the Certificate.
If you want to reference a ClusterIssuer, which is a cluster-scoped version of
an Issuer, you must add ``kind: ClusterIssuer`` to the ``issuerRef`` stanza.
For more information on ClusterIssuers, read the
:doc:`ClusterIssuer reference docs </reference/clusterissuers>`.
The ``acme`` stanza defines the configuration for our ACME challenges.
Here we have defined the configuration for our DNS challenges which will be used
to verify domain ownership.
For each domain mentioned in a ``dns01`` stanza, cert-manager will use the
provider's credentials from the referenced Issuer to create a TXT record called
``_acme-challenge``.
This record will then be verified by the ACME server in order to issue the
certificate.
Once domain ownership has been verified, any cert-manager affected records will
be cleaned up.
.. note::
It is your responsibility to ensure the selected provider is authoritative for
your domain.
After creating the above Certificate, we can check whether it has been obtained
successfully using ``kubectl describe``:
.. code-block:: shell
$ kubectl describe certificate example-com
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning ErrorCheckCertificate 33s cert-manager-controller Error checking existing TLS certificate: secret "example-com-tls" not found
Normal PrepareCertificate 33s cert-manager-controller Preparing certificate with issuer
Normal PresentChallenge 33s cert-manager-controller Presenting dns-01 challenge for domain example.com
Normal PresentChallenge 33s cert-manager-controller Presenting dns-01 challenge for domain www.example.com
Normal SelfCheck 32s cert-manager-controller Performing self-check for domain example.com
Normal SelfCheck 32s cert-manager-controller Performing self-check for domain www.example.com
Normal ObtainAuthorization 6s cert-manager-controller Obtained authorization for domain example.com
Normal ObtainAuthorization 6s cert-manager-controller Obtained authorization for domain www.example.com
Normal IssueCertificate 6s cert-manager-controller Issuing certificate...
Normal CertificateIssued 5s cert-manager-controller Certificate issued successfully
You can also check whether issuance was successful with
``kubectl get secret example-com-tls -o yaml``.
You should see a base64 encoded signed TLS key pair.
Once our certificate has been obtained, cert-manager will periodically check its
validity and attempt to renew it if it gets close to expiry.
cert-manager considers certificates to be close to expiry when the 'Not After'
field on the certificate is less than the current time plus 30 days.
.. _ACME: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment
.. _`staging environment`: https://letsencrypt.org/docs/staging-environment/
.. _`rate limits`: https://letsencrypt.org/docs/rate-limits/
.. _`Subject Alternative Names`: https://en.wikipedia.org/wiki/Subject_Alternative_Name

175
docs/tutorials/acme/http-validation.rst Normal file
View File

@ -0,0 +1,175 @@
=================================================
Issuing an ACME certificate using HTTP validation
=================================================
.. todo::
This guide needs rewriting to be clearer, splitting into sections and
potentially rewriting altogether.
cert-manager can be used to obtain certificates from a CA using the ACME_ protocol.
The ACME protocol supports various challenge mechanisms which are used to prove
ownership of a domain so that a valid certificate can be issued for that domain.
One such challenge mechanism is the HTTP-01 challenge. With a HTTP-01 challenge,
you prove ownership of a domain by ensuring that a particular file is present at
the domain.
It is assumed that you control the domain if you are able to publish the given
file under a given path.
The following Issuer defines the necessary information to enable HTTP validation.
You can read more about the Issuer resource in the :doc:`Issuer reference docs </reference/issuers/index>`.
.. code-block:: yaml
:linenos:
apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
name: letsencrypt-staging
namespace: default
spec:
acme:
# The ACME server URL
server: https://acme-staging.api.letsencrypt.org/directory
# Email address used for ACME registration
email: user@example.com
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsencrypt-staging
# Enable the HTTP-01 challenge provider
http01: {}
We have specified the ACME server URL for Let's Encrypt's `staging environment`_.
The staging environment will not issue trusted certificates but is used to
ensure that the verification process is working properly before moving to
production. Let's Encrypt's production environment imposes much stricter
`rate limits`_, so to reduce the chance of you hitting those limits it is
highly recommended to start by using the staging environment. To move to
production, simply create a new Issuer with the URL set to
``https://acme-v01.api.letsencrypt.org/directory``.
The first stage of the ACME protocol is for the client to register with the
ACME server. This phase includes generating an asymmetric key pair which is
then associated with the email address specified in the Issuer. Make sure to
change this email address to a valid one that you own. It is commonly used to
send expiry notices when your certificates are coming up for renewal. The
generated private key is stored in a Secret named ``letsencrypt-staging``.
The presence of the ``http01`` field simply enables the HTTP-01 challenge for this
Issuer.
No further configuration is necessary or currently possible.
Once we have created the above Issuer we can use it to obtain a certificate.
.. code-block:: yaml
:linenos:
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:
- www.example.com
acme:
config:
- http01:
ingressClass: nginx
domains:
- example.com
- http01:
ingress: my-ingress
domains:
- www.example.com
The Certificate resource describes our desired certificate and the possible
methods that can be used to obtain it. You can learn more about the Certificate
resource in the :doc:`reference docs </reference/certificates>`.
If the certificate is obtained successfully, the resulting key pair will be
stored in a secret called ``example-com-tls`` in the same namespace as the Certificate.
The certificate will have a common name of ``example.com`` and the
`Subject Alternative Names`_ (SANs) will be ``example.com`` and ``www.example.com``.
In our Certificate we have referenced the ``letsencrypt-staging`` Issuer above.
The Issuer must be in the same namespace as the Certificate.
If you want to reference a ClusterIssuer, which is a cluster-scoped version of
an Issuer, you must add ``kind: ClusterIssuer`` to the ``issuerRef`` stanza.
For more information on ClusterIssuers, read the
:doc:`ClusterIssuer reference docs </reference/clusterissuers>`.
The ``acme`` stanza defines the configuration for our ACME challenges.
Here we have defined the configuration for our HTTP-01 challenges which will be
used to verify domain ownership.
To verify ownership of each domain mentioned in an ``http01`` stanza, cert-manager
will create a Pod, Service and Ingress that exposes an HTTP endpoint that satisfies
the HTTP-01 challenge.
The fields ``ingress`` and ``ingressClass`` in the ``http01`` stanza can be used
to control how cert-manager interacts with Ingress resources:
* If the ``ingress`` field is specified, then an Ingress resource with the same
name in the same namespace as the Certificate must already exist and it will
be modified only to add the appropriate rules to solve the challenge.
This field is useful for the GCLB ingress controller, as well as a number of
others, that assign a single public IP address for each ingress resource.
Without manual intervention, creating a new ingress resource would cause any
challenges to fail.
* If the ``ingressClass`` field is specified, a new ingress resource with a
randomly generated name will be created in order to solve the challenge.
This new resource will have an annotation with key ``kubernetes.io/ingress.class``
and value set to the value of the ``ingressClass`` field.
This works for the likes of the NGINX ingress controller.
* If neither are specified, new ingress resources will be created with a randomly
generated name, but they will not have the ingress class annotation set.
* If both are specified, then the ``ingress`` field will take precedence.
Once domain ownership has been verified, any cert-manager affected resources will
be cleaned up or deleted.
.. note::
It is your responsibilty to point each domain name at the correct IP address
for your ingress controller.
After creating the above Certificate, we can check whether it has been obtained
successfully using ``kubectl describe``:
.. code-block:: shell
$ kubectl describe certificate example-com
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning ErrorCheckCertificate 33s cert-manager-controller Error checking existing TLS certificate: secret "example-com-tls" not found
Normal PrepareCertificate 33s cert-manager-controller Preparing certificate with issuer
Normal PresentChallenge 33s cert-manager-controller Presenting http-01 challenge for domain example.com
Normal PresentChallenge 33s cert-manager-controller Presenting http-01 challenge for domain www.example.com
Normal SelfCheck 32s cert-manager-controller Performing self-check for domain example.com
Normal SelfCheck 32s cert-manager-controller Performing self-check for domain www.example.com
Normal ObtainAuthorization 6s cert-manager-controller Obtained authorization for domain example.com
Normal ObtainAuthorization 6s cert-manager-controller Obtained authorization for domain www.example.com
Normal IssueCertificate 6s cert-manager-controller Issuing certificate...
Normal CertificateIssued 5s cert-manager-controller Certificate issued successfully
You can also check whether issuance was successful with
``kubectl get secret example-com-tls -o yaml``.
You should see a base64 encoded signed TLS key pair.
Once our certificate has been obtained, cert-manager will periodically check its
validity and attempt to renew it if it gets close to expiry.
cert-manager considers certificates to be close to expiry when the 'Not After'
field on the certificate is less than the current time plus 30 days.
.. _ACME: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment
.. _`staging environment`: https://letsencrypt.org/docs/staging-environment/
.. _`rate limits`: https://letsencrypt.org/docs/rate-limits/
.. _`Subject Alternative Names`: https://en.wikipedia.org/wiki/Subject_Alternative_Name

2
docs/tutorials/acme/index.rst
View File

@ -11,3 +11,5 @@ helping 'quickstart' common use-cases for the project.
migrating-from-kube-lego
securing-nginx-ingress-with-letsencrypt
dns-validation
http-validation