AWS Observability Accelerator for Terraform

Welcome to AWS Observability Accelerator for Terraform!

The AWS Observability accelerator for Terraform is a set of modules to help you configure Observability for your Amazon EKS clusters with AWS Observability services.

This project proposes a core module to bootstrap your cluster with the AWS Distro for OpenTelemetry (ADOT) Operator for EKS, Amazon Managed Service for Prometheus (AMP), Amazon Managed Grafana (AMG). Additionally we have a set of workloads modules to leverage curated ADOT collector configurations, Grafana dashboards, Prometheus rules and alerts.

You can check our examples (https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/examples) for different end-to-end integrations scenarios.

We will be leveraging EKS Blueprints (https://github.com/aws-ia/terraform-aws-eks-blueprints) repository to deploy the solution.

Getting Started

Prerequisites for each of the examples are covered with in the examples directory.

Deployment Steps

Clone the repository that contains the EKS blueprints:

git clone https://github.com/aws-observability/terraform-aws-eks-blueprints.git

Generate Grafana API Key

• Give admin access to the SSO user you set up when creating the Amazon Managed Grafana Workspace:
• In the AWS Console, navigate to Amazon Grafana. In the left navigation bar, click All workspaces, then click on the workspace name you are using for this example.
• Under Authentication within AWS Single Sign-On (SSO), click Configure users and user groups
• Check the box next to the SSO user you created and click Make admin
• From the workspace in the AWS console, click on the Grafana workspace URL to open the workspace
• If you don't see the gear icon in the left navigation bar, log out and log back in.
• Click on the gear icon, then click on the API keys tab.
• Click Add API key, fill in the Key name field and select Admin as the Role.
• Copy your API key

Documentation

For complete project documentation, please visit our documentation (https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/docs) site.

Examples

To view examples for how you can leverage AWS Observability accelerator, please see the examples (https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/examples) directory.

Usage

The below demonstrates how you can leverage AWS Observability Accelerator to enable monitoring to an existing EKS cluster, Managed Service for Prometheus and Amazon Managed Grafana workspaces. Configure the environment variables like below

Change the directory

cd terraform-aws-observability-accelerator/examples/existing-cluster-with-base-and-infra/

Initialize terraform

terraform init

export TF_VAR_eks_cluster_id=xxx export TF_VAR_managed_prometheus_workspace_id=ws-xxx #existing workspace id otherwise new workspace will be created export TF_VAR_managed_grafana_workspace_id=g-xxx #existing workspace id otherwise new workspace will be created export TF_VAR_grafana_api_key="xxx" #refer getting started section which shows the steps to create Grafana api key

Deploy

terraform apply

The code above will provision the following:

• Enables the AWS EKS Add-on for ADOT operator (https://docs.aws.amazon.com/eks/latest/userguide/opentelemetry.html) to the existing Amazon EKS Cluster (specified in the environment variable) and deploys the ADOT collector with appropriate scrape configuration to ingest metrics to Amazon Managed Service for Prometheus
• Deploys kube-state-metrics (https://github.com/kubernetes/kube-state-metrics) to generate Prometheus format metrics based on the current state of the Kubernetes native resource
• Deploys Node_exporter (https://github.com/prometheus/node_exporter) to collect infrastructure metrics like CPU, Memory and Disk size etc
• Deploys rule files in the Amazon Managed Service for Prometheus Workspace(specified in the terraform variable file) containing rule groups with over 200 rules to gather metrics about Kubernetes native objects
• Configures the Amazon Managed Service for Prometheus workspace as a datasource in the Amazon Managed Grafana workspace
• Creates an Observability folder within the Amazon Managed Grafana workspace(specified in the terraform variable file) and deploys 25 grafana dashboards which visually displays the metrics collected by Amazon Managed Service for Prometheus

Submodules

The root module calls into several submodules which provides support for deploying and integrating a number of external AWS services that can be used in concert with Amazon EKS. This includes Amazon Managed Prometheus, AWS OpenTelemetry Operator etc..,

Motivation

Kubernetes is a powerful and extensible container orchestration technology that allows you to deploy and manage containerized applications at scale. The extensible nature of Kubernetes also allows you to use a wide range of popular open-source tools, commonly referred to as add-ons, in Kubernetes clusters. With such a large number of tooling and design choices available however, building a tailored EKS cluster that meets your application’s specific needs can take a significant amount of time. It involves integrating a wide range of open-source tools and AWS services and requires deep expertise in AWS and Kubernetes.

AWS customers have asked for examples that demonstrate how to integrate the landscape of Kubernetes tools and make it easy for them to provision complete, opinionated EKS clusters that meet specific application requirements. Customers can use AWS Observability Accelerator to configure and deploy purpose built EKS clusters, and start onboarding workloads in days, rather than months.

Support & Feedback

AWS Oservability Accelerator for Terraform is maintained by AWS Solution Architects. It is not part of an AWS service and support is provided best-effort by the AWS Oservability Accelerator community.

To post feedback, submit feature ideas, or report bugs, please use the Issues (https://github.com/aws-observability/terraform-aws-observability-accelerator/issues) section of this GitHub repo.

If you are interested in contributing to EKS Blueprints, see the Contribution (https://github.com/aws-observability/terraform-aws-observability-accelerator/blob/main/CONTRIBUTING.md) guide.

---

Requirements

Name	Version
terraform	>= 0.14.0
aws	>= 4.0.0, < 5.0.0
awscc	>= 0.24.0
grafana	1.25.0

Providers

Name	Version
aws	>= 4.0.0, < 5.0.0
grafana	1.25.0

Modules

Name	Source	Version
managed_grafana	terraform-aws-modules/managed-service-grafana/aws	~> 1.3
operator	./modules/add-ons/adot-operator	n/a

Resources

Name	Type
aws_prometheus_alert_manager_definition.this	resource
aws_prometheus_workspace.this	resource
grafana_data_source.amp	resource
grafana_folder.this	resource
aws_caller_identity.current	data source
aws_eks_cluster.eks_cluster	data source
aws_grafana_workspace.this	data source
aws_partition.current	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
aws_region	AWS Region	string	n/a	yes
eks_cluster_id	EKS Cluster Id	string	n/a	yes
enable_alertmanager	Create AMP AlertManager for all workloads	bool	false	no
enable_amazon_eks_adot	n/a	bool	true	no
enable_cert_manager	Allow reusing an existing installation of cert-manager	bool	true	no
enable_managed_grafana	n/a	bool	true	no
enable_managed_prometheus	n/a	bool	true	no
grafana_api_key	n/a	string	null	no
irsa_iam_permissions_boundary	IAM permissions boundary for IRSA roles	string	""	no
irsa_iam_role_path	IAM role path for IRSA roles	string	"/"	no
managed_grafana_region	AWS Managed Grafana Workspace Region	string	null	no
managed_grafana_workspace_id	n/a	string	""	no
managed_prometheus_workspace_id	AWS Managed Prometheus Workspace ID	string	""	no
managed_prometheus_workspace_region	AWS Managed Prometheus Workspace Region	string	null	no
tags	Additional tags (e.g. map('BusinessUnit,XYZ)	map(string)	{}	no

Outputs

Name	Description
aws_region	EKS Cluster Id
eks_cluster_id	EKS Cluster Id
eks_cluster_version	n/a
grafana_dashboards_folder_id	n/a
managed_grafana_workspace_endpoint	n/a
managed_prometheus_workspace_endpoint	n/a
managed_prometheus_workspace_id	n/a
managed_prometheus_workspace_region	n/a

Security

See CONTRIBUTING for more information.

License

Apache-2.0 Licensed. See LICENSE.