• Documentation
  • Pricing
© 2026 Serverless, Inc. All rights reserved.

Framework

  • Overview
  • Documentation
  • Plugins360
  • Pricing

Learn

  • Blog
  • GuidesUpdated
  • Examples240
  • Courses

Resources

  • Support
  • Security
  • Trust Center
  • Status

Community

  • Slack
  • GitHub47k
  • Forum
  • Meetups

Company

  • About
  • Careers
  • Contact
  • Partners

Legal

  • Terms of Service
  • Privacy Policy
  • Trademark
  • DMCA
Serverless Framework Logo

Serverless Framework

Intro
SetupUpgrading To V4ConceptsTutorialAWS CredentialsLicense Keys
DeployingPackagingBuildingTestingDev ModeServicesFunctions
OverviewHTTP (API Gateway v2)REST (API Gateway v1)ActiveMQApplication Load BalancerAlexa SkillAlexa Smart HomeCloudWatch EventCloudWatch LogCloudFrontCognito User PoolEventBridge EventIoTIoT Fleet ProvisioningKafkaKinesis & DynamoDBMSKRabbitMQS3ScheduleSNSSQSWebsocket
LayersManaged InstancesWeb Apps (Lambda Web Functions)Sandboxes (Lambda MicroVMs)MCP ServersAlertsVersion PruningDomainsIAM Function PermissionsParameters
OverviewSelf-reference serverless.ymlServerless CoreEnvironment VariablesCLI OptionsExternal YAML/JSON FilesJavascript propertiesGitDoppler
OverviewS3 ObjectsSSM Parameter Store & Secrets ManagerCloudFormation Stack Outputs
OverviewVaultTerraform State Output
ResourcesComposing ServicesDeployment BucketStateAgent SkillsPython support
OverviewRuntimeGatewayMemoryBrowserCode InterpreterDev Mode
API Gateway Proxy
OverviewGeneral ConfigurationAuthenticationAPI KeysData SourcesResolversPipeline FunctionsSubstitutionsCachingDelta SyncCustom DomainWAFCLI Commands
Deploying SAM/CFN TemplatesWorkflow Tips
OverviewCreating PluginsCLI OutputCustom CommandsCustom VariablesExtending the Configuration schemaExtending and overriding configuration
OverviewDashboardAxiom
Overviewagent docsagent inspectagent setupagent skills installagent skills list / readdeploydeploy functiondeploy listdevdiffinfoinvokeinvoke localloginlogin awslogin aws ssologsmetricspackageplugin installplugin uninstallprintprunereconcileremoverollbackrollback functionusage
OverviewConcepts
OverviewMetricsTracesTroubleshoot
OverviewNode.jsPython
OutputsProviders
OverviewBranch DeploymentsPreview DeploymentsCustom ScriptsTestingPrivate PackagesNotificationsMono ReposDeploy in your own CI/CDBest PracticesTroubleshootingFAQ
OverviewSetupToolsAWS Integration
Serverless.yml Reference
Examples and TutorialsConfiguration Validation
  1. Usage
  2. Variables
  3. AWS
  4. S3 Objects

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 with type: s3 that 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 the aws partition (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:

KeyTypeDefaultDescription
typeStringRequireds3.
bucketNameStringNoneBucket to read from. The variable's address is then the object key.
objectKeyStringNoneObject to read. Requires bucketName; the variable then needs no address.
regionStringThe parent AWS resolver's RegionRegion 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.
serverSideEncryptionStringNoneServer-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.
Edit this page
Prev OverviewNextSSM Parameter Store & Secrets Manager

Contents

  • S3 Object Variables
  • Syntax of the s3 variable
  • Permissions for s3 variables
  • Read objects with another account or profile
  • Set the bucket and key in a resolver
  • S3 resolver settings
  • Encrypt state written through an S3 resolver
  • Related

Related

GuidesPluginsExamplesSlack CommunitySupport