From 5def5f72d33543db8eaae81affdf8098da0c189e Mon Sep 17 00:00:00 2001 From: Tim Ramlot <42113979+inteon@users.noreply.github.com> Date: Mon, 2 Oct 2023 10:55:08 +0200 Subject: [PATCH 1/4] re-organise the usage section & move missing topics to this section Signed-off-by: Tim Ramlot <42113979+inteon@users.noreply.github.com> --- content/docs/manifest.json | 16 ++++++++-------- content/docs/usage/certificate.md | 2 +- .../{concepts => usage}/certificaterequest.md | 2 +- content/docs/usage/gateway.md | 2 +- content/docs/usage/ingress.md | 2 +- content/docs/usage/kube-csr.md | 2 +- public/_redirects | 3 +++ 7 files changed, 16 insertions(+), 13 deletions(-) rename content/docs/{concepts => usage}/certificaterequest.md (99%) diff --git a/content/docs/manifest.json b/content/docs/manifest.json index 75afe171c44..005a1d6d206 100644 --- a/content/docs/manifest.json +++ b/content/docs/manifest.json @@ -411,19 +411,23 @@ "path": "/docs/usage/README.md" }, { - "title": "Certificate Resources", + "title": "⚓ Certificate", "path": "/docs/usage/certificate.md" }, { - "title": "Securing Ingress Resources", + "title": "⚓ CertificateRequest", + "path": "/docs/usage/certificaterequest.md" + }, + { + "title": "☸️ Ingress", "path": "/docs/usage/ingress.md" }, { - "title": "Securing Gateway Resources", + "title": "☸️ Gateway", "path": "/docs/usage/gateway.md" }, { - "title": "Kubernetes CertificateSigningRequests", + "title": "☸️ CertificateSigningRequests", "path": "/docs/usage/kube-csr.md" }, { @@ -782,10 +786,6 @@ "title": "Certificate", "path": "/docs/concepts/certificate.md" }, - { - "title": "CertificateRequest", - "path": "/docs/concepts/certificaterequest.md" - }, { "title": "ACME Orders and Challenges", "path": "/docs/concepts/acme-orders-challenges.md" diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md index a11dcd08b37..ca29de1e474 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -1,5 +1,5 @@ --- -title: Certificate Resources +title: cert-manager.io Certificate description: 'cert-manager usage: Certificates' --- diff --git a/content/docs/concepts/certificaterequest.md b/content/docs/usage/certificaterequest.md similarity index 99% rename from content/docs/concepts/certificaterequest.md rename to content/docs/usage/certificaterequest.md index 5dbc1ca5465..6f1d0929480 100644 --- a/content/docs/concepts/certificaterequest.md +++ b/content/docs/usage/certificaterequest.md @@ -1,5 +1,5 @@ --- -title: CertificateRequest +title: cert-manager.io CertificateRequest description: 'cert-manager core concepts: CertificateRequests' --- diff --git a/content/docs/usage/gateway.md b/content/docs/usage/gateway.md index 45f8fe62b71..ae852ef6b72 100644 --- a/content/docs/usage/gateway.md +++ b/content/docs/usage/gateway.md @@ -1,5 +1,5 @@ --- -title: Securing gateway.networking.k8s.io Gateway Resources +title: Annotated gateway.networking.k8s.io Gateway description: 'cert-manager usage: Kubernetes Gateways' --- diff --git a/content/docs/usage/ingress.md b/content/docs/usage/ingress.md index 26ff55751ec..af82abbd0aa 100644 --- a/content/docs/usage/ingress.md +++ b/content/docs/usage/ingress.md @@ -1,5 +1,5 @@ --- -title: Securing Ingress Resources +title: Annotated networking.k8s.io Ingress description: 'cert-manager usage: Kubernetes Ingress' --- diff --git a/content/docs/usage/kube-csr.md b/content/docs/usage/kube-csr.md index f6abb93f74a..a4ff6a1a532 100644 --- a/content/docs/usage/kube-csr.md +++ b/content/docs/usage/kube-csr.md @@ -1,5 +1,5 @@ --- -title: Kubernetes CertificateSigningRequests +title: certificates.k8s.io CertificateSigningRequest description: 'cert-manager usage: Kubernetes CertificateSigningRequest resources' --- diff --git a/public/_redirects b/public/_redirects index 8a893e2de4a..2d80cbc1ad0 100644 --- a/public/_redirects +++ b/public/_redirects @@ -215,3 +215,6 @@ https://docs.cert-manager.io/* https://cert-manager.io/docs/:splat 302! /docs/installation/upgrading/* /docs/releases/upgrading/:splat 301! /docs/release-notes/* /docs/releases/release-notes/:splat 301! /docs/installation/supported-releases/ /docs/releases/ 301! + +# Moved the concept pages into the main website +/docs/concepts/certificaterequest/ /docs/usage/certificaterequest/ 301! From d9a71b1d730b331da9a40daee599d667e8aee4c3 Mon Sep 17 00:00:00 2001 From: Tim Ramlot <42113979+inteon@users.noreply.github.com> Date: Mon, 2 Oct 2023 10:56:49 +0200 Subject: [PATCH 2/4] fix broken links Signed-off-by: Tim Ramlot <42113979+inteon@users.noreply.github.com> --- content/docs/concepts/acme-orders-challenges.md | 2 +- content/docs/contributing/external-issuers.md | 6 +++--- content/docs/policy/approval/README.md | 4 ++-- content/docs/policy/approval/approver-policy/README.md | 6 +++--- content/docs/reference/cmctl.md | 2 +- content/docs/usage/certificaterequest.md | 2 +- content/docs/usage/csi-driver-spiffe.md | 10 +++++----- content/docs/usage/csi-driver.md | 2 +- content/docs/usage/kube-csr.md | 2 +- 9 files changed, 18 insertions(+), 18 deletions(-) diff --git a/content/docs/concepts/acme-orders-challenges.md b/content/docs/concepts/acme-orders-challenges.md index 80c31606e4e..e7c67a4a6e2 100644 --- a/content/docs/concepts/acme-orders-challenges.md +++ b/content/docs/concepts/acme-orders-challenges.md @@ -20,7 +20,7 @@ In order to complete these challenges, cert-manager introduces two validation can be found on the Let's Encrypt website [here](https://letsencrypt.org/how-it-works/). An order represents a single certificate request which will be created automatically once a new -[`CertificateRequest`](./certificaterequest.md) resource referencing an ACME +[`CertificateRequest`](../usage/certificaterequest.md) resource referencing an ACME issuer has been created. `CertificateRequest` resources are created automatically by cert-manager once a [`Certificate`](./certificate.md) resource is created, has its specification changed, or needs renewal. diff --git a/content/docs/contributing/external-issuers.md b/content/docs/contributing/external-issuers.md index 4d18572fb31..f4408e1c15c 100644 --- a/content/docs/contributing/external-issuers.md +++ b/content/docs/contributing/external-issuers.md @@ -49,13 +49,13 @@ on how to write an external issuer using Kubebuilder and controller-runtime. ## Approval Before signing a certificate, Issuers **must** also ensure that the `CertificateRequest` is -[`Approved`](../concepts/certificaterequest.md#approval). +[`Approved`](../usage/certificaterequest.md#approval). If the `CertificateRequest` is not `Approved`, the issuer **must** not process it. Issuers are not responsible for approving `CertificateRequests` and should refuse to proceed if they find a certificate that is not approved. -If a `CertificateRequest` created for an issuance associated with a `Certificate` gets [`Denied`](../concepts/certificaterequest.md#approval), the issuance will be failed by cert-manager's issuing controller. +If a `CertificateRequest` created for an issuance associated with a `Certificate` gets [`Denied`](../usage/certificaterequest.md#approval), the issuance will be failed by cert-manager's issuing controller. ## Conditions @@ -65,7 +65,7 @@ status of that resource to a ready state, as this is what is used to signal to h controllers - such as the `Certificate` controller - that the resource is ready to be consumed. Conversely, if the `CertificateRequest` fails, it is as important to mark the resource as such, as this will -also be used as a signal to higher order controllers. Valid condition states are listed under [concepts](../concepts/certificaterequest.md#conditions). +also be used as a signal to higher order controllers. Valid condition states are listed under [concepts](../usage/certificaterequest.md#conditions). ## Implementation diff --git a/content/docs/policy/approval/README.md b/content/docs/policy/approval/README.md index 05f1068f3b1..9374fbb374a 100644 --- a/content/docs/policy/approval/README.md +++ b/content/docs/policy/approval/README.md @@ -13,10 +13,10 @@ that rejects the request. ## Rejecting requests before sending the X.509 Certificate Signing Request (CSR) to the issuer -cert-manager requires that a [CertificateRequest](../../concepts/certificaterequest.md) +cert-manager requires that a [CertificateRequest](../../usage/certificaterequest.md) is approved before it is sent to the issuer. Also, CertificateSigningRequests must be approved before they are sent to the issuer. This approval is done by adding an -[approval condition](../../concepts/certificaterequest.md#approval) to the resource. +[approval condition](../../usage/certificaterequest.md#approval) to the resource. In a default installation, cert-manager automatically approves all CertificateRequests and CertificateSigningRequests that use any of its built-in issuers. This is done to diff --git a/content/docs/policy/approval/approver-policy/README.md b/content/docs/policy/approval/approver-policy/README.md index aa6084f2abb..76131015f79 100644 --- a/content/docs/policy/approval/approver-policy/README.md +++ b/content/docs/policy/approval/approver-policy/README.md @@ -4,14 +4,14 @@ description: 'Policy plugin for cert-manager' --- approver-policy is a cert-manager -[approver](../../../concepts/certificaterequest.md#approval) +[approver](../../../usage/certificaterequest.md#approval) that will approve or deny CertificateRequests based on policies defined in the `CertificateRequestPolicy` custom resource. ## Prerequisites [cert-manager must be installed](../../../installation/README.md), and -the [the default approver in cert-manager must be disabled](../../../concepts/certificaterequest.md#approver-controller). +the [the default approver in cert-manager must be disabled](../../../usage/certificaterequest.md#approver-controller). > ⚠️ If the default approver is not disabled in cert-manager, approver-policy will > race with cert-manager and policy will be ineffective. @@ -69,7 +69,7 @@ If you are using approver-policy with [external issuers](../../../configuration/external.md), you _must_ include their signer names so that approver-policy has permissions to approve and deny CertificateRequests that -[reference them](../../../concepts/certificaterequest.md#rbac-syntax). +[reference them](../../../usage/certificaterequest.md#rbac-syntax). For example, if using approver-policy for the internal issuer types, along with [google-cas-issuer](https://github.com/jetstack/google-cas-issuer), and [aws-privateca-issuer](https://github.com/cert-manager/aws-privateca-issuer), diff --git a/content/docs/reference/cmctl.md b/content/docs/reference/cmctl.md index 3b795614274..d180dec3e3b 100644 --- a/content/docs/reference/cmctl.md +++ b/content/docs/reference/cmctl.md @@ -74,7 +74,7 @@ Use "cmctl [command] --help" for more information about a command. ### Approve and Deny CertificateRequests CertificateRequests can be -[approved or denied](../concepts/certificaterequest.md#approval) using their +[approved or denied](../usage/certificaterequest.md#approval) using their respective cmctl commands: > **Note**: The internal cert-manager approver may automatically approve all diff --git a/content/docs/usage/certificaterequest.md b/content/docs/usage/certificaterequest.md index 6f1d0929480..8d39d914997 100644 --- a/content/docs/usage/certificaterequest.md +++ b/content/docs/usage/certificaterequest.md @@ -4,7 +4,7 @@ description: 'cert-manager core concepts: CertificateRequests' --- The `CertificateRequest` is a namespaced resource in cert-manager that is used -to request X.509 certificates from an [`Issuer`](./issuer.md). The resource +to request X.509 certificates from an [`Issuer`](../concepts/issuer.md). The resource contains a base64 encoded string of a PEM encoded certificate request which is sent to the referenced issuer. A successful issuance will return a signed certificate, based on the certificate signing request. `CertificateRequests` are diff --git a/content/docs/usage/csi-driver-spiffe.md b/content/docs/usage/csi-driver-spiffe.md index 771ce6a1aed..ca52c226942 100644 --- a/content/docs/usage/csi-driver-spiffe.md +++ b/content/docs/usage/csi-driver-spiffe.md @@ -46,7 +46,7 @@ which is used to create and mount Pod volumes from. When a Pod is created with the CSI volume configured, the driver will locally generate a private key, and create a cert-manager -[CertificateRequest](../concepts/certificaterequest.md) +[CertificateRequest](../usage/certificaterequest.md) in the same Namespace as the Pod. The driver uses [CSI Token Request](https://kubernetes-csi.github.io/docs/token-requests.html) to both @@ -61,7 +61,7 @@ expiry of the signed certificate. #### Approver -A distinct [cert-manager approver](../concepts/certificaterequest.md#approval) +A distinct [cert-manager approver](../usage/certificaterequest.md#approval) Deployment is responsible for managing the approval and denial condition of created CertificateRequests that target the configured SPIFFE Trust Domain signer. @@ -78,7 +78,7 @@ The approver ensures that requests have: If any of these checks do not pass, the CertificateRequest will be marked as Denied, else it will be marked as Approved. The approver will only manage -CertificateRequests who request from the same [IssuerRef](../concepts/certificaterequest.md) +CertificateRequests who request from the same [IssuerRef](../usage/certificaterequest.md) that has been configured. ## Installation @@ -98,7 +98,7 @@ cert-manager `v1.3` or higher is also required. csi-driver-spiffe requires cert-manager to be [installed](../installation/README.md) but a default installation of cert-manager **will not work**. -> ⚠️ It is **vital** that the [default approver is disabled in cert-manager](../concepts/certificaterequest.md#approver-controller) ⚠️ +> ⚠️ It is **vital** that the [default approver is disabled in cert-manager](../usage/certificaterequest.md#approver-controller) ⚠️ If the default approver is not disabled, the csi-driver-spiffe approver will race with cert-manager and policy enforcement will become useless. @@ -149,7 +149,7 @@ cmctl approve -n cert-manager \ Install csi-driver-spiffe into the cluster using the issuer we configured. We must also configure the issuer resource type and name of the issuer we -configured so that the approver has [permissions to approve referencing CertificateRequests](../concepts/certificaterequest.md#rbac-syntax). +configured so that the approver has [permissions to approve referencing CertificateRequests](../usage/certificaterequest.md#rbac-syntax). Note that the `issuer.name`, `issuer.kind` and `issuer.group` will need to be changed to match the issuer you're actually using! diff --git a/content/docs/usage/csi-driver.md b/content/docs/usage/csi-driver.md index f241e7bb9bc..12428534ce2 100644 --- a/content/docs/usage/csi-driver.md +++ b/content/docs/usage/csi-driver.md @@ -182,7 +182,7 @@ volumeAttributes: ## Requesting Certificates using the mounting Pod's ServiceAccount If the flag `--use-token-request` is enabled on the csi-driver DaemonSet, the -[CertificateRequest](../concepts/certificaterequest.md) resource will be created +[CertificateRequest](../usage/certificaterequest.md) resource will be created by the mounting Pod's ServiceAccount. This can be paired with [approver-policy](../policy/approval/approver-policy/README.md) to enable advanced policy control on a per-ServiceAccount basis. diff --git a/content/docs/usage/kube-csr.md b/content/docs/usage/kube-csr.md index a4ff6a1a532..0f7c41a3dfc 100644 --- a/content/docs/usage/kube-csr.md +++ b/content/docs/usage/kube-csr.md @@ -6,7 +6,7 @@ description: 'cert-manager usage: Kubernetes CertificateSigningRequest resources 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.md) in that it is used to +[CertificateRequest](../usage/certificaterequest.md) in that it is used to request an X.509 signed certificate from a referenced Certificate Authority (CA). From ebbb7646287314a34af4687e0520089b99b64d9f Mon Sep 17 00:00:00 2001 From: Tim Ramlot <42113979+inteon@users.noreply.github.com> Date: Tue, 3 Oct 2023 14:57:18 +0200 Subject: [PATCH 3/4] improve titles Signed-off-by: Tim Ramlot <42113979+inteon@users.noreply.github.com> --- .spelling | 4 ++++ content/docs/usage/certificate.md | 5 ++++- content/docs/usage/certificaterequest.md | 5 ++++- content/docs/usage/gateway.md | 5 ++++- content/docs/usage/ingress.md | 5 ++++- content/docs/usage/kube-csr.md | 5 ++++- 6 files changed, 24 insertions(+), 5 deletions(-) diff --git a/.spelling b/.spelling index dfe98730153..036797e453c 100644 --- a/.spelling +++ b/.spelling @@ -656,6 +656,10 @@ arukiidou Richardds kahirokunn selfsigned-issuer +apiVersion +gateway.networking.k8s.io +networking.k8s.io +certificates.k8s.io # TEMPORARY # these are temporarily ignored because the spellchecker diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md index ca29de1e474..56087a24442 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -1,8 +1,11 @@ --- -title: cert-manager.io Certificate +title: Certificate resource description: 'cert-manager usage: Certificates' --- +> **apiVersion:** cert-manager.io/v1 +> **kind:** Certificate + In cert-manager, the [`Certificate`](../concepts/certificate.md) resource represents a human readable definition of a certificate request that is to be honored by an issuer which is to be kept up-to-date. This is the usual way that diff --git a/content/docs/usage/certificaterequest.md b/content/docs/usage/certificaterequest.md index 8d39d914997..62531a6dda7 100644 --- a/content/docs/usage/certificaterequest.md +++ b/content/docs/usage/certificaterequest.md @@ -1,8 +1,11 @@ --- -title: cert-manager.io CertificateRequest +title: CertificateRequest resource description: 'cert-manager core concepts: CertificateRequests' --- +> **apiVersion:** cert-manager.io/v1 +> **kind:** CertificateRequest + The `CertificateRequest` is a namespaced resource in cert-manager that is used to request X.509 certificates from an [`Issuer`](../concepts/issuer.md). The resource contains a base64 encoded string of a PEM encoded certificate request which is diff --git a/content/docs/usage/gateway.md b/content/docs/usage/gateway.md index ae852ef6b72..d331fbed9df 100644 --- a/content/docs/usage/gateway.md +++ b/content/docs/usage/gateway.md @@ -1,8 +1,11 @@ --- -title: Annotated gateway.networking.k8s.io Gateway +title: Annotated Gateway resource description: 'cert-manager usage: Kubernetes Gateways' --- +> **apiVersion:** gateway.networking.k8s.io/v1alpha2 +> **kind:** Gateway + **FEATURE STATE**: cert-manager 1.5 [alpha]
diff --git a/content/docs/usage/ingress.md b/content/docs/usage/ingress.md index af82abbd0aa..f12d921e766 100644 --- a/content/docs/usage/ingress.md +++ b/content/docs/usage/ingress.md @@ -1,8 +1,11 @@ --- -title: Annotated networking.k8s.io Ingress +title: Annotated Ingress resource description: 'cert-manager usage: Kubernetes Ingress' --- +> **apiVersion:** networking.k8s.io/v1 +> **kind:** Ingress + A common use-case for cert-manager is requesting TLS signed certificates to secure your ingress resources. This can be done by simply adding annotations to your `Ingress` resources and cert-manager will facilitate creating the diff --git a/content/docs/usage/kube-csr.md b/content/docs/usage/kube-csr.md index 0f7c41a3dfc..d3b39f62125 100644 --- a/content/docs/usage/kube-csr.md +++ b/content/docs/usage/kube-csr.md @@ -1,8 +1,11 @@ --- -title: certificates.k8s.io CertificateSigningRequest +title: CertificateSigningRequest resource description: 'cert-manager usage: Kubernetes CertificateSigningRequest resources' --- +> **apiVersion:** certificates.k8s.io/v1 +> **kind:** CertificateSigningRequest + 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 From ec94f3d00965cd571f6d2fc2e6e6ec428cbcc4ab Mon Sep 17 00:00:00 2001 From: Tim Ramlot <42113979+inteon@users.noreply.github.com> Date: Thu, 12 Oct 2023 09:36:28 +0200 Subject: [PATCH 4/4] remove menu icons Signed-off-by: Tim Ramlot <42113979+inteon@users.noreply.github.com> --- content/docs/manifest.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/docs/manifest.json b/content/docs/manifest.json index 005a1d6d206..8d3ec903f1a 100644 --- a/content/docs/manifest.json +++ b/content/docs/manifest.json @@ -411,23 +411,23 @@ "path": "/docs/usage/README.md" }, { - "title": "⚓ Certificate", + "title": "Certificate", "path": "/docs/usage/certificate.md" }, { - "title": "⚓ CertificateRequest", + "title": "CertificateRequest", "path": "/docs/usage/certificaterequest.md" }, { - "title": "☸️ Ingress", + "title": "Ingress", "path": "/docs/usage/ingress.md" }, { - "title": "☸️ Gateway", + "title": "Gateway", "path": "/docs/usage/gateway.md" }, { - "title": "☸️ CertificateSigningRequests", + "title": "CertificateSigningRequests", "path": "/docs/usage/kube-csr.md" }, {