@aws-quickstart/eks-blueprints

Amazon EKS Blueprints for CDK

Welcome to the Amazon EKS Blueprints for CDK repository.

This repository contains the source code for the eks-blueprints NPM module. eks-blueprints is a CDK construct that makes it easy for customers to build and deploy internal development platforms on top of Amazon EKS.

Documentation

For complete project documentation, please see our official project documentation site.

What is EKS Blueprints?

EKS Blueprints is a framework that helps customers create internal development platforms. It abstracts the complexities of cloud infrastructure from developers, and allows them to deploy workloads with ease. As EKS Blueprints is typically composed of multiple AWS or open source products and services, including services for running containers, CI/CD pipelines, capturing logs/metrics, and security enforcement. The EKS Blueprints packages these tools into a cohesive whole and makes them available to development teams as a service. From an operational perspective, EKS Blueprints allow companies to consolidate tools and best practices for securing, scaling, monitoring, and operating containerized infrastructure into a central platform that can then be used by developers across an enterprise.

What can I do with this QuickStart?

Customers can use this QuickStart to easily architect and deploy a multi-tenant Blueprints built on EKS. Specifically, customers can leverage the eks-blueprints module to:

• Deploy Well-Architected EKS clusters across any number of accounts and regions.
• Manage cluster configuration, including addons that run in each cluster, from a single Git repository.
• Define teams, namespaces, and their associated access permissions for your clusters.
• Create Continuous Delivery (CD) pipelines that are responsible for deploying your infrastructure.
• Leverage GitOps-based workflows for onboarding and managing workloads for your teams.

Examples

To view a library of examples for how you can leverage the eks-blueprints, please see our Blueprints Patterns Repository.

You can also find a sample implementation that resides in this repository in bin/main.ts.

Getting Started

First, make sure you have the aws-cli installed. To verify your installation, run the following:

aws --version
# output aws-cli/2.2.3 Python/3.9.5 Darwin/20.3.0 source/x86_64 prompt/off

Install CDK matching the current version of the Blueprints QuickStart (which can be found in package.json).

npm install -g aws-cdk@2.17.0

Verify the installation.

cdk --version
# must output 2.17.0

Create a new CDK project. We use typescript for this example.

cdk init app --language typescript

Bootstrap your environment.

cdk bootstrap aws://<AWS_ACCOUNT_ID>/<AWS_REGION>

Usage

Run the following command to install the eks-blueprints dependency in your project.

npm i @aws-quickstart/eks-blueprints

Replace the contents of bin/<your-main-file>.ts (where your-main-file by default is the name of the root project directory) with the following:

import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import * as blueprints from '@aws-quickstart/eks-blueprints';

const app = new cdk.App();

// AddOns for the cluster.
const addOns: Array<blueprints.ClusterAddOn> = [
    new blueprints.addons.ArgoCDAddOn,
    new blueprints.addons.CalicoAddOn,
    new blueprints.addons.MetricsServerAddOn,
    new blueprints.addons.ClusterAutoScalerAddOn,
    new blueprints.addons.ContainerInsightsAddOn,
    new blueprints.addons.AwsLoadBalancerControllerAddOn(),
    new blueprints.addons.VpcCniAddOn(),
    new blueprints.addons.CoreDnsAddOn(),
    new blueprints.addons.KubeProxyAddOn(),
    new blueprints.addons.XrayAddOn()
];

const account = 'XXXXXXXXXXXXX'
const region = 'us-east-2'
const props = { env: { account, region } }
new blueprints.EksBlueprint(app, { id: 'east-test-1', addOns}, props)

Note: if the account/region combination used in the code example above is different from the initial combination used with cdk bootstrap, you will need to perform cdk bootstrap again to avoid error.

Please reference CDK usage doc for detail.

Deploy the stack using the following command

cdk deploy

This will provision the following:

• A new Well-Architected VPC with both Public and Private subnets.
• A new Well-Architected EKS cluster in the region and account you specify.
• Nginx into your cluster to serve as a reverse proxy for your workloads.
• ArgoCD into your cluster to support GitOps deployments.
• Calico into your cluster to support Network policies.
• Metrics Server into your cluster to support metrics collection.
• AWS and Kubernetes resources needed to support Cluster Autoscaler.
• AWS and Kubernetes resources needed to forward logs and metrics to Container Insights.
• AWS and Kubernetes resources needed to support AWS Load Balancer Controller.
• Amazon VPC CNI add-on (VpcCni) into your cluster to support native VPC networking for Amazon EKS.
• CoreDNS Amazon EKS add-on (CoreDns) into your cluster. CoreDns is a flexible, extensible DNS server that can serve as the Kubernetes cluster DNS
• kube-proxy Amazon EKS add-on (KubeProxy) into your cluster to maintains network rules on each Amazon EC2 node
• AWS and Kubernetes resources needed to support AWS X-Ray.

---

Why should I use this QuickStart?

The ecosystem of tools that have developed around Kubernetes and the Cloud Native Computing Foundation (CNCF) provides cloud engineers with a wealth of choice when it comes to architecting their infrastructure. Determining the right mix of tools and services however, in addition to how they integrate, can be a challenge. As your Kubernetes estate grows, managing configuration for your clusters can also become a challenge.

AWS customers are building internal platforms to tame this complexity, automate the management of their Kubernetes environments, and make it easy for developers to onboard their workloads. However, these platforms require investment of time and engineering resources to build. The goal of this QuickStart is to provide customers with a tool chain that can help them deploy a Well-Architected platform on top of EKS with ease. The eks-blueprints framework provides logical abstractions and prescriptive guidance for building a platform. Ultimately, we want to help EKS customers accelerate time to market for their own platform initiatives.

Feedback

For architectural details, step-by-step instructions, and customization options, see our official documentation site.

To post feedback, submit feature ideas, or report bugs, use the Issues section of this GitHub repo.

To submit code for this Quick Start, see the AWS Quick Start Contributor's Kit.

License

This library is licensed under the Apache 2.0 License.