Deployment guide for DigitalOcean¶

In this guide we will be using the docker-machine tool to provision a number of Docker Swarm nodes then we'll connect them together and deploy OpenFaaS. Before you get started - sign up to Digital Ocean here to get free credits. Once you've signed up come back to the tutorial.

A foreword on security¶

These instructions are for a development environment. If you plan to expose OpenFaaS on the public Internet you need to enable basic authentication with a proxy such as Kong or Traefik at a minimum. TLS is also highly recomended and freely available with LetsEncrypt.org. Kong guide Traefik guide.

Create DigitalOcean API Access Token¶

Follow the DigitalOcean instructions here to create a Personal Access Token with Read and Write permissions, give the token a descriptive name for example openfaas-getting-started.

Now set an environment variable with the new token value.

$ export DOTOKEN=738cb0cd2jfhu84c33hu...

If you want to make this permanent, you can insert the value into your ~/.bash_profile file.

Install Docker Machine¶

Type in docker-machine to see if you already have the tool installed this is normally bundled with Docker for Mac/Windows. If not then you can download Docker Machine here.

Create Docker Nodes¶

Use Docker Machine to create Docker hosts or nodes. On Digital Ocean your hosts or VMs (Virtual Machines) are called Droplets and will run a full version of Linux. Note: you'll be able to connect to any of your droplets with ssh later on.

The example below creates 3 droplets in the NYC3 zone, if you want to deploy only one Droplet change "1 2 3" to "1".

This process will take a few minutes as Droplets are created and Docker installed.

for i in 1 2 3; do
    docker-machine create \
        --driver digitalocean \
        --digitalocean-image ubuntu-17-04-x64 \
        --digitalocean-tags openfaas-getting-started \
        --digitalocean-region=nyc3 \
        --digitalocean-access-token $DOTOKEN \
        node-$i;
done

List the newly created Docker nodes.

$ docker-machine ls

NAME     ACTIVE   DRIVER         STATE     URL                          SWARM   DOCKER        ERRORS
node-1   -        digitalocean   Running   tcp://104.131.69.233:2376            v17.07.0-ce
node-2   -        digitalocean   Running   tcp://104.131.115.146:2376           v17.07.0-ce
node-3   -        digitalocean   Running   tcp://159.203.168.121:2376           v17.07.0-ce

Refer to the documentation for more detailed information on the DigitalOcean options for docker-machine.

Create your Docker Swarm¶

A Docker Swarm can contain as little as a single master node and begins by running the docker swarm init command. It's important if you have more than one node that you specify an --advertise-addr value.

Intialize Docker Swarm on node-1.

$ docker-machine ssh node-1 -- docker swarm init --advertise-addr $(docker-machine ip node-1)

If you opted to deploy a single node, then skip to the next section.

When deploying more than a single Docker host take a note of the command to add a worker to the Swarm. This output contains your join token.

If you lose it you can get a new one any time with the command: docker swarm join-token worker or manager.

Swarm initialized: current node (je5vne1f974fea60ca75q2cac) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-239v0epdnhuol2ldguttncoaleovy29hnwyglde0kba1owc9ng-9488z5we2invwcn69f5flq7uu 104.131.69.233:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

Add node-2 to the Swarm, using the docker swarm join.. command returned when initializing the master.

$ docker-machine ssh node-2 -- docker swarm join --token SWMTKN-1-239v0epdnhuol2ldguttncoaleovy29hnwyglde0kba1owc9ng-9488z5we2invwcn69f5flq7uu 104.131.69.233:2377

Repeat for node-3.

$ docker-machine ssh node-3 -- docker swarm join --token SWMTKN-1-239v0epdnhuol2ldguttncoaleovy29hnwyglde0kba1owc9ng-9488z5we2invwcn69f5flq7uu 104.131.69.233:2377

Configure Docker CLI to use remote Swarm¶

Run this command each time you open a new shell, this tells Docker where your remote Swarm is.

eval $(docker-machine env node-1)

Deploy the OpenFaaS Stack¶

This command clones the OpenFaaS Github repository then checkouts out a stable release before deploying a Docker stack. Docker Swarm will automatically distribute your functions and OpenFaaS services across the cluster.

$ git clone https://github.com/alexellis/faas && \
  cd faas && \
  git checkout 0.6.5 && \
  ./deploy_stack.sh

Test the UI¶

Within a few seconds (or minutes if on a poor WiFi connection) the API gateway and sample functions will be deployed to the Swarm cluster running on DigitalOcean.

Access the Gateway UI via the IP address returned by docker-machine ip node-1 (you can also access via node-2 and node-3):

$ echo http://$(docker-machine ip node-1):8080

Prometheus metrics can be viewed on port 9090 on a master. Fetch the IP like this:

$ echo http://$(docker-machine ip node-1):9090

Deleting OpenFaaS Droplets¶

You can use docker-machine to delete any created Droplets if are finished with your OpenFaaS deployment.

docker-machine rm node-1 node-2 node-3

Advanced¶

Create a Load Balancer¶

Digital Ocean provide their own Load Balancers which mean you only need to share or map one IP address to your DNS records or internal applications. They can also apply health-checks which ensure traffic is only routed to healthy nodes.

From the DigitalOcean console Networking page, open the Load Balancers tab and click Create Load Balancer.

Give the balancer a name and select the Droplets which will be balanced using the openfaas-getting-started tag and NYC3 region (these were values passed to docker-machine when creating the nodes).

create_lb

Update the forwarding rules to point at the Gateway on 8080 and Prometheus dashboard on 9090: forwarding_rules

Expand the Advanced section and update the health check to use port 8080. health_checks

Click Create Load Balancer and after a few minutes your balancer will be available.

balancer_ready

You can now access the OpenFaaS Gateway, Prometheus dashboard and all functions via the load balanced IP address. For example from the balancer above: - Gateway: http://45.55.124.29:8080 - Prometheus: http://45.55.124.29:9090