diff --git a/content/docs/concepts/acme-orders-challenges.md b/content/docs/concepts/acme-orders-challenges.md index 80c31606e4e..6c3e5bf44ce 100644 --- a/content/docs/concepts/acme-orders-challenges.md +++ b/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). \ No newline at end of file +[`ddff78`](https://github.com/cert-manager/cert-manager/blob/ddff78f011558e64186d61f7c693edced1496afa/pkg/controller/acmechallenges/scheduler/scheduler.go#L31-L33). diff --git a/content/docs/concepts/certificate.md b/content/docs/concepts/certificate.md index 3d8ca12198e..829ad880fc3 100644 --- a/content/docs/concepts/certificate.md +++ b/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) \ No newline at end of file +![Life of a Certificate](/images/letsencrypt-flow-cert-manager.png) diff --git a/content/docs/configuration/README.md b/content/docs/configuration/README.md index 85c5d1334f7..a4c719e1fa2 100644 --- a/content/docs/configuration/README.md +++ b/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). diff --git a/content/docs/usage/certificate.md b/content/docs/configuration/certificate-resources.md similarity index 95% rename from content/docs/usage/certificate.md rename to content/docs/configuration/certificate-resources.md index 32a3d2c20be..405a769f3e7 100644 --- a/content/docs/usage/certificate.md +++ b/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: ... -``` \ No newline at end of file +``` diff --git a/content/docs/configuration/issuer-and-clusterissuer-resources/README.md b/content/docs/configuration/issuer-and-clusterissuer-resources/README.md new file mode 100644 index 00000000000..653e4bf28ec --- /dev/null +++ b/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 +``` diff --git a/content/docs/configuration/acme/README.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/README.md similarity index 97% rename from content/docs/configuration/acme/README.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/README.md index e85e4e4916e..484e66ccc67 100644 --- a/content/docs/configuration/acme/README.md +++ b/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 diff --git a/content/docs/configuration/acme/dns01/README.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/README.md similarity index 100% rename from content/docs/configuration/acme/dns01/README.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/README.md diff --git a/content/docs/configuration/acme/dns01/acme-dns.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/acme-dns.md similarity index 100% rename from content/docs/configuration/acme/dns01/acme-dns.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/acme-dns.md diff --git a/content/docs/configuration/acme/dns01/akamai.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/akamai.md similarity index 100% rename from content/docs/configuration/acme/dns01/akamai.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/akamai.md diff --git a/content/docs/configuration/acme/dns01/azuredns.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/azuredns.md similarity index 100% rename from content/docs/configuration/acme/dns01/azuredns.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/azuredns.md diff --git a/content/docs/configuration/acme/dns01/cloudflare.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/cloudflare.md similarity index 100% rename from content/docs/configuration/acme/dns01/cloudflare.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/cloudflare.md diff --git a/content/docs/configuration/acme/dns01/digitalocean.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/digitalocean.md similarity index 100% rename from content/docs/configuration/acme/dns01/digitalocean.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/digitalocean.md diff --git a/content/docs/configuration/acme/dns01/google.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/google.md similarity index 100% rename from content/docs/configuration/acme/dns01/google.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/google.md diff --git a/content/docs/configuration/acme/dns01/rfc2136.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/rfc2136.md similarity index 100% rename from content/docs/configuration/acme/dns01/rfc2136.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/rfc2136.md diff --git a/content/docs/configuration/acme/dns01/route53.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/route53.md similarity index 100% rename from content/docs/configuration/acme/dns01/route53.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/route53.md diff --git a/content/docs/configuration/acme/dns01/webhook.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/webhook.md similarity index 100% rename from content/docs/configuration/acme/dns01/webhook.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/webhook.md diff --git a/content/docs/configuration/acme/http01/README.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/http01/README.md similarity index 100% rename from content/docs/configuration/acme/http01/README.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/http01/README.md diff --git a/content/docs/configuration/acme/http01/externalloadbalancer.md b/content/docs/configuration/issuer-and-clusterissuer-resources/acme/http01/externalloadbalancer.md similarity index 100% rename from content/docs/configuration/acme/http01/externalloadbalancer.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/acme/http01/externalloadbalancer.md diff --git a/content/docs/configuration/ca.md b/content/docs/configuration/issuer-and-clusterissuer-resources/ca.md similarity index 96% rename from content/docs/configuration/ca.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/ca.md index 66ccc77db1b..680cf7dba17 100644 --- a/content/docs/configuration/ca.md +++ b/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. diff --git a/content/docs/configuration/external.md b/content/docs/configuration/issuer-and-clusterissuer-resources/external.md similarity index 90% rename from content/docs/configuration/external.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/external.md index b1cd23baab9..ed847712144 100644 --- a/content/docs/configuration/external.md +++ b/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. diff --git a/content/docs/configuration/selfsigned.md b/content/docs/configuration/issuer-and-clusterissuer-resources/selfsigned.md similarity index 93% rename from content/docs/configuration/selfsigned.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/selfsigned.md index 83e632787d9..4e78fbfc135 100644 --- a/content/docs/configuration/selfsigned.md +++ b/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, diff --git a/content/docs/configuration/vault.md b/content/docs/configuration/issuer-and-clusterissuer-resources/vault.md similarity index 97% rename from content/docs/configuration/vault.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/vault.md index c2dd25aee54..16e739cd285 100644 --- a/content/docs/configuration/vault.md +++ b/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. \ No newline at end of file +`vault-issuer` within the `sandbox` namespace. diff --git a/content/docs/configuration/venafi.md b/content/docs/configuration/issuer-and-clusterissuer-resources/venafi.md similarity index 95% rename from content/docs/configuration/venafi.md rename to content/docs/configuration/issuer-and-clusterissuer-resources/venafi.md index 6be309c4007..cc67a0156dc 100644 --- a/content/docs/configuration/venafi.md +++ b/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 diff --git a/content/docs/contributing/dns-providers.md b/content/docs/contributing/dns-providers.md index 400f3d17ee8..916fd3c996b 100644 --- a/content/docs/contributing/dns-providers.md +++ b/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)! diff --git a/content/docs/contributing/external-issuers.md b/content/docs/contributing/external-issuers.md index 4169a95f899..de25568c1ce 100644 --- a/content/docs/contributing/external-issuers.md +++ b/content/docs/contributing/external-issuers.md @@ -3,7 +3,7 @@ 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 @@ -11,7 +11,7 @@ main cert-manager repository, cert-manager also supports out-of-tree external is 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 diff --git a/content/docs/contributing/policy.md b/content/docs/contributing/policy.md index d29f34e41f6..ec7c3661d4d 100644 --- a/content/docs/contributing/policy.md +++ b/content/docs/contributing/policy.md @@ -154,6 +154,6 @@ authorization against the API server. If cert-manager used this cert, it could a We try to not include in core cert-manager new functionality that involves calling third party APIs that we don't have infrastructure to test (or that the maintainers don't have the skills to work with). -Instead we try to build interfaces such as [external DNS webhook solver](../configuration/acme/dns01/webhook.md) that can be implemented to use cert-manager with a particular third party implementation. +Instead we try to build interfaces such as [external DNS webhook solver](../configuration/issuer-and-clusterissuer-resources/acme/dns01/webhook.md) that can be implemented to use cert-manager with a particular third party implementation. We believe that this is a more sustainable approach as that way folks who have knowledge and skills to work with particular infrastructure can own a project that interacts with it and it lets us avoid merging potentially untested code to core cert-manager. An example of a PR that might be rejected would be adding a new external DNS solver kind, see https://github.com/cert-manager/cert-manager/pull/1088 diff --git a/content/docs/installation/upgrading/upgrading-0.10-0.11.md b/content/docs/installation/upgrading/upgrading-0.10-0.11.md index d79aea493fa..9912676b48d 100644 --- a/content/docs/installation/upgrading/upgrading-0.10-0.11.md +++ b/content/docs/installation/upgrading/upgrading-0.10-0.11.md @@ -111,7 +111,7 @@ Support for the deprecated `spec.http01` or `spec.dns01` fields in `Issuer` and `ClusterIssuer` have been removed. Any `Issuer` or `ClusterIssuer` objects must be converted to use the equivalent `spec.solvers[].http01` or `spec.solvers[].dns01` syntax. You can read more about the Issuer resource in -the [configuration documentation](../../configuration/README.md). +the [configuration documentation](../../configuration/issuer-and-clusterissuer-resources/README.md). Any issuers that haven't been converted will result the `cert-manager` pod being unable to find any solvers at the expected location. This will result in errors diff --git a/content/docs/installation/upgrading/upgrading-0.7-0.8.md b/content/docs/installation/upgrading/upgrading-0.7-0.8.md index e3fabdca71a..22afff4e9ef 100644 --- a/content/docs/installation/upgrading/upgrading-0.7-0.8.md +++ b/content/docs/installation/upgrading/upgrading-0.7-0.8.md @@ -21,13 +21,13 @@ have a large, multi-team deployment of cert-manager that makes it complex to upgrade all manifests at once in place. After upgrading, it is **strongly recommended** that you update your ACME Issuer -and Certificate resources to the [new format](../../configuration/acme/README.md). +and Certificate resources to the [new format](../../configuration/issuer-and-clusterissuer-resources/acme/README.md). We will be removing support for the old format ahead of the 1.0 release. The documentation has been updated to reflect configuring using the new format, and as such, exhaustive information can be found in the -[document](../../configuration/acme/README.md). +[document](../../configuration/issuer-and-clusterissuer-resources/acme/README.md). ## Performing an incremental switch to the new format @@ -267,4 +267,4 @@ and a workaround is scheduled to be completed for `v0.9`. In the meantime, `ingress-gce` users can either choose to manually create a new solver entry per Ingress resource they want to use to solve challenges, or otherwise continue to use the **old format** until a suitable alternative -appears in `v0.9`. \ No newline at end of file +appears in `v0.9`. diff --git a/content/docs/installation/upgrading/upgrading-1.2-1.3.md b/content/docs/installation/upgrading/upgrading-1.2-1.3.md index 2aa5394fc87..cd822439191 100644 --- a/content/docs/installation/upgrading/upgrading-1.2-1.3.md +++ b/content/docs/installation/upgrading/upgrading-1.2-1.3.md @@ -24,9 +24,9 @@ With this update, cert-manager users with Venafi Cloud issuers will need to be a This means users will need to create an Application in `OutagePREDICT` and associate an _Issuing Template_ with it (the same _Issuing Templates_ assigned to DA Projects Zones can be used since _Issuing Templates_ are shared between Venafi Cloud products). -[Venafi Cloud Issuer]: https://cert-manager.io/docs/configuration/venafi/ +[Venafi Cloud Issuer]: https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/venafi/ [`VCert` `v4.13.0`]: https://github.com/Venafi/vcert/releases/tag/v4.13.0 ## Next Steps -You should now follow the [regular upgrade process](./README.md). \ No newline at end of file +You should now follow the [regular upgrade process](./README.md). diff --git a/content/docs/manifest.json b/content/docs/manifest.json index 83a4ad80930..e9c6695bd7e 100644 --- a/content/docs/manifest.json +++ b/content/docs/manifest.json @@ -180,43 +180,31 @@ "title": "Introduction", "path": "/docs/configuration/README.md" }, + { + "title": "Issuer / ClusterIssuer", + "routes": [ + { - "title": "SelfSigned", - "path": "/docs/configuration/selfsigned.md" - }, - { - "title": "CA", - "path": "/docs/configuration/ca.md" - }, - { - "title": "Vault", - "path": "/docs/configuration/vault.md" - }, - { - "title": "Venafi", - "path": "/docs/configuration/venafi.md" - }, - { - "title": "External", - "path": "/docs/configuration/external.md" + "title": "Introduction", + "path": "/docs/configuration/issuer-and-clusterissuer-resources/README.md" }, { "title": "ACME", "routes": [ { "title": "Introduction", - "path": "/docs/configuration/acme/README.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/README.md" }, { "title": "HTTP01", "routes": [ { "title": "Introduction", - "path": "/docs/configuration/acme/http01/README.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/http01/README.md" }, { "title": "External Load Balancer", - "path": "/docs/configuration/acme/http01/externalloadbalancer.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/http01/externalloadbalancer.md" } ] }, @@ -225,49 +213,78 @@ "routes": [ { "title": "Introduction", - "path": "/docs/configuration/acme/dns01/README.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/README.md" }, { "title": "ACMEDNS", - "path": "/docs/configuration/acme/dns01/acme-dns.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/acme-dns.md" }, { "title": "Akamai", - "path": "/docs/configuration/acme/dns01/akamai.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/akamai.md" }, { "title": "AzureDNS", - "path": "/docs/configuration/acme/dns01/azuredns.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/azuredns.md" }, { "title": "Cloudflare", - "path": "/docs/configuration/acme/dns01/cloudflare.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/cloudflare.md" }, { "title": "DigitalOcean", - "path": "/docs/configuration/acme/dns01/digitalocean.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/digitalocean.md" }, { "title": "Google CloudDNS", - "path": "/docs/configuration/acme/dns01/google.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/google.md" }, { "title": "RFC-2136", - "path": "/docs/configuration/acme/dns01/rfc2136.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/rfc2136.md" }, { "title": "Route53", - "path": "/docs/configuration/acme/dns01/route53.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/route53.md" }, { "title": "Webhook", - "path": "/docs/configuration/acme/dns01/webhook.md" + "path": "/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/webhook.md" } ] } ] + }, + + + + { + "title": "SelfSigned", + "path": "/docs/configuration/issuer-and-clusterissuer-resources/selfsigned.md" + }, + { + "title": "CA", + "path": "/docs/configuration/issuer-and-clusterissuer-resources/ca.md" + }, + { + "title": "Vault", + "path": "/docs/configuration/issuer-and-clusterissuer-resources/vault.md" + }, + { + "title": "Venafi", + "path": "/docs/configuration/issuer-and-clusterissuer-resources/venafi.md" + }, + { + "title": "External", + "path": "/docs/configuration/issuer-and-clusterissuer-resources/external.md" + } + ] + }, + { + "title": "Certificate Resources", + "path": "/docs/configuration/certificate-resources.md" } - ] + ] }, { "title": "Usage", @@ -276,10 +293,6 @@ "title": "Introduction", "path": "/docs/usage/README.md" }, - { - "title": "Certificate Resources", - "path": "/docs/usage/certificate.md" - }, { "title": "Prometheus Metrics", "path": "/docs/usage/prometheus-metrics.md" diff --git a/content/docs/projects/approver-policy.md b/content/docs/projects/approver-policy.md index e28f1fcb868..d65193c4087 100644 --- a/content/docs/projects/approver-policy.md +++ b/content/docs/projects/approver-policy.md @@ -34,7 +34,7 @@ $ helm upgrade -i -n cert-manager cert-manager-approver-policy jetstack/cert-man ``` If you are using approver-policy with [external -issuers](https://cert-manager.io/docs/configuration/external/), you _must_ +issuers](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/external/), you _must_ include their signer names so that approver-policy has permissions to approve and deny CertificateRequests that [reference them](https://cert-manager.io/docs/concepts/certificaterequest/#rbac-syntax). diff --git a/content/docs/projects/csi-driver-spiffe.md b/content/docs/projects/csi-driver-spiffe.md index 930c0540897..3a447aaedc1 100644 --- a/content/docs/projects/csi-driver-spiffe.md +++ b/content/docs/projects/csi-driver-spiffe.md @@ -109,20 +109,20 @@ been configured. > :warning: 2. Install or configure a - [ClusterIssuer](https://cert-manager.io/docs/configuration/) to give + [ClusterIssuer](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/) to give cert-manager the ability to sign against your Trust Domain. If a namespace scoped Issuer is desired, then that Issuer must be created in every namespace that Pods will mount volumes from. You must use an Issuer type which is compatible with signing URI SAN certificates and the private does not need to be available to the signer, for - example [CA](https://cert-manager.io/docs/configuration/ca/), - [Vault](https://cert-manager.io/docs/configuration/vault/), - [Venafi](https://cert-manager.io/docs/configuration/venafi/), + example [CA](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/ca/), + [Vault](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/vault/), + [Venafi](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/venafi/), [AWS PCA](https://github.com/cert-manager/aws-privateca-issuer), [Google CAS](https://github.com/jetstack/google-cas-issuer), [Small Step](https://github.com/smallstep/step-issuer). Issuers such as - [SelfSigned](https://cert-manager.io/docs/configuration/selfsigned/) or - [ACME](https://cert-manager.io/docs/configuration/acme/) *will not work*. + [SelfSigned](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/selfsigned/) or + [ACME](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/acme/) *will not work*. An example demo [ClusterIssuer](https://cert-manager.io/docs/concepts/issuer/#namespaces) can diff --git a/content/docs/projects/csi-driver.md b/content/docs/projects/csi-driver.md index 87c50c3c3e0..7583d993fe7 100644 --- a/content/docs/projects/csi-driver.md +++ b/content/docs/projects/csi-driver.md @@ -122,7 +122,7 @@ this process has been completed. For more information on how to set up issuers for your cluster, refer to the cert-manager documentation -[here](https://cert-manager.io/docs/configuration/). **Note** it is not +[here](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/). **Note** it is not possible to use `SelfSigned` Issuers with the CSI Driver. In order for cert-manager to self sign a certificate, it needs access to the secret containing the private key that signed the certificate request to sign the end diff --git a/content/docs/projects/istio-csr.md b/content/docs/projects/istio-csr.md index 57748517bcf..358b41d79d9 100644 --- a/content/docs/projects/istio-csr.md +++ b/content/docs/projects/istio-csr.md @@ -62,9 +62,9 @@ Our [getting started guide](../tutorials/istio-csr/istio-csr.md) uses an `Issuer Whether you choose to use an `Issuer` or a `ClusterIssuer`, you'll also need to choose the type of issuer you want such as: -- [CA](https://cert-manager.io/docs/configuration/ca/) -- [Vault](https://cert-manager.io/docs/configuration/vault/) -- or an [external issuer](https://cert-manager.io/docs/configuration/external/) +- [CA](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/ca/) +- [Vault](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/vault/) +- or an [external issuer](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/external/) The key requirement is that arbitrary values can be placed into the `subjectAltName` (SAN) X.509 extension, since Istio places SPIFFE IDs there. diff --git a/content/docs/release-notes/release-notes-1.1.md b/content/docs/release-notes/release-notes-1.1.md index 082caaa0954..37fdc91d9be 100644 --- a/content/docs/release-notes/release-notes-1.1.md +++ b/content/docs/release-notes/release-notes-1.1.md @@ -48,5 +48,5 @@ This allows you to get more insight into any rate limiting or other errors your ## Improvements for Venafi TPP Authentication -It is now possible to use a long lived access-token for authentication when configuring [Venafi TPP `Issuer` and `ClusterIssuer` types](../configuration/venafi.md). -This authentication mechanism is supported by `Venafi TPP >= 19.2`. \ No newline at end of file +It is now possible to use a long lived access-token for authentication when configuring [Venafi TPP `Issuer` and `ClusterIssuer` types](../configuration/issuer-and-clusterissuer-resources/venafi.md). +This authentication mechanism is supported by `Venafi TPP >= 19.2`. diff --git a/content/docs/release-notes/release-notes-1.3.md b/content/docs/release-notes/release-notes-1.3.md index b9bc9641b25..9e1ab189220 100644 --- a/content/docs/release-notes/release-notes-1.3.md +++ b/content/docs/release-notes/release-notes-1.3.md @@ -49,7 +49,7 @@ The only impact to Venafi Cloud users is the change in zone syntax. The zone is now `\` (e.g. `My Application\My CIT`). -[Venafi Cloud Issuer]: https://cert-manager.io/docs/configuration/venafi/ +[Venafi Cloud Issuer]: https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/venafi/ ### cert-manager controller @@ -105,4 +105,4 @@ The `--renew-before-expiration-duration` flag has been removed from the cert-man * cert-manager now can be built with go 1.16 on Apple Silicon. * Docker images targets have been added to the Makefile. -* Bazel `v3.5.0` is required to build locally and to run tests. \ No newline at end of file +* Bazel `v3.5.0` is required to build locally and to run tests. diff --git a/content/docs/release-notes/release-notes-1.4.md b/content/docs/release-notes/release-notes-1.4.md index 4620620ae47..eed475edfc4 100644 --- a/content/docs/release-notes/release-notes-1.4.md +++ b/content/docs/release-notes/release-notes-1.4.md @@ -235,7 +235,7 @@ EdgeGrid` Go package. ## Bug Fixes -- The [RFC2136](https://cert-manager.io/docs/configuration/acme/dns01/rfc2136/) +- The [RFC2136](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/acme/dns01/rfc2136/) issuer is now able to handle DNS01 challenges that map to multiple `TXT` records. This lets you create Let's Encrypt certificates using RFC2136 with multiple DNS names. Fixed in the cert-manager PR [#3622][]. @@ -376,4 +376,4 @@ After a lot of thinking, we have decided that trying to support every custom resource for every proxy could not be done in-tree due to the Go dependency weight that each integration adds. Jake Sanders proposed an [out-of-tree approach](https://github.com/cert-manager/cert-manager/issues/3924) that will be -worked on as part of cert-manager 1.5. \ No newline at end of file +worked on as part of cert-manager 1.5. diff --git a/content/docs/release-notes/release-notes-1.7.md b/content/docs/release-notes/release-notes-1.7.md index e2943957a14..e122d66d83d 100644 --- a/content/docs/release-notes/release-notes-1.7.md +++ b/content/docs/release-notes/release-notes-1.7.md @@ -128,7 +128,7 @@ can be requested for the same certificate. Read [Additional Certificate Output Formats] for more details and thanks to [@seuf](https://github.com/seuf) for getting this across the line! -[Additional Certificate Output Formats]: ../usage/certificate.md#additional-certificate-output-formats +[Additional Certificate Output Formats]: ../configuration/certificate-resources.md#additional-certificate-output-formats #### Server-Side Apply diff --git a/content/docs/troubleshooting/acme.md b/content/docs/troubleshooting/acme.md index 11188db640d..6cb71f88135 100644 --- a/content/docs/troubleshooting/acme.md +++ b/content/docs/troubleshooting/acme.md @@ -209,11 +209,11 @@ If your challenge self-check fails with a 404 not found error. Make sure to chec ### DNS01 troubleshooting 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. +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/issuer-and-clusterissuer-resources/acme/dns01/README.md#setting-nameservers-for-dns01-self-check) as some cloud providers overwrite DNS internally. #### cert-manager identifies the wrong zone for your domain name cert-manager by default uses SOA (Start of Authority) records to determine which zone name to use at your DNS provider. -Some DNS resolvers will filter this information, if this is the case cert-manager cannot determine the zone and it is advised to [change the DNS server for DNS01 self-checks](../configuration/acme/dns01/README.md#setting-nameservers-for-dns01-self-check). +Some DNS resolvers will filter this information, if this is the case cert-manager cannot determine the zone and it is advised to [change the DNS server for DNS01 self-checks](../configuration/issuer-and-clusterissuer-resources/acme/dns01/README.md#setting-nameservers-for-dns01-self-check). If you use `dnsmasq` as your DNS server, this may occur if you use the [`--filterwin2k` flag](http://www.thekelleys.org.uk/dnsmasq/docs/setup.html). In [OpenWRT there is a `filterwin2k` configuration option](https://openwrt.org/docs/guide-user/base-system/dhcp#all_options). diff --git a/content/docs/tutorials/acme/dns-validation.md b/content/docs/tutorials/acme/dns-validation.md index bddf11097bf..02f0945d54c 100644 --- a/content/docs/tutorials/acme/dns-validation.md +++ b/content/docs/tutorials/acme/dns-validation.md @@ -18,7 +18,7 @@ have control of the domains DNS records. The following Issuer defines the necessary information to enable DNS validation. You can read more about the Issuer resource in the [Issuer -docs](../../configuration/README.md). +docs](../../configuration/issuer-and-clusterissuer-resources/README.md). ```yaml apiVersion: cert-manager.io/v1 @@ -88,7 +88,7 @@ solve DNS challenges. Our Issuer defines two providers. This gives us a choice of which one to use when obtaining certificates. More information about the DNS provider configuration, including a list of -supported providers, can be found [in the DNS01 reference docs](../../configuration/acme/dns01/README.md). +supported providers, can be found [in the DNS01 reference docs](../../configuration/issuer-and-clusterissuer-resources/acme/dns01/README.md). Once we have created the above Issuer we can use it to obtain a certificate. @@ -166,4 +166,4 @@ example-com-tls -o yaml`. You should see a base64 encoded signed TLS key pair. Once our certificate has been obtained, cert-manager will periodically check its validity and attempt to renew it if it gets close to expiry. cert-manager considers certificates to be close to expiry when the 'Not After' field on the -certificate is less than the current time plus 30 days. \ No newline at end of file +certificate is less than the current time plus 30 days. diff --git a/content/docs/tutorials/acme/nginx-ingress.md b/content/docs/tutorials/acme/nginx-ingress.md index b51bbef46bd..3dd994075f3 100644 --- a/content/docs/tutorials/acme/nginx-ingress.md +++ b/content/docs/tutorials/acme/nginx-ingress.md @@ -275,7 +275,7 @@ kubectl create --edit -f https://raw.githubusercontent.com/cert-manager/website/ # expected output: issuer.cert-manager.io "letsencrypt-prod" created ``` -Both of these issuers are configured to use the [`HTTP01`](../../configuration/acme/http01/README.md) challenge provider. +Both of these issuers are configured to use the [`HTTP01`](../../configuration/issuer-and-clusterissuer-resources/acme/http01/README.md) challenge provider. Check on the status of the issuer after you create it: diff --git a/content/docs/tutorials/acme/pomerium-ingress.md b/content/docs/tutorials/acme/pomerium-ingress.md index 9c8fcf6fc3e..0af7dc52122 100644 --- a/content/docs/tutorials/acme/pomerium-ingress.md +++ b/content/docs/tutorials/acme/pomerium-ingress.md @@ -74,7 +74,7 @@ For communication between the Ingresses and the internet, we'll want to use cert 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/README.md) challenge provider. +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/issuer-and-clusterissuer-resources/acme/http01/README.md) 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. 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 9286e8c26ca..ff3a40abaf7 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 @@ -384,7 +384,7 @@ Status: > ⚠️ In the next step you will see a warning about untrusted certificates because > we start with the staging issuer, but that's totally expected. > -> 🔰 Read more about [configuring the ACME Issuer](../configuration/acme). +> 🔰 Read more about [configuring the ACME Issuer](../configuration/issuer-and-clusterissuer-resources/acme). ## 8. Re-configure the Ingress for SSL diff --git a/content/docs/tutorials/istio-csr/istio-csr.md b/content/docs/tutorials/istio-csr/istio-csr.md index fc58cdc0578..dc7ee70b959 100644 --- a/content/docs/tutorials/istio-csr/istio-csr.md +++ b/content/docs/tutorials/istio-csr/istio-csr.md @@ -49,7 +49,7 @@ kubectl create namespace istio-system An Issuer tells cert-manager how to issue certificates; we'll create a self-signed root CA in our cluster because it's really simple to configure. -The approach of using a locally generated root certificate would work in a production deployment too, but there are also several [other issuers](https://cert-manager.io/docs/configuration/) in cert-manager which could be used. Note that the ACME issuer **will not work**, since it can't add the required fields to issued certificates. +The approach of using a locally generated root certificate would work in a production deployment too, but there are also several [other issuers](https://cert-manager.io/docs/configuration/issuer-and-clusterissuer-resources/) in cert-manager which could be used. Note that the ACME issuer **will not work**, since it can't add the required fields to issued certificates. There are also some comments on the [example-issuer](https://github.com/cert-manager/website/blob/master/content/docs/tutorials/istio-csr/example/example-issuer.yaml) providing a little more detail. Note also that this guide only uses `Issuer`s and not `ClusterIssuer`s - using a `ClusterIssuer` isn't a drop-in replacement, and in any case we recommend that production deployments use Issuers for easier access controls and scoping. diff --git a/content/docs/tutorials/venafi/venafi.md b/content/docs/tutorials/venafi/venafi.md index 2fe856e37dc..37a562b2529 100644 --- a/content/docs/tutorials/venafi/venafi.md +++ b/content/docs/tutorials/venafi/venafi.md @@ -385,7 +385,7 @@ correctly, we can begin requesting certificates which can be used by Kubernetes applications. Full information on how to specify and request Certificate resources can be -found in the [Issuing certificates](../../usage/certificate.md) guide. +found in the [Issuing certificates](../../configuration/certificate-resources.md) guide. For now, we will create a basic X.509 Certificate that is valid for our domain, `example.com`: @@ -583,4 +583,4 @@ Once this has been created, you should be able to visit your application at the configured URL, here `example.com`! Navigate to the address in your web browser and you should see the certificate -obtained via Venafi being used to secure application traffic. \ No newline at end of file +obtained via Venafi being used to secure application traffic. diff --git a/content/docs/usage/README.md b/content/docs/usage/README.md index b0d93801a94..1803360599e 100644 --- a/content/docs/usage/README.md +++ b/content/docs/usage/README.md @@ -3,11 +3,11 @@ title: Issuing Certificates description: 'cert-manager usage: Overview' --- -Once an [`Issuer`](../configuration/README.md) has been configured, you're ready to issue your first certificate! +Once an [`Issuer`](../configuration/issuer-and-clusterissuer-resources/README.md) has been configured, you're ready to issue your first certificate! There are several use cases and methods for requesting certificates through cert-manager: -- [Certificate Resources](./certificate.md): The simplest and most common method for +- [Certificate Resources](../configuration/certificate-resources.md): The simplest and most common method for requesting signed certificates. - [Securing Ingress Resources](./ingress.md): A method to secure ingress resources in your cluster. diff --git a/content/docs/usage/gateway.md b/content/docs/usage/gateway.md index ce52268c13c..75999e4eb04 100644 --- a/content/docs/usage/gateway.md +++ b/content/docs/usage/gateway.md @@ -10,7 +10,7 @@ description: 'cert-manager usage: Kubernetes Gateways' 📌 This page focuses on automatically creating Certificate resources by annotating Gateway resource. If you are looking for using an ACME Issuer along with HTTP-01 challenges using the Gateway API, see [ACME -HTTP-01](../configuration/acme/http01/README.md). +HTTP-01](../configuration/issuer-and-clusterissuer-resources/acme/http01/README.md). diff --git a/content/docs/usage/kube-csr.md b/content/docs/usage/kube-csr.md index dab4da9f894..e863641d81a 100644 --- a/content/docs/usage/kube-csr.md +++ b/content/docs/usage/kube-csr.md @@ -16,7 +16,7 @@ and they still wish for certificates to be signed through cert-manager. CertificateSigningRequests reference a `SignerName` or signer as the entity it wishes to sign its request from. For cert-manager, a signer can be mapped to -either an [Issuer or ClusterIssuer](../configuration/README.md). +either an [Issuer or ClusterIssuer](../configuration/issuer-and-clusterissuer-resources/README.md). #### Feature State @@ -44,10 +44,10 @@ $ helm install \ ``` > Note: cert-manager supports signing CertificateSigningRequests -> using all [internal Issuers](../configuration/README.md). +> using all [internal Issuers](../configuration/issuer-and-clusterissuer-resources/README.md). > Note: cert-manager _does not_ automatically approve CertificateSigningRequests -> that reference a cert-manager [Issuer](../configuration/README.md). Please refer to +> that reference a cert-manager [Issuer](../configuration/issuer-and-clusterissuer-resources/README.md). Please refer to > the [Kubernetes documentation](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/#request-signing-process) > for the request process of CertificateSigningRequests. @@ -157,10 +157,10 @@ Signer annotations: CertificateSigningRequests can be manually created using [cmctl](./cmctl.md#experimental). This command takes a manifest file containing a -[Certificate](../usage/certificate.md) resource as input. This generates a +[Certificate](../configuration/certificate-resources.md) resource as input. This generates a private key and creates a CertificateSigningRequest. CertificateSigningRequests are not approved by default, so you will likely need to approve it manually: ```bash $ kubectl certificate approve -``` \ No newline at end of file +``` diff --git a/public/_redirects b/public/_redirects index 1165674e123..4d0fefcbc4d 100644 --- a/public/_redirects +++ b/public/_redirects @@ -182,3 +182,15 @@ https://docs.cert-manager.io/* https://cert-manager.io/docs/:splat 302! # Demoted the cmctl x install page /docs/installation/cmctl/ /docs/reference/cmctl/ 301! + + +# Moved Issuer and ClusterIssuer resources to a subdirectory +/docs/configuration/acme/* /docs/configuration/issuer-and-clusterissuer-resources/acme/:splat 301! +/docs/configuration/ca/ /docs/configuration/issuer-and-clusterissuer-resources/ca/ 301! +/docs/configuration/external/ /docs/configuration/issuer-and-clusterissuer-resources/external/ 301! +/docs/configuration/selfsigned/ /docs/configuration/issuer-and-clusterissuer-resources/selfsigned/ 301! +/docs/configuration/vault/ /docs/configuration/issuer-and-clusterissuer-resources/vault/ 301! +/docs/configuration/venafi/ /docs/configuration/issuer-and-clusterissuer-resources/venafi/ 301! + +# Moved Certificate resources documentation from usage to configuration +/docs/usage/certificate/ /docs/configuration/certificate-resources/ 301!