From 8db6922f72963b2df88b2062ee45b24739690141 Mon Sep 17 00:00:00 2001 From: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> Date: Tue, 27 Jun 2023 13:00:48 -0700 Subject: [PATCH] Reorganize the Agent Flow Install topics into single task topics (#4232) (#4272) * First draft of the install config start reorg * Update macOS and Windows topics * Move topics to match Grafana docs arch * Fix relrefs in docer topic * Second pass at relrefs in docker topic * More relref corrections * Fix more relrefs * Clean up metadata and add missing info * Update Windows uninstall * Fix markdown in note * Clean up spacing between steps * Add missing space between steps * Fix alias redirects * Expand navigation titles for clarity * Small tweaks to the nav * Shorten nav titles * Update headings for consistency * Update missed nav title (cherry picked from commit b71f2285efc69c774bda43a5cc75a447e992921d) --- docs/sources/flow/_index.md | 2 +- docs/sources/flow/install/_index.md | 10 - docs/sources/flow/install/linux.md | 284 ------------------ docs/sources/flow/install/macos.md | 138 --------- docs/sources/flow/install/windows.md | 162 ---------- docs/sources/flow/monitoring/debugging.md | 2 +- docs/sources/flow/setup/_index.md | 12 + docs/sources/flow/setup/configure/_index.md | 18 ++ .../flow/setup/configure/configure-linux.md | 89 ++++++ .../flow/setup/configure/configure-macos.md | 80 +++++ .../flow/setup/configure/configure-windows.md | 87 ++++++ docs/sources/flow/setup/install/_index.md | 17 ++ .../flow/{ => setup}/install/binary.md | 8 +- .../flow/{ => setup}/install/docker.md | 16 +- .../flow/{ => setup}/install/kubernetes.md | 6 +- docs/sources/flow/setup/install/linux.md | 163 ++++++++++ docs/sources/flow/setup/install/macos.md | 45 +++ docs/sources/flow/setup/install/windows.md | 54 ++++ docs/sources/flow/setup/start-agent.md | 123 ++++++++ 19 files changed, 711 insertions(+), 605 deletions(-) delete mode 100644 docs/sources/flow/install/_index.md delete mode 100644 docs/sources/flow/install/linux.md delete mode 100644 docs/sources/flow/install/macos.md delete mode 100644 docs/sources/flow/install/windows.md create mode 100644 docs/sources/flow/setup/_index.md create mode 100644 docs/sources/flow/setup/configure/_index.md create mode 100644 docs/sources/flow/setup/configure/configure-linux.md create mode 100644 docs/sources/flow/setup/configure/configure-macos.md create mode 100644 docs/sources/flow/setup/configure/configure-windows.md create mode 100644 docs/sources/flow/setup/install/_index.md rename docs/sources/flow/{ => setup}/install/binary.md (87%) rename docs/sources/flow/{ => setup}/install/docker.md (84%) rename docs/sources/flow/{ => setup}/install/kubernetes.md (94%) create mode 100644 docs/sources/flow/setup/install/linux.md create mode 100644 docs/sources/flow/setup/install/macos.md create mode 100644 docs/sources/flow/setup/install/windows.md create mode 100644 docs/sources/flow/setup/start-agent.md diff --git a/docs/sources/flow/_index.md b/docs/sources/flow/_index.md index 699b733afb47..c40c7f7b33f4 100644 --- a/docs/sources/flow/_index.md +++ b/docs/sources/flow/_index.md @@ -67,7 +67,7 @@ prometheus.remote_write "default" { * Check out our [Reference][] documentation to find specific information you might be looking for. -[Install]: {{< relref "./install/" >}} +[Install]: {{< relref "./setup/install/" >}} [Concepts]: {{< relref "./concepts/" >}} [Getting started]: {{< relref "./getting-started/" >}} [Tutorials]: {{< relref "./tutorials/ ">}} diff --git a/docs/sources/flow/install/_index.md b/docs/sources/flow/install/_index.md deleted file mode 100644 index a19a6a21e819..000000000000 --- a/docs/sources/flow/install/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Install -weight: 50 ---- - -# Install Grafana Agent Flow - -Distributions of Grafana Agent Flow are available for: - -{{< section >}} diff --git a/docs/sources/flow/install/linux.md b/docs/sources/flow/install/linux.md deleted file mode 100644 index 4eb8aa3db9aa..000000000000 --- a/docs/sources/flow/install/linux.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -title: Linux systems -weight: 300 ---- - -# Install Grafana Agent Flow on Linux systems - -You can install Grafana Agent Flow as a systemd service on Linux. - -## Install on Debian or Ubuntu - -To install Grafana Agent Flow on Debian or Ubuntu, run the following commands in a terminal window. - -1. Import the GPG key and add the Grafana package repository: - - ```shell - sudo mkdir -p /etc/apt/keyrings/ - wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null - echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list - ``` - -1. Update the repositories: - - ```shell - sudo apt-get update - ``` - -1. Install Grafana Agent Flow: - - ```shell - sudo apt-get install grafana-agent-flow - ``` - -### Uninstall on Debian or Ubuntu - -To uninstall Grafana Agent Flow on Debian or Ubuntu, run the following commands in a terminal window. - -1. Stop the systemd service for Grafana Agent Flow: - - ```shell - sudo systemctl stop grafana-agent-flow - ``` - -1. Uninstall Grafana Agent Flow: - - ```shell - sudo apt remove grafana-agent-flow - ``` - -1. (Optional) Remove the Grafana repository: - - ```shell - sudo rm -i /etc/apt/sources.list.d/grafana.list - ``` - -## Install on RHEL or Fedora - -To install Grafana Agent Flow on RHEL or Fedora, run the following commands in a terminal window. - -1. Import the GPG key: - - ```shell - wget -q -O gpg.key https://rpm.grafana.com/gpg.key - sudo rpm --import gpg.key - ``` - -1. Create `/etc/yum.repos.d/grafana.repo` with the following content: - - ```shell - [grafana] - name=grafana - baseurl=https://rpm.grafana.com - repo_gpgcheck=1 - enabled=1 - gpgcheck=1 - gpgkey=https://rpm.grafana.com/gpg.key - sslverify=1 - sslcacert=/etc/pki/tls/certs/ca-bundle.crt - ``` - -1. (Optional) Verify the Grafana repository configuration: - - ```shell - cat /etc/yum.repos.d/grafana.repo - ``` - -1. Install Grafana Agent Flow: - - ```shell - sudo dnf install grafana-agent-flow - ``` - -### Uninstall on RHEL or Fedora - -To uninstall Grafana Agent Flow on RHEL or Fedora, run the following commands in a terminal window: - -1. Stop the systemd service for Grafana Agent Flow: - - ```shell - sudo systemctl stop grafana-agent-flow - ``` - -1. Uninstall Grafana Agent Flow: - - ```shell - sudo dnf remove grafana-agent-flow - ``` - -1. (Optional) Remove the Grafana repository: - - ```shell - sudo rm -i /etc/yum.repos.d/rpm.grafana.repo - ``` - -## Install on SUSE or openSUSE - -To install Grafana Agent Flow on SUSE or openSUSE, run the following commands in a terminal window. - -1. Import the GPG key and add the Grafana package repository: - - ```shell - wget -q -O gpg.key https://rpm.grafana.com/gpg.key - sudo rpm --import gpg.key - sudo zypper addrepo https://rpm.grafana.com grafana - ``` - -1. Update the repositories: - - ```shell - sudo zypper update - ``` - -1. Install Grafana Agent Flow: - - ```shell - sudo zypper install grafana-agent-flow - ``` - -### Uninstall on SUSE or openSUSE - -To uninstall Grafana Agent Flow on SUSE or openSUSE, run the following commands in a terminal: - -1. Stop the systemd service for Grafana Agent Flow: - - ```shell - sudo systemctl stop grafana-agent-flow - ``` - -1. Uninstall Grafana Agent Flow: - - ```shell - sudo zypper remove grafana-agent-flow - ``` - -1. (Optional) Remove the Grafana repository: - - ```shell - sudo zypper removerepo grafana - ``` - -## Operation guide - -After installing Grafana Agent Flow on Linux, it will be exposed as a -[systemd][] service. - -[systemd]: https://systemd.io/ - -### Run Grafana Agent Flow - -To run Grafana Agent Flow, run the following command in a terminal: - -```shell -sudo systemctl start grafana-agent-flow -``` - -To check the status of Grafana Agent Flow, run the following command in a -terminal: - -```shell -sudo systemctl status grafana-agent-flow -``` - -### Run Grafana Agent Flow on startup - -To automatically run Grafana Agent Flow when the system starts, run the -following command in a terminal: - -```shell -sudo systemctl enable grafana-agent-flow.service -``` - -### Configuring Grafana Agent Flow - -To configure Grafana Agent Flow when installed on Linux, perform the following -steps: - -1. Edit the default configuration file at `/etc/grafana-agent-flow.river`. - -2. Run the following command in a terminal to reload the configuration file: - - ```shell - sudo systemctl reload grafana-agent-flow - ``` - -To change the configuration file used by the service, perform the following steps: - -1. Edit the environment file for the service: - - * Debian-based systems: edit `/etc/default/grafana-agent-flow` - * RedHat-based systems: edit `/etc/sysconfig/grafana-agent-flow` - -2. Change the contents of the `CONFIG_FILE` environment variable to point to - the new configuration file to use. - -3. Restart the Grafana Agent Flow service: - - ```shell - sudo systemctl restart grafana-agent-flow - ``` - -### Passing additional command-line flags - -By default, the Grafana Agent Flow service will launch with the [run][] -command, passing the following flags: - -* `--storage.path=/var/lib/grafana-agent-flow` - -To pass additional command-line flags to the Grafana Agent Flow binary, perform -the following steps: - -1. Edit the environment file for the service: - - * Debian-based systems: edit `/etc/default/grafana-agent-flow` - * RedHat-based systems: edit `/etc/sysconfig/grafana-agent-flow` - -2. Change the contents of the `CUSTOM_ARGS` environment variable to specify - command-line flags to pass. - -3. Restart the Grafana Agent Flow service: - - ```shell - sudo systemctl restart grafana-agent-flow - ``` - -To see the list of valid command-line flags that can be passed to the service, -refer to the documentation for the [run][] command. - -[run]: {{< relref "../reference/cli/run.md" >}} - -### Exposing the UI to other machines - -By default, Grafana Agent Flow listens on the local network for its HTTP -server. This prevents other machines on the network from being able to access -the [UI for debugging][UI]. - -To expose the UI to other machines, complete the following steps: - -1. Follow [Passing additional command-line flags](#passing-additional-command-line-flags) - to edit command line flags passed to Grafana Agent Flow, including the - following customizations: - - 1. Add the following command line argument to `CUSTOM_ARGS`: - - ``` - --server.http.listen-addr=LISTEN_ADDR:12345 - ``` - - Replace `LISTEN_ADDR` with an address which other machines on the - network have access to, like the network IP address of the machine - Grafana Agent Flow is running on. - - To listen on all interfaces, replace `LISTEN_ADDR` with `0.0.0.0`. - -[UI]: {{< relref "../monitoring/debugging.md#grafana-agent-flow-ui" >}} - -### Viewing Grafana Agent Flow logs - -Logs of Grafana Agent Flow can be found by running the following command in a -terminal: - -```shell -sudo journalctl -u grafana-agent-flow -``` - diff --git a/docs/sources/flow/install/macos.md b/docs/sources/flow/install/macos.md deleted file mode 100644 index 9ad601d137c7..000000000000 --- a/docs/sources/flow/install/macos.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: macOS -weight: 500 ---- - -# Install Grafana Agent Flow on macOS - -Grafana Agent Flow can be installed on Intel and Apple Silicon macOS machines. - -## Before you begin - -* Ensure that [Homebrew][] is installed on your machine. - -[Homebrew]: https://brew.sh - -## Install - -To install Grafana Agent Flow on macOS, perform the following steps: - -1. Add the Grafana Homebrew tap by running the following command in a terminal - window: - - ```shell - brew tap grafana/grafana - ``` - -2. Install the Grafana Agent Flow formula by running the following command in a - terminal window: - - ```shell - brew install grafana-agent-flow - ``` - -## Operation guide - -After installing Grafana Agent Flow on macOS, it will be exposed as a -launchd service. - -### Run Grafana Agent Flow - -To run Grafana Agent Flow, run the following command in a terminal: - -```shell -brew services start grafana-agent-flow -``` - -After running this command, Grafana Agent Flow will be running as a service and -will automatically run on system startup. - -To check the status of Grafana Agent Flow, run the following command in a -terminal: - -```shell -brew services info grafana-agent-flow -``` - -### Configuring Grafana Agent Flow - -To configure Grafana Agent Flow when installed on macOS, perform the following -steps: - -1. Edit the default configuration file at - `$(brew --prefix)/etc/grafana-agent-flow/config.river`. - -2. Run the following command in a terminal to restart the Grafana Agent Flow - service: - - ```shell - brew services restart grafana-agent-flow - ``` - -### Configuring the Grafana Agent Flow service - -> **NOTE**: Due to limitations in Homebrew, customizing the service used by -> Grafana Agent Flow on macOS requires changing the Homebrew formula and -> reinstalling Grafana Agent Flow. - -To customize the Grafana Agent Flow service on macOS, perform the following -steps: - -1. Run the following command in a terminal: - - ```shell - brew edit grafana-agent-flow - ``` - - This will open the Grafana Agent Flow Homebrew Formula in an editor. - -2. Modify the `service` section as desired to change things such as: - - * The configuration file used by Grafana Agent Flow. - * Flags passed to the Grafana Agent Flow binary. - * Location of log files. - - When done, save the resulting formula file. - -3. Reinstall the Grafana Agent Flow Formula by running the following command in - a terminal: - - ```shell - brew reinstall grafana-agent-flow - ``` - -4. Restart the Grafana Agent Flow service by running the command in a terminal: - - ```shell - brew services restart grafana-agent-flow - ``` - -### Exposing the UI to other machines - -By default, Grafana Agent Flow listens on the local network for its HTTP -server. This prevents other machines on the network from being able to access -the [UI for debugging][UI]. - -To expose the UI to other machines, complete the following steps: - -1. Follow [Configuring the Grafana Agent Flow service](#configuring-the-grafana-agent-flow-service) - to edit command line flags passed to Grafana Agent Flow, including the - following customizations: - - 1. Modify the line inside the `service` block containing - `--server.http.listen-addr=127.0.0.1:12345`, replacing `127.0.0.1` with - the address which other machines on the network have access to, like the - network IP address of the machine Grafana Agent Flow is running on. - - To listen on all interfaces, replace `127.0.0.1` with `0.0.0.0`. - -[UI]: {{< relref "../monitoring/debugging.md#grafana-agent-flow-ui" >}} - -### Viewing Grafana Agent Flow logs - -By default, logs are written to `$(brew --prefix)/var/log/grafana-agent-flow.log` and -`$(brew --prefix)/var/log/grafana-agent-flow.err.log`. - -If you followed [Configuring the Grafana Agent Flow service](#configuring-the-grafana-agent-flow-service) -and changed the path where logs are written, refer to your current copy of the -Grafana Agent Flow formula to locate log files. diff --git a/docs/sources/flow/install/windows.md b/docs/sources/flow/install/windows.md deleted file mode 100644 index 93b168a08369..000000000000 --- a/docs/sources/flow/install/windows.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Windows -weight: 400 ---- - -# Install Grafana Agent Flow on Windows - -Grafana Agent Flow can be installed on AMD64-based Windows machines. - -## Graphical install - -1. Navigate to the [latest release][latest]. -2. Scroll down to the **Assets** section. -3. Download the file called `grafana-agent-flow-installer.exe.zip`. -4. Unzip the downloaded file. -5. Double-click on the unzipped installer to run it. - -[latest]: https://github.com/grafana/agent/releases/latest - -## Silent install - -1. Navigate to the [latest release][latest]. - -2. Scroll down to the **Assets** section. - -3. Download the file called `grafana-agent-flow-installer.exe.zip`. - -4. Unzip the downloaded file. - -5. Run the following command in PowerShell or Command Prompt: - - ```shell - PATH_TO_INSTALLER /S - ``` - - 1. Replace `PATH_TO_INSTALLER` with the path where the unzipped installer - executable is located, such as - `C:\Users\Alexis\Downloads\grafana-agent-flow-installer.exe`. - -[latest]: https://github.com/grafana/agent/releases/latest - -## Operation guide - -After installing Grafana Agent Flow on Windows, it will be exposed as a Windows -Service, where it automatically runs on startup. - -### Configuring Grafana Agent Flow - -To configure Grafana Agent Flow when installed on Windows, perform the following -steps: - -1. Edit the default configuration file at `C:\Program Files\Grafana Agent - Flow\config.river`. - -2. Restart the Grafana Agent Flow service: - - 1. Open the Windows Services manager (`services.msc`): - - 1. Right click on the Start Menu icon. - - 2. Click on **Run**. - - 3. In the resulting dialog box, type `services.msc`. - - 4. Click **OK**. - - 2. Right click on the service called "Grafana Agent Flow". - - 3. In the resulting dialog menu, click on All Tasks > Restart. - -### Change command-line arguments - -By default, the Grafana Agent Flow service will launch with passing the -following arguments to the Grafana Agent Flow binary: - -* `run` -* `C:\Program Files\Grafana Agent Flow\config.river` -* `--storage.path=C:\ProgramData\Grafana Agent Flow\data` - -To change the set of command-line arguments passed to the Grafana Agent Flow -binary, perform the following steps: - -1. Open the Registry Editor: - - 1. Right click on the Start Menu icon. - - 2. Click on **Run**. - - 3. In the resulting dialog box, type `regedit`. - - 4. Click **OK**. - -2. Navigate to the key at the path `HKEY_LOCAL_MACHINE\SOFTWARE\Grafana\Grafana - Agent Flow`. - -3. Double-click on the value called "Arguments". - -4. In the resulting dialog box, enter the new set of arguments to pass to the - Grafana Agent Flow binary. - -5. Restart the Grafana Agent Flow service: - - 1. Open the Windows Services manager (`services.msc`): - - 1. Right click on the Start Menu icon. - - 2. Click on **Run**. - - 3. In the resulting dialog box, type `services.msc`. - - 4. Click **OK**. - - 2. Right click on the service called "Grafana Agent Flow". - - 3. In the resulting dialog menu, click on All Tasks > Restart. - -### Exposing the UI to other machines - -By default, Grafana Agent Flow listens on the local network for its HTTP -server. This prevents other machines on the network from being able to access -the [UI for debugging][UI]. - -To expose the UI to other machines, complete the following steps: - -1. Follow [Change command-line arguments](#change-command-line-arguments) - to edit command line flags passed to Grafana Agent Flow, including the - following customizations: - - 1. Add the following command line argument: - - ``` - --server.http.listen-addr=LISTEN_ADDR:12345 - ``` - - Replace `LISTEN_ADDR` with an address which other machines on the - network have access to, like the network IP address of the machine - Grafana Agent Flow is running on. - - To listen on all interfaces, replace `LISTEN_ADDR` with `0.0.0.0`. - -[UI]: {{< relref "../monitoring/debugging.md#grafana-agent-flow-ui" >}} - -### Viewing Grafana Agent Flow logs - -When running on Windows, Grafana Agent Flow writes its logs to Windows Event -Logs with an event source name of "Grafana Agent Flow". - -To view the logs, perform the following steps: - -1. Open the Event Viewer: - - 1. Right click on the Start Menu icon. - - 2. Click on **Run**. - - 3. In the resulting dialog box, type `eventvwr`. - - 4. Click **OK**. - -2. In the Event Viewer, click on Windows Logs > Application. - -3. Search for events with the source called "Grafana Agent Flow." diff --git a/docs/sources/flow/monitoring/debugging.md b/docs/sources/flow/monitoring/debugging.md index 9de20f9f63bb..9e9b2b47c72b 100644 --- a/docs/sources/flow/monitoring/debugging.md +++ b/docs/sources/flow/monitoring/debugging.md @@ -29,7 +29,7 @@ server, which defaults to listening at `http://localhost:12345`. > learn how to change the HTTP listen address, and pass the appropriate flag > when running Grafana Agent Flow. > -> [install]: {{< relref "../install/" >}} +> [install]: {{< relref "../setup/install/" >}} [grafana-agent run]: {{< relref "../reference/cli/run.md" >}} diff --git a/docs/sources/flow/setup/_index.md b/docs/sources/flow/setup/_index.md new file mode 100644 index 000000000000..7ab21db71a58 --- /dev/null +++ b/docs/sources/flow/setup/_index.md @@ -0,0 +1,12 @@ +--- +description: Install and configure Grafana Agent Flow +title: Setup Grafana Agent Flow +menuTitle: Setup Flow mode +weight: 50 +--- + +# Setup Grafana Agent Flow + +This section includes information that helps you get Grafana Agent Flow installed and configured. + +{{< section >}} diff --git a/docs/sources/flow/setup/configure/_index.md b/docs/sources/flow/setup/configure/_index.md new file mode 100644 index 000000000000..ec4e89b39666 --- /dev/null +++ b/docs/sources/flow/setup/configure/_index.md @@ -0,0 +1,18 @@ +--- +description: Configure Grafana Agent Flow after it is installed +title: Configure Grafana Agent Flow +menuTitle: Configure Flow mode +weight: 150 +--- + +# Configure Grafana Agent Flow + +You can configure Grafana Agent Flow after it is installed. The default configuration file is located at: + +* Linux: `/etc/grafana-agent-flow.river` +* macOS: `$(brew --prefix)/etc/grafana-agent-flow/config.river` +* Windows: `C:\Program Files\Grafana Agent Flow\config.river` + +This section includes information that helps you configure Grafana Agent Flow. + +{{< section >}} diff --git a/docs/sources/flow/setup/configure/configure-linux.md b/docs/sources/flow/setup/configure/configure-linux.md new file mode 100644 index 000000000000..b6cf1b572b97 --- /dev/null +++ b/docs/sources/flow/setup/configure/configure-linux.md @@ -0,0 +1,89 @@ +--- +description: Learn how to configure Grafana Agent Flow on Linux +title: Configure Grafana Agent Flow on Linux +menuTitle: Linux +weight: 200 +--- + +# Configure Grafana Agent Flow on Linux + +To configure Grafana Agent Flow on Linux, perform the following steps: + +1. Edit the default configuration file at `/etc/grafana-agent-flow.river`. + +1. Run the following command in a terminal to reload the configuration file: + + ```shell + sudo systemctl reload grafana-agent-flow + ``` + +To change the configuration file used by the service, perform the following steps: + +1. Edit the environment file for the service: + + * Debian or Ubuntu: edit `/etc/default/grafana-agent-flow` + * RHEL/Fedora or SUSE/openSUSE: edit `/etc/sysconfig/grafana-agent-flow` + +1. Change the contents of the `CONFIG_FILE` environment variable to point to + the new configuration file to use. + +1. Restart the Grafana Agent Flow service: + + ```shell + sudo systemctl restart grafana-agent-flow + ``` + +## Pass additional command-line flags + +By default, the Grafana Agent Flow service launches with the [run][] +command, passing the following flags: + +* `--storage.path=/var/lib/grafana-agent-flow` + +To pass additional command-line flags to the Grafana Agent Flow binary, perform +the following steps: + +1. Edit the environment file for the service: + + * Debian-based systems: edit `/etc/default/grafana-agent-flow` + * RedHat or SUSE-based systems: edit `/etc/sysconfig/grafana-agent-flow` + +1. Change the contents of the `CUSTOM_ARGS` environment variable to specify + command-line flags to pass. + +1. Restart the Grafana Agent Flow service: + + ```shell + sudo systemctl restart grafana-agent-flow + ``` + +To see the list of valid command-line flags that can be passed to the service, +refer to the documentation for the [run][] command. + +[run]: {{< relref "../../reference/cli/run.md" >}} + +## Expose the UI to other machines + +By default, Grafana Agent Flow listens on the local network for its HTTP +server. This prevents other machines on the network from being able to access +the [UI for debugging][UI]. + +To expose the UI to other machines, complete the following steps: + +1. Follow [Pass additional command-line flags](#pass-additional-command-line-flags) + to edit command line flags passed to Grafana Agent Flow, including the + following customizations: + + 1. Add the following command line argument to `CUSTOM_ARGS`: + + ``` + --server.http.listen-addr=LISTEN_ADDR:12345 + ``` + + Replace `LISTEN_ADDR` with an address which other machines on the + network have access to, like the network IP address of the machine + Grafana Agent Flow is running on. + + To listen on all interfaces, replace `LISTEN_ADDR` with `0.0.0.0`. + +[UI]: {{< relref "../../monitoring/debugging.md#grafana-agent-flow-ui" >}} diff --git a/docs/sources/flow/setup/configure/configure-macos.md b/docs/sources/flow/setup/configure/configure-macos.md new file mode 100644 index 000000000000..9f154ecec396 --- /dev/null +++ b/docs/sources/flow/setup/configure/configure-macos.md @@ -0,0 +1,80 @@ +--- +description: Learn how to configure Grafana Agent Flow on macOS +title: Configure Grafana Agent Flow on macOS +menuTitle: macOS +weight: 300 +--- + +# Configure Grafana Agent Flow on macOS + +To configure Grafana Agent Flow on macOS, perform the following +steps: + +1. Edit the default configuration file at + `$(brew --prefix)/etc/grafana-agent-flow/config.river`. + +1. Run the following command in a terminal to restart the Grafana Agent Flow + service: + + ```shell + brew services restart grafana-agent-flow + ``` + +## Configure the Grafana Agent Flow service + +> **NOTE**: Due to limitations in Homebrew, customizing the service used by +> Grafana Agent Flow on macOS requires changing the Homebrew formula and +> reinstalling Grafana Agent Flow. + +To customize the Grafana Agent Flow service on macOS, perform the following +steps: + +1. Run the following command in a terminal: + + ```shell + brew edit grafana-agent-flow + ``` + + This will open the Grafana Agent Flow Homebrew Formula in an editor. + +1. Modify the `service` section as desired to change things such as: + + * The configuration file used by Grafana Agent Flow. + * Flags passed to the Grafana Agent Flow binary. + * Location of log files. + + When done, save the resulting formula file. + +1. Reinstall the Grafana Agent Flow Formula by running the following command in + a terminal: + + ```shell + brew reinstall grafana-agent-flow + ``` + +1. Restart the Grafana Agent Flow service by running the command in a terminal: + + ```shell + brew services restart grafana-agent-flow + ``` + +## Expose the UI to other machines + +By default, Grafana Agent Flow listens on the local network for its HTTP +server. This prevents other machines on the network from being able to access +the [UI for debugging][UI]. + +To expose the UI to other machines, complete the following steps: + +1. Follow [Configure the Grafana Agent Flow service](#configure-the-grafana-agent-flow-service) + to edit command line flags passed to Grafana Agent Flow, including the + following customizations: + + 1. Modify the line inside the `service` block containing + `--server.http.listen-addr=127.0.0.1:12345`, replacing `127.0.0.1` with + the address which other machines on the network have access to, like the + network IP address of the machine Grafana Agent Flow is running on. + + To listen on all interfaces, replace `127.0.0.1` with `0.0.0.0`. + +[UI]: {{< relref "../../monitoring/debugging.md#grafana-agent-flow-ui" >}} diff --git a/docs/sources/flow/setup/configure/configure-windows.md b/docs/sources/flow/setup/configure/configure-windows.md new file mode 100644 index 000000000000..8306a876fe76 --- /dev/null +++ b/docs/sources/flow/setup/configure/configure-windows.md @@ -0,0 +1,87 @@ +--- +description: Learn how to configure Grafana Agent Flow on Windows +title: Configure Grafana Agent Flow on Windows +menuTitle: Windows +weight: 400 +--- + +# Configure Grafana Agent Flow on Windows + +To configure Grafana Agent Flow when installed on Windows, perform the following +steps: + +1. Edit the default configuration file at `C:\Program Files\Grafana Agent Flow\config.river`. + +1. Restart the Grafana Agent Flow service: + + 1. Open the Windows Services manager (`services.msc`): + + 1. Right click on the Start Menu and select **Run**. + + 1. Type `services.msc` and click **OK**. + + 1. Right click on the service called **Grafana Agent Flow**. + + 1. Click on **All Tasks > Restart**. + +## Change command-line arguments + +By default, the Grafana Agent Flow service will launch with passing the +following arguments to the Grafana Agent Flow binary: + +* `run` +* `C:\Program Files\Grafana Agent Flow\config.river` +* `--storage.path=C:\ProgramData\Grafana Agent Flow\data` + +To change the set of command-line arguments passed to the Grafana Agent Flow +binary, perform the following steps: + +1. Open the Registry Editor: + + 1. Right click on the Start Menu and select **Run**. + + 1. Type `regedit` and click **OK**. + +1. Navigate to the key at the path `HKEY_LOCAL_MACHINE\SOFTWARE\Grafana\Grafana Agent Flow`. + +1. Double-click on the value called "Arguments". + +1. In the resulting dialog box, enter the new set of arguments to pass to the Grafana Agent Flow binary. + +1. Restart the Grafana Agent Flow service: + + 1. Open the Windows Services manager (`services.msc`): + + 1. 1. Right click on the Start Menu and select **Run**. + + 1. Type `services.msc` and click **OK**. + + 1. Right click on the service called **Grafana Agent Flow**. + + 1. Click on **All Tasks > Restart**. + +## Expose the UI to other machines + +By default, Grafana Agent Flow listens on the local network for its HTTP +server. This prevents other machines on the network from being able to access +the [UI for debugging][UI]. + +To expose the UI to other machines, complete the following steps: + +1. Follow [Change command-line arguments](#change-command-line-arguments) + to edit command line flags passed to Grafana Agent Flow, including the + following customizations: + + 1. Add the following command line argument: + + ``` + --server.http.listen-addr=LISTEN_ADDR:12345 + ``` + + Replace `LISTEN_ADDR` with an address which other machines on the + network have access to, like the network IP address of the machine + Grafana Agent Flow is running on. + + To listen on all interfaces, replace `LISTEN_ADDR` with `0.0.0.0`. + +[UI]: {{< relref "../../monitoring/debugging.md#grafana-agent-flow-ui" >}} diff --git a/docs/sources/flow/setup/install/_index.md b/docs/sources/flow/setup/install/_index.md new file mode 100644 index 000000000000..039810818b8b --- /dev/null +++ b/docs/sources/flow/setup/install/_index.md @@ -0,0 +1,17 @@ +--- +title: Install Grafana Agent Flow +menuTitle: Install Flow mode +weight: 50 +aliases: + - /docs/sources/flow/install/ +--- + +# Install Grafana Agent Flow + +You can install Grafana Agent Flow on Kubernetes, Docker, Linux, Windows, or macOS. + +{{% admonition type="note" %}} +Installation of Grafana on other operating systems is possible, but is not recommended or supported. +{{% /admonition %}} + +{{< section >}} diff --git a/docs/sources/flow/install/binary.md b/docs/sources/flow/setup/install/binary.md similarity index 87% rename from docs/sources/flow/install/binary.md rename to docs/sources/flow/setup/install/binary.md index 374547e8a255..007b8b14f346 100644 --- a/docs/sources/flow/install/binary.md +++ b/docs/sources/flow/setup/install/binary.md @@ -1,9 +1,13 @@ --- -title: Other systems +description: Learn how to install Grafana Agent Flow on other systems +title: Install Grafana Agent Flow on other systems +menuTitle: Other systems weight: 600 +aliases: + - ../../install/binary/ --- -# Run Grafana Agent Flow on other systems +# Install Grafana Agent Flow on other systems Grafana Agent Flow is distributed as plain binaries for various systems: diff --git a/docs/sources/flow/install/docker.md b/docs/sources/flow/setup/install/docker.md similarity index 84% rename from docs/sources/flow/install/docker.md rename to docs/sources/flow/setup/install/docker.md index cab1c1fc1cd3..5b5e56672e63 100644 --- a/docs/sources/flow/install/docker.md +++ b/docs/sources/flow/setup/install/docker.md @@ -1,6 +1,10 @@ --- -title: Docker +description: Learn how to install GRafana Agent Flow on Docker +title: Install Grafana Agent Flow on Docker +menuTitle: Docker weight: 200 +aliases: + - ../../install/docker/ --- # Install Grafana Agent Flow on Docker @@ -56,8 +60,8 @@ refer to the documentation for [run][]. > argument like in the example above, otherwise the [debugging UI][] won't be > available outside of the Docker container. -[debugging UI]: {{< relref "../monitoring/debugging.md#grafana-agent-flow-ui" >}} -[run]: {{< relref "../reference/cli/run.md" >}} +[debugging UI]: {{< relref "../../monitoring/debugging.md#grafana-agent-flow-ui" >}} +[run]: {{< relref "../../reference/cli/run.md" >}} ## Run a Windows Docker container @@ -86,8 +90,8 @@ refer to the documentation for [run][]. > argument like in the example above, otherwise the [debugging UI][] won't be > available outside of the Docker container. -[debugging UI]: {{< relref "../monitoring/debugging.md#grafana-agent-flow-ui" >}} -[run]: {{< relref "../reference/cli/run.md" >}} +[debugging UI]: {{< relref "../../monitoring/debugging.md#grafana-agent-flow-ui" >}} +[run]: {{< relref "../../reference/cli/run.md" >}} ## Result @@ -98,4 +102,4 @@ To validate that Grafana Agent Flow is running successfully, navigate to to ensure that the Grafana Agent Flow [UI][] loads without error. -[UI]: {{< relref "../monitoring/debugging.md#grafana-agent-flow-ui" >}} +[UI]: {{< relref "../../monitoring/debugging.md#grafana-agent-flow-ui" >}} diff --git a/docs/sources/flow/install/kubernetes.md b/docs/sources/flow/setup/install/kubernetes.md similarity index 94% rename from docs/sources/flow/install/kubernetes.md rename to docs/sources/flow/setup/install/kubernetes.md index 0a250668c07b..15c371ddebe2 100644 --- a/docs/sources/flow/install/kubernetes.md +++ b/docs/sources/flow/setup/install/kubernetes.md @@ -1,6 +1,10 @@ --- -title: Kubernetes +description: Learn how to install Grafana Agent Flow on Kubernetes +title: Install Grafana Agent Flow on Kubernetes +menuTitle: Kubernetes weight: 100 +aliases: + - ../../install/kubernetes/ --- ## Install Grafana Agent Flow on Kubernetes diff --git a/docs/sources/flow/setup/install/linux.md b/docs/sources/flow/setup/install/linux.md new file mode 100644 index 000000000000..d54e25f7d801 --- /dev/null +++ b/docs/sources/flow/setup/install/linux.md @@ -0,0 +1,163 @@ +--- +description: Learn how to install Grafana Agent Flow on Linux +title: Install Grafana Agent Flow on Linux +menuTitle: Linux +weight: 300 +aliases: + - ../../install/linux/ +--- + +# Install Grafana Agent Flow on Linux + +You can install Grafana Agent Flow as a systemd service on Linux. + +## Install on Debian or Ubuntu + +To install Grafana Agent Flow on Debian or Ubuntu, run the following commands in a terminal window. + +1. Import the GPG key and add the Grafana package repository: + + ```shell + sudo mkdir -p /etc/apt/keyrings/ + wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null + echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list + ``` + +1. Update the repositories: + + ```shell + sudo apt-get update + ``` + +1. Install Grafana Agent Flow: + + ```shell + sudo apt-get install grafana-agent-flow + ``` + +### Uninstall on Debian or Ubuntu + +To uninstall Grafana Agent Flow on Debian or Ubuntu, run the following commands in a terminal window. + +1. Stop the systemd service for Grafana Agent Flow: + + ```shell + sudo systemctl stop grafana-agent-flow + ``` + +1. Uninstall Grafana Agent Flow: + + ```shell + sudo apt remove grafana-agent-flow + ``` + +1. (Optional) Remove the Grafana repository: + + ```shell + sudo rm -i /etc/apt/sources.list.d/grafana.list + ``` + +## Install on RHEL or Fedora + +To install Grafana Agent Flow on RHEL or Fedora, run the following commands in a terminal window. + +1. Import the GPG key: + + ```shell + wget -q -O gpg.key https://rpm.grafana.com/gpg.key + sudo rpm --import gpg.key + ``` + +1. Create `/etc/yum.repos.d/grafana.repo` with the following content: + + ```shell + [grafana] + name=grafana + baseurl=https://rpm.grafana.com + repo_gpgcheck=1 + enabled=1 + gpgcheck=1 + gpgkey=https://rpm.grafana.com/gpg.key + sslverify=1 + sslcacert=/etc/pki/tls/certs/ca-bundle.crt + ``` + +1. (Optional) Verify the Grafana repository configuration: + + ```shell + cat /etc/yum.repos.d/grafana.repo + ``` + +1. Install Grafana Agent Flow: + + ```shell + sudo dnf install grafana-agent-flow + ``` + +### Uninstall on RHEL or Fedora + +To uninstall Grafana Agent Flow on RHEL or Fedora, run the following commands in a terminal window: + +1. Stop the systemd service for Grafana Agent Flow: + + ```shell + sudo systemctl stop grafana-agent-flow + ``` + +1. Uninstall Grafana Agent Flow: + + ```shell + sudo dnf remove grafana-agent-flow + ``` + +1. (Optional) Remove the Grafana repository: + + ```shell + sudo rm -i /etc/yum.repos.d/rpm.grafana.repo + ``` + +## Install on SUSE or openSUSE + +To install Grafana Agent Flow on SUSE or openSUSE, run the following commands in a terminal window. + +1. Import the GPG key and add the Grafana package repository: + + ```shell + wget -q -O gpg.key https://rpm.grafana.com/gpg.key + sudo rpm --import gpg.key + sudo zypper addrepo https://rpm.grafana.com grafana + ``` + +1. Update the repositories: + + ```shell + sudo zypper update + ``` + +1. Install Grafana Agent Flow: + + ```shell + sudo zypper install grafana-agent-flow + ``` + +### Uninstall on SUSE or openSUSE + +To uninstall Grafana Agent Flow on SUSE or openSUSE, run the following commands in a terminal: + +1. Stop the systemd service for Grafana Agent Flow: + + ```shell + sudo systemctl stop grafana-agent-flow + ``` + +1. Uninstall Grafana Agent Flow: + + ```shell + sudo zypper remove grafana-agent-flow + ``` + +1. (Optional) Remove the Grafana repository: + + ```shell + sudo zypper removerepo grafana + ``` diff --git a/docs/sources/flow/setup/install/macos.md b/docs/sources/flow/setup/install/macos.md new file mode 100644 index 000000000000..115abb46e431 --- /dev/null +++ b/docs/sources/flow/setup/install/macos.md @@ -0,0 +1,45 @@ +--- +description: Learn how to install Grafana Agent Flow on macOS +title: Install Grafana Agent Flow on macOS +menuTitle: macOS +weight: 500 +aliases: + - ../../install/macos/ +--- + +# Install Grafana Agent Flow on macOS + +You can install Grafana Agent Flow with Homebrew on macOS. + +{{% 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`. +{{% /admonition %}} + +## Before you begin + +* Install [Homebrew][] on your computer. + +[Homebrew]: https://brew.sh + +## Install + +To install Grafana Agent Flow on macOS, run the following commands in a terminal window. + +1. Add the Grafana Homebrew tap: + + ```shell + brew tap grafana/grafana + ``` + +1. Install Grafana Agent Flow: + + ```shell + brew install grafana-agent-flow + ``` +## Uninstall + +To install Grafana Agent Flow 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 new file mode 100644 index 000000000000..7c04a221189e --- /dev/null +++ b/docs/sources/flow/setup/install/windows.md @@ -0,0 +1,54 @@ +--- +description: Learn how to install Grafana Agent Flow on Windows +title: Install Grafana Agent Flow on Windows +menuTitle: Windows +weight: 400 +aliases: + - ../../install/windows/ +--- + +# Install Grafana Agent Flow on Windows + +You can install Grafana Agent Flow on Windows with the stanadrd graphical installer, or as a silent install. + +## Graphical install + +1. Navigate to the [latest release][latest]. + +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. + +[latest]: https://github.com/grafana/agent/releases/latest + +## Silent install + +1. Navigate to the [latest release][latest]. + +1. Scroll down to the **Assets** section. + +1. Download the file called `grafana-agent-flow-installer.exe.zip`. + +1. Unzip the downloaded file. + +1. Run the following command in PowerShell or Command Prompt: + + ```shell + PATH_TO_INSTALLER /S + ``` + + Replace `PATH_TO_INSTALLER` with the path where the unzipped installer + executable is located, such as + `C:\Users\Alexis\Downloads\grafana-agent-flow-installer.exe`. + +[latest]: https://github.com/grafana/agent/releases/latest + +## Uninstall + +You can uninstall Grafana Agent Flow with Windows Remove Programs or `C:\Program Files\Grafana Agent\uninstaller.exe`. Uninstalling Grafana Agent Flow will stop the service and remove it from disk. This includes any configuration files in the installation directory. + +Grafana Agent Flow can also be silently uninstalled by running `uninstall.exe /S` as Administrator. diff --git a/docs/sources/flow/setup/start-agent.md b/docs/sources/flow/setup/start-agent.md new file mode 100644 index 000000000000..5b66a385a271 --- /dev/null +++ b/docs/sources/flow/setup/start-agent.md @@ -0,0 +1,123 @@ +--- +description: Learn how to start, restart, and stop Grafana Agent Flow after it is installed +title: Start, restart, and stop Grafana Agent Flow +menuTitle: Start Flow mode +weight: 800 +--- + +# Start Grafana Agent Flow + +You can start, restart, and stop Grafana Agent Flow after it is installed. + +## Linux + +Grafana Agent Flow is installed as a [systemd][] service on Linux. + +[systemd]: https://systemd.io/ + +### Start Grafana Agent Flow + +To start Grafana Agent Flow, run the following commands in a terminal window. + +1. Start Grafana Agent Flow: + + ```shell + sudo systemctl start grafana-agent-flow + ``` + +1. (Optional) Verify that the service is running: + + ```shell + sudo systemctl status grafana-agent-flow + ``` + +### Configure Grafana Agent Flow to start at boot + +To automatically run Grafana Agent Flow when the system starts, run the following command in a terminal: + +```shell +sudo systemctl enable grafana-agent-flow.service +``` + +### Restart Grafana Agent Flow + +To restart Grafana Agent Flow, run the following command in a terminal window: + +```shell +sudo systemctl restart grafana-agent-flow +``` + +### Stop Grafana Agent Flow + +To stop Grafana Agent Flow, run the following commands in a terminal window: + +```shell +sudo systemctl stop grafana-agent-flow +``` + +### View Grafana Agent Flow logs on Linux + +To view the Grafana Agent Flow log files, run the following command in a terminal: + +```shell +sudo journalctl -u grafana-agent-flow +``` + +## Windows + +Grafana Agent Flow is installed as a Windows Service. The service is configured to automatically run on startup. + +To verify that Grafana Agent Flow is running as a Windows Service: + +1. Open the Windows Services manager (services.msc): + + 1. Right click on the Start Menu and select **Run**. + + 1. Type: `services.msc` and click **OK**. + +1. Scroll down to find the **Grafana Agent Flow** service and verify that the **Status** is **Running**. + +### View Grafana Agent Flow logs + +When running on Windows, Grafana Agent Flow writes its logs to Windows Event +Logs with an event source name of "Grafana Agent Flow". + +To view the logs, perform the following steps: + +1. Open the Event Viewer: + + 1. Right click on the Start Menu and select **Run**. + + 1. Type `eventvwr` and click **OK**. + +1. In the Event Viewer, click on **Windows Logs > Application**. + +1. Search for events with the source **Grafana Agent Flow**. + +## macOS + +Grafana Agent Flow is installed as a launchd service on macOS. + +### Start Grafana Agent Flow + +1. Start Grafana Agent Flow: + + ```shell + brew services start grafana-agent-flow + ``` + + Grafana Agent Flow automatically runs when the system starts. + +1. (Optional) Verify that the serivce is running: + + ```shell + brew services info grafana-agent-flow + ``` +### View Grafana Agent Flow logs on macOS + +By default, logs are written to `$(brew --prefix)/var/log/grafana-agent-flow.log` and +`$(brew --prefix)/var/log/grafana-agent-flow.err.log`. + +If you followed [Configuring the Grafana Agent Flow service](#configuring-the-grafana-agent-flow-service) +and changed the path where logs are written, refer to your current copy of the +Grafana Agent Flow formula to locate log files.