AWS 代码平线构造库

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

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

管道

要构造空管道 :

// Construct an empty Pipeline
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline');

为了给管道一个人能读取的好名字:

// Give the Pipeline a nice, human-readable name
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  pipelineName: 'MyPipeline',
});

注意在默认配置中 Pipeline 构造创建 aWS 密钥管理服务( AWS KMS) 客户主密钥( CMK) 供您使用 加密文物桶中的文物,费用为: 1美元/个月。此默认配置对于允许交叉账户是必要的 行动.

如果您不打算进行交叉账户部署, 可以禁用 通过传递创建客户主密钥 crossAccountKeys: false 当定义管道时 :

// Don't create Customer Master Keys
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  crossAccountKeys: false,
});

如果您想要为生成的 KMS 密钥启用密钥旋转, 你可以通过路过来配置它 enableKeyRotation: true 当创建管道时. 注意关键轮换将产生额外费用 1美元/个月。 。 。 .

// Enable key rotation for the generated KMS key
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  // ...
  enableKeyRotation: true,
});

阶段

您可以在创建管道时提供阶段 :

// Provide a Stage when creating a pipeline
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  stages: [
    {
      stageName: 'Source',
      actions: [
        // see below...
      ],
    },
  ],
});

或将一个阶段附加到已有管道中 :

// Append a Stage to an existing Pipeline
declare const pipeline: codepipeline.Pipeline;
const sourceStage = pipeline.addStage({
  stageName: 'Source',
  actions: [ // optional property
    // see below...
  ],
});

您可以在管道的任意点插入新阶段 :

// Insert a new Stage at an arbitrary point
declare const pipeline: codepipeline.Pipeline;
declare const anotherStage: codepipeline.IStage;
declare const yetAnotherStage: codepipeline.IStage;

const someStage = pipeline.addStage({
  stageName: 'SomeStage',
  placement: {
    // note: you can only specify one of the below properties
    rightBefore: anotherStage,
    justAfter: yetAnotherStage,
  }
});

您可以禁用向阶段的过渡 :

// Disable transition to a stage
declare const pipeline: codepipeline.Pipeline;

const someStage = pipeline.addStage({
  stageName: 'SomeStage',
  transitionToEnabled: false,
  transitionDisabledReason: 'Manual transition only', // optional reason
})

如果你不想让每一次处决 都进入 这个阶段自动。 之后过渡可以"手动"后被启用.

行动

动作在一个单独的包, @aws-cdk/aws-codepipeline-actions。 。 。 .

要在阶段中添加动作,您可以在创建阶段时提供它, 输入 actions 财产, 或者你可以使用 IStage.addAction() 改变现有阶段的方法:

// Use the `IStage.addAction()` method to mutate an existing Stage.
declare const sourceStage: codepipeline.IStage;
declare const someAction: codepipeline.Action;
sourceStage.addAction(someAction);

自定义行动注册

为了让自己的自定义代码Pipeline Action需要注册动作提供者. 看着 JenkinsProvider 内 @aws-cdk/aws-codepipeline-actions 以实施为例.

// Make a custom CodePipeline Action
new codepipeline.CustomActionRegistration(this, 'GenericGitSourceProviderResource', {
  category: codepipeline.ActionCategory.SOURCE,
  artifactBounds: { minInputs: 0, maxInputs: 0, minOutputs: 1, maxOutputs: 1 },
  provider: 'GenericGitSource',
  version: '1',
  entityUrl: 'https://docs.aws.amazon.com/codepipeline/latest/userguide/actions-create-custom-action.html',
  executionUrl: 'https://docs.aws.amazon.com/codepipeline/latest/userguide/actions-create-custom-action.html',
  actionProperties: [
    {
      name: 'Branch',
      required: true,
      key: false,
      secret: false,
      queryable: false,
      description: 'Git branch to pull',
      type: 'String',
    },
    {
      name: 'GitUrl',
      required: true,
      key: false,
      secret: false,
      queryable: false,
      description: 'SSH git clone URL',
      type: 'String',
    },
  ],
});

交叉账户代码

跨账户管道行动要求管道具备 没有 已经 创建于 crossAccountKeys: false。 。 。 .

大多数管道动作接受 AWS 资源对象运行. 例如:

• S3DeployAction 接受一个 s3.IBucket。 。 。 .
• CodeBuildAction 接受一个 codebuild.IProject。 。 。 .
• 包括:.

这些资源可以是新定义的(new s3.Bucket(...))或导入 (单位:千美元)s3.Bucket.fromBucketAttributes(...)(b) 确定应提供的资源 改为:.

这些资源可能与管道本身不同。 对于 例如,以下行动将部署在从一个 不同账户 :

// Deploy an imported S3 bucket from a different account
declare const stage: codepipeline.IStage;
declare const input: codepipeline.Artifact;
stage.addAction(new codepipeline_actions.S3DeployAction({
  bucket: s3.Bucket.fromBucketAttributes(this, 'Bucket', {
    account: '123456789012',
    // ...
  }),
  input: input,
  actionName: 's3-deploy-action',
  // ...
}));

不接受资源对象的动作接受明示 account 参数 :

// Actions that don't accept a resource objet accept an explicit `account` parameter
declare const stage: codepipeline.IStage;
declare const templatePath: codepipeline.ArtifactPath;
stage.addAction(new codepipeline_actions.CloudFormationCreateUpdateStackAction({
  account: '123456789012',
  templatePath,
  adminPermissions: false,
  stackName: Stack.of(this).stackName,
  actionName: 'cloudformation-create-update',
  // ...
}));

这个 Pipeline 构造自动定义 IAM 作用 为你在 目标账户,管道将假设 执行这一行动。 这个 作用将在 支持堆栈 名称 <PipelineStackName>-support-<account>,将自动部署 在包含管道的堆栈之前.

如果您不想使用生成的角色,也可以明确通过一个 role 当创建动作时。 在这样的情况下,行动将在 该角色属于:

// Explicitly pass in a `role` when creating an action.
declare const stage: codepipeline.IStage;
declare const templatePath: codepipeline.ArtifactPath;
stage.addAction(new codepipeline_actions.CloudFormationCreateUpdateStackAction({
  templatePath,
  adminPermissions: false,
  stackName: Stack.of(this).stackName,
  actionName: 'cloudformation-create-update',
  // ...
  role: iam.Role.fromRoleArn(this, 'ActionRole', '...'),
}));

跨区域代码

类似于您如何设置交叉账户动作, AWS 资源对象为您 转到动作也可以是不同的 区域。例如 以下动作部署在从不同区域进口的S3桶上:

// Deploy to an imported S3 bucket from a different Region.
declare const stage: codepipeline.IStage;
declare const input: codepipeline.Artifact;
stage.addAction(new codepipeline_actions.S3DeployAction({
  bucket: s3.Bucket.fromBucketAttributes(this, 'Bucket', {
    region: 'us-west-1',
    // ...
  }),
  input: input,
  actionName: 's3-deploy-action',
  // ...
}));

不使用 AWS 资源的动作会接受一个明确的 region 参数 :

// Actions that don't take an AWS resource will accept an explicit `region` parameter.
declare const stage: codepipeline.IStage;
declare const templatePath: codepipeline.ArtifactPath;
stage.addAction(new codepipeline_actions.CloudFormationCreateUpdateStackAction({
  templatePath,
  adminPermissions: false,
  stackName: Stack.of(this).stackName,
  actionName: 'cloudformation-create-update',
  // ...
  region: 'us-west-1',
}));

这个 Pipeline 构造自动定义 a 复制桶 页:1 在目标区域, 管道将复制 文物到和 从. 此桶将在 支持堆栈 名称 <PipelineStackName>-support-<region>,将自动部署 在包含管道的堆栈之前.

如果你不想使用这些支持堆栈, 并且已经装有桶 作为复制桶的地方, 您可以在管道定义中提供这些 使用时间 crossRegionReplicationBuckets 参数。 示例

// Supply replication buckets for the Pipeline instead of using the generated support stack
const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  // ...

  crossRegionReplicationBuckets: {
    // note that a physical name of the replication Bucket must be known at synthesis time
    'us-west-1': s3.Bucket.fromBucketAttributes(this, 'UsWest1ReplicationBucket', {
      bucketName: 'my-us-west-1-replication-bucket',
      // optional KMS key
      encryptionKey: kms.Key.fromKeyArn(this, 'UsWest1ReplicationKey',
        'arn:aws:kms:us-west-1:123456789012:key/1234-5678-9012'
      ),
    }),
  },
});

见 这里的 AWS 文件 欲了解更多跨区域代码.

创建加密复制桶

如果你通过一个复制桶 在不同的堆叠, 像这样:

// Passing a replication bucket created in a different stack.
const app = new App();
const replicationStack = new Stack(app, 'ReplicationStack', {
  env: {
    region: 'us-west-1',
  },
});
const key = new kms.Key(replicationStack, 'ReplicationKey');
const replicationBucket = new s3.Bucket(replicationStack, 'ReplicationBucket', {
  // like was said above - replication buckets need a set physical name
  bucketName: PhysicalName.GENERATE_IF_NEEDED,
  encryptionKey: key, // does not work!
});

// later...
new codepipeline.Pipeline(replicationStack, 'Pipeline', {
  crossRegionReplicationBuckets: {
    'us-west-1': replicationBucket,
  },
});

当试图加密时 (并注意如果任何跨区域行动也恰好是交叉账户, 桶头 必须 加密 - 否则管道在运行时会失效 ), 无法直接使用密钥 - KMS 密钥没有物理名称, 所以你不能在环境中参考它们.

在这种情况下,在创建水桶时需要使用别名来代替密钥:

// Passing an encrypted replication bucket created in a different stack.
const app = new App();
const replicationStack = new Stack(app, 'ReplicationStack', {
  env: {
    region: 'us-west-1',
  },
});
const key = new kms.Key(replicationStack, 'ReplicationKey');
const alias = new kms.Alias(replicationStack, 'ReplicationAlias', {
  // aliasName is required
  aliasName: PhysicalName.GENERATE_IF_NEEDED,
  targetKey: key,
});
const replicationBucket = new s3.Bucket(replicationStack, 'ReplicationBucket', {
  bucketName: PhysicalName.GENERATE_IF_NEEDED,
  encryptionKey: alias,
});

变量

库支持CodePipeline可变特性. 发出变量的每个动作类都有单独的变量接口, 作为诉讼案件财产使用 variables。 。 。 . 将动作舱立即分配到本地的变量上; 如果您想要在不同的动作配置中使用变量, 您访问从 variables, (中文(简体) ), 表示单个变量. 示例

// MyAction is some action type that produces variables, like EcrSourceAction
const myAction = new MyAction({
  // ...
  actionName: 'myAction',
});
new OtherAction({
  // ...
  config: myAction.variables.myVariable,
  actionName: 'otherAction',
});

将使用的命名空间名称将由管道构造自动生成, 基于舞台和行动名称; 创建动作实例时, 您可以通过自定义名称 :

// MyAction is some action type that produces variables, like EcrSourceAction
const myAction = new MyAction({
  // ...
  variablesNamespace: 'MyNamespace',
  actionName: 'myAction',
});

还存在全球变量, 与任何行动无关; 它们是通过 GlobalVariables 类 :

// OtherAction is some action type that produces variables, like EcrSourceAction
new OtherAction({
  // ...
  config: codepipeline.GlobalVariables.executionId,
  actionName: 'otherAction',
});

检查文件 @aws-cdk/aws-codepipeline-actions 详细介绍如何使用每个动作类的变量.

见 代码平线文档 关于如何使用变量特性的更详细信息.

活动

利用管道作为事件目标

管道可以作为云表事件规则的目标:

// A pipeline being used as a target for a CloudWatch event rule.
import * as targets from '@aws-cdk/aws-events-targets';
import * as events from '@aws-cdk/aws-events';

// kick off the pipeline every day
const rule = new events.Rule(this, 'Daily', {
  schedule: events.Schedule.rate(Duration.days(1)),
});

declare const pipeline: codepipeline.Pipeline;
rule.addTarget(new targets.CodePipeline(pipeline));

当管道被用作事件目标时 “编码管:启动PipelineExecution”被授予AWS 云表事件服务.

事件来源

管道释放出"云表"事件. 定义事件规则 管道、阶段或行动,使用 onXxx 有关方法 构造 :

// Define event rules for events emitted by the pipeline
import * as events from '@aws-cdk/aws-events';

declare const myPipeline: codepipeline.Pipeline;
declare const myStage: codepipeline.IStage;
declare const myAction: codepipeline.Action;
declare const target: events.IRuleTarget;
myPipeline.onStateChange('MyPipelineStateChange', { target: target } );
myStage.onStateChange('MyStageStateChange', target);
myAction.onStateChange('MyActionStateChange', target);

代码星通知

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

// Define CodeStar Notification rules for Pipelines
import * as chatbot from '@aws-cdk/aws-chatbot';
const target = new chatbot.SlackChannelConfiguration(this, 'MySlackChannel', {
  slackChannelConfigurationName: 'YOUR_CHANNEL_NAME',
  slackWorkspaceId: 'YOUR_SLACK_WORKSPACE_ID',
  slackChannelId: 'YOUR_SLACK_CHANNEL_ID',
});

declare const pipeline: codepipeline.Pipeline;
const rule = pipeline.notifyOnExecutionStateChange('NotifyOnExecutionStateChange', target);