Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Deprecate kube-lego and document cert-manager usage #755

Closed
wants to merge 3 commits into from
Closed

Deprecate kube-lego and document cert-manager usage #755

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a2c1a72
Deprecate kube-lego and document cert-manager usage
clkao Jul 9, 2018
ec9710a
disable proxy https by default
clkao Jul 9, 2018
06b18f6
Full helm command for cert-manager and doc link
clkao Jul 10, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 32 additions & 12 deletions doc/source/advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,25 +41,46 @@ Note that Nginx maintains two additional ingress controllers.
For most use cases, we recommend the community maintained **kubernetes/ingress-nginx** since that
is the ingress controller that the development team has the most experience using.

### Ingress and Automatic HTTPS with kube-lego & Let's Encrypt
### Ingress and Automatic HTTPS with cert-manager & Let's Encrypt

When using an ingress object, the default automatic HTTPS support does not work.
To have automatic fetch and renewal of HTTPS certificates, you must set it up
yourself.

Here's a method that uses [kube-lego](https://github.com/jetstack/kube-lego)
Here's a method that uses [cert-manager](https://github.com/jetstack/cert-manager)
to automatically fetch and renew HTTPS certificates from [Let's Encrypt](https://letsencrypt.org/).
This approach with kube-lego and Let's Encrypt currently only works with two ingress controllers:
the community-maintained [**kubernetes/ingress-nginx**](https://github.com/kubernetes/ingress-nginx)
and **google cloud's ingress controller**.

1. Make sure that DNS is properly set up (configuration depends on the ingress
controller you are using and how your cluster was set up). Accessing
`<hostname>` from a browser should route traffic to the hub.
2. Install & configure kube-lego using the
[kube-lego helm-chart](https://github.com/kubernetes/charts/tree/master/stable/kube-lego).
Remember to change `config.LEGO_EMAIL` and `config.LEGO_URL` at the least.
3. Add an annotation + TLS config to the ingress so kube-lego knows to get certificates for

2. Install & configure cert-manager using the
[cert-manager helm-chart](https://github.com/kubernetes/charts/tree/master/stable/cert-manager) with ingressShim enabled: `--set ingressShim.defaultIssuerName=letsencrypt-prod --set ingressShim.defaultIssuerKind=ClusterIssuer`.

3. Create the default ClusterIssuer:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add the command that people should run with this yaml? Can't we integrate this into the z2jh chart?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can I think - we can declare it as a dependency.

I've done that for the z2jh-chart itself and built on top of it.

For reference: https://github.com/consideRatio/z2jh-extended/blob/master/z2jh-extended/requirements.yaml

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is very likely the users already run or will run cert-manager cluster-wide, if using it. having it as a hard dependency and the issuer managed by us seems to complicate things.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@betatim just added the full command


```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
namespace: default
spec:
acme:
# The ACME server URL
server: https://acme-v02.api.letsencrypt.org/directory
# Email address used for ACME registration
email: $EMAIL
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsencrypt
# Enable the HTTP-01 challenge provider
http01: {}
```

Remember to change `$EMAIL`.

4. Add an annotation + TLS config to the ingress so cert-manager knows to get certificates for
it:

```yaml
Expand All @@ -69,11 +90,10 @@ and **google cloud's ingress controller**.
tls:
- hosts:
- <hostname>
secretName: kubelego-tls-jupyterhub
secretName: jupyterhub-tls
```

This should provision a certificate, and keep renewing it whenever it gets close
to expiry!
This should provision a certificate, and keep renewing it whenever it gets close to expiry!

## Arbitrary extra code and configuration in `jupyterhub_config.py`

Expand Down
20 changes: 1 addition & 19 deletions doc/source/security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,25 +31,7 @@ on HTTPS security see the certificates section of [this blog post](https://blog.

### Set up automatic HTTPS

JupyterHub uses [Let's Encrypt](https://letsencrypt.org/) to automatically create
HTTPS certificates for your deployment. This will cause your HTTPS certificate
to automatically renew every few months. To enable this, make the following
changes to your `config.yaml` file:

1. Specify the two bits of information that we need to automatically provision
HTTPS certificates - your domain name & a contact email address.

```yaml
proxy:
https:
hosts:
- <your-domain-name>
letsencrypt:
contactEmail: <your-email-address>
```

2. Apply the config changes by running `helm upgrade ...`
3. Wait for about a minute, now your hub should be HTTPS enabled!
Refer to the Advanced Topics section for Automatic HTTPS with cert-manager and [Let's Encrypt](https://letsencrypt.org/).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to make sure that enabling letsencrypt remains the simplest and first recommended way to enable HTTPS. It shouldn't be moved to advanced topics. This https-enabling config that faces the users should ideally stay the same and the kube-lego->certmanager transition should be hidden from the user as much as possible.

What's the impediment to doing this now?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressing this is mandatory and in my eyes what needs to be done before we can merge this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Happy to add the simple command back to the security section.


### Set up manual HTTPS

Expand Down
12 changes: 0 additions & 12 deletions jupyterhub/templates/proxy/autohttps/configmap-nginx.yaml
View file
Open in desktop

This file was deleted.

136 changes: 0 additions & 136 deletions jupyterhub/templates/proxy/autohttps/deployment.yaml
View file
Open in desktop

This file was deleted.

30 changes: 0 additions & 30 deletions jupyterhub/templates/proxy/autohttps/ingress-internal.yaml
View file
Open in desktop

This file was deleted.

Loading