Merge pull request #40 from IBM/doc-updates-jun13

Doc edits

Author: eric-simpson

docs/guides/appinstall.md

@@ -22,7 +22,7 @@ First, head over to the Projects tab and select Create.
 
 ![](../images/appinst/appinst-1.png)
 
-This gives you a name and a desciption to fill out. I named this project `company-system`.
+This gives you a name and a description to fill out. I named this project `company-system`.
 
 ![](../images/appinst/appinst-2.png)
 
@@ -39,12 +39,12 @@ Applications only get installed once into a project. Future developers using thi
 
 To install a tool, head to the **Catalog** and see what tools are available. If you right click on IBM i Developer, have two options:
 
-1. **View Details** which gives you a desciption of the tool
+1. **View Details** which gives you a description of the tool
 2. **Install the Application** which installs it into a chosen project in the next steps
 
 ![](../images/appinst/appinst-3.png)
 
-After you select 'Install the Application', there is a prompt to review and accept a licence agreement.
+After you select 'Install the Application', there is a prompt to review and accept a license agreement.
 
 ![](../images/appinst/appinst-4.png)
 

docs/guides/flows.md

@@ -20,10 +20,10 @@ ARCAD builder has a specific way it fetches source code from a repository before
 
 In order for ARCAD Builder to successfully clone from the 'External source code Management' URL defined in the ARCAD application, the user profile that is running the ARCAD Builder job needs access to the repository URL.
 
-* The `AGENSSHKEY` can be used to generate the keypair for the user running the ARCAD Builder job on IBM i. The standard directory for the public key is `/home/<user>/.ssh/id_rsa.pub`.
+* The `AGENSSHKEY` can be used to generate the key pair for the user running the ARCAD Builder job on IBM i. The standard directory for the public key is `/home/<user>/.ssh/id_rsa.pub`.
 * The generated public key must be added to a GitHub/Azure/BitBucket account that has access to the repository being used.
 * The user who runs the ARCAD Builder job can be changed with the `CHGAFSSVR` command.
 
-It is also possible to override the user used for the clone. If you head to the ARCAD Builder Web Interface and navigate to the application, under the build model it is possible to define a 'Build' login and password (an IBM i user profile) which will be used for this application. The user profile provided also needs an SSH keypair setup.
+It is also possible to override the user used for the clone. If you head to the ARCAD Builder Web Interface and navigate to the application, under the build model it is possible to define a 'Build' login and password (an IBM i user profile) which will be used for this application. The user profile provided also needs an SSH key pair setup.
 
 ![](../images/cicd/cicd-14-b.png)

docs/guides/openshift/local.md

@@ -10,25 +10,8 @@ This guide exists for users who potentially have hardware available for OpenShif
 
 ## System requirements
 
-Red Hat OpenShift Local at present is only supported on AMD64 and Intel 64 processor architectures. It has the following minimum hardware requirements:
+Please see the official Red Hat documentation regarding system requirements: [Openshift Local System Requirements](https://access.redhat.com/documentation/en-us/red_hat_openshift_local/2.5/html/release_notes_and_known_issues/minimum-system-requirements_rn-ki)
 
-- 4 physical CPU cores
-- 9 GB of free memory
-- 35 GB of storage space
-
-And the following operating system requirements:
-
-- Microsoft Windows 10 Fall Creators Update (version 1709) or later
-- macOS 11 Big Sur or later
-- The latest two Red Hat Enterprise Linux/CentOS 7, 8 and 9 minor releases and on the latest two stable Fedora releases.
-
-**Note:**
-
-The OpenShift Local requires these (above) minimum hardware resources to run the smallest OpenShift Container Platform. Some workloads may require more resources. We recommend the following resources for running OpenShift Local:
-
-- 8 physical CPU cores
-- 64 GB of free memory
-- 256 GB of storage space
 
 ## Install Red Hat OpenShift Local
 
@@ -247,7 +230,7 @@ From OpenShift web console, locate the Merlin namespace, open the postgres pod t
 * In the psql session, run the following command to create an empty merlindb database:
     * `DROP DATABASE IF EXISTS merlindb WITH (FORCE);`
     * `CREATE DATABASE merlindb;`
-* Run `\q` to quit the psql sesison.
+* Run `\q` to quit the psql session.
 * In the Terminal, run `psql -f /tmp/merlindb_dumpfile -d merlindb` to restore the merlindb database.
    
 Now, you can use admin user and password to access Merlin GUI and use the vault secret and token to unseal vault which you had already written down. 

docs/guides/openshift/merlininstall.md

@@ -102,7 +102,7 @@ The admin user can be used to log in to the Merlin instance for first time setup
 
 ## Initializing the Vault
 
-After Merlin has been installed, an admin will need to initialise the vault. The vault is used to securely store credentials and important information securely. When you initialise the vault, **be sure to store** the secrets and token that are provided by the UI. **These are required** during Merlin upgrades and any time the vault needs to be unsealed.
+After Merlin has been installed, an admin will need to initialize the vault. The vault is used to securely store credentials and important information securely. When you initialize the vault, **be sure to store** the secrets and token that are provided by the UI. **These are required** during Merlin upgrades and any time the vault needs to be unsealed.
 
 ![](../../images/osc/osc-20.png)
 

docs/guides/overview/sandbox.md

@@ -1,6 +1,6 @@
 # Merlin Test Drive
 
-It is now possible to try Merlin (and all components) for a limited timeframe.  Please reach out to your Seller to be nominated for participation.
+It is now possible to try Merlin (and all components) for a limited timeframe.  Please reach out to your seller to be nominated for participation.
 
 The Merlin Test Drive environment provides access to:
 
@@ -16,7 +16,7 @@ With access to the Merlin Test Drive environment, this hands-on documentation ca
 * A [self-guided tour](./workshop/readme.md) and sample code are provided
 * Leverage, test, and / or demonstrate IBM i Merlin.
 * The user is provided an OpenShift Merlin Workspace and a dedicated IBM i partition
-* IBM Client Engineering for Systems team provides the infrastructure, IBM i Development provides the Merlin expertise, and you test-drive Merlin
+* IBM Client Engineering for Systems team provides the infrastructure. IBM i Development provides the Merlin expertise. And you test-drive Merlin
 
 #### Limitations
 
@@ -29,5 +29,5 @@ With access to the Merlin Test Drive environment, this hands-on documentation ca
 * BP or IBM Sellers can engage with the submission of a Deal Support Request against a pre-sales opportunity.
 * Clients should reach out to your Seller to be nominated for participation.  Your Seller will submit a Deal Support Request for `Power IBM i Merlin TestDrive` via the Client Engineering engagement process.
 
-For general inqueries, contact us at [email protected].
+For general inquiries, contact us at [email protected].
 

docs/guides/overview/security.md

@@ -5,7 +5,7 @@ This topic provides security recommendations for setting up Data In Motion Encry
 
 ## Data at rest
 
-All user sensitive data at rest is stored in Hashicorp Vault. Hashicorp Vault is used to secure, store and tightly control access to tokens, passwords, certificates, encryption keys for protecting secrets and other sensitive data using a UI, CLI, or HTTP API. Merlin leverages HashiCorp Vault as the Active Encryption solution to store sensitive data such as credentials. Users do not need to directly work with HashiCorp Vault. Vault encrypts data in transit (with TLS) and at rest (using AES 256-bit CBC encryption). This protects sensitive data from unauthorized access in two major ways: as it travels across the network as well as in storage in the cloud and datacenters. But it is neccessary for OpenShift administrator to understand that Vault is used underneath. For more information, please read the content of the following link: https://learn.hashicorp.com/vault. 
+All user sensitive data at rest is stored in Hashicorp Vault. Hashicorp Vault is used to secure, store and tightly control access to tokens, passwords, certificates, encryption keys for protecting secrets and other sensitive data using a UI, CLI, or HTTP API. Merlin leverages HashiCorp Vault as the Active Encryption solution to store sensitive data such as credentials. Users do not need to directly work with HashiCorp Vault. Vault encrypts data in transit (with TLS) and at rest (using AES 256-bit CBC encryption). This protects sensitive data from unauthorized access in two major ways: as it travels across the network as well as in storage in the cloud and data centers. But it is necessary for OpenShift administrator to understand that Vault is used underneath. For more information, please read the content of the following link: https://learn.hashicorp.com/vault. 
 
 ## Data in motion
 Data in motion is encrypted using transport layer security (TLS 1.2) to secure all inbound and outbound requests from Merlin. 
@@ -15,23 +15,23 @@ Network Policies are an application-centric construct which allow Merlin to spec
 
 Four Network Policies are created by Merlin
 * engine - defines that 'engine-0' pod is only allowed to be accessed by other pods, which are in the same namespace and owned by same Merlin instance, and the workspaces created by the same Merlin instance.
-* postgres - defines that the 'postgres-0' can only be accessed by engine, vault, keycloak pods in the same namespace. 
-* keycloak - defines that the 'keycloak-0' can only be accessed by engine, vault pods in the same namespace. 
-* vault - defines that the 'vault-0' can only be accessed by engine pod in the same namespace. 
+* postgres - defines that the 'postgres-0' can only be accessed by the engine, vault, and keycloak pods in the same namespace. 
+* keycloak - defines that the 'keycloak-0' can only be accessed by the engine, and vault pods in the same namespace. 
+* vault - defines that the 'vault-0' can only be accessed by the engine pod in the same namespace. 
 
 ## Manage certificate for Merlin
 Merlin uses cert-manager to manage all the certifications. 
 For more information refer to https://www.ibm.com/docs/en/cloud-paks/cp-management/1.2.0?topic=management-certificate-manager-cert-manager
 
-Merlin first creates a SelfSigned issuer resource, the SelfSigned issuer is for initially bootstrapping a CA issuer. Then issue a root certificate and use that root as a CA issuer. 
-The CA issuer will sign Merlin services certificate based on the private key.
+Merlin first creates a SelfSigned issuer resource. The SelfSigned issuer is for initially bootstrapping a CA issuer. Then it issues a root certificate and uses that root as a CA issuer. 
+The CA issuer will sign the Merlin services certificate based on the private key.
 
-The CA certificate stored in secret merlin-ca-secret, and the Merlin services certificate stored in secret merlin-https-cert.
+The CA certificate is stored in the secret merlin-ca-secret, and the Merlin services certificate is stored in the secret merlin-https-cert.
 
-Merlin external routes are re-encrypt secured routes, see https://docs.openshift.com/container-platform/4.10/networking/routes/secured-routes.html for more detail about secured route. The route resource is using the Openshift default ingress certificate and reencrypt TLS termination to destination CA certificate to enable the Ingress Controller to trust the service’s certificate.
+Merlin external routes are re-encrypt secured routes, see https://docs.openshift.com/container-platform/4.10/networking/routes/secured-routes.html for more detail about secured routes. The route resource is using the Openshift default ingress certificate and the reencrypt TLS termination to destination CA certificate to enable the Ingress Controller to trust the service’s certificate.
 
-There 2 steps to do if you want to use custom certificate both for Merlin services and routes:
-1. To use a custom certificate for Merlin services, manually create the merlin-ca-secret which contains the TLS key and certificate under the same namespace within Merlin before installing the Merlin. When installing Merlin, Merlin will not create the root CA but use the custom one as the root CA to sign the Merlin services certificate.
+There are two steps to do if you want to use a custom certificate for both Merlin services and routes:
+1. To use a custom certificate for Merlin services, manually create the merlin-ca-secret which contains the TLS key and certificate under the same namespace within Merlin before installing Merlin. When installing Merlin, Merlin will not create the root CA but instead it will use the custom one as the root CA to sign the Merlin services certificate.
 
     Use the following oc admin command to create the secret:
 
@@ -45,7 +45,7 @@ There 2 steps to do if you want to use custom certificate both for Merlin servic
     **Note**: This will replace the Openshift cluster default certificate.
 
 ## Manage Merlin secrets
-There are several secrects created when Merlin platform has been deployed. The key secrects are listed as follows:
+There are several secrets created when Merlin platform has been deployed. The key secrets are listed as follows:
 * merlin-ca-secret
 * merlin-credential-secret
 * merlin-https-cert
@@ -56,21 +56,21 @@ There are several secrects created when Merlin platform has been deployed. The k
 ### Customer Image Verification
 **Important**: Customer verification of container image signatures is not required at this point in time.  This documentation will provide a way for teams to enable their customers to verify the image signatures, but the customer can chose not to run the verification.  
 
-After the customer downloads the images to their Bastion server, they must do image signature verification before they transfer the downloaded images to their disconnected network.  Customers have the option to disable image signature verification, but this is a customer specific setting.  There are a few different options that can be used to verify the image signature, depending on the tooling the customer has, and this section will provide some examples and guidance around verifying the image signature. For more detailed signature verification documentation visit the IBM CISO Code Sign Service Documentation.
+After the customer downloads the images to their bastion server, they must do image signature verification before they transfer the downloaded images to their disconnected network.  Customers have the option to disable image signature verification, but this is a customer specific setting.  There are a few different options that can be used to verify the image signature, depending on the tooling the customer has, and this section will provide some examples and guidance around verifying the image signature. For more detailed signature verification documentation, visit the IBM CISO Code Sign Service Documentation.
 
 ### Enabling Customers to Verify the Image Signature
 The customer needs access to the public portion of the pgp key used to sign the image,  in order to verify the image signature of the downloaded image.  The ```$ucl pgp-key -n <alias>``` command will export the pgp key to your gpg key ring.  The private portion of this key will be a pointer to the HSM where the actual key data is stored, and the public portion will be readily available in the key ring.  This public key data will need to be provided to the customer, in order for them to verify the image signature.  The way a customer gets this public key data MUST be declared in the product offering's README file or Knowledge Center.  
 
 ### Portieris
-Portieris is the open source version of CISE, which is an admission controller for Kubernetes.  Portieris is being enhanced to support Red Hat signed image verification, and this will work out of the box on Red Hat OpenShift.  The admission controller will be installed to the cluster, and only allow images it can verify to be spun up and ran inside your cluster.   
+Portieris is the open source version of CISE, which is an admission controller for Kubernetes.  Portieris is being enhanced to support Red Hat signed image verification, and this will work out of the box on Red Hat OpenShift.  The admission controller will be installed to the cluster, and only allow images it can verify to be spun up and run inside your cluster.   
 
 ### OCP Verification 
 
 OCP verification is verification using any tool that relies on the atomic framework like: ```skopeo```, ```podman```, or ```oc```.  
 
 In OCP 4, signature validation for Red Hat signed images comes automatically when the image is pulled to the platform.  The /etc/containers/policy.json file is what drives the verification of image signatures in OCP. Follow these steps to configure automatic signature verification on OCP 4: 
 
-**Note**: If the customer wants to take advantage of this feature for oc image, then the public key for your offering must be imported to the disk of the machines for the cluster 
+**Note**: If the customer wants to take advantage of this feature for the oc image, then the public key for your offering must be imported to the disk of the machines for the cluster 
 
   1. Configure client to read from the entitled registry
   2. Create the necessary configuration files 
@@ -80,13 +80,13 @@ In OCP 4, signature validation for Red Hat signed images comes automatically whe
   4. Create a machine config that will write those files to disk on the worker nodes
   5. Apply the machine config yaml to the cluster
   6. Repeat for the master nodes
-  7. Verify the changes took place by describing themachine configs, refer to https://docs.openshift.com/container-platform/4.9/security/container_security/security-container-signature.html
+  7. Verify the changes took place by describing the machine configs, refer to https://docs.openshift.com/container-platform/4.9/security/container_security/security-container-signature.html
 
 ### Configure client to read from the entitled registry
 
 In order to configure the client binary to read from the entitled registry, there must be credentials provided to the docker config file ```$HOME/.docker/config.json```.
 
-Note: If using ```podmanto``` do the image pull and verification, then a ```$podman login``` to the entitled registry is all that is required to provide the necessary auth information.
+Note: If using ```podman``` to perform the image pull and verification, then a ```podman login``` to the entitled registry is all that is required to provide the necessary auth information.
   
     {
         "auths": {