localstack-deploy

基础设施即代码部署

使用 Terraform、AWS CDK、CloudFormation、SAM 和 Pulumi 等热门 IaC 工具，将 AWS 基础设施部署到 LocalStack。

功能

• 将 Terraform 配置部署到 LocalStack
• 在本地运行 AWS CDK 部署
• 部署 CloudFormation 堆栈
• 构建并部署 AWS SAM 应用程序
• 针对 LocalStack 执行 Pulumi 程序
• 在部署前验证基础设施

前提条件

• 已安装 lstk CLI，且模拟器正在运行（lstk start）——请参阅 localstack 技能
• 底层工具位于 PATH 中：terraform、cdk、sam 或 aws。lstk 会代理这些工具，但不会将它们打包在内。

lstk 取代了旧版 awslocal / tflocal / cdklocal / samlocal 包装器——你不再需要通过 pip install / npm install 安装它们。Pulumi 是个例外；请参阅 Pulumi。

Terraform

使用 lstk terraform（推荐）

lstk terraform（别名 lstk tf）通过生成提供程序覆盖文件来针对 LocalStack 运行 Terraform，因此你的 .tf 文件无需进行 LocalStack 专用修改。

lstk terraform init
lstk terraform plan
lstk terraform apply -auto-approve
lstk terraform destroy -auto-approve

# Short alias
lstk tf apply -auto-approve

lstk 专用标志需放在 Terraform 子命令之前：

lstk terraform --region us-west-2 plan
lstk terraform --account 000000000000 apply

标志	默认值	说明
--region <region>	us-east-1	回退到 AWS_REGION
--account <id>	test	12 位数字；回退到 AWS_ACCESS_KEY_ID

常用环境变量：AWS_ENDPOINT_URL、LSTK_TF_CMD（二进制名称，默认为 terraform）、LSTK_TF_OVERRIDE_FILE_NAME（默认为 localstack_providers_override.tf）、LSTK_TF_DRY_RUN。

lstk terraform 仅针对 AWS 模拟器。

手动配置提供程序（备用方案）

仅在无法使用 lstk 时使用手动配置提供程序（例如，CI 镜像中仅安装了 terraform）。此方法需要修改你的 Terraform 文件：

# In your provider configuration:
provider "aws" {
  access_key                  = "test"
  secret_key                  = "test"
  region                      = "us-east-1"

  endpoints {
    s3       = "http://localhost:4566"
    dynamodb = "http://localhost:4566"
    lambda   = "http://localhost:4566"
    # Add other services as needed
  }

  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true
}

注意：使用手动配置时，必须列出配置中使用的每项 AWS 服务的端点。

AWS CDK

需要 AWS CDK CLI 2.177.0 或更高版本。

# Bootstrap (first time only)
lstk cdk bootstrap

# Deploy all stacks
lstk cdk deploy --all --require-approval never

# Deploy a specific stack
lstk cdk deploy MyStack

# Synthesize
lstk cdk synth

# Destroy
lstk cdk destroy --all --force

lstk cdk 接受放在 CDK 命令之前的 --region <region>（默认为 us-east-1）。没有 --account 标志——CDK 始终针对默认账户 000000000000。

常用环境变量：AWS_ENDPOINT_URL、AWS_ENDPOINT_URL_S3、LSTK_CDK_CMD（默认为 cdk）、AWS_REGION。

CloudFormation

使用 lstk aws，它会代理主机上的 aws CLI，并预先配置端点、凭证和区域。

# Create stack
lstk aws cloudformation create-stack \
  --stack-name my-stack \
  --template-body file://template.yaml

# Update stack
lstk aws cloudformation update-stack \
  --stack-name my-stack \
  --template-body file://template.yaml

# Delete stack
lstk aws cloudformation delete-stack --stack-name my-stack

# Describe stack
lstk aws cloudformation describe-stacks --stack-name my-stack

如果你更愿意使用原生 aws CLI，可运行一次 lstk setup aws，将 localstack 配置写入 ~/.aws/config 和 ~/.aws/credentials，然后使用 aws --profile localstack ...。

AWS SAM

需要 AWS SAM CLI 1.95.0 或更高版本。

lstk sam build
lstk sam validate
lstk sam deploy
lstk sam --region us-west-2 deploy

lstk sam 接受放在 SAM 命令之前的 --region <region>（默认为 us-east-1）和 --account <id>（默认为 000000000000）。

限制： lstk sam 不支持基于镜像/容器的 Lambda（ECR）部署和嵌套 CloudFormation 堆栈。对于这些工作流，请安装 samlocal 包装器（pip install aws-sam-cli-local）并使用它。

Pulumi

lstk 没有 Pulumi 代理命令，因此 Pulumi 仍需使用 pulumilocal 包装器。

使用 pulumilocal（推荐）

# Requires Python/pip — this is an extra install beyond lstk
pip install pulumi-local

# Use pulumilocal instead of pulumi - no config changes needed
pulumilocal preview
pulumilocal up --yes
pulumilocal destroy --yes

手动配置（备用方案）

仅在无法安装 pulumilocal 时使用手动配置（例如，环境中没有 Python/pip）：

# Configure Pulumi for LocalStack
pulumi config set aws:accessKey test
pulumi config set aws:secretKey test
pulumi config set aws:region us-east-1
pulumi config set aws:endpoints '[{"s3":"http://localhost:4566"}]'

# Deploy with standard pulumi commands
pulumi preview
pulumi up --yes
pulumi destroy --yes

端点解析

lstk aws、lstk terraform、lstk cdk 和 lstk sam 会探测 localhost.localstack.cloud 是否解析到 127.0.0.1，若是则使用该地址；否则回退到 127.0.0.1:4566。可使用 LOCALSTACK_HOST 环境变量覆盖此设置。

最佳实践

• 使用 lstk 代理命令（lstk terraform、lstk cdk、lstk sam、lstk aws），而不要将端点编辑到 IaC 文件中
• 在部署到 AWS 之前，先在本地测试基础设施变更
• 使用 lstk start --persist，以便在 LocalStack 重启后保留状态
• 使用 lstk save 对已部署的基础设施创建快照，以便立即恢复，而不必重新部署 — 请参阅 localstack-state 技能
• 在 CI 中，为 lstk 命令添加 --non-interactive，并设置 LOCALSTACK_AUTH_TOKEN