From bb29d9c8cafa1d6f65ee7d3c34ff2d1ecb1b3b4d Mon Sep 17 00:00:00 2001 From: Emile Vauge Date: Thu, 29 Sep 2016 13:49:12 +0200 Subject: [PATCH] Add documentation Signed-off-by: Emile Vauge --- docs/toml.md | 4 ++-- docs/user-guide/cluster.md | 19 +++++++++++++++++++ docs/user-guide/kv-config.md | 16 +++++++++++++++- mkdocs.yml | 1 + traefik.sample.toml | 12 +++++++++--- 5 files changed, 46 insertions(+), 6 deletions(-) create mode 100644 docs/user-guide/cluster.md diff --git a/docs/toml.md b/docs/toml.md index 95feaa327..6c72c88ea 100644 --- a/docs/toml.md +++ b/docs/toml.md @@ -247,7 +247,7 @@ Supported filters: # email = "test@traefik.io" -# File used for certificates storage. +# File or key used for certificates storage. # WARNING, if you use Traefik in Docker, you have 2 options: # - create a file on your host and mount it as a volume # storageFile = "acme.json" @@ -258,7 +258,7 @@ email = "test@traefik.io" # # Required # -storageFile = "acme.json" +storage = "acme.json" # or "traefik/acme/account" if using KV store # Entrypoint to proxy acme challenge to. # WARNING, must point to an entrypoint on port 443 diff --git a/docs/user-guide/cluster.md b/docs/user-guide/cluster.md new file mode 100644 index 000000000..e39795f2f --- /dev/null +++ b/docs/user-guide/cluster.md @@ -0,0 +1,19 @@ +# Clustering / High Availability + +This guide explains how tu use Træfɪk in high availability mode. +In order to deploy and configure multiple Træfɪk instances, without copying the same configuration file on each instance, we will use a distributed Key-Value store. + +## Prerequisites + +You will need a working KV store cluster. + +## File configuration to KV store migration + +We created a special Træfɪk command to help configuring your Key Value store from a Træfɪk TOML configuration file. +Please refer to [this section](/user-guide/kv-config/#store-configuration-in-key-value-store) to get more details. + +## Deploy a Træfɪk cluster + +Once your Træfɪk configuration is uploaded on your KV store, you can start each Træfɪk instance. +A Træfɪk cluster is based on a master/slave model. When starting, Træfɪk will elect a master. If this instance fails, another master will be automatically elected. + \ No newline at end of file diff --git a/docs/user-guide/kv-config.md b/docs/user-guide/kv-config.md index 368bb7a87..749f77093 100644 --- a/docs/user-guide/kv-config.md +++ b/docs/user-guide/kv-config.md @@ -302,6 +302,7 @@ Further, if the `/traefik/alias` key is set, all other configuration with `/trae # Store configuration in Key-value store +Don't forget to [setup the connection between Træfɪk and Key-value store](/user-guide/kv-config/#launch-trfk). The static Træfɪk configuration in a key-value store can be automatically created and updated, using the [`storeconfig` subcommand](/basics/#commands). ```bash @@ -309,6 +310,19 @@ $ traefik storeconfig [flags] ... ``` This command is here only to automate the [process which upload the configuration into the Key-value store](/user-guide/kv-config/#upload-the-configuration-in-the-key-value-store). Træfɪk will not start but the [static configuration](/basics/#static-trfk-configuration) will be uploaded into the Key-value store. +If you configured ACME (Let's Encrypt), your registration account and your certificates will also be uploaded. + +To upload your ACME certificates to the KV store, get your traefik TOML file and add the new `storage` option in the `acme` section: + +``` +[acme] +email = "test@traefik.io" +storage = "traefik/acme/account" # the key where to store your certificates in the KV store +storageFile = "acme.json" # your old certificates store +``` + +Call `traefik storeconfig` to upload your config in the KV store. +Then remove the line `storageFile = "acme.json"` from your TOML config file. +That's it! -Don't forget to [setup the connection between Træfɪk and Key-value store](/user-guide/kv-config/#launch-trfk). diff --git a/mkdocs.yml b/mkdocs.yml index be6298810..fbb1642d8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,3 +51,4 @@ pages: - 'Swarm cluster': 'user-guide/swarm.md' - 'Kubernetes': 'user-guide/kubernetes.md' - 'Key-value store configuration': 'user-guide/kv-config.md' + - 'Clustering/HA': 'user-guide/cluster.md' diff --git a/traefik.sample.toml b/traefik.sample.toml index 17b798780..989395a73 100644 --- a/traefik.sample.toml +++ b/traefik.sample.toml @@ -100,12 +100,18 @@ # # email = "test@traefik.io" -# File used for certificates storage. -# WARNING, if you use Traefik in Docker, don't forget to mount this file as a volume. +# File or key used for certificates storage. +# WARNING, if you use Traefik in Docker, you have 2 options: +# - create a file on your host and mount it as a volume +# storageFile = "acme.json" +# $ docker run -v "/my/host/acme.json:acme.json" traefik +# - mount the folder containing the file as a volume +# storageFile = "/etc/traefik/acme/acme.json" +# $ docker run -v "/my/host/acme:/etc/traefik/acme" traefik # # Required # -# storageFile = "acme.json" +# storage = "acme.json" # or "traefik/acme/account" if using KV store # Entrypoint to proxy acme challenge to. # WARNING, must point to an entrypoint on port 443