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.

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

Initial SSL for swarm tutorial #107

Open
wants to merge 10 commits into
base: master
from

Conversation

Projects
None yet
3 participants
@LucasRoesler
Copy link
Member

LucasRoesler commented Dec 26, 2018

Description

  • Adds a new reference document to guide a user through installing OpenFaaS on Docker Swarm with Traefik as the proxy with ssl certs from Let's Encrypt

Motivation and Context

  • I have raised an issue to propose this change (required)

Resolves #85

How Has This Been Tested?

Tested on a digital ocean swarm cluster

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

  • My code follows the code style of this project.
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • I've read the CONTRIBUTION guide
  • I have signed-off my commits with git commit -s
Initial SSL for swarm tutorial
**What**
- Adds a new reference document to guide a user through installing
OpenFaaS on Docker Swarm with Traefik as the proxy with ssl certs from
Let's Encrypt

Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>
@@ -0,0 +1,319 @@
# SSL on Swarm with Traefik

To completely secure your OpenFaaS installation, you need SSL. On Swarm, you can do this easily with [Traefik][traefik] and [Let's Encrypt][letsencrypt]. Traefik is is reverse proxy that comes with SSL support via Let's Encrypt. In this tutorial we will show you how to deploy OpenFaaS with Traefik.

This comment has been minimized.

@rgee0

rgee0 Dec 28, 2018

Member

Typo Traefik is is

This comment has been minimized.

@rgee0

rgee0 Dec 28, 2018

Member

Are the double square brackets meant to be markdown links?

This comment has been minimized.

@LucasRoesler

LucasRoesler Dec 28, 2018

Member

yes, they are link references where the definition or the link is provided at the bottom of the document: https://daringfireball.net/projects/markdown/syntax#link

@rgee0
Copy link
Member

rgee0 left a comment

A few typos / changes.

I think this guide should work on ARM too since traefik is multi arch:

 Manifest List: Yes
Supported platforms:
 - linux/amd64
 - linux/arm/v6
 - linux/arm64

I shall give it a run through on a Pi this afternoon.


## Create an A record

If your domain is `.domain.com` then create an A record using your DNS administration panel such as `gateway.domain.com` or `openfaas.domain.com`. The required steps will vary depending on your domain provider and your cluster provider. For example; [on Google Cloud DNS](https://cloud.google.com/kubernetes-engine/docs/tutorials/configuring-domain-name-static-ip) or [with Route53 using AWS](https://kubernetes.io/docs/setup/custom-cloud/kops/#2-5-create-a-route53-domain-for-your-cluster).

This comment has been minimized.

@rgee0

rgee0 Dec 28, 2018

Member

Query whether we should call out specific CSPs as examples if we aren't mentioning all of them.

This comment has been minimized.

@LucasRoesler

LucasRoesler Dec 28, 2018

Member

This follows the statement in the k8s documentation. I will gladly add more, of course all is not possible

This comment has been minimized.

@alexellis

This comment has been minimized.

@LucasRoesler

LucasRoesler Jan 1, 2019

Member

Cloud service provider

## Update the Compose configuration

### Configure Traefik
To use Traefik with OpenFaaS, you need to modify the OpenFaaS deployment manifest to include Traefik and configuring OpenFaaS communicate through Traefik instead of directly exposing its services to the internet.

This comment has been minimized.

@rgee0

rgee0 Dec 28, 2018

Member

Suggest amending and configuring OpenFaaS communicate to and configure OpenFaaS to communicate

This comment has been minimized.

@rgee0

rgee0 Dec 28, 2018

Member

'the' Internet has a capital, otherwise its an internet

- "acme:/etc/traefik/acme"
...
```
6. Next you must configure the networks the `traefix` service is part of. All OpenFaaS components live on the `functions` networks, which is also defined in the compose file.

This comment has been minimized.

@rgee0

rgee0 Dec 28, 2018

Member

typo traefix


- If you want to tail the Traefik logs, you can use
```sh
$ docker service ls -f traefik

This comment has been minimized.

@rgee0

rgee0 Dec 28, 2018

Member

should this be logs, rather than ls?

This comment has been minimized.

@LucasRoesler
```
You can see internet traffic logs as well as logs related to the Let's Encrypt certificate process.

## Profit!

This comment has been minimized.

@rgee0

rgee0 Dec 28, 2018

Member

I haven't seen profit used like this before?

This comment has been minimized.

@LucasRoesler

LucasRoesler Dec 28, 2018

Member

It was something silly that I had added and quietly made it into the ssl for k8s docs, so I duplicated it here. I can remove both

This comment has been minimized.

@alexellis

alexellis Jan 1, 2019

Member

I think this type of thing sounds better in personal blog posts where the reader is connecting with the writer.

@rgee0

This comment has been minimized.

Copy link
Member

rgee0 commented Dec 28, 2018

I had to play with the quotes to get things working:

    traefik:
        image: traefik:v1.7.6
        command:
          - '--api=true'
          - '--docker=true'
          - '--docker.swarmmode=true'
          - '--docker.domain=traefik'
          - '--docker.watch=true'
          - '--defaultEntryPoints=http,https'
          - '--entryPoints=Name:https Address::443 TLS'
          - '--entryPoints=Name:http Address::80'
          - '--acme=true'
          - '--acme.entrypoint=https'
          - '--acme.httpchallenge=true'
          - '--acme.httpchallenge.entrypoint=http'
          - '--acme.domains=openfaas.domain.co.uk'
          - '--acme.email=prefix@domain.co.uk'
          - '--acme.ondemand=true'
          - '--acme.onhostrule=true'
          - '--acme.storage=/etc/traefik/acme/acme.json'
        ports:
          - 80:80
          - 8080:8080
          - 443:443
        volumes:
          - "/var/run/docker.sock:/var/run/docker.sock"
          - "acme:/etc/traefik/acme"
        networks:
          - functions
        deploy:
          placement:
            constraints: [node.role == manager]

It seems that it works with double quotes as well and its the mixture of the two that causes it problems.

Before this I was plagued by:

func_traefik.1.ukikkmpgcpwd@openfaas-20181228T171625    | time="2018-12-28T17:47:10Z" level=fatal msg="Unknown entrypoint \"'https'\" for ACME configuration"
func_traefik.1.2n93ehgbb7uy@openfaas-20181228T171625    | time="2018-12-28T17:47:17Z" level=fatal msg="Unknown entrypoint \"'https'\" for ACME configuration"
func_traefik.1.di467p1zav5b@openfaas-20181228T171625    | time="2018-12-28T17:46:59Z" level=fatal msg="Unknown entrypoint \"'https'\" for ACME configuration"

LucasRoesler added some commits Dec 28, 2018

Fix duplicate "is" typo
**What**
- Replace duplicate "is" with missing "a" in the opening statement

Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>
Add missing word to configure traefik intro
**What**
- Add missing "to"
- Replace "the internate" with "publicaly"

Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>
Fix traefix typo in traefik part number 6
Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>
Fix logs debug command
**What**
- Replace `ls` with `logs`

Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>
@LucasRoesler

This comment has been minimized.

Copy link
Member

LucasRoesler commented Dec 28, 2018

I will clean up the quotes, that is something I copied and then was cleaning up from how I originally had it in my files to clean up and standardize the mix of quotes that I had copied from other docs/tutorials

Cleanup quotes in the traefik command
**What**
- Remove the unnecceessary single quotes

Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>
$ git clone https://github.com/openfaas/faas && cd faas
```

2. Add the `traefik` service to the `docker-compose.yaml`.

This comment has been minimized.

@alexellis

alexellis Jan 1, 2019

Member

I can see why you've gone for this approach, but it's going to be difficult for a user to follow all the edits. My gist had a separate version of the file for ease of use, but this would mean some maintenance.

What do you think to defining a new file and referencing the network as external maybe? See the Kafka connector as an example of this


On your first visit, the HTTP authentication dialogue box will open, you can login with the username `admin` and secure random password that the deploy script created for you when you deployed OpenFaaS.

## Verify and Debug

This comment has been minimized.

@alexellis

alexellis Jan 1, 2019

Member

This isn't verifying or debugging. How about "check the logs"?

This comment has been minimized.

@LucasRoesler

LucasRoesler Jan 2, 2019

Member

I wanted to keep some of the structure from the k8s reference, I figured someone might be able to recommend other commands to put here? if not I can change the title

```
Replace `openfaas.mydomain.com` with your domain as well as adding the username `admin` and secure random password that the deploy script created for you when you deployed OpenFaaS.

### Using the web UI

This comment has been minimized.

@alexellis

alexellis Jan 1, 2019

Member

Please prefer an active style for headings:

Use vs using
Setup vs setting up
Create a vs creating a

@alexellis

This comment has been minimized.

Copy link
Member

alexellis commented Jan 1, 2019

Lucas, it'll be great to provide users with an easy way to get SSL with LE for their OpenFaaS deployments. Thanks for working on this.

Do you think there is a way to simplify the number of manual edits or use some scripts to help the user with some of the steps? Overall this looks to be much more involved than the cert-manager version. It may have to be that way, but I thought I'd mention it as my first impression.

@LucasRoesler

This comment has been minimized.

Copy link
Member

LucasRoesler commented Jan 1, 2019

Of hand, a script to edit the docker compose file seems like something that would be fragile and people would forget to check/test. We could create a demo project they contains the required edits, but we would need to ensure that it stays in sync with the base compose file.

A lot of the content of the tutorial is partial explanations of what is changing. We could simplify the walkthrough by reducing the amount of description and skip right to the "copy this service and chnagelog these two other lines", but I think that will make it more opeque.

LucasRoesler added some commits Jan 2, 2019

Remove profit section
Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>
Consolidate traefik configuration steps
**What**
- Reduce the number of steps so that it is easier for people to see the
required changes

Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>
Update titles to active voice
Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>
Simplify the configure openfaas section
**What**
- Remove the "all together" snippet since the modification is so small
and it should be clear.  This should make it easier for someone to see
what is happening instead of a large block of yaml

Signed-off-by: Lucas Roesler <roesler.lucas@gmail.com>
@LucasRoesler

This comment has been minimized.

Copy link
Member

LucasRoesler commented Jan 2, 2019

@alexellis i consolidated the traefik configuration into a single step as well as other streamlining and fixes, can you take another look?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment