Skip to content

Commit ada6d6c

Browse files
bonclay7bonclay7
committed
Fix comments
1 parent f9a0127 commit ada6d6c

File tree

1 file changed

+57
-104
lines changed

1 file changed

+57
-104
lines changed

‎README.md

Lines changed: 57 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,142 +1,95 @@
11
# AWS Observability Accelerator for Terraform
22

3-
Welcome to AWS Observability Accelerator for Terraform!
3+
Welcome to the AWS Observability Accelerator for Terraform!
44

5-
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.
5+
The AWS Observability accelerator for Terraform is a set of modules to help you
6+
configure Observability for your Amazon EKS clusters with AWS Observability services.
7+
This project proposes a core module to bootstrap your cluster with the AWS Distro for
8+
OpenTelemetry (ADOT) Operator for EKS, Amazon Managed Service for Prometheus (AMP),
9+
Amazon Managed Grafana (AMG). Additionally we have a set of workloads modules to
10+
leverage curated ADOT collector configurations, Grafana dashboards,
11+
Prometheus recording rules and alerts.
612

7-
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.
13+
You can check our [examples](./examples) for different end-to-end integrations scenarios.
814

9-
You can check our examples (https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/examples) for different end-to-end integrations scenarios.
15+
We will be leveraging [EKS Blueprints](https://github.com/aws-ia/terraform-aws-eks-blueprints)
16+
repository to deploy the solution.
1017

11-
We will be leveraging EKS Blueprints (https://github.com/aws-ia/terraform-aws-eks-blueprints) repository to deploy the solution.
18+
## Example Usage
1219

13-
## Getting Started
20+
The sections below demonstrate how you can leverage AWS Observability Accelerator
21+
to enable monitoring to an existing EKS cluster.
1422

15-
Prerequisites for each of the examples are covered with in the examples directory.
23+
### Base Module
1624

17-
## Deployment Steps
18-
Clone the repository that contains the EKS blueprints:
25+
The base module allows you to configure the AWS Observability services for your cluster and
26+
the AWS Distro for OpenTelemetry (ADOT) Operator as the signals collection mechanism.
1927

20-
`git clone https://github.com/aws-observability/terraform-aws-eks-blueprints.git`
28+
This is the minimum configuration to have a new Managed Grafana Workspace, Amazon Managed
29+
Service for Prometheus Workspace, ADOT Operator deployed for you and ready to receive your
30+
data.
2131

22-
23-
# Generate Grafana API Key
24-
25-
* Give admin access to the SSO user you set up when creating the Amazon Managed Grafana Workspace:
26-
* 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.
27-
* Under **Authentication** within **AWS Single Sign-On (SSO)**, click **Configure users and user groups**
28-
* Check the box next to the SSO user you created and click **Make admin**
29-
* From the workspace in the AWS console, click on the `Grafana workspace` URL to open the workspace
30-
* If you don't see the gear icon in the left navigation bar, log out and log back in.
31-
* Click on the gear icon, then click on the **API keys** tab.
32-
* Click **Add API key**, fill in the *Key name* field and select *Admin* as the Role.
33-
* Copy your API key
34-
35-
36-
## Documentation
37-
38-
For complete project documentation, please visit our documentation (https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/docs) site.
39-
40-
## Examples
41-
42-
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.
43-
44-
## Usage
45-
46-
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
47-
48-
### Base Module Snippet
49-
50-
This base module allows you to customize whether you would like to use the existing Managed Service for Prometheus and Amazon Managed Grafana workspaces or you can update to create new workspaces.
51-
52-
`
53-
# deploys the base module
32+
```hcl
5433
module "eks_observability_accelerator" {
55-
# source = "aws-observability/terrarom-aws-observability-accelerator"
56-
source = "../../"
57-
58-
aws_region = var.aws_region
59-
eks_cluster_id = var.eks_cluster_id
34+
source = "aws-observability/terrarom-aws-observability-accelerator"
35+
aws_region = "eu-west-1"
36+
eks_cluster_id = "my-eks-cluster"
37+
}
38+
```
6039

61-
# deploys AWS Distro for OpenTelemetry operator into the cluster
62-
enable_amazon_eks_adot = true
40+
You can optionally reuse existing Workspaces:
6341

64-
# reusing existing certificate manager? defaults to true
65-
enable_cert_manager = true
42+
```hcl
43+
module "eks_observability_accelerator" {
44+
source = "aws-observability/terrarom-aws-observability-accelerator"
45+
aws_region = "eu-west-1"
46+
eks_cluster_id = "my-eks-cluster"
6647
67-
# creates a new AMP workspace, defaults to true
48+
# prevents creation of a new AMP workspace
6849
enable_managed_prometheus = false
6950
70-
# reusing existing AMP -- needs data source for alerting rules
71-
managed_prometheus_workspace_id = var.managed_prometheus_workspace_id
72-
managed_prometheus_workspace_region = null # defaults to the current region, useful for cross region scenarios (same account)
51+
# reusing existing AMP
52+
managed_prometheus_workspace_id = "ws-abcd123..."
7353
74-
# sets up the AMP alert manager at the workspace level
75-
enable_alertmanager = true
76-
77-
# reusing existing Amazon Managed Grafana workspace
54+
# prevents creation of a new AMG workspace
7855
enable_managed_grafana = false
79-
managed_grafana_workspace_id = var.managed_grafana_workspace_id
80-
grafana_api_key = var.grafana_api_key
8156
82-
tags = local.tags
57+
managed_grafana_workspace_id = 'g-abcdef123'
58+
grafana_api_key = var.grafana_api_key
8359
}
84-
`
60+
```
8561

86-
The values being passed either via environment variables or files would be used here to refer to the existing EKS cluster and its region.
62+
View all the configuration options in the module documentation below.
8763

88-
`
89-
aws_region = var.aws_region
90-
eks_cluster_id = var.eks_cluster_id
91-
`
64+
### Workload modules
9265

93-
By default, it tries to use the existing Managed Service for Prometheus and Amazon Managed Grafana workspaces however, you can customize them by toggling the below variables.
66+
We provide also workloads modules which essentially provide curated
67+
metrics collection, alerting rule and Grafana dashboards.
9468

95-
`
96-
# creates a new AMP workspace, defaults to true
97-
enable_managed_prometheus = false
9869

99-
...
70+
#### Infrastructure monitoring
10071

101-
# reusing existing Amazon Managed Grafana workspace
102-
enable_managed_grafana = false
10372

104-
`
10573

106-
You need to turn on `enable_managed_prometheus` and `enable_managed_grafana` variables to create a new managed workspaces for both Prometheus and Grafana.
74+
```hcl
75+
module "workloads_infra" {
76+
source = "aws-observability/terrarom-aws-observability-accelerator/workloads/infra"
10777
108-
### Example on how to enable monitoring using existing EKS Cluster, Managed Service for Prometheus and Amazon Managed Grafana workspaces by setting up the necessary environment variables.
78+
eks_cluster_id = module.eks_observability_accelerator.eks_cluster_id
10979
110-
1. Make sure to complete the prerequisites and clone the repository.
80+
dashboards_folder_id = module.eks_observability_accelerator.grafana_dashboards_folder_id
81+
managed_prometheus_workspace_id = module.eks_observability_accelerator.managed_prometheus_workspace_id
11182
112-
2. Change the directory
113-
114-
`cd terraform-aws-observability-accelerator/examples/existing-cluster-with-base-and-infra/`
115-
116-
3. Initialize terraform
117-
118-
`terraform init`
119-
120-
`
121-
export TF_VAR_eks_cluster_id=xxx # existing EKS clusterid
122-
export TF_VAR_managed_prometheus_workspace_id=ws-xxx #existing workspace id otherwise new workspace will be created
123-
export TF_VAR_managed_grafana_workspace_id=g-xxx #existing workspace id otherwise new workspace will be created
124-
export TF_VAR_grafana_api_key="xxx" #refer getting started section which shows the steps to create Grafana api key
125-
`
126-
127-
4. Deploy using environment variables
83+
managed_prometheus_workspace_endpoint = module.eks_observability_accelerator.managed_prometheus_workspace_endpoint
84+
managed_prometheus_workspace_region = module.eks_observability_accelerator.managed_prometheus_workspace_region
85+
}
86+
```
12887

129-
`terraform apply`
88+
Grafana dashboard
13089

13190

132-
The code above will provision the following:
13391

134-
* 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
135-
* 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
136-
* Deploys Node_exporter (https://github.com/prometheus/node_exporter) to collect infrastructure metrics like CPU, Memory and Disk size etc
137-
* 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
138-
* Configures the Amazon Managed Service for Prometheus workspace as a datasource in the Amazon Managed Grafana workspace
139-
* 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
92+
To quickstart with a complete workflow, visit the [existing cluster with base and module example](./examples/existing-cluster-with-base-and-infra/)
14093

14194

14295
## Motivation
@@ -227,7 +180,7 @@ If you are interested in contributing to EKS Blueprints, see the Contribution (h
227180
| <a name="output_managed_prometheus_workspace_region"></a> [managed\_prometheus\_workspace\_region](#output\_managed\_prometheus\_workspace\_region) | n/a |
228181
<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
229182

230-
## Security
183+
## Contributing
231184

232185
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
233186

0 commit comments

Comments
 (0)