Merge pull request #139 from cloudbees/copy-edits

Minor copy edits to recently revised docs.

.cloudbees/workflows/bp-tf-ci.yaml

@@ -173,4 +173,4 @@ jobs:
       shell: bash
       run : |
         [ "${{ env.CLEAN_UP }}" = "true" ] && terraform -chdir=blueprints/${{ env.ROOT }} init -reconfigure && CI=true make destroy \
-          || CI=true make destroy
+          || CI=true make destroy

CONTRIBUTING.md

@@ -24,38 +24,38 @@ When filing an issue:
 
 ## Contribute via pull requests
 
-Contributions via pull requests are appreciated. Before submitting a pull request, please ensure that you:
+Contributions via pull requests (PRs) are appreciated. Before submitting a PR, please ensure that you:
 
 1. Are working against the latest source on the `main` branch.
-2. Check existing open, and recently merged, pull requests to make sure someone else has not already addressed the problem.
+2. Check existing open and recently merged PRs, to ensure the problem has not already been addressed.
 3. Open an issue to discuss any significant work; we do not want your time to be wasted.
 
-To submit a pull request:
+To submit a PR:
 
 1. Fork the repository.
 2. Create feature branch extending from the `main` branch.
 3. Modify the source and focus on the specific change you are contributing. If you reformat all the code, it is hard for reviewers to focus on your specific change.
 4. **Ensure that local tests pass**.
 5. Make commits to your fork using clear commit messages.
-6. Submit a pull request against the `develop` branch and answer any default questions in the pull request interface.
-7. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
+6. Submit a PR against the `develop` branch and answer any default questions in the PR interface.
+7. Pay attention to any automated CI failures reported in the PR, and stay involved in the conversation.
 
 > [!IMPORTANT]
-> If you make updates to CasC bundles, you must push the changes to a public repository/branch before running `terraform apply`. The default is `https://github.com/cloudbees/terraform-aws-cloudbees-ci-eks-addon.git/main`, which follows a monorepo approach where the CasC bundles and `blueprints` are stored in the same repository.
+> If you make updates to Configuration as Code (CasC) bundles, you must push the changes to a public repository/branch before running `terraform apply`. The default is `https://github.com/cloudbees/terraform-aws-cloudbees-ci-eks-addon.git/main`, which uses a mono-repository approach where the CasC bundles and blueprints are stored in the same repository
 
 >[!TIP]
-> GitHub provides additional documentation on [forking a repository](https://help.github.com/articles/fork-a-repo/) and [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
+> GitHub provides additional documentation on [forking a repository](https://help.github.com/articles/fork-a-repo/) and [creating a PR](https://help.github.com/articles/creating-a-pull-request/).
 
 ### Pre-commits: Linting, formatting and secrets scanning
 
 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).
 
 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).
-2. Run `pre-commit run --all-files`. Run this command again if the automated checks fail when you create a pull request.
+2. Run `pre-commit run --all-files`. Run this command again if the automated checks fail when you create a PR.
 
 ## Blueprint Terraform CI pipeline
 
-Validate your pull request changes inside the blueprint agent described in the [Dockerfile](.docker/agent). It is the same agent used for the CI pipeline [bp-agent-ecr.yaml](.cloudbees/workflows/bp-agent-ecr.yaml).
+Validate your PR changes inside the blueprint agent described in the [Dockerfile](.docker/agent). It is the same agent used for the CI pipeline [bp-agent-ecr.yaml](.cloudbees/workflows/bp-agent-ecr.yaml).
 
 > [!NOTE]
 > The agent and dependencies can be automated using the [Makefile](Makefile) at the root of the project, under the target `bpAgent-dRun`. It is the same Makefile used in the CloudBees CI pipeline.
@@ -69,29 +69,24 @@ The [bp-tf-ci.yaml](.cloudbees/workflows/bp-tf-ci.yaml) blueprints are orchestra
 - AWS Route 53 zone name, to create DNS records.
 
 > [!IMPORTANT]
-> CloudBees Platform currently only supports push events. Therefore, pull requests are sent to the `develop` branch for integration.
+> The [CloudBees platform](https://www.cloudbees.com/products/saas-platform) currently only supports push events. Therefore, PRs are first opened on the `develop` branch for integration.
 
 ## Release
 
-CloudBees CI Terraform EKS Addon versions try to be in sync with the [CloudBees CI releases](https://docs.cloudbees.com/docs/release-notes/latest/cloudbees-ci/).
+The CloudBees CI add-on versions attempt to stay in sync with the [CloudBees CI releases](https://docs.cloudbees.com/docs/release-notes/latest/cloudbees-ci/).
 
-Before a new CloudBees CI Helm chart is released, new features for this addon and its companion blueprints are merged into the integration branch (`develop`). When a new version of the CloudBees CI Helm chart is released, the addon is updated to the new version following this process:
+Before a new CloudBees CI Helm chart is released, new features for this add-on and its companion blueprints are merged into the `develop` integration branch. When a new version of the CloudBees CI Helm chart is released, the add-on is updated to the new version using the following process:
 
-1. Test the update in the integration branch (`develop`).
-   - Update the `version` field if CloudBees CI Terraform EKS Addon update needs to be updated to the new [version of the Helm chart](https://artifacthub.io/packages/helm/cloudbees/cloudbees-core/).
-   - The field `source` in the `eks_blueprints_addon_cbci` in the blueprints folder must point to the local CloudBees CI Terraform EKS Addon root of the repository `source = "../../"` (not to the remote [terraform registry version](https://registry.terraform.io/modules/cloudbees/cloudbees-ci-eks-addon/aws/latest)).
-   - Test the update locally.
+1. Test the update in the `develop` integration branch.
+   - Update the `version` field if the CloudBees CI add-on for Amazon EKS blueprints needs to be updated to the new [version of the Helm chart](https://artifacthub.io/packages/helm/cloudbees/cloudbees-core/).
+   - Verify that the `source` field for `eks_blueprints_addon_cbci` (in the `blueprints` folder) points to the local root of the `terraform-aws-cloudbees-ci-eks-addon` repository: `source = "../../"`, and not to the remote [terraform registry version](https://registry.terraform.io/modules/cloudbees/cloudbees-ci-eks-addon/aws/latest).
+   - Test the update locally using the following targets from the [Makefile](Makefile): `deploy` > `validate` > `destroy`.
 
-> [!TIP]
-> Use the following targets from [Makefile](Makefile): `deploy` > `validate` > `destroy`.
-
-2. Create a PR against the `main` branch. including the Helm chart update plus other updates available in the integration branch (`develop`). Ensure that the field `source` in the `eks_blueprints_addon_cbci` at blueprints is pointing to the remote [terraform registry version](https://registry.terraform.io/modules/cloudbees/cloudbees-ci-eks-addon/aws/latest) and `version >= "x.x.x"`.
-3. Once the pull request is merged, verify that the `main` branch successfully passes the [Terraform CI build](#blueprint-terraform-ci-pipeline).
+2. Create a PR against the `main` branch, including the Helm chart update plus other updates available in the `develop` integration branch. Ensure that the `source` field for `eks_blueprints_addon_cbci` in the `blueprints` folder points to the remote [terraform registry version](https://registry.terraform.io/modules/cloudbees/cloudbees-ci-eks-addon/aws/latest) and `version >= "x.x.x"`.
+3. Once the PR is merged, verify that the `main` branch successfully passes the [Terraform CI build](#blueprint-terraform-ci-pipeline).
 4. Create a [new release](https://github.com/cloudbees/terraform-aws-cloudbees-ci-eks-addon/releases). The release version semantics follow the Helm chart convention.
 
 > [!IMPORTANT]
-> This project uses a mono-repository approach where the CasC bundles and `blueprints` are stored in the same repository.  In the `main` branch CasC bundle SCM configuration should point to the `main` branch.
-
-This project uses [Release Drafter](https://github.com/release-drafter/release-drafter); pull request labels should be set accordingly.
-
-Kubernetes' environment versions are managed centrally in the [blueprints/.k8.env](blueprints/.k8s.env) file.
+> - This project uses a mono-repository approach where the CasC bundles and blueprints are stored in the same repository. In the `main` branch, the CasC bundle SCM configuration should point to the `main` branch.
+> - This project uses [Release Drafter](https://github.com/release-drafter/release-drafter); PR labels should be set accordingly.
+> - Kubernetes' environment versions are managed centrally in the [blueprints/.k8.env](blueprints/.k8s.env) file.

blueprints/01-getting-started/README.md

@@ -16,8 +16,8 @@ Get started with the [CloudBees CI on modern platforms in Amazon Elastic Kuberne
 ![Architecture](img/getting-started.architect.drawio.svg)
 
 - Node groups specification:
-  - Instance Type: [Graviton Processor](https://aws.amazon.com/ec2/graviton/) family
-  - AMI Type: [Amazon EKS-Optimized Amazon Linux 2023](https://aws.amazon.com/blogs/containers/amazon-eks-optimized-amazon-linux-2023-amis-now-available/)
+  - Instance type: [Graviton Processor](https://aws.amazon.com/ec2/graviton/) family
+  - AMI type: [Amazon EKS-Optimized Amazon Linux 2023](https://aws.amazon.com/blogs/containers/amazon-eks-optimized-amazon-linux-2023-amis-now-available/)
 
 ### Kubernetes cluster
 

blueprints/02-at-scale/README.md

@@ -16,8 +16,7 @@ Once you have familiarized yourself with [CloudBees CI blueprint add-on: Get sta
   | [Kube Prometheus Stack](https://aws-ia.github.io/terraform-aws-eks-blueprints-addons/main/addons/kube-prometheus-stack/) | Used for metrics observability.|
   | [Metrics Server](https://aws-ia.github.io/terraform-aws-eks-blueprints-addons/main/addons/metrics-server/) | This is a requirement for CloudBees CI HA/HS controllers for horizontal pod autoscaling.|
   | [Velero](https://aws-ia.github.io/terraform-aws-eks-blueprints-addons/main/addons/velero/)| Backs up and restores Kubernetes resources and volume snapshots. It is only compatible with Amazon Elastic Block Store (Amazon EBS).|
-  | [Bottlerocket Update Operator](https://aws-ia.github.io/terraform-aws-eks-blueprints-addons/main/addons/bottlerocket/) | Coordinates Bottlerocket updates on hosts in a cluster. It is configured for CloudBees CI Applications and Agents Node Groups at a specific time according to `scheduler_cron_expression`, when the build workload is minimal (weekend). In a case where the CI service cannot be interrupted at any time by the Update Operator, it could be excluded from planned updates by removing the [bottlerocket.aws/updater-interface-version=2.0.0](https://github.com/bottlerocket-os/bottlerocket-update-operator#label-nodes) label.|
-
+  | [Bottlerocket Update Operator](https://aws-ia.github.io/terraform-aws-eks-blueprints-addons/main/addons/bottlerocket/) | Coordinates Bottlerocket updates on hosts in a cluster. It is configured for CloudBees CI applications and agents node groups at a specific time according to `scheduler_cron_expression`, when the build workload is minimal (for example, on the weekend). If the CI service cannot be interrupted at any time by the Bottlerocket Update Operator, it can be excluded from planned updates by removing the [bottlerocket.aws/updater-interface-version=2.0.0](https://github.com/bottlerocket-os/bottlerocket-update-operator#label-nodes) label. |
 - [Amazon EKS blueprints Helm Release Add-on](https://aws-ia.github.io/terraform-aws-eks-blueprints-addons/main/helm-release/) is used to install the following applications:
 
   | Helm Chart | Description |
@@ -95,9 +94,9 @@ Once you have familiarized yourself with [CloudBees CI blueprint add-on: Get sta
 | prometheus_dashboard | Provides access to Prometheus dashboards. |
 | s3_cbci_arn | CloudBees CI Amazon S3 bucket ARN. |
 | s3_cbci_name | CloudBees CI Amazon S3 bucket name. It is required by CloudBees CI for workspace caching and artifact management. |
-| velero_backup_on_demand | Takes an on-demand Velero backup from the schedule for selected controller using Block Storage. |
-| velero_backup_schedule | Creates a Velero backup schedule for selected controller using Block Storage and deletes the existing schedulle, if it exists. |
-| velero_restore | Restores selected controller using Block Storage from a backup. |
+| velero_backup_on_demand | Takes an on-demand Velero backup from the schedule for the selected controller that is using block storage. |
+| velero_backup_schedule | Creates a Velero backup schedule for the selected controller that is using block storage, and then deletes the existing schedule, if it exists. |
+| velero_restore | Restores the selected controller that is using block storage from a backup. |
 | vpc_arn | VPC ID. |
 <!-- END_TF_DOCS -->
 
@@ -225,11 +224,11 @@ Once the resources have been created, a `kubeconfig` file is created in the [/k8
 
 For backup and restore operations, you can use the [preconfigured CloudBees CI Cluster Operations job](#create-daily-backups-using-a-cloudbees-ci-cluster-operations-job) to automatically perform a daily backup, which can be used for Amazon EFS and Amazon EBS storage.
 
-[Velero](#create-a-velero-backup-schedule) is an alternative for services only for controllers using Amazon EBS. Velero commands and configuration in this blueprint follow [Using Velero back up and restore Kubernetes cluster resources](https://docs.cloudbees.com/docs/cloudbees-ci/latest/backup-restore/velero-dr).
+[Velero](#create-a-velero-backup-schedule) is an alternative for services for controllers using Amazon EBS. Velero commands and configuration in this blueprint follow [Using Velero back up and restore Kubernetes cluster resources](https://docs.cloudbees.com/docs/cloudbees-ci/latest/backup-restore/velero-dr).
 
 > [!NOTE]
-> - An installation that has been completely converted to CasC may not need traditional backups; a restore operation could consist simply of running a CasC bootstrap script. This is only an option for a customer who has translated every significant system setting and job configuration to CasC. Even then it may be desirable to perform a filesystem-level restore from backup in order to preserve transient data such as build history.
-> - There is no alternative for services using Amazon EFS storage. Although [AWS Backup](https://aws.amazon.com/backup/) includes this Amazon EFS drive as a protected resource, there is not currently a best practice to dynamically restore Amazon EFS PVCs. For more information, refer to [Issue 39](https://github.com/cloudbees/terraform-aws-cloudbees-ci-eks-addon/issues/39).
+> - An installation that has been completely converted to CasC may not need traditional backups; a restore operation could consist simply of running a CasC bootstrap script. This is only an option for customers who have translated every significant system setting and job configuration to CasC. Even then it may be desirable to perform a filesystem-level restore from a backup to preserve transient data, such as build history.
+> - There is no alternative for services using Amazon EFS storage. Although [AWS Backup](https://aws.amazon.com/backup/) includes the Amazon EFS drive as a protected resource, there is not a best practice to dynamically restore Amazon EFS PVCs. For more information, refer to [Issue 39](https://github.com/cloudbees/terraform-aws-cloudbees-ci-eks-addon/issues/39).
 
 ##### Create daily backups using a CloudBees CI Cluster Operations job
 
@@ -246,7 +245,7 @@ To view the **backup-all-controllers** job:
 
 ##### Create a Velero backup schedule
 
-Issue the following command to create a Velero backup schedule for selected controller `team-b` (this can also be applied to `team-a`):
+Issue the following command to create a Velero backup schedule for the `team-b` controller (this can also be applied to `team-a`):
 
    ```sh
    eval $(terraform output --raw velero_backup_schedule)
@@ -267,8 +266,8 @@ Issue the following command to take an on-demand Velero backup for a specific po
 
 1. Make updates on the `team-b` controller (for example, add some jobs and generate builds).
 2. [Take an on-demand Velero backup](#take-an-on-demand-velero-backup), including the updates that you made.
-3. Remove the latest update (for example, remove jobs you create and build on existing jobs).
-4. Manage `team-b` > Deprovision the controller.
+3. Remove the most recent update (for example, remove jobs you created and build on existing jobs).
+4. From the operations center dashboard, select the down arrow to the right of the `team-b` controller’s name, and then select **Manage > Deprovision** to deprovision the controller.
 5. Issue the following command to restore the controller from the last backup:
 
    ```sh
@@ -281,8 +280,8 @@ Issue the following command to take an on-demand Velero backup for a specific po
 
 Grafana is used to visualize and query:
 
-- [Jenkins Metrics](https://plugins.jenkins.io/metrics/) that are stored in Prometheus.
-- [Jenkins Tracing via OpenTelemetry](https://plugins.jenkins.io/opentelemetry/) that stored into Grafana Tempo.
+- [Jenkins metrics](https://plugins.jenkins.io/metrics/) that are stored in Prometheus.
+- [Jenkins tracing via OpenTelemetry](https://plugins.jenkins.io/opentelemetry/) that are stored in Grafana Tempo.
 
 1. Issue the following command to verify that the CloudBees CI targets are connected to Prometheus:
 
@@ -306,19 +305,19 @@ Grafana is used to visualize and query:
 
    If successful, the Grafana dashboard should be available at `http://localhost:50002`.
 
-   - For Jenkins Metrics Dashboards navigate to **Dashboards > CloudBees CI**. Then, select the controller pod to view the metrics. The following image shows metrics for team-b.
+   - For Jenkins metrics dashboards, navigate to **Dashboards > CloudBees CI**, and then select the controller pod to view the metrics. The following image shows metrics for the `team-b` controller:
 
    ![CloudBees CI Dashboard](img/observability/cbci-dashboard.png)
 
-   - For Tracing Data, navigate to **Home > Explore > Select Tempo > Select `Query Type: Search`**. Then, select the `service name: jenkins` and the desired `Span Name` to `Run Query`. The following image shows an example of the ws-cache pipeline build.
+   - For tracing data, navigate to **Home > Explore > Tempo > Query Type: Search**. For the **Service name**, select **jenkins**, and then select the appropriate **Span Name** to run the query. The following image shows an example of the `ws-cache` pipeline build:
 
    ![CloudBees CI Tracing Example](img/observability/cbci-tracing-example.png)
 
 #### Logs
 
 For application logs, Fluent Bit acts as a router.
 
-- Short-term application logs live in the [Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) group, under `/aws/eks/<CLUSTER_NAME>/aws-fluentbit-logs` and contains log streams for all the Kubernetes services running in the cluster, including CloudBees CI applications and agents. The following image shows an example of team b controller logs.
+- Short-term application logs live in the [Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) group, under `/aws/eks/<CLUSTER_NAME>/aws-fluentbit-logs` and contains log streams for all the Kubernetes services running in the cluster, including CloudBees CI applications and agents. The following image shows an example of `team b` controller logs.
 
    ```sh
    eval $(terraform output --raw aws_logstreams_fluentbit) | jq '.[] '