[DOCS-10133] [DOCS-10131] Review/edit CloudBees CD/RO blueprint add-on documentation and diagrams

CONTRIBUTING.md

@@ -1,23 +1,57 @@
 # Contributing
 
-This document provides guidelines for contributing to the module.
+This document provides guidelines for contributing to the CloudBees CD/RO add-on for Amazon EKS blueprints.
 
 ## Dependencies
 
-Validate your changes inside the blueprint-agent described in [.Dockerfile](blueprints/Dockerfile). It can be run `make dBuildAndRun`.
+Validate your changes inside the blueprint agent, as described in [Dockerfile](blueprints/Dockerfile) For example, it can be used to run `make dBuildAndRun`.
 
-## Pre-commits: Linting, Formatting and Secrets Scanning
+<!---
+## Report bugs and feature requests
+
+CloudBees welcomes you to use the GitHub issue tracker to report bugs or suggest features.
+
+When filing an issue:
+
+1. Check existing open and recently closed [issues](https://github.com/cloudbees/terraform-aws-cloudbees-cd-eks-addon/issues) to ensure the issue has not already been reported.
+1. Review the upstream repositories:
+    - [aws-ia/terraform-aws-eks-blueprints](https://github.com/aws-ia/terraform-aws-eks-blueprints/issues)
+    - [aws-ia/terraform-aws-eks-blueprints-addons](https://github.com/aws-ia/terraform-aws-eks-blueprints-addons/issues)
+1. Try to include as much information as you can. Details like the following are incredibly useful:
+    - A reproducible test case or series of steps
+    - The version of code being used
+    - Any modifications you have made relevant to the bug
+    - Anything unusual about your environment or deployment
+
+## Contribute via pull requests
 
-Many of the files in the repository can be linted or formatted to
-maintain a standard of quality.
+Contributions via pull requests are appreciated. Before submitting a pull request, please ensure that you:
 
-Additionally, secret leaks are watched via gitleaks and git-secrets.
+1. Are working against the latest source on the `develop` branch.
+1. Check existing open, and recently merged, pull requests to make sure someone else has not already addressed the problem.
+1. Open an issue to discuss any significant work; we do not want your time to be wasted.
+
+To submit a pull request:
+
+1. Fork the repository.
+1. Create a feature branch based on the `develop` branch.
+1. Modify the source and focus on the specific change you are contributing. For example, if you reformat all the code, it is hard for reviewers to focus on your specific change.
+1. **Ensure that local tests pass**. Local tests can be orchestrated via the companion [Makefile](Makefile).
+1. Make commits to your fork using clear commit messages.
+1. Submit a pull request against the `develop` branch and answer any default questions in the pull request interface.
+1. Pay attention to any automated failures reported in the pull request, and stay involved in the conversation.
+
+> [!IMPORTANT]
+> If you make updates to embedded repository (e.g. CasC bundles), you must push the changes to the public upstream (repository/branch) before running `terraform apply` locally. The endpoint and/or branch can be updated via `set-casc-location` from the companion [Makefile](Makefile).
+-->
+
+## Pre-commits: Linting, Formatting and Secrets Scanning
 
-When working with the repository for the first time run pre-commit
+Many of the files in the repository can be linted or formatted to maintain a standard of quality. Additionally, secret leaks are watched via [gitleaks](https://github.com/zricethezav/gitleaks#pre-commit) and [git-secrets](https://github.com/awslabs/git-secrets).
 
-Run `pre-commit install`
-Run `pre-commit run --all-files`
+1. When working with the repository for the first time, you must install `pre-commit`. For more information, refer to [pre-commit installation](https://pre-commit.com/#installation).
+1. Run `pre-commit run --all-files`. Run this command again if the automated checks fail when you create a pull request.
 
 ## Release Drafter
 
-This repository uses [Release Drafter](https://github.com/release-drafter/release-drafter) thus it is recommended to use [Semantic Commit Messages](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716) to ease labelling your Pull Request accordingly.
+This repository uses [Release Drafter](https://github.com/release-drafter/release-drafter) thus it is recommended to use [Semantic Commit Messages](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716) to ease labelling your pull request accordingly.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 CloudBees
+Copyright (c) 2024 CloudBees
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,8 +1,8 @@
-# CloudBees CD Add-on for AWS EKS
+# CloudBees CD/RO add-on for Amazon EKS blueprints
 
 <p align="center">
   <a href="https://www.cloudbees.com/capabilities/continuous-delivery"><img alt="cloudbees-icon" src="https://images.ctfassets.net/vtn4rfaw6n2j/7FKeUjwsXI1d2JPUIvSMZJ/be286872ace9ca3b6b66a64adbb3c16a/cb-tag-sm.svg?fm=webp&q=85" height="120px" /></a>
-  <p align="center">Deploy CloudBees CD to AWS EKS Clusters with this add-on.</p>
+  <p align="center">Deploy CloudBees CD/RO to Amazon Web Services (AWS) Elastic Kubernetes Service (EKS) clusters
 </p>
 
 ---
@@ -11,17 +11,17 @@
 
 ## Motivation
 
-This [AWS Partner Addon](https://aws-ia.github.io/terraform-aws-eks-blueprints-addons/main/aws-partner-addons/) aims to ease the adoption and experimentation of CloudBees CD enterprise features by:
+The CloudBees CD/RO AWS add-on streamlines the adoption and experimentation of CloudBees CD/RO enterprise features by:
 
-- Encapsulating the Deployment of [CloudBees CD Modern in AWS EKS](https://docs.cloudbees.com/docs/cloudbees-cd/latest/install-k8s/) into a Terraform module.
-- Providing a series of [Blueprints](blueprints) implementing the mentioned CloudBees CD Addon module on top of [AWS Terraform EKS Addons](https://aws-ia.github.io/terraform-aws-eks-blueprints-addons/main/) which are aligned with [EKS Best Practices Guides](https://aws.github.io/aws-eks-best-practices/).
+- Encapsulating the deployment of [CloudBees CD/RO in AWS EKS](https://docs.cloudbees.com/docs/cloudbees-cd/latest/install-k8s/) into a Terraform module.
+- Providing a series of opinionated [blueprints](blueprints) that implement the CloudBees CD/RO add-on module for use with [Amazon EKS blueprints for Terraform](https://aws-ia.github.io/terraform-aws-eks-blueprints-addons/main/) which are aligned with the [EKS Best Practices Guides](https://aws.github.io/aws-eks-best-practices/).
 
-## CD License
-You'll need a valid license to operate the Cloudbees CD server. By default the product use the Server License type. Please visit the [CloudBees CD Licensing](https://docs.cloudbees.com/docs/cloudbees-cd/latest/set-up-cdro/licenses) for more information.
+## CloudBees CD/RO license
+You must have a valid license to operate the CloudBees CD/RO server. By default, CloudBees CD/RO uses the Server License type. For more information, refer to [CloudBees CD/RO Licensing](https://docs.cloudbees.com/docs/cloudbees-cd/latest/set-up-cdro/licenses).
 
 ## Usage
 
-There are examples of implementation included in the [blueprint](blueprints) folder but the simplest example of usage is as follows:
+Implementation examples are included in the [blueprint](blueprints) folder, however this is the simplest example of usage:
 
 ```terraform
 module "eks_blueprints_addon_cbcd" {
@@ -33,46 +33,42 @@ module "eks_blueprints_addon_cbcd" {
 }
 ```
 
-By default, it uses a minimum required configuration described in [values.yml](values.yml).
-
-If you would like to override any defaults with the chart, you can do so by passing the `helm_config` variable.
+By default, it uses a minimum required configuration described in the Helm chart [values.yml](values.yml). If you need to override any default settings with the chart, you can do so by passing the `helm_config` variable.
 
 > [!TIP]
-> Blueprints lifecycle (`deploy` > `validate` > `destroy`) can be orchestrated via the companion [Makefile](Makefile).
+> The blueprints lifecycle (`deploy` > `validate` > `destroy`) can be orchestrated via the companion [Makefile](Makefile).
 
 ## Prerequisites
 
 ### Tooling
 
-Blueprint `deploy` and `destroy` phases use the same tooling requirement per [AWS EKS Blueprints - Getting Started Guide - Prerequisites](https://aws-ia.github.io/terraform-aws-eks-blueprints/getting-started/#prerequisites).
-
-Nevertheless, the Blueprint `validate` phase might require additional toolings like `jq` and `velero`.
+The blueprint `deploy` and `destroy` phases use the same requirements provided in the [AWS EKS Blueprints for Terraform - Prerequisites](https://aws-ia.github.io/terraform-aws-eks-blueprints/getting-started/#prerequisites). However, the blueprint `validate` phase may require additional tooling, such as `jq` and `velero`.
 
 > [!NOTE]
-> There is a companion [Dockerfile](blueprints/Dockerfile) to run the blueprints in a containerized Dev environment ensuring dependecies are met. It can be built by using the [Makefile](Makefile) target `make dRun`.
+> There is a companion [Dockerfile](blueprints/Dockerfile) to run the blueprints in a containerized development environment, ensuring all dependencies are met. It can be built locally using the [Makefile](Makefile) target `make dRun`.
 
-### AWS Authentication
+### AWS authentication
 
-Make sure to export your required [AWS Environment Variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) to your CLI before getting started (eg. `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` or `AWS_PROFILE`).
+Before getting started, you must export your required [AWS Environment Variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) to your CLI before getting started (for example, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_PROFILE`).
 
-### Existing AWS Hosted Zone
+### Existing AWS 53 hosted zone
 
-These blueprints rely on an existing Hosted Zone in AWS Route53. If you don't have one, you can create one by following the [AWS Route53 documentation](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html).
+These blueprints rely on an existing hosted zone in AWS Route 53. If you do not have a hosted zone, you can create one by following the [AWS Rout 53 documentation](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html).
 
-## Data Storage Options
+## Data storage options
 
-The main components of CloudBees CD, use a file system to persist data. Data is stored in a couple of [places](https://docs.cloudbees.com/docs/cloudbees-cd/latest/requirements/k8s-requirements#persist) that can be configured to be stored in Amazon EBS or EFS:
+CloudBees CD/RO uses a file system to persist data. Data is stored in several [locations](https://docs.cloudbees.com/docs/cloudbees-cd/latest/requirements/k8s-requirements#persist) and configured to be stored in Amazon Elastic Block Store (Amazon EBS) or Amazon Elastic File System (Amazon EFS)
 
-- Amazon EBS volumes are scoped to a particular Availability Zone to offer high-speed, low-latency access to the EC2 instances they are connected to. If an Availability Zone fails, an EBS volume becomes inaccessible due to file corruption, or there is a service outage, the data on these volumes will become inaccessible. Operations Center and Managed Controller pods require this persistent data and have no mechanism to replicate the data, so we recommend frequent backups for Amazon EBS.
-- Amazon EFS file systems are scoped to an AWS Region and can be accessed from any Availability Zone in the Region the file system was created in. Using Amazon EFS as a storage class for the Operations Center and Managed Controller allows pods to be rescheduled successfully onto healthy nodes in the event of an Availability Zone outage. Amazon EFS file systems may increase the cost of the deployment compared to the Amazon EBS option, but provide greater fault tolerance.
+- Amazon EBS volumes are scoped to a particular availability zone to offer high-speed, low-latency access to the Amazon Elastic Compute Cloud (Amazon EC2) instances they are connected to. If an availability zone fails, an Amazon EBS volume becomes inaccessible due to file corruption, or there is a service outage, the data on these volumes becomes inaccessible. The pods require this persistent data and have no mechanism to replicate the data, so CloudBees recommends frequent backups for Amazon EBS.
+- Amazon EFS file systems are scoped to an AWS region and can be accessed from any availability zone in the region that the file system was created in. Using Amazon EFS as a storage class allows pods to be rescheduled successfully onto healthy nodes in the event of an availability zone outage. Amazon EFS is more expensive than Amazon EBS, but provides greater fault tolerance.
 
 > [!IMPORTANT]  
-> CloudBees CD clustered mode requires Amazon EFS. See [CloudBees CD EKS Storage Requirements](https://docs.cloudbees.com/docs/cloudbees-cd/latest/requirements/k8s-requirements#persist).
+> CloudBees CD/RO clustered mode requires Amazon EFS. For more information, refer to [CloudBees CD/RO EKS Storage Requirements](https://docs.cloudbees.com/docs/cloudbees-cd/latest/requirements/k8s-requirements#persist).
 
 > [!NOTE]
-> For more information on pricing, see the [Amazon EBS pricing page](https://aws.amazon.com/ebs/pricing/) and the [Amazon EFS pricing page](https://aws.amazon.com/efs/pricing/).
+> For more information on pricing and cost analysis, refer to [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/) and [Amazon EFS pricing](https://aws.amazon.com/efs/pricing/).
 
-## Terraform Docs
+## Terraform documentation
 
 <!-- BEGIN_TF_DOCS -->
 ### Inputs
@@ -82,7 +78,7 @@ The main components of CloudBees CD, use a file system to persist data. Data is
 | cert_arn | Certificate ARN from AWS ACM | `string` | n/a | yes |
 | host_name | Route53 Host name | `string` | n/a | yes |
 | flow_db_secrets_file | Secrets file yml path containing the secrets names:values to create the Kubernetes secret flow_db_secret. | `string` | `"flow_db_secrets-values.yml"` | no |
-| helm_config | CloudBees CD Helm chart configuration | `any` | <pre>{<br>  "values": [<br>    ""<br>  ]<br>}</pre> | no |
+| helm_config | CloudBees CD/RO Helm chart configuration | `any` | <pre>{<br>  "values": [<br>    ""<br>  ]<br>}</pre> | no |
 
 ### Outputs
 
@@ -98,15 +94,12 @@ The main components of CloudBees CD, use a file system to persist data. Data is
 | merged_helm_config | (merged) Helm Config for CloudBees CD |
 <!-- END_TF_DOCS -->
 
-## Communications
-
-Cloudbees' slack channel [#cbcd-eks-blueprints](https://cloudbees.slack.com/archives/C05NACAEM5H)
-
-## References
+## Additional resources
 
-- [CloudBees CD Docs](https://docs.cloudbees.com/docs/cloudbees-cd/latest/)
-- [CloudBees CD release notes](https://docs.cloudbees.com/docs/release-notes/latest/cloudbees-cd/)
-- [Architecture for CloudBees CD on modern cloud platforms](https://docs.cloudbees.com/docs/cloudbees-cd/latest/architecture/cd-cloud)
+- [CloudBees CD/RO documentation](https://docs.cloudbees.com/docs/cloudbees-cd/latest/)
+- [CloudBees CD/RO release notes](https://docs.cloudbees.com/docs/release-notes/latest/cloudbees-cd/)
+- [Architecture for CloudBees CD/RO](https://docs.cloudbees.com/docs/cloudbees-cd/latest/architecture/)
 - [Amazon EKS Blueprints Addons](https://aws-ia.github.io/terraform-aws-eks-blueprints-addons/main/)
-- [Amazon EKS Blueprints Patterns](https://aws-ia.github.io/terraform-aws-eks-blueprints/)
-- [Bootstrapping clusters with EKS Blueprints | Containers](https://aws.amazon.com/blogs/containers/bootstrapping-clusters-with-eks-blueprints/)
+- [Amazon EKS Blueprints for Terraform](https://aws-ia.github.io/terraform-aws-eks-blueprints/)
+- [Containers: Bootstrapping clusters with EKS Blueprints](https://aws.amazon.com/blogs/containers/bootstrapping-clusters-with-eks-blueprints/)
+- [EKS Workshop](https://www.eksworkshop.com/)