diff --git a/README.md b/README.md index 2ed028ee3..bc42cf388 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/user-guides/helm.md b/docs/user-guides/helm.md new file mode 100644 index 000000000..02c97a8fd --- /dev/null +++ b/docs/user-guides/helm.md @@ -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). \ No newline at end of file