[ aws . cloudformation ]

package

Description

Packages the local artifacts (local paths) that your AWS CloudFormation template references. The command uploads local artifacts, such as source code for an AWS Lambda function or a Swagger file for an AWS API Gateway REST API, to an S3 bucket. The command returns a copy of your template, replacing references to local artifacts with the S3 location where the command uploaded the artifacts.

Use this command to quickly upload local artifacts that might be required by your template. After you package your template’s artifacts, run the deploy command to deploy the returned template.

This command can upload local artifacts referenced in the following places:

• BodyS3Location property for the AWS::ApiGateway::RestApi resource

• Code property for the AWS::Lambda::Function resource

• CodeUri property for the AWS::Serverless::Function resource

• DefinitionS3Location property for the AWS::AppSync::GraphQLSchema resource

• RequestMappingTemplateS3Location property for the AWS::AppSync::Resolver resource

• ResponseMappingTemplateS3Location property for the AWS::AppSync::Resolver resource

• DefinitionUri property for the AWS::Serverless::Api resource

• Location parameter for the AWS::Include transform

• SourceBundle property for the AWS::ElasticBeanstalk::ApplicationVersion resource

• TemplateURL property for the AWS::CloudFormation::Stack resource

• Command.ScriptLocation property for the AWS::Glue::Job resource

• DefinitionS3Location property for the AWS::StepFunctions::StateMachine resource

To specify a local artifact in your template, specify a path to a local file or folder, as either an absolute or relative path. The relative path is a location that is relative to your template’s location.

For example, if your AWS Lambda function source code is in the /home/user/code/lambdafunction/ folder, specify CodeUri: /home/user/code/lambdafunction for the AWS::Serverless::Function resource. The command returns a template and replaces the local path with the S3 location: CodeUri: s3://mybucket/lambdafunction.zip.

If you specify a file, the command directly uploads it to the S3 bucket. If you specify a folder, the command zips the folder and then uploads the .zip file. For most resources, if you don’t specify a path, the command zips and uploads the current working directory. The exception is AWS::ApiGateway::RestApi; if you don’t specify a BodyS3Location, this command will not upload an artifact to S3.

Before the command uploads artifacts, it checks if the artifacts are already present in the S3 bucket to prevent unnecessary uploads. The command uses MD5 checksums to compare files. If the values match, the command doesn’t upload the artifacts. Use the --force-upload flag to skip this check and always upload the artifacts.

See ‘aws help’ for descriptions of global parameters.

Synopsis

  package
--template-file <value>
--s3-bucket <value>
[--s3-prefix <value>]
[--kms-key-id <value>]
[--output-template-file <value>]
[--use-json]
[--force-upload]
[--metadata <value>]

Options

--template-file (string) The path where your AWS CloudFormation template is located.

--s3-bucket (string) The name of the S3 bucket where this command uploads the artifacts that are referenced in your template.

--s3-prefix (string) A prefix name that the command adds to the artifacts’ name when it uploads them to the S3 bucket. The prefix name is a path name (folder name) for the S3 bucket.

--kms-key-id (string) The ID of an AWS KMS key that the command uses to encrypt artifacts that are at rest in the S3 bucket.

--output-template-file (string) The path to the file where the command writes the output AWS CloudFormation template. If you don’t specify a path, the command writes the template to the standard output.

--use-json (boolean) Indicates whether to use JSON as the format for the output AWS CloudFormation template. YAML is used by default.

--force-upload (boolean) Indicates whether to override existing files in the S3 bucket. Specify this flag to upload artifacts even if they match existing artifacts in the S3 bucket.

--metadata (map) A map of metadata to attach to ALL the artifacts that are referenced in your template.key -> (string)

value -> (string)

Shorthand Syntax:

KeyName1=string,KeyName2=string

JSON Syntax:

{"string": "string"
  ...}

See ‘aws help’ for descriptions of global parameters.

Examples

Following command exports a template named template.json by uploading local artifacts to S3 bucket bucket-name and writes the exported template to packaged-template.json:

aws cloudformation package --template-file /path_to_template/template.json --s3-bucket bucket-name --output-template-file packaged-template.json