使用 AWS CDK(Python)搭建 CodePipeline 流水线:CodeBuild 构建 Docker 镜像并推送至 ECR

原创2026-10-14 13:48:451,844 阅读

使用 AWS CDK(Python)搭建 CodePipeline 流水线:CodeBuild 构建 Docker 镜像并推送至 ECR

本篇技术指南以 aws-cdk-examples 仓库中的 python/codepipeline-docker-build 示例为核心,完整讲解如何用 AWS CDK(Python)将 S3、CodeBuild、ECR 与 CodePipeline 组装成一条"上传源码压缩包 → 自动构建 Docker 镜像 → 推送 ECR"的持续交付流水线。你将掌握多 Stack 架构下的资源编排、跨 Stack 对象传递、用 Parameter Store 保存运行时参数,以及用 push.sh 一键触发流水线的完整实战方案。

示例核心设计一览

该示例的官方 ReadMe.md 给出了五个核心设计要点,它们决定了整个示例的骨架:

  1. 这是一个使用 CodeBuild 构建 Docker 镜像并推送到 ECR 的 CodePipeline 项目;
  2. 示例采用多个 Stack 拆分资源,专门用于演示如何在不同 Stack 之间传递对象;
  3. push.sh 通过 S3 上传 来触发流水线;
  4. 使用 Parameter Store(SSM 参数) 保存流水线名称与 S3 桶名称,供 push.sh 稍后读取;
  5. Parameter Store 可以替换为 CloudFormation Outputs 或 Exports 方案。

下文将逐一展开这些要点,并结合仓库源码给出可验证的实现细节。

目录结构与运行前置条件

示例目录内的文件职责划分如下:

文件 职责
app.py CDK 应用入口,负责创建两个 Stack 并建立依赖关系
Base.py 基础资源栈:S3 桶、ECR 仓库、CodeBuild 项目
Pipeline.py 流水线栈:CodePipeline 的 Source / Build 两阶段
push.sh 打包源码并上传 S3,触发流水线执行
pipeline_delivery/docker_build_buildspec.yml CodeBuild 的构建规范:登录 ECR、构建并推送镜像
pipeline_delivery/Dockerfile 被构建的示例镜像:基于 python:3.7.2-alpine 并安装 awscli
cdk.json 指定应用入口为 python3 app.py
requirements.txt 依赖声明:aws-cdk-lib>=2.262.0,<3.0.0 与 constructs>=10.5.0,<11.0.0

从 requirements.txt 可以看出,本示例基于 CDK v2(aws-cdk-lib)编写。运行前需准备 Python 3 环境并安装依赖,同时配置好 AWS 凭证与目标区域(push.sh 中默认使用 us-east-1)。

双 Stack 架构:资源栈与流水线栈的拆分

示例通过 app.py 完成编排,入口代码非常精简:

from aws_cdk import App

from Base import Base
from Pipeline import Pipeline

props = {'namespace': 'cdk-example-pipeline'}
app = App()

# stack for ecr, bucket, codebuild
base = Base(app, f"{props['namespace']}-base", props)

# pipeline stack
pipeline = Pipeline(app, f"{props['namespace']}-pipeline", base.outputs)
pipeline.add_dependency(base)
app.synth()

关键设计点:

  • 通过一个 props 字典({'namespace': 'cdk-example-pipeline'})统一定义命名空间,后续所有资源名称都以它为前缀,避免命名冲突并保持可读性;
  • 先创建 cdk-example-pipeline-base 栈,再创建 cdk-example-pipeline-pipeline 栈;
  • Pipeline 栈接收 base.outputs 作为构造参数,这是本示例演示"跨 Stack 传递对象"的核心机制(详见后文);
  • 显式调用 pipeline.add_dependency(base),确保部署时资源栈先于流水线栈创建。

Base 栈:S3 源桶、ECR 仓库与 CodeBuild 项目

Base.py 中 Base 栈负责创建三类基础资源。

1. 版本化的 S3 源桶

bucket = aws_s3.Bucket(
    self, "SourceBucket",
    bucket_name=f"{props['namespace'].lower()}-{Aws.ACCOUNT_ID}",
    versioned=True,
    removal_policy=RemovalPolicy.DESTROY)

源码注释明确指出 "pipeline requires versioned bucket":CodePipeline 的源工件桶必须开启版本控制,否则流水线无法正常工作。桶名由 namespace(小写)与 AWS 账户 ID 拼接而成,全局唯一;RemovalPolicy.DESTROY 表示删除 Stack 时一并销毁该桶(仅适用于演示场景,生产环境需谨慎)。

2. ECR 镜像仓库

ecr = aws_ecr.Repository(
    self, "ECR",
    repository_name=f"{props['namespace']}",
    removal_policy=RemovalPolicy.DESTROY
)

ECR 仓库用于接收 CodeBuild 推送的 Docker 镜像,仓库名与命名空间保持一致。

3. CodeBuild 构建项目

cb_docker_build = aws_codebuild.PipelineProject(
    self, "DockerBuild",
    project_name=f"{props['namespace']}-Docker-Build",
    build_spec=aws_codebuild.BuildSpec.from_source_filename(
        filename='pipeline_delivery/docker_build_buildspec.yml'),
    environment=aws_codebuild.BuildEnvironment(
        privileged=True,
    ),
    # pass the ecr repo uri into the codebuild project so codebuild knows where to push
    environment_variables={
        'ecr': aws_codebuild.BuildEnvironmentVariable(
            value=ecr.repository_uri),
        'tag': aws_codebuild.BuildEnvironmentVariable(
            value='cdk')
    },
    description='Pipeline for CodeBuild',
    timeout=Duration.minutes(60),
)

这里有几个值得注意的配置含义:

  • 使用 PipelineProject 而非普通 Project,因为它要在 CodePipeline 内作为流水线动作运行;
  • privileged=True 是 Docker 构建的前提:CodeBuild 构建 Docker 镜像需要 Docker daemon,必须开启特权模式,这是本示例能够"在 CodeBuild 里 build Docker 镜像"的关键;
  • 构建规范通过 BuildSpec.from_source_filename 直接引用仓库内的 pipeline_delivery/docker_build_buildspec.yml;
  • 通过 environment_variables 把 ECR 仓库 URI(ecr)与镜像标签(tag=cdk) 注入构建环境,CodeBuild 因此知道镜像要推送到哪里、打什么标签;
  • 超时上限设置为 60 分钟,避免 Docker 镜像构建长时间挂起。

4. IAM 权限授予

bucket.grant_read_write(cb_docker_build)
ecr.grant_pull_push(cb_docker_build)

Base 栈最后为 CodeBuild 授予了 S3 桶读写与 ECR 拉取/推送权限,并通过 CfnOutput 输出 ECR URI 与 S3 桶名供控制台查看。

Pipeline 栈:两阶段 CodePipeline

Pipeline.py 中 Pipeline 栈创建了一条包含 Source 与 Build 两个阶段的流水线:

source_output = aws_codepipeline.Artifact(artifact_name='source')

pipeline = aws_codepipeline.Pipeline(
    self, "Pipeline",
    pipeline_name=f"{props['namespace']}",
    artifact_bucket=props['bucket'],
    stages=[
        aws_codepipeline.StageProps(
            stage_name='Source',
            actions=[
                aws_codepipeline_actions.S3SourceAction(
                    bucket=props['bucket'],
                    bucket_key='source.zip',
                    action_name='S3Source',
                    run_order=1,
                    output=source_output,
                    trigger=aws_codepipeline_actions.S3Trigger.POLL
                ),
            ]
        ),
        aws_codepipeline.StageProps(
            stage_name='Build',
            actions=[
                aws_codepipeline_actions.CodeBuildAction(
                    action_name='DockerBuildImages',
                    input=source_output,
                    project=props['cb_docker_build'],
                    run_order=1,
                )
            ]
        )
    ]
)

流水线细节:

  • Source 阶段:S3SourceAction 监听源桶中的 source.zip 对象。trigger=aws_codepipeline_actions.S3Trigger.POLL 表示 CodePipeline 会轮询 S3 桶,一旦检测到 source.zip 发生变化(新版本上传)即自动开始执行流水线——这正是 push.sh"通过 S3 上传触发流水线"的原理;
  • Build 阶段:CodeBuildAction 将 Source 阶段的工件(source_output)交给 Base 栈创建的 CodeBuild 项目执行 Docker 构建与推送;
  • artifact_bucket=props['bucket'] 把 Base 栈的 S3 桶作为流水线的工件桶(再次体现跨 Stack 传参);
  • 最后执行 props['bucket'].grant_read_write(pipeline.role),为流水线角色授予读写桶的权限。

跨 Stack 对象传递:props 字典与 outputs 属性

本示例的核心教学点之一,就是"如何在多个 Stack 之间传递对象"。其机制在 Base.py 末尾:

self.output_props = props.copy()
self.output_props['bucket'] = bucket
self.output_props['cb_docker_build'] = cb_docker_build

# pass objects to another stack
@property
def outputs(self):
    return self.output_props

实现原理可以总结为三步:

  1. Base 栈构造时接收外部传入的 props 字典,并在构造过程中把新创建的 CDK 对象(bucket、cb_docker_build)塞回这个字典;
  2. 通过 @property outputs 暴露该字典,供外部读取;
  3. app.py 将 base.outputs 作为 props 传给 Pipeline 栈构造函数,Pipeline 内部便可以直接以 props['bucket']、props['cb_docker_build'] 的方式引用这些资源对象。

这种方式与把资源 ARN 写进 CfnOutput 再用 Fn.importValue 拉取的传统跨栈引用不同:它传递的是构造(construct)对象本身,Pipeline 栈可以直接对桶调用 grant_read_write、直接把 CodeBuild 项目作为动作输入,代码更直观、类型更安全。作为配合,add_dependency 保证了依赖栈先部署,避免对象在合成/部署阶段的顺序问题。

参数存储:Parameter Store 与 CloudFormation Outputs / Exports 的取舍

ReadMe 明确指出:"Parameter Store is used to store the value of the Pipeline and S3 Bucket so it can be retrieved later in push.sh"、"Parameter Store can be replaced with CloudFormation Outputs or Exports"。

在 Base 栈中:

bucket_param = aws_ssm.StringParameter(
    self, "ParameterB",
    parameter_name=f"{props['namespace']}-bucket",
    string_value=bucket.bucket_name,
    description='cdk pipeline bucket'
)

在 Pipeline 栈中:

pipeline_param = aws_ssm.StringParameter(
    self, "PipelineParam",
    parameter_name=f"{props['namespace']}-pipeline",
    string_value=pipeline.pipeline_name,
    description='cdk pipeline bucket'
)

两个 SSM 参数名称分别为 cdk-example-pipeline-bucket 与 cdk-example-pipeline-pipeline,保存了"桶名"与"流水线名"这两个 push.sh 运行时必需的取值。

与此同时,两个栈也都通过 CfnOutput 输出了关键信息(Base 输出 ECR URI 与 S3 桶名,Pipeline 输出流水线名)。这印证了 ReadMe 中"可替换"的说法:如果不想依赖 SSM,可以把这些 CfnOutput 升级为 CloudFormation Exports(导出),然后在 push.sh 或其它栈中通过 Fn.importValue 读取。两种方案的对比:

  • Parameter Store 方案:push.sh 通过 aws ssm get-parameter 直接取值,无需跨 Stack 的 CloudFormation 依赖解析,适合脚本快速读取;
  • Outputs / Exports 方案:把值沉淀为 CloudFormation 层面的标准输出,适合与其它 CloudFormation 资源或 Stack 联动,但取值要经过 CloudFormation 的导入导出机制。

push.sh:用 S3 上传触发流水线

push.sh 完整代码如下:

#!/usr/bin/env bash

export account_id=$(aws sts get-caller-identity | jq -r .Account)
export source_bucket=$(aws ssm get-parameter --name 'cdk-example-pipeline-bucket' | jq -r .Parameter.Value)
export pipeline_name=$(aws ssm get-parameter --name 'cdk-example-pipeline-pipeline' | jq -r .Parameter.Value)
export REGION='us-east-1'

zip -r source.zip .
aws s3 cp source.zip s3://${source_bucket}/source.zip
#aws codepipeline start-pipeline-execution --name ${pipeline_name}

脚本的执行逻辑分为三步:

  1. 读取运行时参数:通过 aws sts get-caller-identity 获取当前账户 ID,通过两条 aws ssm get-parameter 从 Parameter Store 读取桶名与流水线名(用 jq 解析 JSON);REGION 硬编码为 us-east-1,与部署区域保持一致;
  2. 打包源码:zip -r source.zip . 将当前目录(含 Dockerfile 与 buildspec)压缩为 source.zip;
  3. 上传触发:aws s3 cp source.zip s3://${source_bucket}/source.zip 把压缩包上传到源桶。由于 Pipeline 的 S3SourceAction 使用 S3Trigger.POLL 轮询,上传即触发流水线执行。

脚本末尾还注释保留了一条备选方案 aws codepipeline start-pipeline-execution --name ${pipeline_name}:如果不想依赖 S3 轮询,也可以显式调用 start-pipeline-execution 手动启动流水线。这恰好与 Pipeline 栈中保存流水线名到 Parameter Store 的设计呼应——pipeline_name 变量的用途就在这里。

buildspec 与 Dockerfile:镜像构建与推送细节

CodeBuild 使用的构建规范 pipeline_delivery/docker_build_buildspec.yml 内容如下:

version: 0.2

phases:
  pre_build:
    commands:
      - echo logging into docker
      - $(aws ecr get-login --no-include-email --region $AWS_DEFAULT_REGION)
  build:
    commands:
      - echo Entered the post_build phase...
      - echo Build completed on `date`
      - docker build -t ${tag}:latest pipeline_delivery/
      - docker tag $tag:latest $ecr:$tag
      - docker push $ecr

各阶段作用:

  • pre_build:执行 aws ecr get-login --no-include-email --region $AWS_DEFAULT_REGION 获取并执行 ECR 的 Docker 登录命令,使本地 Docker 具备推送凭证;
  • build:先用 docker build -t ${tag}:latest pipeline_delivery/ 基于 pipeline_delivery/ 目录中的 Dockerfile 构建镜像(标签 tag=cdk 来自 Base 栈注入的环境变量);再通过 docker tag 将镜像重新标记为 ECR 仓库 URI 形式($ecr:$tag);最后 docker push $ecr 推送到 ECR。

示例使用的 Dockerfile 非常轻量:

FROM python:3.7.2-alpine
RUN pip install awscli

它仅用于演示"构建一个可推送的镜像"这一过程,实际项目中可替换为任意真实业务镜像。整个流程体现了"CodeBuild 特权模式 + ECR 登录 + docker push"这一标准的 ECR 推送链路。

从部署到运行的完整流程

综合以上各文件,该示例的端到端使用流程为:

  1. 安装依赖:按 requirements.txt 安装 aws-cdk-lib(CDK v2)与 constructs;
  2. 部署 Stack:执行 cdk deploy cdk-example-pipeline-base 部署资源栈(S3 桶、ECR、CodeBuild),再执行 cdk deploy cdk-example-pipeline-pipeline 部署流水线栈;由于 add_dependency 的存在,也可使用 cdk deploy --all 一次性按依赖顺序部署。部署完成后,SSM 参数 cdk-example-pipeline-bucket、cdk-example-pipeline-pipeline 以及 CloudFormation Outputs(ECR URI、S3 桶名、流水线名)即已就绪;
  3. 触发流水线:在包含 pipeline_delivery/ 目录的项目根目录执行 ./push.sh,脚本打包 source.zip 并上传到源桶;
  4. 等待构建:CodePipeline 轮询到新的 source.zip 后自动执行 Source → Build 两阶段,CodeBuild 完成 Docker 镜像构建并推送到 ECR;
  5. 验证结果:在 CodePipeline 控制台观察执行状态,或在 ECR 仓库中查看新推送的镜像(标签为 cdk)。

需要注意的是,push.sh 中硬编码的区域(us-east-1)与 SSM 参数名应与实际部署保持一致;同时 ECR 镜像推送依赖 Base 栈授予的 ecr.grant_pull_push 权限,删除或修改权限配置会导致 Build 阶段失败。

小结

本示例用最精简的两栈结构,完整覆盖了 AWS 持续交付链路中的核心环节:版本化 S3 桶承载源码工件、CodeBuild 特权模式构建 Docker 镜像、ECR 收纳镜像产物、CodePipeline 轮询触发编排,并额外示范了两种值得在生产中复用的工程实践——通过 props 字典 + outputs 属性在 Stack 间传递构造对象,以及通过 Parameter Store(或 CloudFormation Outputs / Exports)沉淀运行时参数供外部脚本读取。无论你是刚开始接触 CDK 流水线,还是需要为现有项目设计 CI/CD 骨架,都可以直接参照 python/codepipeline-docker-build 目录下的源码落地一套可运行的 Docker 交付流水线。

登录后查看全文
aws-cdk-examples