1. Introduction
   1. Use cases
2. How it works
3. Contributing
4. Installation
   1. Install from the Global NPM registry
      1. Try it out
   2. Local Installation
5. Usage
   1. precloud
   2. precloud --version
   3. precloud --help
6. Available Commands
   1. precloud help
   2. precloud check
      1. Options
      2. Config File
      3. Example Config File
      4. Check Behaviour
      5. Authentication
         1. AWS
         2. GCP
         3. Microsoft Azure
7. Community

Infrastructure code deployments often fail due to mismatched constraints over resource fields between the infrastructure code, the deployment engine, and the target cloud. For example, you may be able to pass any arbitrary string as a resource name to terraform or AWS CDK, and plan or synth go through fine, but the deployment may fail because that string failed a naming constraint on the target cloud.

This package is an open source command line interface that is run before deploying to the cloud. It contains rules that check for names, quotas, and resource-specific constraints to make sure that your infrastructure code can be deployed successfully.

1. Harden your deployments. Ensure that you haven't defined resources that already exist so that you don't have to fail during deployments.
2. Enforce organizational resource patterns. Use resource checks to ensure resources are named and tagged correctly.
3. Maintain security standards. Use template check plugins to make sure that you're not launching things outside of VPCs, leaving public IPs open, or allowing global access to S3 buckets.

This package compairs resources in CDK diffs and Terraform Plans against the state of your cloud account. The rules and validations come from default and custom defined "plugins", which are composed of parsers and checkers. See DEVELOPING_PLUGINS.md for more information.

You may want to check for other attributes before deploying. This package is built using a plugin-model. You can find existing plugins at PLUGINS.md and use them easily by adding the plugin to your config file. See the example config file below.

It is easy to create additional tests as plugins, please see DEVELOPING_PLUGINS.md. Make sure to issue a PR to add your plugin to this package!

# Install the CLI globally
# Using the -g option installs the precloud cli to your shell scope instead of the package scope. 
# It adds the CLI command to bin, allowing you to call precloud from anywhere
npm i -g @tinystacks/precloud;

# Use the CLI, refer to the usage guide below
precloud --version;

# After installing the CLI, you can try it out on a cdk or terraform package
# An example cdk package is included in this package
git clone https://github.com/tinystacks/precloud.git;

# navigate to the examples directory
cd precloud/examples/cdk;

# install dependencies
npm i;

# (Optional) initalize precloud
precloud init;

# run precloud check
precloud check;

# To see a precloud check fail, uncomment the commented out lines in examples/cdk/index.ts
precloud check;

# Clone this package
git clone https://github.com/tinystacks/precloud.git;

# Install dependencies and build
npm i; npm run build;

# Install the CLI globally
# Using the -g option installs the precloud cli to your shell scope instead of the package scope. 
#  It adds the CLI command to bin, allowing you to call precloud from anywhere
npm i -g;

# Use the CLI, refer to the usage guide below
precloud --version;

Shows usage and help information.

Alias: -V Shows the current installed version number.

Alias: -h Shows usage and help information.

Shows usage and help information.

Performs a check on an AWS CDK app or a Terraform configuration to validate the planned resources can be launched or updated.

Alternatively, instead of specifying options via command line flags, you can set them in a configuration file. This file must be valid JSON and named either precloud.config.json or the --config-file flag specified. Valid config properties:

{
    "awsCdkParsers": [
        "@tinystacks/aws-cdk-parser"
    ],
    "terraformParsers": [
        "@tinystacks/terraform-resource-parser",
        "@tinystacks/terraform-module-parser"
    ],
    "templateChecks": [
        "@tinystacks/aws-template-checks"  
    ],
    "resourceChecks": [
        "@tinystacks/aws-resource-checks"
    ]
}

When the check command is run, it will first perform a diffing operation to determine the changes that deploying the stack would make. For AWS CDK this is cdk diff, for Terraform terraform plan.

The diff from this operation is then used to identify resources that would change. These resources are then tested first by running template checks which validate across the resources in the IaC configuration, and then at an individual resource level to determine if any runtime errors might occur during a deployment.

This cli includes some of our plugins for parsing and running template and resource checks by default. The default plugins will check the following:

1. Any SQS queue names are unique.
2. Any S3 bucket names are unique.
3. The current stack will not surpass the S3 service quota.
4. The current stack will not surpass the Elastic IP Address service quota.
5. The current stack will not surpass the VPC service quota.
6. (Optional) Verifies that the VPC has private subnets (egress-only subnets via a NAT Gateway or Nat Instance(s)).

This command requires authentication to the Cloud Provider the CDK app or Terraform config will use. The following authentication methods are supported.

• Environment Variables (preferred)
• Any other authetication method supported by the Node Provider Chain.

Not supported.

Not supported.

Join our discord to have a chat!