diff --git a/README.md b/README.md index bc42cf388..620b75e99 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # cert-manager [![Build Status](https://travis-ci.org/jetstack-experimental/cert-manager.svg?branch=master)](https://travis-ci.org/jetstack-experimental/cert-manager) -cert-manager is a Kubernetes addon to automate the management and issuance of +cert-manager is a Kubernetes add-on to automate the management and issuance of TLS certificates from various issuing sources. It will ensure certificates are valid and up to date periodically, and attempt @@ -15,75 +15,43 @@ and has borrowed some wisdom from other similar projects e.g. ## Current status This project is not yet ready to be a component in a critical production stack, -however is at a point where it offers comparable features to other projects -in the space. If you have a non-critical piece of infrastructure, or are -feeling brave, please do try cert-manager and report your experience here in -the issue section. +however it *is* at a point where it offers comparable features to other +projects in the space. If you have a non-critical piece of infrastructure, or +are 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` -resources you have already created. We aim to provide a stable API after a 1.0 -release. +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. ## Quickstart > 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 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. +### Pre-requisites -### 0. Pre-requisites - -* Kubernetes cluster with CustomResourceDefinitions or ThirdPartyResource +* Kubernetes cluster with `CustomResourceDefinition` or `ThirdPartyResource` support -### 1. Deploy cert-manager using Helm +### Deploying cert-manager -To deploy the latest version of cert-manager, follow the [Deploying cert-manager using Helm](docs/user-guides/helm.md) user guide. +The easiest way to deploy cert-manager into your cluster is to use the Helm +chart. For information on how to do this see the [Deploying cert-manager using +Helm](docs/user-guides/helm.md) user guide. -### 2. Set up an Issuer +### Creating your first Issuer and Certificate -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]. +An `Issuer` in cert-manager describes a source of X.509 certificates. A +`Certificate` in cert-manager defines a desired X.509 certificate. Below is a +list of user guides that can be used to get started with both resources: -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 -certificate is valid for the requested domains and if not, will attempt to -retrieve a signed `Certificate` from the specified `Issuer.` - -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 -API in the form of Event resources. - -You can check the events produced about a Certificate with `kubectl describe`: - -``` -$ kubectl describe certificate test-jetstack-net -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Warning ErrorCheckCertificate 33s cert-manager-controller Error checking existing TLS certificate: secret "example-com" 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 PresentChallenge 33s cert-manager-controller Presenting dns-01 challenge for domain example2.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 SelfCheck 32s cert-manager-controller Performing self-check for domain example2.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 ObtainAuthorization 6s cert-manager-controller Obtained authorization for domain example2.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 -o yaml`. You should see a base64 encoded signed TLS key pair. +* [Creating a simple CA based Issuer](docs/user-guides/ca-based-issuer.md) +* [Creating cluster wide Issuers](docs/user-guides/cluster-issuers.md) +* [Issuing an ACME certificate using HTTP +validation](docs/user-guides/acme-http-validation.md) +* [Issuing an ACME certificate using DNS +validation](docs/user-guides/acme-dns-validation.md) ## Further documentation @@ -104,8 +72,8 @@ project. Please take a look at our [issue tracker](https://github.com/jetstack-experimental/cert-manager/issues) 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. +We also use the #kube-lego channel on kubernetes.slack.com for chat relating to +the project. Developer documentation should be available soon at [docs/devel](docs/devel). diff --git a/docs/README.md b/docs/README.md index aa150c8f0..5dc125833 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ It is split into these three sections for easier navigation. ## User guides +* [Deploying cert-manager using Helm](user-guides/helm.md) * [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) diff --git a/docs/user-guides/README.md b/docs/user-guides/README.md index e44711cb2..6446c5400 100644 --- a/docs/user-guides/README.md +++ b/docs/user-guides/README.md @@ -2,6 +2,7 @@ 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). +* [Deploying cert-manager using Helm](helm.md) * [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) diff --git a/docs/user-guides/helm.md b/docs/user-guides/helm.md index 02c97a8fd..948856fea 100644 --- a/docs/user-guides/helm.md +++ b/docs/user-guides/helm.md @@ -6,6 +6,4 @@ 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 +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