Create an InfluxDB template

Use the InfluxDB user interface (UI) and the influx export command to create InfluxDB templates from resources in an organization. Add buckets, Telegraf configurations, tasks, and more in the InfluxDB UI and then export those resources as a template.

Create a template

Creating a new organization to contain only your template resources is an easy way to ensure you export the resources you want. Follow these steps to create a template from a new organization.

  1. Start InfluxDB.

  2. Create a new organization.

  3. In the InfluxDB UI, add one or more resources.

  4. Create an All-Access API token (or a token that has read access to the organization).

  5. Use the API token from Step 4 with the influx export all subcommand to export all resources in the organization to a template file.

    1. influx export all \
    2.   -o YOUR_INFLUX_ORG \
    3.   -t YOUR_ALL_ACCESS_TOKEN \
    4.   -f ~/templates/template.yml

Export resources to a template

The influx export command and subcommands let you export resources from an organization to a template manifest. Your API token must have read access to resources that you want to export.

If you want to export resources that depend on other resources, be sure to export the dependencies.

Authentication credentials

The examples below assume your InfluxDB host, organization, and token are provided by the active influx CLI configuration. If you do not have a CLI configuration set up, use the appropriate flags to provide these required credentials.

To create a template that adds, modifies, and deletes resources when applied to an organization, use InfluxDB stacks. First, initialize the stack and then export the stack.

To create a template that only adds resources when applied to an organization (and doesn’t modify existing resources there), choose one of the following:

Export all resources

To export all resources within an organization to a template manifest file, use the influx export all subcommand with the --file (-f) option.

Provide the following:

  • Destination path and filename for the template manifest. The filename extension determines the output format:
    • your-template.yml: YAML format
    • your-template.json: JSON format
  1. # Syntax
  2. influx export all -f <FILE_PATH>

Export resources filtered by labelName or resourceKind

The influx export all subcommand accepts a --filter option that exports only resources that match specified label names or resource kinds. To filter on label name and resource kind, provide a --filter for each.

Export only dashboards and buckets with specific labels

The following example exports resources that match this predicate logic:

  1. (resourceKind == "Bucket" or resourceKind == "Dashboard")
  2. and
  3. (labelName == "Example1" or labelName == "Example2")
  1. influx export all \
  2.   -f ~/templates/template.yml \
  3.   --filter=resourceKind=Bucket \
  4.   --filter=resourceKind=Dashboard \
  5.   --filter=labelName=Example1 \
  6.   --filter=labelName=Example2

For more options and examples, see the influx export all subcommand.

Export specific resources

To export specific resources by name or ID, use the influx export command with one or more lists of resources to include.

Provide the following:

  • Destination path and filename for the template manifest. The filename extension determines the output format:
    • your-template.yml: YAML format
    • your-template.json: JSON format
  • Resource options with corresponding lists of resource IDs or resource names to include in the template. For information about what resource options are available, see the influx export command.
  1. # Syntax
  2. influx export -f <file-path> [resource-flags]

Export specific resources by ID

  1. influx export \
  2.   --org-id ed32b47572a0137b \
  3.   -f ~/templates/template.yml \
  4.   -t $INFLUX_TOKEN \
  5.   --buckets=00x000ooo0xx0xx,o0xx0xx00x000oo \
  6.   --dashboards=00000xX0x0X00x000 \
  7.   --telegraf-configs=00000x0x000X0x0X0

Export specific resources by name

  1. influx export \
  2.   --org-id ed32b47572a0137b \
  3.   -f ~/templates/template.yml \
  4.   --bucket-names=bucket1,bucket2 \
  5.   --dashboard-names=dashboard1,dashboard2 \
  6.   --telegraf-config-names=telegrafconfig1,telegrafconfig2

Export a stack

To export an InfluxDB stack and all its associated resources as a template, use the influx export stack command. Provide the following:

  • Organization name or ID
  • API token with read access to the organization
  • Destination path and filename for the template manifest. The filename extension determines the output format:
    • your-template.yml: YAML format
    • your-template.json: JSON format
  • Stack ID

Export a stack as a template

  1. # Syntax
  2. influx export stack \
  3.   -o <INFLUX_ORG> \
  4.   -t <INFLUX_TOKEN> \
  5.   -f <FILE_PATH> \
  6.   <STACK_ID>
  8. # Example
  9. influx export stack \
  10.   -o my-org \
  11.   -t mYSuP3RS3CreTt0K3n
  12.   -f ~/templates/awesome-template.yml \
  13.   05dbb791a4324000

Include user-definable resource names

After exporting a template manifest, replace resource names with environment references to let users customize resource names when installing your template.

  1. Export a template.

  2. Select any of the following resource fields to update:

    • metadata.name
    • associations[].name
    • endpointName (unique to NotificationRule resources)

  3. Replace the resource field value with an envRef object with a key property that references the key of a key-value pair the user provides when installing the template. During installation, the envRef object is replaced by the value of the referenced key-value pair. If the user does not provide the environment reference key-value pair, InfluxDB uses the key string as the default value.

    YAML JSON

    1. apiVersion: influxdata.com/v2alpha1
    2. kind: Bucket
    3. metadata:
    4.   name:
    5.     envRef:
    6.       key: bucket-name-1
    1. {
    2.   "apiVersion": "influxdata.com/v2alpha1",
    3.   "kind": "Bucket",
    4.   "metadata": {
    5.     "name": {
    6.       "envRef": {
    7.         "key": "bucket-name-1"
    8.       }
    9.     }
    10.   }
    11. }

Using the example above, users are prompted to provide a value for bucket-name-1 when applying the template. Users can also include the --env-ref flag with the appropriate key-value pair when installing the template.

  1. # Set bucket-name-1 to "myBucket"
  2. influx apply \
  3.   -f /path/to/template.yml \
  4.   --env-ref=bucket-name-1=myBucket

If sharing your template, we recommend documenting what environment references exist in the template and what keys to use to replace them.

Resource fields that support environment references

Only the following fields support environment references:

  • metadata.name
  • spec.endpointName
  • spec.associations.name

Troubleshoot template results and permissions

If you get unexpected results, missing resources, or errors when exporting templates, check the following:

Ensure read access

The API token must have read access to resources that you want to export. The influx export all command only exports resources that the API token can read. For example, to export all resources in an organization that has ID abc123, the API token must have the read:/orgs/abc123 permission.

To learn more about permissions, see how to view authorizations and how to create a token with specific permissions.

Use Organization ID

If your token doesn’t have read access to the organization and you want to export specific resources, use the --org-id <org-id> flag (instead of -o <org-name> or --org <org-name>) to provide the organization.

Check for resource dependencies

If you want to export resources that depend on other resources, be sure to export the dependencies as well. Otherwise, the resources may not be usable.

Share your InfluxDB templates

Share your InfluxDB templates with the entire InfluxData community. Contribute your template to the InfluxDB Community Templates repository on GitHub.

View InfluxDB Community Templates