simulate

README

Gaggle CDK Template App

This repo exists as a starting point for a typical Gaggle CDK application.

It contains starter files for a CDK application, as well as the skeleton of a Gaggle CodePipeline.

Keep in mind that this is just a starting point to get you up and running faster. There is still a lot that you'll need to modify to make it useful.

Setup Quickstart

• Add dependencies to requirements/requirements.in
• Add dev dependencies (if any) to requirements/requirements-dev.in
  • Generally it is best practice to leave dependencies "unpinned" without specific versions, unless a specific version is required.
• Run make update
• If using Pyenv Virtualenv: run make virtualenv and activate it
• Run make install

Directory Structure

app.py

This is the CDK starting point for your CDK application. This is a good place to gather context variables to pass on to your application stack.

pipeline.py

This is the CDK starting point for your CodePipeline.

buildspec.yml and buildspec-deploy.yml

These are the CodeBuild buildspec files that define what the Build and Deploy stages in your Pipeline actually do.

buildspec.yml defines the actions that the CI Build (triggered by pushes to feature branches) and Pipeline Build (triggered by pushes to the main branch) perform.

This is where you can run unit tests and lint, and build and push your application artifacts. The CI Build is also where test reports are sent from CodeBuild to Github, which you see in Pull Requests.

buildspec-deploy.yml defines the actions during the Deploy stages of your pipeline. A skeleton CDK deployment is provided.

cdk.json

cdk.json defines the default CDK context values and the command needed to interact with the CDK app.

This is a good place to store default context variables, such as "gaggle-cdk:toolchain-account": "460106496004".

All of these values can be overridden when executing cdk commands by passing in a --context <context-name>=<context-value> flag. This is useful when deploying into different environments that have different variable values.

Makefile

The Makefile adds convenience commands for managing dependencies, running tests and building applications. Some useful commands are provided for you, such as:

make install: Install your dependencies from requirements.txt and requirements-dev.txt

make update: Update the requirements.txt and requirements-dev.txt files. Use this when you add new dependencies to requirements/requirements.in or requirements/requirements-dev.in

make upgrade: Does the same thing as make update, but also bumps the depdendency versions to their latest.

make format: Runs Black, which is a Python utility to automatically format your code to PEP 8 standards. Good to run just before you make a commit.

make lint: Run Pylint

requirements/

Your Python requirements files go here.

Add CDK app requirements (such as aws-cdk.aws-iam) in requirements.in, and don't pin the version.

Add any development requirements (like pylint) to requirements-dev.in, and similarly don't pin versions.

When you add a new package to either file, run make update to update your requirements.txt and requirements-dev.txt files. Then run make install to install dependencies from the requirements.txt files.

requirements.txt and requirements-dev.txt

These files are generated by make update/make upgrade. Don't change these files on your own.

stacks

This is where your CDK Stack classes live. To start with you have an app_stack.py where your application resources are defined, and pipeline_stack.py where your Gaggle CodePipeline is defined.

You're provided with the skeleton of a Gaggle DeploymentPipeline stack, which you can modify to your needs.