Upgrade from InfluxDB 1.x to 2.3 with Docker

This page documents an earlier version of InfluxDB. InfluxDB v2.7 is the latest stable version. View this page in the v2.7 documentation.

Use the automated upgrade process built into the InfluxDB 2.x Docker image to update InfluxDB 1.x Docker deployments to InfluxDB 2.x.

Export continuous queries before upgrading

The automated upgrade process does not migrate InfluxDB 1.x continuous queries (CQs) to InfluxDB 2.x tasks (the 2.x equivalent). Export all of your CQs before upgrading to InfluxDB 2.x. For information about exporting and migrating CQs to tasks, see Migrate continuous queries to tasks.

Upgrade requirements

InfluxDB 2.x provides a 1.x compatibility API, but expects a different storage layout on disk. To account for theses differences, the InfluxDB Docker image migrates 1.x data and into 2.x-compatible data automatically before booting the influxd server.

To ensure InfluxDB reboots post-upgrade without overwriting migrated data, the upgrade won’t run if an existing boltdb file is found at the configured 2.x configuration path.

Find more information about the automated InfluxDB upgrade process, see Automatically upgrade from InfluxDB 1.x to 2.3.

InfluxDB 2.x initialization credentials

The automated InfluxDB upgrade process bootstraps an initial admin user, organization, and bucket required by InfluxDB 2.x. Set the following environment variables in your Docker container to provide setup credentials:

  • DOCKER_INFLUXDB_INIT_USERNAME: Username to set for the admin user (Required).
  • DOCKER_INFLUXDB_INIT_PASSWORD: Password to set for the admin user (Required).
  • DOCKER_INFLUXDB_INIT_ORG: Name to set for the initial organization (Required).
  • DOCKER_INFLUXDB_INIT_BUCKET: Name to set for the initial bucket (Required).
  • DOCKER_INFLUXDB_INIT_RETENTION: Duration for the initial bucket’s retention period. If not set, the initial bucket will retain data forever.
  • DOCKER_INFLUXDB_INIT_ADMIN_TOKEN: API token to associate with the admin user. If not set, InfluxDB automatically generates a token.

File system mounts

The InfluxDB upgrade process requires extra volumes to be mounted into the 2.x container. Use environment variables and Docker mounts to specify and configure the appropriate mount paths for the following:

  • 1.x data on disk
  • Custom 1.x configuration file (if any)
  • 2.x data on disk (/var/lib/influxdb2)
  • 2.x configuration directory (/etc/influxdb2)

The InfluxDB upgrade process searches for mounted 1.x data and configuration files in the following priority order:

  1. 1.x configuration file specified by the DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG environment variable
  2. 1.x data directory specified by the DOCKER_INFLUXDB_INIT_UPGRADE_V1_DIR environment variable
  3. 1.x configuration file mounted at /etc/influxdb/influxdb.conf
  4. 1.x data directory mounted at /var/lib/influxdb

Avoid data loss

By default, the automated upgrade process generates both data and configuration files under /var/lib/influxdb2 and /etc/influxdb2. We recommend mounting volumes at both paths to avoid losing data.

Upgrade initialization mode

Set the DOCKER_INFLUXDB_INIT_MODE environment variable to upgrade.

Minimal upgrade

If you’re currently running a minimal InfluxDB 1.x deployment similar to:

  1. docker run -p 8086:8086 \
  2.   -v influxdb:/var/lib/influxdb \
  3.   influxdb:1.8

To upgrade this minimal deployment to InfluxDB 2.x:

  1. Stop the running InfluxDB 1.x container.

  2. Start the InfluxDB container with the following:

    • Volume mount for the InfluxDB 1.x data directory
    • Volume mount for the InfluxDB 2.x data directory
    • InfluxDB initialization mode environment variable
    • InfluxDB initialization credential environment variables
    • influxdb:2.3 Docker image
    1. docker run -p 8086:8086 \
    2.   -v influxdb:/var/lib/influxdb \
    3.   -v influxdb2:/var/lib/influxdb2 \
    4.   -e DOCKER_INFLUXDB_INIT_MODE=upgrade \
    5.   -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \
    6.   -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \
    7.   -e DOCKER_INFLUXDB_INIT_ORG=my-org \
    8.   -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \
    9.   influxdb:2.3

Upgrade with a custom InfluxDB 1.x configuration file

If you’re currently running an InfluxDB 1.x deployment with a custom configuration file similar to:

  1. docker run -p 8086:8086 \
  2.   -v influxdb:/var/lib/influxdb \
  3.   -v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf:ro \
  4.   influxdb:1.8

To upgrade an InfluxDB 1.x deployment with a custom configuration file to InfluxDB 2.x:

  1. Stop the running InfluxDB 1.x container.

  2. Start the InfluxDB container with the following:

    • Volume mount for the InfluxDB 1.x data directory
    • Volume mount for the InfluxDB 1.x configuration file
    • Volume mount for the InfluxDB 2.x data directory (/var/lib/influxdb2)
    • Volume mount for the InfluxDB 2.x configuration directory (/etc/influxdb2)
    • InfluxDB initialization mode environment variable
    • InfluxDB initialization credential environment variables
    • influxdb:2.3 Docker image
  1. docker run -p 8086:8086 \
  2.   -v influxdb:/var/lib/influxdb \
  3.   -v $PWD/influxdb.conf:/etc/influxdb/influxdb.conf:ro \
  4.   -v influxdb2:/var/lib/influxdb2 \
  5.   -v influxdb2:/etc/influxdb2 \
  6.   -e DOCKER_INFLUXDB_INIT_MODE=upgrade \
  7.   -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \
  8.   -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \
  9.   -e DOCKER_INFLUXDB_INIT_ORG=my-org \
  10.   -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \
  11.   influxdb:2.3

Upgrade with custom paths

If you’re currently running an InfluxDB 1.x deployment with the data directory and configuration file mounted at custom paths similar to:

  1. docker run -p 8086:8086 \
  2.   -v influxdb:/root/influxdb/data \
  3.   -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf:ro \
  4.   influxdb:1.8 -config /root/influxdb/influxdb.conf

To upgrade an InfluxDB 1.x deployment with custom paths to InfluxDB 2.x:

  1. Stop the running InfluxDB 1.x container.
  2. Decide to either keep using custom paths or use InfluxDB 2.x default paths.

Keep using custom paths Use InfluxDB 2.x defaults

To retain your custom InfluxDB 1.x paths, start the InfluxDB container with the following:

  • Volume mount for the InfluxDB 1.x data directory
  • Volume mount for the InfluxDB 1.x configuration file
  • Volume mount for the InfluxDB 2.x data directory
  • Volume mount for the InfluxDB 2.x configuration directory
  • InfluxDB initialization mode environment variable
  • InfluxDB initialization credential environment variables
  • InfluxDB 2.x v1 configuration file path environment variable:
    • DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG
  • InfluxDB 1.x custom path environment variables:
    • INFLUXD_CONFIG_PATH
    • INFLUXD_BOLT_PATH
    • INFLUXD_ENGINE_PATH
  • influxdb:<span class="current-version">2.3</span> Docker image
  1. docker run -p 8086:8086 \
  2.   -v influxdb:/root/influxdb/data \
  3.   -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf:ro \
  4.   -v influxdb2:/root/influxdb2/data \
  5.   -v influxdb2:/root/influxdb2 \
  6.   -e DOCKER_INFLUXDB_INIT_MODE=upgrade \
  7.   -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \
  8.   -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \
  9.   -e DOCKER_INFLUXDB_INIT_ORG=my-org \
  10.   -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \
  11.   -e DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG=/root/influxdb/influxdb.conf \
  12.   -e INFLUXD_CONFIG_PATH=/root/influxdb2/config.toml \
  13.   -e INFLUXD_BOLT_PATH=/root/influxdb2/influxdb.bolt \
  14.   -e INFLUXD_ENGINE_PATH=/root/influxdb2/engine \
  15.   influxdb:<span class="current-version">2.3</span>

To use default InfluxDB 2.x paths, start the InfluxDB container with the following:

  • Volume mount for the InfluxDB 1.x data directory
  • Volume mount for the InfluxDB 1.x configuration file
  • Volume mount for the InfluxDB 2.x data directory (/var/lib/influxdb2)
  • Volume mount for the InfluxDB 2.x configuration directory (/etc/influxdb2)
  • InfluxDB initialization mode environment variable
  • InfluxDB initialization credential environment variables
  • InfluxDB 2.x v1 configuration file path environment variable:
    • DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG
  • influxdb:<span class="current-version">2.3</span> Docker image
  1. docker run -p 8086:8086 \
  2.   -v influxdb:/root/influxdb/data \
  3.   -v $PWD/influxdb.conf:/root/influxdb/influxdb.conf:ro \
  4.   -v influxdb2:/var/lib/influxdb2 \
  5.   -v influxdb2:/etc/influxdb2 \
  6.   -e DOCKER_INFLUXDB_INIT_MODE=upgrade \
  7.   -e DOCKER_INFLUXDB_INIT_USERNAME=my-user \
  8.   -e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \
  9.   -e DOCKER_INFLUXDB_INIT_ORG=my-org \
  10.   -e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \
  11.   -e DOCKER_INFLUXDB_INIT_UPGRADE_V1_CONFIG=/root/influxdb/influxdb.conf \
  12.   influxdb:<span class="current-version">2.3</span>