Merge pull request #1046 from influxdata/pkg/stacks

InfluxDB stacks

content/v2.0/influxdb-templates/_index.md

@@ -13,8 +13,15 @@ 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.
 
+**InfluxDB templates do the following:**
+
+- Reduce setup time
+- Facilitate secure, portable, source-controlled InfluxDB platform states.
+- Simplify sharing and using pre-built InfluxDB solutions.
+
 ## Template manifests
-A template is defined in a single file known as a **manifest**.
+A template consists of a single file known as a **manifest** that defines the
+InfluxDB state and associated [resources](#template-resources).
 Template manifests support the following formats:
 
 - [YAML](https://yaml.org/)
@@ -26,6 +33,11 @@ Template manifests are compatible with
 [Kubernetes Custom Resource Definitions (CRD)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/).
 {{% /note %}}
 
+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.
+
 _See [Create an InfluxDB template](/v2.0/influxdb-templates/create/) for information about
 generating template manifests._
 
@@ -42,6 +54,13 @@ Include the following **resources** in a template:
 - tasks
 - 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.
+
 ---
 
 {{< children >}}

content/v2.0/influxdb-templates/create.md

@@ -56,8 +56,9 @@ Dashboard cells that use table visualization are not included in exported templa
 ## Export a template
 Do one of the following to export a template:
 
-1. Export all resources in an organization _(recommended)_
+- [Export all resources in an organization](#export-all-resources)
-2. Export specific resources in an organization
+- [Export specific resources in an organization](#export-specific-resources)
+- [Export a stack and its associated resources](#export-a-stack)
 
 ### Export all resources
 To export all templatable resources within an organization to a template manifest,
@@ -139,6 +140,35 @@ influx export all \
   --telegraf-configs=00000x0x000X0x0X0
 ```
 
+### Export a stack
+To export a stack and all its associated resources as a template, use the
+`influx export stack` 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.
+- **Stack ID**
+
+###### Export a stack as a template
+```sh
+# Syntax
+influx export stack \
+  -o <org-name> \
+  -t <token> \
+  -f <file-path> \
+  <stack-id>
+
+# Example
+influx export stack \
+  -o my-org \
+  -t mYSuP3RS3CreTt0K3n
+  -f ~/templates/awesome-template.yml \
+  05dbb791a4324000
+```
+
 ## Include user-definable resource names
 After exporting a template manifest, replace resource names with **environment references**
 to let users customize resource names when installing your template.

content/v2.0/influxdb-templates/stacks/_index.md

@@ -0,0 +1,51 @@
+---
+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.
+menu:
+  v2_0:
+    parent: InfluxDB templates
+weight: 105
+related:
+  - /v2.0/reference/cli/influx/pkg/stack/
+---
+
+**InfluxDB stacks** are **stateful [InfluxDB templates](/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.
+
+## Ideal use cases for InfluxDB stacks
+Stacks help save time and effort in the following use cases:
+
+- [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)
+
+### 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.
+
+### 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](/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 >}}

content/v2.0/influxdb-templates/stacks/init.md

@@ -0,0 +1,73 @@
+---
+title: Initialize an InfluxDB stack
+list_title: Initialize a stack
+description: >
+  InfluxDB automatically creates a new stack each time you [apply an InfluxDB template](/v2.0/influxdb-templates/use/)
+  **without providing a stack ID**.
+  To manually create or initialize a new stack, use the [`influx stacks init` command](/v2.0/reference/cli/influx/stacks/init/).
+menu:
+  v2_0:
+    parent: InfluxDB stacks
+    name: Initialize a stack
+weight: 201
+related:
+  - /v2.0/reference/cli/influx/stacks/init/
+list_code_example: |
+  ```sh
+  influx apply \
+    -o example-org \
+    -f path/to/template.yml
+  ```
+  ```sh
+  influx stacks init \
+    -o example-org \
+    -n "Example Stack" \
+    -d "InfluxDB stack for monitoring some awesome stuff" \
+    -u https://example.com/template-1.yml \
+    -u https://example.com/template-2.yml
+  ```
+---
+
+InfluxDB automatically creates a new stack each time you [apply an InfluxDB template](/v2.0/influxdb-templates/use/)
+**without providing a stack ID**.
+To manually create or initialize a new stack, use the [`influx stacks init` command](/v2.0/reference/cli/influx/stacks/init/).
+
+## Initialize a stack when applying a template
+To automatically create a new stack when [applying an InfluxDB template](/v2.0/influxdb-templates/use/)
+**don't provide a stack ID**.
+InfluxDB applies the resources in the template to a new stack and provides the **stack ID** the output.
+
+```sh
+influx apply \
+  -o example-org \
+  -f path/to/template.yml
+```
+
+## Manually initialize a new stack
+Use the [`influx stacks init` command](/v2.0/reference/cli/influx/stacks/init/)
+to create or initialize a new InfluxDB stack.
+
+**Provide the following:**
+
+- Organization name or ID
+- Stack name
+- Stack description
+- InfluxDB template URLs
+
+<!-- -->
+```sh
+# Syntax
+influx stacks init \
+  -o <org-name> \
+  -n <stack-name> \
+  -d <stack-description \
+  -u <package-url>
+
+# Example
+influx stacks init \
+  -o example-org \
+  -n "Example Stack" \
+  -d "InfluxDB stack for monitoring some awesome stuff" \
+  -u https://example.com/template-1.yml \
+  -u https://example.com/template-2.yml
+```

content/v2.0/influxdb-templates/stacks/remove.md

@@ -0,0 +1,39 @@
+---
+title: Remove an InfluxDB stack
+list_title: Remove a stack
+description: >
+  Use the [`influx stacks remove` command](/v2.0/reference/cli/influx/stacks/remove/)
+  to remove an InfluxDB stack and all its associated resources.
+menu:
+  v2_0:
+    parent: InfluxDB stacks
+    name: Remove a stack
+weight: 204
+related:
+  - /v2.0/reference/cli/influx/stacks/remove/
+list_code_example: |
+  ```sh
+  influx stacks remove \
+    -o example-org \
+    --stack-id=12ab34cd56ef
+  ```
+---
+
+Use the [`influx stacks remove` command](/v2.0/reference/cli/influx/stacks/remove/)
+to remove an InfluxDB stack and all its associated resources.
+
+**Provide the following:**
+
+- Organization name or ID
+- Stack ID
+
+<!-- -->
+```sh
+# Syntax
+influx stacks remove -o <org-name> --stack-id=<stack-id>
+
+# Example
+influx stacks remove \
+  -o example-org \
+  --stack-id=12ab34cd56ef
+```

content/v2.0/influxdb-templates/stacks/update.md

@@ -0,0 +1,56 @@
+---
+title: Update an InfluxDB stack
+list_title: Update a stack
+description: >
+  Use the [`influx apply` command](/v2.0/reference/cli/influx/apply/)
+  to update a stack with a modified template.
+  When applying a template to an existing stack, InfluxDB checks to see if the
+  resources in the template match existing resources.
+  InfluxDB updates, adds, and removes resources to resolve differences between
+  the current state of the stack and the newly applied template.
+menu:
+  v2_0:
+    parent: InfluxDB stacks
+    name: Update a stack
+weight: 202
+related:
+  - /v2.0/reference/cli/influx/apply
+  - /v2.0/reference/cli/influx/stacks/update/
+list_code_example: |
+  ```sh
+  influx applyapply \
+    -o example-org \
+    -u http://example.com/template-1.yml \
+    -u http://example.com/template-2.yml \
+    --stack-id=12ab34cd56ef
+  ```
+---
+
+Use the [`influx apply` command](/v2.0/reference/cli/influx/apply/)
+to update a stack with a modified template.
+When applying a template to an existing stack, InfluxDB checks to see if the
+resources in the template match existing resources.
+InfluxDB updates, adds, and removes resources to resolve differences between
+the current state of the stack and the newly applied template.
+
+Each stack is uniquely identified by a **stack ID**.
+For information about retrieving your stack ID, see [View stacks](/v2.0/influxdb-templates/stacks/view/).
+
+**Provide the following:**
+
+- Organization name or ID
+- Stack ID
+- InfluxDB template URLs to apply
+
+<!-- -->
+```sh
+influx apply \
+  -o example-org \
+  -u http://example.com/template-1.yml \
+  -u http://example.com/template-2.yml \
+  --stack-id=12ab34cd56ef
+```
+
+Template resources are uniquely identified by their `metadata.name` field.
+If errors occur when applying changes to a stack, all applied changes are
+reversed and the stack is returned to its previous state.

content/v2.0/influxdb-templates/stacks/view.md

@@ -0,0 +1,66 @@
+---
+title: View InfluxDB stacks
+list_title: View stacks
+description: >
+  Use the [`influx stacks` command](/v2.0/reference/cli/influx/stacks/)
+  to view installed InfluxDB stacks and their associated resources.
+menu:
+  v2_0:
+    parent: InfluxDB stacks
+    name: View stacks
+weight: 203
+related:
+  - /v2.0/reference/cli/influx/stacks/
+list_code_example: |
+  ```sh
+  influx stacks -o example-org
+  ```
+---
+
+Use the [`influx stacks` command](/v2.0/reference/cli/influx/stacks/)
+to view installed InfluxDB stacks and their associated resources.
+
+**Provide the following:**
+
+- Organization name or ID
+
+<!-- -->
+```sh
+# Syntax
+influx stacks -o <org-name>
+
+# Example
+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 \
+  -o <org-name> \
+  --stack-name=<stack-name>
+
+# Example
+influx stacks \
+  -o example-org \
+  --stack-name=stack1 \
+  --stack-name=stack2
+```
+
+### Filter by stack ID
+```sh
+# Syntax
+influx stacks \
+  -o <org-name> \
+  --stack-id=<stack-id>
+
+# Example
+influx stacks \
+  -o example-org \
+  --stack-id=12ab34cd56ef \
+  --stack-id=78gh910i11jk
+```

content/v2.0/influxdb-templates/use.md

@@ -119,6 +119,14 @@ from your local filesystem or from 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](/v2.0/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.

content/v2.0/reference/config-options.md

@@ -6,7 +6,7 @@ description: >
 menu:
   v2_0_ref:
     name: Configuration options
-    weight: 3
+weight: 3
 products: [oss]
 ---
 

content/v2.0/reference/flux/stdlib/testing/assertempty.md

@@ -7,7 +7,7 @@ menu:
   v2_0_ref:
     name: testing.assertEmpty
     parent: Testing
-    weight: 301
+weight: 301
 ---
 
 The `testing.assertEmpty()` function tests if an input stream is empty.

content/v2.0/reference/flux/stdlib/testing/diff.md

@@ -7,7 +7,7 @@ menu:
   v2_0_ref:
     name: testing.diff
     parent: Testing
-    weight: 301
+weight: 301
 ---
 
 The `testing.diff()` function produces a diff between two streams.

content/v2.0/reference/internals/_index.md

@@ -3,7 +3,7 @@ title: InfluxDB Internals
 menu:
   v2_0_ref:
     name: InfluxDB Internals
-    weight: 8
+weight: 8
 ---
 
 {{< children >}}

content/v2.0/reference/release-notes/_index.md

@@ -4,7 +4,7 @@ description: Find important information about what's included in new versions of
 menu:
   v2_0_ref:
     name: Release notes
-    weight: 1
+weight: 1
 ---
 
 Find important information about what's included in new versions of our products: