AWS S3 connections

The aws-s3 connection type represents an Amazon Simple Storage Service (S3) or S3-compatible endpoint. It has multiton cardinality and uses the host lookup strategy.

Configure AWS S3

app-config.yaml

connections:
  - type: aws-s3
    title: Internal object storage
    host: s3.example.com
    endpoint: https://s3.example.com
    s3ForcePathStyle: true
    auth:
      - method: accessKey
        accessKeyId: ${S3_ACCESS_KEY_ID}
        secretAccessKey: ${S3_SECRET_ACCESS_KEY}

Connection fields

Field	Type	Required	Description
host	string	Yes	Host matched against the resource URL supplied by the consumer.
endpoint	string	No	Custom S3 API endpoint.
s3ForcePathStyle	boolean	No	Whether an S3 client should use path-style bucket URLs.

Authentication methods

Method	Field	Type	Required	Description
none	None	—	—	Does not accept authentication fields.
accessKey	accessKeyId	string	Yes	Static AWS access key ID.
accessKey	secretAccessKey	string	Yes	Static AWS secret access key.
assumeRole	roleArn	string	Yes	ARN of the role to assume.
assumeRole	externalId	string	No	External ID passed when assuming the role.

Use none explicitly for an endpoint that permits unauthenticated access. The service does not infer unauthenticated access from a missing auth array.

For assumeRole, the service returns the role parameters. A separate AWS credential provider performs role assumption and credential refresh.

Lookup and selection

The consumer supplies a lookup query containing a URL. The service selects the connection whose host matches the parsed URL host exactly, including a port when one is present.

When more than one authentication entry is visible to the calling plugin, the first visible entry is selected. Use plugin scoping to supply different credentials to a specific plugin; otherwise, configuration order determines which entry is selected.

Consume an AWS S3 connection

const connection = await connections.find({
  type: 'aws-s3',
  query: { url: 'https://s3.example.com/catalog/catalog-info.yaml' },
  authMethods: ['accessKey', 'assumeRole', 'none'],
});

connection.endpoint; // string | undefined
connection.s3ForcePathStyle; // boolean | undefined

Narrow connection.auth.method before reading method-specific credential fields.

Return to the built-in connection type index.