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

Add migrating from kube-lego document

Browse Source
This commit is contained in:
James Munnelly 2018-01-18 16:47:33 +00:00
parent 7400a13c6f
commit 13f91a6570
1 changed files with 245 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

245
docs/user-guides/migrating-from-kube-lego.md Normal file
View File

@ -0,0 +1,245 @@
# Migrating from kube-lego
[kube-lego](https://github.com/jetstack/kube-lego) is an older Jetstack project
for obtaining TLS certificates from Let's Encrypt (or another ACME server).
Since cert-managers release, kube-lego has been gradually deprecated in favour
of this project. There are a number of key differences between the two:
| | kube-lego | cert-manager |
| --------- | --------- | ------------ |
| Configuration | Annotations on Ingress resources | CRDs |
| CAs | ACME **only** | ACME, signing keypair |
| Kubernetes | v1.2 - v1.8 | v1.7+ (v1.6+ after [#201](https://github.com/jetstack/cert-manager/issues/201)) |
| Debugging | Look at logs | Kubernetes Events API |
| Multi-tenancy | Not supported | Supported |
| Distinct issuance sources per Certificate | Not supported | Supported |
| Ingress controller support (ACME) | GCE, nginx | All |
This guide will walk through how you can safely migrate your kube-lego installation to cert-manager, without service interruption.
By the end of the guide, we should have:
* Scaled down and removed kube-lego
* Installed cert-manager
* Migrated ACME private key to cert-manager
* Created an ACME ClusterIssuer using this private key, to issue certificates
throughout your cluster
* Configured cert-manager's [ingress-shim](ingress-shim.md) to automatically
provision Certificate resources for all Ingress resources with the
`kubernetes.io/tls-acme: "true"` annotation, using the ClusterIssuer we have
created
## Step 1 - scale down kube-lego
Before we begin deploying cert-manager, it is best we scale our kube-lego deployment down to 0 replicas. This will prevent the two controllers potentially 'fighting' each other. If you deployed kube-lego using the official deployment YAMLs, a command like so should do:
```bash
$ kubectl scale \
--namespace kube-lego \
--replicas=0 \
deployment kube-lego
```
You can then verify your kube-lego pod is no longer running with:
```bash
$ kubectl get pods --namespace kube-lego
```
## Step 2 - deploy cert-manager
cert-manager should be deployed using Helm, according to our official
[deploying.md](deploying.md) guide. No special steps are required here. We will
return to this deployment at the end of this guide and perform an upgrade of
some of the CLI flags we deploy cert-manager with however.
Please take extra care to ensure you have configured RBAC correctly when
deploying Helm and cert-manager - there are some nuances described in our
deploying document!
## Step 3 - obtaining your ACME account private key
In order to continue issuing and renewing certificates on your behalf, we need
to migrate the user account private key that kube-lego has created for you over
to cert-manager.
Your ACME user account identity is a private key, stored in a secret resource.
By default, kube-lego will store this key in a secret named `kube-lego-account`
in the same namespace as your kube-lego Deployment. You may have overridden
this value when you deploy kube-lego, in which case the secret name to use will
be the value of the `LEGO_SECRET_NAME` environment variable.
You should download a copy of this secret resource and save it in your local
directory:
```bash
$ kubectl get secret \
-o yaml \
--namespace kube-lego \
--export \
kube-lego-account > kube-lego-account.yaml
```
Once saved, open up this file and change the `metadata.name` field to something
more relevant to cert-manager. For the rest of this guide, we'll assume you
chose `letsencrypt-private-key`.
Once done, we need to create this new resource in the `kube-system` namespace.
This is where cert-manager looks for supporting resources for ClusterIssuers
by default:
```bash
$ kubectl create \
--namespace kube-system
-f kube-lego-account.yaml
```
## Step 4 - creating an ACME ClusterIssuer using your old ACME account
We need to create a ClusterIssuer which will hold information about the ACME
account previously registered via kube-lego. In order to do so, we need two
more pieces of information from our old kube-lego deployment: the server URL of
the ACME server, and the email address used to register the account.
Both of these bits of information are stored within the kube-lego ConfigMap.
To retrieve them, you should be able to `get` the ConfigMap using `kubectl`:
```bash
$ kubectl get configmap \
-o yaml \
--namespace kube-lego \
--export \
kube-lego
```
Your email address should be shown under the `.data.lego.email` field, and the
ACME server URL under `.data.lego.url`.
For the purposes of this guide, we will assume the lego email is
`user@example.com` and the URL `https://acme-staging.api.letsencrypt.org/directory`.
Now that we have migrated our private key to the new Secret resource, as well
as obtaining our ACME email address and URL, we can create a ClusterIssuer
resource!
Create a file named cluster-issuer.yaml:
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: ClusterIssuer
metadata:
# Adjust the name here accordingly
name: letsencrypt-staging
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 from step 3
privateKeySecretRef:
name: letsencrypt-private-key
# Enable the HTTP-01 challenge provider
http01: {}
```
We then submit this file to our Kubernetes cluster:
```bash
$ kubectl create -f cluster-issuer.yaml
```
You should be able to verify the ACME account has been verified successfully:
```bash
$ kubectl describe clusterissuer letsencrypt-staging
Name: letsencrypt-staging
Namespace:
Labels: <none>
Annotations: <none>
API Version: certmanager.k8s.io/v1alpha1
Kind: ClusterIssuer
Metadata:
Cluster Name:
Creation Timestamp: 2017-11-30T22:33:40Z
Generation: 0
Resource Version: 4450170
Self Link: /apis/certmanager.k8s.io/v1alpha1/letsencrypt-staging
UID: 83d04e6b-d61e-11e7-ac26-42010a840044
Spec:
Acme:
Email: user@example.com
Http 01:
Private Key Secret Ref:
Key:
Name: letsencrypt-private-key
Server: https://acme-staging.api.letsencrypt.org/directory
Status:
Acme:
Uri: https://acme-staging.api.letsencrypt.org/acme/reg/5160358
Conditions:
Last Transition Time: 2017-11-30T22:33:41Z
Message: The ACME account was registered with the ACME server
Reason: ACMEAccountRegistered
Status: True
Type: Ready
```
## Step 5 - configuring ingress-shim to use our new ClusterIssuer by default
Now that our ClusterIssuer is ready to issue certificates, we have one last
thing to do: we must reconfigure ingress-shim (deployed as part of
cert-manager) to automatically create Certificate resources for all Ingress
resources it finds with appropriate annotations.
More information on the role of ingress-shim can be found
[in the docs](ingress-shim.md), but for now we can just run a `helm upgrade`
in order to add a few additional flags. Assuming you've named your
ClusterIssuer `letsencrypt-staging` (as above), run:
```bash
helm upgrade \
cert-manager \
./contrib/charts/cert-manager \
--namespace kube-system \
--set ingressShim.extraArgs='{--default-issuer-name=letsencrypt-staging,--default-issuer-kind=ClusterIssuer}'
```
If you get an error like: `Error: path "./contrib/charts/cert-manager" not found`,
ensure you have cloned the cert-manager repository and you are in the root of
the repository.
You should see the cert-manager pod be re-created, and once started it should
automatically create Certificate resources for all of your ingresses that
previously had kube-lego enabled.
## Step 6 - verify each ingress now has a corresponding Certificate
Before we finish, we should make sure there is now a Certificate resource for
each ingress resource you previously enabled kube-lego on.
You should be able to check this by running:
```
$ kubectl get certificates --all-namespaces
```
There should be an entry for each ingress in your cluster with the kube-lego
annotation.
We can also verify that cert-manager has 'adopted' the old TLS certificates by
'describing' one of these newly created certificates:
```
$ kubectl describe certificate my-example-certificate
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal RenewalScheduled 1m cert-manager-controller Certificate scheduled for renewal in 292 hours
```
Here we can see cert-manager has verified the existing TLS certificate and
scheduled it to be renewed in 292h time.