@wheatstalk/aws-cdk-exec/README.md

An AWS CDK Cloud Assembly-aware command to help find and execute lambda functions and state machines

# AWS CDK Exec

Provides `cdk-exec`, an AWS CDK dev tool to quickly find and execute your
Lambdas and State Machines in AWS.

```
$ cdk-exec integ-cdk-exec/Function --input '{"succeed":true}'
⚡  Executing integ-cdk-exec/Function/Resource (integ-cdk-exec-Function76856677-k5ehIzbG2T6S)


✨  Final status of integ-cdk-exec/Function/Resource

Output:
{
  "succeed": true,
  "message": "Hello from Lambda"
}

✅  Execution succeeded
```

> WARNING: Do not rely on this tool to execute your functions in a production
> environment. Now that you have been warned, please read on.

**Exporting Environment Variables**

If during local development you want to access the environment variables
configured for a Lambda Function, such as to see the arns of real resources,
you may use `cdk-exec --export-env integ-cdk-exec/Function`.

```
$ cdk-exec --export-env integ-cdk-exec/Function
FOO=bar
SECRET_ARN=arn:aws:secretsmanager:REGION:000000000000:secret:SecretA720EF05-qa4X020B9S3f-UI3sIs
```

## Usage

First, add `@wheatstalk/aws-cdk-exec` to your project's dev dependencies.
Then synthesize your app to a `cdk.out` directory. Once synthesized there, you
can execute one of your resources with `cdk-exec`.

> If you're using `cdk watch`, the CDK will keep your `cdk.out` up to date, so
> when you use watch mode, you can run `cdk-exec` (roughly) at will.

## Full Example

**app.ts**

```ts
import { App, Stack } from 'aws-cdk-lib';
import { Code, Function, Runtime } from 'aws-cdk-lib/aws-lambda';
import { Choice, Condition, Fail, StateMachine, Succeed } from 'aws-cdk-lib/aws-stepfunctions';

const app = new App();
const stack = new Stack(app, 'integ-cdk-exec');

new StateMachine(stack, 'StateMachine', {
  definition: new Choice(stack, 'Choice')
    .when(Condition.isPresent('$.succeed'),
      new Succeed(stack, 'ChoiceSucceed'))
    .otherwise(
      new Fail(stack, 'ChoiceFail')),
});

new Function(stack, 'Function', {
  runtime: Runtime.PYTHON_3_9,
  handler: 'index.handler',
  code: Code.fromInline(`
def handler(event, context):
  if "succeed" in event:
    return {"succeed": True, "message": "Hello from Lambda"}

  raise Exception('Error from lambda')
`),
});

app.synth();
```

**Synthesize your app**

The `cdk-exec` tool operates on a synthesized cloud assembly (your `cdk.out`
directory), so the first step is to synthesize your app:

```console
$ cdk synth --output cdk.out
```

**Execute a state machine with input**

```
$ cdk-exec integ-cdk-exec/StateMachine --input '{"succeed":true}'
⚡  Executing integ-cdk-exec/StateMachine/Resource (arn:aws:states:REGION:000000000000:stateMachine:StateMachine2E01A3A5-8z4XHXAvT3qq)


✨  Final status of integ-cdk-exec/StateMachine/Resource

Output:
{
  "succeed": true
}

✅  Execution succeeded
```

**Execute a lambda with input**

```
$ cdk-exec integ-cdk-exec/Function --input '{"succeed":true}'
⚡  Executing integ-cdk-exec/Function/Resource (integ-cdk-exec-Function76856677-k5ehIzbG2T6S)


✨  Final status of integ-cdk-exec/Function/Resource (integ-cdk-exec-Function76856677-k5ehIzbG2T6S)

Output:
{
  "succeed": true,
  "message": "Hello from Lambda"
}

✅  Execution succeeded
```

**Use a custom cloud assembly directory**

```
$ cdk-exec --app path/to/cdkout integ-cdk-exec/Function --input '{"json":"here"}'
⚡  Executing integ-cdk-exec/Function/Resource (integ-cdk-exec-Function76856677-k5ehIzbG2T6S)


✨  Final status of integ-cdk-exec/Function/Resource

Output:
{
  "succeed": true,
  "message": "Hello from Lambda"
}

✅  Execution succeeded
```

## Resource Matching

**Path matching**

`cdk-exec` searches for resources matching the exact path you provide and any
deeper nested resources. This is how we support both L1 & L2 constructs, but
is also a convenient shortcut when your app has only one executable resource.

For example, if you have only one function or state machine in a stack, you
can type `cdk-exec my-stack` and your resource will be found. If your entire
app has only one executable resource, you can run `cdk-exec` without arguments
to run it.

**Tag matching**

When running `cdk-exec --tag mytag=value`, cdk-exec will search for a resource
matching tags that you have defined in your CDK app. If more than one resource
would match, by default `cdk-exec` will produce an error message. But, if you
want to execute several resources simultaneously, `cdk-exec` provides `--all`.

We have also added aliases and shorthands to streamline typing label-matching
commands. For example, `cdk-exec -at mytag` will try to run all resources with
a tag named `mytag`, regardless of the value of the tag. This has the same
effect as typing the longer `cdk-exec --all --tag mytag` command.

**Metadata matching**

When running `cdk-exec --metadata mymeta=myvalue`, cdk-exec will search for and
run resources containing the given metadata. Same as for tag matching, you can
run one or more matching resources if you specify the `--all` option.

## Notes

**Path metadata**

This tool requires path metadata to be enabled in your assembly.