From 63d12c5d04c9a43abfe827a7d6ec81f7ba54e521 Mon Sep 17 00:00:00 2001 From: sdarwin Date: Tue, 10 Dec 2024 14:58:41 -0700 Subject: [PATCH] General review/proofreading Signed-off-by: sdarwin --- content/docs/configuration/acme/README.md | 7 +++++++ content/docs/configuration/acme/dns01/route53.md | 2 +- content/docs/installation/best-practice.md | 2 +- content/docs/troubleshooting/acme.md | 4 ++-- content/docs/trust/trust-manager/README.md | 2 +- .../tutorials/acme/migrating-from-kube-lego.md | 4 ++-- content/docs/tutorials/acme/nginx-ingress.md | 2 +- .../docs/tutorials/certificate-defaults/README.md | 2 +- .../README.md | 3 ++- .../getting-started-with-trust-manager/README.md | 4 ++-- content/docs/usage/csi.md | 6 +++--- content/docs/usage/gateway.md | 2 +- content/docs/usage/ingress.md | 15 ++++++++++----- 13 files changed, 34 insertions(+), 21 deletions(-) diff --git a/content/docs/configuration/acme/README.md b/content/docs/configuration/acme/README.md index 47eb22c9ee3..8e2fba4c4f7 100644 --- a/content/docs/configuration/acme/README.md +++ b/content/docs/configuration/acme/README.md @@ -60,6 +60,13 @@ spec: server: https://acme-staging-v02.api.letsencrypt.org/directory privateKeySecretRef: # Secret resource that will be used to store the account's private key. + # This is your identity with your ACME provider. Any secret name + # may be chosen. It will be populated with data automatically, + # so generally nothing further needs to be done with + # the secret. If you lose this identity/secret, you will be able to + # generate a new one and generate certificates for any/all domains + # managed using your previous account, but you will be unable to revoke + # any certificates generated using that previous account. name: example-issuer-account-key # Add a single challenge solver, HTTP01 using nginx solvers: diff --git a/content/docs/configuration/acme/dns01/route53.md b/content/docs/configuration/acme/dns01/route53.md index ec5a2a8006f..6815dcf0ab6 100644 --- a/content/docs/configuration/acme/dns01/route53.md +++ b/content/docs/configuration/acme/dns01/route53.md @@ -387,7 +387,7 @@ Here's how to set it up: - `` name of the `ServiceAccount` object. - `` namespace of the `ServiceAccount` object. - - `` name of cert-managers `ServiceAccount` object, as created during cert-manager installation. + - `` name of cert-manager's `ServiceAccount` object, as created during cert-manager installation. - `` namespace that cert-manager is deployed into. 4. **Create an Issuer or ClusterIssuer** diff --git a/content/docs/installation/best-practice.md b/content/docs/installation/best-practice.md index 20a65fe1975..0aed7b4e28b 100644 --- a/content/docs/installation/best-practice.md +++ b/content/docs/installation/best-practice.md @@ -256,7 +256,7 @@ By default the cert-manager webhook Deployment has 1 replica, but in production If the cert-manager webhook is unavailable, all API operations on cert-manager custom resources will fail, and this will disrupt any software that creates, updates or deletes cert-manager custom resources (including cert-manager itself), and it may cause other disruptions to your cluster. -So it is *especially* important to keep at multiple replicas of the cert-manager webhook running at all times. +So it is *especially* important to keep multiple replicas of the cert-manager webhook running at all times. > ℹī¸ By contrast, if there is only a single replica of the cert-manager controller, there is less risk of disruption. > For example, if the Node hosting the single cert-manager controller manager Pod is drained, diff --git a/content/docs/troubleshooting/acme.md b/content/docs/troubleshooting/acme.md index c8b527b1cfd..ca5118eb4d7 100644 --- a/content/docs/troubleshooting/acme.md +++ b/content/docs/troubleshooting/acme.md @@ -61,7 +61,7 @@ Events: ## 2. Troubleshooting Orders -When we run a describe on the `CertificateRequest` resource we see that an `Order` that has +When we run a describe on the `CertificateRequest` resource we see that an `Order` has been created: ```bash @@ -207,7 +207,7 @@ If your challenge self-check fails with a 404 not found error. Make sure to chec * use `kubectl describe ingress` to check the status of the HTTP01 solver ingress. (unless you use `acme.cert-manager.io/http01-edit-in-place`, then check the same ingress as your domain) ### DNS01 troubleshooting -If you see no error events about your DNS provider you can check the following +If you see no error events about your DNS provider you can check the following. Check if you can see the `_acme_challenge.domain` TXT DNS record from the public internet, or in your DNS provider's interface. cert-manager will check if a DNS record has been propagated by querying the cluster's DNS solver. If you are able to see it from the public internet but not from inside the cluster you might want to change [the DNS server for self-check](../configuration/acme/dns01/README.md#setting-nameservers-for-dns01-self-check) as some cloud providers overwrite DNS internally. diff --git a/content/docs/trust/trust-manager/README.md b/content/docs/trust/trust-manager/README.md index 68d1ebea586..6777c66f712 100644 --- a/content/docs/trust/trust-manager/README.md +++ b/content/docs/trust/trust-manager/README.md @@ -31,7 +31,7 @@ install trust-manager. ## Usage -trust-manager is intentionally simple, adding just one new Kubernetes `CustomResourceDefintion`: `Bundle`. +trust-manager is intentionally simple, adding just one new Kubernetes `CustomResourceDefinition`: `Bundle`. A `Bundle` represents a set of X.509 certificates that should be distributed across a cluster. diff --git a/content/docs/tutorials/acme/migrating-from-kube-lego.md b/content/docs/tutorials/acme/migrating-from-kube-lego.md index 84992cb0fbd..7623c01a456 100644 --- a/content/docs/tutorials/acme/migrating-from-kube-lego.md +++ b/content/docs/tutorials/acme/migrating-from-kube-lego.md @@ -6,7 +6,7 @@ description: 'cert-manager tutorials: Migrating from kube-lego' [kube-lego](https://github.com/jetstack/kube-lego) is an older Jetstack project for obtaining TLS certificates from Let's Encrypt (or another ACME server). -Since cert-managers release, kube-lego has been gradually deprecated in favor +Since cert-manager's release, kube-lego has been gradually deprecated in favor of this project. There are a number of key differences between the two: | Feature | kube-lego | cert-manager | @@ -229,4 +229,4 @@ I1025 21:54:02.869269 1 sync.go:206] Certificate my-example-certificate sc ``` Here we can see cert-manager has verified the existing TLS certificate and -scheduled it to be renewed in 292 hours time. \ No newline at end of file +scheduled it to be renewed in 292 hours time. diff --git a/content/docs/tutorials/acme/nginx-ingress.md b/content/docs/tutorials/acme/nginx-ingress.md index c7cf9f1568e..55e931a2116 100644 --- a/content/docs/tutorials/acme/nginx-ingress.md +++ b/content/docs/tutorials/acme/nginx-ingress.md @@ -107,7 +107,7 @@ sample deployment and an associated service: ```yaml file=./example/service.yaml ``` -You can create download and reference these files locally, or you can +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, do the following: diff --git a/content/docs/tutorials/certificate-defaults/README.md b/content/docs/tutorials/certificate-defaults/README.md index e14febf9c85..3a5fd0468bb 100644 --- a/content/docs/tutorials/certificate-defaults/README.md +++ b/content/docs/tutorials/certificate-defaults/README.md @@ -531,7 +531,7 @@ To instead only need to specify the configuration important to them, for example ``` 🔗 `cert-test-minimal.yaml` -With this policy we achieved our objective and have enabled users to submit minimal `Certifiate` resources. +With this policy we achieved our objective and have enabled users to submit minimal `Certificate` resources. This completes our fifth [use case](#use-cases), with only a single field contained within the specification, the `dnsNames` entry. Every other specified field was automatically defaulted using Kyverno with `ClusterPolicy` which would typically be setup by a platform administrator. diff --git a/content/docs/tutorials/getting-started-with-cert-manager-on-google-kubernetes-engine-using-lets-encrypt-for-ingress-ssl/README.md b/content/docs/tutorials/getting-started-with-cert-manager-on-google-kubernetes-engine-using-lets-encrypt-for-ingress-ssl/README.md index 6ba62a3d528..8d727ae8ec9 100644 --- a/content/docs/tutorials/getting-started-with-cert-manager-on-google-kubernetes-engine-using-lets-encrypt-for-ingress-ssl/README.md +++ b/content/docs/tutorials/getting-started-with-cert-manager-on-google-kubernetes-engine-using-lets-encrypt-for-ingress-ssl/README.md @@ -235,6 +235,7 @@ metadata: # This tells Google Cloud to create an External Load Balancer to realize this Ingress kubernetes.io/ingress.class: gce # This enables HTTP connections from Internet clients + # Since "true" is the default, does not need to be set. kubernetes.io/ingress.allow-http: "true" # This tells Google Cloud to associate the External Load Balancer with the static IP which we created earlier kubernetes.io/ingress.global-static-ip-name: web-ip @@ -277,7 +278,7 @@ At this point we have a Google load balancer which is forwarding HTTP traffic to > configured and for Internet clients to be routed to your web server. > Refer to the [Troubleshooting](#troubleshooting) section if it takes longer. > -> 🔰 Read about how to [Use a static IP addresses for HTTP(S) load balancers via Ingress annotation](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress-xlb#static_ip_addresses_for_https_load_balancers). +> 🔰 Read about how to [Use static IP addresses for HTTP(S) load balancers via Ingress annotation](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress-xlb#static_ip_addresses_for_https_load_balancers). > > 🔰 Read a [Summary of external Ingress annotations for GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/load-balance-ingress#summary_of_external_ingress_annotations). > diff --git a/content/docs/tutorials/getting-started-with-trust-manager/README.md b/content/docs/tutorials/getting-started-with-trust-manager/README.md index afeec714f1b..bc5eafaff63 100644 --- a/content/docs/tutorials/getting-started-with-trust-manager/README.md +++ b/content/docs/tutorials/getting-started-with-trust-manager/README.md @@ -188,7 +188,7 @@ trusted `ca-certificates.crt` is present. lrwxrwxrwx 1 root root 26 Apr 14 15:12 ca-certificates.crt -> ..data/ca-certificates.crt ``` - Note that normally this container image the output would look something + Note that normally the output would look something like the following, when there is no volume overriding this directory: ``` @@ -242,7 +242,7 @@ having to pass the additional `--cacert` flag: Based on the example above, Kubernetes is able to mount over the top of the default CA certificate bundle. You can use this with applications assuming you -know where the default locations they retrieve CA certificates from. +know the default locations from where they retrieve CA certificates. For example with `Go` your application is configurable with either `SSL_CERT_FILE` or `SSL_CERT_DIR` to point to the default CA certificate diff --git a/content/docs/usage/csi.md b/content/docs/usage/csi.md index a05b6017eee..1fa029c842b 100644 --- a/content/docs/usage/csi.md +++ b/content/docs/usage/csi.md @@ -17,7 +17,7 @@ certificate will be unique to each Pod and will be stored on disk to the node that the Pod is scheduled to. The life cycle of the certificate key pair matches that of the Pod; the certificate is issued -when the Pod is creation, and destroyed during termination. +when the Pod is created, and destroyed during termination. This driver also handles renewal of live certificates on the fly. @@ -70,8 +70,8 @@ node, containing that Pods information as well as the attributes detailed from the in-line volume attributes. From this, the driver will generate a private key as well as a certificate request based upon that key using information built from the volume attributes. The driver will create a `CertificateRequest` -resource in the same namespace in the Pod that, if valid, cert-manager will -return a signed certificate. +resource in the same namespace as the Pod. If the request is valid, cert-manager +will return a signed certificate. The resulting signed certificate and generated key will be written to that node's file system to be mounted to the Pods file system. Since the driver needs diff --git a/content/docs/usage/gateway.md b/content/docs/usage/gateway.md index 87e51c471ea..2069ecb68c0 100644 --- a/content/docs/usage/gateway.md +++ b/content/docs/usage/gateway.md @@ -152,7 +152,7 @@ meet the following requirements: | Field | Requirement | |--------------------------------|-------------------------------------------------------------| -| `tls.hostname` | Must not be empty. | +| `hostname` | Must not be empty. | | `tls.mode` | Must be set to `Terminate`. `Passthrough` is not supported. | | `tls.certificateRef.name` | Cannot be left empty. | | `tls.certificateRef.kind` | If specified, must be set to `Secret`. | diff --git a/content/docs/usage/ingress.md b/content/docs/usage/ingress.md index cc1b9fc04a4..b9c9a56c449 100644 --- a/content/docs/usage/ingress.md +++ b/content/docs/usage/ingress.md @@ -187,10 +187,11 @@ Besides the annotation, it is necessary that each ingress possess a unique `tls. The ingress-shim sub-component is deployed automatically as part of installation. -If you would like to use the old -[kube-lego](https://github.com/jetstack/kube-lego) `kubernetes.io/tls-acme: -"true"` annotation for fully automated TLS, you will need to configure a default -`Issuer` when deploying cert-manager. This can be done by adding the following +The old [kube-lego](https://github.com/jetstack/kube-lego) `kubernetes.io/tls-acme: "true"` +annotation is an alternate method to fully automated TLS. +If this annotation is set, the other annotations are not needed, +but in order to use it you will need to configure a default Issuer when deploying cert-manager. +This can be done by adding the following `--set` when deploying using Helm: ```bash @@ -212,7 +213,11 @@ In the above example, cert-manager will create `Certificate` resources that reference the `ClusterIssuer` `letsencrypt-prod` for all Ingresses that have a `kubernetes.io/tls-acme: "true"` annotation. -Issuers configured via annotations have a preference over the default issuer. If a default issuer is configured via CLI flags and a `cert-manager.io/cluster-issuer` or `cert-manager.io/issuer` annotation also has been added to an Ingress, the created `Certificate` will refer to the issuer configured via annotation. +Issuers configured via specific annotations have a preference over the default issuer. If a default issuer is configured via CLI flags and a `cert-manager.io/cluster-issuer` or `cert-manager.io/issuer` annotation also has been added to an Ingress, the created `Certificate` will refer to the issuer configured via annotation. + +When `kubernetes.io/tls-acme: "true"` hasn't been set, automatic certificate deployment may still occur based on the `cert-manager.io/issuer`, `cert-manager.io/issuer-kind`, and `cert-manager.io/issuer-group` annotations. + +If all annotations are absent, then manual deployment is necessary: create Certificate resources directly, and assign the resulting Secret to the Ingress. For more information on deploying cert-manager, read the [installation guide](../installation/README.md).