Merge pull request #1299 from influxdata/stacks-example
Updated examples for stackspull/1544/head^2
kelseiv
GitHub
commit
00aadfceaa
|
|
@ -1,29 +1,31 @@
|
|||
---
|
||||
title: InfluxDB templates
|
||||
description: >
|
||||
InfluxDB templates are prepackaged InfluxDB configurations that contain everything
|
||||
InfluxDB templates are preconfigured InfluxDB resources and can contain everything
|
||||
from dashboards and Telegraf configurations to notifications and alerts.
|
||||
menu: influxdb_2_0
|
||||
weight: 9
|
||||
influxdb/v2.0/tags: [templates]
|
||||
---
|
||||
|
||||
InfluxDB templates are prepackaged InfluxDB configurations that contain everything
|
||||
InfluxDB templates are preconfigured InfluxDB resources and can 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.
|
||||
Use InfluxDB templates to quickly get set up monitoring a specific technology,
|
||||
set up a fresh instance of InfluxDB, back up your dashboard configuration, or
|
||||
share your configuration with the InfluxData community.
|
||||
|
||||
**InfluxDB templates do the following:**
|
||||
|
||||
- Reduce setup time
|
||||
- Facilitate secure, portable, source-controlled InfluxDB platform states.
|
||||
- Reduce setup time by giving you resources that are already configured for your use-case.
|
||||
- Facilitate secure, portable, and source-controlled InfluxDB resource states.
|
||||
- Simplify sharing and using pre-built InfluxDB solutions.
|
||||
|
||||
{{< youtube 2JjW4Rym9XE >}}
|
||||
|
||||
## Template manifests
|
||||
A template consists of a single file known as a **manifest** that defines the
|
||||
InfluxDB state and associated [resources](#template-resources).
|
||||
|
||||
A template consists of one or more files known as **manifests** that define the
|
||||
InfluxDB [resources](#template-resources).
|
||||
Template manifests support the following formats:
|
||||
|
||||
- [YAML](https://yaml.org/)
|
||||
|
|
@ -38,12 +40,13 @@ Template manifests are compatible with
|
|||
The `metadata.name` field in manifests uniquely identifies each resource in the template.
|
||||
`metadata.name` values must be [DNS-1123](https://tools.ietf.org/html/rfc1123) compliant.
|
||||
If resources in the template depend on other InfluxDB resources, all dependencies
|
||||
must be included in the template.
|
||||
should be included in the template, otherwise, the resources may not be usable.
|
||||
|
||||
_See [Create an InfluxDB template](/influxdb/v2.0/influxdb-templates/create/) for information about
|
||||
generating template manifests._
|
||||
|
||||
### Template resources
|
||||
|
||||
Include the following **resources** in a template:
|
||||
|
||||
- buckets
|
||||
|
|
@ -57,11 +60,12 @@ Include the following **resources** in a template:
|
|||
- Telegraf configurations
|
||||
|
||||
## Stacks
|
||||
**InfluxDB stacks** are stateful InfluxDB templates.
|
||||
When you apply a template, InfluxDB associates resources in the template with a stack.
|
||||
Use stacks to add, update, or remove templated resources over time.
|
||||
|
||||
For more information, see [InfluxDB Stacks](#influxdb-stacks) below.
|
||||
Use **InfluxDB stacks** to manage InfluxDB templates.
|
||||
When you apply a template, InfluxDB associates resources in the template with a stack.
|
||||
Use stacks to add, update, or remove InfluxDB templates over time.
|
||||
|
||||
For more information, see [InfluxDB stacks](#influxdb-stacks) below.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,51 +1,26 @@
|
|||
---
|
||||
title: InfluxDB stacks
|
||||
description: >
|
||||
InfluxDB stacks are stateful InfluxDB templates that let you add,
|
||||
update, and remove templated resources over time, avoid duplicating resources
|
||||
when applying the same or similar templates more than once, and apply
|
||||
changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.
|
||||
Use an InfluxDB stack to manage your InfluxDB templates—add, update, or remove templates over time.
|
||||
menu:
|
||||
influxdb_2_0:
|
||||
parent: InfluxDB templates
|
||||
weight: 105
|
||||
related:
|
||||
- /influxdb/v2.0/reference/cli/stacks/
|
||||
- /v2.0/reference/cli/influx/pkg/stack/
|
||||
---
|
||||
|
||||
**InfluxDB stacks** are **stateful [InfluxDB templates](/influxdb/v2.0/influxdb-templates)**
|
||||
that let you add, update, and remove templated resources over time, avoid
|
||||
duplicating resources when applying the same or similar templates more than once,
|
||||
and apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.
|
||||
Use InfluxDB stacks to manage [InfluxDB templates](/influxdb/v2.0/influxdb-templates).
|
||||
When you apply a template, InfluxDB associates resources in the template with a stack. Use the stack to add, update, or remove InfluxDB templates over time.
|
||||
|
||||
## Ideal use cases for InfluxDB stacks
|
||||
Stacks help save time and effort in the following use cases:
|
||||
{{< children type="anchored-list" >}}
|
||||
|
||||
- [Actively develop and extend templates](#actively-develop-and-extend-templates)
|
||||
- [Apply updates from source-controlled templates](#apply-updates-from-source-controlled-templates)
|
||||
- [Apply template updates across multiple InfluxDB instances](#apply-template-updates-across-multiple-influxdb-instances)
|
||||
{{< children readmore=true >}}
|
||||
|
||||
### Actively develop and extend templates
|
||||
InfluxDB stacks aid in developing and maintaining InfluxDB templates.
|
||||
Stacks let you modify and update template manifests and apply those changes in
|
||||
any stack that uses the template.
|
||||
{{% note %}}
|
||||
**Key differences between stacks and templates**:
|
||||
|
||||
### Apply updates from source-controlled templates
|
||||
You can use a variety of InfluxDB templates from many different sources including
|
||||
[Community Templates](https://github.com/influxdata/community-templates/) or
|
||||
self-built custom templates.
|
||||
As templates are updated over time, stacks allow template users to gracefully
|
||||
apply updates without creating duplicate resources.
|
||||
|
||||
### Apply template updates across multiple InfluxDB instances
|
||||
In many cases, users have more than one instance of InfluxDB running and apply
|
||||
the same template to each separate instance.
|
||||
By using stacks, you can make changes to a stack on one instance,
|
||||
[export the stack as a template](/influxdb/v2.0/influxdb-templates/create/#export-a-stack)
|
||||
and then apply the changes to your other InfluxDB instances.
|
||||
|
||||
## Manage InfluxDB Stacks
|
||||
|
||||
{{< children type="anchored-list" >}}
|
||||
|
||||
{{< children readmore=true >}}
|
||||
- A template defines a set of resources in a text file outside of InfluxDB. When you apply a template, a stack is automatically created to manage the applied template.
|
||||
- Stacks add, modify or delete resources in an instance.
|
||||
- Templates do not recognize resources in an instance. All resources in the template are added, creating duplicate resources if a resource already exists.
|
||||
{{% /note %}}
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ menu:
|
|||
influxdb_2_0:
|
||||
parent: InfluxDB stacks
|
||||
name: Initialize a stack
|
||||
weight: 201
|
||||
weight: 202
|
||||
related:
|
||||
- /influxdb/v2.0/reference/cli/influx/stacks/init/
|
||||
list_code_example: |
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
influxdb_2_0:
|
||||
parent: InfluxDB stacks
|
||||
name: Remove a stack
|
||||
weight: 204
|
||||
weight: 205
|
||||
related:
|
||||
- /influxdb/v2.0/reference/cli/influx/stacks/remove/
|
||||
list_code_example: |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,165 @@
|
|||
---
|
||||
title: Save time with InfluxDB stacks
|
||||
list_title: Save time with stacks
|
||||
description: >
|
||||
Discover how to use InfluxDB stacks to save time.
|
||||
menu:
|
||||
influxdb_2_0:
|
||||
parent: InfluxDB stacks
|
||||
name: Save time with stacks
|
||||
weight: 201
|
||||
related:
|
||||
- /influxdb/v2.0/reference/cli/influx/stacks/
|
||||
|
||||
---
|
||||
|
||||
Save time and money using InfluxDB stacks. Here's a few ideal use cases:
|
||||
|
||||
- [Automate deployments with GitOps and stacks](#automate-deployments-with-gitops-and-stacks)
|
||||
- [Apply updates from source-controlled templates](#apply-updates-from-source-controlled-templates)
|
||||
- [Apply template updates across multiple InfluxDB instances](#apply-template-updates-across-multiple-influxdb-instances)
|
||||
- [Develop templates](#develop-templates)
|
||||
|
||||
### Automate deployments with GitOps and stacks
|
||||
|
||||
GitOps is popular way to configure and automate deployments. Use InfluxDB stacks in a GitOps workflow
|
||||
to automatically update distributed instances of InfluxDB OSS or InfluxDB Cloud.
|
||||
|
||||
To automate an InfluxDB deployment with GitOps and stacks, complete the following steps:
|
||||
|
||||
1. [Set up a GitHub repository](#set-up-a-github-repository)
|
||||
2. [Add existing resources to the GitHub repository](#add-existing-resources-to-the-github-repository)
|
||||
3. [Automate the creation of a stack for each folder](#automate-the-creation-of-a-stack-for-each-folder)
|
||||
4. [Set up Github Actions or CircleCI](#set-up-github-actions-or-circleci)
|
||||
|
||||
#### Set up a GitHub repository
|
||||
|
||||
Set up a GitHub repository to back your InfluxDB instance. Determine how you want to organize the resources in your stacks within your Github repository. For example, organize resources under folders for specific teams or functions.
|
||||
|
||||
We recommend storing all resources for one stack in the same folder. For example, if you monitor Redis, create a `redis` stack and put your Redis monitoring resources (a Telegraf configuration, four dashboards, a label, and two alert checks) into one Redis folder, each resource in a separate file. Then, when you need to update a Redis resource, it's easy to find and make changes in one location.
|
||||
|
||||
{{% note %}}
|
||||
Typically, we **do not recommend** using the same resource in multiple stacks. If your organization uses the same resource in multiple stacks, before you delete a stack, verify the stack does not include resources that another stack depends on. Stacks with buckets often contain data used by many different templates. Because of this, we recommend keeping buckets separate from the other stacks.
|
||||
{{% /note %}}
|
||||
|
||||
#### Add existing resources to the GitHub repository
|
||||
|
||||
Skip this section if you are starting from scratch or don’t have existing resources you want to add to your stack.
|
||||
|
||||
Use the `influx export` command to quickly export resources. Keep all your resources in a single file or have files for each one. You can always split or combine them later.
|
||||
|
||||
For example, if you export resources for three stacks: `buckets`, `redis`, and `mysql`, your folder structure might look something like this when you are done:
|
||||
|
||||
```sh
|
||||
influxdb-assets/
|
||||
├── buckets/
|
||||
│ ├── telegraf_bucket.yml
|
||||
├── redis/
|
||||
│ ├── redis_overview_dashboard.yml
|
||||
│ ├── redis_label.yml
|
||||
│ ├── redis_cpu_check.yml
|
||||
│ └── redis_mem_check.yml
|
||||
├── mysql/
|
||||
│ ├── mysql_assets.yml
|
||||
└── README.md
|
||||
|
||||
```
|
||||
{{% note %}}
|
||||
When you export a resource, InfluxDB creates a `meta.name` for that resource. These resource names should be unique inside your InfluxDB instance. Use a good naming convention to prevent duplicate `meta.names`. Changing the `meta.name` of the InfluxDB resource will cause the stack to orphan the resource with the previous name and create a new resource with the updated name.
|
||||
{{% /note %}}
|
||||
|
||||
Add the exported resources to your new GitHub repository.
|
||||
|
||||
#### Automate the creation of a stack for each folder
|
||||
|
||||
To automatically create a stack from each folder in your GitHub repository, create a shell script to check for an existing stack and if the stack isn't found, use the `influx stacks init` command to create a new stack. The following sample script creates a `redis` stack and automatically applies those changes to your instance:
|
||||
|
||||
```sh
|
||||
echo "Checking for existing redis stack..."
|
||||
REDIS_STACK_ID=$(influx stacks --stack-name redis --json | jq -r '.[0].ID')
|
||||
if [ "$REDIS_STACK_ID" == "null" ]; then
|
||||
echo "No stack found. Initializing our stack..."
|
||||
REDIS_STACK_ID=$(influx stacks init -n redis --json | jq -r '.ID')
|
||||
fi
|
||||
|
||||
# Setting the base path
|
||||
BASE_PATH="$(pwd)"
|
||||
|
||||
echo "Applying our redis stack..."
|
||||
cat $BASE_PATH/redis/*.yml | \
|
||||
influx apply --force true --stack-id $REDIS_STACK_ID -q
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
The `--json` flag in the InfluxDB CLI is very useful when scripting against the CLI. This flag lets you grab important information easily using [`jq`](https://stedolan.github.io/jq/manual/v1.6/).
|
||||
{{% /note %}}
|
||||
|
||||
Repeat this step for each of the stacks in your repository. When a resource in your stack changes, re-run this script to apply updated resources to your InfluxDB instance. Re-applying a stack with an updated resource won't add, delete, or duplicate resources.
|
||||
|
||||
#### Set up Github Actions or CircleCI
|
||||
|
||||
Once you have a script to apply changes being made to your local instance, automate the deployment to other environments as needed. Use the InfluxDB CLI to maintain multiple [configuration profiles]() to easily switch profile and issue commands against other InfluxDB instances. To apply the same script to a different InfluxDB instance, change your active configuration profile using the `influx config set` command. Or set the desired profile dynamically using the `-c, --active-config` flag.
|
||||
|
||||
{{% note %}}
|
||||
Before you run automation scripts against shared environments, we recommend manually running the steps in your script.
|
||||
{{% /note %}}
|
||||
|
||||
Verify your deployment automation software lets you run a custom script, and then set up the custom script you've built locally another environment. For example, here's a custom Github Action that automates deployment:
|
||||
|
||||
```yml
|
||||
name: deploy-influxdb-resources
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ master ]
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
with:
|
||||
ref: ${{ github.ref }}
|
||||
- name: Deploys repo to cloud
|
||||
env:
|
||||
# These secrets can be configured in the Github repo to connect to
|
||||
# your InfluxDB instance.
|
||||
INFLUX_TOKEN: ${{ secrets.INFLUX_TOKEN }}
|
||||
INFLUX_ORG: ${{ secrets.INFLUX_ORG }}
|
||||
INFLUX_URL: ${{ secrets.INFLUX_URL }}
|
||||
GITHUB_REPO: ${{ github.repository }}
|
||||
GITHUB_BRANCH: ${{ github.ref }}
|
||||
run: |
|
||||
cd /tmp
|
||||
wget https://dl.influxdata.com/platform/nightlies/influx_nightly_linux_amd64.tar.gz
|
||||
tar xvfz influx_nightly_linux_amd64.tar.gz
|
||||
sudo cp influx_nightly_linux_amd64/influx /usr/local/bin/
|
||||
cd $GITHUB_WORKSPACE
|
||||
# This runs the script to set up your stacks
|
||||
chmod +x ./setup.sh
|
||||
./setup.sh prod
|
||||
```
|
||||
|
||||
For more information about using GitHub Actions in your project, check out the complete [Github Actions documentation](https://github.com/features/actions).
|
||||
|
||||
### Apply updates from source-controlled templates
|
||||
|
||||
You can use a variety of InfluxDB templates from many different sources including
|
||||
[Community Templates](https://github.com/influxdata/community-templates/) or
|
||||
self-built custom templates.
|
||||
As templates are updated over time, stacks let you gracefully
|
||||
apply updates without creating duplicate resources.
|
||||
|
||||
### Apply template updates across multiple InfluxDB instances
|
||||
|
||||
In many cases, you may have more than one instance of InfluxDB running and want to apply
|
||||
the same template to each separate instance.
|
||||
Using stacks, you can make changes to a stack on one instance,
|
||||
[export the stack as a template](/influxdb/v2.0/influxdb-templates/create/#export-a-stack)
|
||||
and then apply the changes to your other InfluxDB instances.
|
||||
|
||||
### Develop templates
|
||||
|
||||
InfluxDB stacks aid in developing and maintaining InfluxDB templates.
|
||||
Stacks let you modify and update template manifests and apply those changes in
|
||||
any stack that uses the template.
|
||||
|
|
@ -12,7 +12,7 @@ menu:
|
|||
influxdb_2_0:
|
||||
parent: InfluxDB stacks
|
||||
name: Update a stack
|
||||
weight: 202
|
||||
weight: 203
|
||||
related:
|
||||
- /influxdb/v2.0/reference/cli/influx/apply
|
||||
- /influxdb/v2.0/reference/cli/influx/stacks/update/
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
influxdb_2_0:
|
||||
parent: InfluxDB stacks
|
||||
name: View stacks
|
||||
weight: 203
|
||||
weight: 204
|
||||
related:
|
||||
- /influxdb/v2.0/reference/cli/influx/stacks/
|
||||
list_code_example: |
|
||||
|
|
@ -34,10 +34,12 @@ influx stacks -o example-org
|
|||
```
|
||||
|
||||
### Filter stacks
|
||||
|
||||
To output information about specific stacks, use the `--stack-name` or `--stack-id`
|
||||
flags to filter output by stack names or stack IDs.
|
||||
|
||||
##### Filter by stack name
|
||||
|
||||
```sh
|
||||
# Syntax
|
||||
influx stacks \
|
||||
|
|
@ -52,6 +54,7 @@ influx stacks \
|
|||
```
|
||||
|
||||
### Filter by stack ID
|
||||
|
||||
```sh
|
||||
# Syntax
|
||||
influx stacks \
|
||||
|
|
|
|||
|
|
@ -35,10 +35,23 @@ influx stacks init [flags]
|
|||
| `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` |
|
||||
|
||||
## Examples
|
||||
|
||||
### Initialize a stack with a name and description
|
||||
|
||||
```sh
|
||||
# Initialize a stack with a name and description
|
||||
# Use environment variables
|
||||
influx stack init -n $STACK_NAME -d $STACK_DESCRIPTION
|
||||
|
||||
# Initialize a stack with a name and urls to associate with stack.
|
||||
influx stack init -n $STACK_NAME -u $PATH_TO_TEMPLATE
|
||||
# Use strings
|
||||
influx stack init -n "Example Stack" -d "InfluxDB stack for monitoring some awesome stuff"
|
||||
```
|
||||
|
||||
### Initialize a stack with a name and URLs to associate with the stack
|
||||
|
||||
```sh
|
||||
# Use environment variables
|
||||
influx stack init -n $STACK_NAME -u $PATH_TO_TEMPLATE
|
||||
|
||||
# Use strings
|
||||
influx stack init -n "Example Stack" -u https://example.com/template-1.yml
|
||||
```
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 177 KiB |
Loading…
Reference in New Issue