Update docs

pcbailey · pcbailey · commit d23888ff0ec3 · 2021-09-01T08:08:28.000-04:00
diff --git a/README.md b/README.md
@@ -5,9 +5,9 @@
 
 ![alt gopher network](https://raw.githubusercontent.com/kubevirt-ui/kube-gateway-operator/main/docs/network-side.png)
 
-kube-gateway-operator installs and operate [kube-gateway](https://github.com/kubevirt-ui/kube-gateway), kube-gateway allow access k8s API using time limited access tokens, kube-gateway allow usage of one time access tokens to k8s resources.
+The kube-gateway-operator installs and operates the [kube-gateway](https://github.com/kubevirt-ui/kube-gateway) service, which allows access to the k8s API using time-limited access tokens and usage of one-time access tokens to access k8s resources.
 
-The operator manges service accounts, permisions, secrets needed for operatin of [kube-gateway](https://github.com/kubevirt-ui/kube-gateway) and JWT token generation for one time k8s API access.
+The operator manages service accounts, permissions, and secrets needed for the operation of the [kube-gateway](https://github.com/kubevirt-ui/kube-gateway) service and JWT token generation used for one-time k8s API access.
 
 ## Build and push images
 
@@ -22,18 +22,17 @@ IMG=quay.io/$USERNAME/kube-gateway-operator:v0.0.1 make podman-push
 For more information about deployment options see the [deploy](/docs/deploy.md) doc.
 
 ```bash
-# Deploy the operator, RBAC roles and CRDs
+# Deploy the operator, RBAC roles, and CRDs
 export USERNAME=yaacov
 IMG=quay.io/$USERNAME/kube-gateway-operator:v0.0.1 make deploy
 
-# Deploy from an example deployment yaml
-# Will use pre-defined images and permistions, users can also copy this file to local
-# directory and edit the container image used.
+# Deploy from an example deployment yaml. Will use pre-defined images and permissions. 
+# Users can also copy this file to a local directory and edit the container image used.
 oc create -f https://raw.githubusercontent.com/kubevirt-ui/kube-gateway-operator/main/deploy/kube-gateway-operator.yaml
 ```
 
 ```bash
-# Remove deployment of the operator, RBAC roles and CRDs
+# Remove deployment of the operator, RBAC roles, and CRDs
 export USERNAME=yaacov
 IMG=quay.io/$USERNAME/kube-gateway-operator:v0.0.1 make undeploy
 ```
@@ -48,13 +47,13 @@ For more information about running the gateway proxy and generating a token see
 # Use the kube-gateway namespace
 oc create namespace kube-gateway
 
-# create a sample gateway server
+# Create a sample gateway server
 oc create -f config/samples/kubegateway_v1beta1_gateserver.yaml
 
-# create a sample token request
+# Create a sample token request
 oc create -f config/samples/kubegateway_v1beta1_gatetoken.yaml
 
-# check the token
+# Check the token
 oc get gatetoken gatetoken-sample -o yaml
 ```
 Example files:
@@ -66,10 +65,10 @@ Example files:
 ## Building for local development
 
 ```bash
-# Compile operator
+# Compile the operator
 make
 
-# Install CRD on cluser for running loaclly
+# Install CRDs on the cluster for running locally
 make install
 # make uninstall
 
diff --git a/docs/deploy.md b/docs/deploy.md
@@ -1,47 +1,47 @@
 # Deploy
 
-## Deploy using the example deployment
+## Deploy using the example deployment file
 
-The example deployment, use images from `quay.io/kubevirt-ui` and `gcr.io/kubebuilder`
+The example deployment file use images from `quay.io/kubevirt-ui` and `gcr.io/kubebuilder`.
 If your installation is connected to the internet and you do not intend to customize the images,
-Deployment using the example deployment file can be a good option.
+deployment using the example deployment file can be a good option.
 
 ```bash
 oc create -f https://raw.githubusercontent.com/kubevirt-ui/kube-gateway-operator/main/deploy/kube-gateway-operator.yaml
 ```
 
-## Deploy using customized / local images 
+## Deploy using customized/local images 
 
-The gateway operator deployment use 3 container images that need customization.
+The gateway operator deployment uses three container images that require customization.
 A user may use the default images or customized ones.
 
 | Image | Description
 |---|---
-| gcr.io/kubebuilder/kube-rbac-proxy:v0.5.0 | rbac proxy used by the operator manager
-| quay.io/kubevirt-ui/kube-gateway:latest | the kube gateway proxy server
-| quay.io/kubevirt-ui/kube-gateway-operator:v0.0.1 | the kube gateway operator image
+| gcr.io/kubebuilder/kube-rbac-proxy:v0.5.0 | RBAC proxy used by the operator manager
+| quay.io/kubevirt-ui/kube-gateway:latest | The kube-gateway proxy server
+| quay.io/kubevirt-ui/kube-gateway-operator:v0.0.1 | The kube-gateway operator image
 
-To cusomize the deployment replace this images in the example file:
+To customize the deployment, replace these images in the example file:
 
 ```bash
 curl https://raw.githubusercontent.com/kubevirt-ui/kube-gateway-operator/main/deploy/kube-gateway-operator.yaml > operator.yaml
 
-# Check the current images for rbac-proxy, kube-gateway and kube-gateway-operator
-# and replacy them with you customize / local images.
+# Check the current images for the rbac-proxy, kube-gateway, and kube-gateway-operator
+# files and replace them with your customized/local images.
 
 # Here is an example script for replacing the images:
-RBAC_IMAG=gcr.io/kubebuilder/kube-rbac-proxy:v0.5.0
-GATEWAY_IMAG=quay.io/kubevirt-ui/kube-gateway:latest
-GATEWAY_OPERATOR_IMAG=quay.io/kubevirt-ui/kube-gateway-operator:v0.0.1
+RBAC_IMAGE=gcr.io/kubebuilder/kube-rbac-proxy:v0.5.0
+GATEWAY_IMAGE=quay.io/kubevirt-ui/kube-gateway:latest
+GATEWAY_OPERATOR_IMAGE=quay.io/kubevirt-ui/kube-gateway-operator:v0.0.1
 
-RBAC_IMAG_CI=ci.org/gateway/kube-rbac-proxy@sha256~1234
-sed -i "s|${RBAC_IMAG}|${RBAC_IMAG_CI}|g;" operator.yaml
+RBAC_IMAGE_CI=ci.org/gateway/kube-rbac-proxy@sha256~1234
+sed -i "s|${RBAC_IMAGE}|${RBAC_IMAGE_CI}|g;" operator.yaml
 
 GATEWAY_IMAG_CI=ci.org/gateway/kube-gateway@sha256~1234
-sed -i "s|${GATEWAY_IMAG}|${GATEWAY_IMAG_CI}|g;" operator.yaml
+sed -i "s|${GATEWAY_IMAGE}|${GATEWAY_IMAGE_CI}|g;" operator.yaml
 
-GATEWAY_OPERATOR_IMAG_CI=ci.org/gateway/kube-gateway-operator@sha256~1234
-sed -i "s|${GATEWAY_OPERATOR_IMAG}|${GATEWAY_OPERATOR_IMAG_CI}|g;" operator.yaml
+GATEWAY_OPERATOR_IMAGE_CI=ci.org/gateway/kube-gateway-operator@sha256~1234
+sed -i "s|${GATEWAY_OPERATOR_IMAGE}|${GATEWAY_OPERATOR_IMAGE_CI}|g;" operator.yaml
 ```
 
 ```bash
@@ -51,17 +51,17 @@ oc create -f operator.yaml
 
 ## Starting a gateway
 
-Now that the operator it installed, we can start running a kube gateway server.
-Create the proxy in the namespace that contain the k8s resources you with to expose.
+Now that the operator is installed, we can start running a kube-gateway server.
+Create the proxy in the namespace that contains the k8s resources you wish to expose.
 
-For this example, we will create a namespace called "gateway-example" and spin up a gateway server:
+For this example, we will create a namespace called "gateway-example" and spin up a gateway server.
 
 ```bash
 oc new-project gateway-example
 ```
 
-Set the `namespace`, `route` and `image`
-`namespace` - the namespace to expose k8s resources
+Set the `namespace`, `route` and `image`.
+`namespace` - the namespace containing the k8s resources to be exposed
 `route` - the host of the proxy server
 `image` - the `kube-gateway` container image
 
@@ -80,9 +80,9 @@ EOF
 
 The gateway manager pod should start running in the namespace.
 
-### Note: the secret holding the private key for signing the token
+### Important note
 
-When creating signed tokens for this gateway proxy, a user must know the secret name:
+When creating signed tokens for this gateway proxy, a user must know the name of the secret holding the private key for signing the token.
 
 ```bash
 oc get secrets -n gateway-example | grep jwt-secret
diff --git a/docs/token.md b/docs/token.md
@@ -4,10 +4,10 @@ Generating a signed token requires access to the secret holding the private key.
 
 ## Getting the name of the secret
 
-When spinning up a gateway server it creates a secret containing the private
+When a gateway server spins up it creates a secret containing the private
 and public keys used to sign and authenticate the JWT tokens.
 
-The secret will end with `jwt-secret`:
+The name of the secret will end with `jwt-secret`:
 
 ```bash
 oc get secrets -n <namespace running the gateway proxy> | grep jwt-secret
@@ -43,40 +43,40 @@ EOF
 
 ## Generating a token
 
-The folowing example describe how to create a token resource using a curl commend to access kubevirt vnc server.
+The following example describes how to create a token resource using a curl command to access the kubevirt VNC server.
 
 ```bash
-# Set the vm name
+# Set the VM name
 vm=testvm
-# Set the vm namespace (the virtual machine must be in the same namespace as the proxy)
+# Set the VM namespace (the virtual machine must be in the same namespace as the proxy)
 ns=gateway-example
 
-# Generate the vnc subresource path
+# Generate the VNC subresource path
 path=/apis/subresources.kubevirt.io/v1/namespaces/$ns/virtualmachineinstances/$vm/vnc
 
-# Get the admin user k8s bearer token, and the k8s API path,
-# We will use the k8s API and credentials to create the gatetoken resource
-# NOTE: users should know the admin token and k8s api host, the scripts here 
-#       gets this value using oc command only for this example.
+# Get the admin user's k8s bearer token and the k8s API path.
+# We will use the k8s API and credentials to create the gatetoken resource.
+# NOTE: Users should know the admin token and k8s API host. The script here 
+#       gets this value using only the oc command for this example.
 token=$(oc whoami -t)
 apipath=$(oc whoami --show-server)/apis/kubegateway.kubevirt.io/v1beta1/namespaces/$ns/gatetokens
 
 # Get the name of the secret holding the private key for signing the gatetoken
-# NOTE: users should know the secret name, the script here
-#       gets this value using oc command only for this example.
+# NOTE: Users should know the secret name. The script here
+#       gets this value using only the oc command for this example.
 secret_name=$(oc get secrets -n $ns -o name | grep jwt-secret | cut -d "/" -f2)
 
-# Generate a uniqe gatetoken name
+# Generate a unique gatetoken name
 date=$(date "+%y%m%d%H%M")
 name=$vm-$date
 
 # Create the gatetoken resource
 data="{\"apiVersion\":\"kubegateway.kubevirt.io/v1beta1\",\"kind\":\"GateToken\",\"metadata\":{\"name\":\"$name\",\"namespace\":\"$ns\"},\"spec\":{\"secret-name\":\"$secret_name\",\"urls\":[\"$path\"]}}"
 
-# Call k8s API using admin credentials to create a new gatetoken
+# Call the k8s API using admin credentials to create a new gatetoken
 curl -k -H 'Accept: application/json' -H "Authorization: Bearer $token" -H "Content-Type: application/json" --request POST --data $data $apipath
 
-# Another way to create the gatetoken is using the oc command
+# You can also create the gatetoken using the oc command
 # cat <<EOF | oc create -f -
 # apiVersion: kubegateway.kubevirt.io/v1beta1
 # kind: GateToken\
@@ -90,15 +90,16 @@ curl -k -H 'Accept: application/json' -H "Authorization: Bearer $token" -H "Cont
 # EOF
 ```
 
-## Get the JWT singed token from the token resource
+## Get the JWT signed token from the token resource
 
-Once a token resource is registered it will try to sign the token, get the sign token:
+Once a token resource is registered it will try to sign the token. Get the signed token:
 
 ```bash
 # Get the token resource
 curl -k -H 'Accept: application/json' -H "Authorization: Bearer $token" $apipath/$name
 
-# Another way to get the gatetoke is using the oc command: oc get gatetoken $name -o json
+# You can also get the gatetoken using the oc command
+# oc get gatetoken $name -o json
 ```
 
 ## Use the token to access the resource
@@ -107,16 +108,16 @@ curl -k -H 'Accept: application/json' -H "Authorization: Bearer $token" $apipath
 # Get the JWT from the gatetoken resource using admin credentials
 jwt=$(curl -k -H 'Accept: application/json' -H "Authorization: Bearer $token" $apipath/$name | jq .status.token)
 
-# Another way to get the gatetoken is using the oc command
+# You can also get the gatetoken using the oc command
 # oc get gatetoken $name -o json | jq .status.token
 
-# The proxy URL is set in the gateserver spec
+# The proxy URL is set in the gateserver spec.
 proxyurl=https://$(oc get gateserver -o json | jq -r .items[0].spec.route)
 
 # The link is signed using ${jwt} and will access the k8s API at ${path}.
 signed_link="${proxyurl}/auth/jwt/set?token=${jwt}&then=/noVNC/vnc_lite.html?path=k8s${path}"
 
-# Users holding the signed link will be able to use it for 1h:
+# Users holding the signed link will be able to use it for 1 hour.
 
 # Open the link in a browser
 google-chrome "${signed_link}"
