`remote.s3`

remote.s3 exposes the string contents of a file located in AWS 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 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

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

Arguments

You can use the following arguments with remote.s3:

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.	`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:

Block	Description	Required
`client`	Additional options for configuring the S3 client.	no

`client`

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

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:

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

remote.s3 exposes the following metrics:

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

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

Was this page helpful?

Email docs@grafana.com

Help and support

Community