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/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/manifest.json b/content/docs/manifest.json index 75afe171c44..8d3ec903f1a 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/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/certificate.md b/content/docs/usage/certificate.md index a11dcd08b37..56087a24442 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -1,8 +1,11 @@ --- -title: Certificate Resources +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/concepts/certificaterequest.md b/content/docs/usage/certificaterequest.md similarity index 98% rename from content/docs/concepts/certificaterequest.md rename to content/docs/usage/certificaterequest.md index 5dbc1ca5465..62531a6dda7 100644 --- a/content/docs/concepts/certificaterequest.md +++ b/content/docs/usage/certificaterequest.md @@ -1,10 +1,13 @@ --- -title: 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`](./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/gateway.md b/content/docs/usage/gateway.md index 45f8fe62b71..d331fbed9df 100644 --- a/content/docs/usage/gateway.md +++ b/content/docs/usage/gateway.md @@ -1,8 +1,11 @@ --- -title: Securing gateway.networking.k8s.io Gateway Resources +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]