weiguoqiang/cert-manager
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Merge pull request #131 from dippynark/create-use-case-focused-tutorials

Browse Source 
Automatic merge from submit-queue.

Create use-case focused tutorials
This commit is contained in:
jetstack-bot 2017-10-23 21:24:46 +01:00 committed by GitHub
commit 3f54dad575
10 changed files with 396 additions and 130 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

136
README.md
View File

@ -21,7 +21,7 @@ feeling brave, please do try cert-manager and report your experience here in
the issue section.
**NOTE:** currently we provide no guarantees on our API stability. This means
there may be breaking changes that will require changes to *all* Issuer/Certificate
there may be breaking changes that will require changes to *all* `Issuer`/`Certificate`
resources you have already created. We aim to provide a stable API after a 1.0
release.
@ -29,14 +29,7 @@ release.
> Prebuilt images for cert-manager are made available on Dockerhub.
This guide sets up cert-manager to run as a Deployment on your Kubernetes
cluster.
It will then go on to set up the [Let's Encrypt ACME staging server](https://letsencrypt.org/docs/staging-environment/)
as a Certificate issuer, and request a Certificate for a domain you control
using both the HTTP01 and DNS01 challenge mechanisms.
By default, it will be configured to fulfil Certificate resources in all
namespaces.
This guide sets up cert-manager to run as a Deployment on your Kubernetes cluster. It will then describe the best places to find the information you need to set up an `Issuer` in your cluster and to start provisioning certificates using `Certificate` resources.
### 0. Pre-requisites
@ -45,122 +38,27 @@ support
### 1. Deploy cert-manager using Helm
To deploy the latest version of cert-manager using Helm, run:
To deploy the latest version of cert-manager, follow the [Deploying cert-manager using Helm](docs/user-guides/helm.md) user guide.
```
$ helm install --name cert-manager --namespace kube-system contrib/charts/cert-manager
```
### 2. Set up an Issuer
There are a number of options you can customise when deploying, as detailed in
[the chart itself](https://github.com/jetstack-experimental/cert-manager/tree/master/contrib/charts/cert-manager).
An `Issuer` in cert-manager describes a source for signed TLS certificates that cert-manager can use to fulfil `Certificate` resources in a Kubernetes cluster. You can read more about the `Issuer` resource [here][2].
### 2. Set up letsencrypt staging issuer
An Issuer in cert-manager describes a source for signed TLS certificates that
cert-manager can use to fulfil Certificate resources in a Kubernetes cluster.
Within the Issuer's spec, we can define any configuration that may be required
(e.g. credentials for updating a DNS server) on a per-issuer basis.
In the below example, you **must** remember to fill in the `spec.acme.email`
field.
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
name: letsencrypt-staging
spec:
acme:
# The ACME server URL
server: https://acme-staging.api.letsencrypt.org/directory
# Email address used for ACME registration
email: ""
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsencrypt-staging
# Enable the HTTP-01 challenge provider
http01: {}
# ACME dns-01 provider configurations
dns01:
# Here we define a list of DNS-01 providers that can solve DNS challenges
providers:
# We define a provider named 'prod-dns', with configuration for the
# clouddns challenge provider.
- name: prod-dns
clouddns:
# A secretKeyRef to a the google cloud json service account
serviceAccountSecretRef:
name: clouddns-service-account
key: service-account.json
# The project in which to update the DNS zone
project: gcloud-prod-project
```
This is an example Issuer for the letsencrypt staging server. Here, we define
one DNS provider, named clouddns, that can be used to solve ACME challenges.
HTTP-01 is also supported without additional configuration when using the ACME
issuer.
Upon creation of the Issuer, any initial preparation for that Issuer will be
performed, e.g. for the ACME issuer, an account is registered with the ACME
server specified in the spec, and a corresponding private key generated too if
required.
Multiple Issuers may exist at any one time, and they should be referenced by
name in a Certificate resource. The Issuer and Certificate resource must exist
in the same namespace, as cert-manager does not allow the traversal of
namespace boundaries.
If you would like to deploy a cluster-wide issuer, you can deploy a
ClusterIssuer. The structure of a ClusterIssuer is identical to that of an
Issuer. You can find more information in the [Issuer api type docs](docs/api-types/issuer).
The [user guides](docs/user-guides) cover common ways to configure an `Issuer`.
### 3. Create a Certificate resource
Now we have an Issuer configured, we can create a Certificate resource that
uses it. A Certificate represents the lifecycle of a TLS certificate in your
cluster. When a Certificate is created, cert-manager will verify the
Now we have an `Issuer` configured, we can create a `Certificate` resource that
uses it. A `Certificate` represents the lifecycle of a TLS certificate in your
cluster. When a `Certificate` is created, cert-manager will verify the
certificate is valid for the requested domains and if not, will attempt to
retrieve a signed Certificate from the specified Issuer.
retrieve a signed `Certificate` from the specified `Issuer.`
```yaml
## Example Certificate that uses multiple challenge mechanisms to obtain
## a SAN certificate for multiple domains from the letsencrypt-staging issuer.
apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
name: example-com
spec:
# The name of the Kubernetes secret resource to store the signed TLS keypair
secretName: example-com
# The Issuer to use for this certificate
issuerRef:
name: letsencrypt-staging
# A list of domains to include on the TLS certificate
dnsNames:
- example.com
- www.example.com
- example2.com
acme:
# A pairing of domains to challenge types for the ACME provider to use
# when attempting to validate domain ownership for the listed domains
config:
- domains:
- example.com
- www.example.com
http01:
ingressClass: nginx
- domains:
- example2.com
dns01:
provider: prod-dns
```
The [user guides](docs/user-guides) cover common ways to obtain `Certificates` using a configured `Issuer`.
### 4. Ensuring the Certificate request has been fulfiled
cert-manager logs events about Issuers and Certificates back to the Kubernetes
cert-manager logs events about `Issuers` and `Certificates` back to the Kubernetes
API in the form of Event resources.
You can check the events produced about a Certificate with `kubectl describe`:
@ -185,13 +83,7 @@ Events:
Normal CeritifcateIssued 5s cert-manager-controller Certificated issued successfully
```
You can also check the signed TLS keypair exists with:
```
$ kubectl get secret -o yaml example-com
```
You should see a base64 encoded TLS keypair if issuance was successful.
You can also check whether issuance was successful with `kubectl get secret -o yaml`. You should see a base64 encoded signed TLS key pair.
## Further documentation
@ -215,7 +107,7 @@ if you are unsure where to start with getting involved!
We also use the #kube-lego channel on kubernetes.slack.com for chat relating
to the project.
Developer documentation should soon be available at [docs/devel](docs/devel).
Developer documentation should be available soon at [docs/devel](docs/devel).
## Changelog

9
docs/README.md
View File

@ -12,11 +12,10 @@ It is split into these three sections for easier navigation.
## User guides
* Creating a simple CA based issuer
* Creating cluster wide issuers
* Creating an ACME Issuer
* Issuing an ACME certificate using an ingress controller
* Issuing an ACME certificate using DNS validation
* [Creating a simple CA based issuer](user-guides/ca-based-issuer.md)
* [Creating cluster wide issuers](user-guides/cluster-issuers.md)
* [Issuing an ACME certificate using HTTP validation](user-guides/acme-http-validation.md)
* [Issuing an ACME certificate using DNS validation](user-guides/acme-dns-validation.md)
## Developer docs

2
docs/examples/acme-cert.yaml
View File

@ -22,7 +22,7 @@ spec:
- cm-http-nginx.k8s.group
- cm-http-nginx2.k8s.group
- http01:
ingressName: my-gce-ingress
ingress: my-gce-ingress
domains:
- cm-http-gce.k8s.group
- dns01:

4
docs/examples/acme-issuer.yaml
View File

@ -10,7 +10,7 @@ spec:
email: user@example.com
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsncrypt-prod
name: letsencrypt-prod
# Enable the HTTP-01 challenge provider
http01: {}
# ACME dns-01 provider configurations
@ -28,7 +28,7 @@ spec:
- name: cf-dns
cloudflare:
email: user@example.com
# A secretKeyRef to a the google cloud json service account
# A secretKeyRef to a cloudflare api key
apiKeySecretRef:
name: cloudflare-api-key
key: api-key.txt

8
docs/user-guides/README.md
View File

@ -0,0 +1,8 @@
# User guides
This section of the documentation contains user guides for cert-manager. Full specifications of the different options in cert-manager can be found in [`docs/api-types`](../api-types).
* [Creating a simple CA based issuer](ca-based-issuer.md)
* [Creating cluster wide issuers](cluster-issuers.md)
* [Issuing an ACME certificate using HTTP validation](acme-http-validation.md)
* [Issuing an ACME certificate using DNS validation](acme-dns-validation.md)

112
docs/user-guides/acme-dns-validation.md Normal file
View File

@ -0,0 +1,112 @@
# Issuing an ACME certificate using DNS validation
cert-manager can be used to obtain certificates from a CA using the [ACME][1] protocol. The ACME protocol supports various challenge mechanisms which are used to prove ownership of a domain so that a valid certificate can be issued for that domain. One such challenge mechanism is DNS-01. With a DNS-01 challenge, you prove ownership of a domain by proving you control its DNS records. This is done by creating a TXT record with specific content.
The following `Issuer` defines the necessary information to enable DNS validation. You can read more about the `Issuer` resource [here][2].
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
name: letsencrypt-staging
namespace: default
spec:
acme:
# The ACME server URL
server: https://acme-staging.api.letsencrypt.org/directory
# Email address used for ACME registration
email: user@example.com
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsencrypt-staging
# ACME DNS-01 provider configurations
dns01:
# Here we define a list of DNS-01 providers that can solve DNS challenges
providers:
- name: prod-dns
clouddns:
# A secretKeyRef to a google cloud json service account
serviceAccountSecretRef:
name: clouddns-service-account
key: service-account.json
# The project in which to update the DNS zone
project: gcloud-prod-project
- name: cf-dns
cloudflare:
email: user@example.com
# A secretKeyRef to a cloudflare api key
apiKeySecretRef:
name: cloudflare-api-key
key: api-key.txt
```
We have specified the ACME server URL for Let's Encrypt's [staging environment][3]. The staging environment will not issue trusted certificates but is used to ensure that the verification process is working properly before moving to production. Let's Encrypt's production environment imposes much stricter [rate limits][4], so to reduce the chance of you hitting those limits it is highly recommended to start by using the staging environment. To move to production, simply create a new `Issuer` with the URL set to `https://acme-v01.api.letsencrypt.org/directory`.
The first stage of the ACME protocol is for the client to register with the ACME server. This phase includes generating an asymmetric key pair which is then associated with the email address specified in the `Issuer`. Make sure to change this email address to a valid one that you own. It is commonly used to send expiry notices when your certificates are coming up for renewal. The generated private key is stored in a `Secret` called `letsencrypt-staging`.
The `dns01` stanza contains a list of DNS-01 providers that can be used to 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 currently supported providers, can be found [here][5].
Once we have created the above `Issuer` we can use it to obtain a certificate.
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
issuerRef:
name: letsencrypt-staging
commonName: example.com
dnsNames:
- www.example.com
acme:
config:
- dns01:
provider: clouddns
domains:
- example.com
- dns01:
provider: cloudflare
domains:
- www.example.com
```
The `Certificate` resource describes our desired certificate and the possible methods that can be used to obtain it. You can learn more about the `Certificate` resource [here][7]. If the certificate is obtained successfully, the resulting key pair will be stored in a secret called `example-com-tls` in the same namespace as the `Certificate`. The certificate will have a common name of `example.com` and the [Subject Alternative Names][6] (SANs) will be `example.com` and `www.example.com`.
In our `Certficate` we have referenced the `letsencrypt-staging` `Issuer` above. The `Issuer` must be in the same namespace as the `Certficate`. If you want to reference a `ClusterIssuer`, which is a cluster-scoped version of an `Issuer`, you must add `kind: ClusterIssuer` to the `issuerRef` stanza. For more information on `ClusterIssuers`, read the [Creating cluster wide Issuers][8] user guide.
The `acme` stanza defines the configuration for our ACME challenges. Here we have defined the configuration for our DNS challenges which will be used to verify domain ownership. For each domain mentioned in a `dns01` stanza, cert-manager will use the provider's credentials from the referenced `Issuer` to create a TXT record called `_acme-challenge`. This record will then be verified by the ACME server in order to issue the certificate. Once domain ownership has been verified, any cert-manager affected records will be cleaned up. Note that it is your responsibility to ensure the provider is authoritative for your domain.
After creating the above `Certificate`, we can check whether it has been obtained successfully using `kubectl describe`:
```
$ kubectl describe certificate example-com
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning ErrorCheckCertificate 33s cert-manager-controller Error checking existing TLS certificate: secret "example-com-tls" not found
Normal PrepareCertificate 33s cert-manager-controller Preparing certificate with issuer
Normal PresentChallenge 33s cert-manager-controller Presenting dns-01 challenge for domain example.com
Normal PresentChallenge 33s cert-manager-controller Presenting dns-01 challenge for domain www.example.com
Normal SelfCheck 32s cert-manager-controller Performing self-check for domain example.com
Normal SelfCheck 32s cert-manager-controller Performing self-check for domain www.example.com
Normal ObtainAuthorization 6s cert-manager-controller Obtained authorization for domain example.com
Normal ObtainAuthorization 6s cert-manager-controller Obtained authorization for domain www.example.com
Normal IssueCertificate 6s cert-manager-controller Issuing certificate...
Normal CeritifcateIssued 5s cert-manager-controller Certificated issued successfully
```
You can also check whether issuance was successful with `kubectl get secret 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.
[1]: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment
[2]: ../api-types/issuer/
[3]: https://letsencrypt.org/docs/staging-environment/
[4]: https://letsencrypt.org/docs/rate-limits/
[5]: ../api-types/issuer/spec.md#user-content-acme-issuer-dns-provider-configuration
[6]: https://en.wikipedia.org/wiki/Subject_Alternative_Name
[7]: ../api-types/certificate/
[8]: cluster-issuers.md

103
docs/user-guides/acme-http-validation.md Normal file
View File

@ -0,0 +1,103 @@
# Issuing an ACME certificate using HTTP validation
cert-manager can be used to obtain certificates from a CA using the [ACME][1] protocol. The ACME protocol supports various challenge mechanisms which are used to prove ownership of a domain so that a valid certificate can be issued for that domain. One such challenge mechanism is the HTTP-01 challenge. With a HTTP-01 challenge, you prove ownership of a domain by ensuring that a particular file is present at the domain. It is assumed that you control the domain if you are able to publish the given file under a given path.
The following `Issuer` defines the necessary information to enable HTTP validation. You can read more about the `Issuer` resource [here][5].
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
name: letsencrypt-staging
namespace: default
spec:
acme:
# The ACME server URL
server: https://acme-staging.api.letsencrypt.org/directory
# Email address used for ACME registration
email: user@example.com
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsencrypt-staging
# Enable the HTTP-01 challenge provider
http01: {}
```
We have specified the ACME server URL for Let's Encrypt's [staging environment][3]. The staging environment will not issue trusted certificates but is used to ensure that the verification process is working properly before moving to production. Let's Encrypt's production environment imposes much stricter [rate limits][4], so to reduce the chance of you hitting those limits it is highly recommended to start by using the staging environment. To move to production, simply create a new `Issuer` with the URL set to `https://acme-v01.api.letsencrypt.org/directory`.
The first stage of the ACME protocol is for the client to register with the ACME server. This phase includes generating an asymmetric key pair which is then associated with the email address specified in the `Issuer`. Make sure to change this email address to a valid one that you own. This is commonly used to send expiry notices when your certificates are coming up for renewal. The generated private key is stored in a `Secret` called `letsencrypt-staging`.
The presence of the `http01` field simply enables the HTTP-01 challenge for this `Issuer`. No further configuration is necessary or currently possible.
Once we have created the above `Issuer` we can use it to obtain a certificate.
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
issuerRef:
name: letsencrypt-staging
commonName: example.com
dnsNames:
- www.example.com
acme:
config:
- http01:
ingressClass: nginx
domains:
- example.com
- http01:
ingress: my-ingress
domains:
- www.example.com
```
The `Certificate` resource describes our desired certificate and the possible methods that can be used to obtain it. You can learn more about the `Certificate` resource [here][4]. If the certificate is obtained successfully, the resulting key pair will be stored in a secret called `example-com-tls` in the same namespace as the `Certificate`. The certificate will have a common name of `example.com` and the [Subject Alternative Names][6] (SANs) will be `example.com` and `www.example.com`.
In our `Certficate` we have referenced the `letsencrypt-staging` `Issuer` above. The `Issuer` must be in the same namespace as the `Certficate`. If you want to reference a `ClusterIssuer`, which is a cluster-scoped version of an `Issuer`, you must add `kind: ClusterIssuer` to the `issuerRef` stanza. For more information on `ClusterIssuers`, read the [Creating cluster wide Issuers][7] user guide.
The `acme` stanza defines the configuration for our ACME challenges. Here we have defined the configuration for our HTTP-01 challenges which will be used to verify domain ownership. To verify ownership of each domain mentioned in an `http01` stanza, cert-manager will create a `Pod` that exposes an HTTP endpoint that satisfies the HTTP-01 challenge. For each `http01` stanza, cert-manager will create or modify an `Ingress` resource in the same namespace as the `Certificate` with the correct rules to route incoming challenge requests to the `Pods` corresponding to the domains in that stanza.
The fields `ingress` and `ingressClass` in the `http01` stanza can be used to control how cert-manager interacts with `Ingress` resources:
* If the `ingress` field is specified, then an `Ingress` resource with the same name in the same namespace as the `Certificate` must already exist and it will be modified only to add the appropriate rules to solve the challenge. This field is useful for the GCLB ingress controller, as well as a number of others, that assign a single public IP address for each ingress resource. Without manual intervention, creating a new ingress resource would cause any challenges to fail.
* If the `ingressClass` field is specified, a new ingress resource with a randomly generated name will be created in order to solve the challenge. This new resource will have an annotation with key `kubernetes.io/ingress.class` and value set to the value of the `ingressClass` field. This works for the likes of the NGINX `Ingress` controller.
* If neither are specified, new ingress resources will be created with a randomly generated name, but they will not have the ingress class annotation set.
* If both are specified, then the `ingress` field will take precedence.
Once domain ownership has been verified, any cert-manager affected resources will be cleaned up or deleted. Note that it is your responsibilty to point each domain name at the correct IP address for your ingress controller.
After creating the above `Certificate`, we can check whether it has been obtained successfully using `kubectl describe`:
```
$ kubectl describe certificate example-com
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning ErrorCheckCertificate 33s cert-manager-controller Error checking existing TLS certificate: secret "example-com-tls" not found
Normal PrepareCertificate 33s cert-manager-controller Preparing certificate with issuer
Normal PresentChallenge 33s cert-manager-controller Presenting http-01 challenge for domain example.com
Normal PresentChallenge 33s cert-manager-controller Presenting http-01 challenge for domain www.example.com
Normal SelfCheck 32s cert-manager-controller Performing self-check for domain example.com
Normal SelfCheck 32s cert-manager-controller Performing self-check for domain www.example.com
Normal ObtainAuthorization 6s cert-manager-controller Obtained authorization for domain example.com
Normal ObtainAuthorization 6s cert-manager-controller Obtained authorization for domain www.example.com
Normal IssueCertificate 6s cert-manager-controller Issuing certificate...
Normal CeritifcateIssued 5s cert-manager-controller Certificated issued successfully
```
You can also check whether issuance was successful with `kubectl get secret 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.
[1]: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment
[2]: https://letsencrypt.org/docs/staging-environment/
[3]: https://letsencrypt.org/docs/rate-limits/
[4]: ../api-types/certificate/
[5]: ../api-types/issuer/
[6]: https://en.wikipedia.org/wiki/Subject_Alternative_Name
[7]: cluster-issuers.md]

77
docs/user-guides/ca-based-issuer.md Normal file
View File

@ -0,0 +1,77 @@
# Creating a simple CA based issuer
cert-manager can be used to obtain certificates using a signing key pair. There are various tools you can use to generate your own key pair including [openssl][1] and [cfssl][2]. For a quick and basic CA, you can generate a signing key pair using openssl with the following commands:
* `openssl genrsa -out ca.key 2048`
* `openssl req -x509 -new -nodes -key ca.key -subj "/CN=${COMMON_NAME}" -days 3650 -out ca.crt`
The output of these commands will be two files, `ca.key` and `ca.crt`, the key and certificate for your signing key pair.
We are going to create an `Issuer` that will use this key pair to generate signed certificates. You can read more about the `Issuer` resource [here][3]. To allow the `Issuer` to reference our key pair we need to put it into a `Secret`. `Issuers` are namespaced resources and can only reference and create `Secrets` in their own namespace, so we will need to make sure to put our key pair `Secret` into the same namespace as our `Issuer`. We could alternatively create a `ClusterIssuer`, a cluster-scoped version of an `Issuer`. For more information on `ClusterIssuers`, read the [Creating cluster wide Issuers][6] user guide.
The following command will create a `Secret` containing our signing key pair in the default namespace.
```bash
$ kubectl create secret tls ca-key-pair --cert=/path/to/ca.crt --key=/path/to/ca.key --namespace default
```
We can now create an `Issuer` referencing our `Secret`.
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
name: ca-issuer
namespace: default
spec:
ca:
secretName: ca-key-pair
```
We are now ready to obtain certificates. We can create the following `Certificate` resource which specifies our desired certificate. You can read more about the `Certificate` resource [here][4]. Note that to use our `Issuer` above to obtain our certificate, we must create the `Certificate` resource in the same namespace as our `Issuer`.
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
issuerRef:
name: ca-issuer
# We can reference ClusterIssuers by changing the kind here.
# The default value is Issuer (i.e. a locally namespaced Issuer)
kind: Issuer
commonName: example.com
dnsNames:
- www.example.com
```
Once we have created the `Certificate` resource, cert-manager will attempt to use our `ca-issuer` to obtain a certificate. If successful, the certificate will be stored in a `Secret` called `example-com-tls` in the default namespace. Note that since we have specified the `commonName` then `example.com` will be the common name for our certificate and both the common name and all the elements of the `dnsNames` array will be [Subject Alternative Names][5] (SANs). If we had not specified the common name then the first element of the `dnsNames` array would be used as the common name and all elements of the `dnsNames` array would be SANs.
Note that since we have not specified the `commonName` on the `Certificate`, the first element of the `dnsNames` array will be used as the common name and all elements of the `dnsNames` array will be [Subject Alternative Names][5] (SANs). If we had specified the `commonName`, then the `commonName` and all the elements of the `dnsNames` array would be SANs.
After creating the above `Certificate`, we can check whether it has been obtained successfully using `kubectl describe`:
```
$ kubectl describe certificate example-com
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning ErrorCheckCertificate 26s cert-manager-controller Error checking existing TLS certificate: secret "example-com-tls" not found
Normal PrepareCertificate 26s cert-manager-controller Preparing certificate with issuer
Normal IssueCertificate 26s cert-manager-controller Issuing certificate...
Normal CeritifcateIssued 25s cert-manager-controller Certificated issued successfully
```
You can also check whether issuance was successful with `kubectl get secret example-com-tls -o yaml`. You should see a base64 encoded signed TLS key pair.
Once our certificate has been obtained, cert-manager will keep checking 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. For CA based `Issuers`, cert-manager will issue certificates with the 'Not After' field set to the current time plus 365 days.
[1]: https://github.com/openssl/openssl
[2]: https://github.com/cloudflare/cfssl
[3]: ../api-types/issuer/
[4]: ../api-types/certificate/
[5]: https://en.wikipedia.org/wiki/Subject_Alternative_Name
[6]: cluster-issuers.md

64
docs/user-guides/cluster-issuers.md Normal file
View File

@ -0,0 +1,64 @@
# Creating cluster wide Issuers
cert-manager has the concept of `ClusterIssuers`. These are a non-namespaced and cluster-scoped version of an `Issuer`. The specification of a `ClusterIssuer` is exactly the same as that of an `Issuer`, but there are a couple of nuances you need to be aware of.
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: ClusterIssuer
metadata:
name: ca-cluster-issuer
spec:
ca:
secretName: ca-key-pair
```
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: ClusterIssuer
metadata:
name: letsencrypt-staging-cluster-issuer
spec:
acme:
server: https://acme-staging.api.letsencrypt.org/directory
email: user@example.com
privateKeySecretRef:
name: letsencrypt-staging
http01: {}
```
The two manifests above define two `ClusterIssuers`. As `ClusterIssuer` resources do not specify a namespace, we must configure a namespace that cert-manager will use to store supporting resources required for each `ClusterIssuer`. We do this by specifying the `--cluster-resource-namespace` flag on the cert-manager controller. By default, this flag will be set to `kube-system`.
In order to reference a `ClusterIssuer` in a `Certificate` you must specify the `kind` in the `issuerRef` stanza. The following are two examples of `Certificates` that reference our `ClusterIssuers` above.
```yaml
kind: Certificate
metadata:
name: ca-crt
namespace: default
spec:
secretName: ca-crt-secret
issuerRef:
name: ca-cluster-issuer
kind: ClusterIssuer
dnsNames:
- cert-manager.k8s.io
```
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
name: nginx-k8s-io
namespace: default
spec:
secretName: nginx-k8s-io-tls
issuerRef:
name: letsencrypt-staging-cluster-issuer
kind: ClusterIssuer
commonName: nginx.k8s.io
acme:
config:
- http01: {}
domains:
- nginx.k8s.io
```

11
docs/user-guides/helm.md Normal file
View File

@ -0,0 +1,11 @@
# Deploying cert-manager using Helm
To deploy the latest version of cert-manager using Helm, run:
```
$ helm install --name cert-manager --namespace kube-system contrib/charts/cert-manager
```
By default, it will be configured to fulfil `Certificate` resources in all
namespaces. There are a number of options you can customise when deploying, as detailed in
[the chart itself](https://github.com/jetstack-experimental/cert-manager/tree/master/contrib/charts/cert-manager).