From d90f6c00644e6ba8586441c82440388b8df1221e Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Mon, 8 Aug 2022 09:09:08 -0500 Subject: [PATCH] Update and fix use templates (#4302) * feat: document templates for CLI and API. * fix: template API examples. * feat(api): use templates API with environment references and secrets. * feat(api): revise templates guide for CLI and API. * feat(api): replace template examples and cleanup. * feat(api): templates fixup. * Update content/influxdb/v2.3/influxdb-templates/use.md * Update content/influxdb/v2.3/influxdb-templates/use.md * Update content/influxdb/v2.3/influxdb-templates/use.md * Update content/influxdb/v2.3/influxdb-templates/use.md * Update content/influxdb/v2.3/influxdb-templates/use.md Co-authored-by: Scott Anderson * Apply suggestions from code review Co-authored-by: Scott Anderson * Apply suggestions from code review Co-authored-by: Scott Anderson * Update content/influxdb/v2.3/influxdb-templates/use.md * feat(templates): Fixes TOC, intro, cloud page, headings. * feat(templates): TOC updates and troubleshooting. * feat(templates): More template revisions, dry run example fixes. * feat(templates): update Cloud frontmatter, expand on dry run example * fix(templates): cloud link. * fix(templates): typo. * Update content/influxdb/v2.3/influxdb-templates/use.md Co-authored-by: sunbryely-influxdata <101659702+sunbryely-influxdata@users.noreply.github.com> * Update content/influxdb/v2.3/influxdb-templates/use.md Co-authored-by: sunbryely-influxdata <101659702+sunbryely-influxdata@users.noreply.github.com> Co-authored-by: Scott Anderson Co-authored-by: sunbryely-influxdata <101659702+sunbryely-influxdata@users.noreply.github.com> --- .../influxdb/cloud/influxdb-templates/use.md | 230 +--- .../influxdb/v2.3/influxdb-templates/use.md | 1061 +++++++++++++++-- 2 files changed, 939 insertions(+), 352 deletions(-) diff --git a/content/influxdb/cloud/influxdb-templates/use.md b/content/influxdb/cloud/influxdb-templates/use.md index 327467de3..7c6822f96 100644 --- a/content/influxdb/cloud/influxdb-templates/use.md +++ b/content/influxdb/cloud/influxdb-templates/use.md @@ -1,8 +1,8 @@ --- title: Use InfluxDB templates description: > - Use the `influx` command line interface (CLI) to summarize, validate, and apply - templates from your local filesystem and from URLs. + Use the `influx` command line interface (CLI) and the InfluxDB `/api/v2/templates` API to summarize, validate, and apply + templates from file systems and URLs. menu: influxdb_cloud: parent: InfluxDB templates @@ -13,229 +13,7 @@ related: - /influxdb/cloud/reference/cli/influx/apply/ - /influxdb/cloud/reference/cli/influx/template/ - /influxdb/cloud/reference/cli/influx/template/validate/ + - /influxdb/cloud/api/ --- -Use the `influx` command line interface (CLI) to summarize, validate, and apply -templates from your local filesystem and from URLs. - -- [Use InfluxDB community templates](#use-influxdb-community-templates) -- [View a template summary](#view-a-template-summary) -- [Validate a template](#validate-a-template) -- [Apply templates](#apply-templates) - - -## Use InfluxDB community templates -The [InfluxDB community templates repository](https://github.com/influxdata/community-templates/) -is home to a growing number of InfluxDB templates developed and maintained by -others in the InfluxData community. -Apply community templates directly from GitHub using a template's download URL -or download the template. - -{{< youtube 2JjW4Rym9XE >}} - -{{% note %}} -When attempting to access the community templates via the URL, the templates use the following -as the root of the URL: - -```sh -https://raw.githubusercontent.com/influxdata/community-templates/master/ -``` - -For example, the Docker community template can be accessed via: - -```sh -https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml -``` -{{% /note %}} - -View InfluxDB Community Templates - -## View a template summary -To view a summary of what's included in a template before applying the template, -use the [`influx template` command](/influxdb/cloud/reference/cli/influx/template/). -View a summary of a template stored in your local filesystem or from a URL. - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[From a file](#) -[From a URL](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sh -# Syntax -influx template -f - -# Example -influx template -f /path/to/template.yml -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sh -# Syntax -influx template -u - -# Example -influx template -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -## Validate a template -To validate a template before you install it or troubleshoot a template, use -the [`influx template validate` command](/influxdb/cloud/reference/cli/influx/template/validate/). -Validate a template stored in your local filesystem or from a URL. - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[From a file](#) -[From a URL](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sh -# Syntax -influx template validate -f - -# Example -influx template validate -f /path/to/template.yml -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sh -# Syntax -influx template validate -u - -# Example -influx template validate -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -## Apply templates -Use the [`influx apply` command](/influxdb/cloud/reference/cli/influx/apply/) to install templates -from your local filesystem or from URLs. - -- [Apply a template from a file](#apply-a-template-from-a-file) -- [Apply all templates in a directory](#apply-all-templates-in-a-directory) -- [Apply a template from a URL](#apply-a-template-from-a-url) -- [Apply templates from both files and URLs](#apply-templates-from-both-files-and-urls) -- [Define environment references](#define-environment-references) -- [Include a secret when installing a template](#include-a-secret-when-installing-a-template) - -{{% note %}} -#### Apply templates to an existing stack -To apply a template to an existing stack, include the stack ID when applying the template. -Any time you apply a template without a stack ID, InfluxDB initializes a new stack -and all new resources. -For more information, see [InfluxDB stacks](/influxdb/cloud/influxdb-templates/stacks/). -{{% /note %}} - -### Apply a template from a file -To install templates stored on your local machine, use the `-f` or `--file` flag -to provide the **file path** of the template manifest. - -```sh -# Syntax -influx apply -o -f - -# Examples -# Apply a single template -influx apply -o example-org -f /path/to/template.yml - -# Apply multiple templates -influx apply -o example-org \ - -f /path/to/this/template.yml \ - -f /path/to/that/template.yml -``` - -### Apply all templates in a directory -To apply all templates in a directory, use the `-f` or `--file` flag to provide -the **directory path** of the directory 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, -include the `-R`, `--recurse` flag. - -```sh -# Syntax -influx apply -o -f - -# Examples -# Apply all templates in a directory -influx apply -o example-org -f /path/to/template/dir/ - -# Apply all templates in a directory and its subdirectories -influx apply -o example-org -f /path/to/template/dir/ -R -``` - -### Apply a template from a URL -To apply templates from a URL, use the `-u` or `--template-url` flag to provide the URL -of the template manifest. - -```sh -# Syntax -influx apply -o -u - -# Examples -# Apply a single template from a URL -influx apply -o example-org -u https://example.com/templates/template.yml - -# Apply multiple templates from URLs -influx apply -o example-org \ - -u https://example.com/templates/template1.yml \ - -u https://example.com/templates/template2.yml -``` - -### Apply templates from both files and URLs -To apply templates from both files and URLs in a single command, include multiple -file or directory paths and URLs, each with the appropriate `-f` or `-u` flag. - -```sh -# Syntax -influx apply -o -u -f - -# Example -influx apply -o example-org \ - -u https://example.com/templates/template1.yml \ - -u https://example.com/templates/template2.yml \ - -f ~/templates/custom-template.yml \ - -f ~/templates/iot/home/ \ - --recurse -``` - -### Define environment references -Some templates include [environment references](/influxdb/cloud/influxdb-templates/create/#include-user-definable-resource-names) that let you provide custom resource names. -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 including an `--env-ref` -flag with a key-value pair comprised of the environment reference key and the -value to replace it. - -```sh -influx apply -o example-org -f /path/to/template.yml \ - --env-ref=bucket-name-1=myBucket - --env-ref=label-name-1=Label1 \ - --env-ref=label-name-2=Label2 -``` - -### Include a secret when installing a template -Some templates use [secrets](/influxdb/cloud/security/secrets/) in queries. -Secret values are not included in templates. -To define secret values when installing a template, include the `--secret` flag -with the secret key-value pair. - -```sh -# Syntax -influx apply -o -f \ - --secret== - -# Examples -# Define a single secret when applying a template -influx apply -o example-org -f /path/to/template.yml \ - --secret=FOO=BAR - -# Define multiple secrets when applying a template -influx apply -o example-org -f /path/to/template.yml \ - --secret=FOO=bar \ - --secret=BAZ=quz -``` - -_To add a secret after applying a template, see [Add secrets](/influxdb/cloud/security/secrets/manage-secrets/add/)._ +{{< duplicate-oss >}} diff --git a/content/influxdb/v2.3/influxdb-templates/use.md b/content/influxdb/v2.3/influxdb-templates/use.md index 1e86adc44..d5ad93243 100644 --- a/content/influxdb/v2.3/influxdb-templates/use.md +++ b/content/influxdb/v2.3/influxdb-templates/use.md @@ -1,8 +1,8 @@ --- title: Use InfluxDB templates description: > - Use the `influx` command line interface (CLI) to summarize, validate, and apply - templates from your local filesystem and from URLs. + Use the `influx` command line interface (CLI) and the InfluxDB `/api/v2/templates` API to summarize, validate, and apply + templates from file systems and URLs. menu: influxdb_2_3: parent: InfluxDB templates @@ -13,229 +13,1038 @@ related: - /influxdb/v2.3/reference/cli/influx/apply/ - /influxdb/v2.3/reference/cli/influx/template/ - /influxdb/v2.3/reference/cli/influx/template/validate/ + - /influxdb/v2.3/api/ --- -Use the `influx` command line interface (CLI) to summarize, validate, and apply -templates from your local filesystem and from URLs. +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. -- [Use InfluxDB community templates](#use-influxdb-community-templates) +- [Get prebuilt templates](#get-prebuilt-templates) - [View a template summary](#view-a-template-summary) - [Validate a template](#validate-a-template) -- [Apply templates](#apply-templates) +- [Use a template dry run to preview changes](#use-a-template-dry-run-to-preview-changes) +- [Apply templates to an InfluxDB instance](#apply-templates-to-an-influxdb-instance) +- [Troubleshoot applying templates](#troubleshoot-applying-templates) +## Get prebuilt templates -## Use InfluxDB community templates The [InfluxDB community templates repository](https://github.com/influxdata/community-templates/) is home to a growing number of InfluxDB templates developed and maintained by others in the InfluxData community. -Apply community templates directly from GitHub using a template's download URL -or download the template. +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. {{< youtube 2JjW4Rym9XE >}} {{% note %}} -When attempting to access the community templates via the URL, the templates use the following -as the root of the URL: + +The [`master` branch](https://raw.githubusercontent.com/influxdata/community-templates/master/) of +the [InfluxDB community templates repository](https://github.com/influxdata/community-templates/) +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: ```sh https://raw.githubusercontent.com/influxdata/community-templates/master/ ``` -For example, the Docker community template can be accessed via: +For example, the most current version of the Docker community template can be accessed via: ```sh https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml ``` + {{% /note %}} View InfluxDB Community Templates ## View a template summary -To view a summary of what's included in a template before applying the template, + +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. + +{{% warn %}} +You can't generate a template summary with the InfluxDB `/api/v2` API. +{{% /warn %}} + +### View a template summary with the CLI + +To view a template summary, use the [`influx template` command](/influxdb/v2.3/reference/cli/influx/template/). -View a summary of a template stored in your local filesystem or from a URL. -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[From a file](#) -[From a URL](#) -{{% /code-tabs %}} -{{% code-tab-content %}} ```sh # Syntax -influx template -f +influx template --file TEMPLATE_FILE_PATH +influx template -f TEMPLATE_FILE_PATH -# Example -influx template -f /path/to/template.yml +influx template --template-url TEMPLATE_FILE_URL +influx template -u TEMPLATE_FILE_URL ``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sh -# Syntax -influx template -u -# Example -influx template -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} +`--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: + + ```sh + influx template --file /Users/me/template.yml + ``` + +- Summarize a template located at a remote URL: + + ```sh + 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 -To validate a template before you install it or troubleshoot a template, use -the [`influx template validate` command](/influxdb/v2.3/reference/cli/influx/template/validate/). -Validate a template stored in your local filesystem or from a URL. -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[From a file](#) -[From a URL](#) -{{% /code-tabs %}} -{{% code-tab-content %}} +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](/influxdb/v2.3/reference/cli/influx/template/validate/) to validate a template from your local file system or a URL. + ```sh # Syntax -influx template validate -f +influx template validate --file TEMPLATE_FILE_PATH +influx template validate -f TEMPLATE_FILE_PATH -# Example -influx template validate -f /path/to/template.yml +influx template validate --template-url TEMPLATE_FILE_URL +influx template validate -u TEMPLATE_FILE_URL ``` -{{% /code-tab-content %}} -{{% code-tab-content %}} + +The following code sample shows how to validate a template located on the local file system: + ```sh -# Syntax -influx template validate -u - -# Example -influx template validate -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml +influx template validate --file /path/to/template.yml ``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} -## Apply templates -Use the [`influx apply` command](/influxdb/v2.3/reference/cli/influx/apply/) to install templates -from your local filesystem or from URLs. +The following code sample shows how to validate the `linux_system` community template located on GitHub: -- [Apply a template from a file](#apply-a-template-from-a-file) -- [Apply all templates in a directory](#apply-all-templates-in-a-directory) -- [Apply a template from a URL](#apply-a-template-from-a-url) -- [Apply templates from both files and URLs](#apply-templates-from-both-files-and-urls) -- [Define environment references](#define-environment-references) -- [Include a secret when installing a template](#include-a-secret-when-installing-a-template) +```sh +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](#use-a-template-dry-run-to-preview-changes). + +### 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). + +## 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. + +[{{< api-endpoint method="POST" endpoint="/api/v2/templates/apply" >}}](/influxdb/v2.3/api/#operation/ApplyTemplate) {{% note %}} -#### Apply templates to an existing stack -To apply a template to an existing stack, include the stack ID when applying the template. -Any time you apply a template without a stack ID, InfluxDB initializes a new stack -and all new resources. -For more information, see [InfluxDB stacks](/influxdb/v2.3/influxdb-templates/stacks/). +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](/influxdb/v2.3/security/tokens/) for more information. {{% /note %}} -### Apply a template from a file -To install templates stored on your local machine, use the `-f` or `--file` flag -to provide the **file path** of the template manifest. +Consider a template that contains an unsupported value--for example, the following template +contains an invalid InfluxDB resource type (`"kind": "Foo"`): + +{{% code-callout "Foo" %}} + +```json +{ + "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" + } + } + ] +} +``` + +{{% /code-callout %}} + +The following code sample shows how to pass `dryRun: true` and the template to +the `/api/v2/templates/apply` endpoint: + +```sh + 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: + +{{% truncate %}} +{{% code-callout "unsupported kind provided" %}} + +```json +{ + "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" +} +``` + +{{% /code-callout %}} + +{{% /truncate %}} + +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: + +{{% truncate %}} + +```json +{ + "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": [] + } +} +``` + +{{% /truncate %}} + +- 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](/influxdb/v2.3/influxdb-templates/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 + +{{% note %}} +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](/influxdb/v2.3/security/tokens/) for more information. +{{% /note %}} + +Use the `influx` CLI or `/api/v2` API to apply templates to an InfluxDB instance. + +- [Apply templates with the CLI](#apply-templates-with-the-cli) + - [Apply a template from the file system](#apply-a-template-from-the-file-system) + - [Apply all templates in a directory](#apply-all-templates-in-a-directory) + - [Apply a template from a URL](#apply-a-template-from-a-url) + - [Apply multiple templates from files and URLs](#apply-multiple-templates-from-files-and-urls) +- [Apply templates with the API](#apply-templates-with-the-api) + - [Apply templates from template objects](#apply-templates-from-template-objects) + - [Apply templates from URLs with the API](#apply-templates-from-urls-with-the-api) + - [Apply templates from URLs and template objects](#apply-templates-from-urls-and-template-objects) +- [Define environment references](#define-environment-references) +- [Pass secrets when installing a template](#pass-secrets-when-installing-a-template) + +### Apply templates with the CLI + +Use the [`influx apply` command](/influxdb/v2.3/reference/cli/influx/apply/) 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: + +```sh +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: + +{{% truncate %}} + +```sh +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 +``` + +{{% /truncate %}} + +#### 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. ```sh # Syntax -influx apply -o -f - -# Examples -# Apply a single template -influx apply -o example-org -f /path/to/template.yml - -# Apply multiple templates -influx apply -o example-org \ - -f /path/to/this/template.yml \ - -f /path/to/that/template.yml +influx apply --file TEMPLATE_FILE_PATH +influx apply -f TEMPLATE_FILE_PATH ``` -### Apply all templates in a directory -To apply all templates in a directory, use the `-f` or `--file` flag to provide -the **directory path** of the directory where template manifests are stored. +The following code sample shows how to apply a template from a file path. + +```sh +influx apply --file /Users/me/template.yml +``` + +To use one command to apply multiple templates, pass `--file` for each template file path--for example: + +```sh +# 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, -include the `-R`, `--recurse` flag. +pass the `--recurse` flag. ```sh # Syntax -influx apply -o -f +influx apply --org INFLUX_ORG --file DIRECTORY_PATH [--recurse] +``` -# Examples +The following code sample shows how to apply all templates from a directory: + +```sh # Apply all templates in a directory -influx apply -o example-org -f /path/to/template/dir/ +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: + +```sh # Apply all templates in a directory and its subdirectories -influx apply -o example-org -f /path/to/template/dir/ -R +influx apply --org INFLUX_ORG --file /Users/me --recurse ``` -### Apply a template from a URL -To apply templates from a URL, use the `-u` or `--template-url` flag to provide the URL -of the template manifest. +#### 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. ```sh # Syntax -influx apply -o -u +influx apply --org INFLUX_ORG --template-url TEMPLATE_FILE_URL +``` -# Examples +The following code sample shows how to apply a community template located on GitHub: + +```sh # Apply a single template from a URL -influx apply -o example-org -u https://example.com/templates/template.yml - -# Apply multiple templates from URLs -influx apply -o example-org \ - -u https://example.com/templates/template1.yml \ - -u https://example.com/templates/template2.yml +influx apply --org my-org --template-url https://raw.githubusercontent.com/influxdata/community-templates/master/kafka/kafka-template.yml ``` -### Apply templates from both files and URLs -To apply templates from both files and URLs in a single command, include multiple -file or directory paths and URLs, each with the appropriate `-f` or `-u` flag. +To use one command to apply multiple templates from URLs, pass `--template-url` +for each template file--for example: + +```sh +# 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. ```sh # Syntax -influx apply -o -u -f +influx apply --org my-org --template-url TEMPLATE_FILE_URL --file TEMPLATE_FILE_PATH +``` -# Example -influx apply -o example-org \ - -u https://example.com/templates/template1.yml \ - -u https://example.com/templates/template2.yml \ - -f ~/templates/custom-template.yml \ - -f ~/templates/iot/home/ \ +The following code sample shows a single command to apply multiple templates from URLs and file paths: + +```sh +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 ``` -### Define environment references -Some templates include [environment references](/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names) that let you provide custom resource names. -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 including an `--env-ref` -flag with a key-value pair comprised of the environment reference key and the -value to replace it. +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. + +[{{< api-endpoint method="POST" endpoint="/api/v2/templates/apply" >}}](/influxdb/v2.3/api/#operation/ApplyTemplate) + +With the API, you can apply templates from remote URLs or template objects in your request. + +- [Apply templates from template objects](#apply-templates-from-template-objects) +- [Apply templates from URLs with the API](#apply-templates-from-urls-with-the-api) +- [Apply templates from URLs and template objects](#apply-templates-from-urls-and-template-objects) + +#### 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](/influxdb/v2.3/api/#operation/ApplyTemplate). + +The following code sample shows how to define a template and apply it +with the `/api/v2/templates/apply` API endpoint: + +{{% truncate %}} ```sh -influx apply -o example-org -f /path/to/template.yml \ +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 +``` + +{{% /truncate %}} + +To apply multiple templates in a single request, pass the _`templates`_ parameter with +an array of template objects in the request body--for example: + +{{% truncate %}} + +```sh +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 +``` + +{{% /truncate %}} + +The _`template`_ and _`templates`_ parameters are mutually exclusive; if you pass both parameters in your request, InfluxDB responds with an error--for example: + +```json +{ +... + "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](#use-influxdb-community-templates) located on GitHub: + +```sh +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: + +{{% truncate %}} + +```sh +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 +``` + +{{% /truncate %}} +### Define environment references + +Some templates include [environment references](/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names) that let you provide custom names for resources and specs. + +- [Define environment references with the CLI](#define-environment-references-with-the-cli) +- [Define environment references with the API](#define-environment-references-with-the-api) + +#### 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: + +```sh +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 ``` -### Include a secret when installing a template -Some templates use [secrets](/influxdb/v2.3/security/secrets/) in queries. -Secret values are not included in templates. -To define secret values when installing a template, include the `--secret` flag +#### 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`): + +{{% truncate %}} + +```sh + 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 +``` + +{{% /truncate %}} + +For more API schema detail, see the [`/api/v2/templates/apply` reference documentation](/influxdb/v2.3/api/#operation/ApplyTemplate). + +### Pass secrets when installing a template + +Some queries use [secrets](/influxdb/v2.3/security/secrets/)--for example, to access +external APIs for sending data or messages. + +The following example Flux (from the [**fortnite** community template](https://github.com/influxdata/community-templates/blob/adb5c7cad12e195baa587ae123bdac7ec8cc0f3f/fortnite/fn-template.yml)) +requires a`SLACK_WEBHOOK` secret for sending a Slack message: + +{{% truncate %}} +{{% code-callout "SLACK_WEBHOOK" %}} + +```js + 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})) +``` + +{{% /code-callout %}} +{{% caption %}} +[community-templates/fortnite/fn-template.yml on GitHub](https://github.com/influxdata/community-templates/blob/adb5c7cad12e195baa587ae123bdac7ec8cc0f3f/fortnite/fn-template.yml#L23) +{{% /caption %}} + +{{% /truncate %}} + +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](#pass-secrets-with-the-cli) +- [Pass secrets with the API](#pass-secrets-with-the-api) + +#### 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. ```sh # Syntax -influx apply -o -f \ - --secret== +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 -o example-org -f /path/to/template.yml \ +influx apply --org my-org --file /path/to/template.yml \ --secret=FOO=BAR # Define multiple secrets when applying a template -influx apply -o example-org -f /path/to/template.yml \ +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](/influxdb/v2.3/security/secrets/manage-secrets/add/)._ + +#### 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](https://github.com/influxdata/community-templates/blob/adb5c7cad12e195baa587ae123bdac7ec8cc0f3f/fortnite/fn-template.yml): + +{{% code-callout "SLACK_WEBHOOK" %}} + +```sh + 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 +``` + +{{% /code-callout %}} + +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](/influxdb/v2.3/api/#operation/ApplyTemplate). + +## 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 + +{{% oss-only %}} + +| HTTP response code | Error message | Description | +| :----------------------------- | :----------------------------------------- | :----------- | +| `HTTP 401 "Unauthorized"` | unauthorized access | The API token may not have `read` or `write` access for resources in the template. +| `HTTP 422 "Unprocessable Entity"` | duplicate name: `RESOURCE NAME` | You may have passed a parameter combination that InfluxDB doesn't support--for example, `template` and `templates` in the same request. + +{{% /oss-only %}} + +{{% cloud-only %}} + +| HTTP response code | Error message | Description | +| :----------------------------- | :----------------------------------------- | :----------- | +| `HTTP 401 "Unauthorized"` | unauthorized access | The API token may not have `read` or `write` access for resources in the template. +| `HTTP 422 "Unprocessable Entity"` | duplicate name: `RESOURCE NAME` | You may have passed a parameter combination that InfluxDB doesn't support--for example, `template` and `templates` in the same request. +| `HTTP 500 "Internal Server Error"` | failed to create `RESOURCE NAME`: creating `RESOURCE` would exceed quota | Creating the requested resource (bucket, dashboard, task, user) would exceed your plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas). | + +{{% /cloud-only %}}