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

Update docs (#172)

Browse Source
This commit is contained in:
Rodrigue Koffi
2023-06-06 08:19:22 +02:00
committed by GitHub
parent 0392f5bda0
commit 1f16bec27f
7 changed files with 92 additions and 303 deletions
Download Patch File Download Diff File Expand all files Collapse all files
examples/eks-cluster-with-vpc/README.md
+1 -90
View File
@@ -8,93 +8,4 @@ This example deploys the following Basic EKS Cluster with VPC
- Creates Internet gateway for Public Subnets and NAT Gateway for Private Subnets
- Creates EKS Cluster Control plane with one managed node group
## How to Deploy
### Prerequisites
Ensure that you have installed the following tools in your Mac or Windows Laptop before start working with this module and run Terraform Plan and Apply
1. [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)
2. [Kubectl](https://Kubernetes.io/docs/tasks/tools/)
3. [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)
### Minimum IAM Policy
> **Note**: The policy resource is set as `*` to allow all resources, this is not a recommended practice.
You can find the policy [here](min-iam-policy.json)
### Deployment Steps
#### Step 1: Clone the repo using the command below
```sh
git clone https://github.com/aws-observability/terraform-aws-observability-accelerator.git
```
#### Step 2: Run Terraform INIT
Initialize a working directory with configuration files
```sh
cd examples/eks-cluster-with-vpc/
terraform init
```
#### Step 3: Run Terraform PLAN
Verify the resources created by this execution
```sh
export TF_VAR_aws_region=<ENTER YOUR REGION> # Select your own region
export TF_VAR_cluster_name=<ENTER YOUR CLUSTER NAME> # Enter your cluster name
terraform plan
```
#### Step 4: Finally, Terraform APPLY
**Deploy the pattern**
```sh
terraform apply
```
Enter `yes` to apply.
### Configure `kubectl` and test cluster
EKS Cluster details can be extracted from terraform output or from AWS Console to get the name of cluster.
This following command used to update the `kubeconfig` in your local machine where you run kubectl commands to interact with your EKS Cluster.
#### Step 5: Run `update-kubeconfig` command
`~/.kube/config` file gets updated with cluster details and certificate from the below command
aws eks --region <enter-your-region> update-kubeconfig --name <cluster-name>
#### Step 6: List all the worker nodes by running the command below
kubectl get nodes
#### Step 7: List all the pods running in `kube-system` namespace
kubectl get pods -n kube-system
## Cleanup
To clean up your environment, destroy the Terraform modules in reverse order.
Destroy the Kubernetes Add-ons, EKS cluster with Node groups and VPC
```sh
terraform destroy -target="module.eks_blueprints_kubernetes_addons" -auto-approve
terraform destroy -target="module.eks_blueprints" -auto-approve
terraform destroy -target="module.vpc" -auto-approve
```
Finally, destroy any additional resources that are not in the above modules
```sh
terraform destroy -auto-approve
```
You can view the full documentation for this example [here](https://aws-observability.github.io/terraform-aws-observability-accelerator/helpers/new-eks-cluster/)
examples/existing-cluster-with-base-and-infra/README.md
+1 -121
View File
@@ -11,127 +11,7 @@ to provide an existing EKS cluster with an OpenTelemetry collector,
curated Grafana dashboards, Prometheus alerting and recording rules with multiple
configuration options on the cluster infrastructure.
## Prerequisites
Ensure that you have the following tools installed locally:
1. [aws cli v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
2. [kubectl](https://kubernetes.io/docs/tasks/tools/)
3. [terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)
## Setup
This example uses a local terraform state. If you need states to be saved remotely,
on Amazon S3 for example, visit the [terraform remote states](https://www.terraform.io/language/state/remote) documentation
1. Clone the repo using the command below
```
git clone https://github.com/aws-observability/terraform-aws-observability-accelerator.git
```
2. Initialize terraform
```console
cd examples/existing-cluster-with-base-and-infra
terraform init
```
3. Amazon EKS Cluster
To run this example, you need to provide your EKS cluster name.
If you don't have a cluster ready, visit [this example](../eks-cluster-with-vpc)
first to create a new one.
Add your cluster name for `eks_cluster_id="..."` to a new `terraform.tfvars` file
or use an environment variable `export TF_VAR_eks_cluster_id=xxx`.
4. 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
`export TF_VAR_managed_grafana_workspace_id=g-xxx`.
To create a new one, visit [this example](../managed-grafana-workspace).
> In the URL `https://g-xyz.grafana-workspace.eu-central-1.amazonaws.com`, the workspace ID would be `g-xyz`
5. <a name="apikey"></a> Grafana API Key
Amazon Managed Service for Grafana provides a control plane API for generating Grafana API keys. We will provide to Terraform
a short lived API key to run the `apply` or `destroy` command.
Ensure you have necessary IAM permissions (`CreateWorkspaceApiKey, DeleteWorkspaceApiKey`)
```sh
export TF_VAR_grafana_api_key=`aws grafana create-workspace-api-key --key-name "observability-accelerator-$(date +%s)" --key-role ADMIN --seconds-to-live 1200 --workspace-id $TF_VAR_managed_grafana_workspace_id --query key --output text`
```
## Deploy
```sh
terraform apply -var-file=terraform.tfvars
```
or if you had only setup environment variables, run
```sh
terraform apply
```
## Additional configuration
For the purpose of the example, we have provided default values for some of the variables.
1. AWS Region
Specify the AWS Region where the resources will be deployed. Edit the `terraform.tfvars` file and modify `aws_region="..."`. You can also use environement variables `export TF_VAR_aws_region=xxx`.
2. Amazon Managed Service for Prometheus workspace
If you have an existing workspace, add `managed_prometheus_workspace_id=ws-xxx`
or use an environment variable `export TF_VAR_managed_prometheus_workspace_id=ws-xxx`.
## Visualization
1. Prometheus datasource on Grafana
Make sure to open the link in the output. After a successful deployment, this will open
the Prometheus datasource configuration on Grafana.
Click `Save & test` and you should see a notification confirming that the Amazon Managed Service for Prometheus workspace is ready to be used on Grafana.
```bash
terraform output grafana_prometheus_datasource_test
```
2. Grafana dashboards
Go to the Dashboards panel of your Grafana workspace. You should see a list of dashboards under the `Observability Accelerator Dashboards`
<img width="1540" alt="image" src="https://user-images.githubusercontent.com/10175027/190000716-29e16698-7c90-49d6-8c37-79ca1790e2cc.png">
Open a specific dashboard and you should be able to view its visualization
<img width="1721" alt="Screenshot 2022-08-30 at 20 01 32" src="https://user-images.githubusercontent.com/10175027/187515925-67864dd1-2b35-4be0-a15e-1e36805e8b29.png">
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 should find new rules deployed.
<img width="1629" alt="image" src="https://user-images.githubusercontent.com/10175027/189301297-4865e75d-2d71-434f-b5d0-9750b3533632.png">
To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html)
## Destroy resources
If you leave this stack running, you will incur charges. To remove all resources
created by Terraform, [refresh your Grafana API key](#apikey) and run:
```sh
terraform destroy -var-file=terraform.tfvars
```
View the full documentation for this example [here](https://aws-observability.github.io/terraform-aws-observability-accelerator/eks/)
<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->