diff --git a/.go-version b/.go-version index ace44233b4a..de646d2fc11 100644 --- a/.go-version +++ b/.go-version @@ -1 +1 @@ -1.15.1 +1.16.6 diff --git a/content/en/docs/usage/kube-csr.md b/content/en/docs/usage/kube-csr.md index de90d7746a8..0f4f75f6eb0 100644 --- a/content/en/docs/usage/kube-csr.md +++ b/content/en/docs/usage/kube-csr.md @@ -13,8 +13,12 @@ request an X.509 signed certificate from a referenced Certificate Authority (CA). Using this resource may be useful for users who are using an application that -supports this resource, and not the cert-manager CertificateRequest resource, -but they still wish for certificates to be signed through cert-manager. +supports this resource, but not the cert-manager CertificateRequest resource, +and they still wish for certificates to be signed through cert-manager. + +CertificateSigningRequests reference a `SignerName` or signer as the entity it +wishes to sign its request from. For cert-manager, a signer can be mapped to +either an [Issuer or ClusterIssuer](../../configuration/). #### Feature State @@ -41,8 +45,8 @@ $ helm install \ # --set installCRDs=true ``` -> Note: cert-manager currently only supports signing CertificateSigningRequests -> using the [CA issuer](../../configuration/ca/). +> Note: cert-manager supports signing CertificateSigningRequests +> using all [internal Issuers](../../configuration/). > Note: cert-manager _does not_ automatically approve CertificateSigningRequests > that reference a cert-manager [Issuer](../../configuration/). Please refer to @@ -113,13 +117,52 @@ values that do not exist as `spec` or `status` fields on the CertificateSigningRequest resource. These fields are either set by the _requester_ or by the _signer_ as labelled below. +Requester annotations: + - `experimental.cert-manager.io/request-duration`: **Set by the requester**. Accepts a [Go time duration](https://golang.org/pkg/time/#ParseDuration) string - specifying the requested certificate duration. Defaults to 90 days. + specifying the requested certificate duration. Defaults to 90 days. Some + signers such as Venafi or ACME typically _do not_ allow requesting a + duration. - `experimental.cert-manager.io/request-is-ca`: **Set by the requester**. If set to `"true"`, will request for a CA certificate. -- `experimental.cert-manager.io/ca`: **Set by the signer**. Once signed, the - signer will populate this annotation with the base 64 encode CA certificate - of the signing chain. +- `experimental.cert-manager.io/private-key-secret-name`: **Set by the + requester**. Required only for the SelfSigned signer. Used to reference a + Secret which contains the PEM encoded private key of the requester's X.509 + certificate signing request at key `tls.key`. Used to sign the requester's + request. + +- `venafi.experimental.cert-manager.io/custom-fields`: **Set by the + requester**. Optional for only the Venafi signer. Used for adding custom + fields to the Venafi request. This will only work with Venafi TPP `v19.3` + and higher. The value is a JSON array with objects containing the name and + value keys, for example: + ``` + venafi.experimental.cert-manager.io/custom-fields: |- + [ + {"name": "field-name", "value": "field value"}, + {"name": "field-name-2", "value": "field value 2"} + ] + ``` + +Signer annotations: + +- `venafi.experimental.cert-manager.io/pickup-id`: **Set by the signer**. Only + used for the Venafi signer. Used to record the Venafi Pickup ID of a + certificate signing request that has been submitted to the Venafi API for + collection during issuance. + +## Usage + +CertificateSigningRequests can be manually created using the +[kubectl cert-manager plugin](../kubectl-plugin/#experimental). +This command takes a manifest file containing a +[Certificate](../../usage/certificate/) resource as input. This generates a +private key and creates a CertificateSigningRequest. CertificateSigningRequests +are not approved by default, so you will likely need to approve it manually: + +```bash +$ kubectl certificate approve +``` diff --git a/content/en/docs/usage/kubectl-plugin.md b/content/en/docs/usage/kubectl-plugin.md index 42df913be18..df7c64900f6 100644 --- a/content/en/docs/usage/kubectl-plugin.md +++ b/content/en/docs/usage/kubectl-plugin.md @@ -27,12 +27,16 @@ Usage: kubectl cert-manager [command] Available Commands: - convert Convert cert-manager config files between different API versions - create Create cert-manager resources - help Help about any command - renew Mark a Certificate for manual renewal - status Get details on current status of cert-manager resources - version Print the kubectl cert-manager version + approve Approve a CertificateRequest + convert Convert cert-manager config files between different API versions + create Create cert-manager resources + deny Deny a CertificateRequest + experimental Interact with experimental features + help Help about any command + inspect Get details on certificate related resources + renew Mark a Certificate for manual renewal + status Get details on current status of cert-manager resources + version Print the kubectl cert-manager version Flags: --as string Username to impersonate for the operation @@ -107,6 +111,7 @@ kubectl cert-manager convert -f cert.yaml ### Create `kubectl cert-manager create` can be used to create cert-manager resources manually. Sub-commands are available to create different resources: + #### CertificateRequest To create a cert-manager CertificateRequest, use `kubectl cert-manager create certificaterequest`. The command takes in the name of the CertificateRequest to be created, and creates a new CertificateRequest resource based on the YAML manifest of a Certificate resource as specified by `--from-certificate-file` flag, by generating a private key locally and creating a 'certificate signing request' @@ -154,3 +159,50 @@ Approved CertificateRequest 'istio-system/mesh-ca' $ kubectl cert-manager deny -n my-app my-app --reason "example.com" --message "violates policy" Denied CertificateRequest 'my-app/my-app' ``` + +--- + +### Experimental +`kubectl cert-manager x` has experimental sub-commands for operations which are +currently under evaluation to be included into cert-manager proper. The behavior +and interface of these commands are subject to change or removal in future +releases. + + +#### Create +`kubectl cert-manager x create` can be used to create cert-manager resources manually. Sub-commands are available +to create different resources: + +##### CertificateSigningRequest +To create a [CertificateSigningRequest](../kube-csr/), use `kubectl cert-manager +x create csr`. This command takes the name of the CertificateSigningRequest to +be created, as well as a file containing a Certificate manifest (`-f, +--from-certificate-file`). This command will generate a private key, based on +the options of the Certificate, and write it to the local file `.key`, or +specified by `-k, --output-key-file`. + +```bash +$ kubectl cert-manager x create csr -f my-cert.yaml my-req +``` + + +{{% pageinfo color="warning" %}} + +cert-manager **will not** automatically approve +CertificateSigningRequests. If you are not running a custom approver in your +cluster, you will likely need to manually approve the CertificateSigningRequest: + +```bash +$ kubectl certificate approve +``` + +{{% /pageinfo %}} + +This command can also wait for the CertificateSigningRequest to be signed using +the flag `-w, --fetch-certificate`. Once signed it will write the resulting +signed certificate to the local file `.crt`, or specified by `-c, +--output-certificate-file`. + +```bash +$ kubectl cert-manager x create csr -f my-cert.yaml my-req -w +```