Adds documentation for CSR supporting all issuers, and the CTL command

.go-version

@@ -1 +1 @@
-1.15.1
+1.16.6

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 <name>
+```

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 `<name>.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 <name>
+```
+
+{{% /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 `<name>.crt`, or specified by `-c,
+--output-certificate-file`.
+
+```bash
+$ kubectl cert-manager x create csr -f my-cert.yaml my-req -w
+```