---
title: "remote.s3 | Grafana Alloy documentation"
description: "Learn about remote.s3"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# `remote.s3`

`remote.s3` exposes the string contents of a file located in [AWS S3](https://aws.amazon.com/s3/) to other components. `remote.s3` polls the file for changes, so the most recent content is always available.

The most common use of `remote.s3` is to load secrets from files.

You can specify multiple `remote.s3` components by giving them different labels. By default, `remote.s3` uses [AWS environment variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) to authenticate against S3. Use the `key` and `secret` arguments inside `client` blocks to provide custom authentication.

> Note
> 
> `remote.s3` can read other S3-compatible systems, but they may require specific authentication environment variables. `remote.s3` isn’t guaranteed to work with non-AWS S3 systems.

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
remote.s3 "<LABEL>" {
  path = "<S3_FILE_PATH>"
}
```

## Arguments

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

Expand table

| Name             | Type       | Description                                                                                             | Default | Required |
|------------------|------------|---------------------------------------------------------------------------------------------------------|---------|----------|
| `path`           | `string`   | Path in the format of `"s3://bucket/file"`.                                                             |         | yes      |
| `is_secret`      | `bool`     | Marks the file as containing a [secret](../../../../get-started/expressions/types_and_values/#secrets). | `false` | no       |
| `poll_frequency` | `duration` | How often to poll the file for changes. Must be greater than 30 seconds.                                | `"10m"` | no       |

> Note
> 
> `path` must include a full path to a file. This doesn’t support reading of directories.

## Blocks

You can use the following block with `remote.s3`:

No valid configuration blocks found.

### `client`

The `client` block customizes options to connect to the S3 server.

Expand table

| Name             | Type     | Description                                                                            | Default | Required |
|------------------|----------|----------------------------------------------------------------------------------------|---------|----------|
| `key`            | `string` | Used to override default access key.                                                   |         | no       |
| `secret`         | `secret` | Used to override default secret value.                                                 |         | no       |
| `endpoint`       | `string` | Specifies a custom URL to access, used generally for S3-compatible systems.            |         | no       |
| `disable_ssl`    | `bool`   | Used to disable SSL, generally used for testing.                                       | `false` | no       |
| `use_path_style` | `bool`   | Path style is a deprecated setting that’s generally enabled for S3 compatible systems. | `false` | no       |
| `region`         | `string` | Used to override default region.                                                       |         | no       |
| `signing_region` | `string` | Used to override the signing region when using a custom endpoint.                      |         | no       |

## Exported fields

The following fields are exported and can be referenced by other components:

Expand table

| Name      | Type                 | Description               |
|-----------|----------------------|---------------------------|
| `content` | `string` or `secret` | The contents of the file. |

The `content` field is secret if `is_secret` is `true`.

## Component health

Instances of `remote.s3` report as healthy if the most recent read of the watched file was successful.

## Debug information

`remote.s3` doesn’t expose any component-specific debug information.

## Debug metrics

The following Prometheus metrics are exposed:

Expand table

| Name                                             | Type      | Description                                 |
|--------------------------------------------------|-----------|---------------------------------------------|
| `remote_s3_errors_total`                         | `counter` | The number of errors while accessing S3.    |
| `remote_s3_timestamp_last_accessed_unix_seconds` | `gauge`   | The last successful access in Unix seconds. |

## Examples

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
remote.s3 "data" {
  path = "s3://test-bucket/file.txt"
}
```