From 0b2023492f1661c353d35754645e6fbc658dcbd1 Mon Sep 17 00:00:00 2001 From: Kevin Lewin <97046295+lewinkedrs@users.noreply.github.com> Date: Tue, 7 Feb 2023 15:27:25 -0500 Subject: [PATCH] Docs prettify (#112) * docs admonitions * removing test files * Revert "docs admonitions" This reverts commit a76ce7804e03b6f1a44c31fa2c6933345bfdd836. * docs improvements * removing broken links * updating diagram --- docs/concepts.md | 14 +++++++++----- docs/eks/destroy.md | 7 ++++--- docs/eks/index.md | 8 ++++---- docs/helpers/new-eks-cluster.md | 7 ++++--- docs/images/example-diagram.svg | 1 + docs/index.md | 17 +++++++++-------- docs/workloads/java.md | 15 ++++++++------- docs/workloads/managed-prometheus.md | 8 ++++---- docs/workloads/nginx.md | 15 ++++++++------- 9 files changed, 51 insertions(+), 41 deletions(-) create mode 100644 docs/images/example-diagram.svg diff --git a/docs/concepts.md b/docs/concepts.md index 410b23c..cf204f9 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -13,8 +13,9 @@ All examples in this repository require the following tools installed To run the examples, you need a set of AWS IAM permissions. You can find an example of minimum permissions required [in this file](https://github.com/aws-observability/terraform-aws-observability-accelerator/blob/main/docs/iam/min-iam-policy.json). -> **Note**: The policy resource is set as `*` to allow all resources, this is not a recommended practice. -You should restrict instead to the ARNs when applicable. +!!! warning + The policy resource is set as `*` to allow all resources, this is not a recommended practice. + You should restrict instead to the ARNs when applicable. ### Terraform states and variables @@ -27,7 +28,8 @@ You can also edit the `terraform.tfvars` files directly and deploy with `terraform apply -var-file=terraform.tfvars`. Terraform tfvars file can be useful if you need to track changes as part of a Git repository or CI/CD pipeline. -> **Note:** When using `tfvars` files, always be careful to not store and commit any secrets (keys, passwords, ...) +!!! warning + When using `tfvars` files, always be careful to not store and commit any secrets (keys, passwords, ...) ## Base module @@ -53,7 +55,7 @@ module "eks_observability_accelerator" { } ``` -You can optionally reuse an existing Amazon Managed Servce for Prometheus Workspace: +You can optionally reuse an existing Amazon Managed Service for Prometheus Workspace: ```hcl module "eks_observability_accelerator" { @@ -89,7 +91,9 @@ All the modules come with end-to-end deployable examples. [Examples](https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/examples) put modules together in a ready to deploy terraform configuration as a starting point. With little to no configuration, you can run `terraform apply` and use the deployed resources on your AWS Account. -You can find **workload** examples like [Amazon EKS infrstructure monitoring](https://aws-observability.github.io/terraform-aws-observability-accelerator/eks/) or [monitoring your Amazon Managed Service for Prometheus workspace](https://aws-observability.github.io/terraform-aws-observability-accelerator/workloads/managed-prometheus/) and more. +You can find **workload** examples like [Amazon EKS infrastructure monitoring](https://aws-observability.github.io/terraform-aws-observability-accelerator/eks/) or [monitoring your Amazon Managed Service for Prometheus workspace](https://aws-observability.github.io/terraform-aws-observability-accelerator/workloads/managed-prometheus/) and more. + +![example diagram](images/example-diagram.svg) ## Getting started with AWS Observability services diff --git a/docs/eks/destroy.md b/docs/eks/destroy.md index 831ad16..ca07449 100644 --- a/docs/eks/destroy.md +++ b/docs/eks/destroy.md @@ -3,9 +3,10 @@ If you leave this stack running, you will continue to incur charges. To remove all resources created by Terraform, [refresh your Grafana API key](https://aws-observability.github.io/terraform-aws-observability-accelerator/eks/#6-grafana-api-key) and run the command below. -Be careful, this command will removing everything created by Terraform. If you wish -to keep your Amazon Managed Grafana or Amazon Managed Service for Prometheus workspaces. Remove them -from your terraform state before running the destroy command. +!!! warning + Be careful, this command will removing everything created by Terraform. If you wish + to keep your Amazon Managed Grafana or Amazon Managed Service for Prometheus workspaces. Remove them + from your terraform state before running the destroy command. ```bash terraform destroy diff --git a/docs/eks/index.md b/docs/eks/index.md index 05475de..faa69f7 100644 --- a/docs/eks/index.md +++ b/docs/eks/index.md @@ -22,8 +22,8 @@ on your EKS cluster. ## Prerequisites -Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) -before proceeding. +!!! note + Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) before proceeding. ## Setup @@ -132,8 +132,8 @@ Open the Amazon Managed Service for Prometheus console and view the details of y image - -To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html) +!!! note + To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html) ## Custom metrics collection diff --git a/docs/helpers/new-eks-cluster.md b/docs/helpers/new-eks-cluster.md index c4ece12..59bec48 100644 --- a/docs/helpers/new-eks-cluster.md +++ b/docs/helpers/new-eks-cluster.md @@ -1,6 +1,7 @@ # Creating a new Amazon EKS cluster with VPC -> Note: This example is a subset from [this EKS Blueprint example](https://github.com/aws-ia/terraform-aws-eks-blueprints/tree/main/examples/eks-cluster-with-new-vpc) +!!! note + This example is a subset from [this EKS Blueprint example](https://github.com/aws-ia/terraform-aws-eks-blueprints/tree/main/examples/eks-cluster-with-new-vpc) This example deploys the following: @@ -10,8 +11,8 @@ This example deploys the following: ## Prerequisites -Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) -before proceeding. +!!! note + Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) before proceeding. ## Setup diff --git a/docs/images/example-diagram.svg b/docs/images/example-diagram.svg new file mode 100644 index 0000000..2d77f3b --- /dev/null +++ b/docs/images/example-diagram.svg @@ -0,0 +1 @@ +
Example
BaseModule
Amazon Managed Prometheus
Amazon Distro for Open Telemetry
WorkloadModule
Amazon Distro for Open Telemetry Config
Amazon Managed Grafana Dashboards
Amazon Managed Prometheus Alerts
 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index ea07755..4967afd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,7 @@ Welcome to the AWS Observability Accelerator for Terraform! The AWS Observability accelerator is a set of Terraform modules to help you -configure Observability for your container workloads and environemnts with AWS +configure Observability for your container workloads and environments with AWS Observability services. This project proposes a core module to bootstrap your Amazon EKS cluster with the AWS Distro for OpenTelemetry (ADOT) Operator for EKS, Amazon Managed Service for Prometheus, Amazon Managed Grafana. @@ -23,19 +23,20 @@ dashboards and alerts for monitoring: - Java/JMX workloads (running on Amazon EKS) - Amazon Managed Service for Prometheus workspaces with Amazon CloudWatch -These modules can be directly configured in your exisiting Terraform configurations or ready +These modules can be directly configured in your existing Terraform configurations or ready to be deployed in our packaged [examples](https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/examples) -We have supporting examples for quick setup such as: +!!! tip + We have supporting examples for quick setup such as: -- Creating an empty Amazon EKS cluster and a VPC -- Creating and configure an Amazon Managed Grafana workspace with SSO + - Creating an empty Amazon EKS cluster and a VPC + - Creating and configure an Amazon Managed Grafana workspace with SSO ## Motivation -To gain deep visibility into your workloads and environements, AWS proposes a -set of secure, scalabale, highly available, production-grade managed open +To gain deep visibility into your workloads and environments, AWS proposes a +set of secure, scalable, highly available, production-grade managed open source services such as Amazon Managed Service for Prometheus, Amazon Managed Grafana and Amazon OpenSearch. @@ -43,7 +44,7 @@ AWS customers have asked for best-practices and guidance to collect metrics, log and traces from their containerized applications and microservices with ease of deployment. Customers can use the AWS Observability Accelerator to configure their metrics collection, leveraging [AWS Distro for OpenTelemetry](https://aws-otel.github.io/), -to have opinionated dashoards and alerts available in only minutes. +to have opinionated dashboards and alerts available in only minutes. ## Support & Feedback diff --git a/docs/workloads/java.md b/docs/workloads/java.md index ca0b313..545ac6f 100644 --- a/docs/workloads/java.md +++ b/docs/workloads/java.md @@ -7,8 +7,8 @@ configuration options on the cluster infrastructure. ## Prerequisites -Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) -before proceeding. +!!! note + Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) before proceeding. ## Setup @@ -118,8 +118,8 @@ Open the Amazon Managed Service for Prometheus console and view the details of y image - -To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html) +!!! note + To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html) ## Deploy an Example Java Application @@ -178,9 +178,10 @@ tomcat-traffic-generator 1/1 Running 0 11s If you leave this stack running, you will continue to incur charges. To remove all resources created by Terraform, [refresh your Grafana API key](#6-grafana-api-key) and run the command below. -Be careful, this command will removing everything created by Terraform. If you wish -to keep your Amazon Managed Grafana or Amazon Managed Service for Prometheus workspaces. Remove them -from your terraform state before running the destroy command. +!!! warning + Be careful, this command will removing everything created by Terraform. If you wish + to keep your Amazon Managed Grafana or Amazon Managed Service for Prometheus workspaces. Remove them + from your terraform state before running the destroy command. ```bash terraform destroy diff --git a/docs/workloads/managed-prometheus.md b/docs/workloads/managed-prometheus.md index a843202..e8b2c7e 100644 --- a/docs/workloads/managed-prometheus.md +++ b/docs/workloads/managed-prometheus.md @@ -7,10 +7,10 @@ workspace dashboard. ## Prerequisites -Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) -before proceeding. - -> This example doesn't require an Amazon EKS cluster and Kubernetes tools (ex. `kubectl`). +!!! note + Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) + before proceeding. + This example doesn't require an Amazon EKS cluster and Kubernetes tools (ex. `kubectl`). ## Setup diff --git a/docs/workloads/nginx.md b/docs/workloads/nginx.md index 6a41583..e5aad86 100644 --- a/docs/workloads/nginx.md +++ b/docs/workloads/nginx.md @@ -8,8 +8,8 @@ configuration options on the cluster infrastructure. ## Prerequisites -Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) -before proceeding. +!!! note + Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) before proceeding. ## Setup @@ -118,8 +118,8 @@ Open the Amazon Managed Service for Prometheus console and view the details of y image - -To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html) +!!! note + To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html) ## Deploy an Example Application to Visualize @@ -178,9 +178,10 @@ Log back into your Managed Grafana Workspace and navigate to the dashboard side If you leave this stack running, you will continue to incur charges. To remove all resources created by Terraform, [refresh your Grafana API key](#6-grafana-api-key) and run the command below. -Be careful, this command will removing everything created by Terraform. If you wish -to keep your Amazon Managed Grafana or Amazon Managed Service for Prometheus workspaces. Remove them -from your terraform state before running the destroy command. +!!! warning + Be careful, this command will removing everything created by Terraform. If you wish + to keep your Amazon Managed Grafana or Amazon Managed Service for Prometheus workspaces. Remove them + from your terraform state before running the destroy command. ```bash terraform destroy