From 63b51be34df1be130bc782005253ffb8dd84c93d Mon Sep 17 00:00:00 2001 From: Luke Addison Date: Mon, 23 Oct 2017 23:37:21 +0100 Subject: [PATCH] Slim down main README, complete user guide list and change helm user guide structure --- README.md | 99 ++++++++------------------------------ docs/README.md | 1 + docs/user-guides/README.md | 1 + docs/user-guides/helm.md | 4 +- 4 files changed, 24 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index bc42cf388..d58115f26 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,58 @@ # 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 -TLS certificates from various issuing sources. +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 -to renew certificates at an appropriate time before expiry. +It will ensure certificates are valid and up to date periodically, and attempt to renew certificates at an appropriate time before expiry. -It is loosely based upon the work of [kube-lego](https://github.com/jetstack/kube-lego) -and has borrowed some wisdom from other similar projects e.g. -[kube-cert-manager](https://github.com/PalmStoneGames/kube-cert-manager). +It is loosely based upon the work of [kube-lego](https://github.com/jetstack/kube-lego) and has borrowed some wisdom from other similar projects e.g. [kube-cert-manager](https://github.com/PalmStoneGames/kube-cert-manager). ![cert-manager high level overview diagram](/docs/high-level-overview.png) ## 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. +This project is not yet ready to be a component in a critical production stack, 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. +**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. ## 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 `CustomResourceDefinition` or `ThirdPartyResource` support -* Kubernetes cluster with CustomResourceDefinitions or ThirdPartyResource -support +### Deploying cert-manager -### 1. Deploy cert-manager using Helm +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. -To deploy the latest version of cert-manager, follow the [Deploying cert-manager using Helm](docs/user-guides/helm.md) user guide. +### Creating your first Issuer and Certificate -### 2. Set up an Issuer +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: -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]. - -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 -For further documentation, please check the [/docs](/docs) directory in this -repository. +For further documentation, please check the [/docs](/docs) directory in this repository. ## Troubleshooting -If you encounter any issues whilst using cert-manager, and your issue is not -documented, please [file an issue](https://github.com/jetstack-experimental/cert-manager/issues). +If you encounter any issues whilst using cert-manager, and your issue is not documented, please [file an issue](https://github.com/jetstack-experimental/cert-manager/issues). ## Contributing -We welcome pull requests with open arms! There's a lot of work to do here, and -we're especially concerned with ensuring the longevity and reliability of the -project. +We welcome pull requests with open arms! There's a lot of work to do here, and we're especially concerned with ensuring the longevity and reliability of the 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! +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). ## Changelog -The [list of releases](https://github.com/jetstack-experimental/cert-manager/releases) -is the best place to look for information on changes between releases. +The [list of releases](https://github.com/jetstack-experimental/cert-manager/releases) is the best place to look for information on changes between releases. 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