Documentation

Use InfluxDB templates

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

Preview, validate, and apply templates for InfluxDB resources. Learn how to find and use InfluxDB community templates. Learn how to use secrets and custom names in templates.

Get prebuilt templates

The InfluxDB community templates repository is home to a growing number of InfluxDB templates developed and maintained by others in the InfluxData community. You can use the CLI or API to apply community templates directly from GitHub URLs or you can download the templates and apply them from your system.

The master branch of the InfluxDB community templates repository contains the most current published version of each template. When attempting to access community templates via URL, use the following as the root of the template URL:

https://raw.githubusercontent.com/influxdata/community-templates/master/

For example, the most current version of the Docker community template can be accessed via:

https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml

View InfluxDB Community Templates

View a template summary

With the influx CLI, you can generate a summary of template resources. The summary contains resource metadata in table format that you can review before applying the template to your InfluxDB instance. You can generate a summary for a template located at a file path or at a URL.

You can’t generate a template summary with the InfluxDB /api/v2 API.

View a template summary with the CLI

To view a template summary, use the influx template command.

# Syntax
influx template --file TEMPLATE_FILE_PATH
influx template -f TEMPLATE_FILE_PATH

influx template --template-url TEMPLATE_FILE_URL
influx template -u TEMPLATE_FILE_URL

--file and --template-url aren’t repeatable with the influx template command; you can only generate a summary for one template at a time.

The following code samples show how to generate a template summary:

  • Summarize a template located on the local file system:

    influx template --file /Users/me/template.yml
    
  • Summarize a template located at a remote URL:

    influx template --template-url https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml
    

The output is a series of tables that contain template resource metadata.

Validate a template

Use the CLI or API to validate and troubleshoot templates before you apply them to your InfluxDB instance.

Validate a template with the CLI

Use the influx template validate command to validate a template from your local file system or a URL.

# Syntax
influx template validate --file TEMPLATE_FILE_PATH
influx template validate -f TEMPLATE_FILE_PATH

influx template validate --template-url TEMPLATE_FILE_URL
influx template validate -u TEMPLATE_FILE_URL

The following code sample shows how to validate a template located on the local file system:

influx template validate --file /path/to/template.yml

The following code sample shows how to validate the linux_system community template located on GitHub:

influx template validate --template-url https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml

To validate a template and preview the changes for your InfluxDB instance, see how to use a template dry run.

Validate a template with the API

To validate a template with the API, use a template dry run.

Use a template dry run to preview changes

Before you install a template, you can do a dry run to preview the installation.

By default, when you apply a template, InfluxDB installs the template, creates or updates resources in the stack, and generates a diff of the changes. With the dryRun option, InfluxDB validates the template and generates the resource diff, but doesn’t make any changes to your instance.

To do a template dry run, pass "dryRun": true in the InfluxDB /api/v2/templates/apply API endpoint request body.

POST /api/v2/templates/apply

When running API code samples, replace the following in each sample:

  • INFLUX_TOKEN: your InfluxDB API token that has write permission for the organization.
  • INFLUX_ORG_ID: your InfluxDB organization ID.

When applying templates, you must use an API token that has write permission for the resource types configured in the template. See tokens for more information.

Consider a template that contains an unsupported value–for example, the following template contains an invalid InfluxDB resource type ("kind": "Foo"):

{
  "contents": [
    {
      "apiVersion": "influxdata.com/v2alpha1",
      "kind": "Foo",
      "metadata": {
        "name": "unruffled-benz-d4d007"
      },
      "spec": {
        "color": "#326BBA",
        "name": "inputs.cpu"
      }
    },
    {
      "apiVersion": "influxdata.com/v2alpha1",
      "kind": "Label",
      "metadata": {
        "name": "unruffled-boa-d4a001"
      },
      "spec": {
        "color": "#326BBA",
        "name": "inputs.mem"
      }
    }
  ]
}

The following code sample shows how to pass dryRun: true and the template to the /api/v2/templates/apply endpoint:

  curl "http://localhost:8086/api/v2/templates/apply" \
    --header "Authorization: Token INFLUX_TOKEN" \
    --data @- << EOF
      {
        "dryRun": true,
        "orgID": "INFLUX_ORG_ID",
        "template":
          {
            "contents": [
              {
                "apiVersion": "influxdata.com/v2alpha1",
                "kind": "Foo",
                "metadata": {
                  "name": "unruffled-benz-d4d007"
                },
                "spec": {
                  "color": "#326BBA",
                  "name": "inputs.cpu"
                }
              },
              {
                "apiVersion": "influxdata.com/v2alpha1",
                "kind": "Label",
                "metadata": {
                  "name": "unruffled-boa-d4a001"
                },
                "spec": {
                  "color": "#326BBA",
                  "name": "inputs.mem"
                }
              }
            ]
          }
      }
EOF

If you run the code sample, InfluxDB responds with a 422 status code and a response body similar to the following:

{
  "sources": [],
  "stackID": "",
  "diff": {
    "buckets": [],
    "checks": [],
    "dashboards": [],
    "labels": [],
    "labelMappings": [],
    "notificationEndpoints": [],
    "notificationRules": [],
    "tasks": [],
    "telegrafConfigs": [],
    "variables": []
  },
  "summary": {
    "buckets": [],
    "checks": [],
    "dashboards": [],
    "notificationEndpoints": [],
    "notificationRules": [],
    "labels": [],
    "labelMappings": [],
    "missingEnvRefs": null,
    "missingSecrets": null,
    "summaryTask": [],
    "telegrafConfigs": [],
    "variables": []
  },
  "errors": [
    {
      "kind": "Foo",
      "fields": [
        "root",
        "kind"
      ],
      "idxs": [
        0,
        null
      ],
      "reason": "unsupported kind provided"
    }
  ],
  "code": "unprocessable entity",
  "message": "unprocessable entity"
}

Given the invalid Foo type, the template fails validation and the response contains the following:

  • empty stack ID
  • empty resource diffs
  • list of errors
  • error code and message

If you replace "kind": "Foo" with "kind": "Label" in the sample and pass it in a new dry run request, InfluxDB responds with a 200 OK status: the template is valid, and the response body is similar to the following:

{
  "sources": [
    "byte stream"
  ],
  "stackID": "",
  "diff": {
    "buckets": [],
    "checks": [],
    "dashboards": [],
    "labels": [
      {
        "id": 0,
        "stateStatus": "new",
        "templateMetaName": "unruffled-benz-d4d007",
        "kind": "Label",
        "new": {
          "name": "inputs.cpu",
          "color": "#326BBA",
          "description": ""
        },
        "old": null
      },
      {
        "id": 0,
        "stateStatus": "new",
        "templateMetaName": "unruffled-boa-d4a001",
        "kind": "Label",
        "new": {
          "name": "inputs.mem",
          "color": "#326BBA",
          "description": ""
        },
        "old": null
      }
    ],
    "labelMappings": [],
    "notificationEndpoints": [],
    "notificationRules": [],
    "tasks": [],
    "telegrafConfigs": [],
    "variables": []
  },
  "summary": {
    "buckets": [],
    "checks": [],
    "dashboards": [],
    "notificationEndpoints": [],
    "notificationRules": [],
    "labels": [
      {
        "kind": "Label",
        "templateMetaName": "unruffled-benz-d4d007",
        "envReferences": [],
        "id": 0,
        "orgID": 5244587287857221000,
        "name": "inputs.cpu",
        "properties": {
          "color": "#326BBA",
          "description": ""
        }
      },
      {
        "kind": "Label",
        "templateMetaName": "unruffled-boa-d4a001",
        "envReferences": [],
        "id": 0,
        "orgID": 5244587287857221000,
        "name": "inputs.mem",
        "properties": {
          "color": "#326BBA",
          "description": ""
        }
      }
    ],
    "labelMappings": [],
    "missingEnvRefs": [],
    "missingSecrets": [],
    "summaryTask": [],
    "telegrafConfigs": [],
    "variables": []
  }
}
  • The dry run diff shows that the template would add two Label resources.
  • Labels with id: 0 indicate that no labels were created.
  • An empty stackID indicates that no stack was created or updated.

Apply templates to an InfluxDB instance

When you apply a template, you specify the organization that owns the template resources. InfluxDB validates and then installs the template to create and update resources in the organization. If you provide a stack ID when applying a template, InfluxDB updates the installed stack in your instance. If you apply a template without providing a stack ID, InfluxDB initializes a new stack with all new resources.

To learn how to use InfluxDB stacks, see InfluxDB stacks.

After applying the template, InfluxDB responds with the following:

  • Stack ID for the stack that was created or updated
  • A diff of added and removed resources

When running API code samples, replace the following in each sample:

  • INFLUX_TOKEN: your InfluxDB API token that has write permission for the organization.
  • INFLUX_ORG_ID: your InfluxDB organization ID.

When applying templates, you must use an API token that has write permission for the resource types configured in the template. See tokens for more information.

Use the influx CLI or /api/v2 API to apply templates to an InfluxDB instance.

Apply templates with the CLI

Use the influx apply command to install templates to your InfluxDB organization. You can apply templates stored in your local file system or from URLs.

The following code sample uses influx apply to apply the sample-data template to the $INFLUX_ORG configured in the environment:

influx apply \
--template-url https://raw.githubusercontent.com/influxdata/community-templates/master/sample-data/sample-data.yml \
--token INFLUX_TOKEN

Once the template is applied, InfluxDB responds with the stack ID and a table-formatted diff. The output is similar to the following:

BUCKETS    +add | -remove | unchanged
+-----+--------------------+------------------+---------------+------------------+-------------+-------------+------------------+
| +/- |   METADATA NAME    |        ID        | RESOURCE NAME | RETENTION PERIOD | DESCRIPTION | SCHEMA TYPE | NUM MEASUREMENTS |
+-----+--------------------+------------------+---------------+------------------+-------------+-------------+------------------+
| +   | sample-data-bucket | 0000000000000000 | sample_data   | 168h0m0s         |             | implicit    | 0                |
+-----+--------------------+------------------+---------------+------------------+-------------+-------------+------------------+
|                                                                                                   TOTAL    |        1         |
+-----+--------------------+------------------+---------------+------------------+-------------+-------------+------------------+

TASKS    +add | -remove | unchanged
+-----+-------------------+------------------+-------------------+-------------+-------+
| +/- |   METADATA NAME   |        ID        |   RESOURCE NAME   | DESCRIPTION | CYCLE |
+-----+-------------------+------------------+-------------------+-------------+-------+
| +   | fetch-sample-data | 0000000000000000 | Fetch Sample Data |             |       |
+-----+-------------------+------------------+-------------------+-------------+-------+
|                                                                     TOTAL    |   1   |
+-----+-------------------+------------------+-------------------+-------------+-------+

BUCKETS
+--------------------+------------------+---------------+-----------+--------------------------------+-------------+
|    PACKAGE NAME    |        ID        | RESOURCE NAME | RETENTION |          DESCRIPTION           | SCHEMA TYPE |
+--------------------+------------------+---------------+-----------+--------------------------------+-------------+
| sample-data-bucket | d981dd0a2fed16be |  sample_data  | 168h0m0s  |                                |  implicit   |
+--------------------+------------------+---------------+-----------+--------------------------------+-------------+
|                                                                                 TOTAL              |      1      |
+--------------------+------------------+---------------+-----------+--------------------------------+-------------+

Stack ID: 09bd87cd33be3000

Apply a template from the file system

To install templates stored on your local machine, pass the -f, --file option with the relative or absolute file path of the template manifest.

# Syntax
influx apply --file TEMPLATE_FILE_PATH
influx apply -f TEMPLATE_FILE_PATH

The following code sample shows how to apply a template from a file path.

influx apply --file /Users/me/template.yml

To use one command to apply multiple templates, pass --file for each template file path–for example:

# Apply multiple templates
influx apply --org my-org \
  --file /path/to/first/template.yml \
  --file /path/to/second/template.yml

Apply all templates in a directory

To apply all templates in a directory, pass the --file option with the directory path where template manifests are stored. By default, this only applies templates stored in the specified directory. To apply all templates stored in the specified directory and its subdirectories, pass the --recurse flag.

# Syntax
influx apply --org INFLUX_ORG --file DIRECTORY_PATH [--recurse]

The following code sample shows how to apply all templates from a directory:

# Apply all templates in a directory
influx apply --org INFLUX_ORG --file /Users/me

The following code sample uses the --recurse flag to apply all templates from a directory and its subdirectories:

# Apply all templates in a directory and its subdirectories
influx apply --org INFLUX_ORG --file /Users/me --recurse

Apply a template from a URL

To apply a template from a URL, pass the --template-url, -u option with the URL of the template file.

# Syntax
influx apply --org INFLUX_ORG --template-url TEMPLATE_FILE_URL

The following code sample shows how to apply a community template located on GitHub:

# Apply a single template from a URL
influx apply --org my-org --template-url https://raw.githubusercontent.com/influxdata/community-templates/master/kafka/kafka-template.yml

To use one command to apply multiple templates from URLs, pass --template-url for each template file–for example:

# Apply multiple templates from URLs
influx apply --org my-org \
  --template-url https://example.com/templates/template1.yml \
  --template-url https://example.com/templates/template2.yml

Apply multiple templates from files and URLs

To use a single command to apply templates from multiple file paths and URLs, pass each template with the appropriate --file or --template-url option.

# Syntax
influx apply --org my-org --template-url TEMPLATE_FILE_URL --file TEMPLATE_FILE_PATH

The following code sample shows a single command to apply multiple templates from URLs and file paths:

influx apply --org INFLUX_ORG \
  --template-url https://example.com/templates/template1.yml \
  --template-url https://example.com/templates/template2.yml \
  --file ~/templates/custom-template.yml \
  --file ~/templates/iot/home/ \
  --recurse

The --recurse flag applies any templates from the ~/templates/iot/home/ directory and subdirectories.

Apply templates with the API

Use the /api/v2/templates/apply endpoint to install templates to your InfluxDB instance.

POST /api/v2/templates/apply

With the API, you can apply templates from remote URLs or template objects in your request.

Apply templates from template objects

To apply a template from a template object, pass the template parameter with a template in the request body. A template contains a contents property with a list of template resources. For more information about template schemas, see the /api/v2/templates/apply reference documentation.

The following code sample shows how to define a template and apply it with the /api/v2/templates/apply API endpoint:

curl "http://localhost:8086/api/v2/templates/apply" \
  --header "Authorization: Token INFLUX_TOKEN" \
  --data @- << EOF
  { "orgID": "INFLUX_ORG_ID",
    "dryRun": true,
    "template": {
      "contents": [
        {
          "apiVersion": "influxdata.com/v2alpha1",
          "kind": "Bucket",
          "metadata": {
            "name": "heuristic-sinoussi-004"
          },
          "spec": {
            "name": "docker",
            "retentionRules": [
              {
                "everySeconds": 604800,
                "type": "expire"
              }
            ]
          }
        },
        {
          "apiVersion": "influxdata.com/v2alpha1",
          "kind": "Label",
          "metadata": {
            "name": "unruffled-benz-004"
          },
          "spec": {
            "color": "#326BBA",
            "name": "inputs.cpu"
          }
        }
      ]
    }
  }
EOF

To apply multiple templates in a single request, pass the templates parameter with an array of template objects in the request body–for example:

curl "http://localhost:8086/api/v2/templates/apply" \
  --header "Authorization: Token INFLUX_TOKEN" \
  --data @- << EOF
  { "orgID": "INFLUX_ORG_ID",
    "dryRun": true,
    "templates": [
      { "contents": [{
          "apiVersion": "influxdata.com/v2alpha1",
          "kind": "Label",
          "metadata": {
            "name": "unruffled-benz-001"
          },
          "spec": {
            "color": "#326BBA",
            "name": "inputs.cpu"
          }
        }]
      },
      { "contents": [{
          "apiVersion": "influxdata.com/v2alpha1",
          "kind": "Bucket",
          "metadata": {
            "name": "heuristic-sinoussi-004"
          },
          "spec": {
            "name": "docker",
            "retentionRules": [
              {
                "everySeconds": 604800,
                "type": "expire"
              }
            ]
          }
        }]
      }
    ]
  }
EOF

The template and templates parameters are mutually exclusive; if you pass both parameters in your request, InfluxDB responds with an error–for example:

{
...
  "errors": [
    {
      "kind": "Label",
      "fields": [
              "root",
              "spec",
              "name"
      ],
      "idxs": [
              2,
              null,
              null
      ],
      "reason": "duplicate name: unruffled-benz-004"
    }
  ],
  "code": "unprocessable entity",
  "message": "unprocessable entity"
}

Apply templates from URLs with the API

To apply a template located at a URL, pass remotes with an array in the request body. In the array, pass an object with the url property for the template you want to apply.

The following code sample shows how to install the linux_system community template located on GitHub:

curl "http://localhost:8086/api/v2/templates/apply" \
  --header "Authorization: Token INFLUX_TOKEN" \
  --data @- << EOF
    { "orgID": "INFLUX_ORG_ID",
      "remotes": [
        {
          "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml"
        }
      ]
    }
EOF

Apply templates from URLs and template objects

The following code sample shows how to pass remotes and templates parameters to apply templates from a URL and template objects:

curl "http://localhost:8086/api/v2/templates/apply" \
  --header "Authorization: Token INFLUX_TOKEN" \
  --data @- << EOF
    { "orgID": "INFLUX_ORG_ID",
      "dryRun": true,
      "remotes": [
        {
          "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml"
        }
      ],
      "templates": [
      { "contents": [{
          "apiVersion": "influxdata.com/v2alpha1",
          "kind": "Label",
          "metadata": {
            "name": "unruffled-benz-001"
          },
          "spec": {
            "color": "#326BBA",
            "name": "inputs.cpu"
          }
        }]
      },
      { "contents": [{
          "apiVersion": "influxdata.com/v2alpha1",
          "kind": "Bucket",
          "metadata": {
            "name": "heuristic-sinoussi-004"
          },
          "spec": {
            "name": "docker",
            "retentionRules": [
              {
                "everySeconds": 604800,
                "type": "expire"
              }
            ]
          }
        }]
      }]
    }
EOF

Define environment references

Some templates include environment references that let you provide custom names for resources and specs.

Define environment references with the CLI

The influx apply command prompts you to provide a value for each environment reference in the template. You can also provide values for environment references by passing an --env-ref option with a key-value pair comprised of the environment reference key and the value to replace it–for example:

influx apply --org INFLUX_ORG_ID --file /path/to/template.yml \
  --env-ref=bucket-name-1=myBucket
  --env-ref=label-name-1=Label1 \
  --env-ref=label-name-2=Label2

Define environment references with the API

To provide environment reference values when you apply a template with the /api/v2/templates/apply API endpoint, pass envRefs with key-value pairs in the request body.

The following code sample shows a request that defines environment references (envRef) in template objects, and passes environment reference values (envRefs):

  curl -v "http://localhost:8086/api/v2/templates/apply" \
    --header "Authorization: Token INFLUX_TOKEN" \
    --data @- << EOF
    { "orgID": "INFLUX_ORG_ID",
      "dryRun": true,
      "envRefs": {
        "linux-cpu-label": "MY_CPU_LABEL",
        "docker-bucket": "MY_DOCKER_BUCKET",
        "docker-spec-1": "MY_DOCKER_SPEC"
      },
      "templates": [
        { "contents": [{
            "apiVersion": "influxdata.com/v2alpha1",
            "kind": "Label",
            "metadata": {
              "name": {
                "envRef": {
                  "key": "linux-cpu-label"
                }
              }
            },
            "spec": {
              "color": "#326BBA",
              "name": "inputs.cpu"
            }
          }]
        },
        { "contents": [{
            "apiVersion": "influxdata.com/v2alpha1",
            "kind": "Bucket",
            "metadata": {
              "name": {
                "envRef": {
                  "key": "docker-bucket"
                }
              }
            },
            "spec": {
              "name": {
                "envRef": {
                  "key": "docker-spec-1"
                }
              },
              "retentionRules": [
                {
                  "everySeconds": 604800,
                  "type": "expire"
                }
              ]
            }
          }]
        }
      ]
    }
EOF

For more API schema detail, see the /api/v2/templates/apply reference documentation.

Pass secrets when installing a template

Some queries use secrets–for example, to access external APIs for sending data or messages.

The following example Flux (from the fortnite community template) requires aSLACK_WEBHOOK secret for sending a Slack message:

  import "slack"
  import "strings"
  import "influxdata/influxdb/secrets"
  webhook = secrets.get(key: "SLACK_WEBHOOK")
  sendSlackMessage = (text) =>
    (slack.message(
      url: webhook,
      token: "",
      channel: "",
      text: text,
      color: "good",
    ))
  from(bucket: "fortnite")
        |> range(start: -2h, stop: -30m)
        |> filter(fn: (r) =>
        (r["_measurement"] == "exec_fortnite"))
        |> filter(fn: (r) =>
        (r["_field"] == "squad_placetop1" or r["_field"] == "solo_placetop1" or r["_field"] == "duo_placetop1"))
        |> filter(fn: (r) =>
        (r["pro"] == "no" or r["pro"] == "yes"))
        |> group(columns: ["name", "_field"])
        |> drop(columns: ["_start", "_stop", "pro"])
        |> difference()
        |> group(columns: ["_time", "name"])
        |> filter(fn: (r) =>
        (r["_value"] == 1))
        |> map(fn: (r) =>
        ({r with newColumn: if r["_value"] == 1 then sendSlackMessage(text: "Congratulations to *${string(v: r.name)}* for winning a Fortnite *${strings.trimSuffix(v: r._field, suffix: "_placetop1")}* match! :boom: :boom: :boom:") else 100}))

When you apply a template that uses secrets, you can pass the secret key-value pairs in your request. Don’t include secret values in your template.

Pass secrets with the CLI

To define secret values when installing a template with the influx CLI, include the --secret flag with the secret key-value pair.

# Syntax
influx apply --org INFLUX_ORG --file TEMPLATE_FILE_PATH \
  [--secret=SECRET_KEY=SECRET_VALUE]

# Examples
# Define a single secret when applying a template
influx apply --org my-org --file /path/to/template.yml \
  --secret=FOO=BAR

# Define multiple secrets when applying a template
influx apply --org my-org --file /path/to/template.yml \
  --secret=FOO=bar \
  --secret=BAZ=quz

InfluxDB doesn’t expose secret values in CLI or API responses.

To add a secret after applying a template, see Add secrets.

Pass secrets with the API

To define secret values when installing a template with the InfluxDB /api/v2/templates/apply endpoint, pass the secrets parameter in the request body with an object that contains the secret key-value pairs.

The following code sample shows how to pass SLACK_WEBHOOK in secrets when applying the fortnite community template:

  curl "http://localhost:8086/api/v2/templates/apply" \
    --header "Authorization: Token INFLUX_TOKEN" \
    --data @- << EOF | jq .
      {
        "dryRun": false,
        "orgID": "INFLUX_ORG_ID",
        "secrets": {
          "SLACK_WEBHOOK": "YOUR_SECRET_WEBHOOK_URL"
        },
        "remotes": [
          {
            "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/fortnite/fn-template.yml"
          }
        ]
      }
EOF

The secret value is not exposed in the InfluxDB /api/v2/templates/apply API response.

For more detail about the API schema, see the /api/v2/templates/apply reference documentation.

Troubleshoot applying templates

If applying a template fails, check the InfluxDB response for your specific error. Below are common causes of template failures.

API error responses

HTTP response codeError messageDescription
HTTP 401 "Unauthorized"unauthorized accessThe API token may not have read or write access for resources in the template.
HTTP 422 "Unprocessable Entity"duplicate name: RESOURCE NAMEYou may have passed a parameter combination that InfluxDB doesn’t support–for example, template and templates in the same request.

Was this page helpful?

Thank you for your feedback!


Set your InfluxDB URL

Upgrade to InfluxDB Cloud or InfluxDB 2.0!

InfluxDB Cloud and InfluxDB OSS 2.0 ready for production.