diff --git a/.spelling b/.spelling index c1479106e69..8f6162ef882 100644 --- a/.spelling +++ b/.spelling @@ -31,12 +31,16 @@ boolean CAs CertificateRequest CertificateRequests +CertificateSigningRequest +CertificateSigningRequests Changelog ChartMuseum CloudDNS Cloudflare CloudFlare ClusterRole +ClusterIssuer +ClusterIssuers CNAME CNAMEs CNI @@ -162,6 +166,7 @@ stdout subdomain (sub)domains subdomains +SubjectAccessReview subresource templating Tiller @@ -248,6 +253,20 @@ retweets upstream JetstackHQ acme-dns +Ramlot +andreas-p +renewBefore +erikgb +eddiehoffman +inteon +anton-johansson +edglynes +jandersen-plaid +foosinn +clatour +tamalsaha +JoshVanL +Kyverno hardcodes # As per https://tools.ietf.org/html/rfc5280, the spelling "X.509" is the diff --git a/content/en/docs/contributing/crds.md b/content/en/docs/contributing/crds.md index 5802f571c4d..ab867d481c0 100644 --- a/content/en/docs/contributing/crds.md +++ b/content/en/docs/contributing/crds.md @@ -20,11 +20,15 @@ This will also update the version conversion code if needed. ## Versions -cert-manager at time of writing has 4 CRD versions in use. +cert-manager currently has 4 CRD versions in use: -These versions are defined in [`//pkg/apis/certmanager`](https://github.com/jetstack/cert-manager/tree/master/pkg/apis/certmanager). ACME related resources are in `//pkg/apis/acme`. +- `v1` +- `v1beta1` (deprecated in cert-manager `v1.4.0`, removed `v1.6.0`) +- `v1alpha3` (deprecated in cert-manager `v1.4.0`, removed `v1.6.0`) +- `v1alpha2` (deprecated in cert-manager `v1.4.0`, removed `v1.6.0`) + +These versions are defined in [`//pkg/apis/certmanager`](https://github.com/jetstack/cert-manager/tree/master/pkg/apis/certmanager). ACME related resources are in [`//pkg/apis/acme`](https://github.com/jetstack/cert-manager/tree/master/pkg/apis/certmanager). -This has the versions `v1alpha2`, `v1alpha3`, `v1beta1` and `v1`. If you need to introduce a new field in any of them it **must** be present in all 4 versions so conversion can be used. Code comments on these fields are being converted into documentation on our website and text of `kubectl explain`. @@ -34,6 +38,8 @@ We also have an internal API version, it lives at [`//pkg/internal/apis`](https: This is a version that is only used for validation and conversion, controllers should not use it as it is not meant to be user-friendly and not stable. However all new fields also have to be added here for the conversion logic to work. +See the [official Kubernetes docs for CRD versioning](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/) to understand conversion, which versions are stored and served etc. + ## Kubebuilder diff --git a/content/en/docs/faq/_index.md b/content/en/docs/faq/_index.md index 559328c75df..20e80f61464 100644 --- a/content/en/docs/faq/_index.md +++ b/content/en/docs/faq/_index.md @@ -52,7 +52,7 @@ spec: ### If `renewBefore` or `duration` is not defined, what will be the default value? cert-manager will default to a `duration` of [90 days](https://github.com/jetstack/cert-manager/blob/v1.2.0/pkg/apis/certmanager/v1/const.go#L26) with a `renewBefore` of [30 days](https://github.com/jetstack/cert-manager/blob/v1.2.0/pkg/apis/certmanager/v1/const.go#L32). -If `renewBefore` is not set and the duration of the signed certificate is shorter or equal to 30 days, the `renewBefore` time will be set to 2/3 of the signed certificate validity duration. +The renewal time of the certificate will be calculated using the formula `min(duration / 3, renewBefore)`, see [renewal](../usage/certificate/#renewal) for more detail. When setting `duration` it is recommended to also set `renewBefore`, if `renewBefore` is longer than `duration` you will receive an error. ## Miscellaneous @@ -70,8 +70,10 @@ because such certificates increase the opportunity for attacks on the Kubernetes In Kubernetes 1.19 the [Certificate Signing Requests API] has reached V1 and it can be used more generally by following (or automating) the [Request Signing Process]. -There are plans for cert-manager make greater use of this API now that it is stable. + +cert-manager currently has some [limited experimental support] for this resource. [Certificate Signing Requests API]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#certificatesigningrequest-v1-certificates-k8s-io [`kubectl certificates` command]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#certificate [Request signing process]: https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/#request-signing-process +[limited experimental support]: ../usage/kube-csr/ diff --git a/content/en/docs/installation/supported-releases.md b/content/en/docs/installation/supported-releases.md index acfdbc4b110..3fe037671b3 100644 --- a/content/en/docs/installation/supported-releases.md +++ b/content/en/docs/installation/supported-releases.md @@ -17,24 +17,27 @@ release every two months. ## Supported releases {#supported-releases} -| Release | Release Date | EOL | [Supported Kubernetes versions][s] | -| ------- | :----------: | :---------------: | :--------------------------------: | -| [1.3][] | Apr 08, 2021 | [~][]Aug 2021 | 1.16, 1.17, 1.18, 1.19, 1.20, 1.21 | -| [1.2][] | Feb 10, 2021 | [~][]Jun 11, 2021 | 1.16, 1.17, 1.18, 1.19, 1.20, 1.21 | +| Release | Release Date | EOL | [Supported Kubernetes versions][s] | +|---------|:------------:|:------------:|:----------------------------------:| +| [1.4][] | Jun 15, 2021 | Oct 13, 2021 | 1.16, 1.17, 1.18, 1.19, 1.20, 1.21 | +| [1.3][] | Apr 08, 2021 | Aug 11, 2021 | 1.16, 1.17, 1.18, 1.19, 1.20, 1.21 | ## Upcoming releases -| Release | Release Date | EOL | [Supported Kubernetes versions][s] | -| ------- | :---------------: | :-----------: | :--------------------------------: | -| [1.4][] | [~][]Jun 11, 2021 | [~][]Oct 2021 | 1.16, 1.17, 1.18, 1.19, 1.20, 1.21 | +| Release | Release Date | EOL | [Supported Kubernetes versions][s] | +|---------|:------------:|:------------:|:----------------------------------------:| +| [1.5][] | Aug 11, 2021 | Dec 15, 2021 | 1.16, 1.17, 1.18, 1.19, 1.20, 1.21, 1.22 | +| 1.6 | Oct 13, 2021 | Feb 16, 2022 | to be defined | +| 1.7 | Dec 15, 2021 | Apr 13, 2022 | to be defined | -> The `~` sign is used when the date is uncertain and might change; the -> "EOL" abbreviation stands for End Of Life. +> Note that dates in the future are uncertain and might change. The "EOL" +> abbreviation stands for End Of Life. ## Old releases | Release | Release Date | EOL | Compatible Kubernetes versions | -| -------- | :----------: | :----------: | :----------------------------: | +|----------|:------------:|:------------:|:------------------------------:| +| [1.2][] | Feb 10, 2021 | Jun 15, 2021 | 1.16 → 1.21 | | [1.1][] | Nov 24, 2021 | Apr 08, 2021 | 1.11 → 1.21 | | [1.0][] | Sep 02, 2020 | Feb 10, 2021 | 1.11 → 1.21 | | [0.16][] | Jul 23, 2020 | Nov 24, 2020 | 1.11 → 1.21 | @@ -45,8 +48,8 @@ release every two months. | [0.11][] | Oct 10, 2019 | Jan 21, 2020 | 1.9 → 1.21 | [s]: #kubernetes-supported-versions -[~]: https://docs.google.com/document/d/1Tc5t6ylY9dhXAan1OjOoldeaoys1Yh4Ir710ATfBa5U/edit?pli=1#bookmark=id.jzi02xg0ngn "Project timeline" -[1.4]: https://github.com/jetstack/cert-manager/milestone/25 +[1.5]: https://github.com/jetstack/cert-manager/milestone/26 +[1.4]: https://cert-manager.io/docs/release-notes/release-notes-1.4 [1.3]: https://cert-manager.io/docs/release-notes/release-notes-1.3 [1.2]: https://cert-manager.io/docs/release-notes/release-notes-1.2 [1.1]: https://cert-manager.io/docs/release-notes/release-notes-1.1 @@ -210,10 +213,10 @@ Our testing coverage is: | Release branch | Prow configuration | Dashboard | Kubernetes versions tested | Periodicity | | :------------: | :---------------------------- | :------------------------ | :--------------------------- | :-----------: | | PRs | [`presubmits.yaml`][] | [`presubmits-blocking`][] | 1.21 | On each PR | -| master | [`periodics.yaml`][] | [`master`][] | 1.16, 1.17, 1.18, 1.19, 1.20 | Every 2 hours | -| release-1.4 | [`next-periodics.yaml`][] | [`next`][] | 1.16, 1.17, 1.18, 1.19, 1.20 | Every 2 hours | -| release-1.3 | [`previous-periodics.yaml`][] | [`previous`][] | 1.16, 1.17, 1.18, 1.19, 1.20 | Every 2 hours | -| release-1.2 | N/A | | N/A | N/A | +| master | [`periodics.yaml`][] | [`master`][] | 1.16, 1.17, 1.18, 1.19, 1.21 | Every 2 hours | +| release-1.5 | [`next-periodics.yaml`][] | [`next`][] | 1.16, 1.17, 1.18, 1.19, 1.21 | Every 2 hours | +| release-1.4 | [`previous-periodics.yaml`][] | [`previous`][] | 1.16, 1.17, 1.18, 1.19, 1.21 | Every 2 hours | +| release-1.3 | N/A | | N/A | N/A | [`presubmits.yaml`]: https://github.com/jetstack/testing/blob/master/config/jobs/cert-manager/cert-manager-presubmits.yaml [`periodics.yaml`]: https://github.com/jetstack/testing/blob/master/config/jobs/cert-manager/cert-manager-periodics.yaml @@ -227,15 +230,15 @@ Our testing coverage is: The oldest Kubernetes release supported by cert-manager is 1.16, as we want to be supporting most commercial Kubernetes offerings. -| Vendor | Oldest Kubernetes Release\* | End of Life | -| :--------: | :-------------------------: | :---------: | -| [EKS][eks] | 1.16 | 25 Jul 2021 | -| [GKE][gke] | 1.17 | Nov 2021 | -| [AKS][aks] | 1.18 | Jun 2021 | +| Vendor | Oldest Kubernetes Release\* | Other Old Kubernetes Releases | +|:----------:|:---------------------------:|--------------------------------------------------------------| +| [EKS][eks] | 1.16 (EOL Jul 2021) | 1.17 (EOL Sep 2021), 1.18 (EOL Nov 2021), 1.9 (EOF Apr 2022) | +| [GKE][gke] | 1.17 (EOL Nov 2021) | 1.18 (EOL Dec 2021), 1.19 (EOL Feb 2022) | +| [AKS][aks] | 1.18 (EOL Jul 2021) | 1.19 (EOL Aug 2021) | -\*As of 2021-05-25. +\*As of June 15, 2021. -[eks]: https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html +[eks]: https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html#kubernetes-release-calendar [gke]: https://cloud.google.com/kubernetes-engine/docs/release-schedule [aks]: https://docs.microsoft.com/en-us/azure/aks/supported-kubernetes-versions#aks-kubernetes-release-calendar diff --git a/content/en/docs/installation/upgrading/remove-deprecated-apis.md b/content/en/docs/installation/upgrading/remove-deprecated-apis.md new file mode 100644 index 00000000000..8ff989eba3b --- /dev/null +++ b/content/en/docs/installation/upgrading/remove-deprecated-apis.md @@ -0,0 +1,52 @@ +--- +title: "Removing Deprecated API Resources" +linkTitle: "Removing Deprecated API Resources" +weight: 20 +type: "docs" +--- + +We have deprecated the following cert-manager APIs: + +- `cert-manager.io/v1alpha2` +- `cert-manager.io/v1alpha3` +- `cert-manager.io/v1beta1` +- `acme.cert-manager.io/v1alpha2` +- `acme.cert-manager.io/v1alpha3` +- `acme.cert-manager.io/v1beta1` + +These APIs will be removed in cert-manager `v1.6.0`. +If you have a cert-manager installation that is using or has previously used these deprecated APIs you may need to upgrade your cert-manager custom resources and CRDs. This needs to be done before upgrading to cert-manager `v1.6.0`. + + +## Upgrading existing cert-manager resources + +1. Familiarize yourself with the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#writing-reading-and-updating-versioned-customresourcedefinition-objects) on CRD versioning. +2. Make sure your installed cert-manager deployment is `v1.0.0` or later. + +3. Make sure any version-controlled cert-manager custom resource config files that still use the deprecated APIs are updated to use the `cert-manager.io/v1` API and re-applied. This should update stored versions of the given resources. + +After that, follow the official Kubernetes documentation [here](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#upgrade-existing-objects-to-a-new-stored-version): + +1. If there are other resources (e.g. `Certificate`s created by ingress-shim, `CertificateRequest`s, etc.) that are not version controlled and may have been created using the deprecated APIs, run + ```bash + kubectl get -oyaml | kubectl apply -f - + ``` + to force the resources to be stored in `etcd` at the current storage version. + +2. To remove legacy API versions from cert-manager CRDs run the following `curl` commands: + +```bash +kubectl proxy & + +curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json" -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/certificates.cert-manager.io/status + +curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json" -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/certificaterequests.cert-manager.io/status + +curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json" -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/issuers.cert-manager.io/status + +curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json" -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/clusterissuers.cert-manager.io/status + +curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json" -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/orders.acme.cert-manager.io/status + +curl -d '[{ "op": "replace", "path":"/status/storedVersions", "value": ["v1"] }]' -H "Content-Type: application/json-patch+json" -X PATCH http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/challenges.acme.cert-manager.io/status +``` diff --git a/content/en/docs/installation/upgrading/upgrading-1.3-1.4.md b/content/en/docs/installation/upgrading/upgrading-1.3-1.4.md new file mode 100644 index 00000000000..cc46d487954 --- /dev/null +++ b/content/en/docs/installation/upgrading/upgrading-1.3-1.4.md @@ -0,0 +1,9 @@ +--- +title: "Upgrading from v1.3 to v1.4" +linkTitle: "v1.3 to v1.4" +weight: 820 +type: "docs" +--- + +When upgrading from `v1.3` to `v1.4`, no special upgrade steps are required 🎉. +From here on you can follow the [regular upgrade process](../). diff --git a/content/en/docs/release-notes/_index.md b/content/en/docs/release-notes/_index.md index f6f78c0c2a9..f4c4c992b1e 100644 --- a/content/en/docs/release-notes/_index.md +++ b/content/en/docs/release-notes/_index.md @@ -9,6 +9,7 @@ no_list: true Here you will find a link to all release notes for each version release of cert-manager: +- [`v1.4`](./release-notes-1.4/) - [`v1.3`](./release-notes-1.3/) - [`v1.2`](./release-notes-1.2/) - [`v1.1`](./release-notes-1.1/) diff --git a/content/en/docs/release-notes/release-notes-1.3.md b/content/en/docs/release-notes/release-notes-1.3.md index ad80751d103..400df4a4b02 100644 --- a/content/en/docs/release-notes/release-notes-1.3.md +++ b/content/en/docs/release-notes/release-notes-1.3.md @@ -5,7 +5,20 @@ weight: 800 type: "docs" --- -This release prepares for the implementation of certificate issuance policies and adoption of the upstream [Kubernetes CSR](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/) API. It also improves interoperability with HashiCorp [Vault Enterprise](https://www.vaultproject.io/docs/enterprise). +# Patch Release `v1.3.1` + +## Bug and Security Fixes + +- A Helm upgrade bug was + [fixed](https://github.com/jetstack/cert-manager/pull/3882), you should now + able to upgrade from cert-manager 1.2 to 1.3 when `--set installCRDs=true` is + used. This issue was due to [a Helm + bug](https://github.com/helm/helm/issues/5806#issuecomment-788116838) with the + `minimum` field on the CRDs. + +# Final Release `v1.3.0` + +The 1.3 release prepares for the implementation of certificate issuance policies and adoption of the upstream [Kubernetes CSR](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/) API. It also improves interoperability with HashiCorp [Vault Enterprise](https://www.vaultproject.io/docs/enterprise). A slew of bugs have also been squashed. Special thanks to the external contributors who contributed to this release: @@ -28,9 +41,9 @@ Please read the [upgrade notes](/docs/installation/upgrading/upgrading-1.2-1.3/) As always, the full change log is available on the [GitHub release](https://github.com/jetstack/cert-manager/releases/tag/v1.3.0). -# Deprecated Features and Breaking Changes +## Deprecated Features and Breaking Changes -## Venafi Cloud Issuer +### Venafi Cloud Issuer This release updates the [Venafi Cloud Issuer][] to use `OutagePREDICT` instead of `DevOpsACCELERATE`. @@ -40,17 +53,17 @@ The zone is now `\` [Venafi Cloud Issuer]: https://cert-manager.io/docs/configuration/venafi/ -## cert-manager controller +### cert-manager controller The `--renew-before-expiration-duration` flag has been removed from the cert-manager controller, having been deprecated in the previous release. -## cert-manager CRDs +### cert-manager CRDs `CertificateRequests` are now immutable - the `spec` and `metadata.annotations` fields cannot be changed after creation. They were always designed to be immutable but this behavior is now *enforced* by the cert-manager webhook. -# New Features +## New Features -## Policy Support Preparation +### Policy Support Preparation * The [design documentation](https://github.com/jetstack/cert-manager/blob/v1.3.0/design/20210203.certificate-request-identity.md) for Certificate Identity is now available. * `CertificateRequests` now have identity fields mirroring the upstream [Kubernetes CSR](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/) object. @@ -59,38 +72,38 @@ The `--renew-before-expiration-duration` flag has been removed from the cert-man * The cert-manager controller currently always approves any `CertificateRequest`. * Added `kubectl cert-manager [approve|deny]` commands to the kubectl plugin. -## cert-manager CRDs +### cert-manager CRDs * `CertificateRequests` now support the `revisionHistoryLimit` field to limit the amount of retained history. The default is unlimited (`nil`). -## Vault Enterprise +### Vault Enterprise * cert-manager now sends the `X-VAULT-NAMESPACE` header for the `requestTokenWithAppRoleRef` API call. -# Bug Fixes +## Bug Fixes -## cert-manager Controller +### cert-manager Controller * Fixed an issue which could cause multiple `CertificateRequests` to be created in a short time for a single `Certificate` resource. * Certificate Readiness controller only updates a certificate's status if something has changed. -## SelfSigned Issuer +### SelfSigned Issuer * The issuer now warns if you request a certificate with an empty subject DN - creating a certificate that is in violation of RFC 5280. Some applications will reject such certificates as invalid, such as Java's `keytool`. -## Helm Chart +### Helm Chart * The `targetPort` used by the Prometheus service monitor is now correctly set from helm values. * The correct permissions are added to the aggregate `edit` role. -# Other Changes +## Other Changes ## Repository Hygiene * `SECURITY.md` now contains information on how to report security issues. * The language of `CONTRIBUTING.md` has been updated to match existing copyright notices. -## Tooling +### Tooling * cert-manager now can be built with go 1.16 on Apple Silicon. * Docker images targets have been added to the Makefile. diff --git a/content/en/docs/release-notes/release-notes-1.4.md b/content/en/docs/release-notes/release-notes-1.4.md new file mode 100644 index 00000000000..ba049bb4e05 --- /dev/null +++ b/content/en/docs/release-notes/release-notes-1.4.md @@ -0,0 +1,355 @@ +--- +title: "Release Notes" +linkTitle: "v1.4" +weight: 800 +type: "docs" +--- + +# Final Release `v1.4.0` + +Special thanks to the external contributors who contributed to this release: + +* [@andreas-p](https://github.com/andreas-p) +* [@erikgb](https://github.com/erikgb) +* [@eddiehoffman](https://github.com/eddiehoffman) +* [@inteon](https://github.com/inteon) +* [@anton-johansson](https://github.com/anton-johansson) +* [@edglynes](https://github.com/edglynes) +* [@jandersen-plaid](https://github.com/jandersen-plaid) +* [@foosinn](https://github.com/foosinn) +* [@jsoref](https://github.com/jsoref) +* [@clatour](https://github.com/clatour) +* [@tamalsaha](https://github.com/tamalsaha) + +## Deprecated Features and Breaking Changes + +### Upgrading cert-manager CRDs and stored versions of cert-manager custom resources + +We have deprecated the following cert-manager APIs: + +- `cert-manager.io/v1alpha2` +- `cert-manager.io/v1alpha3` +- `cert-manager.io/v1beta1` +- `acme.cert-manager.io/v1alpha2` +- `acme.cert-manager.io/v1alpha3` +- `acme.cert-manager.io/v1beta1` + +These APIs will be removed in cert-manager 1.6. + +{{% pageinfo color="warning" %}} + +⛔️ If you are upgrading cert-manager on a cluster which has previously had +cert-manager < `v1.0.0`, you will need to ensure that all cert-manager custom +resources are stored in `etcd` at `v1` version and that cert-manger CRDs do not +reference the deprecated APIs **by the time you upgrade to `v1.6`**. + +This is explained in more detail in the [Upgrading existing cert-manager +resources][upgrade-resources] page. + +{{% /pageinfo %}} + +This change was made in the cert-manager PR [#4021][]. + +[upgrade-resources]: ../../installation/upgrading/remove-deprecated-apis/#upgrading-existing-cert-manager-resources +[#4021]: https://github.com/jetstack/cert-manager/pull/4021 "Warn about removal of old v1alpha2, v1alpha3 and v1beta1 in 1.6" + +### Helm chart: `securityContext` defaults to non-root + +The Helm chart now follows the current Pod hardening best practices as defined +by the Kyverno [`pod-security +restricted`](https://kyverno.io/policies/pod-security/#restricted) policy. + +To pass the validation, the controller, webhook, and cainjector Pods are now +running as non-root: + +```yaml +apiVersion: v1 +kind: Pod +spec: + securityContext: + runAsNonRoot: true +``` + +{{% pageinfo color="warning" %}} + +⛔️ If you are using custom containers that run as root with the Helm chart, you +will need to set this back to `false`. + +{{% /pageinfo %}} + +Implemented in the cert-manager PR [#4036][]. + +[#4036]: https://github.com/jetstack/cert-manager/pull/4036 "controller, cainject and webhook now run as non-root" + +### CA, Vault and Venafi issuer handling of `ca.crt` and `tls.crt` + +The CA, Vault, and Venafi issuer now produce a `tls.crt` that is de-duplicated, +in the correct order (leaf at the top, issuing certificate at the bottom) and +verified (i.e. each signature can be verified). + +The CA issuer now produces a `ca.crt` that contains the "most" root CA that +cert-manager is aware of. `ca.crt` may thus not be the actual self-signed root +CA, since cert-manager may not be aware of it. + +Fixed in the cert-manager PRs [#3982][], [#3983][], and [#3985][]. + +{{% pageinfo color="warning" %}} + +⛔️ You may need to adjust systems that consume the `ca.crt` from Secrets +managed by cert-manager with the CA issuer. + +{{% /pageinfo %}} + +[#3982]: https://github.com/jetstack/cert-manager/pull/3982 "All issuers + Vault issuer" +[#3983]: https://github.com/jetstack/cert-manager/pull/3983 "Venafi issuer" +[#3985]: https://github.com/jetstack/cert-manager/pull/3985 "CA issuer" + + +### Vault renewal bug + +The renewal behavior has changed when a Certificate has a `duration` value of +more than 90 days and `renewBefore` has not been set. + +Previously, the Certificate was renewed 30 days before expiry; now, the renewal +happens 2/3 through the duration. + +This change was necessary to fix a bug where users of the Vault issuer would see +a clash between the default renewal duration of 30 days and the duration of +certificates issued by the Vault PKI. + +{{% pageinfo color="warning" %}} + +⛔️ If you were relying on the default renewal happening 30 days before expiry, +we would advise setting `renewBefore` to 30 days (`720h`) to keep the old +behavior. + +{{% /pageinfo %}} + +Fixed in the cert-manager PR [#4092][]. + +[#4092]: https://github.com/jetstack/cert-manager/pull/4092 "Defaukt renewal changed from 30 days before to 2/3 of the duration before expiry" + +## New Features + +### Experimental Support for Kubernetes CertificateSigningRequests + +It is now possible to use the built-in Kubernetes [CertificateSigningRequest][] +resources with cert-manager. The CA Issuer is currently the only supported +issuer. The feature is experimental and can be enabled by adding a flag to the +cert-manager controller. For example, with Helm: + +```sh +helm install cert-manager jetstack/cert-manager \ + --set extraArgs="{--feature-gates=ExperimentalCertificateSigningRequestControllers=true}" +``` + +Note that you will still need to manually approve the CSR object before +cert-manager can sign the CSR. + +The documentation is available on the [the Kubernetes CSR usage +page](../../usage/kube-csr/). + +Implemented in cert-manager PR [#4064][]. + +[#4064]: https://github.com/jetstack/cert-manager/pull/4064 "CA issuer experimental support for CertificateSigningRequests" +[CertificateSigningRequest]: https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/ + +### Helm chart: webhook externally accessible for bare-metal + +In [some](https://github.com/kubernetes/kubernetes/issues/72936#issue-399522387) +Kubernetes setups, the apiserver is not able to talk to `kube-dns` (i.e., when +Kubernetes is running on bare-metal with no special `resolv.conf`). + +To work around that, the cert-manager webhook can now be configured to be +accessible from outside of the cluster. For example, in `values.yaml`: + +```yaml +# values.yaml +webhook: + serviceType: LoadBalancer + loadBalancerIP: 198.51.100.20 + url: + host: 198.51.100.20 +``` + +Implemented in the cert-manager PR [#4064][]. + +### Helm chart: Service labels + +The cert-manager controller Service now supports custom labels using the +top-level field in `values.yaml`: + +```yaml +# values.yaml +serviceLabels: + app: armada-api +``` + +This may be useful in conjunction with Prometheus' `labelmap`. For example, with +the following sample Prometheus configuration: + +```yaml +# prometheus.yaml +- action: labelmap + regex: __meta_kubernetes_service_label_(.+) +``` + +With the above example, the source label +`__meta_kubernetes_service_label_app='armada-api'` becomes the new label +`app='armada-api'` when metrics related to this Service are scraped. + +Implemented in the cert-manager PR [#4009][]. + +[#4009]: https://github.com/jetstack/cert-manager/pull/4009 "Helm chart: the Service labels can now be set on the controller" + +### Akamai DNS01 solver + +The Akamai DNS01 solver has been [updated][4007] to use the v2 of the `OPEN +EdgeGrid` Go package. + +[#4007]: https://github.com/jetstack/cert-manager/pull/4007 "Update of the Akamai DNS01 solver" + +## Bug Fixes + +- The [RFC2136](https://cert-manager.io/docs/configuration/acme/dns01/rfc2136/) + issuer is now able to handle DNS01 challenges that map to multiple `TXT` + records. This lets you create Let's Encrypt certificates using RFC2136 with + multiple DNS names. Fixed in the cert-manager PR [#3622][]. +- The comparison function `PublicKeysEqual` is now correct for public keys. + Fixed in PR [#3914][]. +- The ACME issuer now works correctly with Certificates that have a long name + (52 characters or more). These Certificates would not get renewed due to + non-unique Order names being generated. Fixed in the cert-manager PR + [#3866][]. +- Orders that are used with a misbehaving ACME server should not get stuck + anymore. By misbehaving, we mean an ACME server that would validate the + authorizations before having set the status of the order to "ready". Fixed in + the cert-manager PR [#3805][]. +- The internal issuers now set the condition `Ready=False` with the reason + `RequestDenied` when a CertificateRequest has been `Denied`. This is to keep + the same behavior where a terminal state of a CertificateRequest should have a + `Ready` condition. Fixed in the cert-manager PR [#3878][]. + +[#3622]: https://github.com/jetstack/cert-manager/pull/3622 "RFC2136 fixed when used with challenge domains that contain multiple TXT records" +[#3914]: https://github.com/jetstack/cert-manager/pull/3914 "Comparison between public keys now works properly" +[#3866]: https://github.com/jetstack/cert-manager/pull/3866 "Certificates with long names are not generated non-unique Orders anymore" +[#3805]: https://github.com/jetstack/cert-manager/pull/3805 "Misbehaving ACME servers won't get Orders stuck anymore" +[#3878]: https://github.com/jetstack/cert-manager/pull/3878 "When a CertificateRequest is Denied, the internal issuers set Ready=False" + +## Other Changes + +- The cert-manager controller now uses the `configmapsleases` resource instead + of the `configmaps` one for leader election. The only noticeable difference is + that a new `Lease` object is now being created in the leader election + namespace. Implemented in the cert-manager PR [#4016][]. + +[#4016]: https://github.com/jetstack/cert-manager/pull/4016 "Use the configmapsleases resource instead of configmaps" + +- The `keyAlgorithm` for the ACME Issuer is now deprecated, and the EAB MAC + algorithm is now hard-coded to `HS256`. + + ```yaml + apiVersion: cert-manager.io/v1 + kind: Issuer + spec: + acme: + externalAccountBinding: + keyAlgorithm: HS256 # DEPRECATED. + ``` + Previously, we used to have a fork of `golang/crypto` which allowed us to set + the EAB MAC algorithm. We now use the upstream version of `golang/crypto` + where the EAB MAC algorithm is hard-coded to HS256. + + This change were implemented in the cert-manager PRs [#3877][] and [#3936][]. + +[#3877]: https://github.com/jetstack/cert-manager/pull/3877 "Deprecation of the keyAlgorithm field" +[#3936]: https://github.com/jetstack/cert-manager/pull/3936 "Webhook warns the user when keyAlgorithm is used" + +- If you happen to look at the cert-manager controller logs, you may see this + new message about optimistic locking: + + ``` + I0419 controller.go:158] msg="re-queuing item due to optimistic locking on resource" error="Operation cannot be fulfilled on certificates.cert-manager.io sauron-adverts-evo-app-tls: the object has been modified; please apply your changes to the latest version and try again" + ``` + + This message, shown at the `info` level, replaces the `error` level message + that showed previously: + + ``` + E0419 controller.go:158] msg="re-queuing item due to error processing" error="Operation cannot be fulfilled on certificates.cert-manager.io sauron-adverts-evo-app-tls: the object has been modified; please apply your changes to the latest version and try again" + ``` + + The goal is to prevent users from thinking that the optimistic locking + mechanism has to do with their issues, when in reality it mostly isn't and is + the normal operation mode for Kubernetes controllers. + + Fixed in the cert-manager PR [#3794][]. + +[#3794]: https://github.com/jetstack/cert-manager/pull/3794 "Less alarming message on optimistic locking errors" + +- The `util.UsageContentCommittment` (which contained a spelling mistake) was + deprecated in favor of `util.UsageContentCommitment`. The only people impacted + by this deprecation are the the people importing the Go package + `github.com/jetstack/cert-manager/pkg/api/util`. + +[#3860]: https://github.com/jetstack/cert-manager/pull/3860 "Fix a spelling mistake in a cert-manager Go package and deprecate the old name" + +- The webhook now panics when it is not able to register the API schemes. + Previously, the webhook would silently skip the error and start. + +[#4037]: https://github.com/jetstack/cert-manager/pull/4037 "Webhook now panics instead of silently starting if the API scheme cannot be registered" + +- A couple of legacy functions in `test/e2e/util` package have been removed. + These functions can be found in the `test/unit/gen` package. + +[#3873]: https://github.com/jetstack/cert-manager/pull/3873 "Legacy functions in the test/e2e/util have been removed" + +- The Kubernetes Go dependencies have been updated from `v0.19.0` to `v0.21.0`. + +[#3926]: https://github.com/jetstack/cert-manager/pull/3926 "Update Kubernetes Go imports from v0.19.0 to v0.21.0" + +- When waiting for DNS propagating, the ACME DNS01 self-check now returns a + better message when an unexpected DNS response code is received, such as + `SERVFAIL`. + + Before: + ``` + Could not find the start of authority + ``` + + After: + ``` + Could not find the SOA record in the DNS tree + for the domain '_acme-challenge.foo.example.com' + using nameservers [8.8.8.8, 8.8.4.4] + ``` + + In addition to the above, you will get a new message when the DNS returns an + unexpected response code: + + ``` + When querying the SOA record for the domain + '_acme-challenge.foo.example.com' using nameservers + [8.8.8.8, 8.8.4.4], rcode was expected to be 'NOERROR' + or 'NXDOMAIN', but got 'SERVFAIL' + ``` + + Fixed in the cert-manager PR [#3906][]. + +[#3906]: https://github.com/jetstack/cert-manager/pull/3906 "Better message when the ACME DNS01 self-check gets an unexpected DNS response code" + +- The `distroless/static` base image was updated to the latest version as of + 2021-05-20. + +## Honorable mentions + +Tim Ramlot ([@inteon](https://github.com/inteon)) has done a fantastic job at +adding the Istio `VirtualService` support for HTTP01 challenges in +[#3724](https://github.com/jetstack/cert-manager/pull/3724). It took an immense +effort to have this PR ready and merged for the 1.4 release. + +After a lot of thinking, we have decided that trying to support every custom +resource for every proxy could not be done in-tree due to the Go dependency +weight that each integration adds. Jake Sanders proposed an [out-of-tree +approach](https://github.com/jetstack/cert-manager/issues/3924) that will be +worked on as part of cert-manager 1.5. diff --git a/content/en/docs/usage/certificate.md b/content/en/docs/usage/certificate.md index dd4675ce284..6e54e78b5fc 100644 --- a/content/en/docs/usage/certificate.md +++ b/content/en/docs/usage/certificate.md @@ -16,7 +16,7 @@ In order to issue any certificates, you'll need to configure an ## Creating Certificate Resources -A `Certificate` resource specifies fields that are used to generated certificate +A `Certificate` resource specifies fields that are used to generate certificate signing requests which are then fulfilled by the issuer type you have referenced. `Certificates` specify which issuer they want to obtain the certificate from by specifying the `certificate.spec.issuerRef` field. @@ -91,15 +91,6 @@ The `Certificate` will be issued using the issuer named `ca-issuer` in the > from functioning correctly > [`#1269`](https://github.com/jetstack/cert-manager/issues/1269). -> Note: Take care when setting the `renewBefore` field to be very close to the -> `duration` as this can lead to a renewal loop, where the `Certificate` is always -> in the renewal period. Some `Issuers` set the `notBefore` field on their -> issued X.509 certificates before the issue time to fix clock-skew issues, -> leading to the working duration of a certificate to be less than the full -> duration of the certificate. For example, Let's Encrypt sets it to be one hour -> before issue time, so the actual *working duration* of the certificate is 89 -> days, 23 hours (the *full duration* remains 90 days). - A full list of the fields supported on the Certificate resource can be found in the [API reference documentation](../../reference/api-docs/#cert-manager.io/v1alpha2.CertificateSpec) @@ -173,3 +164,13 @@ This means that deleting a `Certificate` won't take down any services that are c The `Secret` needs to be manually deleted if it is no longer needed. If you would prefer the `Secret` to be deleted automatically when the `Certificate` is deleted, you need to configure your installation to pass the `--enable-certificate-owner-ref` flag to the controller. + +## Renewal + +`cert-manager` will automatically renew issued certificates. It will calculate _when_ to renew a certificate based on certificate's duration and a 'renewBefore' value which specifies _how long_ before expiry a certificate should be renewed. + +`spec.duration` and `spec.renewBefore` fields on a `Certificate` can be used to specify custom duration and 'renewBefore' values for a certificate. Default values for these fields are 90 days and 30 days respectively. Some issuers might be configured to only issue certificates with a set duration, so the actual duration may be different. +Minimum value for `spec.duration` is 1 hour and minimum value for `spec.renewBefore` is 5 minutes. +It is also required that `spec.duration` > `spec.renewBefore` so if you set `spec.duration` to a value smaller than 30 days (720 hours) you will also need to set `spec.renewBefore` to some smaller value. + +Once a certificate has been issued, `cert-manager` will calculate _how long_ before expiry a cert should be renewed using the formula `min(spec.renewBefore, actual_duration / 3)` and use this value to calculate _when_ a certificate should be renewed. `Certifcate`'s `status.RenewalTime` field will then be set to the time when renewal will be attempted. \ No newline at end of file diff --git a/content/en/docs/usage/kube-csr.md b/content/en/docs/usage/kube-csr.md new file mode 100644 index 00000000000..de90d7746a8 --- /dev/null +++ b/content/en/docs/usage/kube-csr.md @@ -0,0 +1,125 @@ +--- +title: "Kubernetes CertificateSigningRequests" +linkTitle: "Kubernetes CertificateSigningRequests" +weight: 400 +type: "docs" +--- + +Kubernetes has an in-built +[CertificateSigningRequest](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/) +resource. This resource is similar to the cert-manager +[CertificateRequest](../../concepts/certificaterequest/) in that it is used to +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. + +#### Feature State + +This feature is currently in an _experimental_ state, and its behavior is +subject to change in further releases. + +{{% pageinfo color="warning" %}} + +⛔️ This feature is only enabled by adding it to the `--feature-gates` flag on +the cert-manager controller: + +```bash +--feature-gates=ExperimentalCertificateSigningRequestControllers=true +``` + +Which can be added using Helm: + +```bash +$ helm install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --set featureGates="ExperimentalCertificateSigningRequestControllers=true" \ + # --set installCRDs=true +``` + +> Note: cert-manager currently only supports signing CertificateSigningRequests +> using the [CA issuer](../../configuration/ca/). + +> Note: cert-manager _does not_ automatically approve CertificateSigningRequests +> that reference a cert-manager [Issuer](../../configuration/). Please refer to +> the [Kubernetes documentation](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/#request-signing-process) +> for the request process of CertificateSigningRequests. + + +{{% /pageinfo %}} + + +## Signer Name + +CertificateSigningRequests contain a +[`spec.signerName`](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/#request-signing-process) +field to reference a CA to sign the request. cert-manager Issuers or +ClusterIssuers are referenced in the following form: + +``` +.cert-manager.io/. +``` + +For example, a namespaced Issuer in the namespace `sandbox` with the name +`my-issuer` would be referenced via: + +```yaml + signerName: issuers.cert-manager.io/sandbox.my-issuer +``` + +A ClusterIssuer with the name `my-cluster-issuer` would be referenced via: + +```yaml + signerName: clusterissuers.cert-manager.io/my-cluster-issuer +``` + +### Referencing Namespaced Issuers + +Unlike CertificateRequests, CertificateSigningRequests are cluster scoped +resources. To prevent users from requesting certificates from a namespaced +Issuer in a namespace that they otherwise would not have access to, cert-manager +performs a +[SubjectAccessReview](https://kubernetes.io/docs/reference/access-authn-authz/authorization/#checking-api-access). +This review ensures that the requesting user has the permission to `reference` +the `signers` resource in the given namespace. The name should be either the +name of the Issuer, or `"*"` to reference all Issuers in that namespace. + +An example Role to give permissions to reference Issuers in the `sandbox` +namespace would look like the following: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cert-manager-referencer:my-issuer + namespace: sandbox +rules: +- apiGroups: ["cert-manager.io"] + resources: ["signers"] + verbs: ["reference"] + resourceNames: + - "my-issuer" # To give permission to _only_ reference Issuers with the name 'my-issuer' + - "*" # To give permission to reference Issuers with any name in this namespace +``` + +## Annotations + +To keep feature parity with CertificateRequests, annotations are used to store +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. + +- `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. + +- `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.