Move Issuer / ClusterIssuer and Certificate resource content to a sub-folder of configuration/

content/docs/concepts/acme-orders-challenges.md

@@ -5,7 +5,7 @@ description: 'cert-manager core concepts: ACME Orders and Challenges'
 
 cert-manager supports requesting certificates from ACME servers, including from
 [Let's Encrypt](https://letsencrypt.org/), with use of the [ACME
-Issuer](../configuration/acme/README.md). These certificates are typically trusted on
+Issuer](../configuration/issuer-and-clusterissuer-resources/acme/README.md). These certificates are typically trusted on
 the public Internet by most computers. To successfully request a certificate,
 cert-manager must solve ACME Challenges which are completed in order to prove
 that the client owns the DNS addresses that are being requested.
@@ -97,4 +97,4 @@ as well as disallows two challenges for the same DNS name and solver type
 (`HTTP01` or `DNS01`) to be completed at once.
 
 The maximum number of challenges that can be processed at a time is 60 as of
-[`ddff78`](https://github.com/cert-manager/cert-manager/blob/ddff78f011558e64186d61f7c693edced1496afa/pkg/controller/acmechallenges/scheduler/scheduler.go#L31-L33).
+[`ddff78`](https://github.com/cert-manager/cert-manager/blob/ddff78f011558e64186d61f7c693edced1496afa/pkg/controller/acmechallenges/scheduler/scheduler.go#L31-L33).

content/docs/concepts/certificate.md

@@ -94,7 +94,7 @@ A `Certificate` can alternatively reference a `ClusterIssuer` which is
 non-namespaced and so can be referenced from any namespace.
 
 You can read more on how to configure your `Certificate` resources
-[here](../usage/certificate.md).
+[here](../configuration/certificate-resources.md).
 
 ## Certificate Lifecycle
 
@@ -103,4 +103,4 @@ ACME / Let's Encrypt issuer. You don't need to understand all of these steps
 to use cert-manager; this is more of an explanation of the logic which happens
 under the hood for those curious about the process.
 
-![Life of a Certificate](/images/letsencrypt-flow-cert-manager.png)
+![Life of a Certificate](/images/letsencrypt-flow-cert-manager.png)

content/docs/configuration/README.md

@@ -1,30 +1,36 @@
 ---
-title: Issuer Configuration
-description: Learn about configuring cert-manager using Issuer and ClusterIssuer resources.
+title: Configuration
+description: |
+    Learn about how to configure cert-manager using Issuer, ClusterIssuer and Certificate resources.
 ---
 
+Learn about how to configure cert-manager using Issuer, ClusterIssuer and Certificate resources.
+
+## Overview
+
+After installing cert-manager you will find that some new resource types have been added to the Kubernetes API server
+such as `Issuer`, `ClusterIssuer`, and `Certificate`.
+They all have `metadata`, `spec` and `status` fields, just like other Kubernetes resources.
+
+You can create them by writing the content to a YAML file and using `kubectl apply` to send them to the Kubernetes API server.
+Whenever you create or update one of these resources cert-manager will react;
+it will do some work and it will update the status with information about what it has done.
+
+Here is an overview of each of these resources explaining when you should create them and what cert-manager will do in each case.
+
+## Issuer / ClusterIssuer Resources
+
 The first thing you'll need to configure after you've installed cert-manager is an `Issuer` or a `ClusterIssuer`.
 These are resources that represent certificate authorities (CAs)
-able to sign certificates in response to certificate signing requests.
-
-This section documents how the different issuer types can be configured. You might want to
-[read more about `Issuer` and `ClusterIssuer` resources](../concepts/issuer.md).
+which are able to sign certificates in response to certificate signing requests.
 
-cert-manager comes with a number of built-in certificate issuers which are denoted by being in
-the `cert-manager.io` group. You can also install external issuers in addition to the built-in types.
-Built-in and external issuers are treated the same and are configured similarly.
+📖 [Learn more about Issuer and ClusterIssuer resources](issuer-and-clusterissuer-resources/README.md).
 
-## Cluster Resource Namespace
 
-When using `ClusterIssuer` resource types, ensure you understand the purpose of the
-Cluster Resource Namespace; this can be a common source
-of issues for people getting started with cert-manager.
+## Certificate Resources
 
-The `ClusterIssuer` resource is cluster scoped. This means that when referencing
-a secret via the `secretName` field, secrets will be looked for in the `Cluster
-Resource Namespace`. By default, this namespace is `cert-manager` however it can be
-changed via a flag on the cert-manager-controller component:
+Next you'll probably want to create a Certificate.
+This resource represents a desired X.509 certificate which will be signed and renewed before it expires.
+The private key and signed certificate will be stored in a Secret which you can then mount in to a Pod or use in an Ingress resource.
 
-```bash
---cluster-resource-namespace=my-namespace
-```
+📖 [Learn more about Certificate resources](certificate-resources.md).

content/docs/usage/certificate.md → content/docs/configuration/certificate-resources.md

@@ -1,15 +1,21 @@
 ---
 title: Certificate Resources
-description: 'cert-manager usage: Certificates'
+description: |
+    Learn about Certificate resources which represent a desired X.509 certificates which will be signed and renewed before they expire.
 ---
 
+Learn about Certificate resources which represent a desired X.509 certificates which will be signed and renewed before they expire.
+The private key and signed certificate will be stored in a Secret which you can then mount in to a Pod or use in an Ingress resource.
+
+## Overview
+
 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
 you will interact with cert-manager to request signed certificates.
 
 In order to issue any certificates, you'll need to configure an
-[`Issuer`](../configuration/README.md) or [`ClusterIssuer`](../configuration/README.md)
+[`Issuer`](../configuration/issuer-and-clusterissuer-resources/README.md) or [`ClusterIssuer`](../configuration/issuer-and-clusterissuer-resources/README.md)
 resource first.
 
 ## Creating Certificate Resources
@@ -183,7 +189,7 @@ makes sure deployments get restarted whenever a mounted Secret changes.
 Re-use of private keys
 
 Some issuers, like the built-in [Venafi
-issuer](../configuration/venafi.md), may disallow re-using private keys.
+issuer](../configuration/issuer-and-clusterissuer-resources/venafi.md), may disallow re-using private keys.
 If this is the case, you must explicitly configure the `rotationPolicy:
 Always` setting for each of your Certificate objects accordingly.
 
@@ -365,4 +371,4 @@ type: kubernetes.io/tls
 data:
   key.der: <DER binary format of private key>
   ...
-```
+```

content/docs/configuration/issuer-and-clusterissuer-resources/README.md

@@ -0,0 +1,75 @@
+---
+title: Issuer Configuration
+description: |
+    Learn how to configure cert-manager using Issuer and ClusterIssuer resources
+---
+
+Learn how to configure cert-manager using Issuer and ClusterIssuer resources.
+
+## Overview
+
+The first thing you'll need to configure after you've installed cert-manager is an `Issuer` or a `ClusterIssuer`.
+These are resources that represent certificate authorities (CAs)
+able to sign certificates in response to certificate signing requests.
+
+This section documents how the different issuer types can be configured. You might want to
+[read more about `Issuer` and `ClusterIssuer` resources](../concepts/issuer.md).
+
+cert-manager comes with a number of built-in certificate issuers which are denoted by being in
+the `cert-manager.io` group. You can also install external issuers in addition to the built-in types.
+Built-in and external issuers are treated the same and are configured similarly.
+
+## ACME / Let's Encrypt
+
+Learn how to use the ACME Issuer / ClusterIssuer fields to configure how cert-manager connects to Let's Encrypt
+or any ACME compliant certificate authority.
+
+📖 Read the [ACME / Let's Encrypt Issuer section](./acme/README.md).
+
+## SelfSigned
+
+Learn about the SelfSigned Issuer which is useful for bootstrapping a root certificate for custom Public Key Infrastructure,
+or for creating simple ad-hoc certificates.
+
+📖 Read the [SelfSigned Issuer section](./selfsigned.md).
+
+## CA
+
+Learn about the CA Issuer which generates a Certificate Authority whose certificate and
+private key are stored inside the cluster as a Kubernetes `Secret`.
+
+📖 Read the [CA Issuer section](./ca.md).
+
+## Vault
+
+Learn about the Vault Issuer which signs certificates using HashiCorp Vault.
+
+📖 Read the [Vault Issuer section](./vault.md).
+
+## Venafi
+
+Learn about the Venafi Issuer which signs certificates using Venafi TPP or Venafi-as-a-Service.
+
+📖 Read the [Venafi Issuer section](./venafi.md).
+
+
+## External
+
+Learn about external issuers which are extensions for cert-manager and allow it to get signed certificates from a variety of other certificate authorities.
+
+📖 Read the [External Issuer section](./external.md).
+
+## Cluster Resource Namespace
+
+When using `ClusterIssuer` resource types, ensure you understand the purpose of the
+Cluster Resource Namespace; this can be a common source
+of issues for people getting started with cert-manager.
+
+The `ClusterIssuer` resource is cluster scoped. This means that when referencing
+a secret via the `secretName` field, secrets will be looked for in the `Cluster
+Resource Namespace`. By default, this namespace is `cert-manager` however it can be
+changed via a flag on the cert-manager-controller component:
+
+```bash
+--cluster-resource-namespace=my-namespace
+```

content/docs/configuration/acme/README.md → content/docs/configuration/issuer-and-clusterissuer-resources/acme/README.md

@@ -1,8 +1,13 @@
 ---
 title: ACME
-description: 'cert-manager configuration: ACME Issuers'
+description: |
+    Learn how to use the ACME Issuer / ClusterIssuer fields to configure how cert-manager connects to Let's Encrypt or any ACME compliant certificate authority
 ---
 
+Learn how to use the ACME Issuer / ClusterIssuer fields to configure how cert-manager connects to Let's Encrypt or any ACME compliant certificate authority.
+
+## Overview
+
 The ACME Issuer type represents a single account registered with the Automated
 Certificate Management Environment (ACME) Certificate Authority server. When you
 create a new ACME `Issuer`, cert-manager will generate a private key which is

content/docs/configuration/ca.md → content/docs/configuration/issuer-and-clusterissuer-resources/ca.md

@@ -1,17 +1,21 @@
 ---
 title: CA
-description: 'cert-manager configuration: CA Issuers'
+description: |
+    Learn about the CA Issuer which generates a Certificate Authority whose certificate and
+    private key are stored inside the cluster as a Kubernetes `Secret`.
 ---
 
+Learn about the CA Issuer which generates a Certificate Authority whose certificate and
+private key are stored inside the cluster as a Kubernetes `Secret`.
+
+## Overview
+
 ⚠️ CA issuers are generally either for trying cert-manager out or else for advanced users with
 a good idea of how to run a PKI. To be used safely in production, CA issuers introduce complex
 planning requirements around rotation, trust store distribution and disaster recovery.
 
 If you're not planning to run your own PKI, use a different issuer type.
 
-The CA issuer represents a Certificate Authority whose certificate and
-private key are stored inside the cluster as a Kubernetes `Secret`.
-
 Certificates issued by a CA issuer will not be publicly trusted and so are unlikely to be trusted
 by your applications without further configuration work. Consider the [cert-manager/trust](../projects/trust.md)
 project for distributing trust stores.

content/docs/configuration/external.md → content/docs/configuration/issuer-and-clusterissuer-resources/external.md

@@ -1,8 +1,13 @@
 ---
 title: External
-description: 'cert-manager configuration: External Issuers'
+description: |
+    Learn about external issuers which are extensions for cert-manager and allow it to get signed certificates from a variety of other certificate authorities.
 ---
 
+Learn about external issuers which are extensions for cert-manager and allow it to get signed certificates from a variety of other certificate authorities.
+
+## Overview
+
 cert-manager supports external `Issuer` types. While external issuers are not
 implemented in the main cert-manager repository, they are otherwise treated the
 same as any other issuer.

content/docs/configuration/selfsigned.md → content/docs/configuration/issuer-and-clusterissuer-resources/selfsigned.md

@@ -1,8 +1,15 @@
 ---
 title: SelfSigned
-description: 'cert-manager configuration: SelfSigned Issuers'
+description: |
+    Learn about the SelfSigned Issuer which is useful for bootstrapping a root certificate for custom Public Key Infrastructure,
+    or for creating simple ad-hoc certificates.
 ---
 
+Learn about the SelfSigned Issuer which is useful for bootstrapping a root certificate for custom Public Key Infrastructure,
+or for creating simple ad-hoc certificates.
+
+## Overview
+
 ⚠️ `SelfSigned` issuers are generally useful for bootstrapping a PKI locally, which
 is a complex topic for advanced users. To be used safely in production, running a PKI
 introduces complex planning requirements around rotation, trust store distribution and disaster recovery.
@@ -14,10 +21,6 @@ instead denotes that certificates will "sign themselves" using a given private
 key. In other words, the private key of the certificate will be used to sign
 the certificate itself.
 
-This `Issuer` type is useful for bootstrapping a root certificate for a
-custom PKI (Public Key Infrastructure), or for otherwise creating simple
-ad-hoc certificates for a quick test.
-
 There are important [caveats](#caveats) - including security issues - to
 consider with `SelfSigned` issuers; in general you'd likely  want to use a
 [`CA`](./ca.md) issuer rather than a `SelfSigned` issuer. That said,

content/docs/configuration/vault.md → content/docs/configuration/issuer-and-clusterissuer-resources/vault.md

@@ -1,8 +1,13 @@
 ---
 title: Vault
-description: 'cert-manager configuration: Vault Issuers'
+description: |
+    Learn about the Vault Issuer which signs certificates using HashiCorp Vault.
 ---
 
+Learn about the Vault Issuer which signs certificates using HashiCorp Vault.
+
+## Overview
+
 The `Vault` `Issuer` represents the certificate authority
 [Vault](https://www.vaultproject.io/) - a multi-purpose secret store that can be
 used to sign certificates for your Public Key Infrastructure (PKI). Vault is an
@@ -233,7 +238,7 @@ Kubernetes 1.24 and above.
     ```
 
 1) Create the Issuer resource referencing the Secret resource:
-  
+
     ```yaml
     apiVersion: cert-manager.io/v1
     kind: Issuer
@@ -267,4 +272,4 @@ vault-issuer  True    Vault verified  2m
 ```
 
 Certificates are now ready to be requested by using the Vault issuer named
-`vault-issuer` within the `sandbox` namespace.
+`vault-issuer` within the `sandbox` namespace.

content/docs/configuration/venafi.md → content/docs/configuration/issuer-and-clusterissuer-resources/venafi.md

@@ -1,8 +1,13 @@
 ---
 title: Venafi
-description: 'cert-manager configuration: Venafi Issuers'
+description: |
+    Learn about the Venafi Issuer which signs certificates using Venafi TPP or Venafi-as-a-Service.
 ---
 
+Learn about the Venafi Issuer which signs certificates using Venafi TPP or Venafi-as-a-Service.
+
+## Overview
+
 The Venafi `Issuer` types allows you to obtain certificates from [Venafi
 as a Service (VaaS)](https://vaas.venafi.com/jetstack) and [Venafi Trust Protection
 Platform (TPP)](https://www.venafi.com/platform/tls-protect) instances.
@@ -32,10 +37,10 @@ resources, read the [Namespaces](../concepts/issuer.md#namespaces) section.
 If you haven't already done so, create your Venafi as a Service account on this
 [page](https://vaas.venafi.com/jetstack) and copy the API key from your user
 preferences.  Then you may want to create a custom CA Account and Issuing Template
-or choose instead to use defaults that are automatically created for testing 
+or choose instead to use defaults that are automatically created for testing
 ("Built-in CA" and "Default", respectively).  Lastly you'll need to create an
 Application for establishing ownership of all the certificates requested by your
-cert-manager Issuer, and assign to it the Issuing Template.  
+cert-manager Issuer, and assign to it the Issuing Template.
 
 > Make a note of the Application name and API alias of the Issuing Template because
 > together they comprise the 'zone' you will need for your `Issuer` configuration.
@@ -100,7 +105,7 @@ vaas-issuer    True    Venafi issuer started  2m
 You are now ready to issue certificates using the newly provisioned Venafi
 `Issuer` and Venafi as a Service.
 
-Read the [Issuing Certificates](../usage/certificate.md) document for
+Read the [Issuing Certificates](../configuration/certificate-resources.md) document for
 more information on how to create Certificate resources.
 
 
@@ -252,7 +257,7 @@ $ kubectl describe issuer tpp-issuer --namespace='NAMESPACE OF YOUR ISSUER RESOU
 You are now ready to issue certificates using the newly provisioned Venafi
 `Issuer` and Trust Protection Platform.
 
-Read the [Issuing Certificates](../usage/certificate.md) document for
+Read the [Issuing Certificates](../configuration/certificate-resources.md) document for
 more information on how to create Certificate resources.
 
 # Issuer specific annotations

content/docs/contributing/dns-providers.md

@@ -17,7 +17,7 @@ implementation on the [cert-manager webhook-example](https://github.com/cert-man
 
 There's further information available in the configuration section:
 
-- [ACME DNS01 via webhook](../configuration/acme/dns01/README.md#webhook)
-- [Configuring an ACME issuer with external webhook](../configuration/acme/dns01/webhook.md)
+- [ACME DNS01 via webhook](../configuration/issuer-and-clusterissuer-resources/acme/dns01/README.md#webhook)
+- [Configuring an ACME issuer with external webhook](../configuration/issuer-and-clusterissuer-resources/acme/dns01/webhook.md)
 
 If you're struggling with creating a new DNS webhook, reach out on [Slack](./README.md#slack)!

content/docs/contributing/external-issuers.md

@@ -3,15 +3,15 @@ title: Implementing External Issuers
 description: 'cert-manager contributing guide: External Issuers'
 ---
 
-cert-manager offers a number of [core issuer types](../configuration/README.md) that represent
+cert-manager offers a number of [core issuer types](../configuration/issuer-and-clusterissuer-resources/README.md) that represent
 various certificate authorities.
 
 Since the number of potential issuers is larger than what could reasonably be supported in the
 main cert-manager repository, cert-manager also supports out-of-tree external issuers, and treats
 them the same as in-tree issuer types.
 
 This document is for people looking to _create_ external issuers. For more information on how to
-install and configure external issuer types, read the [configuration documentation](../configuration/external.md).
+install and configure external issuer types, read the [configuration documentation](../configuration/issuer-and-clusterissuer-resources/external.md).
 
 ## General Overview