Caution

Grafana Agent has reached End-of-Life (EOL) on November 1, 2025. Agent is no longer receiving vendor support and will no longer receive security or bug fixes. Current users of Agent Static mode, Agent Flow mode, and Agent Operator should proceed with migrating to Grafana Alloy. If you have already migrated to Alloy, no further action is required. Read more about why we recommend migrating to Grafana Alloy.

Documentationbreadcrumb arrow Grafana Agentbreadcrumb arrow Flow modebreadcrumb arrow Referencebreadcrumb arrow Components referencebreadcrumb 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 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

Alloy 
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
clientclientAdditional options for configuring the S3 client.no

client block

The client 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
signing_regionstringUsed 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:

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

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