Deployment Triggers - Githubissues

mneil commented 6 years ago

Description

Allow specifying arbitrary handlers which execute as part of the deployment process and trigger them before/after resources or stacks.

Published: https://github.com/awslabs/cdk-triggers

README

Hypothetical README for this feature

You can trigger the execution of arbitrary AWS Lambda functions before or after resources or groups of resources are provisioned using the Triggers API.

The library includes constructs that represent different triggers. The BeforeCreate and AfterCreate constructs can be used to trigger a handler before/after a set of resources have been created.

new triggers.AfterCreate(this, 'InvokeAfter', {
  resources: [resource1, resource2, stack, ...],
  handler: myLambdaFunction,
});

Similarly, triggers.BeforeCreate can be used to set up a "before" trigger.

Where resources is a list of construct scopes which determine when handler is invoked. Scopes can be either specific resources or composite constructs (in which case all the resources in the construct will be used as a group). The scope can also be a Stack, in which case the trigger will apply to all the resources within the stack (same as any composite construct). All scopes must roll up to the same stack.

Let's look at an example. Say we want to publish a notification to an SNS topic that says "hello, topic!" after the topic is created.

// define a topic
const topic = new sns.Topic(this, 'MyTopic');

// define a lambda function which publishes a message to the topic
const publisher = new NodeJsFunction(this, 'PublishToTopic');
publisher.addEnvironment('TOPIC_ARN', topic.topicArn);
publisher.addEnvironment('MESSAGE', 'Hello, topic!');
topic.grantPublish(publisher);

// trigger the lambda function after the topic is created
new triggers.AfterCreate(this, 'SayHello', {
  scopes: [topic],
  handler: publisher
});

Requirements

One-off exec before/after resource/s are created (Trigger.AfterCreate).
Additional periodic execution after deployment (repeatOnSchedule).
Async checks (retryWithTImeout)
Execute on updates (bind logical ID to hash of CFN properties of triggered resource)
Execute shell command inside a Docker image

Use Cases

Here are some examples of use cases for triggers:

Intrinsic validations: execute a check to verify that a resource or set of resources have been deployed correctly
- Test connections to external systems (e.g. security tokens are valid)
- Verify integration between resources is working as expected
- Execute as one-off and also periodically after deployment
- Wait for data to start flowing (e.g. wait for a metric) before deployment is successful
Data priming: add data to resources after they are created
- CodeCommit repo + initial commit
- Database + test data for development
Check prerequisites before depoyment
- Account limits
- Availability of external services
Connect to other accounts

Implementation

At the base level, the trigger handler can be invoked through a custom resource and the timing (before/after) will be determined using CFN dependencies ("after" means the trigger CR depends on the scope, and "before" is the opposite).

This simple implementation will allow us to implement "one-off" triggers. This means that we wait for a CFN CREATE request on the custom resource and invoke the handler. Any updates to the stack will not include any changes to the properties of the custom resource and therefore the trigger won't get invoked again (unless it's removed).

We need to consider the following:

If the trigger handler itself changes, do we want it to be invoked again?
If the triggering resource is updated, do we want the trigger to be invoked again?
Do we want some kind of support for triggers that always gets invoked (for any update)?
Do we want triggers for "AfterDelete" or "AfterUpdate" does that make sense?

Lots to talk about!

Next Steps

[ ] Least-privilege IAM policy for trigger custom resource provider (currently it's invokeFunction for * resources).
[ ] Invoke trigger if another resource is added to the stack (even if the trigger has already been created).
[ ] Consider adding support for "update" triggers (if the triggering resource has been updated).

Related Issues

See #75 for a discussion, then, use these for e.g. integration test assertions (#31)

Progress

[x] Tracking Issue Created
[ ] RFC PR Created
[ ] Core Team Member Assigned
[ ] Initial Approval / Final Comment Period
[ ] Ready For Implementation
- [ ] implementation issue 1
[ ] Resolved

eladb commented 6 years ago

@mneil this is an interesting proposal. I can't say I have a good idea on how to implement something like this in our current architecture, but we might be able to achieve something like this when we generalize through aws/aws-cdk#233.

Do you have other use cases in mind that you can share?

mneil commented 6 years ago

Another thing I can think of is the need to peer cross region vpcs. Currently I believe cfn only works in a single region with the peer resource. If I want to peer two vpcs in different regions I need to launch my stack in two regions with different cidr blocks then use the sdk to run the peering command.

Without events is have to run the cdk code, let it exit, then launch a separate process to do the peering.

rix0rrr commented 6 years ago

I think the solution to each of these cases is going to be Custom Resources (you can run arbitrary code in a Lambda during the CloudFormation workflow). You can write these yourself, today, and they can do what you need. It cannot be anything else because the CDK app executes completely before the CloudFormation deployment starts, and so before the first bucket gets created.

If you want to define them as part of your CDK app, it follows that we're going to have to transparently generate Lambdas for you. It can be done, but there's a good chance it won't work the way you expect it to. For example, any state in your CDK app that your even handler closes over is going to be very hard to transport into the Lambda when it executes at some indeterminate point later in time.

mneil commented 6 years ago

Yes, I'm aware I can use a custom resource.

Right now I'm solving it with code pipeline and code deploy.

I guess I just imagined that if I could use a programming language to compose my stack then I could also use that stack within the context of other code - more like the sdk. As it stands now a cdk application must stand alone and couldn't be triggered within a larger application.

If I wanted to maybe make my cdk app into a micro service I'd need to write a program to accept an incoming connection, then spawn a separate cdk process, wait for it to exit, read the response code, then respond.

Even just adding some lifecycle hooks to the app object would make it far more extensible. I could even attempt a first pass on this at the app level and open a pr. I don't want to spend time on it though if it's not something anyone wants to add.

rix0rrr commented 6 years ago

Okay, I think I see what you're saying. During the course of a deployment we can call the CDK app again, but instead of synthesizing we can invoke arbitrary callbacks, depending on the progress of the deployment.

It's an interesting notion. Definitely not on our current roadmap, but I'd be interested to see a PoC, and more importantly hear of some use cases that were best addressed this way (and not using Custom Resources for example).

Also I don't quite get where the need for a microservice is coming from?

rix0rrr commented 6 years ago

Alternatively, you could implement some constructs right now that have this feature to solve your own use cases, and vend those as an extension library to the CDK.

dnagir commented 5 years ago

At this stage (personally for me), it would be sufficient to just have the "hooks" after the stacks are deployed.

Similar to aws/aws-cdk#1938 but on the client-side.

The use-cases:

use AWS API to amend the resources that CloudFormation doesn't support (#1938 is probably better for that, but local update often times is enough)
pushing notifications, outside of the account where the deployment happens
confirming a success/failure and the details for the automation scripts

Possible API (not well thought through) could look like:

// App-level - constructor parameters
const app = new cdk.App(hooks: { deployed: (s: Stack, outcome: cdk.OutcomeDetails)=>{...} });
// ...
app.run()

// App-level - promise-like
const app = new cdk.App();
// ...
app.run().whenDeployed().then((stack, outcome) => { ... });

// Stack override
export class Stack1 extends cdk.Stack {
    constructor(scope: cdk.App) { ... }

    whenDeployed(outcome: cdk.OutcomeDetails) {
      // default implementaion - noop
    }
}

const app = new cdk.App();
const stack1 = new Stack1(app);

Out of the above, I think my current preference is Stack override as it would make sense in my use-case - amend Cognito client OAuth details. This option keeps the stack-related details closer together.

But the application-level options are fine too and probably are better for other use-cases.