Observability Builder for Observability Accelerator

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.
+

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 :
+
+- `addNativeObservabilityBuilderAddOns`: This method helps you prepare a blueprint for setting up observability with AWS native services
+- `addOpenSourceObservabilityBuilderAddOns`: This method helps you prepare a blueprint for setting up observability with AWS managed open source services
+- `addMixedObservabilityBuilderAddOns`: 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<blueprints.ClusterAddOn> = [
+            new blueprints.addons.CloudWatchLogsAddon({
+                logGroupPrefix: `/aws/eks/${stackId}`,
+                logRetentionDays: 30
+            }),
+            new blueprints.addons.ContainerInsightsAddOn(),
+            new blueprints.addons.XrayAddOn()
+        ];
+
+        ObservabilityBuilder.builder()
+            .account(account)
+            .region(region)
+            .addNativeObservabilityBuilderAddOns()
+            .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<blueprints.ClusterAddOn> = [
+            new blueprints.addons.CloudWatchLogsAddon({
+                logGroupPrefix: `/aws/eks/${stackId}`,
+                logRetentionDays: 30
+            }),
+            new blueprints.addons.AdotCollectorAddOn(),
+            cloudWatchAdotAddOn,
+            new blueprints.addons.XrayAdotAddOn(),
+        ];
+
+        ObservabilityBuilder.builder()
+            .account(account)
+            .region(region)
+            .addMixedObservabilityBuilderAddOns()
+            .clusterProvider(importClusterProvider)
+            .resourceProvider(blueprints.GlobalResources.Vpc, new blueprints.VpcProvider(vpcId)) 
+            .addOns(...addOns)
+            .build(scope, stackId);
+    }
+}
+```

lib/builders/observability-builder.ts

@@ -0,0 +1,77 @@
+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 {
+
+    public addNativeObservabilityBuilderAddOns(): ObservabilityBuilder {
+        return this.addOns(
+            new blueprints.addons.AwsLoadBalancerControllerAddOn(),
+            new blueprints.addons.CertManagerAddOn(),
+            new blueprints.addons.CoreDnsAddOn(),
+            new blueprints.addons.KubeProxyAddOn(),
+            new blueprints.addons.KubeStateMetricsAddOn(),
+            new blueprints.addons.MetricsServerAddOn(),
+            new blueprints.addons.PrometheusNodeExporterAddOn(),
+            new blueprints.addons.VpcCniAddOn());
+    }
+
+    public addMixedObservabilityBuilderAddOns(): 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(),
+            new blueprints.addons.VpcCniAddOn());
+    }
+
+    public addOpenSourceObservabilityBuilderAddOns(): ObservabilityBuilder {
+        return this.addOns(
+            new blueprints.addons.AwsLoadBalancerControllerAddOn(),
+            new blueprints.addons.AdotCollectorAddOn(),
+            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(),
+            new blueprints.addons.VpcCniAddOn());
+    }
+
+    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));
+    }
+}

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: