diff --git a/design/20210209.certificates.k8s.io-adoption.md b/design/20210209.certificates.k8s.io-adoption.md index 2d526a6a7..dd3818480 100644 --- a/design/20210209.certificates.k8s.io-adoption.md +++ b/design/20210209.certificates.k8s.io-adoption.md @@ -9,7 +9,7 @@ approvers: - @jetstack/team-cert-manager editor: "@joshvanl" creation-date: 2021-02-09 -last-updated: 2021-02-17 +last-updated: 2021-02-25 status: provisional --- @@ -41,7 +41,7 @@ status: provisional In Kubernetes v1.19 the [`CertificateSigningRequest`](https://github.com/kubernetes/api/blob/48bd8381a38a486f8b3cdf28cf7334a45b182f2e/certificates/v1/types.go#L41) resource graduated to `certificates.k8s.io/v1`. This makes the concept of -requesting, signing, and consuming certificates in Kubernetes first class +requesting, signing, and consuming certificates in Kubernetes first-class objects. cert-manager is well placed to serve this resource type as it becomes more popular in the wider community, whilst preserving all the features and extensions that cert-manager has to offer. @@ -49,42 +49,68 @@ extensions that cert-manager has to offer. ## Motivation +### Third Party Projects + With the extensiveness of cert-manager’s ecosystem, it is well placed to manage the core Kubernetes resource type. This gives cert-manager the ability to integrate with components that it otherwise wouldn't have, without changes to the third-party project. + +### Security + Having the "request" resource managed inside the API server has a better security profile (i.e. `UserInfo` fields are managed by the API server rather than a configurable webhook, [see](https://github.com/jetstack/cert-manager/pull/3630)). -Consumers of this API do not require cert-manager as a hard dependency. -cert-manager can cause issues with order of operation scenarios during -installation or upgrades. For example, the `CertificateRequest` resource needs -to be installed and the webhook ready for consumers/clients of this API to make -requests. + +### cert-manager Webhook Dependency + +Consumers of the certificates.k8s.io `CertificateRequest` do not require +cert-manager as a hard dependency. cert-manager can cause issues with order of +operation scenarios during installation or upgrades. For example, the +`CertificateRequest` resource needs to be installed and the webhook ready for +consumers/clients of this API to make requests. + +In some setups, the cert-manager installation is handled by two separate teams: + +- The cert-manager CRDs and webhook are installed and managed by the + operations team, which allows the operations team to enforce cluster + policies; +- The cert-manager controller, cainjector and acmesolver are installed and + managed by the developer team. + +By supporting the built-in `CertificateSigningRequest` resource, we decrease the +coupling between the operations team and the developer team. Since the +`CertificateSigningRequest` resource is built-in, it does not need any +`CustomResourceDefinition` installation, and the webhook for this resource is +integrated to the API server. + + +### CertificateSigningRequest Migration Path Support for the `CertificateSigningRequest` resource in cert-manager is a stepping stone to migrating to this resource instead of the `CertificateRequest` resource, if the project does indeed want to migrate. + ### Goals * Add `CertificateSigningRequest` signer controllers to cert-manager for all `Issuer` types -* Pave a way for complete adoption for the `CertificateSigningRequest` - resource in future if wanted +* Pave a way for replacement of the `CertificateRequest` resource for `CertificateSigningRequest` ### Non-Goals -* Remove the `CertificateRequest` resource +* Remove the `CertificateRequest` resource before `CertificateSigningRequest` is + fully supported and a migration path is in place --- ## Reasons for Approach -Bellow are a summary of properties of the `CertificateSigningRequest` which +Below are a summary of properties of the `CertificateSigningRequest` which cause issues or caveats which need to be addressed when adding support for the resource. @@ -106,7 +132,7 @@ selectors. ### Namespaced issuers referenced by CertificateSigningRequest `CertificateSigningRequests` are cluster scoped resources, whereas -`CertificateRequests` are not. cert-manager has the concept of of namespaced +`CertificateRequests` are not. cert-manager has the concept of namespaced issuers that may only be referenced by `CertificateRequests` that reside in the same namespace. Since `CertificateSigningRequests` can reference any namespaced `Issuer`, there must be some mechanism to prevent privilege @@ -135,7 +161,7 @@ reference `Issuers` in the same namespace. with the `CertificateRequest` resource, the duration field will be moved to an annotation as `cert-manager.io/duration` which includes a [Go time duration string](https://golang.org/pkg/time/#Duration.String). This annotation may not -be changed after creation. +be changed after creation of the `CertificateSigningRequest`. ### CA Field @@ -143,7 +169,7 @@ be changed after creation. the `CertificateRequest` resource, the `ca` field will be moved to an annotation as `cert-manager.io/ca`. This annotation value contains the base 64 PEM encoded CA certificate (if one was returned by the signer). This annotation may not be -changed after creation. +changed after creation of the `CertificateSigningRequest`. ### External Issuers @@ -171,8 +197,8 @@ checked via the [discovery endpoint of the API server](https://github.com/kubernetes/client-go/blob/7279fc64d8478bd5f9d38122143b5e6294f06e75/discovery/discovery_client.go#L55). If the resource is not available, the `CertificateSigningRequest` controllers should gracefully never start. If the Kubernetes API server were to be upgraded -to a version that does support this resource, cert-manager will need to be -restarted to make use of these controllers. This is acceptable- worker nodes are +to a version that does support this resource, cert-manager would need to be +restarted to make use of these controllers. This is acceptable—worker nodes are typically always restarted during a cluster upgrade. @@ -185,10 +211,12 @@ conflicts with other external signer projects. ```yaml # Namespaced issuer reference - signerName: cert-manager.io/. + # e.g. `issuers.cert-manager.io/my-namespace.my-issuer + signerName: .cert-manager.io/. # Cluster scoped issuer reference - signerName: cert-manager.io/ + # e.g. `clusterissuers.cert-manager.iomy-issuer + signerName: .cert-manager.io/ ``` Using the same approach of referencing by _just_ name, rather than issuer type @@ -229,7 +257,7 @@ of `Approved`, `Denied`, and `Failed`. All `CertificateSigningRequest` signer controllers should not begin computation of the request until the resource has the `Approved` condition set to `True`. -In the absence of further policy, the `Approved` condition is always set with +In the absence of further policy, the `Approved` condition is always set t `True`, _unless_, the `CertificateSigningRequest` references a namespaced `Issuer` and the requester does not have create permissions for `certificates.k8s.io/CertificateSigningRequests` in that namespace. In the case @@ -280,7 +308,7 @@ No effect to upgrades as only additional controllers added. No CRD API changes. Below is each level of graduation for support of `CertificateSigningRequest` in cert-manager. -1. Create signer implementations for each cert-manager.io issuers. These +1. Create signer implementations for each cert-manager.io issuer types. These controllers are active in a default cert-manager installation, though `CertificateRequests` are the resource created from `Certificate` resources. @@ -289,4 +317,3 @@ cert-manager. 1. [TBD] Remove the `CertificateRequest` resource from the cert-manager project, in favour of the `CertificateSigningRequest` resource. -