Rework Grafana Agent static mode docs to align with flow mode (#4355)

* Update headers, reorganize and edit topics * Clean up Docker and update Linux steps * Create new stub topics, move content, fix errors * Fix broken xref link * Update layout and fix linking * Update K8s deploy steps * Updates to better align static and flow topics * Update macOS and K8s steps * Update and align Windows topics * Fix aliases for install topics * Updates from review * Remove extra space
grafana · Jul 7, 2023 · d58ffa5 · d58ffa5
1 parent 87d1e95
commit d58ffa5
Show file tree

Hide file tree

Showing 27 changed files with 712 additions and 379 deletions.
diff --git a/docs/sources/flow/getting-started/_index.md b/docs/sources/flow/getting-started/_index.md
@@ -1,12 +1,13 @@
 ---
-title: Getting started
+title: Get started with Grafana Agent in flow mode
+menuTitle: Get started
 weight: 200
 aliases:
 - getting_started/
 ---
 
-# Getting started
+# Get started with Grafana Agent in flow mode
 
-This section details guides for getting started with Grafana Agent Flow.
+This section details guides for getting started with Grafana Agent in flow mode.
 
 {{< section >}}
diff --git a/docs/sources/flow/setup/configure/_index.md b/docs/sources/flow/setup/configure/_index.md
@@ -5,7 +5,7 @@ menuTitle: Configure flow mode
 weight: 150
 ---
 
-# Configure Grafana Agent
+# Configure Grafana Agent in flow mode
 
 You can configure Grafana Agent in flow mode after it is installed. The default River configuration file for flow mode is located at:
 

diff --git a/docs/sources/flow/setup/configure/configure-kubernetes.md b/docs/sources/flow/setup/configure/configure-kubernetes.md
@@ -5,7 +5,7 @@ menuTitle: Kubernetes
 weight: 200
 ---
 
-# Configure Grafana Agent on Kubernetes
+# Configure Grafana Agent in flow mode on Kubernetes
 
 To configure Grafana Agent in flow mode on Kubernetes, perform the following steps:
 

diff --git a/docs/sources/flow/setup/configure/configure-linux.md b/docs/sources/flow/setup/configure/configure-linux.md
@@ -50,7 +50,7 @@ the following steps:
 
 1. Change the contents of the `CUSTOM_ARGS` environment variable to specify
    command-line flags to pass.
-   
+
 1. Restart the Grafana Agent service:
 
    ```shell

diff --git a/docs/sources/flow/setup/configure/configure-macos.md b/docs/sources/flow/setup/configure/configure-macos.md
@@ -5,7 +5,7 @@ menuTitle: macOS
 weight: 400
 ---
 
-# Configure Grafana Agent on macOS
+# Configure Grafana Agent in flow mode on macOS
 
 To configure Grafana Agent in flow mode on macOS, perform the following steps:
 

diff --git a/docs/sources/flow/setup/configure/configure-windows.md b/docs/sources/flow/setup/configure/configure-windows.md
@@ -5,7 +5,7 @@ menuTitle: Windows
 weight: 500
 ---
 
-# Configure Grafana Agent on Windows
+# Configure Grafana Agent in flow mode on Windows
 
 To configure Grafana Agent in flow mode on Windows, perform the following steps:
 

diff --git a/docs/sources/flow/setup/install/_index.md b/docs/sources/flow/setup/install/_index.md
@@ -10,6 +10,13 @@ aliases:
 
 You can install Grafana Agent in flow mode on Docker, Kubernetes, Linux, macOS, or Windows.
 
+The following architectures are supported:
+
+- Linux: AMD64, ARM64, ARMv6, ARMv7
+- Windows: AMD64
+- macOS: AMD64 (Intel), ARM64 (Apple Silicon)
+- FreeBSD: AMD64
+
 {{% admonition type="note" %}}
 Installing Grafana Agent on other operating systems is possible, but is not recommended or supported.
 {{% /admonition %}}

diff --git a/docs/sources/flow/setup/install/binary.md b/docs/sources/flow/setup/install/binary.md
@@ -7,9 +7,9 @@ aliases:
  - ../../install/binary/
 ---
 
-# Install Grafana Agent in flow mode
+# Install Grafana Agent in flow mode as a standalone binary
 
-Grafana Agent is distributed as a standalone binarie for various operating systems and architectures:
+Grafana Agent is distributed as a standalone binary for the following operating systems and architectures:
 
 * Linux: AMD64, ARM64, ARMv6, ARMv7
 * Windows: AMD64
@@ -20,7 +20,7 @@ Grafana Agent is distributed as a standalone binarie for various operating syste
 
 To download the Grafana Agent as a standalone binary, perform the following steps.
 
-1. Navigate to the current Grafana Agent [release][] page.
+1. Navigate to the current Grafana Agent [release](https://github.com/grafana/agent/releases) page.
 
 1. Scroll down to the **Assets** section.
 
@@ -38,5 +38,5 @@ To download the Grafana Agent as a standalone binary, perform the following step
 
 ## Next steps
 
-- [Start Grafana Agent]({{< relref "../start-agent#standalone-binary" >}})
-- [Configure Grafana Agent]({{< relref "../configure/" >}})
+* [Start Grafana Agent]({{< relref "../start-agent#standalone-binary" >}})
+* [Configure Grafana Agent]({{< relref "../configure/" >}})
diff --git a/docs/sources/flow/setup/install/docker.md b/docs/sources/flow/setup/install/docker.md
@@ -1,18 +1,18 @@
 ---
 description: Learn how to install Grafana Agent in flow mode on Docker
-title: Install Grafana Agent in flow mode on Docker
+title: Run Grafana Agent in flow mode in a Docker container
 menuTitle: Docker
 weight: 100
 aliases:
  - ../../install/docker/
 ---
 
-# Install Grafana Agent in flow mode on Docker
+# Run Grafana Agent in flow mode in a Docker container
 
-Grafana Agent is available as Docker images on the following platforms:
+Grafana Agent is available as a Docker container image on the following platforms:
 
-* [Linux containers][] for AMD64 and ARM64 machines.
-* [Windows containers][] for AMD64 machines.
+* [Linux containers][] for AMD64 and ARM64.
+* [Windows containers][] for AMD64.
 
 [Linux containers]: #run-a-linux-docker-container
 [Windows containers]: #run-a-windows-docker-container
@@ -33,71 +33,56 @@ Grafana Agent is available as Docker images on the following platforms:
 
 ## Run a Linux Docker container
 
-To run Grafana Agent in flow mode as a Linux Docker container, perform the following steps:
+To run Grafana Agent in flow mode as a Linux Docker container, run the following command in a terminal window:
 
-1. Run the following command in a terminal window:
+```shell
+docker run \
+  -e AGENT_MODE=flow \
+  -v CONFIG_FILE_PATH:/etc/agent/config.river \
+  -p 12345:12345 \
+  grafana/agent:latest \
+    run --server.http.listen-addr=0.0.0.0:12345 /etc/agent/config.river
+```
 
-   ```shell
-   docker run \
-     -e AGENT_MODE=flow \
-     -v CONFIG_FILE_PATH:/etc/agent/config.river \
-     -p 12345:12345 \
-     grafana/agent:latest \
-       run --server.http.listen-addr=0.0.0.0:12345 /etc/agent/config.river
-   ```
+Replace `CONFIG_FILE_PATH` with the path of the configuration file on your host system.
 
-   Replace `CONFIG_FILE_PATH` with the path of the configuration file on
-   your host system.
-
-The last line may be modified to change the arguments passed to the Grafana
-Agent binary. To see the set of options available to the `run` command,
-refer to the documentation for [run][].
+You can modify the last line to change the arguments passed to the Grafana Agent binary.
+Refer to the documentation for [run][] for more information about the options available to the `run` command.
 
 {{% admonition type="note" %}}
-Make sure you pass `--server.http.listen-addr=0.0.0.0:12345` as an
-argument as shown in the example above. If you don't pass this argument, the [debugging UI][] won't be
-available outside of the Docker container.
+Make sure you pass `--server.http.listen-addr=0.0.0.0:12345` as an argument as shown in the example above.
+If you don't pass this argument, the [debugging UI](../../monitoring/debugging.md#grafana-agent-flow-ui) won't be available outside of the Docker container.
 {{% /admonition %}}
 
-[debugging UI]: {{< relref "../../monitoring/debugging.md#grafana-agent-flow-ui" >}}
 [run]: {{< relref "../../reference/cli/run.md" >}}
 
 ## Run a Windows Docker container
 
-To run Grafana Agent in flow mode as a Windows Docker container, perform the following
-steps:
-
-1. Run the following command in a terminal window:
+To run Grafana Agent in flow mode as a Windows Docker container, run the following command in a terminal window:
 
-   ```shell
-   docker run \
-     -e AGENT_MODE=flow \
-     -v CONFIG_FILE_PATH:C:\etc\grafana-agent\config.river \
-     -p 12345:12345 \
-     grafana/agent:latest-windows \
-       run --server.http.listen-addr=0.0.0.0:12345 C:\etc\grafana-agent\config.river
-   ```
+```shell
+docker run \
+  -e AGENT_MODE=flow \
+  -v CONFIG_FILE_PATH:C:\etc\grafana-agent\config.river \
+  -p 12345:12345 \
+  grafana/agent:latest-windows \
+    run --server.http.listen-addr=0.0.0.0:12345 C:\etc\grafana-agent\config.river
+```
 
-   Replace `CONFIG_FILE_PATH` with the path of the configuration file on
-   your host system.
+Replace `CONFIG_FILE_PATH` with the path of the configuration file on your host system.
 
-The last line may be modified to change the arguments passed to the Grafana
-Agent binary. To see the set of options available to the `run` command,
-refer to the documentation for [run][].
+You can modify the last line to change the arguments passed to the Grafana Agent binary.
+Refer to the documentation for [run][] for more information about the options available to the `run` command.
 
 {{% admonition type="note" %}}
-Make sure you pass `--server.http.listen-addr=0.0.0.0:12345` as an
-argument as shown in the example above. If you don't pass this argument, the [debugging UI][] won't be
-available outside of the Docker container.
+Make sure you pass `--server.http.listen-addr=0.0.0.0:12345` as an argument as shown in the example above.
+If you don't pass this argument, the [debugging UI](../../monitoring/debugging.md#grafana-agent-flow-ui) won't be available outside of the Docker container.
 {{% /admonition %}}
 
-[debugging UI]: {{< relref "../../monitoring/debugging.md#grafana-agent-flow-ui" >}}
 [run]: {{< relref "../../reference/cli/run.md" >}}
 
 ## Verify
 
-To verify that Grafana Agent is running successfully, navigate to
-<http://localhost:12345> and make sure the Grafana Agent [UI][] loads
-without error.
+To verify that Grafana Agent is running successfully, navigate to <http://localhost:12345> and make sure the Grafana Agent [UI][] loads without error.
 
 [UI]: {{< relref "../../monitoring/debugging.md#grafana-agent-flow-ui" >}}
diff --git a/docs/sources/flow/setup/install/kubernetes.md b/docs/sources/flow/setup/install/kubernetes.md
@@ -1,15 +1,15 @@
 ---
-description: Learn how to install Grafana Agent in flow mode on Kubernetes
-title: Install Grafana Agent in flow mode on Kubernetes
+description: Learn how to deploy Grafana Agent in flow mode on Kubernetes
+title: Deploy Grafana Agent in flow mode on Kubernetes
 menuTitle: Kubernetes
 weight: 200
 aliases:
  - ../../install/kubernetes/
 ---
 
-# Install Grafana Agent in flow mode on Kubernetes
+# Deploy Grafana Agent in flow mode on Kubernetes
 
-Grafana Agent can be installed on Kubernetes by using the Helm chart for Grafana Agent.
+Grafana Agent can be deployed on Kubernetes by using the Helm chart for Grafana Agent.
 
 ## Before you begin
 
@@ -19,14 +19,14 @@ Grafana Agent can be installed on Kubernetes by using the Helm chart for Grafana
 
 [Helm]: https://helm.sh
 
-## Install
+## Deploy
 
 {{% admonition type="note" %}}
 These instructions show you how to install the generic [Helm chart](https://github.com/grafana/agent/tree/main/operations/helm/charts/grafana-agent) for Grafana
 Agent. You can deploy Grafana Agent either in static mode or flow mode. The Helm chart deploys Grafana Agent in flow mode by default.
 {{% /admonition %}}
 
-To install Grafana Agent on Kubernetes using Helm, run the following commands in a terminal window:
+To deploy Grafana Agent on Kubernetes using Helm, run the following commands in a terminal window:
 
 1. Add the Grafana Helm chart repository:
 
@@ -40,7 +40,7 @@ To install Grafana Agent on Kubernetes using Helm, run the following commands in
    helm repo update
    ```
 
-1. Install the Grafana Agent Helm chart:
+1. Install Grafana Agent:
 
    ```shell
    helm install RELEASE_NAME grafana/grafana-agent

diff --git a/docs/sources/flow/setup/install/macos.md b/docs/sources/flow/setup/install/macos.md
@@ -9,10 +9,10 @@ aliases:
 
 # Install Grafana Agent in flow mode on macOS
 
-You can install Grafana Agent in flow mode with Homebrew on macOS.
+You can install Grafana Agent in flow mode on macOS with Homebrew .
 
 {{% admonition type="note" %}}
-The default prefix for Homebrew on Intel is `/usr/local`. The default prefix for Homebrew on Apple Silicon is `/opt/Homebrew`. You can verify the default prefix for Homebrew on your computer by opening a terminal and typing `brew --prefix`.
+The default prefix for Homebrew on Intel is `/usr/local`. The default prefix for Homebrew on Apple Silicon is `/opt/Homebrew`. To verify the default prefix for Homebrew on your computer, open a terminal window and type `brew --prefix`.
 {{% /admonition %}}
 
 ## Before you begin
@@ -37,9 +37,25 @@ To install Grafana Agent on macOS, run the following commands in a terminal wind
    brew install grafana-agent-flow
    ```
 
+## Upgrade
+
+To upgrade Grafana Agent on macOS, run the following commands in a terminal window.
+
+1. Upgrade Grafana Agent:
+
+   ```shell
+   brew upgrade grafana-agent
+   ```
+
+1. Restart Grafana Agent:
+
+   ```shell
+   brew services restart grafana-agent
+   ```
+
 ## Uninstall
 
-To install Grafana Agent on macOS, run the following command in a terminal window:
+To uninstall Grafana Agent on macOS, run the following command in a terminal window:
 
 ```shell
 brew uninstall grafana-agent-flow

diff --git a/docs/sources/flow/setup/install/windows.md b/docs/sources/flow/setup/install/windows.md
@@ -9,29 +9,31 @@ aliases:
 
 # Install Grafana Agent in flow mode on Windows
 
-You can install Grafana Agent in flow mode on Windows with the standard graphical installer, or as a silent install.
+You can install Grafana Agent in flow mode on Windows as a standard graphical install, or as a silent install.
 
-## Graphical install
+## Standard graphical install
 
 To do a standard graphical install of Grafana Agent on Windows, perform the following steps.
 
-1. Navigate to the [latest release][latest].
+1. Navigate to the [latest release][latest] on GitHub.
 
 1. Scroll down to the **Assets** section.
 
 1. Download the file called `grafana-agent-flow-installer.exe.zip`.
 
 1. Unzip the downloaded file.
 
-1. Double-click on the unzipped installer to run it.
+1. Double-click on `grafana-agent-installer.exe` to install Grafana Agent.
+
+Grafana Agent is installed into the default directory `C:\Program Files\Grafana Agent Flow`.
 
 [latest]: https://github.com/grafana/agent/releases/latest
 
 ## Silent install
 
 To do a silent install of Grafana Agent on Windows, perform the following steps.
 
-1. Navigate to the [latest release][latest].
+1. Navigate to the [latest release][latest] on GitHub.
 
 1. Scroll down to the **Assets** section.
 
@@ -45,9 +47,7 @@ To do a silent install of Grafana Agent on Windows, perform the following steps.
    PATH_TO_INSTALLER /S
    ```
 
-   Replace `PATH_TO_INSTALLER` with the path where the unzipped installer
-   executable is located, for example
-   `C:\Users\Alexis\Downloads\grafana-agent-flow-installer.exe`.
+   Replace `PATH_TO_INSTALLER` with the path where the unzipped installer executable is located.
 
 [latest]: https://github.com/grafana/agent/releases/latest