S3 Object Variables
A ${s3:<bucket>/<key>} variable reads the content of an Amazon S3 object while the Serverless Framework loads serverless.yml. Use it for values kept in a shared bucket, such as a configuration value or a certificate, that several services read.
The following serverless.yml sets an environment variable to the content of the config/api-url.txt object in the my-config-bucket bucket:
# serverless.yml
service: my-service
provider:
name: aws
runtime: nodejs24.x
functions:
hello:
handler: handler.hello
environment:
API_URL: ${s3:my-config-bucket/config/api-url.txt}
The variable resolves to the object's content as a string, with no parsing. The bucket can be in any Region: requests follow Amazon S3's redirect to the bucket's Region.
Syntax of the s3 variable
${s3:BUCKET/KEY}
${RESOLVER_NAME:s3:BUCKET/KEY}
${RESOLVER_NAME:s3:s3://BUCKET/KEY}
${RESOLVER_NAME:s3:arn:aws:s3:::BUCKET/KEY}
${RESOLVER_NAME:NESTED_RESOLVER_NAME:KEY}
${RESOLVER_NAME:NESTED_RESOLVER_NAME}
BUCKET: the bucket name. Everything after the first/is the object key, so keys with/work as written.RESOLVER_NAME: an AWS resolver.${s3:...}uses the deployment credentials.NESTED_RESOLVER_NAME: a nested resolver withtype: s3that sets the bucket, and optionally the key; see Set the bucket and key in a resolver.- Through a resolver, the address can also be an S3 URI (
s3://BUCKET/KEY) or an S3 object ARN in theawspartition (arn:aws:s3:::BUCKET/KEY).
When the object doesn't exist, the variable uses its default (${s3:my-config-bucket/config/api-url.txt, 'https://example.com'}), otherwise the command stops with a Cannot resolve '${s3:...}' variable error. Other errors, such as a missing bucket or denied access, stop the command even when a default is set.
Permissions for s3 variables
The credentials that read the object need s3:GetObject on it. Grant s3:ListBucket on the bucket too when a variable has a default: without it, Amazon S3 answers a request for a missing object with AccessDenied instead of NoSuchKey, and AccessDenied stops the command. See the GetObject permissions.
Read objects with another account or profile
To read an object with other credentials, declare an AWS resolver and reference s3 through it:
stages:
default:
resolvers:
sharedAccount:
type: aws
profile: shared-account
provider:
name: aws
functions:
hello:
handler: handler.hello
environment:
API_URL: ${sharedAccount:s3:my-config-bucket/config/api-url.txt}
LOGO_URL: ${sharedAccount:s3:s3://my-config-bucket/config/logo-url.txt}
This service also deploys with the shared-account profile: a single type: aws resolver supplies the deployment credentials when neither provider.profile nor provider.resolver is set. To deploy with other credentials, set provider.profile, or declare another type: aws resolver and name it in provider.resolver.
Set the bucket and key in a resolver
To name the bucket once, declare a nested resolver with type: s3 and bucketName; the variable's address is then the object key. With objectKey set as well, the variable needs no address:
stages:
default:
resolvers:
sharedAccount:
type: aws
configBucket:
type: s3
bucketName: my-config-bucket
apiUrlFile:
type: s3
bucketName: my-config-bucket
objectKey: config/api-url.txt
provider:
name: aws
functions:
hello:
handler: handler.hello
environment:
LOGO_URL: ${sharedAccount:configBucket:config/logo-url.txt}
API_URL: ${sharedAccount:apiUrlFile}
S3 resolver settings
A nested resolver with type: s3 under an AWS resolver accepts these keys:
| Key | Type | Default | Description |
|---|---|---|---|
type | String | Required | s3. |
bucketName | String | None | Bucket to read from. The variable's address is then the object key. |
objectKey | String | None | Object to read. Requires bucketName; the variable then needs no address. |
region | String | The parent AWS resolver's Region | Region for the first request. Applies only when the parent AWS resolver doesn't set region; requests follow Amazon S3's redirect to the bucket's Region either way. |
serverSideEncryption | String | None | Server-side encryption for objects the Framework writes through the resolver when it is the Compose state store: AES256, aws:kms or aws:kms:dsse. Reading variables doesn't use it. |
Encrypt state written through an S3 resolver
When an S3 resolver is the Compose state store and the bucket policy requires an encryption header on uploads, set serverSideEncryption to the algorithm the policy expects. The Framework then sends it as the x-amz-server-side-encryption header when it writes state objects. Reads use the bucket's default encryption and need no setting.
The following bucket policy denies uploads without AES256:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EnforceEncryptionMethod",
"Effect": "Deny",
"Principal": "*",
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::my-state-bucket/*",
"Condition": {
"StringNotEquals": {
"s3:x-amz-server-side-encryption": ["AES256"]
}
}
}
]
}
Without serverSideEncryption, writing state to this bucket stops with an error like:
AccessDenied: User: ... is not authorized to perform: s3:PutObject on resource: "arn:aws:s3:::my-state-bucket/..." with an explicit deny in a resource-based policy
The following serverless-compose.yml writes state with AES256:
# serverless-compose.yml
state: stateBucket
stages:
default:
resolvers:
myAccount:
type: aws
stateBucket:
type: s3
bucketName: my-state-bucket
serverSideEncryption: AES256
services:
service-a:
path: service-a
Related
- AWS variables and resolvers: the account ID, Region and partition, and AWS resolver settings.
- Variables in serverless.yml: syntax, defaults and the other variable sources.
- Compose state: where Compose stores service state.