Scott Anderson
GitHub
commit
b494fc7acd
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
title: InfluxDB templates
|
||||
description: >
|
||||
InfluxDB templates are prepackaged InfluxDB configurations that contain everything
|
||||
from dashboards and Telegraf configurations to notifications and alerts.
|
||||
menu: v2_0
|
||||
weight: 10
|
||||
v2.0/tags: [templates]
|
||||
---
|
||||
|
||||
InfluxDB templates are prepackaged InfluxDB configurations that contain everything
|
||||
from dashboards and Telegraf configurations to notifications and alerts.
|
||||
Use InfluxDB templates to quickly set up a fresh instance of InfluxDB, back up your
|
||||
dashboard configuration, or share your configuration with the InfluxData community.
|
||||
|
||||
## Template manifests
|
||||
A template is defined in a single file known as a **manifest**.
|
||||
Template manifests support the following formats:
|
||||
|
||||
- [YAML](https://yaml.org/)
|
||||
- [JSON](https://www.json.org/)
|
||||
- [Jsonnet](https://jsonnet.org/)
|
||||
|
||||
{{% note %}}
|
||||
Template manifests are compatible with
|
||||
[Kubernetes Custom Resource Definitions (CRD)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/).
|
||||
{{% /note %}}
|
||||
|
||||
_See [Create an InfluxDB template](/v2.0/influx-templates/create/) for information about
|
||||
generating template manifests._
|
||||
|
||||
### Template resources
|
||||
Include the following **resources** in a template:
|
||||
|
||||
- buckets
|
||||
- checks
|
||||
- dashboards
|
||||
- dashboard variables
|
||||
- labels
|
||||
- notification endpoints
|
||||
- notification rules
|
||||
- tasks
|
||||
- Telegraf configurations
|
||||
|
||||
---
|
||||
|
||||
{{< children >}}
|
||||
|
|
@ -0,0 +1,191 @@
|
|||
---
|
||||
title: Create an InfluxDB template
|
||||
description: >
|
||||
Use the InfluxDB UI and the `influx pkg export` command to create InfluxDB templates.
|
||||
menu:
|
||||
v2_0:
|
||||
parent: InfluxDB templates
|
||||
name: Create a template
|
||||
identifier: Create an InfluxDB template
|
||||
weight: 102
|
||||
v2.0/tags: [templates]
|
||||
---
|
||||
|
||||
Use the InfluxDB user interface (UI) and the `influx pkg export` command to
|
||||
create InfluxDB templates.
|
||||
Add resources (buckets, Telegraf configurations, tasks, and more) in the InfluxDB
|
||||
UI and export the resources as a template.
|
||||
|
||||
{{% note %}}
|
||||
Templatable resources are scoped to a single organization, so the simplest way to create a
|
||||
template is to create a new organization, build the template within the organization,
|
||||
and then [export all resources](#export-all-resources) as a template.
|
||||
|
||||
**InfluxDB OSS** supports multiple organizations so you can create new organizations
|
||||
for the sole purpose of building and maintaining a template.
|
||||
In **InfluxDB Cloud**, your user account is an organization.
|
||||
**We recommend using InfluxDB OSS to create InfluxDB templates.**
|
||||
{{% /note %}}
|
||||
|
||||
**To create a template:**
|
||||
|
||||
1. [Start InfluxDB](/v2.0/get-started/).
|
||||
2. [Create a new organization](/v2.0/organizations/create-org/).
|
||||
3. In the InfluxDB UI add one or more of the following templatable resources:
|
||||
|
||||
- [buckets](/v2.0/organizations/buckets/create-bucket/)
|
||||
- [checks](/v2.0/monitor-alert/checks/create/)
|
||||
- [dashboards](/v2.0/visualize-data/dashboards/create-dashboard/)
|
||||
- [dashboard variables](/v2.0/visualize-data/variables/create-variable/)
|
||||
- [labels](/v2.0/visualize-data/labels/)
|
||||
- [notification endpoints](/v2.0/monitor-alert/notification-endpoints/create/)
|
||||
- [notification rules](/v2.0/monitor-alert/notification-rules/create/)
|
||||
- [tasks](/v2.0/process-data/manage-tasks/create-task/)
|
||||
- [Telegraf configurations](/v2.0/write-data/use-telegraf/)
|
||||
|
||||
4. Export the template _(see [below](#export-a-template))_.
|
||||
|
||||
{{% warn %}}
|
||||
InfluxDB templates do not support the [table visualization type](/v2.0/visualize-data/visualization-types/table/).
|
||||
Dashboard cells that use table visualization are not included in exported templates.
|
||||
{{% /warn %}}
|
||||
|
||||
## Export a template
|
||||
Do one of the following to export a template:
|
||||
|
||||
1. Export all resources in an organization _(recommended)_
|
||||
2. Export specific resources in an organization
|
||||
|
||||
### Export all resources
|
||||
To export all templatable resources within an organization to a template manifest,
|
||||
use the `influx pkg export all` command.
|
||||
Provide the following:
|
||||
|
||||
- **Organization name** or **ID**
|
||||
- **Authentication token** with read access to the organization
|
||||
- **Destination path and filename** for the template manifest.
|
||||
The filename extension determines the template format—both **YAML** (`.yml`) and
|
||||
**JSON** (`.json`) are supported.
|
||||
|
||||
###### Export all resources to a template
|
||||
```sh
|
||||
# Syntax
|
||||
influx pkg export all -o <org-name> -f <file-path> -t <token>
|
||||
|
||||
# Example
|
||||
influx pkg export all \
|
||||
-o my-org \
|
||||
-f ~/templates/awesome-template.yml \
|
||||
-t $INFLUX_TOKEN
|
||||
```
|
||||
|
||||
For information about flags, see the
|
||||
[`influx pkg export all` documentation](/v2.0/reference/cli/influx/pkg/export/all/).
|
||||
|
||||
### Export specific resources
|
||||
To export specific resources within an organization to a template manifest,
|
||||
use the `influx pkg export` with resource flags for each resource to include.
|
||||
Provide the following:
|
||||
|
||||
- **Organization name** or **ID**
|
||||
- **Authentication token** with read access to the organization
|
||||
- **Destination path and filename** for the template manifest.
|
||||
The filename extension determines the template format—both **YAML** (`.yml`) and
|
||||
**JSON** (`.json`) are supported.
|
||||
- **Resource flags** with corresponding lists of resource IDs to include in the template.
|
||||
For information about what resource flags are available, see the
|
||||
[`influx pkg export` documentation](/v2.0/reference/cli/influx/pkg/export/).
|
||||
|
||||
###### Export specific resources to a template
|
||||
```sh
|
||||
# Syntax
|
||||
influx pkg export all -o <org-name> -f <file-path> -t <token> [resource-flags]
|
||||
|
||||
# Example
|
||||
influx pkg export all \
|
||||
-o my-org \
|
||||
-f ~/templates/awesome-template.yml \
|
||||
-t $INFLUX_TOKEN \
|
||||
--buckets=00x000ooo0xx0xx,o0xx0xx00x000oo \
|
||||
--dashboards=00000xX0x0X00x000 \
|
||||
--telegraf-configs=00000x0x000X0x0X0
|
||||
```
|
||||
|
||||
## 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](#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 reference 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.
|
||||
|
||||
{{< code-tabs-wrapper >}}
|
||||
{{% code-tabs %}}
|
||||
[YAML](#)
|
||||
[JSON](#)
|
||||
{{% /code-tabs %}}
|
||||
{{% code-tab-content %}}
|
||||
```yml
|
||||
apiVersion: influxdata.com/v2alpha1
|
||||
kind: Bucket
|
||||
metadata:
|
||||
name:
|
||||
envRef:
|
||||
key: bucket-name-1
|
||||
```
|
||||
{{% /code-tab-content %}}
|
||||
{{% code-tab-content %}}
|
||||
```json
|
||||
{
|
||||
"apiVersion": "influxdata.com/v2alpha1",
|
||||
"kind": "Bucket",
|
||||
"metadata": {
|
||||
"name": {
|
||||
"envRef": {
|
||||
"key": "bucket-name-1"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
{{% /code-tab-content %}}
|
||||
{{< /code-tabs-wrapper >}}
|
||||
|
||||
Using the example above, users are prompted to provide a value for `bucket-name-1`
|
||||
when [installing the template](/v2.0/influxdb-templates/use/#install-templates).
|
||||
Users can also include the `--env-ref` flag with the appropriate key-value pair
|
||||
when installing the template.
|
||||
|
||||
```sh
|
||||
# Set bucket-name-1 to "myBucket"
|
||||
influx pkg \
|
||||
-f /path/to/template.yml \
|
||||
--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._
|
||||
|
||||
{{% note %}}
|
||||
#### Resource fields that support environment references
|
||||
Only the following fields support environment references:
|
||||
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
## Share your InfluxDB templates
|
||||
Share your InfluxDB templates with the entire InfluxData community.
|
||||
**Contribute your template to the [InfluxDB Community Templates](https://github.com/influxdata/community-templates/)
|
||||
repository on GitHub.**
|
||||
|
||||
<a class="btn" href="https://github.com/influxdata/community-templates/" target="\_blank">View InfluxDB Community Templates</a>
|
||||
|
|
@ -0,0 +1,210 @@
|
|||
---
|
||||
title: Use InfluxDB templates
|
||||
description: >
|
||||
Use the `influx pkg` command to view and install templates from your local
|
||||
filesystem or from URLs.
|
||||
menu:
|
||||
v2_0:
|
||||
parent: InfluxDB templates
|
||||
name: Use templates
|
||||
weight: 101
|
||||
v2.0/tags: [templates]
|
||||
---
|
||||
|
||||
Use the `influx pkg` command to summarize, validate, and install templates from
|
||||
your local filesystem and from URLs.
|
||||
|
||||
- [View a template summary](#view-a-template-summary)
|
||||
- [Validate a template](#validate-a-template)
|
||||
- [Install templates](#install-templates)
|
||||
- [Use InfluxDB community templates](#use-influxdb-community-templates)
|
||||
|
||||
## View a template summary
|
||||
To view a summary of what's included in a template before installing the template,
|
||||
use the [`influx pkg summary` command](/v2.0/reference/cli/influx/pkg/summary/).
|
||||
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 pkg summary -f <template-file-path>
|
||||
|
||||
# Example
|
||||
influx pkg summary -f /path/to/template.yml
|
||||
```
|
||||
{{% /code-tab-content %}}
|
||||
{{% code-tab-content %}}
|
||||
```sh
|
||||
# Syntax
|
||||
influx pkg summary -u <template-url>
|
||||
|
||||
# Example
|
||||
influx pkg summary -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 your install it or troubleshoot a template, use
|
||||
the [`influx pkg validate` command](/v2.0/reference/cli/influx/pkg/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 pkg validate -f <template-file-path>
|
||||
|
||||
# Example
|
||||
influx pkg validate -f /path/to/template.yml
|
||||
```
|
||||
{{% /code-tab-content %}}
|
||||
{{% code-tab-content %}}
|
||||
```sh
|
||||
# Syntax
|
||||
influx pkg validate -u <template-url>
|
||||
|
||||
# Example
|
||||
influx pkg validate -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml
|
||||
```
|
||||
{{% /code-tab-content %}}
|
||||
{{% /code-tabs-wrapper %}}
|
||||
|
||||
## Install templates
|
||||
Use the [`influx pkg` command](/v2.0/reference/cli/influx/pkg/) to install templates
|
||||
from your local filesystem or from URLs.
|
||||
|
||||
- [Install a template from a file](#install-a-template-from-a-file)
|
||||
- [Install all templates in a directory](#install-all-templates-in-a-directory)
|
||||
- [Install a template from a URL](#install-a-template-from-a-url)
|
||||
- [Install templates from both files and URLs](#install-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)
|
||||
|
||||
### Install 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 pkg -f <template-file-path>
|
||||
|
||||
# Examples
|
||||
# Install a single template
|
||||
influx pkg -f /path/to/template.yml
|
||||
|
||||
# Install multiple templates
|
||||
influx pkg \
|
||||
-f /path/to/this/template.yml \
|
||||
-f /path/to/that/template.yml
|
||||
```
|
||||
|
||||
### Install all templates in a directory
|
||||
To install 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 installs templates stored in the specified directory.
|
||||
To install all templates stored in the specified directory and its subdirectories,
|
||||
include the `--recurse` flag.
|
||||
|
||||
```sh
|
||||
# Syntax
|
||||
influx pkg -f <template-directory-path>
|
||||
|
||||
# Examples
|
||||
# Install all templates in a directory
|
||||
influx pkg -f /path/to/template/dir/
|
||||
|
||||
# Install all templates in a directory and its subdirectories
|
||||
influx pkg -f /path/to/template/dir/ --recurse
|
||||
```
|
||||
|
||||
### Install a template from a URL
|
||||
To install templates from a URL, use the `-u` or `--url` flag to provide the URL
|
||||
of the template manifest.
|
||||
|
||||
```sh
|
||||
# Syntax
|
||||
influx pkg -u <template-url>
|
||||
|
||||
# Examples
|
||||
# Install a single template from a URL
|
||||
influx pkg -u https://mydomain.com/templates/template.yml
|
||||
|
||||
# Install multiple templates from URLs
|
||||
influx pkg \
|
||||
-u https://mydomain.com/templates/template1.yml \
|
||||
-u https://mydomain.com/templates/template2.yml
|
||||
```
|
||||
|
||||
### Install templates from both files and URLs
|
||||
To install 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 pkg -u <template-url> -f <template-path>
|
||||
|
||||
# Example
|
||||
influx pkg \
|
||||
-u https://mydomain.com/templates/template1.yml \
|
||||
-u https://mydomain.com/templates/template2.yml \
|
||||
-f ~/templates/custom-template.yml \
|
||||
-f ~/templates/iot/home/ \
|
||||
--recurse
|
||||
```
|
||||
|
||||
### Define environment references
|
||||
Some templates include [environment references](/v2.0/influxdb-templates/create/#include-user-definable-resource-names) that let you provide custom resource names.
|
||||
The `influx pkg` 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 pkg -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](/v2.0/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 pkg -f <template-file-path> --secret=<secret-key>=<secret-value>
|
||||
|
||||
# Examples
|
||||
# Define a single secret when installing a template
|
||||
influx pkg -f /path/to/template.yml \
|
||||
--secret=FOO=BAR
|
||||
|
||||
# Define multiple secrets when installing a template
|
||||
influx pkg -f /path/to/template.yml \
|
||||
--secret=FOO=bar \
|
||||
--secret=BAZ=quz
|
||||
```
|
||||
|
||||
_To add a secret after installing a template, see [Add secrets](/v2.0/security/secrets/manage-secrets/add/)._
|
||||
|
||||
## 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.
|
||||
Install community templates directly from GitHub using a template's download URL
|
||||
or download the template.
|
||||
|
||||
<a class="btn" href="https://github.com/influxdata/community-templates/" target="\_blank">View InfluxDB Community Templates</a>
|
||||
|
|
@ -6,7 +6,7 @@ menu:
|
|||
name: influx pkg
|
||||
parent: influx
|
||||
weight: 101
|
||||
v2.0/tags: [packages]
|
||||
v2.0/tags: [templates]
|
||||
---
|
||||
|
||||
The `influx pkg` command manages packages in InfluxDB.
|
||||
|
|
|
|||
Loading…
Reference in New Issue