storytold/terraform-aws-observability-accelerator
2
0
Fork 0
mirror of https://github.com/storytold/terraform-aws-observability-accelerator.git synced 2026-10-09 00:09:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: improvements (#128)

Browse Source 
Update docs
This commit is contained in:
Rodrigue Koffi
2023-02-27 20:56:12 +01:00
committed by GitHub
parent 5298fb04b2
commit 215933bd19
4 changed files with 44 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+10 -7
View File
@@ -4,13 +4,16 @@
Welcome to the AWS Observability Accelerator for Terraform! Welcome to the AWS Observability Accelerator for Terraform!
The AWS Observability accelerator for Terraform is a set of modules to help you The AWS Observability Accelerator for Terraform is a set of opinionated modules to
configure Observability for your Amazon EKS clusters with AWS Observability services. help you set up observability for your AWS environments with
This project proposes a core module to bootstrap your cluster with the AWS Distro for AWS-managed observability services such as Amazon Managed Service for Prometheus,
OpenTelemetry (ADOT) Operator for EKS, Amazon Managed Service for Prometheus, Amazon Managed Grafana and AWS Distro for OpenTelemetry (ADOT).
Amazon Managed Grafana. Additionally we have a set of workloads modules to
leverage curated ADOT collector configurations, Grafana dashboards, We provide curated metrics, traces collection, alerting rules and Grafana dashboards
Prometheus recording rules and alerts. for your EKS infrastructure, Java/JMX, NGINX based workloads and custom applications.
You also can monitor your Amazon Managed Service for Prometheus workspaces ingestion,
costs, active series with [this module](./modules/managed-prometheus-monitoring).
<img width="1501" alt="image" src="docs/images/dark-o11y-accelerator-amp-xray.png"> <img width="1501" alt="image" src="docs/images/dark-o11y-accelerator-amp-xray.png">
docs/eks/index.md
+12 -12
View File
@@ -1,8 +1,8 @@
# Amazon EKS cluster metrics # Amazon EKS cluster metrics
This example demonstrates how to monitor your Amazon Elastic Kubernetes Service This example demonstrates how to monitor your Amazon Elastic Kubernetes Service
(Amazon EKS) cluster with the Observability Accelerator's EKS (Amazon EKS) cluster with the Observability Accelerator's
[infrastructure module](https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/modules/eks-monitoring). [EKS monitoring module](https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/modules/eks-monitoring).
Monitoring Amazon Elastic Kubernetes Service (Amazon EKS) for metrics has two categories: Monitoring Amazon Elastic Kubernetes Service (Amazon EKS) for metrics has two categories:
the control plane and the Amazon EKS nodes (with Kubernetes objects). the control plane and the Amazon EKS nodes (with Kubernetes objects).
@@ -17,7 +17,7 @@ It provides default dashboards to get a comprehensible visibility on your nodes,
namespaces, pods, and kubelet operations health. Finally, you get curated Prometheus recording rules namespaces, pods, and kubelet operations health. Finally, you get curated Prometheus recording rules
and alerts to operate your cluster. and alerts to operate your cluster.
Additionally, you can optionally collect additional custom Prometheus metrics from your applications running Additionally, you can optionally collect custom Prometheus metrics from your applications running
on your EKS cluster. on your EKS cluster.
## Prerequisites ## Prerequisites
@@ -27,7 +27,7 @@ on your EKS cluster.
## Setup ## Setup
### 1. Download sources and initialize Terraform #### 1. Download sources and initialize Terraform
``` ```
git clone https://github.com/aws-observability/terraform-aws-observability-accelerator.git git clone https://github.com/aws-observability/terraform-aws-observability-accelerator.git
@@ -35,7 +35,7 @@ cd examples/existing-cluster-with-base-and-infra
terraform init terraform init
``` ```
### 2. AWS Region #### 2. AWS Region
Specify the AWS Region where the resources will be deployed: Specify the AWS Region where the resources will be deployed:
@@ -43,7 +43,7 @@ Specify the AWS Region where the resources will be deployed:
export TF_VAR_aws_region=xxx export TF_VAR_aws_region=xxx
``` ```
### 3. Amazon EKS Cluster #### 3. Amazon EKS Cluster
To run this example, you need to provide your EKS cluster name. If you don't To run this example, you need to provide your EKS cluster name. If you don't
have a cluster ready, visit [this example](https://aws-observability.github.io/terraform-aws-observability-accelerator/helpers/new-eks-cluster/) have a cluster ready, visit [this example](https://aws-observability.github.io/terraform-aws-observability-accelerator/helpers/new-eks-cluster/)
@@ -55,7 +55,7 @@ Specify your cluster name:
export TF_VAR_eks_cluster_id=xxx export TF_VAR_eks_cluster_id=xxx
``` ```
### 4. Amazon Managed Service for Prometheus workspace (optional) #### 4. Amazon Managed Service for Prometheus workspace (optional)
By default, we create an Amazon Managed Service for Prometheus workspace for you. By default, we create an Amazon Managed Service for Prometheus workspace for you.
However, if you have an existing workspace you want to reuse, edit and run: However, if you have an existing workspace you want to reuse, edit and run:
@@ -70,7 +70,7 @@ To create a workspace outside of Terraform's state, simply run:
aws amp create-workspace --alias observability-accelerator --query '.workspaceId' --output text aws amp create-workspace --alias observability-accelerator --query '.workspaceId' --output text
``` ```
### 5. Amazon Managed Grafana workspace #### 5. Amazon Managed Grafana workspace
To run this example you need an Amazon Managed Grafana workspace. If you have an existing workspace, create an environment variable as described below. To run this example you need an Amazon Managed Grafana workspace. If you have an existing workspace, create an environment variable as described below.
To create a new workspace, visit our Amazon Managed Grafana [documentation](https://docs.aws.amazon.com/grafana/latest/userguide/getting-started-with-AMG.html). To create a new workspace, visit our Amazon Managed Grafana [documentation](https://docs.aws.amazon.com/grafana/latest/userguide/getting-started-with-AMG.html).
@@ -83,7 +83,7 @@ Make sure to provide the workspace with Amazon Managed Service for Prometheus re
export TF_VAR_managed_grafana_workspace_id=g-xxx export TF_VAR_managed_grafana_workspace_id=g-xxx
``` ```
### 6. Grafana API Key #### 6. Grafana API Key
Amazon Managed Grafana provides a control plane API for generating Grafana API keys. Amazon Managed Grafana provides a control plane API for generating Grafana API keys.
As a security best practice, we will provide to Terraform a short lived API key to As a security best practice, we will provide to Terraform a short lived API key to
@@ -105,7 +105,7 @@ terraform apply
## Visualization ## Visualization
### 1. Prometheus datasource on Grafana #### 1. Prometheus datasource on Grafana
Make sure to open the link in the output. After a successful deployment, this will open Make sure to open the link in the output. After a successful deployment, this will open
the Prometheus datasource configuration on Grafana. the Prometheus datasource configuration on Grafana.
@@ -115,7 +115,7 @@ Click `Save & test` and you should see a notification confirming that the Amazon
terraform output grafana_prometheus_datasource_test terraform output grafana_prometheus_datasource_test
``` ```
### 2. Grafana dashboards #### 2. Grafana dashboards
Go to the Dashboards panel of your Grafana workspace. You should see a list of dashboards under the `Observability Accelerator Dashboards` Go to the Dashboards panel of your Grafana workspace. You should see a list of dashboards under the `Observability Accelerator Dashboards`
@@ -125,7 +125,7 @@ Open a specific dashboard and you should be able to view its visualization
<img width="2056" alt="cluster headlines" src="https://user-images.githubusercontent.com/10175027/199110753-9bc7a9b7-1b45-4598-89d3-32980154080e.png"> <img width="2056" alt="cluster headlines" src="https://user-images.githubusercontent.com/10175027/199110753-9bc7a9b7-1b45-4598-89d3-32980154080e.png">
### 3. Amazon Managed Service for Prometheus rules and alerts #### 3. Amazon Managed Service for Prometheus rules and alerts
Open the Amazon Managed Service for Prometheus console and view the details of your workspace. Under the `Rules management` tab, you should find new rules deployed. Open the Amazon Managed Service for Prometheus console and view the details of your workspace. Under the `Rules management` tab, you should find new rules deployed.
docs/eks/java.md
+14 -9
View File
@@ -11,7 +11,7 @@ configuration options for Java based workloads on EKS.
## Setup ## Setup
### 1. Add Java metrics, dashboards and alerts #### 1. Add Java metrics, dashboards and alerts
From the [previous example's](https://aws-observability.github.io/terraform-aws-observability-accelerator/eks/) configuration, From the [previous example's](https://aws-observability.github.io/terraform-aws-observability-accelerator/eks/) configuration,
simply enable the Java pattern's flag. simply enable the Java pattern's flag.
@@ -26,7 +26,7 @@ module "eks_monitoring" {
You can further customize the Java pattern by providing `java_config` [options](https://github.com/aws-observability/terraform-aws-observability-accelerator/blob/main/modules/eks-monitoring/README.md#input_java_config). You can further customize the Java pattern by providing `java_config` [options](https://github.com/aws-observability/terraform-aws-observability-accelerator/blob/main/modules/eks-monitoring/README.md#input_java_config).
### 2. Grafana API key #### 2. Grafana API key
Make sure to refresh your temporary Grafana API key Make sure to refresh your temporary Grafana API key
@@ -48,7 +48,7 @@ terraform apply
## Visualization ## Visualization
1. Grafana dashboards #### 1. Grafana dashboards
Go to the Dashboards panel of your Grafana workspace. There will be a folder called `Observability Accelerator Dashboards` Go to the Dashboards panel of your Grafana workspace. There will be a folder called `Observability Accelerator Dashboards`
@@ -58,7 +58,7 @@ Open the "Java/JMX" dashboard to view its visualization
<img width="2560" alt="Grafana Java dashboard" src="https://user-images.githubusercontent.com/10175027/217821001-2119c81f-94bd-4811-8bbb-caaf1ae5a77a.png"> <img width="2560" alt="Grafana Java dashboard" src="https://user-images.githubusercontent.com/10175027/217821001-2119c81f-94bd-4811-8bbb-caaf1ae5a77a.png">
2. Amazon Managed Service for Prometheus rules and alerts #### 2. Amazon Managed Service for Prometheus rules and alerts
Open the Amazon Managed Service for Prometheus console and view the details of your workspace. Under the `Rules management` tab, you will find new rules deployed. Open the Amazon Managed Service for Prometheus console and view the details of your workspace. Under the `Rules management` tab, you will find new rules deployed.
@@ -72,9 +72,14 @@ Open the Amazon Managed Service for Prometheus console and view the details of y
In this section we will reuse an example from the AWS OpenTelemetry collector [repository](https://github.com/aws-observability/aws-otel-collector/blob/main/docs/developers/container-insights-eks-jmx.md). For convenience, the steps can be found below. In this section we will reuse an example from the AWS OpenTelemetry collector [repository](https://github.com/aws-observability/aws-otel-collector/blob/main/docs/developers/container-insights-eks-jmx.md). For convenience, the steps can be found below.
1. Clone [this repository](https://github.com/aws-observability/aws-otel-test-framework) and navigate to the `sample-apps/jmx/` directory. #### 1. Clone repository
2. Authenticate to Amazon ECR ```sh
git clone https://github.com/aws-observability/aws-otel-test-framework
cd aws-otel-test-framework/sample-apps/jmx/
```
#### 2. Authenticate to Amazon ECR
```sh ```sh
export AWS_ACCOUNT_ID=`aws sts get-caller-identity --query Account --output text` export AWS_ACCOUNT_ID=`aws sts get-caller-identity --query Account --output text`
@@ -82,7 +87,7 @@ export AWS_REGION={region}
aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com
``` ```
3. Create an Amazon ECR repository #### 3. Create an Amazon ECR repository
```sh ```sh
aws ecr create-repository --repository-name prometheus-sample-tomcat-jmx \ aws ecr create-repository --repository-name prometheus-sample-tomcat-jmx \
@@ -90,14 +95,14 @@ aws ecr create-repository --repository-name prometheus-sample-tomcat-jmx \
--region $AWS_REGION --region $AWS_REGION
``` ```
4. Build Docker image and push to ECR. #### 4. Build Docker image and push to ECR.
```sh ```sh
docker build -t $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/prometheus-sample-tomcat-jmx:latest . docker build -t $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/prometheus-sample-tomcat-jmx:latest .
docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/prometheus-sample-tomcat-jmx:latest docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/prometheus-sample-tomcat-jmx:latest
``` ```
5. Install sample application #### 5. Install sample application
```sh ```sh
export SAMPLE_TRAFFIC_NAMESPACE=javajmx-sample export SAMPLE_TRAFFIC_NAMESPACE=javajmx-sample
docs/index.md
+8 -9
View File
@@ -2,14 +2,13 @@
Welcome to the AWS Observability Accelerator for Terraform! Welcome to the AWS Observability Accelerator for Terraform!
The AWS Observability accelerator is a set of Terraform modules to help you The AWS Observability Accelerator for Terraform is a set of opinionated modules to
configure Observability for your container workloads and environments with AWS help you set up observability for your AWS environments with
Observability services. This project proposes a core module to bootstrap AWS-managed observability services such as Amazon Managed Service for Prometheus,
your Amazon EKS cluster with the AWS Distro for OpenTelemetry (ADOT) Operator for EKS, Amazon Managed Grafana and AWS Distro for OpenTelemetry (ADOT).
Amazon Managed Service for Prometheus, Amazon Managed Grafana.
Additionally we have a set of workload modules to leverage curated ADOT We provide curated metrics, traces collection, alerting rules and Grafana dashboards
collector configurations, Grafana dashboards, Prometheus recording rules and alerts. for your EKS infrastructure, Java/JMX, NGINX based workloads and custom applications.
<img width="1501" alt="image" src="images/dark-o11y-accelerator-amp-xray.png"> <img width="1501" alt="image" src="images/dark-o11y-accelerator-amp-xray.png">
@@ -30,7 +29,7 @@ to be deployed in our packaged
!!! tip !!! tip
We have supporting examples for quick setup such as: We have supporting examples for quick setup such as:
- Creating an empty Amazon EKS cluster and a VPC - Creating a new Amazon EKS cluster and a VPC
- Creating and configure an Amazon Managed Grafana workspace with SSO (coming soon) - Creating and configure an Amazon Managed Grafana workspace with SSO (coming soon)
## Motivation ## Motivation
@@ -43,7 +42,7 @@ Grafana and Amazon OpenSearch.
AWS customers have asked for best-practices and guidance to collect metrics, logs AWS customers have asked for best-practices and guidance to collect metrics, logs
and traces from their containerized applications and microservices with ease of and traces from their containerized applications and microservices with ease of
deployment. Customers can use the AWS Observability Accelerator to configure their deployment. Customers can use the AWS Observability Accelerator to configure their
metrics collection, leveraging [AWS Distro for OpenTelemetry](https://aws-otel.github.io/), metrics and traces collection, leveraging [AWS Distro for OpenTelemetry](https://aws-otel.github.io/),
to have opinionated dashboards and alerts available in only minutes. to have opinionated dashboards and alerts available in only minutes.