diff --git a/.spelling b/.spelling index 17697568cc2..32ede9efced 100644 --- a/.spelling +++ b/.spelling @@ -56,6 +56,7 @@ DataDog Dean-Coakley DigitalOcean Distroless +etcd EC2 ECDSA EKS @@ -79,6 +80,7 @@ HTTPRoute HashiCorp Helmfile IAM +IdP INWX IPs IPv6 @@ -94,6 +96,7 @@ KUARD Kirill-Garbar Knative Krew +kuard KubeCon Kubernetes Kyverno @@ -116,9 +119,11 @@ OperatorHub.io PEM PKCS#12 PKCS#8 +Pomerium PowerShell Prometheus RBAC +Redis RFC2136 RFC8555 RR @@ -245,6 +250,7 @@ manual-rotation-private-key mechanism metadata middleware +migrate-api-version misconfiguration misconfigured mixin @@ -257,6 +263,7 @@ namespace namespaced namespaces ndegory +oauth2 openshift-supported-versions powershell pre @@ -270,6 +277,7 @@ publicised reStructuredText rebase reissuance +reflector remediate renewBefore repo diff --git a/_redirects b/_redirects index 21d1045ad21..f515c195d66 100644 --- a/_redirects +++ b/_redirects @@ -77,3 +77,6 @@ https://docs.cert-manager.io/en/release-0.16/* https://cert-manager.io/docs/rele https://docs.cert-manager.io/en/release-* https://cert-manager.io/docs/release-notes/release-notes-:splat 301! https://docs.cert-manager.io https://cert-manager.io/docs 301! https://docs.cert-manager.io/* https://cert-manager.io/docs/:splat 302! + +# These rules handle page renames +https://cert-manager.io/docs/faq/kubed/* https://cert-manager.io/docs/faq/sync-secrets/ \ No newline at end of file diff --git a/content/en/docs/configuration/acme/_index.md b/content/en/docs/configuration/acme/_index.md index 3a155f5587b..cd27fdc497d 100644 --- a/content/en/docs/configuration/acme/_index.md +++ b/content/en/docs/configuration/acme/_index.md @@ -371,13 +371,13 @@ solvers: apiKeySecretRef: name: cloudflare-apikey-secret key: apikey -selector: - matchLabels: - 'email': 'user@example.com' - 'solver': 'cloudflare' - dnsZones: - - 'test.example.com' - - 'example.dev' + selector: + matchLabels: + 'email': 'user@example.com' + 'solver': 'cloudflare' + dnsZones: + - 'test.example.com' + - 'example.dev' ``` In this case the `DNS01` solver for CloudFlare will only be used to solve a challenge for a DNS name if the `Certificate` has a label from diff --git a/content/en/docs/configuration/acme/dns01/_index.md b/content/en/docs/configuration/acme/dns01/_index.md index 913a6a68920..91a7753f858 100644 --- a/content/en/docs/configuration/acme/dns01/_index.md +++ b/content/en/docs/configuration/acme/dns01/_index.md @@ -115,7 +115,7 @@ spec: - selector: dnsZones: - 'example.com' - - dns01: + dns01: # Valid values are None and Follow cnameStrategy: Follow route53: @@ -169,6 +169,7 @@ Links to these supported providers along with their documentation are below: - [`cert-manager-webhook-gandi`](https://github.com/bwolf/cert-manager-webhook-gandi) - [`cert-manager-webhook-infomaniak`](https://github.com/Infomaniak/cert-manager-webhook-infomaniak) - [`cert-manager-webhook-inwx`](https://gitlab.com/smueller18/cert-manager-webhook-inwx) +- [`cert-manager-webhook-linode`](https://github.com/slicen/cert-manager-webhook-linode) - [`cert-manager-webhook-oci`](https://gitlab.com/dn13/cert-manager-webhook-oci) (Oracle Cloud Infrastructure) - [`cert-manager-webhook-scaleway`](https://github.com/scaleway/cert-manager-webhook-scaleway) - [`cert-manager-webhook-selectel`](https://github.com/selectel/cert-manager-webhook-selectel) @@ -177,6 +178,7 @@ Links to these supported providers along with their documentation are below: - [`cert-manager-webhook-loopia`](https://github.com/Identitry/cert-manager-webhook-loopia) - [`cert-manager-webhook-arvan`](https://github.com/kiandigital/cert-manager-webhook-arvan) - [`bizflycloud-certmanager-dns-webhook`](https://github.com/bizflycloud/bizflycloud-certmanager-dns-webhook) +- [`cert-manager-webhook-hetzner`](https://github.com/vadimkim/cert-manager-webhook-hetzner) You can find more information on how to configure webhook providers [here](./webhook/). diff --git a/content/en/docs/configuration/external.md b/content/en/docs/configuration/external.md index 89cc2ca0ecc..3af3c8eb61b 100644 --- a/content/en/docs/configuration/external.md +++ b/content/en/docs/configuration/external.md @@ -43,6 +43,7 @@ These external issuers are known to support and honor [approval](https://cert-ma certificates signed by [FreeIPA](https://www.freeipa.org). - [ADCS Issuer](https://github.com/nokia/adcs-issuer): Requests certificates signed by [Microsoft Active Directory Certificate Service](https://docs.microsoft.com/en-us/windows-server/networking/core-network-guide/cncg/server-certs/install-the-certification-authority). +- [CFSSL Issuer](https://gerrit.wikimedia.org/r/plugins/gitiles/operations/software/cfssl-issuer/): Request certificates signed by a [CFSSL](https://github.com/cloudflare/cfssl) `multirootca` instance. ## Building New External Issuers diff --git a/content/en/docs/faq/_index.md b/content/en/docs/faq/_index.md index fa833a5a7e4..a562c68c58a 100644 --- a/content/en/docs/faq/_index.md +++ b/content/en/docs/faq/_index.md @@ -11,7 +11,7 @@ face: - [TLS Terminology, including commonly misused terms](./terminology/) - [Troubleshooting issuing ACME certificates](./acme/) - [How to change the Cluster Resource Namespace](./cluster-resource/) -- [How to sync secrets across namespaces](./kubed/) +- [How to sync secrets across namespaces](./sync-secrets/) - [Failing to create resources due to Webhook](./webhook/) ## Certificates diff --git a/content/en/docs/faq/acme.md b/content/en/docs/faq/acme.md index 2cb55686e6d..96da40ba22b 100644 --- a/content/en/docs/faq/acme.md +++ b/content/en/docs/faq/acme.md @@ -54,6 +54,7 @@ Events: * `Failed to update ACME account:400 urn:ietf:params:acme:error:invalidEmail`: the email you specified in the Issuer configuration isn't valid. * `Error initializing issuer: Failed to register ACME account: secrets "acme-key" already exists`: there might be a leftover account from a previous issuer that is no longer valid, you should remove the secret so it can be recreated. +* `Error accepting challenge: 400 urn:ietf:params:acme:error:malformed: Unable to update challenge :: authorization must be pending`: this suggests that the authorization was not in 'pending' state at a time when cert-manager sent a request to the ACME server to accept the challenge. This may be because the domain validation has already failed and the authorization has been marked as 'invalid'. Check the authorization URL on the status of the `Order` or `Challenge` to see the status of the authorization and any additional information. ## 2. Troubleshooting Orders @@ -109,6 +110,12 @@ Events: Normal OrderValid 4s cert-manager Order completed successfully ``` +You can see some additional information about the state of the [ACME authorization](https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.4) that needs to be validated as part of this order using the authorization URL from the status of the `Order`: + +```bash +$ kubectl get order -ojsonpath='{.status.authorizations[x].url}' +``` + If the Order is not completing successfully, you can debug the challenges for the Order by running `kubectl describe` on the `Challenge` resource which is described in the following steps. @@ -170,6 +177,12 @@ Status: In this example our HTTP01 check fails due a network issue. You will also see any errors coming from your DNS provider here. +You can also see some additional information about the state of the [ACME authorization](https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.4) that the challenge should validate using the authorization URL on from the status of the `Challenge`: + +```bash +$ kubectl get challenge -ojsonpath='{.spec.authorizationURL}' +``` + ### HTTP01 troubleshooting First of all check if you can see the challenge URL from the public internet, if this does not work check your Ingress and firewall configuration as well as the service and pod cert-manager created to solve the ACME challenge. If this does work check if your cluster can see it too. It is important to test this from inside a Pod. If you get a connection error it is suggested to check the cluster's network configuration. diff --git a/content/en/docs/faq/kubed.md b/content/en/docs/faq/sync-secrets.md similarity index 52% rename from content/en/docs/faq/kubed.md rename to content/en/docs/faq/sync-secrets.md index c8ecaab3301..d9fd336543e 100644 --- a/content/en/docs/faq/kubed.md +++ b/content/en/docs/faq/sync-secrets.md @@ -7,9 +7,11 @@ type: "docs" It may be required for multiple components across namespaces to consume the same `Secret` that has been created by a single `Certificate`. The recommended way to -do this is to use [kubed](https://github.com/appscode/kubed) with its [secret -syncing -feature](https://appscode.com/products/kubed/v0.11.0/guides/config-syncer/intra-cluster/). However if your use case is a wildcard certificate another approach may meet your needs. +do this is to use extensions such as: + - [reflector](https://github.com/emberstack/kubernetes-reflector) with support + for auto secret reflection + - [kubed](https://github.com/appscode/kubed) with its + [secret syncing feature](https://appscode.com/products/kubed/v0.11.0/guides/config-syncer/intra-cluster/) ## Serving a wildcard to ingress resources in different namespaces (default SSL certificate) @@ -31,9 +33,43 @@ spec: #secretName omitted to use default wildcard certificate ``` -## Syncing arbitrary secrets across namespaces using kubed -In order for the target Secret to be synced, you can use the `secretTemplate` field for annotating the generated secret with the kubed sync annotation (See [CertificateSecretTemplate]). The example below shows syncing +## Syncing arbitrary secrets across namespaces using extensions + +In order for the target Secret to be synced, you can use the `secretTemplate` field +for annotating the generated secret with the extension specific annotation (See [CertificateSecretTemplate]). + + +### Using `reflector` + The example below shows syncing a certificate's secret from the `cert-manager` namespace to multiple namespaces (i.e. `dev`, `staging`, `prod`). + Reflector will ensure that any namespace (existing or new) matching the allowed condition (with regex support) will get a copy of the certificate's secret and will keep it up to date. + You can also sync other secrets (different name) using `reflector` (consult the extension's [README](https://github.com/emberstack/kubernetes-reflector/blob/main/README.md)) + +```yaml +--- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: source + namespace: cert-manager +spec: + secretName: source-tls + commonName: source + issuerRef: + name: source-ca + kind: Issuer + group: cert-manager.io + secretTemplate: + annotations: + reflector.v1.k8s.emberstack.com/reflection-allowed: "true" + reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces: "dev,staging,prod" # Control destination namespaces + reflector.v1.k8s.emberstack.com/reflection-auto-enabled: "true" # Auto create reflection for matching namespaces + reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces: "dev,staging,prod" # Control auto-reflection namespaces +``` + + +### Using `kubed` + The example below shows syncing a certificate belonging to the `sandbox` Certificate from the `cert-manager` namespace, into the `sandbox` namespace. @@ -62,4 +98,6 @@ spec: kubed.appscode.com/sync: "cert-manager-tls=sandbox" # Sync certificate to matching namespaces ``` -[CertificateSecretTemplate]: ../../reference/api-docs/#cert-manager.io/v1.CertificateSecretTemplate \ No newline at end of file +[CertificateSecretTemplate]: ../../reference/api-docs/#cert-manager.io/v1.CertificateSecretTemplate + + diff --git a/content/en/docs/faq/webhook.md b/content/en/docs/faq/webhook.md index 60f2d020bc1..2c1cfc47392 100644 --- a/content/en/docs/faq/webhook.md +++ b/content/en/docs/faq/webhook.md @@ -1,6 +1,6 @@ --- -title: "Webhook" -linkTitle: "Webhook" +title: "Troubleshooting webhook" +linkTitle: "Troubleshooting webhook" weight: 60 type: "docs" --- @@ -10,3 +10,5 @@ and as such no cert-manager resources can be created or updated. In this case, it is advised to check the [compatibility](../../installation/compatibility/) of your environment and take necessary action outlined there. + +See more information about debugging webhook related issues [here](../../concepts/webhook/#known-problems-and-solutions). diff --git a/content/en/docs/installation/helm.md b/content/en/docs/installation/helm.md index a124b2da973..82aa2515d48 100644 --- a/content/en/docs/installation/helm.md +++ b/content/en/docs/installation/helm.md @@ -82,7 +82,7 @@ $ helm install \ --create-namespace \ --version v1.6.1 \ --set prometheus.enabled=false \ # Example: disabling prometheus using a Helm parameter - --set webhook.timeoutSeconds=4 # Example: changing the wehbook timeout using a Helm parameter + --set webhook.timeoutSeconds=4 # Example: changing the webhook timeout using a Helm parameter ``` Once you have deployed cert-manager, you can [verify](../verify/) the installation. diff --git a/content/en/docs/installation/supported-releases.md b/content/en/docs/installation/supported-releases.md index 3781589e8d9..715c27dd4c4 100644 --- a/content/en/docs/installation/supported-releases.md +++ b/content/en/docs/installation/supported-releases.md @@ -64,7 +64,7 @@ Note that dates in the future are uncertain and might change. [0.11]: https://cert-manager.io/docs/release-notes/release-notes-0.11 You can find available releases on the [releases -page](https://github.com/cert-manager/cert-manager/releases). You can find +page](https://github.com/jetstack/cert-manager/releases). You can find the release notes for each minor release [here](https://cert-manager.io/docs/release-notes/), and the upgrade instructions are @@ -173,7 +173,7 @@ possible. [#2857]: https://github.com/jetstack/cert-manager/issues/2857 "CloudDNS DNS01 challenge crashes cert-manager" [#4142]: https://github.com/jetstack/cert-manager/issues/4142 "Cannot issue a certificate that has the same subject and issuer" [#3444]: https://github.com/jetstack/cert-manager/issues/3444 "Certificates do not get immediately updated after updating them" -[#3882]: https://github.com/jetstack/cert-manager/pull/3882: "Helm upgrade from v1.2 to v1.2 impossible due to a Helm bug" +[#3882]: https://github.com/jetstack/cert-manager/pull/3882 "Certificate's revision history limit validated by webhook" [#3644]: https://github.com/jetstack/cert-manager/issues/3644 "Helm upgrade from v1.2 to v1.2 impossible due to a Helm bug" @@ -183,22 +183,16 @@ The list of supported Kubernetes versions displayed in the [Supported Releases](#supported-releases) section depends on what the cert-manager maintainers think is reasonable to support and to test. -As of 16 Dec 2021, our testing coverage is: +As of 6th January 2022, our testing coverage is: | Release branch | Prow configuration | Dashboard | Kubernetes versions tested | Periodicity | |:--------------:|:------------------------------|:--------------------------|:--------------------------:|:-------------:| -| PRs | [`presubmits.yaml`][] | [`presubmits-blocking`][] | 1.22 | On each PR | +| PRs | [`presubmits.yaml`][] | [`presubmits-blocking`][] | 1.23 | On each PR | | master | [`periodics.yaml`][] | [`master`][] | 1.18 → 1.23 | Every 2 hours | -| release-1.7 | n/a\* | n/a | n/a | n/a | -| release-1.6 | [`previous-periodics.yaml`][] | [`previous`][] | 1.18 → 1.23 | Every 2 hours | +| release-1.7 | [`next-periodics.yaml`][] | [`next`][] | 1.18 → 1.23 | Every 2 hours | +| release-1.6 | [`previous-periodics.yaml`][] | [`previous`][] | 1.18 → 1.22 | Every 2 hours | | release-1.5 | n/a | | n/a | n/a | -\*The release-1.7 is currently equal to release-1.6; we decided to disable the -periodic tests until we release `1.7.0-alpha.0`. The disabling of the periodic -tests was performed in the [testing PR -606](https://github.com/jetstack/testing/pull/606). This note should be removed -as soon as we release `1.7.0-alpha.0`. - [`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 [`next-periodics.yaml`]: https://github.com/jetstack/testing/blob/master/config/jobs/cert-manager/release-next/cert-manager-release-next-periodics.yaml @@ -208,8 +202,7 @@ as soon as we release `1.7.0-alpha.0`. [`next`]: https://testgrid.k8s.io/jetstack-cert-manager-next [`previous`]: https://testgrid.k8s.io/jetstack-cert-manager-previous -The oldest Kubernetes release supported by cert-manager is 1.16, as we want -to be supporting most commercial Kubernetes offerings. +The oldest Kubernetes release supported by cert-manager is currently 1.18. | Vendor | Oldest Kubernetes Release\* | Other Old\*\* Kubernetes Releases | |:-----------------:|-----------------------------|---------------------------------------------------------------| @@ -218,7 +211,7 @@ to be supporting most commercial Kubernetes offerings. | [AKS][aks] | 1.19 (EOL Jan 2022) | 1.20 (EOL Feb 2022) | | [OpenShift 4][os] | 1.18 (4.5, EOL July 2021) | 1.19 (4.6 EUS, EOL May 2022) | -\*Oldest release relevant to the next cert-manager release, as of 2021-11-19 +\*Oldest release relevant to the next cert-manager release, as of 2022-01-06 \*\*We say that a Kubernetes offering is "old" when it is not supported upstream as per the [Version Skew diff --git a/content/en/docs/installation/upgrading/remove-deprecated-apis.md b/content/en/docs/installation/upgrading/remove-deprecated-apis.md index ae366d89051..837ac94749f 100644 --- a/content/en/docs/installation/upgrading/remove-deprecated-apis.md +++ b/content/en/docs/installation/upgrading/remove-deprecated-apis.md @@ -1,11 +1,11 @@ --- -title: "Removing Deprecated API Resources" -linkTitle: "Removing Deprecated API Resources" +title: "Migrating Deprecated API Resources" +linkTitle: "Migrating Deprecated API Resources" weight: 20 type: "docs" --- -We have deprecated the following cert-manager APIs: +The following cert-manager APIs were deprecated in cert-manager `v1.4`: - `cert-manager.io/v1alpha2` - `cert-manager.io/v1alpha3` @@ -14,37 +14,18 @@ We have deprecated the following cert-manager APIs: - `acme.cert-manager.io/v1alpha3` - `acme.cert-manager.io/v1beta1` -These APIs were 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'll need to upgrade your cert-manager custom resources and CRDs. This needs to be done before upgrading to cert-manager `v1.6.0`. +These APIs are no longer served in cert-manager 1.6 and are fully removed in cert-manager 1.7. If you have a cert-manager installation that is using or has previously used these deprecated APIs you might need to upgrade your cert-manager custom resources and CRDs. This should be done before upgrading to cert-manager 1.6 or later. -## Upgrading existing cert-manager resources +{{% alert title="Note" color="warning" %}} +An earlier version of this document listed a number of kubectl commands to run to migrate resources. These steps have now been encoded in [`cmctl upgrade migrate-api-version` command](https://cert-manager.io/docs/usage/cmctl/#migrate-api-version). If you have already run the kubectl commands, your resources should have been migrated and there should be no need to also run the `cmctl` command. However, if you are not sure, you can still run the `cmctl` command as well- it will be a no-op if no actions are needed. +{{% /alert %}} -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: +# Upgrading existing cert-manager resources -```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 +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. -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 +2. Make sure your cert-manager deployment is currently at version `v1.0` or later. -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 +3. Make sure that any cert-manager custom resource manifests that refer to the deprecated APIs are updated to use the `cert-manager.io/v1` API and re-applied. You can use the [cmctl convert command](https://cert-manager.io/docs/usage/cmctl/#convert)to convert manifests. -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 -``` +4. Run the command [`cmctl upgrade migrate-api-version`](https://cert-manager.io/docs/usage/cmctl/#migrate-api-version). It automates the steps described in [Upgrade existing objects to a new stored version](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#upgrade-existing-objects-to-a-new-stored-version). diff --git a/content/en/docs/tutorials/_index.md b/content/en/docs/tutorials/_index.md index dedf6cb860e..71ecdca346c 100644 --- a/content/en/docs/tutorials/_index.md +++ b/content/en/docs/tutorials/_index.md @@ -10,7 +10,8 @@ for you to learn from. Take a look! - [Backup and Restore Resources](./backup/): Backup the cert-manager resources in your cluster and then restore them. -- [Securing Ingresses with NGINX-Ingress and cert-manager](./acme/ingress/): Tutorial for deploying NGINX into your +- [Pomerium Ingress](./acme/pomerium-ingress/): Tutorial on using the Pomerium Ingress Controller with cert-manager. +- [Securing Ingresses with NGINX-Ingress and cert-manager](./acme/nginx-ingress/): Tutorial for deploying NGINX into your cluster and securing incoming connections with a certificate from Let's Encrypt. - [Issuing an ACME Certificate using DNS Validation](./acme/dns-validation/): Tutorial on how to resolve DNS ownership validation using DNS01 challenges. diff --git a/content/en/docs/tutorials/acme/example/pomerium-certificates.yaml b/content/en/docs/tutorials/acme/example/pomerium-certificates.yaml new file mode 100644 index 00000000000..7e07111417d --- /dev/null +++ b/content/en/docs/tutorials/acme/example/pomerium-certificates.yaml @@ -0,0 +1,36 @@ +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: pomerium-cert + namespace: pomerium +spec: + secretName: pomerium-tls + issuerRef: + name: pomerium-issuer + kind: Issuer + usages: + - server auth + - client auth + dnsNames: + - pomerium-proxy.pomerium.svc.cluster.local + - pomerium-authorize.pomerium.svc.cluster.local + - pomerium-databroker.pomerium.svc.cluster.local + - pomerium-authenticate.pomerium.svc.cluster.local +--- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: pomerium-redis-cert + namespace: pomerium +spec: + secretName: pomerium-redis-tls + issuerRef: + name: pomerium-issuer + kind: Issuer + usages: + - server auth + - client auth + dnsNames: + - pomerium-redis-master.pomerium.svc.cluster.local + - pomerium-redis-headless.pomerium.svc.cluster.local + - pomerium-redis-replicas.pomerium.svc.cluster.local diff --git a/content/en/docs/tutorials/acme/example/pomerium-production-issuer.yaml b/content/en/docs/tutorials/acme/example/pomerium-production-issuer.yaml new file mode 100644 index 00000000000..5cedb91f068 --- /dev/null +++ b/content/en/docs/tutorials/acme/example/pomerium-production-issuer.yaml @@ -0,0 +1,18 @@ +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: letsencrypt-prod +spec: + acme: + # The ACME server URL + server: https://acme-v02.api.letsencrypt.org/directory + # Email address used for ACME registration + email: user@example.com + # Name of a secret used to store the ACME account private key + privateKeySecretRef: + name: letsencrypt-prod + # Enable the HTTP-01 challenge provider + solvers: + - http01: + ingress: + class: pomerium \ No newline at end of file diff --git a/content/en/docs/tutorials/acme/example/pomerium-staging-issuer.yaml b/content/en/docs/tutorials/acme/example/pomerium-staging-issuer.yaml new file mode 100644 index 00000000000..54862cd3451 --- /dev/null +++ b/content/en/docs/tutorials/acme/example/pomerium-staging-issuer.yaml @@ -0,0 +1,18 @@ +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: letsencrypt-staging +spec: + acme: + # The ACME server URL + server: https://acme-staging-v02.api.letsencrypt.org/directory + # Email address used for ACME registration + email: user@example.com + # Name of a secret used to store the ACME account private key + privateKeySecretRef: + name: letsencrypt-staging + # Enable the HTTP-01 challenge provider + solvers: + - http01: + ingress: + class: pomerium \ No newline at end of file diff --git a/content/en/docs/tutorials/acme/example/pomerium-values.yaml b/content/en/docs/tutorials/acme/example/pomerium-values.yaml new file mode 100644 index 00000000000..2460377547d --- /dev/null +++ b/content/en/docs/tutorials/acme/example/pomerium-values.yaml @@ -0,0 +1,39 @@ +authenticate: + existingTLSSecret: pomerium-tls + idp: + provider: "google" + clientID: YOUR_CLIENT_ID + clientSecret: YOUR_SECRET + serviceAccount: YOUR_SERVICE_ACCOUNT + ingress: + annotations: + cert-manager.io/issuer: letsencrypt-staging + tls: + secretName: authenticate.localhost.pomerium.io-tls + +proxy: + existingTLSSecret: pomerium-tls + +databroker: + existingTLSSecret: pomerium-tls + storage: + clientTLS: + existingSecretName: pomerium-redis-tls + existingCASecretKey: ca.crt + +authorize: + existingTLSSecret: pomerium-tls + +redis: + enabled: true + generateTLS: false + tls: + certificateSecret: pomerium-redis-tls + +ingressController: + enabled: true + +config: + rootDomain: localhost.pomerium.io #Change this to your reserved domain space. + existingCASecret: pomerium-tls + generateTLS: false # On by default, disabled when cert-manager or another solution is in place. diff --git a/content/en/docs/tutorials/acme/ingress.md b/content/en/docs/tutorials/acme/nginx-ingress.md similarity index 100% rename from content/en/docs/tutorials/acme/ingress.md rename to content/en/docs/tutorials/acme/nginx-ingress.md diff --git a/content/en/docs/tutorials/acme/pomerium-ingress.md b/content/en/docs/tutorials/acme/pomerium-ingress.md new file mode 100644 index 00000000000..64580505601 --- /dev/null +++ b/content/en/docs/tutorials/acme/pomerium-ingress.md @@ -0,0 +1,280 @@ +--- +title: "Pomerium Ingress" +linkTitle: "Pomerium Ingress" +weight: 50 +type: "docs" +--- + +This tutorial covers installing the [Pomerium Ingress Controller](https://pomerium.com/docs/k8s/ingress.html) and securing it with cert-manager. [Pomerium](https://pomerium.com) is an identity-aware proxy that can also provide a custom ingress controller for your Kubernetes services. + +## Prerequisites + +1. Install [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) and set the context to the cluster you'll be working with. + +1. Install Helm on your local computer. See [Installing Helm](https://helm.sh/docs/intro/install/) for the best installation method for your operating system. + +1. Pomerium connects to an identity provider (**IdP**) to authenticate users. See one of their [guides](https://www.pomerium.com/docs/identity-providers/) to learn how to set up your IdP of choice to provide oauth2 validation. + +1. This tutorial assumes you have a domain space reserved for this cluster (such as `*.cluster.example.com`). You will need access to DNS for this domain to assign A and CNAME records as needed. + +## Install cert-manager + +1. Create a namespace for cert-manager: + + ```bash + kubectl create namespace cert-manager + ``` + +1. Add the `jetstack` repository and update Helm: + + ```bash + helm repo add jetstack https://charts.jetstack.io + helm repo update + ``` + +1. Install cert-manager to your cluster: + + ```bash + helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace \ + --set installCRDs=true + ``` + +1. Confirm deployment with `kubectl get pods --namespace cert-manager`: + + ```bash + kubectl get pods --namespace cert-manager + NAME READY STATUS RESTARTS AGE + cert-manager-5d7f97b46d-8g942 1/1 Running 0 33s + cert-manager-cainjector-69d885bf55-6x5v2 1/1 Running 0 33s + cert-manager-webhook-8d7495f4-s5s6p 1/1 Running 0 33s + ``` + +## Configure a Private Certificate Issuer + +For secure communication between Pomerium services, create a private certificate issuer. This issuer will reside in the `pomerium` namespace, which we will use when creating the Ingress Controller. The certificates issued will only be used for communication between Pomerium components. + +1. Define an issuer in the file `pomerium-issuer.yaml`: + + ```yaml + apiVersion: cert-manager.io/v1 + kind: Issuer + metadata: + name: pomerium-ca + namespace: pomerium + spec: + selfSigned: {} + --- + apiVersion: cert-manager.io/v1 + kind: Certificate + metadata: + name: pomerium-ca + namespace: pomerium + spec: + isCA: true + secretName: pomerium-ca + commonName: pomerium ca + issuerRef: + name: pomerium-ca + kind: Issuer + --- + apiVersion: cert-manager.io/v1 + kind: Issuer + metadata: + name: pomerium-issuer + namespace: pomerium + spec: + ca: + secretName: pomerium-ca + ``` + +1. Deploy the issuer: + + ```bash + kubectl apply -f pomerium-issuer.yaml + ``` + +## Configure Let's Encrypt Issuer + +For communication between the Ingresses and the internet, we'll want to use certificates signed by a trusted certificate authority like Let's Encrypt. This example creates two Let's Encrypt issuers, one for staging and one for production. + +The Let's Encrypt production issuer has [strict rate limits](https://letsencrypt.org/docs/rate-limits/). Before your configuration is finalized you may have to recreate services several times, hitting those limits. It's easy to confuse rate limiting with errors in configuration or operation while building your stack. + +Because of this, we will start with the Let's Encrypt staging issuer. Once your configuration is all but finalized, we will switch to a production issuer. Both of these issuers are configured to use the [`HTTP01`](../../../configuration/acme/http01/) challenge provider. +
    +
  1. + +The following YAML defines a staging certificate issuer. You must update the email address to your own. The `email` field is required by Let's Encrypt and used to notify you of certificate expiration and updates. + +{{% include file="../example/pomerium-staging-issuer.yaml" language="yaml" %}} + +You can download and edit the example and apply it with `kubectl apply -f`, or edit, and apply the custom resource in one command: + +```bash +kubectl create --edit -f https://cert-manager.io/docs/tutorials/acme/example/pomerium-staging-issuer.yaml +``` +
    2. +
  2. + +Create a production issuer and deploy it. As with the staging issuer, update this example with your own email address: + +{{% include file="../example/pomerium-production-issuer.yaml" language="yaml" %}} + +```bash +kubectl create --edit -f https://cert-manager.io/docs/tutorials/acme/example/pomerium-production-issuer.yaml +``` +
    3. +
+ +You can confirm on the status of the issuers after you create them: + +```bash +kubectl describe issuer letsencrypt-staging +kubectl describe issuer letsencrypt-prod +``` + +You should see the issuer listed with a registered account. + + +## Install The Pomerium Ingress Controller + +
    +
  1. + +Set your `kubectl` context to the Pomerium namespace: + +```bash +kubectl config set-context --current --namespace=pomerium +``` + +
  2. + +Create certificate configurations for Pomerium. Our example is named `pomerium-certificates.yaml`: + +{{% include file="../example/pomerium-certificates.yaml" language="yaml" %}} + +Replace `localhost.pomerium.io` with the domain name you'll assign to the Ingress. Keep the subdomain `authenticate`. + +This example defines 2 certificates: + - One using the self-signed `pomerium-issuer` to encrypt traffic between Pomerium's services, + - One using the self-signed `pomerium-issuer` to encrypt traffic to and from the Redis service(s) used by Pomerium. + +Additional certificates will be issued as new Ingresses are created. +
  3. + +Apply the certificate configuration, and confirm: + +```bash +kubectl apply -f pomerium-certificates.yaml +``` + +```bash +kubectl get certificate +NAME READY SECRET AGE +pomerium-ca True pomerium-ca 10s +pomerium-cert True pomerium-tls 10s +pomerium-redis-cert True pomerium-redis-tls 10s +``` + +
  4. + +Create a values file for Helm to use when installing Pomerium. Our example is named `pomerium-values.yaml`. + +{{% include file="../example/pomerium-values.yaml" language="yaml" %}} + +The options required in the `authenticate.idp` block will vary depending on your identity provider. + +Update `config.rootDomain` to match your domain space. + +
  5. + +Add Pomerium's Helm repo: + +```bash +helm repo add pomerium https://helm.pomerium.io +``` + +
  6. + +Install Pomerium to the cluster: + +```bash +helm upgrade --install pomerium pomerium/pomerium --values ./pomerium-values.yaml +``` + +
  7. + +Use `kubectl` to confirm that the Pomerium Proxy has stood up, and get the external IP needed to route your domain space to the cluster: + +```bash +kubectl get svc pomerium-proxy +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +pomerium-proxy LoadBalancer 10.128.117.25 192.0.2.20 443:30006/TCP,9090:30707/TCP 2m37s +``` + +
+ +## Define a Test Service + +To test our new Ingress Controller, we will add the [kuard](https://github.com/kubernetes-up-and-running/kuard) app to our cluster and define an Ingress for it. + +
  1. + +Define the kuard deployment and associated service: + +{{% include file="../example/deployment.yaml" language="yaml" %}} + +{{% include file="../example/service.yaml" language="yaml" %}} + +You can download and reference these files locally, or you can reference them from the GitHub source repository for this documentation. + +To install the example service from the tutorial files straight from GitHub: + +```bash +kubectl apply -f https://cert-manager.io/docs/tutorials/acme/example/deployment.yaml +kubectl apply -f https://netlify.cert-manager.io/docs/tutorials/acme/example/service.yaml +``` +
  2. + +Create a new Ingress manifest (`example-ingress.yaml`) for our test service: + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: kuard + annotations: + cert-manager.io/issuer: letsencrypt-staging + ingress.pomerium.io/policy: '[{"allow":{"and":[{"domain":{"is":"example.com"}}]}}]' +spec: + ingressClassName: pomerium + rules: + - host: kuard.localhost.pomerium.io + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: kuard + port: + number: 80 + tls: + - hosts: + - kuard.localhost.pomerium.io + secretName: kuard.localhost.pomerium.io-tls +``` + +Again, change the references to `localhost.pomerium.io` to match your domain space. + +
  3. + +Apply the Ingress manifest to the cluster: + + ```bash + kubectl apply -f example-ingress.yaml + ``` +
+ +The Pomerium Ingress Controller will use cert-manager to automatically provision a certificate from the `letsencrypt-staging` issuer for the route to `kuard.localhost.pomerium.io`. + +Once you've configured all your application services correctly in the cluster, adjust the issuer for your Ingresses (including the Authenticate service) to use `letsencrypt-prod`. diff --git a/content/en/docs/usage/cmctl.md b/content/en/docs/usage/cmctl.md index 2bca236ca96..328d76da144 100644 --- a/content/en/docs/usage/cmctl.md +++ b/content/en/docs/usage/cmctl.md @@ -49,6 +49,7 @@ Available Commands: inspect Get details on certificate related resources renew Mark a Certificate for manual renewal status Get details on current status of cert-manager resources + upgrade Tools that assist in upgrading cert-manager version Print the cert-manager CLI version and the deployed cert-manager version Flags: @@ -250,3 +251,22 @@ signed certificate to the local file `.crt`, or specified by `-c, ```bash $ cmctl x create csr -f my-cert.yaml my-req -w ``` + +#### Upgrade + +Tools that assist in upgrading cert-manager + +```bash +$ cmctl upgrade --help +``` +##### Migrate API version + +This command can be used to prepare a cert-manager installation that was created +before cert-manager `v1` for upgrading to a cert-manager version `v1.6` or later. +It ensures that any cert-manager custom resources that may have been stored in etcd at +a deprecated API version get migrated to `v1`. See [Migrating Deprecated API +Resources](https://cert-manager.io/docs/installation/upgrading/remove-deprecated-apis) for more context. + +```bash +$ cmctl upgrade migrate-api-version --qps 5 --burst 10 +``` diff --git a/content/en/docs/usage/ingress.md b/content/en/docs/usage/ingress.md index a316d68428a..7717dc2c747 100644 --- a/content/en/docs/usage/ingress.md +++ b/content/en/docs/usage/ingress.md @@ -60,7 +60,7 @@ trigger Certificate resources to be automatically created: Ingress resides, as ClusterIssuers are non-namespaced resources. - `cert-manager.io/issuer-kind`: the kind of the external issuer resource, for - example `AWSPCACIssuer`. This is only necessary for out-of-tree issuers. + example `AWSPCAIssuer`. This is only necessary for out-of-tree issuers. - `cert-manager.io/issuer-group`: the API group of the external issuer controller, for example `awspca.cert-manager.io`. This is only necessary for diff --git a/content/en/docs/usage/kubectl-plugin.md b/content/en/docs/usage/kubectl-plugin.md index e2347aff00c..aeefdc1b4aa 100644 --- a/content/en/docs/usage/kubectl-plugin.md +++ b/content/en/docs/usage/kubectl-plugin.md @@ -15,6 +15,8 @@ While the kubectl plugin is supported, it is recommended to use ## Installation You need the `kubectl-cert-manager.tar.gz` file for the platform you're using, these can be found on our [GitHub releases page](https://github.com/jetstack/cert-manager/releases). In order to use the kubectl plugin you need its binary to be accessible under the name `kubectl-cert_manager` in your `$PATH`. + +### macOS/Linux Run the following commands to set up the plugin: ```console $ curl -L -o kubectl-cert-manager.tar.gz https://github.com/jetstack/cert-manager/releases/latest/download/kubectl-cert_manager-linux-amd64.tar.gz @@ -22,6 +24,12 @@ $ tar xzf kubectl-cert-manager.tar.gz $ sudo mv kubectl-cert_manager /usr/local/bin ``` +### Windows +1. Download the [latest version](https://github.com/jetstack/cert-manager/releases/latest/download/kubectl-cert_manager-windows-amd64.tar.gz). +2. Extract the archive. +3. Add the `.exe` file extension to the extracted `kubectl-cert_manager`. +4. Copy `kubectl-cert_manager.exe` to a location which is also in your `PATH`. + You can run `kubectl cert-manager help` to test the plugin is set up properly: ```console $ kubectl cert-manager help