From 85f1e0d4b6d92791b8d1d1f6af338149525fb031 Mon Sep 17 00:00:00 2001
From: Jordan Liggitt <liggitt@google.com>
Date: Mon, 1 Jun 2020 17:39:53 -0400
Subject: [PATCH] CSR API to GA

---
 .../certificate-signing-requests.md           | 28 ++++++++++++++++---
 .../tasks/tls/managing-tls-in-a-cluster.md    | 10 +++++--
 2 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md b/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md
index 3e81215dd818b..8cc6edcd4746a 100644
--- a/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md
+++ b/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md
@@ -10,7 +10,7 @@ weight: 20
 
 {{% capture overview %}}
 
-{{< feature-state for_k8s_version="v1.18" state="beta" >}}
+{{< feature-state for_k8s_version="v1.19" state="stable" >}}
 
 The Certificates API enables automation of
 [X.509](https://www.itu.int/rec/T-REC-X.509) credential provisioning by providing
@@ -109,6 +109,7 @@ Kubernetes provides built-in signers that each have a well-known `signerName`:
 
 1. `kubernetes.io/legacy-unknown`:  has no guarantees for trust at all. Some distributions may honor these as client
   certs, but that behavior is not standard Kubernetes behavior.
+  This signerName can only be requested in CertificateSigningRequests created via the `certificates.k8s.io/v1beta1` API version.
   Never auto-approved by {{< glossary_tooltip term_id="kube-controller-manager" >}}.
     1. Trust distribution: None.  There is no standard trust or distribution for this signer in a Kubernetes cluster.
     1. Permitted subjects - any
@@ -267,12 +268,13 @@ status condition based on the state you determine:
 For `Approved` CSRs:
 
 ```yaml
-apiVersion: certificates.k8s.io/v1beta1
+apiVersion: certificates.k8s.io/v1
 kind: CertificateSigningRequest
 ...
 status:
   conditions:
   - lastUpdateTime: "2020-02-08T11:37:35Z"
+    lastTransitionTime: "2020-02-08T11:37:35Z"
     message: Approved by my custom approver controller
     reason: ApprovedByMyPolicy # You can set this to any string
     type: Approved
@@ -281,12 +283,13 @@ status:
 For `Denied` CSRs:
 
 ```yaml
-apiVersion: certificates.k8s.io/v1beta1
+apiVersion: certificates.k8s.io/v1
 kind: CertificateSigningRequest
 ...
 status:
   conditions:
   - lastUpdateTime: "2020-02-08T11:37:35Z"
+    lastTransitionTime: "2020-02-08T11:37:35Z"
     message: Denied by my custom approver controller
     reason: DeniedByMyPolicy # You can set this to any string
     type: Denied
@@ -315,7 +318,24 @@ Users of the REST API can sign CSRs by submitting an UPDATE request to the `stat
 subresource of the CSR to be signed.
 
 As part of this request, the `status.certificate` field should be set to contain the
-signed certificate.
+signed certificate. This field contains one or more PEM-encoded certificates.
+
+All PEM blocks must have the "CERTIFICATE" label, contain no headers,
+and the encoded data must be a BER-encoded ASN.1 Certificate structure
+as described in section 4 of RFC5280.
+
+Non-PEM content may appear before or after the CERTIFICATE PEM blocks and is unvalidated,
+to allow for explanatory text as described in section 5.2 of RFC7468.
+
+When encoded in JSON or YAML, this field is base-64 encoded:
+
+```yaml
+apiVersion: certificates.k8s.io/v1
+kind: CertificateSigningRequest
+...
+status:
+  certificate: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...<one or more base64-encoded CERTIFICATE PEM blocks>..."
+```
 
 {{% /capture %}}
 
diff --git a/content/en/docs/tasks/tls/managing-tls-in-a-cluster.md b/content/en/docs/tasks/tls/managing-tls-in-a-cluster.md
index 7cd4cc8be5866..a47e86e05c933 100644
--- a/content/en/docs/tasks/tls/managing-tls-in-a-cluster.md
+++ b/content/en/docs/tasks/tls/managing-tls-in-a-cluster.md
@@ -108,12 +108,13 @@ command:
 
 ```shell
 cat <<EOF | kubectl apply -f -
-apiVersion: certificates.k8s.io/v1beta1
+apiVersion: certificates.k8s.io/v1
 kind: CertificateSigningRequest
 metadata:
   name: my-svc.my-namespace
 spec:
   request: $(cat server.csr | base64 | tr -d '\n')
+  signerName: kubernetes.io/kubelet-serving
   usages:
   - digital signature
   - key encipherment
@@ -124,10 +125,13 @@ EOF
 Notice that the `server.csr` file created in step 1 is base64 encoded
 and stashed in the `.spec.request` field. We are also requesting a
 certificate with the "digital signature", "key encipherment", and "server
-auth" key usages. We support all key usages and extended key usages listed
+auth" key usages, signed by the `kubernetes.io/kubelet-serving` signer.
+We support all key usages and extended key usages listed
 [here](https://godoc.org/k8s.io/api/certificates/v1beta1#KeyUsage)
 so you can request client certificates and other certificates using this
-same API.
+same API. A specific `signerName` must be requested.
+View documentation for [supported signer names](/docs/reference/access-authn-authz/certificate-signing-requests/#signers)
+for more information.
 
 The CSR should now be visible from the API in a Pending state. You can see
 it by running: