diff --git a/influxdb/content.md b/influxdb/content.md index 4fc68e94e3d4..83ebe353d489 100644 --- a/influxdb/content.md +++ b/influxdb/content.md @@ -6,217 +6,25 @@ 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 -### 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 -``` +### Quick start -Modify `$PWD` to the directory where you want to store data associated with the InfluxDB container. +Using this image is pretty easy, but there are a few things you should know. -You can also have Docker control the volume mountpoint by using a named volume. +- You should forward TCP port 8086 +- You should mount a volume in /var/lib/influxdb2 ```console -$ docker run -p 8086:8086 \ - -v influxdb2:/var/lib/influxdb2 \ - %%IMAGE%%:2.0 +$ docker run \ + -p 8086:8086 \ + -v myInfluxVolume:/var/lib/influxdb2 \ + %%IMAGE%%:latest ``` -### Exposed Ports - -The following ports are important and are used by InfluxDB. - -- 8086 HTTP UI and API port +After starting the container you can use the web interface at http://localhost:8086/ to setup and customize your Influx database. -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 @@ -420,6 +228,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