diff --git a/examples/existing-cluster-with-base-and-infra/README.md b/examples/existing-cluster-with-base-and-infra/README.md index 72e0460..48f0bc3 100644 --- a/examples/existing-cluster-with-base-and-infra/README.md +++ b/examples/existing-cluster-with-base-and-infra/README.md @@ -7,26 +7,96 @@ module with Infrastructure monitoring enabled. The current example deploys the [AWS Distro for OpenTelemetry Operator](https://docs.aws.amazon.com/eks/latest/userguide/opentelemetry.html) for Amazon EKS with its requirements and make use of existing Managed Service for Prometheus and Amazon Managed Grafana workspaces. -It also uses the `infrastructure monitoring`, one of our [workloads modules](../../modules/workloads/) +It is based on the `infrastructure monitoring`, one of our [workloads modules](../../modules/workloads/) to provide an existing EKS cluster with an OpenTelemetry collector, curated Grafana dashboards, Prometheus alerting and recording rules with multiple -configuration options. - -#### ⚠️ Grafana API Key +configuration options on the cluster infrastructure. ## Prerequisites -1. EKS cluster -2. Prometheus -3. Grafana +Ensure that you have the following tools installed locally: + +1. [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) +1. [kubectl](https://kubernetes.io/docs/tasks/tools/) +1. [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. Initialize terraform + +```console +terraform init +``` + +1. EKS Cluster + +To run this example, you need to provide your EKS cluster ID. +If you don't have a cluster ready, visit [this example](../new-empty-eks-cluster) first to create a new one. + +Add `eks_cluster_id=xxx` to your `terraform.tfvars` or use an +environment variable `export TF_VAR_eks_cluster_id=xxx`. + +1. 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`. + +If you don't specify anything a new workspace will be created for you. + + +1. Amazon Managed Grafana workspace + + +If you have an existing workspace, add `managed_grafana_workspace_id=g-xxx` +or use an environment variable `export TF_VAR_managed_grafana_workspace_id=g-xxx`. + +If you don't specify anything a new workspace will be created for you. + + +1. 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 into `terraform.tfvars` under the `grafana_api_key` variable (`grafana_api_key="xxx"`) or set as an environment variable on your CLI (`export TF_VAR_grafana_api_key="xxx"`) + ## Deploy +```sh +terraform apply -var terraform.tfvars +``` + +or if you had setup environment variables + ```sh terraform apply ``` +## Advanced configuration + +1. Cross-region Managed Prometheus workspace + +If your existing Managed Prometheus workspace is in another AWS Region, +add this `managed_prometheus_region=xxx` and `managed_prometheus_workspace_id=ws-xxx`. + +1. Cross-region Managed Grafana workspace + +If your existing Managed Prometheus workspace is in another AWS Region, +add this `managed_prometheus_region=xxx` and `managed_prometheus_workspace_id=ws-xxx`. + + ## Requirements