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

Merge pull request #146 from dippynark/slim-down-main-readme

Browse Source 
Automatic merge from submit-queue.

Slim down main README, complete user guide list and change helm user …

**What this PR does / why we need it**: This PR slims down the main README and links out to further  user guides and documentation. This allows users of cert-manager to find the information they are after more easily
This commit is contained in:
jetstack-bot 2017-10-24 01:44:40 +01:00 committed by GitHub
commit 5d3a3296ba
4 changed files with 29 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@ -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).

1
docs/README.md
View File

@ -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)

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

@ -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)

4
docs/user-guides/helm.md
View File

@ -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).
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).