AWS 代码构建库

AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.

关于如何移徙的更多信息,请参见: 移动到 AWS CDK v2 指南。 。 。 .

AWS 代码构建是一个完全管理的持续集成服务,可以编译 源代码,运行测试,并生成准备使用的软件包 部署。 用代码构建, 您不需要提供、 管理和缩放 建立服务器。 连续构建代码并处理多个构建 同时, 您的建筑不会排队等待 。 你可以来 通过使用预包装的构建环境快速启动, 或者您可以创建 自定义构建使用您自己的构建工具的环境。 用代码构建,你是 按分钟计费的计算资源.

安装

安装模块 :

$ npm i @aws-cdk/aws-codebuild

导入到您的代码 :

import * as codebuild from '@aws-cdk/aws-codebuild';

这个 codebuild.Project 建筑是建设项目的资源。 见 初始化属性综合清单参考文件, 方法和属性.

来源

构建项目通常与 来源,通过 页:1 source 属性,该属性接受扩展的类 Source 抽象基础课. 默认与建设项目无关; 页:1 buildSpec 在这种情况下需要选项.

这里有一个代码构建项目,没有简单的打印源 Hello, CodeBuild!数字 :

最小示例

CodeCommitSource

使用 AWS 代码承诺寄存器作为此构建的来源 :

import * as codecommit from '@aws-cdk/aws-codecommit';

const repository = new codecommit.Repository(this, 'MyRepo', { repositoryName: 'foo' });
new codebuild.Project(this, 'MyFirstCodeCommitProject', {
  source: codebuild.Source.codeCommit({ repository }),
});

S3Source

创建以 S3 桶为源代码构建项目 :

const bucket = new s3.Bucket(this, 'MyBucket');

new codebuild.Project(this, 'MyProject', {
  source: codebuild.Source.s3({
    bucket: bucket,
    path: 'path/to/file.zip',
  }),
});

代码构建角色将被赋予仅读取给定的路径 bucket。 。 。 .

GitHubSource 财务报告和审定财务报表 GitHubEnterpriseSource

这些源类型可用于从一个GitHub寄存器中构建代码. 示例

const gitHubSource = codebuild.Source.gitHub({
  owner: 'awslabs',
  repo: 'aws-cdk',
  webhook: true, // optional, default: true if `webhookFilters` were provided, false otherwise
  webhookTriggersBatchBuild: true, // optional, default is false
  webhookFilters: [
    codebuild.FilterGroup
      .inEventOf(codebuild.EventAction.PUSH)
      .andBranchIs('master')
      .andCommitMessageIs('the commit message'),
  ], // optional, by default all pushes and Pull Requests will trigger a build
});

要提供 GitHub 证书, 请先到 AWS 代码构建控制台连接 或打电话 ImportSourceCredentials 坚持你的个人进入标志. 示例

aws codebuild import-source-credentials --server-type GITHUB --auth-type PERSONAL_ACCESS_TOKEN --token <token_value>

BitBucketSource

此源类型可用于从BitBucket寄存器中构建代码.

const bbSource = codebuild.Source.bitBucket({
  owner: 'owner',
  repo: 'repo',
});

对所有 Git 源码

对所有 Git 源码, 您可以在分块时获取子模块 .

const gitHubSource = codebuild.Source.gitHub({
  owner: 'awslabs',
  repo: 'aws-cdk',
  fetchSubmodules: true,
});

艺术品

CodeBuild Projects可以生产出Artifacts并上传到S3. 例如:

declare const bucket: s3.Bucket;

const project = new codebuild.Project(this, 'MyProject', {
  buildSpec: codebuild.BuildSpec.fromObject({
    version: '0.2',
  }),
  artifacts: codebuild.Artifacts.s3({
      bucket,
      includeBuildId: false,
      packageZip: true,
      path: 'another/path',
      identifier: 'AddArtifact1',
    }),
});

如果你更喜欢在模板中以YAML的形式渲染你的构造谱, 使用该 fromObjectToYaml() 方法代替 fromObject()。 。 。 .

因为我们没有设置 name 属性,此示例将设置 overrideArtifactName 参数,并生成一个以定义 buildspec 文件,上传到 S3 桶(bucket) (中文(简体) ). 路径是 another/path 文物将是一个拉链文件.

代码平线

为了增加一个代码构建项目作为代码平线的动作, 使用该 PipelineProject 类代替 Project。 。 。 . 很简单的课,不能说清楚 sources, (中文(简体) ), secondarySources, (中文(简体) ), artifacts 或者说 secondaryArtifacts, (中文(简体) ), 因为它们是通过设置输入和输出代码Pipeline来处理的 Artifact 实例, 而不是把它们设置在项目上.

const project = new codebuild.PipelineProject(this, 'Project', {
  // properties as above...
})

详情请见 @aws-cdk/@aws-codepipeline-actions 软件包.

缓存

您可以使用缓存来节省项目建设的时间 。 一个缓存可以存储您的构建环境的可重复使用块并跨多块构建使用. 您的构建项目可以使用亚马逊S3或本地两种类型的缓存之一. 一般来说,S3缓存对于建造比下载更昂贵的中小型建筑文物来说是一个很好的选择. 本地缓存对于大型中间建材文物来说是一个很好的选择,因为缓存在建材主机上可以立即得到.

S3 缓存

使用 S3 缓存,缓存存储在可用的 S3 桶中 无论选择什么代码构建实例来运行您的代码构建任务 继续 当使用 S3 缓存时,您还必须在 a 中添加 cache 区域 显示要缓存的文件的构建 spec :

declare const myCachingBucket: s3.Bucket;

new codebuild.Project(this, 'Project', {
  source: codebuild.Source.bitBucket({
    owner: 'awslabs',
    repo: 'aws-cdk',
  }),

  cache: codebuild.Cache.bucket(myCachingBucket),

  // BuildSpec with a 'cache' section necessary for S3 caching. This can
  // also come from 'buildspec.yml' in your source.
  buildSpec: codebuild.BuildSpec.fromObject({
    version: '0.2',
    phases: {
      build: {
        commands: ['...'],
      },
    },
    cache: {
      paths: [
        // The '**/*' is required to indicate all files in this directory
        '/root/cachedir/**/*',
      ],
    },
  }),
});

注意使用相同 S3 桶的两个不同的代码构建项目将 没有 共享他们的缓存: 每个工程都会在 S3 桶中获得一个特殊文件以存储 缓存在.

本地缓存

随着本地缓存,缓存被存储在代码构建实例本身上. 这个 简单、便宜和快,但代码构建无法保证实例的再利用 无法保证缓存命中。 例如,当一个建筑开始和 本地缓存文件, 如果两个后续的构建同时开始 只有其中一座建筑会拿到缓存 三种不同的缓存模式是 ,可以单独打开.

• LocalCacheMode.SOURCE 用于一级和二级源的 Git 元数据.
• LocalCacheMode.DOCKER_LAYER 缓存已存在的 Docker 层 .
• LocalCacheMode.CUSTOM 在构建spec文件中指定的缓存目录.

new codebuild.Project(this, 'Project', {
  source: codebuild.Source.gitHubEnterprise({
    httpsCloneUrl: 'https://my-github-enterprise.com/owner/repo',
  }),

  // Enable Docker AND custom caching
  cache: codebuild.Cache.local(codebuild.LocalCacheMode.DOCKER_LAYER, codebuild.LocalCacheMode.CUSTOM),

  // BuildSpec with a 'cache' section necessary for 'CUSTOM' caching. This can
  // also come from 'buildspec.yml' in your source.
  buildSpec: codebuild.BuildSpec.fromObject({
    version: '0.2',
    phases: {
      build: {
        commands: ['...'],
      },
    },
    cache: {
      paths: [
        // The '**/*' is required to indicate all files in this directory
        '/root/cachedir/**/*',
      ],
    },
  }),
});

环境

默认情况下,项目使用一个带有Ubuntu 18.04图像的小实例. 你个 可以使用 environment 用于自定义构建环境的属性 :

• buildImage 定义所用的 Docker 图像。 见 图像 下图 详细描述如何定义构建图像.
• certificate 定义要导入的 PEM 编码证书的位置.
• computeType 定义构建所用的实例类型.
• privileged 可设定为 true 允许特权进入.
• environmentVariables 可在这一级别(也可在项目中)设置 页:1.

图像

代码构建库通过 Linux 和 Windows 图像支持 LinuxBuildImage (或 LinuxArmBuildImage),以及 WindowsBuildImage 课程.

您可以使用预定义的 Windows/ Linux 图像指定其中之一 常数,例如 WindowsBuildImage.WIN_SERVER_CORE_2019_BASE, (中文(简体) ), WindowsBuildImage.WINDOWS_BASE_2_0, (中文(简体) ), LinuxBuildImage.STANDARD_2_0,或 LinuxArmBuildImage.AMAZON_LINUX_2_ARM。 。 。 .

或者,您可以使用其中一种静态方法指定自定义图像 LinuxBuildImage数字 :

• LinuxBuildImage.fromDockerRegistry(image[, { secretsManagerCredentials }]) 在任何公共或私营多克登记册中引用图像.
• LinuxBuildImage.fromEcrRepository(repo[, tag]) 引用一个可用图像 ECR仓库.
• LinuxBuildImage.fromAsset(parent, id, props) 来使用从 当地资产.
• LinuxBuildImage.fromCodeBuildImageId(id) 来引用一个预定义的, CodeBuild 提供的多克图像.

或一种相应的方法 WindowsBuildImage数字 :

• WindowsBuildImage.fromDockerRegistry(image[, { secretsManagerCredentials }, imageType])
• WindowsBuildImage.fromEcrRepository(repo[, tag, imageType])
• WindowsBuildImage.fromAsset(parent, id, props, [, imageType])

或一种相应的方法 LinuxArmBuildImage数字 :

• LinuxArmBuildImage.fromEcrRepository(repo[, tag])

注意 WindowsBuildImage 静态方法的版本接受类型中的可选参数 WindowsImageType, (中文(简体) ), 也可以这样 WindowsImageType.STANDARD,默认值,或 WindowsImageType.SERVER_2019数字 :

declare const ecrRepository: ecr.Repository;

new codebuild.Project(this, 'Project', {
  environment: {
    buildImage: codebuild.WindowsBuildImage.fromEcrRepository(ecrRepository, 'v1.0', codebuild.WindowsImageType.SERVER_2019),
    // optional certificate to include in the build image
    certificate: {
      bucket: s3.Bucket.fromBucketName(this, 'Bucket', 'my-bucket'),
      objectKey: 'path/to/cert.pem',
    },
  },
  // ...
})

以下示例显示如何从 Docker 资产中定义图像 :

Docker 资产示例

以下示例说明如何从ECR寄存器中定义图像 :

ECR 实例

以下示例显示如何定义来自私人嵌入器注册的图像 :

Docker 注册示例

GPU 图像

班级 LinuxGpuBuildImage 包含用于工作的常数 AWS 深层学习容器图像数字 :

new codebuild.Project(this, 'Project', {
  environment: {
    buildImage: codebuild.LinuxGpuBuildImage.DLC_TENSORFLOW_2_1_0_INFERENCE,
  },
  // ...
})

一个复杂情况是,DLC图像的存储器在 不同AWS区域的不同账户. 在大多数情况下,CDK负责为您提供正确的账户; (例如部署到新地区) 我们的信息可能已经过时, 您总是可以指定账户 (与寄存器名称和标签并列) 明确使用 awsDeepLearningContainersImage 方法 :

new codebuild.Project(this, 'Project', {
  environment: {
    buildImage: codebuild.LinuxGpuBuildImage.awsDeepLearningContainersImage(
      'tensorflow-inference', '2.1.0-gpu-py36-cu101-ubuntu18.04', '123456789012'),
  },
  // ...
})

或者,您可以使用 LinuxGpuBuildImage.fromEcrRepository(repo[, tag]) 方法.

日志

CodeBuild 允许您指定一个 S3 Bucket, Cloud Watch 日志组, 或者两者兼收您的项目日志 .

默认情况下,日志会去云表.

云表日志示例

new codebuild.Project(this, 'Project', {
  logging: {
    cloudWatch: {
      logGroup: new logs.LogGroup(this, `MyLogGroup`),
    }
  },
})

S3 日志示例

new codebuild.Project(this, 'Project', {
  logging: {
    s3: {
      bucket: new s3.Bucket(this, `LogBucket`)
    }
  },
})

全权证书

CodeBuild允许您存储用于与不同来源通信的证书, 像GitHub一样:

new codebuild.GitHubSourceCredentials(this, 'CodeBuildGitHubCreds', {
  accessToken: SecretValue.secretsManager('my-token'),
});
// GitHub Enterprise is almost the same,
// except the class is called GitHubEnterpriseSourceCredentials

键盘 :

new codebuild.BitBucketSourceCredentials(this, 'CodeBuildBitBucketCreds', {
  username: SecretValue.secretsManager('my-bitbucket-creds', { jsonField: 'username' }),
  password: SecretValue.secretsManager('my-bitbucket-creds', { jsonField: 'password' }),
});

说明: 某一区域的某一帐户的全权证书是全局的 -- 它们没有按照代码构建项目定义. 代码构建只允许存储特定类型的单一证书 (GitHub, GitHub Entertainment 或 BitBucket) (中文(简体) ) 在某一区域的某一账户中 任何试图拯救一个以上的尝试都会导致错误. 你可以用这个 list-source-credentials AWS CLI 操作 检查您账户中存储的证书.

测试报告

您可以在构建中指定测试报告 :

const project = new codebuild.Project(this, 'Project', {
  buildSpec: codebuild.BuildSpec.fromObject({
    // ...
    reports: {
      myReport: {
        files: '**/*',
        'base-directory': 'build/test-results',
      },
    },
  }),
});

这将创建一个新的测试报告小组, 名称 <ProjectName>-myReport。 。 。 .

该项目在CDK中的角色将永远被允许创建和使用报告组 从项目名称起命名; 如果你宁愿不增加这些权限, 您可以在创建工程时选择退出 :

declare const source: codebuild.Source;

const project = new codebuild.Project(this, 'Project', {
  source,
  grantReportGroupPermissions: false,
});

或者,您可以指定一个现有资源组的ARN, 而不是简单的名称, 在您的构造图中 :

declare const source: codebuild.Source;

// create a new ReportGroup
const reportGroup = new codebuild.ReportGroup(this, 'ReportGroup');

const project = new codebuild.Project(this, 'Project', {
  source,
  buildSpec: codebuild.BuildSpec.fromObject({
    // ...
    reports: {
      [reportGroup.reportGroupArn]: {
        files: '**/*',
        'base-directory': 'build/test-results',
      },
    },
  }),
});

如果你这样做,你需要授予项目的角色权限 写报告组:

declare const project: codebuild.Project;
declare const reportGroup: codebuild.ReportGroup;

reportGroup.grantWrite(project);

关于试验报告的更多信息, 见 AWS 代码构建文档。 。 。 .

活动

代码构建项目可用作事件源或被触发 通过事件规则.

将项目作为事件目标

这个 @aws-cdk/aws-events-targets.CodeBuildProject 允许使用 AWS 代码构建 作为 AWS 云表事件规则目标的项目 :

// start build when a commit is pushed
import * as codecommit from '@aws-cdk/aws-codecommit';
import * as targets from '@aws-cdk/aws-events-targets';

declare const codeCommitRepository: codecommit.Repository;
declare const project: codebuild.Project;

codeCommitRepository.onCommit('OnCommit', {
  target: new targets.CodeBuildProject(project),
});

使用工程作为事件源

要定义构建项目的亚马逊云表事件规则,请使用其中之一 onXxx 方法:

import * as targets from '@aws-cdk/aws-events-targets';
declare const fn: lambda.Function;
declare const project: codebuild.Project;

const rule = project.onStateChange('BuildStateChange', {
  target: new targets.LambdaFunction(fn)
});

代码星通知

要定义项目代码星通知规则,请使用其中之一 notifyOnXxx() 方法。 。 . 它们与 onXxx() 云表事件的方法:

import * as chatbot from '@aws-cdk/aws-chatbot';

declare const project: codebuild.Project;

const target = new chatbot.SlackChannelConfiguration(this, 'MySlackChannel', {
  slackChannelConfigurationName: 'YOUR_CHANNEL_NAME',
  slackWorkspaceId: 'YOUR_SLACK_WORKSPACE_ID',
  slackChannelId: 'YOUR_SLACK_CHANNEL_ID',
});

const rule = project.notifyOnBuildSucceeded('NotifyOnBuildSucceeded', target);

二级来源和文物

CodeBuild Projects可以从多个地方获得其来源,并生产 多种产出。 例如:

import * as codecommit from '@aws-cdk/aws-codecommit';
declare const repo: codecommit.Repository;
declare const bucket: s3.Bucket;

const project = new codebuild.Project(this, 'MyProject', {
  secondarySources: [
    codebuild.Source.codeCommit({
      identifier: 'source2',
      repository: repo,
    }),
  ],
  secondaryArtifacts: [
    codebuild.Artifacts.s3({
      identifier: 'artifact2',
      bucket: bucket,
      path: 'some/path',
      name: 'file.zip',
    }),
  ],
  // ...
});

注意 identifier 二级来源和 文物.

二级源的内容可供建筑在 指定目录 CODEBUILD_SRC_DIR_<identifier> 环境变量 (因此, CODEBUILD_SRC_DIR_source2 (见上述情况).

二级文物在建筑图中有自己的部分,在 常设经常 artifacts 一个 每个二级文物都有自己的部分,开始 他们的身份识别.

因此,上面的项目的建筑图可以看起来像这样:

const project = new codebuild.Project(this, 'MyProject', {
  // secondary sources and artifacts as above...
  buildSpec: codebuild.BuildSpec.fromObject({
    version: '0.2',
    phases: {
      build: {
        commands: [
          'cd $CODEBUILD_SRC_DIR_source2',
          'touch output2.txt',
        ],
      },
    },
    artifacts: {
      'secondary-artifacts': {
        'artifact2': {
          'base-directory': '$CODEBUILD_SRC_DIR_source2',
          'files': [
            'output2.txt',
          ],
        },
      },
    },
  }),
});

编码构建项目中的 VPC 配置定义

通常情况下,VPC中的资源无法被AWS CodeBuild访问. 启用 访问时,您必须提供额外的 VPC 配置信息,作为 代码构建工程配置的一部分。 其中包括VPC识别码 VPC子网识别码和VPC安全组识别码. 然后是VPC驱动的建筑 能够访问您的 VPC 内部的资源.

详情见 https://docs.aws.amazon.com/codebuilt/latest/userguide/vpc-support.html 页面存档备份,存于互联网档案馆

使用大小写 从 AWS 代码构建的 VPC 连接使得可以:

• 在亚马逊的RDS数据库中 进行整合测试 数据被隔离在一个私人子网上.
• 直接从测试中查询亚马逊埃拉斯蒂卡切集群中的数据.
• 与亚马逊EC2,亚马逊ECS托管的内部网络服务互动,或使用内部弹性负载平衡的服务.
• 取自自自管,内部的文物寄存器,如PyPI为Python,Maven为Java,npm为Node.js.
• 在 Amazon S3 桶中访问对象,只允许通过 Amazon VPC 端点访问 .
• 通过与您子网相关的NAT网关或NAT实例的弹性IP地址查询需要固定IP地址的外部网络服务.

您的建筑可以访问您 VPC 中托管的任何资源 .

启用 Amazon VPC 在您的代码构建工程中访问

在定义您的项目时通过 VPC, 然后确保 给予代码Build 的安全组权限 获得资源 connections 对象.

例如:

declare const loadBalancer: elbv2.ApplicationLoadBalancer;

const vpc = new ec2.Vpc(this, 'MyVPC');
const project = new codebuild.Project(this, 'MyProject', {
  vpc: vpc,
  buildSpec: codebuild.BuildSpec.fromObject({
    // ...
  }),
});

project.connections.allowTo(loadBalancer, ec2.Port.tcp(443));

项目文件系统位置 EFS

添加 CodeBuild 支持以使用 AWS EFS 文件系统挂载 新建的 FileSystemLocation 项目. 这个 fileSystemLocations 接受列表的属性 ProjectFileSystemLocation 以接口为代表 IFileSystemLocations。 。 。 . 唯一支持的文件系统类型是 EFS。 。 。 .

例如:

new codebuild.Project(this, 'MyProject', {
  buildSpec: codebuild.BuildSpec.fromObject({
    version: '0.2',
  }),
  fileSystemLocations: [
    codebuild.FileSystemLocation.efs({
      identifier: "myidentifier2",
      location: "myclodation.mydnsroot.com:/loc",
      mountPoint: "/media",
      mountOptions: "opts"
    })
  ]
});

以下是一个代码构建项目,其中有一个简单的例子,创建了一个安装在AWS EFS上的项目:

最小示例

批量构建

要启动批量建筑,请拨打 enableBatchBuilds() 在项目实例.

它返回包含已创建的批量服务角色的对象, 或者说 undefined 如果无法启用批量构建,例如如果项目是导入的.

declare const source: codebuild.Source;

const project = new codebuild.Project(this, 'MyProject', { source, });

if (project.enableBatchBuilds()) {
  console.log('Batch builds were enabled');
}

超时

在创建您的工程时可以设置两种超时 . 这个 timeout 属性可用于设定工程运行时间的上限,而无需标记为已完成. 默认为60分钟. 下面是压倒违约的例子.

new codebuild.Project(this, 'MyProject', {
  timeout: Duration.minutes(90)
});

这个 queuedTimeout 属性可用于设定您的工程队列要运行的上限. 此属性没有默认值 . 例如,允许您的工程在建设失败前排队30分钟, 使用以下代码.

new codebuild.Project(this, 'MyProject', {
  queuedTimeout: Duration.minutes(30)
});

限制货币

默认情况下,如果新建筑被触发,即使之前的建筑已经在运行中,它也会运行. 可以将最大同时建构值限制在1至账户特定最高限值之间. 默认情况下,没有明确的限制.

new codebuild.Project(this, 'MyProject', {
  concurrentBuildLimit: 1
});