Merge pull request #11 from kdubois/main

Fixing a few typos and improving readability

documentation/modules/ROOT/pages/02-workshop-overview.adoc

@@ -31,7 +31,7 @@ custom resource in the namespace where we want to run the Rollout. In the case o
 RolloutManager has already been provisioned for you.
 
 [NOTE]
-Argo Rollouts can be deployed as ether a namespace or cluster scope, the OpenShift GitOps operator
+Argo Rollouts can be deployed as either a namespace or cluster scope, the OpenShift GitOps operator
 currently only supports namespace scope.
 
 To review the rollout manager, execute the following command:
@@ -43,7 +43,8 @@ oc get rolloutmanager argo-rollout -o yaml -n user%USERNUM%-prod | oc neat
 ----
 
 [NOTE]
-We are using a kubectl plugin called link:https://github.com/itaysk/kubectl-neat[kubectl-neat,window='_blank']
+The `oc` CLI tool is a superset of `kubectl` with some additional Openshift specific features. We will use `oc` in this tutorial but if you prefer you can use `kubectl` as well.
+In the previous command we are using a kubectl plugin called link:https://github.com/itaysk/kubectl-neat[kubectl-neat,window='_blank']
 in order to tidy the yaml by removing additional fields, labels and annotations added automatically by Kubernetes.
 
 This will return an object as follows:
@@ -201,7 +202,7 @@ oc get route -n user%USERNUM%-dev rollouts-demo -o jsonpath='{"https://"}{.spec.
 ----
 
 Copy the URL into a browser and confirm that the application is running, you should see a grid of
-blue squares appearing and disappearing periodically as the application makes requests to it's back-end
+blue squares appearing and disappearing periodically as the application makes requests to its back-end
 from the browser.
 
 image::rollouts-demo-app-blue.png[]

documentation/modules/ROOT/pages/03-bluegreen-rollout.adoc

@@ -19,11 +19,10 @@ The diagram below illustrates this process over time.
 
 image::overview-blue-green.png[]
 
-In traditional infrastructure this approach can be very challenging. While Kubernetes is simpler due to it's declarative nature the process still tends to be cumbersome to manage since bespoke automation needs to be created to manage the separate stacks,
+In traditional infrastructure this approach can be very challenging. While Kubernetes is simpler due to its declarative nature, the process still tends to be cumbersome to manage. Bespoke automation would still need to be created to manage the separate stacks, and for
 testing and traffic management between versions.
 
-This is where Argo Rollouts comes in, it greatly reduces the complexity by providing these capabilities with a simple, declarative approach. In this module
-we will deploy a simple blue-green Rollout and explore it's basic capabilities.
+This is where Argo Rollouts comes in. It greatly reduces the complexity by providing these capabilities with a simple, declarative approach. In this module we will deploy a simple blue-green Rollout and explore its basic capabilities.
 
 [#deploy-blue-green-rollout]
 == Deploy Blue-Green Rollout
@@ -59,10 +58,10 @@ Kubernetes link:https://kubernetes.io/docs/concepts/workloads/pods/#pod-template
 under `.spec.strategy` we have specified the `blueGreen` strategy. The Kubernetes Deployment object supports `rollout`
 and `replace` strategies whereas Argo Rollouts supports `blueGreen` and `canary` strategies.
 
-Under the `blueGreen` strategy we have identified the `active` and `preview` Kubernetes services for the rollout which will be covered
+Under the `blueGreen` strategy we have identified the `active` and `preview` Kubernetes services for the rollout. This will be covered
 in more detail when services are discussed next.
 
-As well as services the field `autoPromotionEnabled` is set to `false` which means the rollout will require manual intervention to promote. Manual promotion
+The field `autoPromotionEnabled` is set to `false`. This means the rollout will require manual intervention to promote. Manual promotion
 is enabled so the behavior of the rollout can be observed in-depth in subsequent sections of this module.
 
 The Argo Rollouts documentation provides a complete list
@@ -109,7 +108,7 @@ oc get pods -l app=rollouts-demo -n user%USERNUM%-prod
 ----
 
 [NOTE]
-We are getting pods using the label `app=rollouts-demo` to specifically select pods from the rollout, remember
+We are getting pods using the label `app=rollouts-demo` to specifically select pods from the rollout. Remember
 the RolloutManager pod is also deployed in the `user%USERNUM%-prod` namespace. Using the label enables us
 to exclude that pod.
 
@@ -184,11 +183,11 @@ spec:
 ----
 
 Notice that the selector now has an additional key, `rollouts-pod-template-hash`, with a hashed value. This is how the rollout manages traffic
-between the active and preview versions. Since we have not deployed a new image, if you check the preview service you will see the same
+between the active and preview versions. Since we have not deployed a new image, the preview service will have the same
 selector used there as well.
 
 Similar to Kubernetes deployments, each revision, i.e. version, of the Rollout is backed by a link:https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/[ReplicaSet,window='_blank'].
-This ReplicaSet will have a `rollouts-pod-template-hash` label in it's PodTemplate with a value unique to the revision. Argo Rollouts will automatically ensure that
+This ReplicaSet will have a `rollouts-pod-template-hash` label in its PodTemplate with a value unique to the revision. Argo Rollouts will automatically ensure that
 the selector in the service is pointing to the appropriate revision.
 
 To view this, output the manifest for the currently deployed ReplicaSet:
@@ -306,7 +305,7 @@ The Argo Rollouts Dashboard is intended to be run on the developer's local machi
 authentication or multi-tenancy. For convenience and simplicity it has been deployed on cluster for each user
 but this is not recommended as a general practice.
 
-In the dashboard each rollout will show in it's own tile on the overview screen. The tile will provide some
+In the dashboard each rollout will show in its own tile on the overview screen. The tile will provide some
 basic information about the rollout as shown here:
 
 image::argo-rollout-dashboard-details.png[]
@@ -339,7 +338,7 @@ Kubernetes Deployment in the `user%USERNUM%-dev` namespace while `deploy-prod` w
 [NOTE]
 This pipeline is not meant to be a comprehensive example of how to manage image promotion, rather we
 are using it provide a simple way in the workshop to drive image changes. This pipeline uses OpenShift
-Pipelines however any Continuous Integration(CI) tool can be used with Argo Rollouts including Argo Workflows,
+Pipelines, an implementation of the link:https://tekton.dev[Tekton,window='_blank'] project, however any Continuous Integration(CI) tool can be used with Argo Rollouts including Argo Workflows,
 GitHub Actions, GitLab, etc.
 
 To start the pipeline, click the `Actions` dropdown and select the `Start` option:
@@ -371,7 +370,7 @@ we deployed.
 image::rollouts-demo-app-green.png[]
 
 Now let's see what the application looks like in production where we are using Rollouts. First, let's check the preview service by
-retrieving it's URL and viewing it in the browser:
+retrieving its URL and viewing it in the browser:
 
 [.console-input]
 [source,bash,subs="attributes+,+macros"]

documentation/modules/ROOT/pages/04-analysis.adoc

@@ -17,14 +17,14 @@ link:https://argo-rollouts.readthedocs.io/en/stable/features/analysis[Analysis,w
 enables Rollouts to collect data and metrics from a variety of providers to validate the
 new version of the application.
 
-In addition to collecting data, an Analysis can include a Job to drive more advanced use cases. For example
+In addition to collecting data, an Analysis can include a Job to drive more advanced use cases. For example,
 a Job could be used to run load against an application in order to generate the metrics needed to
 validate the revision.
 
 To deploy an Analysis, first an AnalysisTemplate is created that defines the analysis that is required
 and then is associated with one or more rollouts. The way an analysis is associated with a rollout is dependent on
 the rollout strategy used. In this module we will look at it from the perspective of the Blue-Green
-strategy we have deployed previously however in the next module we delve into it for the Canary strategy as well.
+strategy we have deployed previously. In the next module we will delve into using an Analysis with the Canary strategy as well.
 
 In the blue-green strategy, an Analysis can be added as either pre-promotion or post-promotion. Pre-promotion
 is used before the new version is deployed and is useful for validating the deployment prior to cutting over to it
@@ -68,13 +68,12 @@ enable the template to be reused across many different rollouts.
 * `.spec.metrics`. These are the metric providers that will be used to collect data for the analysis as well as any jobs
 that need to be executed.
 
-In the metrics provider section we can see we have two providers defined, one that uses the prometheus metric provider to pull
-metrics from Thanos, an aggregator for Prometheus data, and a job that runs link:https://github.com/JoeDog/siege[Apache Siege,window='_blank']
+In the metrics provider section we can see that we have two providers defined. The first one, named `success-rate`, uses the prometheus metric provider to pull metrics from Thanos, an aggregator for Prometheus data. The second one, `run-load` is a job that runs link:https://github.com/JoeDog/siege[Apache Siege,window='_blank']
 to drive some load on the application.
 
 The `count` and `interval` fields in the `success-rate` metric powered by the prometheus provider indicate that the metric will be checked four times
 with a thirty second interval between each check. The `failureLimit` determines how many failures are permitted for the rollout to be considered
-a success, here we set a failure limit of 0.
+a success. Here we set a failure limit of 0.
 
 Finally, remember we are running this Analysis in the pre-promotion phase of the blue-green strategy so the application will not
 be receiving load from users, therefore generating load with Apache Siege will generate the metrics we need to determine whether
@@ -92,7 +91,7 @@ parameter is used to specify the OpenShift route URL where we want to drive the
 siege will be hitting when it generates load.
 
 Finally a third parameter, `api-token`, is provided by a secret. This secret provides the token needed
-to access the OpenShift monitoring stack, it was created by the GitOps process which provisioned this workshop.
+to access the OpenShift monitoring stack. It was created by the GitOps process which provisioned this workshop.
 
 Next let's look at the rollout and see how the AnalysisTemplate is wired into the rollout.
 
@@ -106,7 +105,7 @@ Notice that in `.spec.strategy.blueGreen` we have now defined the `prePromotionA
 we define the analysis template we want to use as well as the arguments that the rollout needs to provide the
 template.
 
-Next to deploy this new version of the blue-green rollout, execute the following command:
+To deploy this new version of the blue-green rollout, execute the following command:
 
 [.console-input]
 [source,bash,subs="attributes+,+macros"]
@@ -127,7 +126,7 @@ The dashboard for our blue-green rollout will appear identically as follows:
 
 image::argo-rollout-dashboard-bg-analysis-initial.png[]
 
-Next confirm that the application is displaying blue squares by opening the active route URL in your browser:
+Confirm that the application is displaying blue squares by opening the active route URL in your browser:
 
 [.console-input]
 [source,bash,subs="attributes+,+macros"]
@@ -163,9 +162,9 @@ image::argo-rollouts-analysis-in-progress-overview.png[]
 
 When a promotion of a rollout with an analysis is executed the controller will
 generate an analysis run for each template execution. Since we only have one template
-being used in pre-promotion we will only see one analysis run being created however
-it is possible for a promotion to have multiple analysis runs dependent on the
-rollout configuration, i.e. in blue-green defining both pre and post promotion analysis.
+being used in pre-promotion we will only see one analysis run being created. 
+It is however possible for a promotion to have multiple analysis runs, dependent on the
+rollout configuration. i.e. in blue-green defining both pre and post promotion analysis.
 
 Clicking on the analysis button will expand the view to show the in-progress analysis
 that is running:
@@ -256,9 +255,9 @@ image::rollouts-demo-errors.png[]
 [IMPORTANT]
 This section should not be overly timing sensitive since we are
 cheating a bit by pre-generating errors. However when we promote the new image the error
-setting will be reset back to 0 for the preview service. After the promotion pipeline completes,
+setting will be reset back to 0 for the preview service. *After the promotion pipeline completes,
 immediately switch back to the tab with the preview service and push the error bar
-back to 100%.
+back to 100%*.
 
 Now we will perform a promotion to a yellow image, go back to the OpenShift Pipeline and start it
 with the yellow image:
@@ -275,7 +274,7 @@ image::argo-rollouts-analysis-failed-details.png[]
 
 [NOTE]
 If the timing did not work out for you, you can try again by promoting with a different color.
-You can see the list of available colors .link:https://quay.io/repository/openshiftdemos/rollouts-demo?tab=tags[here, window='_blank']
+You can see the list of available colors link:https://quay.io/repository/openshiftdemos/rollouts-demo?tab=tags[here, window='_blank']
 where each color is simply a tag in our quay.io registry.
 
 If you expand the Analysis section, you will see at least one metric test has failed as

documentation/modules/ROOT/pages/05-canary-rollout.adoc

@@ -12,8 +12,8 @@ In this module we will:
 == Canary Strategy
 
 link:https://argo-rollouts.readthedocs.io/en/stable/features/canary/[Canary, window='_blank'] can be
-thought of as an advanced version of blue-green where instead of an abrupt cut-over
-of live traffic between a current and new revision traffic is instead gradually increased to the new
+thought of as an advanced version of blue-green. Instead of an abrupt cut-over
+of live traffic between a current and new revision, traffic is instead gradually increased to the new
 version in increments, or steps, while simultaneously decreasing the current revision. Like the
 proverbial link:https://en.wiktionary.org/wiki/canary_in_a_coal_mine[canary in the coal mine,window="_blank"],
 the intent is to allow users to access the new version over time and if unexpected problems occur revert back to the
@@ -64,8 +64,8 @@ see the following:
 include::ROOT:example$canary/base/rollout.yaml[]
 ----
 
-In the rollout we have changed our strategy from blue-green to canary. In the canary strategy, like the blue-green strategy, we specify
-the services to use however here they are stable and canary services. Unlike blue-green we explicitly define the promotion process by
+In the rollout manifest we have changed our strategy from blue-green to canary. In the canary strategy, like the blue-green strategy, we specify
+the services to use however here they are `stable` and `canary` services. Unlike blue-green we explicitly define the promotion process by
 specifying a series of discrete steps. At each step we can set the traffic weight between the services, pause or perform an
 inline analysis.
 
@@ -303,7 +303,7 @@ button or you can promote it using the following command:
 oc argo rollouts promote rollouts-demo -n user%USERNUM%-prod
 ----
 
-Observe the dashboard once it has been promoted, the dashboard will show the progression
+Observe the dashboard once it has been promoted. The dashboard will show the progression
 of the steps by highlighting each step as it is being executed. Also note how pods are
 being drained from one service to the other as traffic weighting changes.
 
@@ -334,12 +334,12 @@ before progressing further. However we can accomplish the same goal by using an
 respect to the canary strategy, an analysis can be performed in the link:https://argo-rollouts.readthedocs.io/en/stable/features/analysis/#background-analysis[background,window='_blank']
 or as an link:https://argo-rollouts.readthedocs.io/en/stable/features/analysis/#inline-analysis[inline] analysis.
 
-A background analysis happens asynchronously and does not block the progression of steps, however
+A Background Analysis happens asynchronously and does not block the progression of steps, however
 if the analysis fails it will abort the rollout similar to what we saw in the previous module with
-the blue-green strategy. In the case of an inline analysis, the analysis is performed as a discrete step
+the blue-green strategy. In the case of an Inline Analysis, the analysis is performed as a discrete step
 and will block the progression of the rollout until it completes.
 
-The files for this example are in the `./canary-analysis/base` folder, to view the list of files
+In the following example we will implement an Inline Analysis. The files for this example are in the `./canary-analysis/base` folder, to view the list of files
 perform an `ls` as follows:
 
 [.console-input]
@@ -348,7 +348,7 @@ perform an `ls` as follows:
 ls ./canary-analysis/base
 ----
 
-Note that the files are identical to the previous example other then the `rollout.yaml` and the
+Note that the files are identical to the previous example other than the `rollout.yaml` and the
 `analysistemplate.yaml` file. The AnalysisTemplate being used here is identical to the one
 we used in the blue-green example so we will not cover it again here.