Menu

Caution

Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentationbreadcrumb arrow Grafana Agentbreadcrumb arrow Grafana Agent Flowbreadcrumb arrow Referencebreadcrumb arrow Componentsbreadcrumb arrow remote.s3
Open source

remote.s3

remote.s3 exposes the string contents of a file located in AWS S3 to other components. The file will be polled for changes so that the most recent content is always available.

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

Multiple remote.s3 components can be specified using different name labels. By default, AWS environment variables are used to authenticate against S3. The key and secret arguments inside client_options blocks can be used to provide custom authentication.

NOTE: Other S3-compatible systems can be read with remote.s3 but may require specific authentication environment variables. There is no guarantee that remote.s3 will work with non-AWS S3 systems.

Usage

river 
remote.s3 "LABEL" {
  path = S3_FILE_PATH
}

Arguments

The following arguments are supported:

NameTypeDescriptionDefaultRequired
pathstringPath in the format of "s3://bucket/file".yes
poll_frequencydurationHow often to poll the file for changes. Must be greater than 30 seconds."10m"no
is_secretboolMarks the file as containing a secret.falseno

NOTE: path must include a full path to a file. This does not support reading of directories.

Blocks

HierarchyNameDescriptionRequired
client_optionsclient_optionsAdditional options for configuring the S3 client.no

client_options block

The client_options block customizes options to connect to the S3 server.

NameTypeDescriptionDefaultRequired
keystringUsed to override default access key.no
secretsecretUsed to override default secret value.no
endpointstringSpecifies a custom url to access, used generally for S3-compatible systems.no
disable_sslboolUsed to disable SSL, generally used for testing.no
use_path_stylestringPath style is a deprecated setting that is generally enabled for S3 compatible systems.falseno
regionstringUsed to override default region.no

Exported fields

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

NameTypeDescriptionDefaultRequired
contentstring or secretThe contents of the file.no

The content field will be secret if is_secret was set to 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 does not expose any component-specific debug information.

Debug metrics

remote.s3 does not expose any component-specific debug metrics.

Example

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