isl-component-resource-definition

Component is used to automate the initialization of AWS resources, specifically AWS EventBridge, based on user-defined metadata.

Usage

The component provides a CLI wrapper for AWS SAM commands with environment variable substitution.

Basic Usage

resource-definition deploy --stack-name %STACK_NAME%

Environment Variable Substitution

Arguments wrapped with % are replaced with their corresponding environment variable values:

# If STACK_NAME=my-stack
resource-definition deploy --stack-name %STACK_NAME%
# Executes: sam deploy --stack-name my-stack

Parameter Overrides

The PARAMETER_OVERRIDE environment variable supports special handling for nested environment variables. When %PARAMETER_OVERRIDE% is used, the --parameter-overrides flag is automatically added if there are resolved values.

Key-Value with Environment Variable Reference

# Environment variables:
# PARAMETER_OVERRIDE="IslSample=$ISL_SAMPLE IslResponseEventbusArn=arn:aws:events:eu-west-1:123456789:event-bus/my-bus"
# ISL_SAMPLE=sample-value

resource-definition deploy %PARAMETER_OVERRIDE%
# Executes: sam deploy --parameter-overrides IslSample=sample-value IslResponseEventbusArn=arn:aws:events:eu-west-1:123456789:event-bus/my-bus

Standalone Environment Variable Reference

When PARAMETER_OVERRIDE contains $ENV_VAR_NAME without a key, the environment variable name is converted to PascalCase as the key:

# Environment variables:
# PARAMETER_OVERRIDE="$ISL_RESPONSE_EVENTBUS_ARN"
# ISL_RESPONSE_EVENTBUS_ARN=arn:aws:events:eu-west-1:123456789:event-bus/my-bus

resource-definition deploy %PARAMETER_OVERRIDE%
# Executes: sam deploy --parameter-overrides IslResponseEventbusArn=arn:aws:events:eu-west-1:123456789:event-bus/my-bus

Empty Standalone Environment Variable

When a standalone $ENV_VAR_NAME resolves to an empty value or is not set, it is skipped entirely to prevent SAM deploy failures:

# Environment variables:
# PARAMETER_OVERRIDE="$UMBRELLA_PRINCIPAL_ARN"
# UMBRELLA_PRINCIPAL_ARN=

resource-definition deploy %PARAMETER_OVERRIDE%
# Executes: sam deploy
# Note: --parameter-overrides is omitted entirely because the env variable is empty

A debug message will be logged when this occurs: Skipping parameter override: UMBRELLA_PRINCIPAL_ARN is empty or not set

Mixed Format

# Environment variables:
# PARAMETER_OVERRIDE="$ISL_SAMPLE CustomKey=$CUSTOM_VALUE StaticKey=static-value"
# ISL_SAMPLE=sample-value
# CUSTOM_VALUE=custom-resolved

resource-definition deploy %PARAMETER_OVERRIDE%
# Executes: sam deploy --parameter-overrides IslSample=sample-value CustomKey=custom-resolved StaticKey=static-value

Establish environment variables (workstation installation)

Copy the .env.example file with default/sample environment variables for development to .env. Examine the variables and edit as necessary/appropriate for your workstation environment.

cp .env.example .env

Installation

First, make sure you are logged-in to the private NPM registry:

npm adduser --registry=https://registry.npmjs.org/ --scope=@aptos-scp

Then install the dependency packages:

npm install

Building the component library

First, make sure you've followed the instructions in the Installation section so you're logged into the private NPM registry and have installed dependency packages.

Then, to build the component library:

$ npm run build

You can then also run tests and coverage:

$ npm run test
$ npm run test:ci

Publishing changes

To publish a new version to the NPM registry:

1. Do these steps only on the master branch -- that is, not on a feature branch. Feature branches should be merged to master before these steps.

2. Commit and push the changes (on master).

3. Update the version of the package using one of the following:

   npm version patch

   or

   npm version minor

   or one of the other variations (see npm-version)

4. Push the version commit and all version tags to trigger the CircleCI build that will build and publish the updated component:

   git push origin master --follow-tags

   or

   From WebStorm or IntelliJ make sure that the Push Tags check-box is checked, when you push changes.

When the build in Circle CI sees the version tag, it will publish the changes to the NPM repository.

License

Please see LICENSE.md.