Merge pull request #10 from aws-observability/existing-cluster-example-doc

Add example doc

Author: bonclay7

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
+<!-- TODO: Remove section when CP Grafana API keys is supported by Terraform -->
+
+- 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`.
+
+
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Requirements