diff --git a/docs/builders/index.md b/docs/builders/index.md new file mode 100644 index 000000000..555c505af --- /dev/null +++ b/docs/builders/index.md @@ -0,0 +1,10 @@ +# Builders + +The `eks-blueprints` framework allows customers to use builders to configure required addons as they prepare a blueprint for setting EKS cluster with required day 2 operational tooling + +The framework currently provides support for the following Builders: + +| Builder | Description | +|-------------------|-----------------------------------------------------------------------------------| +| [`ObservabilityBuilder`](./observability-builder.md) | Allows you to get started with a builder class to configure required addons as you prepare a blueprint for setting up Observability on an existing EKS cluster or a new EKS cluster. + diff --git a/docs/builders/observability-builder.md b/docs/builders/observability-builder.md new file mode 100644 index 000000000..ddd29329b --- /dev/null +++ b/docs/builders/observability-builder.md @@ -0,0 +1,121 @@ +# Observability Builder + +The `ObservabilityBuilder` allows you to get started with a builder class to configure required addons as you prepare a blueprint for setting up observability on an existing EKS cluster or a new EKS cluster. + +## Supported Methods + +`ObservabilityBuilder` supports following methods for setting up observability on Amazon EKS : + +- `enableNativePatternAddOns`: This method helps you prepare a blueprint for setting up observability with AWS native services +- `enableMixedPatternAddOns`: This method helps you prepare a blueprint for setting up observability with AWS managed open source services +- `enableOpenSourcePatternAddOns`: This method helps you prepare a blueprint for setting up observability with a combination of AWS native and AWS managed open source services + +## Usage + +The framework provides a couple of convenience methods to instantiate the `` by leveraging the SDK API calls. + +### Usage 1 - Observability For a New EKS Cluster + +The below usage helps you with a demonstration to use `ObservabilityBuilder` to setup required addons as you prepare a blueprint for setting up observability on a new EKS cluster. + +```typescript +import { Construct } from 'constructs'; +import * as blueprints from '@aws-quickstart/eks-blueprints'; +import { ObservabilityBuilder } from '@aws-quickstart/eks-blueprints'; + +export default class SingleNewEksConstruct { + constructor(scope: Construct, id: string) { + const stackId = `${id}-observability-accelerator`; + + const account = process.env.COA_ACCOUNT_ID! || process.env.CDK_DEFAULT_ACCOUNT!; + const region = process.env.COA_AWS_REGION! || process.env.CDK_DEFAULT_REGION!; + + const addOns: Array = [ + new blueprints.addons.CloudWatchLogsAddon({ + logGroupPrefix: `/aws/eks/${stackId}`, + logRetentionDays: 30 + }), + new blueprints.addons.VpcCniAddOn(), + new blueprints.addons.XrayAddOn() + ]; + + ObservabilityBuilder.builder() + .account(account) + .region(region) + .enableNativePatternAddOns() + .addOns(...addOns) + .build(scope, stackId); + } +} + +``` + +### Usage 2 - Observability For an existing EKS Cluster + +The below usage helps you with a demonstration to use `ObservabilityBuilder` to setup required addons as you prepare a blueprint for setting up observability on an existing EKS cluster. + +```typescript +import { ImportClusterProvider, utils } from '@aws-quickstart/eks-blueprints'; +import * as blueprints from '@aws-quickstart/eks-blueprints'; +import { cloudWatchDeploymentMode } from '@aws-quickstart/eks-blueprints'; +import { ObservabilityBuilder } from '@aws-quickstart/eks-blueprints'; +import * as cdk from "aws-cdk-lib"; +import * as eks from 'aws-cdk-lib/aws-eks'; + +export default class ExistingEksMixedobservabilityConstruct { + async buildAsync(scope: cdk.App, id: string) { + // AddOns for the cluster + const stackId = `${id}-observability-accelerator`; + + const clusterName = utils.valueFromContext(scope, "existing.cluster.name", undefined); + const kubectlRoleName = utils.valueFromContext(scope, "existing.kubectl.rolename", undefined); + + const account = process.env.COA_ACCOUNT_ID! || process.env.CDK_DEFAULT_ACCOUNT!; + const region = process.env.COA_AWS_REGION! || process.env.CDK_DEFAULT_REGION!; + + const sdkCluster = await blueprints.describeCluster(clusterName, region); // get cluster information using EKS APIs + const vpcId = sdkCluster.resourcesVpcConfig?.vpcId; + + /** + * Assumes the supplied role is registered in the target cluster for kubectl access. + */ + + const importClusterProvider = new ImportClusterProvider({ + clusterName: sdkCluster.name!, + version: eks.KubernetesVersion.of(sdkCluster.version!), + clusterEndpoint: sdkCluster.endpoint, + openIdConnectProvider: blueprints.getResource(context => + new blueprints.LookupOpenIdConnectProvider(sdkCluster.identity!.oidc!.issuer!).provide(context)), + clusterCertificateAuthorityData: sdkCluster.certificateAuthority?.data, + kubectlRoleArn: blueprints.getResource(context => new blueprints.LookupRoleProvider(kubectlRoleName).provide(context)).roleArn, + clusterSecurityGroupId: sdkCluster.resourcesVpcConfig?.clusterSecurityGroupId + }); + + const cloudWatchAdotAddOn = new blueprints.addons.CloudWatchAdotAddOn({ + deploymentMode: cloudWatchDeploymentMode.DEPLOYMENT, + namespace: 'default', + name: 'adot-collector-cloudwatch', + metricsNameSelectors: ['apiserver_request_.*', 'container_memory_.*', 'container_threads', 'otelcol_process_.*'], + }); + + const addOns: Array = [ + new blueprints.addons.CloudWatchLogsAddon({ + logGroupPrefix: `/aws/eks/${stackId}`, + logRetentionDays: 30 + }), + new blueprints.addons.VpcCniAddOn(), + cloudWatchAdotAddOn, + new blueprints.addons.XrayAdotAddOn(), + ]; + + ObservabilityBuilder.builder() + .account(account) + .region(region) + .enableMixedPatternAddOns() + .clusterProvider(importClusterProvider) + .resourceProvider(blueprints.GlobalResources.Vpc, new blueprints.VpcProvider(vpcId)) + .addOns(...addOns) + .build(scope, stackId); + } +} +``` \ No newline at end of file diff --git a/lib/builders/observability-builder.ts b/lib/builders/observability-builder.ts new file mode 100644 index 000000000..37d237b61 --- /dev/null +++ b/lib/builders/observability-builder.ts @@ -0,0 +1,95 @@ +import * as blueprints from '../../lib'; +import * as utils from "../utils"; +import { NestedStack, NestedStackProps } from 'aws-cdk-lib'; +import { Construct } from 'constructs'; + +export class ObservabilityBuilder extends blueprints.BlueprintBuilder { + + /** + * This method helps you prepare a blueprint for setting up observability + * returning an array of blueprint addons for AWS native services + */ + public enableNativePatternAddOns(): ObservabilityBuilder { + return this.addOns( + new blueprints.addons.AwsLoadBalancerControllerAddOn(), + new blueprints.addons.CertManagerAddOn(), + new blueprints.addons.ContainerInsightsAddOn(), + new blueprints.addons.CoreDnsAddOn(), + new blueprints.addons.KubeProxyAddOn(), + new blueprints.addons.KubeStateMetricsAddOn(), + new blueprints.addons.MetricsServerAddOn(), + new blueprints.addons.PrometheusNodeExporterAddOn()); + } + + /** + * This method helps you prepare a blueprint for setting up observability + * returning an array of blueprint addons for combination of AWS native and + * AWS managed open source services + */ + public enableMixedPatternAddOns(): ObservabilityBuilder { + return this.addOns( + new blueprints.addons.AwsLoadBalancerControllerAddOn(), + new blueprints.addons.AdotCollectorAddOn(), + new blueprints.addons.CertManagerAddOn(), + new blueprints.addons.CoreDnsAddOn(), + new blueprints.addons.KubeProxyAddOn(), + new blueprints.addons.KubeStateMetricsAddOn(), + new blueprints.addons.MetricsServerAddOn(), + new blueprints.addons.PrometheusNodeExporterAddOn()); + } + + /** + * This method helps you prepare a blueprint for setting up observability + * returning an array of blueprint addons for AWS managed open source services + */ + public enableOpenSourcePatternAddOns(ampPrometheusEndpoint: string): ObservabilityBuilder { + return this.addOns( + new blueprints.addons.AwsLoadBalancerControllerAddOn(), + new blueprints.addons.AdotCollectorAddOn(), + new blueprints.addons.AmpAddOn({ + ampPrometheusEndpoint: ampPrometheusEndpoint, + }), + new blueprints.addons.CertManagerAddOn(), + new blueprints.addons.CoreDnsAddOn(), + new blueprints.addons.ExternalsSecretsAddOn(), + new blueprints.addons.GrafanaOperatorAddon(), + new blueprints.addons.KubeProxyAddOn(), + new blueprints.addons.KubeStateMetricsAddOn(), + new blueprints.addons.MetricsServerAddOn(), + new blueprints.addons.PrometheusNodeExporterAddOn()); + } + + /** + * This method helps you prepare a blueprint for setting up observability with + * usage tracking addon + */ + public static builder(): ObservabilityBuilder { + const builder = new ObservabilityBuilder(); + builder.addOns( + new blueprints.NestedStackAddOn({ + id: "usage-tracking-addon", + builder: UsageTrackingAddOn.builder(), + })); + return builder; + } +} + +/** + * Nested stack that is used as tracker for Observability Accelerator + */ +export class UsageTrackingAddOn extends NestedStack { + + static readonly USAGE_ID = "qs-1u9l12gj7"; + + public static builder(): blueprints.NestedStackBuilder { + return { + build(scope: Construct, id: string, props: NestedStackProps) { + return new UsageTrackingAddOn(scope, id, props); + } + }; + } + + constructor(scope: Construct, id: string, props: NestedStackProps) { + super(scope, id, utils.withUsageTracking(UsageTrackingAddOn.USAGE_ID, props)); + } +} diff --git a/mkdocs.yml b/mkdocs.yml index 4ef7b808b..ec03529df 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -99,6 +99,9 @@ nav: - KMS Key Resource Providers: 'resource-providers/kms-key-providers.md' - S3 Bucket Resource Providers: 'resource-providers/s3-providers.md' - VPC Resource Providers: 'resource-providers/vpc-providers.md' + - Builders: + - Overview: 'builders/index.md' + - Observability Builder: 'builders/observability-builder.md' - Extensibility: 'extensibility.md' - API Reference: 'api' markdown_extensions: