Documentation

Upgrade from InfluxDB OSS 2.x to InfluxDB Cloud

To upgrade from InfluxDB OSS 2.x to InfluxDB Cloud:

  1. Create an InfluxDB Cloud account
  2. Create an All-Access authentication token
  3. Set up influx CLI connection configurations
  4. Use templates to migrate InfluxDB resources
  5. Migrate DBRP mappings
  6. Dual write to InfluxDB 2.x and InfluxDB Cloud
  7. Migrate time series data
  8. Collaborate with other users

Consider when upgrading

  • InfluxDB Cloud requires token authentication, and you must create all new authentication tokens.
  • InfluxDB Cloud does not support:

Create an InfluxDB Cloud account

Do one of the following to create an InfluxDB Cloud account:

Create an All-Access authentication token

InfluxDB authentication tokens are unique to each organization. Create an All-Access token in your InfluxDB Cloud user interface (UI) to use for the upgrade process.

  1. Click Data (Load Data) > Tokens in the left navigation bar.

  2. Click Generate, and then select All-Access Token.

  3. Enter a description for the token, and then click Save.

If you’ve created other tokens in your InfluxDB 2.x instance for external libraries or integrations, create corresponding tokens for each in your InfluxDB Cloud instance. You cannot migrate tokens from InfluxDB 2.x to InfluxDB Cloud.

For more information about managing tokens and token types, see Manage tokens.

Set up influx CLI connection configurations

The influx command line interface (CLI) lets you create connection configurations that automatically provides host, organization, and authentication token credentials to CLI commands. Use the influx CLI packaged with InfluxDB 2.x and the influx config create command to set up the connection configurations for both your InfluxDB Cloud instance and your InfluxDB 2.x instance.

Include the following flags for each configuration:

  • --config-name: Unique name for the connection configuration. The examples below use cloud and oss respectively.
  • --host-url: InfluxDB Cloud region URL or InfluxDB 2.x URL.
  • --org: InfluxDB organization name. The default organization name in InfluxDB Cloud is the email address associated with your account.
  • --token: Authentication token to use to connect to InfluxDB. Provide an All-Access token (or an Operator token for 2.x).
Create an InfluxDB Cloud connection configuration
# Example cloud connection configuration
influx config create \
  --config-name cloud \
  --host-url https://cloud2.influxdata.com \
  --org your.email@example.com \
  --token mY5uP3rS3cRe7Cl0uDt0K3n
Create an InfluxDB 2.x connection configuration
# Example 2.x connection configuration
influx config create \
  --config-name oss \
  --host-url http://localhost:8086 \
  --org example-org \
  --token mY5uP3rS3cRe70S5t0K3n

Use templates to migrate InfluxDB resources

InfluxDB templates let you export InfluxDB resources such as buckets, dashboards, labels, tasks, and more and import them into another InfluxDB instance. Export resources from your InfluxDB 2.x instance and migrate them to your InfluxDB Cloud instance.

InfluxDB Cloud Free Plan resource limits

If upgrading to an InfluxDB Cloud Free Plan, you are only able to create a limited number of resources. If your exported template exceeds these limits, the resource migration will fail.

  • To migrate all resources from an InfluxDB 2.x organization to an InfluxDB Cloud organization:
    Use the influx export all command and pipe the output into the influx apply command. Use the --active-config flag with each command to specify which connection configuration to use:

    influx export all --active-config oss | influx apply --active-config cloud
    
  • To migrate specific resources from an InfluxDB 2.x organization to an InfluxDB Cloud organization:
    Use the influx export command with lists of specific resources to export or the influx export all command with filters. Pipe the output into the influx apply command. Use the --active-config flag with each command to specify which connection configuration to use:

    influx export \
      --active-config oss \
      --buckets 0Xx0oox00XXoxxoo1,0Xx0oox00XXoxxoo2 \
      --labels o0x0oox0Xxoxx001,o0x0oox0Xxoxx002 \
      --dashboards 0XxXooXoo0xooXo0X1,0XxXooXoo0xooXo0X2 | \
    influx apply --active-config cloud
    
    influx export all \
      --active-config oss \
      --filter=resourceKind=Bucket \
      --filter=resourceKind=Dashboard \
      --filter=labelName=Foo | \
    influx apply --active-config cloud
    

    For more export command examples, see the influx export and influx export all documentation.

    Update hardcoded InfluxDB URLs

    If any of your migrated resources contain hardcoded InfluxDB URLs (http://localhost:8086), do one of the following to update these URLs to your InfluxDB Cloud region URL:

    • Migrate your resources to InfluxDB Cloud, and then update URLs in the InfluxDB Cloud UI.
    • Save your template to a file, update URLs in the file, and then apply the template to your InfluxDB Cloud instance.

Migrate DBRP mappings

InfluxDB database and retention policy (DBRP) mappings let you query InfluxDB Cloud buckets with InfluxQL and the InfluxDB 1.x DBRP convention. If you have DBRP mappings in your InfluxDB 2.x instance, migrate them to your InfluxDB Cloud instance.

Migrate DBRP mappings to InfluxDB Cloud

Dual write to InfluxDB 2.x and InfluxDB Cloud

Update external clients to write to your InfluxDB Cloud instance. We recommend writing data to both InfluxDB 2.x and InfluxDB Cloud until you finish migrating your existing time series data.

Configure external clients with your InfluxDB Cloud host, organization, and authentication token.

Update Telegraf configurations

If using Telegraf configurations migrated to or stored in InfluxDB Cloud, update your Telegraf configurations in InfluxDB Cloud to write to both InfluxDB 2.x and InfluxDB Cloud:

  1. Update your Telegraf configuration with a second influxdb_v2 output to write to your InfluxDB Cloud instance.

    Example dual-write Telegraf configuration
    # Write metrics to InfluxDB 2.x
    [[outputs.influxdb_v2]]
      urls = ["https://localhost:8086"]
      token = "$INFLUX_TOKEN"
      organization = "example-org"
      bucket = "example-bucket"
    
    # Write metrics to InfluxDB Cloud
    [[outputs.influxdb_v2]]
      urls = ["https://cloud2.influxdata.com"]
      token = "$INFLUX_CLOUD_TOKEN"
      organization = "your.email@example.com"
      bucket = "example-bucket"
    
  2. Add the following environment variables to your Telegraf environment(s):

    • INFLUX_TOKEN: InfluxDB 2.x authentication token
    • INFLUX_CLOUD_TOKEN: InfluxDB Cloud authentication token
  3. Use the command provided in your Telegraf Setup Instructions to restart Telegraf with the updated configuration and begin writing to both InfluxDB 2.x and InfluxDB Cloud.

Migrate time series data

To migrate your time series data from your InfluxDB 2.x instance to your InfluxDB Cloud instance, do the following:

  1. Use the influx bucket list command to view a list of your InfluxDB 2.x buckets and their IDs.

    influx bucket list --active-config oss
    
  2. Use the influxd inspect export-lp command to export data from a bucket in your InfluxDB 2.x instance as line protocol. Include the following flags:

    • --bucket-id: Bucket ID to export
    • --engine-path: InfluxDB engine path
    • --output-path: Output file path
    • --compress: (Optional) Gzip the exported line protocol
    • --start: (Optional) Earliest timestamp to export
    • --end: (Optional) Latest timestamp to export
    influxd inspect export-lp \
      --bucket-id 12ab34cd56ef \
      --engine-path ~/.influxdbv2/engine \
      --compress \
      --output-path path/to/bucket-export.lp
    
  3. Use the influx write command to write your exported line protocol to your InfluxDB Cloud instance. Provide the following.

    • --bucket: Target bucket name
      OR
      --bucket-id: Target bucket ID
    • --compression: (Optional) gzip if the exported line protocol is compressed
    • --file: Import file path
    influx write \
      --active-config cloud \
      --bucket example-bucket \
      --compression gzip \
      --file path/to/bucket-export.lp
    
  4. Repeat steps 2-3 for each bucket.

InfluxDB Cloud write rate limits

Write requests are subject to rate limits associated with your InfluxDB Cloud pricing plan. If your exported line protocol size potentially exceeds your rate limits, consider doing one of the following:

  • Include the --rate-limit flag with influx write to rate limit written data.

    influx write \
      --active-config cloud \
      --bucket example-bucket \
      --file path/to/bucket-export.lp \
      --rate-limit "5 MB / 5 min"
    
  • Include --start and --end flags with influxd inpsect export-lp to limit exported data by time and then sequentially write the consecutive time ranges.

    influxd inspect export-lp \
      --bucket-id 12ab34cd56ef \
      --engine-path ~/.influxdbv2/engine \
      --start 2021-01-01T00:00:00Z \
      --end 2021-02-01T00:00:00Z \
      --compress \
      --output-path path/to/example-bucket-jan-2021.lp
    

To minimize network bandwidth usage, we recommend using gzip to compress exported line protocol. However, when writing to InfluxDB Cloud, Data In and Ingest batch size rate limits track the payload size of the uncompressed line protocol.

Migrate system buckets

InfluxDB system buckets contain data related to the InfluxDB monitoring and alerting system. Although the retention period for system buckets in both InfluxDB Cloud and InfluxDB 2.x is only seven days, if you want to migrate this data, use the same method described above to migrate time series data.

Export and write data in a single command

If your data and rate limits allow, you can export and write data in a single command without writing a line protocol export file to disk. The influxd inspect export-lp command can output to stdout and the influx write command accepts line protocol from stdin.

Export and write data

Collaborate with other users

To collaborate with other users in your InfluxDB Cloud organization, invite users to join your organization.


Select your region

Upgrade to InfluxDB Cloud or InfluxDB 2.0!

InfluxDB Cloud and InfluxDB OSS 2.0 ready for production.