Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(pipelines): make examples compile #16963

Merged
merged 4 commits into from
Oct 14, 2021
Merged

docs(pipelines): make examples compile #16963

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7cff537
compile all non-readme examples
kaizencc Oct 13, 2021
d695d1c
make README snippets compile
kaizencc Oct 13, 2021
0824986
consistent naming conventions for ORIGINAL_API.md
kaizencc Oct 14, 2021
0bc1059
Merge branch 'master' into compile/pipelines
kaizencc Oct 14, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 57 additions & 41 deletions packages/@aws-cdk/pipelines/ORIGINAL_API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,9 @@ all commands necessary to do a full CDK build and synth, so do include
installing dependencies and running the CDK CLI. For example, the old API:

```ts
SimpleSynthAction.standardNpmSynth({
const sourceArtifact = new codepipeline.Artifact();
const cloudAssemblyArtifact = new codepipeline.Artifact();
pipelines.SimpleSynthAction.standardNpmSynth({
sourceArtifact,
cloudAssemblyArtifact,

Expand All @@ -54,8 +56,10 @@ SimpleSynthAction.standardNpmSynth({
Becomes:

```ts
new ShellStep('Synth', {
input: /* source */,
new pipelines.ShellStep('Synth', {
input: pipelines.CodePipelineSource.connection('my-org/my-app', 'main', {
connectionArn: 'arn:aws:codestar-connections:us-east-1:222222222222:connection/7d2469ff-514a-4e4f-9003-5ca4a43cdc41', // Created using the AWS console * });',
}),
commands: [
'npm ci',
'npm run build',
Expand All @@ -71,7 +75,7 @@ You can use any of the factory functions on `CodePipelineSource`.
For example, for a GitHub source, the following old API:

```ts
sourceAction: new codepipeline_actions.GitHubSourceAction({
sourceAction: new cpactions.GitHubSourceAction({
actionName: 'GitHub',
output: sourceArtifact,
// Replace these with your actual GitHub project name
Expand All @@ -84,8 +88,8 @@ sourceAction: new codepipeline_actions.GitHubSourceAction({
Translates into:

```ts
input: CodePipelineSource.gitHub('OWNER/REPO', 'main', {
authentication: SecretValue.secretsManager('GITHUB_TOKEN_NAME'),
input: pipelines.CodePipelineSource.gitHub('OWNER/REPO', 'main', {
authentication: cdk.SecretValue.secretsManager('GITHUB_TOKEN_NAME'),
}),
```

Expand All @@ -111,8 +115,9 @@ putting manual approvals in `pre` steps, and automated approvals in `post` steps
For example, specifying a manual approval on a stage deployment in old API:

```ts
declare const pipeline: pipelines.CdkPipeline;
const stage = pipeline.addApplicationStage(...);
stage.addAction(new ManualApprovalAction({
stage.addAction(new pipelines.ManualApprovalAction({
actionName: 'ManualApproval',
runOrder: testingStage.nextSequentialRunOrder(),
}));
Expand All @@ -121,9 +126,10 @@ stage.addAction(new ManualApprovalAction({
Becomes:

```ts
pipeline.addStage(..., {
const stage = new MyApplicationStage(this, 'MyApplication');
pipeline.addStage(stage, {
pre: [
new ManualApprovalStep('ManualApproval'),
new pipelines.ManualApprovalStep('ManualApproval'),
],
});
```
Expand All @@ -139,7 +145,7 @@ For example, specifying an automated approval after a stage is deployed in the f

```ts
const stage = pipeline.addApplicationStage(...);
stage.addActions(new ShellScriptAction({
stage.addActions(new pipelines.ShellScriptAction({
actionName: 'MyValidation',
commands: ['curl -Ssf $VAR'],
useOutputs: {
Expand All @@ -153,10 +159,10 @@ stage.addActions(new ShellScriptAction({
Becomes:

```ts
const stage = new MyStage(...);
const stage = new MyApplicationStage(this, 'MyApplication');
pipeline.addStage(stage, {
post: [
new CodeBuildStep('MyValidation', {
new pipelines.CodeBuildStep('MyValidation', {
commands: ['curl -Ssf $VAR'],
envFromCfnOutput: {
VAR: stage.cfnOutput,
Expand All @@ -174,7 +180,19 @@ customizations (like `buildEnvironment`).
#### Change set approvals

In the old API, there were two properties that were used to add actions to the pipeline
in between the `CreateChangeSet` and `ExecuteChangeSet` actions: `manualApprovals` and `extraRunOrderSpace`. These are not supported in the new API.
in between the `CreateChangeSet` and `ExecuteChangeSet` actions: `manualApprovals` and `extraRunOrderSpace`.
This can be achieved in the modern API via the `stackSteps` property, which allows steps to be added
at the stack level:

```ts
const stage = new MyApplicationStage(this, 'MyApplication');
pipeline.addStage(stage, {
stackSteps: [{
stack: stage.stack1,
changeSet: [new pipelines.ManualApprovalStep('ChangeSet Approval')],
}],
});
```

### Custom CodePipeline Actions

Expand All @@ -190,7 +208,6 @@ artifacts:

```ts
import { Construct, Stage, Stack, StackProps, StageProps } from '@aws-cdk/core';
import { CdkPipeline } from '@aws-cdk/pipelines';
import * as codepipeline from '@aws-cdk/aws-codepipeline';

/**
Expand All @@ -203,20 +220,20 @@ class MyPipelineStack extends Stack {
const sourceArtifact = new codepipeline.Artifact();
const cloudAssemblyArtifact = new codepipeline.Artifact();

const pipeline = new CdkPipeline(this, 'Pipeline', {
const pipeline = new pipelines.CdkPipeline(this, 'Pipeline', {
cloudAssemblyArtifact,

sourceAction: new codepipeline_actions.GitHubSourceAction({
sourceAction: new cpactions.GitHubSourceAction({
actionName: 'GitHub',
output: sourceArtifact,
oauthToken: SecretValue.secretsManager('GITHUB_TOKEN_NAME'),
oauthToken: cdk.SecretValue.secretsManager('GITHUB_TOKEN_NAME'),
// Replace these with your actual GitHub project name
owner: 'OWNER',
repo: 'REPO',
branch: 'main', // default: 'master'
}),

synthAction: SimpleSynthAction.standardNpmSynth({
synthAction: pipelines.SimpleSynthAction.standardNpmSynth({
sourceArtifact,
cloudAssemblyArtifact,

Expand Down Expand Up @@ -274,21 +291,21 @@ class MyPipelineStack extends Stack {
const sourceArtifact = new codepipeline.Artifact();
const cloudAssemblyArtifact = new codepipeline.Artifact();

const pipeline = new CdkPipeline(this, 'Pipeline', {
const pipeline = new pipelines.CdkPipeline(this, 'Pipeline', {
pipelineName: 'MyAppPipeline',
cloudAssemblyArtifact,

sourceAction: new codepipeline_actions.GitHubSourceAction({
sourceAction: new cpactions.GitHubSourceAction({
actionName: 'GitHub',
output: sourceArtifact,
oauthToken: SecretValue.secretsManager('GITHUB_TOKEN_NAME'),
oauthToken: cdk.SecretValue.secretsManager('GITHUB_TOKEN_NAME'),
// Replace these with your actual GitHub project name
owner: 'OWNER',
repo: 'REPO',
branch: 'main', // default: 'master'
}),

synthAction: SimpleSynthAction.standardNpmSynth({
synthAction: pipelines.SimpleSynthAction.standardNpmSynth({
sourceArtifact,
cloudAssemblyArtifact,

Expand Down Expand Up @@ -316,7 +333,7 @@ If you prefer more control over the underlying CodePipeline object, you can
create one yourself, including custom Source and Build stages:

```ts
const codePipeline = new cp.Pipeline(pipelineStack, 'CodePipeline', {
const codePipeline = new codepipeline.Pipeline(pipelineStack, 'CodePipeline', {
stages: [
{
stageName: 'CustomSource',
Expand All @@ -330,7 +347,7 @@ const codePipeline = new cp.Pipeline(pipelineStack, 'CodePipeline', {
});

const app = new App();
const cdkPipeline = new CdkPipeline(app, 'CdkPipeline', {
const cdkPipeline = new pipelines.CdkPipeline(app, 'CdkPipeline', {
codePipeline,
cloudAssemblyArtifact,
});
Expand Down Expand Up @@ -360,9 +377,9 @@ using these, the source repository does not need to have a `buildspec.yml`. An e
of using `SimpleSynthAction` to run a Maven build followed by a CDK synth:

```ts
const pipeline = new CdkPipeline(this, 'Pipeline', {
const pipeline = new pipelines.CdkPipeline(this, 'Pipeline', {
// ...
synthAction: new SimpleSynthAction({
synthAction: new pipelines.SimpleSynthAction({
sourceArtifact,
cloudAssemblyArtifact,
installCommands: ['npm install -g aws-cdk'],
Expand Down Expand Up @@ -396,16 +413,16 @@ from the CA repo instead of NPM.
class MyPipelineStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
...
const pipeline = new CdkPipeline(this, 'Pipeline', {
const pipeline = new pipelines.CdkPipeline(this, 'Pipeline', {
...
synthAction: SimpleSynthAction.standardNpmSynth({
synthAction: pipelines.SimpleSynthAction.standardNpmSynth({
sourceArtifact,
cloudAssemblyArtifact,

// Use this to customize and a permissions required for the build
// and synth
rolePolicyStatements: [
new PolicyStatement({
new iam.PolicyStatement({
actions: ['codeartifact:*', 'sts:GetServiceBearerToken'],
resources: ['arn:codeartifact:repo:arn'],
}),
Expand Down Expand Up @@ -477,7 +494,7 @@ const testingStage = pipeline.addApplicationStage(new MyApplication(this, 'Testi
// Add a action -- in this case, a Manual Approval action
// (for illustration purposes: testingStage.addManualApprovalAction() is a
// convenience shorthand that does the same)
testingStage.addAction(new ManualApprovalAction({
testingStage.addAction(new pipelines.ManualApprovalAction({
actionName: 'ManualApproval',
runOrder: testingStage.nextSequentialRunOrder(),
}));
Expand Down Expand Up @@ -522,7 +539,7 @@ In its simplest form, adding validation actions looks like this:
```ts
const stage = pipeline.addApplicationStage(new MyApplication(/* ... */));

stage.addActions(new ShellScriptAction({
stage.addActions(new pipelines.ShellScriptAction({
actionName: 'MyValidation',
commands: ['curl -Ssf https://my.webservice.com/'],
// Optionally specify a VPC if, for example, the service is deployed with a private load balancer
Expand Down Expand Up @@ -563,7 +580,7 @@ const lbApp = new MyLbApplication(this, 'MyApp', {
env: { /* ... */ }
});
const stage = pipeline.addApplicationStage(lbApp);
stage.addActions(new ShellScriptAction({
stage.addActions(new pipelines.ShellScriptAction({
// ...
useOutputs: {
// When the test is executed, this will make $URL contain the
Expand Down Expand Up @@ -594,7 +611,7 @@ two ways.
Either pass additional policy statements in the `rolePolicyStatements` property:

```ts
new ShellScriptAction({
new pipelines.ShellScriptAction({
// ...
rolePolicyStatements: [
new iam.PolicyStatement({
Expand All @@ -608,7 +625,7 @@ new ShellScriptAction({
The Action can also be used as a Grantable after having been added to a Pipeline:

```ts
const action = new ShellScriptAction({ /* ... */ });
const action = new pipelines.ShellScriptAction({ /* ... */ });
pipeline.addStage('Test').addActions(action);

bucket.grantRead(action);
Expand All @@ -623,11 +640,11 @@ if they are executable shell scripts themselves). Pass the `sourceArtifact`:
```ts
const sourceArtifact = new codepipeline.Artifact();

const pipeline = new CdkPipeline(this, 'Pipeline', {
const pipeline = new pipelines.CdkPipeline(this, 'Pipeline', {
// ...
});

const validationAction = new ShellScriptAction({
const validationAction = new pipelines.ShellScriptAction({
actionName: 'TestUsingSourceArtifact',
additionalArtifacts: [sourceArtifact],

Expand All @@ -651,8 +668,8 @@ in the `ShellScriptAction`'s `additionalArtifacts`:
const cloudAssemblyArtifact = new codepipeline.Artifact('CloudAsm');
const integTestsArtifact = new codepipeline.Artifact('IntegTests');

const pipeline = new CdkPipeline(this, 'Pipeline', {
synthAction: SimpleSynthAction.standardNpmSynth({
const pipeline = new pipelines.CdkPipeline(this, 'Pipeline', {
synthAction: pipelines.SimpleSynthAction.standardNpmSynth({
sourceArtifact,
cloudAssemblyArtifact,
buildCommands: ['npm run build'],
Expand All @@ -666,7 +683,7 @@ const pipeline = new CdkPipeline(this, 'Pipeline', {
// ...
});

const validationAction = new ShellScriptAction({
const validationAction = new pipelines.ShellScriptAction({
actionName: 'TestUsingBuildArtifact',
additionalArtifacts: [integTestsArtifact],
// 'test.js' was produced from 'test/test.ts' during the synth step
Expand Down Expand Up @@ -715,12 +732,11 @@ create an SNS Topic, subscribe your own email address, and pass it in via
```ts
import * as sns from '@aws-cdk/aws-sns';
import * as subscriptions from '@aws-cdk/aws-sns-subscriptions';
import * as pipelines from '@aws-cdk/pipelines';

const topic = new sns.Topic(this, 'SecurityChangesTopic');
topic.addSubscription(new subscriptions.EmailSubscription('[email protected]'));

const pipeline = new CdkPipeline(app, 'Pipeline', { /* ... */ });
const pipeline = new pipelines.CdkPipeline(app, 'Pipeline', { /* ... */ });
const stage = pipeline.addApplicationStage(new MyApplication(this, 'PreProd'), {
confirmBroadeningPermissions: true,
securityNotificationTopic: topic,
Expand Down
Loading