From 7bb673c2f1fa9fced35d7f0f881e3adf1e1dd9d2 Mon Sep 17 00:00:00 2001 From: Kasper Guldmann <393906+kalleguld@users.noreply.github.com> Date: Sat, 26 Nov 2022 11:22:01 +0100 Subject: [PATCH 1/3] Influxdb: Add quick start --- influxdb/content.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/influxdb/content.md b/influxdb/content.md index 4fc68e94e3d4..3efa4a2f38c9 100644 --- a/influxdb/content.md +++ b/influxdb/content.md @@ -12,6 +12,22 @@ The `latest` tag for this image now points to the latest released implementation ## Using this Image - InfluxDB 2.x + +### Quick start + +Using this image is pretty easy, but there are a few things you should know. + +- You should forward TCP port 8086 +- You should mount a volume in /var/lib/influxdb2 + +```console +$ docker run \ + -p 8086:8086 \ + -v myInfluxVolume:/var/lib/influxdb2 \ + %%IMAGE%%:latest +``` +After starting the container you can use the web interface at http://localhost:8086/ to setup and customize your Influx database. + ### Upgrading from InfluxDB 1.x InfluxDB 2.x provides a 1.x-compatible API, but expects a different storage layout on disk. To bridge this mismatch, the InfluxDB image contains extra functionality to migrate 1.x data and config into 2.x layouts automatically before booting the `influxd` server. From 61b85b8e7300596333fd9585a9108dede68d2d27 Mon Sep 17 00:00:00 2001 From: Kasper Guldmann <393906+kalleguld@users.noreply.github.com> Date: Sat, 26 Nov 2022 11:28:43 +0100 Subject: [PATCH 2/3] influxdb: re-arrange upgrade instructions. Upgrading from version 1.x is no longer as important, and can be moved below the general use instructions for version 2.x --- influxdb/content.md | 387 ++++++++++++++++++++------------------------ 1 file changed, 177 insertions(+), 210 deletions(-) diff --git a/influxdb/content.md b/influxdb/content.md index 3efa4a2f38c9..6a06b59aff29 100644 --- a/influxdb/content.md +++ b/influxdb/content.md @@ -6,13 +6,8 @@ InfluxDB is a time series database built from the ground up to handle high write %%LOGO%% -## `latest` updated to InfluxDB 2.x - -The `latest` tag for this image now points to the latest released implementation of InfluxDB 2.x. If you are using the `latest` tag and would like to stay on the InfluxDB 1.x line, please update your environment to reference the `1.8` tag. - ## Using this Image - InfluxDB 2.x - ### Quick start Using this image is pretty easy, but there are a few things you should know. @@ -28,211 +23,7 @@ $ docker run \ ``` After starting the container you can use the web interface at http://localhost:8086/ to setup and customize your Influx database. -### Upgrading from InfluxDB 1.x - -InfluxDB 2.x provides a 1.x-compatible API, but expects a different storage layout on disk. To bridge this mismatch, the InfluxDB image contains extra functionality to migrate 1.x data and config into 2.x layouts automatically before booting the `influxd` server. - -The automated upgrade process bootstraps an initial admin user, organization, and bucket in the system. Additional environment variables are used to configure the setup logic: - -- `DOCKER_INFLUXDB_INIT_USERNAME`: The username to set for the system's initial super-user (**Required**). -- `DOCKER_INFLUXDB_INIT_PASSWORD`: The password to set for the system's inital super-user (**Required**). -- `DOCKER_INFLUXDB_INIT_ORG`: The name to set for the system's initial organization (**Required**). -- `DOCKER_INFLUXDB_INIT_BUCKET`: The name to set for the system's initial bucket (**Required**). -- `DOCKER_INFLUXDB_INIT_RETENTION`: The duration the system's initial bucket should retain data. If not set, the initial bucket will retain data forever. -- `DOCKER_INFLUXDB_INIT_ADMIN_TOKEN`: The authentication token to associate with the system's initial super-user. If not set, a token will be auto-generated by the system. - -It also requires extra volumes to be mounted into the 2.x container: - -- Data from the 1.x instance -- Custom config from the 1.x instance (if any) - -The upgrade process searches for mounted 1.x data / config in this priority order: - -1. A config file referred to by the `DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG` environment variable -2. A data directory referred to by the `DOCKER_INFLUXDB_INIT_UPGRADE_V1_DIR` environment variable -3. A config file mounted at `/etc/influxdb/influxdb.conf` -4. A data directory mounted at `/var/lib/influxdb` - -Finally, the `DOCKER_INFLUXDB_INIT_MODE` environment variable must be set to `upgrade`. - -Automated upgrade will generate both data and config files, by default under `/var/lib/influxdb2` and `/etc/influxdb2`. It's recommended to mount volumes at both paths to avoid losing data. - -**NOTE:** Automated upgrade will not run if an existing boltdb file is found at the configured path. This behavior allows for the InfluxDB container to reboot post-upgrade without overwriting migrated data. - -Find more about the InfluxDB upgrade process [here](https://docs.influxdata.com/influxdb/v2.0/upgrade/v1-to-v2/). See below for examples of common upgrade scenarios. - -#### Upgrade Example - Minimal - -Assume you've been running a minimal InfluxDB 1.x deployment: - -```console -$ docker run -p 8086:8086 \ - -v influxdb:/var/lib/influxdb \ - %%IMAGE%%:1.8 -``` - -To upgrade this deployment to InfluxDB 2.x, stop the running InfluxDB 1.x container, then run: - -```console -$ docker run -p 8086:8086 \ - -v influxdb:/var/lib/influxdb \ - -v influxdb2:/var/lib/influxdb2 \ - -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ - -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ - -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ - -e DOCKER_INFLUXDB_INIT_ORG=my-org \ - -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ - %%IMAGE%%:2.0 -``` - -#### Upgrade Example - Custom InfluxDB 1.x Config - -Assume you've been running an InfluxDB 1.x deployment with customized config: - -```console -$ docker run -p 8086:8086 \ - -v influxdb:/var/lib/influxdb \ - -v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf \ - %%IMAGE%%:1.8 -``` - -To upgrade this deployment to InfluxDB 2.x, stop the running container, then run: - -```console -$ docker run -p 8086:8086 \ - -v influxdb:/var/lib/influxdb \ - -v influxdb2:/var/lib/influxdb2 \ - -v influxdb2-config:/etc/influxdb2 \ - -v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf \ - -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ - -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ - -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ - -e DOCKER_INFLUXDB_INIT_ORG=my-org \ - -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ - %%IMAGE%%:2.0 -``` - -#### Upgrade Example - Custom Paths - -Assume you've been running an InfluxDB 1.x deployment with data and config mounted at custom paths: - -```console -$ docker run -p 8086:8086 \ - -v influxdb:/root/influxdb/data \ - -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf \ - %%IMAGE%%:1.8 -config /root/influxdb/influxdb.conf -``` - -To upgrade this deployment to InfluxDB 2.x, first decide if you'd like to keep using custom paths, or use the InfluxDB 2.x defaults. If you decide to use the defaults, you'd stop the running InfluxDB 1.x container, then run: - -```console -$ docker run -p 8086:8086 \ - -v influxdb:/root/influxdb/data \ - -v influxdb2:/var/lib/influxdb2 \ - -v influxdb2-config:/etc/influxdb2 \ - -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf \ - -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ - -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ - -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ - -e DOCKER_INFLUXDB_INIT_ORG=my-org \ - -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ - -e DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG=/root/influxdb/influxdb.conf \ - %%IMAGE%%:2.0 -``` - -To retain your custom paths, you'd run: - -```console -$ docker run -p 8086:8086 \ - -v influxdb:/root/influxdb/data \ - -v influxdb2:/root/influxdb2/data \ - -v influxdb2-config:/etc/influxdb2 \ - -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf \ - -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ - -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ - -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ - -e DOCKER_INFLUXDB_INIT_ORG=my-org \ - -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ - -e DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG=/root/influxdb/influxdb.conf \ - -e DOCKER_INFLUXDB_CONFIG_PATH=/root/influxdb2/config.toml \ - -e DOCKER_INFLUXDB_BOLT_PATH=/root/influxdb2/influxdb.bolt \ - -e DOCKER_INFLUXDB_ENGINE_PATH=/root/influxdb2/engine \ - %%IMAGE%%:2.0 -``` - -### Upgrading from quay.io-hosted InfluxDB 2.x image - -Early Docker builds of InfluxDB 2.x were hosted at `quay.io/influxdb/influxdb`. The builds were very bare-bones, containing the `influx` and `influxd` binaries without any default configuration or helper scripts. By default, the `influxd` process stored data under `/root/.influxdbv2`. - -Starting with `v2.0.4`, we've restored our DockerHub build. This build defaults to storing data in `/var/lib/influxdb2`. Upgrading directly from `quay.io/influxdb/influxdb` to `influxdb:2.0.4` without modifying any settings will appear to cause data loss, as the new process won't be able to find your existing data files. - -To avoid this problem when migrating from `quay.io/influxdb/influxdb` to `influxdb:2.0`, you can use one of the following approaches. - -#### Change volume mount point - -If you don't mind using the new default path, you can switch the mount-point for the volume containing your data: - -```console -# Migrate from this: -$ docker run -p 8086:8086 \ - -v $PWD:/root/.influxdbv2 \ - quay.io/influxdb/influxdb:v2.0.3 - -# To this: -docker run -p 8086:8086 \ - -v $PWD:/var/lib/influxdb2 \ - %%IMAGE%%:2.0 -``` - -#### Override default configs - -If you'd rather keep your data files in the home directory, you can override the container's default config: - -```console -# Migrate from this: -$ docker run -p 8086:8086 \ - -v $PWD:/root/.influxdbv2 \ - quay.io/influxdb/influxdb:v2.0.3 - -# To this: -docker run -p 8086:8086 \ - -e INFLUXD_BOLT_PATH=/root/.influxdbv2/influxd.bolt \ - -e INFLUXD_ENGINE_PATH=/root/.influxdbv2/engine \ - -v $PWD:/root/.influxdbv2 \ - %%IMAGE%%:2.0 -``` - -See the section about configuration below for more ways to override the data paths. - -### Running the container - -The InfluxDB image exposes a shared volume under `/var/lib/influxdb2`. You can mount a host directory to that point to access persisted container data. A typical invocation of the container might be: - -```console -$ docker run -p 8086:8086 \ - -v $PWD:/var/lib/influxdb2 \ - %%IMAGE%%:2.0 -``` - -Modify `$PWD` to the directory where you want to store data associated with the InfluxDB container. - -You can also have Docker control the volume mountpoint by using a named volume. - -```console -$ docker run -p 8086:8086 \ - -v influxdb2:/var/lib/influxdb2 \ - %%IMAGE%%:2.0 -``` - -### Exposed Ports - -The following ports are important and are used by InfluxDB. - -- 8086 HTTP UI and API port - -The HTTP port will be automatically exposed when using `docker run -P`. - -Find more about API Endpoints & Ports [here](https://docs.influxdata.com/influxdb/v2.0/reference/api/). +Find more about API Endpoints & Ports [here](https://docs.influxdata.com/influxdb/v2.5/reference/api/). ### Configuration @@ -436,6 +227,182 @@ $ docker run -p 8086:8086 \ **NOTE:** Custom scripts will not run if an existing boltdb file is found at the configured path (causing `setup` or `upgrade` to be skipped). This behavior allows for the InfluxDB container to reboot post-initialization without encountering errors from non-idempotent script commands. +### Upgrading from InfluxDB 1.x + +InfluxDB 2.x provides a 1.x-compatible API, but expects a different storage layout on disk. To bridge this mismatch, the InfluxDB image contains extra functionality to migrate 1.x data and config into 2.x layouts automatically before booting the `influxd` server. + +The automated upgrade process bootstraps an initial admin user, organization, and bucket in the system. Additional environment variables are used to configure the setup logic: + +- `DOCKER_INFLUXDB_INIT_USERNAME`: The username to set for the system's initial super-user (**Required**). +- `DOCKER_INFLUXDB_INIT_PASSWORD`: The password to set for the system's inital super-user (**Required**). +- `DOCKER_INFLUXDB_INIT_ORG`: The name to set for the system's initial organization (**Required**). +- `DOCKER_INFLUXDB_INIT_BUCKET`: The name to set for the system's initial bucket (**Required**). +- `DOCKER_INFLUXDB_INIT_RETENTION`: The duration the system's initial bucket should retain data. If not set, the initial bucket will retain data forever. +- `DOCKER_INFLUXDB_INIT_ADMIN_TOKEN`: The authentication token to associate with the system's initial super-user. If not set, a token will be auto-generated by the system. + +It also requires extra volumes to be mounted into the 2.x container: + +- Data from the 1.x instance +- Custom config from the 1.x instance (if any) + +The upgrade process searches for mounted 1.x data / config in this priority order: + +1. A config file referred to by the `DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG` environment variable +2. A data directory referred to by the `DOCKER_INFLUXDB_INIT_UPGRADE_V1_DIR` environment variable +3. A config file mounted at `/etc/influxdb/influxdb.conf` +4. A data directory mounted at `/var/lib/influxdb` + +Finally, the `DOCKER_INFLUXDB_INIT_MODE` environment variable must be set to `upgrade`. + +Automated upgrade will generate both data and config files, by default under `/var/lib/influxdb2` and `/etc/influxdb2`. It's recommended to mount volumes at both paths to avoid losing data. + +**NOTE:** Automated upgrade will not run if an existing boltdb file is found at the configured path. This behavior allows for the InfluxDB container to reboot post-upgrade without overwriting migrated data. + +Find more about the InfluxDB upgrade process [here](https://docs.influxdata.com/influxdb/v2.0/upgrade/v1-to-v2/). See below for examples of common upgrade scenarios. + +#### Upgrade Example - Minimal + +Assume you've been running a minimal InfluxDB 1.x deployment: + +```console +$ docker run -p 8086:8086 \ + -v influxdb:/var/lib/influxdb \ + %%IMAGE%%:1.8 +``` + +To upgrade this deployment to InfluxDB 2.x, stop the running InfluxDB 1.x container, then run: + +```console +$ docker run -p 8086:8086 \ + -v influxdb:/var/lib/influxdb \ + -v influxdb2:/var/lib/influxdb2 \ + -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ + -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ + -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ + -e DOCKER_INFLUXDB_INIT_ORG=my-org \ + -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ + %%IMAGE%%:2.0 +``` + +#### Upgrade Example - Custom InfluxDB 1.x Config + +Assume you've been running an InfluxDB 1.x deployment with customized config: + +```console +$ docker run -p 8086:8086 \ + -v influxdb:/var/lib/influxdb \ + -v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf \ + %%IMAGE%%:1.8 +``` + +To upgrade this deployment to InfluxDB 2.x, stop the running container, then run: + +```console +$ docker run -p 8086:8086 \ + -v influxdb:/var/lib/influxdb \ + -v influxdb2:/var/lib/influxdb2 \ + -v influxdb2-config:/etc/influxdb2 \ + -v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf \ + -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ + -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ + -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ + -e DOCKER_INFLUXDB_INIT_ORG=my-org \ + -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ + %%IMAGE%%:2.0 +``` + +#### Upgrade Example - Custom Paths + +Assume you've been running an InfluxDB 1.x deployment with data and config mounted at custom paths: + +```console +$ docker run -p 8086:8086 \ + -v influxdb:/root/influxdb/data \ + -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf \ + %%IMAGE%%:1.8 -config /root/influxdb/influxdb.conf +``` + +To upgrade this deployment to InfluxDB 2.x, first decide if you'd like to keep using custom paths, or use the InfluxDB 2.x defaults. If you decide to use the defaults, you'd stop the running InfluxDB 1.x container, then run: + +```console +$ docker run -p 8086:8086 \ + -v influxdb:/root/influxdb/data \ + -v influxdb2:/var/lib/influxdb2 \ + -v influxdb2-config:/etc/influxdb2 \ + -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf \ + -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ + -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ + -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ + -e DOCKER_INFLUXDB_INIT_ORG=my-org \ + -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ + -e DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG=/root/influxdb/influxdb.conf \ + %%IMAGE%%:2.0 +``` + +To retain your custom paths, you'd run: + +```console +$ docker run -p 8086:8086 \ + -v influxdb:/root/influxdb/data \ + -v influxdb2:/root/influxdb2/data \ + -v influxdb2-config:/etc/influxdb2 \ + -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf \ + -e DOCKER_INFLUXDB_INIT_MODE=upgrade \ + -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \ + -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \ + -e DOCKER_INFLUXDB_INIT_ORG=my-org \ + -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \ + -e DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG=/root/influxdb/influxdb.conf \ + -e DOCKER_INFLUXDB_CONFIG_PATH=/root/influxdb2/config.toml \ + -e DOCKER_INFLUXDB_BOLT_PATH=/root/influxdb2/influxdb.bolt \ + -e DOCKER_INFLUXDB_ENGINE_PATH=/root/influxdb2/engine \ + %%IMAGE%%:2.0 +``` + +### Upgrading from quay.io-hosted InfluxDB 2.x image + +Early Docker builds of InfluxDB 2.x were hosted at `quay.io/influxdb/influxdb`. The builds were very bare-bones, containing the `influx` and `influxd` binaries without any default configuration or helper scripts. By default, the `influxd` process stored data under `/root/.influxdbv2`. + +Starting with `v2.0.4`, we've restored our DockerHub build. This build defaults to storing data in `/var/lib/influxdb2`. Upgrading directly from `quay.io/influxdb/influxdb` to `influxdb:2.0.4` without modifying any settings will appear to cause data loss, as the new process won't be able to find your existing data files. + +To avoid this problem when migrating from `quay.io/influxdb/influxdb` to `influxdb:2.0`, you can use one of the following approaches. + +#### Change volume mount point + +If you don't mind using the new default path, you can switch the mount-point for the volume containing your data: + +```console +# Migrate from this: +$ docker run -p 8086:8086 \ + -v $PWD:/root/.influxdbv2 \ + quay.io/influxdb/influxdb:v2.0.3 + +# To this: +docker run -p 8086:8086 \ + -v $PWD:/var/lib/influxdb2 \ + %%IMAGE%%:2.0 +``` + +#### Override default configs + +If you'd rather keep your data files in the home directory, you can override the container's default config: + +```console +# Migrate from this: +$ docker run -p 8086:8086 \ + -v $PWD:/root/.influxdbv2 \ + quay.io/influxdb/influxdb:v2.0.3 + +# To this: +docker run -p 8086:8086 \ + -e INFLUXD_BOLT_PATH=/root/.influxdbv2/influxd.bolt \ + -e INFLUXD_ENGINE_PATH=/root/.influxdbv2/engine \ + -v $PWD:/root/.influxdbv2 \ + %%IMAGE%%:2.0 +``` + +See the section about configuration below for more ways to override the data paths. + ## Using this Image - InfluxDB 1.x ### Running the container From fadeed6f4d99d53a77c9eb69bdbd5ffb916b4a9f Mon Sep 17 00:00:00 2001 From: Kasper Guldmann <393906+kalleguld@users.noreply.github.com> Date: Tue, 29 Nov 2022 03:54:55 +0100 Subject: [PATCH 3/3] influxDB: formatting --- influxdb/content.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/influxdb/content.md b/influxdb/content.md index 6a06b59aff29..83ebe353d489 100644 --- a/influxdb/content.md +++ b/influxdb/content.md @@ -12,15 +12,16 @@ InfluxDB is a time series database built from the ground up to handle high write Using this image is pretty easy, but there are a few things you should know. -- You should forward TCP port 8086 -- You should mount a volume in /var/lib/influxdb2 +- You should forward TCP port 8086 +- You should mount a volume in /var/lib/influxdb2 ```console $ docker run \ - -p 8086:8086 \ - -v myInfluxVolume:/var/lib/influxdb2 \ - %%IMAGE%%:latest + -p 8086:8086 \ + -v myInfluxVolume:/var/lib/influxdb2 \ + %%IMAGE%%:latest ``` + After starting the container you can use the web interface at http://localhost:8086/ to setup and customize your Influx database. Find more about API Endpoints & Ports [here](https://docs.influxdata.com/influxdb/v2.5/reference/api/).