Update Agent documentation to use doc/reference instead of relrefs (#…

…5555) * Update migrate from static to use doc reference * Update links in opentelemetry topic * Update refernces in Promtail topic * Add full URL to link * Update Prometheus scrape relrefs * Update clustering topic references * More reference updates * Fix a build error * Small correction update * Small text update * Fix syntax for links in blockquotes * Remove redundant relref definition * Fix typos and links in notes * Correct GrafanaCloud to Grafana Cloud * Fix link syntax * Fix some bad link text (cherry picked from commit 1647713)
grafana · Oct 24, 2023 · 2c43fe2 · 2c43fe2
1 parent 449a7de
commit 2c43fe2
Show file tree

Hide file tree

Showing 9 changed files with 246 additions and 177 deletions.
diff --git a/docs/sources/flow/getting-started/collect-opentelemetry-data.md b/docs/sources/flow/getting-started/collect-opentelemetry-data.md
@@ -20,8 +20,6 @@ This topic describes how to:
 * Configure batching
 * Receive OpenTelemetry data over OTLP
 
-[OpenTelemetry]: https://opentelemetry.io
-
 ## Components used in this topic
 
 * [otelcol.auth.basic][]
@@ -30,12 +28,6 @@ This topic describes how to:
 * [otelcol.processor.batch][]
 * [otelcol.receiver.otlp][]
 
-[otelcol.auth.basic]: {{< relref "../reference/components/otelcol.auth.basic.md" >}}
-[otelcol.exporter.otlp]: {{< relref "../reference/components/otelcol.exporter.otlp.md" >}}
-[otelcol.exporter.otlphttp]: {{< relref "../reference/components/otelcol.exporter.otlphttp.md" >}}
-[otelcol.processor.batch]: {{< relref "../reference/components/otelcol.processor.batch.md" >}}
-[otelcol.receiver.otlp]: {{< relref "../reference/components/otelcol.receiver.otlp.md" >}}
-
 ## Before you begin
 
 * Ensure that you have basic familiarity with instrumenting applications with
@@ -45,8 +37,6 @@ This topic describes how to:
 * Identify where Grafana Agent Flow will write received telemetry data.
 * Be familiar with the concept of [Components][] in Grafana Agent Flow.
 
-[Components]: {{< relref "../concepts/components.md" >}}
-
 ## Configure an OpenTelemetry Protocol exporter
 
 Before components can receive OpenTelemetry data, you must have a component
@@ -61,8 +51,6 @@ to forward data to it.
 
 > Refer to the list of available [Components][] for the full list of
 > `otelcol.exporter` components that can be used to export OpenTelemetry data.
->
-> [Components]: {{< relref "../reference/components/" >}}
 
 To configure an `otelcol.exporter.otlp` component for exporting OpenTelemetry
 data using OTLP, complete the following steps:
@@ -180,8 +168,6 @@ batch data before sending it to our exporter.
 > `otelcol.processor` components that can be used to process OpenTelemetry
 > data. You can chain processors by having one processor send data to another
 > processor.
->
-> [Components]: {{< relref "../reference/components/" >}}
 
 To configure an `otelcol.processor.batch` component, complete the following
 steps:
@@ -263,8 +249,6 @@ Agent Flow components.
 > Refer to the list of available [Components][] for the full list of
 > `otelcol.receiver` components that can be used to receive
 > OpenTelemetry-compatible data.
->
-> [Components]: {{< relref "../reference/components/" >}}
 
 To configure an `otelcol.receiver.otlp` component for receiving OTLP data,
 complete the following steps:
@@ -368,3 +352,20 @@ otelcol.exporter.otlp "default" {
 
 For more information on receiving OpenTelemetry data using the OpenTelemetry
 Protocol, refer to [otelcol.receiver.otlp][].
+
+[OpenTelemetry]: https://opentelemetry.io
+
+{{% docs/reference %}}
+[otelcol.auth.basic]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.auth.basic.md"
+[otelcol.auth.basic]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/otelcol.auth.basic.md"
+[otelcol.exporter.otlp]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.exporter.otlp.md"
+[otelcol.exporter.otlp]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/otelcol.exporter.otlp.md"
+[otelcol.exporter.otlphttp]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.exporter.otlphttp.md"
+[otelcol.exporter.otlphttp]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/otelcol.exporter.otlphttp.md"
+[otelcol.processor.batch]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.processor.batch.md"
+[otelcol.processor.batch]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/otelcol.processor.batch.md"
+[otelcol.receiver.otlp]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.receiver.otlp.md"
+[otelcol.receiver.otlp]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/otelcol.receiver.otlp.md"
+[Components]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/components.md"
+[Components]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/components.md"
+{{% /docs/reference %}}
diff --git a/docs/sources/flow/getting-started/collect-prometheus-metrics.md b/docs/sources/flow/getting-started/collect-prometheus-metrics.md
@@ -19,18 +19,12 @@ This topic describes how to:
 * Configure metrics delivery
 * Collect metrics from Kubernetes Pods
 
-[Prometheus]: https://prometheus.io
-
 ## Components used in this topic
 
 * [discovery.kubernetes][]
 * [prometheus.remote_write][]
 * [prometheus.scrape][]
 
-[discovery.kubernetes]: {{< relref "../reference/components/discovery.kubernetes.md" >}}
-[prometheus.remote_write]: {{< relref "../reference/components/prometheus.remote_write.md" >}}
-[prometheus.scrape]: {{< relref "../reference/components/prometheus.scrape.md" >}}
-
 ## Before you begin
 
 * Ensure that you have basic familiarity with instrumenting applications with
@@ -42,8 +36,6 @@ This topic describes how to:
   Cloud, or Grafana Enterprise Metrics.
 * Be familiar with the concept of [Components][] in Grafana Agent Flow.
 
-[Components]: {{< relref "../concepts/components.md" >}}
-
 ## Configure metrics delivery
 
 Before components can collect Prometheus metrics, you must have a component
@@ -168,7 +160,7 @@ To collect metrics from Kubernetes Pods, complete the following steps:
        }
        ```
 
-        1. If you do not want to search for Pods in the Namespace Grafana
+        1. If you don't want to search for Pods in the Namespace Grafana
            Agent is running in, set `own_namespace` to `false`.
 
         2. Replace `NAMESPACE_NAMES` with a comma-delimited list of strings
@@ -233,10 +225,6 @@ To collect metrics from Kubernetes Pods, complete the following steps:
         3. Replace `REMOTE_WRITE_LABEL` with the label chosen for your existing
            `prometheus.remote_write` component.
 
-
-[Field Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
-[Labels and Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement
-
 The following example demonstrates configuring Grafana Agent to collect metrics
 from running production Kubernetes Pods in the `default` Namespace:
 
@@ -377,10 +365,6 @@ To collect metrics from Kubernetes Services, complete the following steps:
         3. Replace `REMOTE_WRITE_LABEL` with the label chosen for your existing
            `prometheus.remote_write` component.
 
-
-[Field Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
-[Labels and Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement
-
 The following example demonstrates configuring Grafana Agent to collect metrics
 from running production Kubernetes Services in the `default` Namespace:
 
@@ -497,4 +481,21 @@ prometheus.remote_write "default" {
 }
 ```
 
-[Objects]: {{< relref "../config-language/expressions/types_and_values.md#objects" >}}
+[Prometheus]: https://prometheus.io
+[Field Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
+[Labels and Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement
+[Field Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
+[Labels and Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement
+
+{{% docs/reference %}}
+[discovery.kubernetes]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/discovery.kubernetes.md"
+[discovery.kubernetes]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/discovery.kubernetes.md"
+[prometheus.remote_write]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/prometheus.remote_write.md"
+[prometheus.remote_write]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/prometheus.remote_write.md"
+[prometheus.scrape]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/prometheus.scrape.md"
+[prometheus.scrape]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/prometheus.scrape.md"
+[Components]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/components.md"
+[Components]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/components.md"
+[Objects]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/config-language/expressions/types_and_values.md#objects"
+[Objects]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/config-language/expressions/types_and_values.md#objects"
+{{% /docs/reference %}}
diff --git a/docs/sources/flow/getting-started/configure-agent-clustering.md b/docs/sources/flow/getting-started/configure-agent-clustering.md
@@ -16,22 +16,21 @@ You can configure Grafana Agent to run with [clustering][] so that
 individual agents can work together for workload distribution and high
 availability.
 
-{{% admonition type="note" %}}
-Clustering is a [beta]({{< relref "../../stability.md#beta" >}}) feature. Beta features are subject to breaking
-changes and may be replaced with equivalent functionality that covers the same
-use case.
-{{%/admonition %}}
 
-This topic describes how to add clustering to an existing installation.
+> **Note:** Clustering is a [beta][] feature. Beta features are subject to breaking changes and may be
+> replaced with equivalent functionality that covers the same use case.
 
-[clustering]: {{< relref "../concepts/clustering.md" >}}
+This topic describes how to add clustering to an existing installation.
 
 ## Configure Grafana Agent clustering with Helm Chart
 
-This section will guide you through enabling clustering when Grafana Agent is
+This section guides you through enabling clustering when Grafana Agent is
 installed on Kubernetes using the [Grafana Agent Helm chart][install-helm].
 
-[install-helm]: {{< relref "../setup/install/kubernetes.md" >}}
+### Before you begin
+
+- Ensure that your `values.yaml` file has `controller.type` set to
+  `statefulset`.
 
 ### Steps
 
@@ -46,7 +45,7 @@ To configure clustering:
        enabled: true
    ```
 
-1. Upgrade your installation to use the new values.yaml file:
+1. Upgrade your installation to use the new `values.yaml` file:
 
    ```bash
    helm upgrade RELEASE_NAME -f values.yaml
@@ -55,10 +54,19 @@ To configure clustering:
    Replace `RELEASE_NAME` with the name of the installation you chose when you
    installed the Helm chart.
 
-1. Use [UI][] to verify the cluster status:
+1. Use the [Grafana Agent UI][UI] to verify the cluster status:
 
    1. Click **Clustering** in the navigation bar.
 
    2. Ensure that all expected nodes appear in the resulting table.
 
-[UI]: {{< relref "../monitoring/debugging.md#clustering-page" >}}
+{{% docs/reference %}}
+[clustering]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/clustering.md"
+[clustering]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/clustering.md"
+[beta]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/stability.md#beta"
+[beta]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/stability.md#beta"
+[install-helm]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/setup/install/kubernetes.md"
+[install-helm]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/setup/install/kubernetes.md"
+[UI]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/monitoring/debugging.md#component-detail-page"
+[UI]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/monitoring/debugging.md#component-detail-page"
+{{% /docs/reference %}}
diff --git a/docs/sources/flow/getting-started/distribute-prometheus-scrape-load.md b/docs/sources/flow/getting-started/distribute-prometheus-scrape-load.md
@@ -17,24 +17,15 @@ Prometheus targets each agent scrapes. [Clustering][] with target
 auto-distribution allows a fleet of agents to work together to dynamically
 distribute their scrape load, providing high-availability.
 
-{{% admonition type="note" %}}
-Clustering is a [beta]({{< relref "../../stability.md#beta" >}}) feature. Beta features are subject to breaking
-changes and may be replaced with equivalent functionality that covers the same
-use case.
-{{%/admonition %}}
-
-[Clustering]: {{< relref "../concepts/clustering.md" >}}
+> **Note:** Clustering is a [beta][] feature. Beta features are subject to breaking
+> changes and may be replaced with equivalent functionality that covers the same use case.
 
 ## Before you begin
 
 - Familiarize yourself with how to [configure existing Grafana Agent installations][configure-grafana-agent].
 - [Configure Prometheus metrics collection][].
 - [Configure clustering][] of agents.
-- Ensure that all of your clustered agents have the same config file.
-
-[configure-grafana-agent]: {{< relref "../setup/configure" >}}
-[Configure Prometheus metrics collection]: {{< relref "collect-prometheus-metrics.md" >}}
-[Configure clustering]: {{< relref "./configure-agent-clustering.md" >}}
+- Ensure that all of your clustered agents have the same configuration file.
 
 ## Steps
 
@@ -53,10 +44,23 @@ To distribute Prometheus metrics scrape load with clustering:
 
 3. Validate that auto-distribution is functioning:
 
-   1. Using the [UI][] on each agent, navigate to the details page for one of
+   1. Using the [Grafana Agent UI][UI] on each agent, navigate to the details page for one of
       the `prometheus.scrape` components you modified.
 
    2. Compare the Debug Info sections between two different agents to ensure
-      that they are not scraping the same sets of targets.
-
-[UI]: {{< relref "../monitoring/debugging.md#component-detail-page" >}}
+      that they're not scraping the same sets of targets.
+
+{{% docs/reference %}}
+[Clustering]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/clustering.md"
+[Clustering]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/clustering.md"
+[beta]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/stability.md#beta"
+[beta]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/stability.md#beta"
+[configure-grafana-agent]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/setup/configure"
+[configure-grafana-agent]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/setup/configure"
+[Configure Prometheus metrics collection]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/getting-started/collect-prometheus-metrics.md"
+[Configure Prometheus metrics collection]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/getting-started/collect-prometheus-metrics.md"
+[Configure clustering]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/getting-started/configure-agent-clustering.md"
+[Configure clustering]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/getting-started/configure-agent-clustering.md"
+[UI]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/monitoring/debugging.md#component-detail-page"
+[UI]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/monitoring/debugging.md#component-detail-page"
+{{% /docs/reference %}}