AWS Observability Accelerator for Terraform

Welcome to the AWS Observability Accelerator for Terraform!

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

We provide curated metrics, logs, traces collection, alerting rules and Grafana dashboards for your EKS infrastructure, Java/JMX, NGINX based workloads and your custom applications.

You also can monitor your Amazon Managed Service for Prometheus workspaces ingestion, costs, active series with this module.

Documentation

To explore the complete project documentation, please visit our documentation site.

Getting started

To quickstart with a complete workflow and view Amazon EKS infrastructure dashboards, visit the Amazon EKS cluster monitoring documentation

How it works

The sections below demonstrate how you can leverage AWS Observability Accelerator to enable monitoring to an existing EKS cluster.

v2.x changes

v2+ releases introduces couple of breaking changes compared to previous versions:

modules/workloads/infra module moves to modules/eks-monitoring
All EKS configuration options moves from the base module to the eks-monitoring module
All EKS workload modules modules/workloads/{java,nginx} merge into eks-monitoring as configuration options (patterns), see examples to provide a more complete visiblity
All examples have been updated to reflect these changes

Base Module

The base module allows you to configure the AWS Observability services for your cluster and the AWS Distro for OpenTelemetry (ADOT) Operator as the signals collection mechanism.

This is the minimum configuration to have a new Amazon Managed Service for Prometheus Workspace and ADOT Operator deployed for you and ready to receive your data. The base module serve as an anchor to the workload modules and cannot run on its own.

module "aws_observability_accelerator" {
  # use release tags and check for the latest versions
  # https://github.com/aws-observability/terraform-aws-observability-accelerator/releases
  source = "github.com/aws-observability/terraform-aws-observability-accelerator?ref=v2.1.0"

  aws_region     = "eu-west-1"
  eks_cluster_id = "my-eks-cluster"

  # As Grafana shares a different lifecycle, we recommend using an existing workspace.
  managed_grafana_workspace_id = var.managed_grafana_workspace_id
  grafana_api_key              = var.grafana_api_key
}

You can optionally reuse an existing Amazon Managed Servce for Prometheus Workspace:

module "aws_observability_accelerator" {
  # use release tags and check for the latest versions
  # https://github.com/aws-observability/terraform-aws-observability-accelerator/releases
  source = "github.com/aws-observability/terraform-aws-observability-accelerator?ref=v2.1.0"

  aws_region     = "eu-west-1"
  eks_cluster_id = "my-eks-cluster"

  # prevents creation of a new Amazon Managed Prometheus workspace
  enable_managed_prometheus = false

  # reusing existing Amazon Managed Prometheus Workspace
  managed_prometheus_workspace_id  = "ws-abcd123..."

  managed_grafana_workspace_id = "g-abcdef123"
  grafana_api_key              = var.grafana_api_key
}

View all the configuration options in the module documentation below.

Workload modules

Workloads modules are provided, which essentially provide curated metrics, logs, traces collection, alerting rules and Grafana dashboards.

Amazon EKS monitoring

module "eks_monitoring" {
  source = "github.com/aws-observability/terraform-aws-observability-accelerator//modules/eks-monitoring?ref=v2.1.0"

  eks_cluster_id = module.eks_observability_accelerator.eks_cluster_id

  dashboards_folder_id            = module.eks_observability_accelerator.grafana_dashboards_folder_id
  managed_prometheus_workspace_id = module.eks_observability_accelerator.managed_prometheus_workspace_id

  managed_prometheus_workspace_endpoint = module.eks_observability_accelerator.managed_prometheus_workspace_endpoint
  managed_prometheus_workspace_region   = module.eks_observability_accelerator.managed_prometheus_workspace_region

  enable_logs = true
  enable_tracing = true
}

Grafana Dashboards

Check the the complete example

Motivation

To gain deep visibility into your workloads and environments, AWS proposes a set of secure, scalable, highly available, production-grade managed open source services such as Amazon Managed Service for Prometheus, Amazon Managed Grafana and Amazon OpenSearch.

AWS customers have asked for best-practices and guidance to collect metrics, logs and traces from their containerized applications and microservices with ease of deployment. Customers can use the AWS Observability Accelerator to configure their metrics and traces collection, leveraging AWS Distro for OpenTelemetry, to have opinionated dashboards and alerts available in only minutes.

Support & Feedback

AWS Observability 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 Observability Accelerator community.

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

If you are interested in contributing, see the Contribution guide.

Requirements

Name	Version
terraform	>= 1.1.0
aws	>= 4.0.0
awscc	>= 0.24.0
grafana	1.25.0

Providers

Name	Version
aws	>= 4.0.0
grafana	1.25.0

Modules

No modules.

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_grafana_workspace.this	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
aws_region	AWS Region	`string`	n/a	yes
create_dashboard_folder	Boolean flag to enable Amazon Managed Grafana folder and dashboards	`bool`	`true`	no
create_prometheus_data_source	Boolean flag to enable Amazon Managed Grafana datasource	`bool`	`true`	no
enable_alertmanager	Creates Amazon Managed Service for Prometheus AlertManager for all workloads	`bool`	`false`	no
enable_managed_prometheus	Creates a new Amazon Managed Service for Prometheus Workspace	`bool`	`true`	no
grafana_api_key	Grafana API key for the Amazon Managed Grafana workspace	`string`	n/a	yes
managed_grafana_workspace_id	Amazon Managed Grafana Workspace ID	`string`	`""`	no
managed_prometheus_workspace_id	Amazon Managed Service for Prometheus Workspace ID	`string`	`""`	no
managed_prometheus_workspace_region	Region where Amazon Managed Service for Prometheus is deployed	`string`	`null`	no
tags	Additional tags (e.g. `map('BusinessUnit`,`XYZ`)	`map(string)`	`{}`	no

Outputs

Name	Description
aws_region	AWS Region
grafana_dashboard_folder_created	Boolean value indicating if the module created a dashboard folder in Amazon Managed Grafana
grafana_dashboards_folder_id	Grafana folder ID for automatic dashboards. Required by workload modules
grafana_prometheus_datasource_test	Grafana save & test URL for Amazon Managed Prometheus workspace
managed_grafana_workspace_endpoint	Amazon Managed Grafana workspace endpoint
managed_grafana_workspace_id	Amazon Managed Grafana workspace ID
managed_prometheus_workspace_endpoint	Amazon Managed Prometheus workspace endpoint
managed_prometheus_workspace_id	Amazon Managed Prometheus workspace ID
managed_prometheus_workspace_region	Amazon Managed Prometheus workspace region
prometheus_data_source_created	Boolean value indicating if the module created a prometheus data source in Amazon Managed Grafana

Contributing

See CONTRIBUTING for more information.

License

Apache-2.0 Licensed. See LICENSE.

pelgrim / terraform-aws-observability-accelerator