docs - swarm integration

2021-08-10 15:01:03 +02:00 · 2021-08-10 15:01:03 +02:00 · d37dc2b629
parent f7c115edff
commit d37dc2b629
1 changed files with 208 additions and 3 deletions
--- a/docs/integrations.md
+++ b/docs/integrations.md
@ -20,7 +20,7 @@ To use bunkerized-nginx as a Docker container you have to pass specific environm

 <img src="https://github.com/bunkerity/bunkerized-nginx/blob/dev/docs/img/docker.png?raw=true" />

-### Basic usage
+### Usage

 To demonstrate the use of the Docker image, we will create a simple "Hello World" static file that will be served by bunkerized-nginx.

@ -125,7 +125,7 @@ $ docker volume create bunkerized-vol

 You can now create the bunkerized-nginx container, connect it to the web services network and start it :
 ```shell
-$ docker run \
+$ docker create \
         --name mybunkerized \
         -l bunkerized-nginx.AUTOCONF \
         --network bunkerized-net \
@ -251,10 +251,215 @@ Please note that if you want to override the `AUTO_LETS_ENCRYPT=yes` previously

 Look at the logs of both autoconf and bunkerized-nginx to check if the configuration has been generated and loaded by bunkerized-nginx. You should now be able to visit http(s)://www.example.com.

-When your service is not needed anymore, you can delete it as usual. The autoconf should get the event and remove generate the configuration again.
+When your container is not needed anymore, you can delete it as usual. The autoconf should get the event and remove generate the configuration again.

 ## Docker Swarm

+### Introduction
+
+Using bunkerized-nginx in a Docker Swarm cluster requires a shared folder accessible from both managers and workers (anything like NFS, GlusterFS, CephFS or even SSHFS will work). The deployment and configuration is very similar to the "Docker autoconf" one but with services instead of containers. A service based on the bunkerized-nginx-autoconf image needs to be scheduled on a manager node (don't worry it doesn't expose any network port for obvious security reasons). This service will listen for Docker Swarm events like service creation or deletion and generate the configuration according to the labels of each service. Once configuration generation is done, the bunkerized-nginx-autoconf service will send a reload order to all the bunkerized-nginx tasks so they can load the new configuration.
+
+<img src="https://github.com/bunkerity/bunkerized-nginx/blob/dev/docs/img/swarm.png?raw=true" />
+
+### Usage
+
+**We will assume that a shared directory is mounted at the /shared location on both your managers and workers. Don't forget that bunkerized-nginx and autoconf are running as unprivileged users with UID and GID 101. You must set the rights and permissions of the subfolder in /shared accordingly.**
+
+**We also recommend you to first read the [Docker](#TODO) section before.**
+
+In this setup we will deploy bunkerized-nginx in global mode on all workers and autoconf as a single replica.
+
+First of all, you will need to setup the shared folders :
+```shell
+$ cd /shared
+$ mkdir www confs letsencrypt acme-challenge
+$ chown root:nginx www confs letsencrypt acme-challenge
+$ chmod 770 www confs letsencrypt acme-challenge
+```
+
+Then you will need to create 2 networks, one for the communication between bunkerized-nginx and autoconf and the other one for the communication between bunkerized-nginx and the web services :
+```shell
+$ docker network create -d overlay --attachable bunkerized-net
+$ docker network create -d overlay --attachable services-net
+```
+
+We can now start the bunkerized-nginx as a service :
+```shell
+$ docker service create \
+         --name mybunkerized \
+         --mode global \
+         --constraint node.role==worker \
+         -l bunkerized-nginx.AUTOCONF \
+         --network bunkerized-net \
+         -p published=80,target=8080,mode=host \
+         -p published=443,target=8443,mode=host \
+         --mount type=bind,source=/shared/confs,destination=/etc/nginx,ro \
+         --mount type=bind,source=/shared/www,destination=/www,ro \
+         --mount type=bind,source=/shared/letsencrypt,destination=/etc/letsencrypt,ro \
+         --mount type=bind,source=/shared/acme-challenge,destination=/acme-challenge,ro \
+         -e SWARM_MODE=yes \
+         -e USE_API=yes \
+         -e API_URI=/ChangeMeToSomethingHardToGuess \
+         -e SERVER_NAME= \
+         -e MULTISITE=yes \
+         -e AUTO_LETS_ENCRYPT=yes \
+         bunkerity/bunkerized-nginx
+$ docker service update \
+         --network-add services-net
+         mybunkerized
+```
+
+Once bunkerized-nginx has been started you can start the autoconf as a service :
+```shell
+$ docker service create \
+         --name myautoconf \
+         --replicas 1 \
+         --constraint node.role==manager \
+         --network bunkerized-net \
+         --mount type=bind,source=/var/run/docker.sock,destination=/var/run/docker.sock,ro \
+         --mount type=bind,source=/shared/confs,destination=/etc/nginx,rw \
+         --mount type=bind,source=/shared/letsencrypt,destination=/etc/letsencrypt,rw \
+         --mount type=bind,source=/shared/acme-challenge,destination=/acme-challenge,rw \
+         -e SWARM_MODE=yes \
+         -e API_URI=/ChangeMeToSomethingHardToGuess \
+         bunkerity/bunkerized-nginx-autoconf
+```
+
+Or do the same with docker-compose if you wish :
+```yaml
+version: '3'
+
+services:
+
+  nginx:
+    image: bunkerity/bunkerized-nginx
+    ports:
+      - published: 80
+        target: 8080
+        mode: host
+        protocol: tcp
+      - published: 443
+        target: 8443
+        mode: host
+        protocol: tcp
+    volumes:
+      - /shared/confs:/etc/nginx:ro
+      - /shared/www:/www:ro
+      - /shared/letsencrypt:/etc/letsencrypt:ro
+      - /shared/acme-challenge:/acme-challenge:ro
+    environment:
+      - SWARM_MODE=yes
+      - USE_API=yes
+      - API_URI=/ChangeMeToSomethingHardToGuess # must match API_URI from autoconf
+      - MULTISITE=yes
+      - SERVER_NAME=
+      - AUTO_LETS_ENCRYPT=yes
+    networks:
+      - bunkerized-net
+      - services-net
+    deploy:
+      mode: global
+      placement:
+        constraints:
+          - "node.role==worker"
+      labels:
+        - "bunkerized-nginx.AUTOCONF"
+
+  autoconf:
+    image: bunkerity/bunkerized-nginx-autoconf
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /shared/confs:/etc/nginx
+      - /shared/letsencrypt:/etc/letsencrypt
+      - /shared/acme-challenge:/acme-challenge
+    environment:
+      - SWARM_MODE=yes
+      - API_URI=/ChangeMeToSomethingHardToGuess # must match API_URI from nginx
+    networks:
+      - bunkerized-net
+    deploy:
+      replicas: 1
+      placement:
+        constraints:
+          - "node.role==manager"
+
+# This will create the networks for you
+networks:
+  bunkerized-net:
+    driver: overlay
+    attachable: true
+    name: bunkerized-net
+  services-net:
+    driver: overlay
+    attachable: true
+    name: services-net
+```
+
+Check the logs of both autoconf and bunkerized-nginx services to see if everything is working as expected.
+
+You can now create a new service and add environment variables as labels with the **"bunkerized-nginx." prefix** so the autoconf service will "automagically" do the configuration for you :
+```shell
+$ docker service create \
+         --name myservice \
+         --constraint node.role==worker \
+         --network services-net \
+         -l bunkerized-nginx.SERVER_NAME=www.example.com \
+         -l bunkerized-nginx.USE_REVERSE_PROXY=yes \
+         -l bunkerized-nginx.REVERSE_PROXY_URL=/ \
+         -l bunkerized-nginx.REVERSE_PROXY_HOST=http://myservice \
+         tutum/hello-world
+```
+
+docker-compose equivalent :
+```yaml
+version: "3"
+
+services:
+
+  myservice:
+    image: tutum/hello-world
+    networks:
+      - services-net
+    deploy:
+      placement:
+        constraints:
+          - "node.role==worker"
+      labels:
+        - "bunkerized-nginx.SERVER_NAME=www.example.com"
+        - "bunkerized-nginx.USE_REVERSE_PROXY=yes"
+        - "bunkerized-nginx.REVERSE_PROXY_URL=/"
+        - "bunkerized-nginx.REVERSE_PROXY_HOST=http://myservice"
+
+networks:
+  services-net:
+    external:
+      name: services-net
+```
+
+Please note that if you want to override the AUTO_LETS_ENCRYPT=yes previously defined in the bunkerized-nginx service, you simply need to add the bunkerized-nginx.AUTO_LETS_ENCRYPT=no label.
+
+Look at the logs of both autoconf and bunkerized-nginx to check if the configuration has been generated and loaded by bunkerized-nginx. You should now be able to visit http(s)://www.example.com.
+
+When your service is not needed anymore, you can delete it as usual. The autoconf should get the event and remove generate the configuration again.
+
 ## Kubernetes

+### Introduction
+
+**This integration is still in beta, please fill an issue if you find a bug or have an idea on how to improve it.**
+
+Using bunkerized-nginx in a Kubernetes cluster requires a shared folder accessible from the nodes (anything like NFS, GlusterFS, CephFS or even SSHFS will work). The bunkerized-nginx-autoconf acts as an Ingress Controller and connects to the k8s API to get cluster events and generate a new configuration when it's needed. Once the configuration is generated, the Ingress Controller sends a reload order to the bunkerized-nginx instances running in the cluster.
+
+<img src="https://github.com/bunkerity/bunkerized-nginx/blob/dev/docs/img/kubernetes.png?raw=true" />
+
+### Usage
+
+**We will assume that a shared directory is mounted at the /shared location on your nodes. Don't forget that bunkerized-nginx and autoconf are running as unprivileged users with UID and GID 101. You must set the rights and permissions of the subfolder in /shared accordingly.**
+
+**We also recommend you to first read the [Docker](#TODO) section before.**
+
 ## Linux
+
+### Introduction
+
+### Usage