AWS Observability Accelerator for CDK¶

GitHub

Welcome to the AWS Observability Accelerator for CDK!

The AWS Observability Accelerator for CDK is a set of opinionated modules to help you set up observability for your AWS environments with AWS Native services and AWS-managed observability services such as Amazon Managed Service for Prometheus,Amazon Managed Grafana, AWS Distro for OpenTelemetry (ADOT) and Amazon CloudWatch.

One of the fallacies of distributed computing is that observability is optional. It's a prevalent but wrong assumption. To have a reliable and changeable system, you need to have proper observability in place. And this project aims to help you.

AWS Observability Accelerator for CDK provides patterns with:

Single EKS Cluster AWS Native Observability Accelerator¶

AWSNative-Architecture

Single EKS Cluster Open Source Observability Accelerator¶

OpenSource-Architecture

Patterns¶

The individual patterns can be found in the lib directory. Most of the patterns are self-explanatory, for some more complex examples please use this guide and docs/patterns directory for more information.

Usage¶

Before proceeding, make sure AWS CLI is installed on your machine.

To use this solution, you must have Node.js and npm installed. You will also use make and brew to simplify build and other common actions.

Workstation Setup Options¶

DevContainer Setup¶

Users can choose this option, if you dont want to run this solution on a mac or ubuntu machine. Please use the dev container configuration in the .devcontainer folder with devpod or any other dev container environment to create a development environment with dependencies such as Node, NPM, aws-cli, aws-cdk, kubectl, helm dependencies for your local development with cdk-aws-observability-accelerator solution.

Ubuntu Setup¶

Follow the below steps to setup and leverage cdk-aws-observability-accelerator in your Ubuntu Linux machine.

Update the package list

Update the package list to ensure you're installing the latest versions.

sudo apt update

Install make

sudo apt install make

Install Node.js and npm

Install Node.js and npm using the NodeSource binary distributions.

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - &&\
sudo apt-get install -y nodejs

Note: The Node.js package from NodeSource includes npm

Verify Node.js and npm Installation

Check the installed version of Node.js:

node -v

The output should be v20.x.x.

Check the installed version of npm:

npm -v

The output should be a version greater than 10.1.x.

If your npm version is not 10.1.x or above, update npm with the following command:

sudo npm install -g npm@latest

Verify the installed version by running npm -v.

Install brew on ubuntu by following instructions as detailed in docs.brew.sh

 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Add Homebrew to your PATH

test -d ~/.linuxbrew && eval "$(~/.linuxbrew/bin/brew shellenv)"
test -d /home/linuxbrew/.linuxbrew && eval "$(/home/linuxbrew/.linux  brew/bin/brew shellenv)"
test -r ~/.bash_profile && echo "eval \"\$($(brew --prefix)/bin/brew shellenv)\"" >> ~/.bash_profile
echo "eval \"\$($(brew --prefix)/bin/brew shellenv)\"" >> ~/.profile

Post completing the above, continue from Step: Repo setup

Mac Setup:¶

Follow the below steps to setup and leverage cdk-aws-observability-accelerator in your local Mac laptop.

Install make and node using brew

brew install make
brew install node

Install npm

sudo npm install -g n
sudo n stable

Make sure the following pre-requisites are met:
Node version is a current stable node version 20.x.x

$ node -v
v20.8.0

Update (provided Node version manager is installed): n stable. May require sudo.

NPM version must be 10.1 or above:

$ npm -v
10.1.0

Updating npm: sudo n stable where stable can also be a specific version above 10.1. May require sudo.

Repo setup¶

Clone the cdk-aws-observability-accelerator repository

git clone https://github.com/aws-observability/cdk-aws-observability-accelerator.git

PS: If you are contributing to this repo, please make sure to fork the repo, add your changes and create a PR against it.

Once you have cloned the repo, you can open it using your favourite IDE and run the below commands to install the dependencies and build the existing patterns.
Install project dependencies.

make deps

To view patterns that are available to be deployed, execute the following:

make build

To list the existing CDK AWS Observability Accelerator Patterns

make list

Note: Some patterns have a hard dependency on AWS Secrets (for example GitHub access tokens). Initially you will see errors complaining about lack of the required secrets. It is normal. At the bottom, it will show the list of patterns which can be deployed, in case the pattern you are looking for is not available, it is due to the hard dependency which can be fixed by following the docs specific to those patterns.

To work with patterns use:
    $ make pattern <pattern-name> <list | deploy | synth | destroy>
Example:
    $ make pattern single-new-eks-opensource-observability deploy

Patterns: 

        existing-eks-awsnative-observability
        existing-eks-mixed-observability
        existing-eks-opensource-observability
        multi-acc-new-eks-mixed-observability
        single-new-eks-awsnative-fargate-observability
        single-new-eks-awsnative-observability
        single-new-eks-cluster
        single-new-eks-cost-monitoring
        single-new-eks-fargate-opensource-observability
        single-new-eks-gpu-opensource-observability
        single-new-eks-graviton-opensource-observability
        single-new-eks-inferentia-opensource-observability
        single-new-eks-mixed-observability
        single-new-eks-opensource-observability

Bootstrap your CDK environment.

npx cdk bootstrap

You can then deploy a specific pattern with the following:

make pattern single-new-eks-opensource-observability deploy

To access instructions for individual patterns check documentation in docs/patterns directory.

Developer Flow¶

Modifications¶

All files are compiled to the dist folder including lib and bin directories. For iterative development (e.g. if you make a change to any of the patterns) make sure to run compile:

make compile

The compile command is optimized to build only modified files and is fast.

New Patterns¶

To create a new pattern, please follow these steps:

Under lib create a folder for your pattern, such as <pattern-name>-pattern. If you plan to create a set of patterns that represent a particular subdomain, e.g. security or hardening, please create an issue to discuss it first. If approved, you will be able to create a folder with your subdomain name and group your pattern constructs under it.
Blueprints generally don't require a specific class, however we use a convention of wrapping each pattern in a plain class like <Pattern-Name>Pattern. This class is generally placed in index.ts under your pattern folder.
Once the pattern implementation is ready, you need to include it in the list of the patterns by creating a file bin/<pattern-name>.ts. The implementation of this file is very light, and it is done to allow patterns to run independently.

Example simple synchronous pattern:

import SingleNewEksOpenSourceobservabilityPattern from '../lib/single-new-eks-opensource-observability-pattern';
import { configureApp } from '../lib/common/construct-utils';

const app = configureApp();

new SingleNewEksOpenSourceobservabilityPattern(app, 'single-new-eks-opensource');
 // configureApp() will create app and configure loggers and perform other prep steps

Security¶

See CONTRIBUTING for more information.

License¶

This library is licensed under the MIT-0 License. See the LICENSE file.