From a2463e7fb4aeab5f90fbeae48fa0f4c866e69a4c Mon Sep 17 00:00:00 2001 From: JoshVanL Date: Tue, 9 Jul 2019 16:05:36 +0100 Subject: [PATCH 1/2] Adds CertificateRequest reference docs Signed-off-by: JoshVanL --- docs/reference/certificaterequests.rst | 53 ++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 2 files changed, 54 insertions(+) create mode 100644 docs/reference/certificaterequests.rst diff --git a/docs/reference/certificaterequests.rst b/docs/reference/certificaterequests.rst new file mode 100644 index 000000000..aede9ba79 --- /dev/null +++ b/docs/reference/certificaterequests.rst @@ -0,0 +1,53 @@ +=================== +CertificateRequests +=================== + +A 'CertificateRequest' is a resource in cert-manager that is used to request +x509 certificates from an issuer. The resource contains a base64 encoded string +of a DER encoded certificate request which is sent to the referenced issuer. A +successful issuance will return a signed certificate, based on the certificate +signing request. 'CertificateRequets' are typically consumed and managed by +controllers or other systems and should not be used by humans - unless +specifically needed. + +.. note:: + To enable cert-manager's internal CertificateRequest controllers, supply the + following feature gate: + `--feature-gates=CertificateRequestControllers=true` + +A simple CertificateRequest looks like the following: + +.. code-block:: yaml + :linenos: + + apiVersion: certmanager.k8s.io/v1alpha1 + kind: CertificateRequest + metadata: + name: acme-cr + spec: + csr: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQzNqQ0NBY1lDQVFBd2daZ3hDekFKQmdOVkJBWVRBbHBhTVE4d0RRWURWUVFJREFaQmNHOXNiRzh4RFRBTApCZ05WQkFjTUJFMXZiMjR4RVRBUEJnTlZCQW9NQ0VwbGRITjBZV05yTVJVd0V3WURWUVFMREF4alpYSjBMVzFoCmJtRm5aWEl4RVRBUEJnTlZCQU1NQ0dwdmMyaDJZVzVzTVN3d0tnWUpLb1pJaHZjTkFRa0JGaDFxYjNOb2RXRXUKZG1GdWJHVmxkWGRsYmtCcVpYUnpkR0ZqYXk1cGJ6Q0NBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQQURDQwpBUW9DZ2dFQkFLd01tTFhuQkNiRStZdTIvMlFtRGsxalRWQ3BvbHU3TlZmQlVFUWl1bDhFMHI2NFBLcDRZQ0c5Cmx2N2kwOHdFMEdJQUgydnJRQmxVd3p6ZW1SUWZ4YmQvYVNybzRHNUFBYTJsY2NMaFpqUlh2NEVMaER0aVg4N3IKaTQ0MWJ2Y01OM0ZPTlRuczJhRkJYcllLWGxpNG4rc0RzTEVuZmpWdXRiV01Zeis3M3ptaGZzclRJUjRzTXo3cQpmSzM2WFM4UkRjNW5oVVcyYU9BZ3lnbFZSOVVXRkxXNjNXYXVhcHg2QUpBR1RoZnJYdVVHZXlZUUVBSENxZmZmCjhyOEt3YTFYK1NwYm9YK1ppSVE0Nk5jQ043OFZnL2dQVHNLZmphZURoNWcyNlk1dEVidHd3MWdRbWlhK0MyRHIKWHpYNU13RzJGNHN0cG5kUnRQckZrU1VnMW1zd0xuc0NBd0VBQWFBQU1BMEdDU3FHU0liM0RRRUJDd1VBQTRJQgpBUUFXR0JuRnhaZ0gzd0N3TG5IQ0xjb0l5RHJrMUVvYkRjN3BJK1VVWEJIS2JBWk9IWEFhaGJ5RFFLL2RuTHN3CjJkZ0J3bmlJR3kxNElwQlNxaDBJUE03eHk5WjI4VW9oR3piN0FVakRJWHlNdmkvYTJyTVhjWjI1d1NVQmxGc28Kd005dE1QU2JwcEVvRERsa3NsOUIwT1BPdkFyQ0NKNnZGaU1UbS9wMUJIUWJSOExNQW53U0lUYVVNSFByRzJVMgpjTjEvRGNMWjZ2enEyeENjYVoxemh2bzBpY1VIUm9UWmV1ZEp6MkxmR0VHM1VOb2ppbXpBNUZHd0RhS3BySWp3ClVkd1JmZWZ1T29MT1dNVnFNbGRBcTlyT24wNHJaT3Jnak1HSE9tTWxleVdPS1AySllhaDNrVDdKU01zTHhYcFYKV0ExQjRsLzFFQkhWeGlKQi9Zby9JQWVsCi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo= + isCA: false + duraton: 90d + issuerRef: + name: letsencrypt-prod + # We can reference ClusterIssuers by changing the kind here. + # The default value is Issuer (i.e. a locally namespaced Issuer) + kind: Issuer + group: certmanager.k8s.io + +This CertificateRequest will make cert-manager attempt to make the Issuer +``letsencrypt-prod`` in the default issuer pool ``certmanager.k8s.io``, return a +certificate based upon the certificate signing request. Other groups can be +specified inside the ``issuerRef`` which will change the targeted issuers to other +external, third party issuers you may have installed. + +The resource also exposes the option for stating the certificate as CA and +requested validity duration. + +A successful issuance of the certificate signing request will cause an update to +the resource, setting the status with the signed certificate, the CA of the +certificate, and setting the condition to ready. + +Whether issuance of the controller was successful or not, a retry of the +issuance will _not_ happen. It is the responsibility of some other controller to +manage the logic and life cycle of CertificateRequets. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index a11849155..d6b6d1a78 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -13,6 +13,7 @@ Step by step user guides and tutorials can be found in the :caption: Contents: certificates + certificaterequests orders challenges issuers From fb0195aa122b7b744a4ef8ab3385a60edac2ce9e Mon Sep 17 00:00:00 2001 From: JoshVanL Date: Tue, 16 Jul 2019 09:53:33 +0100 Subject: [PATCH 2/2] Adds review comments Signed-off-by: JoshVanL --- docs/reference/certificaterequests.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/certificaterequests.rst b/docs/reference/certificaterequests.rst index aede9ba79..c632ed2bb 100644 --- a/docs/reference/certificaterequests.rst +++ b/docs/reference/certificaterequests.rst @@ -4,7 +4,7 @@ CertificateRequests A 'CertificateRequest' is a resource in cert-manager that is used to request x509 certificates from an issuer. The resource contains a base64 encoded string -of a DER encoded certificate request which is sent to the referenced issuer. A +of a PEM encoded certificate request which is sent to the referenced issuer. A successful issuance will return a signed certificate, based on the certificate signing request. 'CertificateRequets' are typically consumed and managed by controllers or other systems and should not be used by humans - unless @@ -23,13 +23,13 @@ A simple CertificateRequest looks like the following: apiVersion: certmanager.k8s.io/v1alpha1 kind: CertificateRequest metadata: - name: acme-cr + name: my-ca-cr spec: csr: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQzNqQ0NBY1lDQVFBd2daZ3hDekFKQmdOVkJBWVRBbHBhTVE4d0RRWURWUVFJREFaQmNHOXNiRzh4RFRBTApCZ05WQkFjTUJFMXZiMjR4RVRBUEJnTlZCQW9NQ0VwbGRITjBZV05yTVJVd0V3WURWUVFMREF4alpYSjBMVzFoCmJtRm5aWEl4RVRBUEJnTlZCQU1NQ0dwdmMyaDJZVzVzTVN3d0tnWUpLb1pJaHZjTkFRa0JGaDFxYjNOb2RXRXUKZG1GdWJHVmxkWGRsYmtCcVpYUnpkR0ZqYXk1cGJ6Q0NBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQQURDQwpBUW9DZ2dFQkFLd01tTFhuQkNiRStZdTIvMlFtRGsxalRWQ3BvbHU3TlZmQlVFUWl1bDhFMHI2NFBLcDRZQ0c5Cmx2N2kwOHdFMEdJQUgydnJRQmxVd3p6ZW1SUWZ4YmQvYVNybzRHNUFBYTJsY2NMaFpqUlh2NEVMaER0aVg4N3IKaTQ0MWJ2Y01OM0ZPTlRuczJhRkJYcllLWGxpNG4rc0RzTEVuZmpWdXRiV01Zeis3M3ptaGZzclRJUjRzTXo3cQpmSzM2WFM4UkRjNW5oVVcyYU9BZ3lnbFZSOVVXRkxXNjNXYXVhcHg2QUpBR1RoZnJYdVVHZXlZUUVBSENxZmZmCjhyOEt3YTFYK1NwYm9YK1ppSVE0Nk5jQ043OFZnL2dQVHNLZmphZURoNWcyNlk1dEVidHd3MWdRbWlhK0MyRHIKWHpYNU13RzJGNHN0cG5kUnRQckZrU1VnMW1zd0xuc0NBd0VBQWFBQU1BMEdDU3FHU0liM0RRRUJDd1VBQTRJQgpBUUFXR0JuRnhaZ0gzd0N3TG5IQ0xjb0l5RHJrMUVvYkRjN3BJK1VVWEJIS2JBWk9IWEFhaGJ5RFFLL2RuTHN3CjJkZ0J3bmlJR3kxNElwQlNxaDBJUE03eHk5WjI4VW9oR3piN0FVakRJWHlNdmkvYTJyTVhjWjI1d1NVQmxGc28Kd005dE1QU2JwcEVvRERsa3NsOUIwT1BPdkFyQ0NKNnZGaU1UbS9wMUJIUWJSOExNQW53U0lUYVVNSFByRzJVMgpjTjEvRGNMWjZ2enEyeENjYVoxemh2bzBpY1VIUm9UWmV1ZEp6MkxmR0VHM1VOb2ppbXpBNUZHd0RhS3BySWp3ClVkd1JmZWZ1T29MT1dNVnFNbGRBcTlyT24wNHJaT3Jnak1HSE9tTWxleVdPS1AySllhaDNrVDdKU01zTHhYcFYKV0ExQjRsLzFFQkhWeGlKQi9Zby9JQWVsCi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo= isCA: false duraton: 90d issuerRef: - name: letsencrypt-prod + name: ca-issuer # We can reference ClusterIssuers by changing the kind here. # The default value is Issuer (i.e. a locally namespaced Issuer) kind: Issuer @@ -46,7 +46,7 @@ requested validity duration. A successful issuance of the certificate signing request will cause an update to the resource, setting the status with the signed certificate, the CA of the -certificate, and setting the condition to ready. +certificate (if available), and setting the `Ready` condition to `True`. Whether issuance of the controller was successful or not, a retry of the issuance will _not_ happen. It is the responsibility of some other controller to