Correct docs for app-delivery & improve usability

[skinny85]

1. (Found by @moofish32 on Gitter) This is wrong:

const project = new codebuild.PipelineProject(pipelineStack, 'CodeBuild', {
  /* ... */
});
const synthesizedApp = project.outputArtifact;

Project doesn't have an outputArtifact property, it's a CodePipeline thing. It's also missing a build Pipeline Stage.

So, it should be something like:

const project = new codebuild.PipelineProject(pipelineStack, 'CodeBuild', {
  /* ... */
});
const buildStage = pipeline.addStage('build');
const buildAction = project.addBuildToPipeline(buildStage, 'CodeBuild');
const synthesizedApp = buildAction.outputArtifact;

2. It uses import cicd = require('@aws-cdk/cicd');, which doesn't exist anymore (the name was changed).

[RomainMuller]

Über-oops. Thanks for the report! It's probably a good idea to turn this into a literate markdown example if possible (not sure this can be done without incurring dependency cycles, though).

[moofish32]

I would like to make this issue a little broader (include the doc update, but also the major missing feature for IAM).

I created a very simple app-delivery example:

The app is basically a security group that is whitelisting an IP and Port. Think about an old data center stuck application that you need access to in AWS (perhaps it's not even owned by you). This practice of IP whitelisting is a last resort and should generally be avoided, but it's a simple example.

As the IP addresses change you would like the security group automatically updated, because IPs are either owned by the service or not, the concept of semver doesn't really apply to this use case. So imagine you update the repo and this artifact is put in an S3 bucket which you want to update your security group.

The VPC parameter here presents an interesting challenge for the app-delivery package. If you want to provide this pattern in a common place for all accounts in your organization AWS Service Catalog might a good place to interface. That means that you need to allow the account to parameterize VPC ID and thus now you need to update a stack and do the equivalent of user previous value. I am not positive but I assume this lives in the Parameter Overrides.

In order to deploy the security group you will need a base set of permissions passed to the role executing the change set. Today that is the missing feature.

If we really want a separate issue for docs, let me know.

[moofish32]

I can't update title or description -- so if we agree to consolidate can somebody with access take care of that?

[moofish32]

For other users hitting this issue you can work around using our escape hatch similar too:

const pipelineActions: cfn.PipelineCreateReplaceChangeSetAction = deployAction.children.
  find( c => (c as cfn.PipelineCreateReplaceChangeSetAction).role !== undefined) as cfn.PipelineCreateReplaceChangeSetAction;

[moofish32]

@RomainMuller and @skinny85 I think we are also going to need to expose capabilities this one is not accessible via overrides as easy.

[RomainMuller]

@moofish32 the capabilities being exposed/settable makes a lot of sense anyway.

[RomainMuller]

We need to give the example in the README.md the literate treatment (hopefully it doesn't imply creating circular dependencies...) so we can maintain guarantee that it at least compiles. I'll get to this once #1165 has landed.