Skip to content

docs: Validate the remote.* component topics #7097

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
clayton-cornell wants to merge 17 commits into
base: main
Choose a base branch
from
Open

docs: Validate the remote.* component topics #7097

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
ddbd325
Validate an clarify some minor points. add review date
clayton-cornell Sep 11, 2026
df2995d
Validat and update configmap topic
clayton-cornell Sep 11, 2026
f6b4ac8
Fix table content
clayton-cornell Sep 11, 2026
d242f2c
Validata content, fix typos, formatting, fix example
clayton-cornell Sep 11, 2026
af60f2d
Formatting cleanup and correct debug metrics section
clayton-cornell Sep 11, 2026
abbccab
Add review date
clayton-cornell Sep 11, 2026
34f1389
Validate content, fix typos, errors, tables
clayton-cornell Sep 11, 2026
ca4373b
Table alignment
clayton-cornell Sep 11, 2026
55b847b
Improve index topic
clayton-cornell Sep 11, 2026
12687ac
Fix for active voice
clayton-cornell Sep 11, 2026
ae67ad3
Fix active voice
clayton-cornell Sep 11, 2026
5b4a416
Fix active voice
clayton-cornell Sep 11, 2026
0c4e35b
Fix passive voice
clayton-cornell Sep 11, 2026
765e13f
Fix active voice
clayton-cornell Sep 11, 2026
94d5a19
Fix table alignment in markdown
clayton-cornell Sep 14, 2026
acecc1a
Fix bad link and align headings
clayton-cornell Sep 14, 2026
c68e627
Fix markdown alignment for readability
clayton-cornell Sep 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion docs/sources/reference/components/remote/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,18 @@
---
canonical: https://grafana.com/docs/alloy/latest/reference/components/remote/
description: Learn about the remote components in Grafana Alloy
review_date: 2026-09-11
labels:
products:
- oss
title: remote
weight: 100
---

# `remote`

This section contains reference documentation for the `remote` components.
The `remote` components retrieve content from sources outside of your {{< param "PRODUCT_NAME" >}} configuration, such as files in object storage, secrets in HashiCorp Vault, and Kubernetes ConfigMaps and Secrets, and expose that content to other components.

Use a `remote` component when a value your configuration depends on, for example, a credential or a list of scrape targets, is managed somewhere else and can change independently of your configuration.

{{< section >}}
48 changes: 25 additions & 23 deletions docs/sources/reference/components/remote/remote.http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,14 @@ labels:
stage: general-availability
products:
- oss
review_date: 2026-09-11
title: remote.http
---

# `remote.http`

`remote.http` exposes the response body of a URL to other components.
The URL is polled for changes so that the most recent content is always available.
`remote.http` polls the URL for changes, so the most recent content is always available.

The most common use of `remote.http` is to load discovery targets from an HTTP server.

Expand All @@ -31,28 +32,29 @@ remote.http "<LABEL>" {

You can use the following arguments with `remote.http`:

| Name | Type | Description | Default | Required |
| ---------------- | ------------- | ------------------------------------------------------------ | ------- | -------- |
| `url` | `string` | URL to poll. | | yes |
| `body` | `string` | The request body. | `""` | no |
| `headers` | `map(string)` | Custom headers for the request. | `{}` | no |
| `is_secret` | `bool` | Whether the response body should be treated as a [secret][]. | `false` | no |
| `method` | `string` | Define HTTP method for the request | `"GET"` | no |
| `poll_frequency` | `duration` | Frequency to poll the URL. | `"1m"` | no |
| `poll_timeout` | `duration` | Timeout when polling the URL. | `"10s"` | no |
| Name | Type | Description | Default | Required |
| ---------------- | ------------- | ----------------------------------------------------------------- | ------- | -------- |
| `url` | `string` | URL to poll. | | yes |
| `body` | `string` | The request body. | `""` | no |
| `headers` | `map(string)` | Custom headers for the request. | `{}` | no |
| `is_secret` | `bool` | Whether to treat the response body as a [secret][]. | `false` | no |
| `method` | `string` | The HTTP method for the request. | `"GET"` | no |
| `poll_frequency` | `duration` | Frequency to poll the URL. | `"1m"` | no |
| `poll_timeout` | `duration` | Timeout when polling the URL. Must be less than `poll_frequency`. | `"10s"` | no |

When `remote.http` performs a poll operation, an HTTP `GET` request is made against the URL specified by the `url` argument.
A poll is triggered by the following:
When `remote.http` performs a poll operation, it makes an HTTP request using the method specified by the `method` argument against the URL specified by the `url` argument.
If the `headers` argument doesn't set a `User-Agent` header, `remote.http` sends a default `User-Agent` header.
The following triggers a poll:

* When the component first loads.
* Every time the component's arguments get re-evaluated.
* At the frequency specified by the `poll_frequency` argument.
- When the component first loads.
- Every time the component's arguments get re-evaluated.
- At the frequency specified by the `poll_frequency` argument.

The poll is successful if the URL returns a `200 OK` response code.
All other response codes are treated as errors and mark the component as unhealthy.
After a successful poll, the response body from the URL is exported.
`remote.http` treats all other response codes as errors and marks the component as unhealthy.
After a successful poll, `remote.http` exports the response body from the URL.

[secret]: ../../../../get-started/configuration-syntax/expressions/types_and_values/#secrets
[secret]: ../../../../get-started/expressions/types_and_values/#secrets

## Blocks

Expand Down Expand Up @@ -111,15 +113,15 @@ The `tls_config` block configures TLS settings for connecting to HTTPS servers.

The following field is exported and can be referenced by other components:

| Name | Type | Description | Default | Required |
| --------- | -------------------- | ------------------------- | ------- | -------- |
| `content` | `string` or `secret` | The contents of the file. | | no |
| Name | Type | Description |
| --------- | -------------------- | ----------------------------------------------------------------------- |
| `content` | `string` or `secret` | The contents of the response body from the most recent successful poll. |

If the `is_secret` argument was `true`, `content` is a secret type.

## Component health

Instances of `remote.http` report as healthy if the most recent HTTP `GET` request of the specified URL succeeds.
Instances of `remote.http` report as healthy if the most recent HTTP request of the specified URL succeeds.

## Debug information

Expand All @@ -129,7 +131,7 @@ Instances of `remote.http` report as healthy if the most recent HTTP `GET` reque

`remote.http` doesn't expose any component-specific debug metrics.

## Example
## Examples

This example reads a JSON array of objects from an endpoint and uses them as a set of scrape targets:

Expand Down
43 changes: 22 additions & 21 deletions docs/sources/reference/components/remote/remote.kubernetes.configmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ labels:
stage: general-availability
products:
- oss
review_date: 2026-09-11
title: remote.kubernetes.configmap
---

Expand Down Expand Up @@ -37,14 +38,14 @@ You can use the following arguments with `remote.kubernetes.configmap`:
| `poll_timeout` | `duration` | Timeout when polling the Kubernetes API. | `"15s"` | no |

When this component performs a poll operation, it requests the ConfigMap data from the Kubernetes API.
A poll is triggered by the following:
The following triggers a poll:

* When the component first loads.
* Every time the component's arguments get re-evaluated.
* At the frequency specified by the `poll_frequency` argument.
- When the component first loads.
- Every time the component's arguments get re-evaluated.
- At the frequency specified by the `poll_frequency` argument.

Any error while polling will mark the component as unhealthy.
After a successful poll, all data is exported with the same field names as the source ConfigMap.
Any error while polling marks the component as unhealthy.
After a successful poll, `remote.kubernetes.configmap` exports all data with the same field names as the source ConfigMap.

## Blocks

Expand Down Expand Up @@ -72,31 +73,31 @@ You can use the following blocks with `remote.kubernetes.configmap`:
### `client`

The `client` block configures the Kubernetes client used to discover ConfigMaps.
If the `client` block isn't provided, the default in-cluster configuration with the service account of the running {{< param "PRODUCT_NAME" >}} Pod is used.
If the `client` block isn't provided, {{< param "PRODUCT_NAME" >}} uses the default in-cluster configuration with the service account of the running {{< param "PRODUCT_NAME" >}} Pod.

The following arguments are supported:
The `client` block supports the following arguments:

| Name | Type | Description | Default | Required |
| ------------------------ | ------------------- | ------------------------------------------------------------------------------------------------ | ------- | -------- |
| `api_server` | `string` | URL of the Kubernetes API server. | | no |
| `bearer_token_file` | `string` | File containing a bearer token to authenticate with. | | no |
| `bearer_token` | `secret` | Bearer token to authenticate with. | | no |
| `enable_http2` | `bool` | Whether HTTP2 is supported for requests. | `true` | no |
| `follow_redirects` | `bool` | Whether redirects returned by the server should be followed. | `true` | no |
| `http_headers` | `map(list(secret))` | Custom HTTP headers to be sent along with each request. The map key is the header name. | | no |
| `bearer_token_file` | `string` | File containing a bearer token to authenticate with. | | no |
| `enable_http2` | `bool` | Whether the client supports HTTP2 for requests. | `true` | no |
| `follow_redirects` | `bool` | Whether the client follows redirects returned by the server. | `true` | no |
| `http_headers` | `map(list(secret))` | Custom HTTP headers to send along with each request. The map key is the header name. | | no |
| `kubeconfig_file` | `string` | Path of the `kubeconfig` file to use for connecting to Kubernetes. | | no |
| `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | | no |
| `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | no |
| `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no |
| `proxy_url` | `string` | HTTP proxy to send requests through. | | no |

At most, one of the following can be provided:
At most, you can provide one of the following:

* [`authorization`](#authorization) block
* [`basic_auth`](#basic_auth) block
* [`bearer_token_file`](#client) argument
* [`bearer_token`](#client) argument
* [`oauth2`](#oauth2) block
- [`authorization`](#authorization) block
- [`basic_auth`](#basic-auth) block
- [`bearer_token_file`](#client) argument
- [`bearer_token`](#client) argument
- [`oauth2`](#oauth2) block

{{< docs/shared lookup="reference/components/http-client-proxy-config-description.md" source="alloy" version="<ALLOY_VERSION>" >}}

Expand Down Expand Up @@ -128,7 +129,7 @@ The `data` field contains a mapping from field names to values.

## Component health

Instances of `remote.kubernetes.configmap` report as healthy if the most recent attempt to poll the kubernetes API succeeds.
Instances of `remote.kubernetes.configmap` report as healthy if the most recent attempt to poll the Kubernetes API succeeds.

## Debug information

Expand All @@ -138,7 +139,7 @@ Instances of `remote.kubernetes.configmap` report as healthy if the most recent

`remote.kubernetes.configmap` doesn't expose any component-specific debug metrics.

## Example
## Examples

This example reads a Secret and a ConfigMap from Kubernetes and uses them to supply remote-write credentials.

Expand All @@ -164,4 +165,4 @@ prometheus.remote_write "default" {
}
```

This example assumes that the Secret and ConfigMap have already been created, and that the appropriate field names exist in their data.
This example assumes that the Secret and ConfigMap already exist, and that the appropriate field names exist in their data.
Loading
Loading