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

Merge pull request #1218 from munnerz/orders-challenges-ref-docs

Browse Source 
Add reference docs for Order and Challenge resources
This commit is contained in:
jetstack-bot 2019-01-16 15:52:37 +00:00 committed by GitHub
commit d5b833070d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 203 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
docs/reference/challenges.rst Normal file
View File

@ -0,0 +1,119 @@
==========
Challenges
==========
Challenge resources are used by the ACME issuer to manage the lifecycle of an
ACME 'challenge' that must be completed in order to complete an 'authorization'
for a single DNS name/identifier.
When an **Order** resource is created, the order controller will create
Challenge resources for each DNS name that is being authorized with the ACME
server.
As an end-user, you will never need to manually create a Challenge resource.
Once created, a Challenge cannot be changed. Instead, a new Challenge resource
must be created.
Challenge lifecycle
===================
After a Challenge resource has been created, it will be initially queued for
processing.
Processing will not begin until the challenge has been 'scheduled' to start.
This scheduling process prevents too many challenges being attempted at once,
or multiple challenges for the same DNS name being attempted at once.
For more information on how challenges are scheduled, read the
`challenge scheduling`_ section.
Once a challenge has been scheduled, it will first be 'synced' with the ACME
server in order to determine its current state. If the challenge is already
valid, its 'state' will be updated to 'valid', and also set
``status.processing = false`` to 'unschedule' itself.
If the challenge is still 'pending', the challenge controller will 'present'
the challenge using the configured solver, one of HTTP01 or DNS01.
Once the challenge has been 'presented', it will set ``status.presented=true``.
Once 'presented', the challenge controller will perform a 'self check' to
ensure that the challenge has 'propagated' (i.e. the authoritve DNS servers
have been updated to respond correctly, or the changes to the ingress resources
have been observed and in-use by the ingress controller).
If the self check fails, cert-manager will retry the self check with a fixed
10 second retry interval. Challenges that do not ever complete the self check
will continue retrying until the user intervenes.
Once the self check is passing, the ACME 'authorization' associated with this
challenge will be 'accepted' (TODO: add link to accepting challenges section of
ACME spec).
The final state of the authorization after accepting it will be copied across
to the Challenge's ``status.state`` field, as well as the 'error reason' if
an error occurred whilst the ACME server attempted to validate the challenge.
Once a Challenge has entered the ``valid``, ``invalid``, ``expired`` or
``revoked`` state, it will set ``status.processing=false`` to prevent any
further processing of the ACME challenge, and to allow another challenge to be
scheduled if there is a backlog of challenges to complete.
Challenge scheduling
====================
Instead of attempting to process all challenges at once, challenges are
'scheduled' by cert-manager.
This scheduler applies a cap on the maximum number of simultaneous challenges
as well as disallows two challenges for the same DNS name and solver type
(http-01 or dns-01) to be completed at once.
The maximum number of challenges that can be processed at a time is 60 as of
ddff78_.
Debugging Challenge resources
=============================
In order to determine why an ACME Certificate is not being issued, we can debug
using the 'Challenge' resources that cert-manager has created.
In order to determine which Challenge is failing, you can run
``kubectl get challenges``:
.. code-block:: shell
$ kubectl get challenges
NAME STATE DOMAIN REASON AGE
example-com-1217431265-0 pending example.com Waiting for dns-01 challenge propagation 22s
This shows that the challenge has been presented using the DNS01 solver
successfully and now cert-manager is waiting for the 'self check' to pass.
You can get more information about the challenge by using ``kubectl describe``:
.. code-block:: shell
$ kubectl describe challenge example-com-1217431265-0
...
Status:
Presented: true
Processing: true
Reason: Waiting for dns-01 challenge propagation
State: pending
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Started 19s cert-manager Challenge scheduled for processing
Normal Presented 16s cert-manager Presented challenge using dns-01 challenge mechanism
Progress about the state of each challenge will be recorded either as Events
or on the Challenge's ``status`` block (as shown above).
Troubleshooting failing challenges
==================================
.. todo::
add section describing common issues and resolutions when challenges are
failing
.. _ddff78: https://github.com/jetstack/cert-manager/blob/ddff78f011558e64186d61f7c693edced1496afa/pkg/controller/acmechallenges/scheduler/scheduler.go#L31-L33

2
docs/reference/index.rst
View File

@ -13,6 +13,8 @@ Step by step user guides and tutorials can be found in the
:caption: Contents:
certificates
orders
challenges
issuers
clusterissuers
ingress-shim

82
docs/reference/orders.rst Normal file
View File

@ -0,0 +1,82 @@
======
Orders
======
Order resources are used by the ACME issuer to manage the lifecycle of an ACME
'order' for a signed TLS certificate.
When a Certificate resource is created that references an ACME issuer,
cert-manager will create an Order resource in order to obtain a signed
certificate.
As an end-user, you will never need to manually create an Order resource.
Once created, an Order cannot be changed. Instead, a new Order resource must be
created.
Debugging Order resources
=========================
In order to debug why a Certificate isn't being issued, we can first run
``kubectl describe`` on the Certificate resource we're having issues with:
.. code-block:: shell
$ kubectl describe certificate example-com
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Generated 1m cert-manager Generated new private key
Normal OrderCreated 1m cert-manager Created Order resource "example-com-1217431265"
We can see here that Certificate controller has created an Order resource to
request a new certificate from the ACME server.
Orders are a useful source of information when debugging failures issuing ACME
certificates. By running ``kubectl describe order`` on a particular order,
information can be gleaned about failures in the process:
.. code-block:: shell
$ kubectl describe order example-com-1248919344
...
Reason:
State: pending
URL: https://acme-v02.api.letsencrypt.org/acme/order/41123272/265506123
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Created 1m cert-manager Created Challenge resource "example-com-1217431265-0" for domain "test1.example.com"
Normal Created 1m cert-manager Created Challenge resource "example-com-1217431265-1" for domain "test2.example.com"
Here we can see that cert-manager has created two Challenge resources in order
to fulfil the requirements of the ACME order to obtain a signed certificate.
You can then go on to run
``kubectl describe challenge example-com-1217431265-0`` to further debug the
progress of the Order.
Once an Order is successful, you should see an event like the following:
.. code-block:: shell
$ kubectl describe order example-com-1248919344
...
Reason:
State: valid
URL: https://acme-v02.api.letsencrypt.org/acme/order/41123272/265506123
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Created 72s cert-manager Created Challenge resource "example-com-1217431265-0" for domain "test1.example.com"
Normal Created 72s cert-manager Created Challenge resource "example-com-1217431265-1" for domain "test2.example.com"
Normal OrderValid 4s cert-manager Order completed successfully
If the Order is not completing successfully, you can debug the challenges
for the Order by running ``kubectl describe`` on the Challenge resource.
For more information on debugging Challenge resources, read the
:doc:`challenge reference docs </reference/challenges>`.