Cleanup the style guide and fix random formatting errors. (#1417)

.spelling

@@ -29,6 +29,7 @@ API
 APIs
 Ansible
 AppOptics
+args.yaml
 AuthPolicy
 Autoscalers
 Bookinfo

content/about/contribute/style-guide.md

@@ -1,44 +1,22 @@
 ---
 title: Style Guide
-description: Explains the dos and donts of writing Istio docs.
+description: Explains the dos and donts of writing Istio documentation.
 weight: 70
 aliases:
     - /docs/welcome/contribute/style-guide.html
     - /docs/reference/contribute/style-guide.html
 ---
 
-TBD: This needs to be updated with Istio examples instead of Kubernetes examples.
+This page provides content guidelines for the Istio documentation.
-
+These are guidelines, not rules, so use your best judgment, and feel free to
-This page gives writing style guidelines for the Istio documentation.
-These are guidelines, not rules. Use your best judgment, and feel free to
 propose changes to this document in a pull request.
 
-For additional information on creating new content for the Istio
-docs, follow the instructions on
-[Creating a Doc Pull Request](/about/contribute/creating-a-pull-request/).
-
 ## Formatting standards
 
-### Use camelCase for API objects
+### Use consistent capitalization
 
-When you refer to an API object, use the same uppercase and lowercase letters
+Don't split configuration type names into separate words and follow the original capitalization. For
-that are used in the actual object name. Typically, the names of API
+example, use `IstioRoleBinding`, not `Istio Role Binding` or `istio role binding`.
-objects use
-[camelCase](https://en.wikipedia.org/wiki/Camel_case).
-
-Don't split the API object name into separate words. For example, use
-`PodTemplateList`, not Pod Template List.
-
-Refer to API objects without saying "object," unless omitting "object"
-leads to an awkward construction.
-
-|Do                                          |Don't
-|--------------------------------------------|------
-|The `Pod` has two Containers.                 |The pod has two containers.
-|The `Deployment` is responsible for ...       |The `Deployment` object is responsible for ...
-|A `PodList` is a list of Pods.                |A Pod List is a list of pods.
-|The two `ContainerPorts` ...                  |The two `ContainerPort` objects ...
-|The two `ContainerStateTerminated` objects ...|The two `ContainerStateTerminated` ...
 
 ### Use angle brackets for placeholders
 
@@ -71,9 +49,9 @@ represents.
 
 |Do                                   | Don't
 |-------------------------------------|------
-|Open the `envars.yaml` file.         | Open the envars.yaml file.
+|Open the `istio.yaml` file.         | Open the istio.yaml file.
-|Go to the `/_docs/tasks` directory.  | Go to the /docs/tasks directory.
+|Go to the `/content/docs/tasks` directory.  | Go to the /content/docs/tasks directory.
-|Open the `_data/concepts.yaml` file. | Open the /_data/concepts.yaml file.
+|Open the `/data/args.yaml` file. | Open the /data/args.yaml file.
 
 ### Use `code` style for inline code and commands
 
@@ -86,18 +64,8 @@ represents.
 
 |Do                                                               | Don't
 |-----------------------------------------------------------------|------
-|Set the value of the `replicas` field in the configuration file. | Set the value of the "replicas" field in the configuration file.
+|Set the value of the `ports` field in the configuration file. | Set the value of the "ports" field in the configuration file.
-|The value of the `exec` field is an ExecAction object.           | The value of the "exec" field is an ExecAction object.
+|The value of the `rule` field is a `Rule` object.           | The value of the "rule" field is a `Rule` object.
-
-### Use normal style for string and integer field values
-
-For field values of type string or integer, use normal style without quotation marks.
-
-|Do                                            | Don't
-|----------------------------------------------|------
-|Set the value of `imagePullPolicy` to Always. | Set the value of `imagePullPolicy` to "Always".
-|Set the value of `image` to nginx:1.8.        | Set the value of `image` to `nginx:1.8`.
-|Set the value of the `replicas` field to 2.   | Set the value of the `replicas` field to `2`.
 
 ### Only capitalize the first letter of headings
 
@@ -110,24 +78,6 @@ except if a word is a proper noun or an acronym.
 |Using Envoy for ingress | Using envoy for ingress
 |Using HTTPS             | Using https
 
-## Code snippet formatting
-
-### Don't include the command prompt
-
-|Do               | Don't
-|-----------------|------
-|`kubectl get pods` | `$ kubectl get pods`
-
-### Separate commands from output
-
-Verify that the pod is running on your chosen node:
-
-```command
-$ kubectl get pods --output=wide
-NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
-nginx    1/1       Running   0          13s    10.200.0.4   worker0
-```
-
 ## Terminology standards
 
 Some standard terms we want to use consistently within the documentation for clarity.
@@ -175,9 +125,7 @@ Not a proper noun. Use in place of service fabric.
 Use in the context of routing and multiple finer-grained versions of a service. Avoid using “service tags” or “service labels”
 which are the mechanism to identify the service versions, not the thing itself.
 
-## Content best practices
+## Best practices
-
-This section contains suggested best practices for clear, concise, and consistent content.
 
 ### Use present tense
 
@@ -222,8 +170,6 @@ mind when creating or reviewing site content.
 
 [Why “click here” is a terrible link, and what to write instead](http://stephanieleary.com/2015/05/why-click-here-is-a-terrible-link-and-what-to-write-instead/).
 
-## Patterns to avoid
-
 ### Avoid using "we"
 
 Using "we" in a sentence can be confusing, because the reader might not know
@@ -259,3 +205,9 @@ considered new in a few months.
 |------------------------------------|------
 |In version 1.4, ...                 | In the current version, ...
 |The Federation feature provides ... | The new Federation feature provides ...
+
+## What's next
+
+- Learn about [creating a new documentation topic](/about/contribute/writing-a-new-topic/).
+
+- Learn about [creating a documentation pull request](/about/contribute/creating-a-pull-request/).

content/about/release-cadence.md

@@ -39,7 +39,7 @@ Our naming scheme for LTS releases is:
 where `<minor>` is increased for every LTS release, and `<LTS patch level>` counts the number of patches for the
 current LTS release. A patch is usually a small change relative to the LTS.
 
-For snapshot releases, our numbering scheme is:
+For snapshot releases, our naming scheme is:
 
 ```plain
 <major>.<minor>.0-snapshot.<snapshot count>

content/docs/setup/kubernetes/quick-start.md

@@ -129,7 +129,7 @@ Nevertheless the list of admission controllers needs to be updated.
 $ kops edit cluster $YOURCLUSTER
 ```
 
-Add following in the configuration file just opened:
+Add the following in the configuration file:
 
 ```yaml
 kubeAPIServer:
@@ -254,7 +254,7 @@ For example, run the following command on a MacOS or Linux system:
 
 Install Istio's core components. Choose one of the four _**mutually exclusive**_ options below fo quick installation.  However, we recommend you to install with the [Helm Chart](/docs/setup/kubernetes/helm-install/) for production installations of Istio to leverage all the options to configure and customize Istio to your needs.
 
-a)  Install Istio without enabling [mutual TLS authentication](/docs/concepts/security/mutual-tls/) between     sidecars. Choose this option for clusters with existing applications, applications where services with an Istio sidecar need to be able to communicate with other non-Istio Kubernetes services, and applications that use [liveness and readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/), headless services, or StatefulSets.
+*  Install Istio without enabling [mutual TLS authentication](/docs/concepts/security/mutual-tls/) between sidecars. Choose this option for clusters with existing applications, applications where services with an Istio sidecar need to be able to communicate with other non-Istio Kubernetes services, and applications that use [liveness and readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/), headless services, or StatefulSets.
 
     ```command
     $ kubectl apply -f install/kubernetes/istio-demo.yaml
@@ -262,7 +262,7 @@ a)  Install Istio without enabling [mutual TLS authentication](/docs/concepts/se
 
 OR
 
-b)  Install Istio and enforce mutual TLS authentication between sidecars by default. Use this option only on a fresh kubernetes cluster where newly deployed workloads are guaranteed to have Istio sidecars installed.
+*  Install Istio and enforce mutual TLS authentication between sidecars by default. Use this option only on a fresh kubernetes cluster where newly deployed workloads are guaranteed to have Istio sidecars installed.
 
     ```command
     $ kubectl apply -f install/kubernetes/istio-demo-auth.yaml
@@ -270,11 +270,11 @@ b)  Install Istio and enforce mutual TLS authentication between sidecars by defa
 
 OR
 
-c)  [Render Kubernetes manifest with Helm and deploy with kubectl](/docs/setup/kubernetes/helm-install/#option-1-install-with-helm-via-helm-template).
+*  [Render Kubernetes manifest with Helm and deploy with kubectl](/docs/setup/kubernetes/helm-install/#option-1-install-with-helm-via-helm-template).
 
 OR
 
-d)  [Use Helm and Tiller to manage the Istio deployment](/docs/setup/kubernetes/helm-install/#option-2-install-with-helm-and-tiller-via-helm-install).
+*  [Use Helm and Tiller to manage the Istio deployment](/docs/setup/kubernetes/helm-install/#option-2-install-with-helm-and-tiller-via-helm-install).
 
 ## Verifying the installation
 
@@ -340,19 +340,17 @@ $ kubectl create -f <(istioctl kube-inject -f <your-app-spec>.yaml)
 
 ## Uninstalling
 
-*   Uninstall Istio core components. For the {{site.data.istio.version}} release, the uninstall
+*   Uninstall Istio core components. For this release, the uninstall
 deletes the RBAC permissions, the `istio-system` namespace, and hierarchically all resources under it.
 It is safe to ignore errors for non-existent resources because they may have been deleted hierarchically.
 
-    a) If you installed Istio with `istio-demo.yaml`:
+If you installed Istio with `istio-demo.yaml`:
 
 ```command
 $ kubectl delete -f install/kubernetes/istio-demo.yaml
 ```
 
-    _**OR**_
+otherwise [uninstall Istio with Helm](/docs/setup/kubernetes/helm-install/#uninstall).
-
-    b) : [Uninstall Istio with Helm](/docs/setup/kubernetes/helm-install/#uninstall).
 
 ## What's next
 

content/docs/setup/kubernetes/upgrading-istio.md

@@ -138,7 +138,7 @@ When all your applications have been migrated and tested, you can repeat the Ist
 `--set global.proxy.image=proxy` option.  This will set the default proxy to `docker.io/istio/proxyv2` for all
 sidecars injected in the future.
 
-### Migrating per-service mutual TLS enablement via annotations to authentication policy
+## Migrating per-service mutual TLS enablement via annotations to authentication policy
 
 If you use service annotations to override global mutual TLS enablement for a service, you need to replace it with [authentication policy](/docs/concepts/security/authn-policy/) and [destination rules](/docs/concepts/traffic-management/rules-configuration/#destination-rules).
 
@@ -214,7 +214,7 @@ trafficPolicy:
     mode: DISABLE
 ```
 
-### Migrating `mtls_excluded_services` config to destination rules
+## Migrating `mtls_excluded_services` config to destination rules
 
 If you installed Istio with mutual TLS enabled, and used mesh config `mtls_excluded_services` to disable mutual TLS when connecting to these services (e.g kubernetes API server), you need to replace this by adding a destination rule. For example:
 

content/docs/tasks/security/https-overlay.md

@@ -22,13 +22,10 @@ Note that authentication should be **disabled** at step 5 in the
 
 ### Generate certificates and configmap
 
-You need to have openssl installed to run this command
+You need to have openssl installed to run these commands:
 
 ```command
 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /tmp/nginx.key -out /tmp/nginx.crt -subj "/CN=my-nginx/O=my-nginx"
-```
-
-```command
 $ kubectl create secret tls nginxsecret --key /tmp/nginx.key --cert /tmp/nginx.crt
 $ secret "nginxsecret" created
 ```

content/docs/tasks/security/mutual-tls.md

@@ -1,5 +1,5 @@
 ---
-title: Testing mutual TLS
+title: Testing Mutual TLS
 description: Shows you how to verify and test Istio's automatic mutual TLS authentication.
 weight: 10
 ---
@@ -15,6 +15,7 @@ Through this task, you will learn how to:
 This task assumes you have a Kubernetes cluster:
 
 * Installed Istio with global mTLS enabled:
+
     ```command
     $ kubectl apply -f install/kubernetes/istio-auth.yaml
     ```
@@ -83,6 +84,7 @@ Istio automatically installs necessary keys and certificates for mutual TLS auth
 In this example, we only have one Citadel in a cluster, so all Envoys have the same `root-cert.pem`.
 
 Use the `oppenssl` tool to check if certificate is valid (current time should be in between `Not Before` and `Not After`)
+
 ```command
 $ kubectl exec $(kubectl get pod -l app=httpbin -o jsonpath={.items..metadata.name}) -c istio-proxy -- cat /etc/certs/cert-chain.pem | openssl x509 -text -noout  | grep Validity -A 2
 Validity
@@ -91,6 +93,7 @@ Use the `oppenssl` tool to check if certificate is valid (current time should be
 ```
 
 You can also check the _identity_ of the client certificate:
+
 ```command
 $ kubectl exec $(kubectl get pod -l app=httpbin -o jsonpath={.items..metadata.name}) -c istio-proxy -- cat /etc/certs/cert-chain.pem | openssl x509 -text -noout  | grep 'Subject Alternative Name' -A 1
         X509v3 Subject Alternative Name:
@@ -104,12 +107,14 @@ Please check [secure naming](/docs/concepts/security/mutual-tls/#workflow) for m
 Assuming mutual TLS authentication is properly turned on, it should not affect communication from one service to another when both sides have the Envoy sidecar. However, requests from pod without sidecar, or requests directly from sidecar without a client certificate should fail. Examples below illustrates this behavior.
 
 1. Request from `sleep` app container to `httpbin` service should succeed (return `200`)
+
     ```command
     $ kubectl exec $(kubectl get pod -l app=sleep -o jsonpath={.items..metadata.name}) -c sleep -- curl httpbin:8000/headers -o /dev/null -s -w '%{http_code}\n'
     200
     ```
 
 1. Request from `sleep` _proxy_ container to `httpbin` service on the other hand fails, as request does not use TLS nor provide a client certificate
+
     ```command
     $ kubectl exec $(kubectl get pod -l app=sleep -o jsonpath={.items..metadata.name}) -c istio-proxy -- curl httpbin:8000/headers -o /dev/null -s -w '%{http_code}\n'
     000
@@ -122,6 +127,7 @@ Assuming mutual TLS authentication is properly turned on, it should not affect c
     ```
 
 1. However, request will success if client certificate is provided
+
     ```command
     $ kubectl exec $(kubectl get pod -l app=sleep -o jsonpath={.items..metadata.name}) -c istio-proxy -- curl https://httpbin:8000/headers -o /dev/null -s -w '%{http_code}\n' --key /etc/certs/key.pem --cert /etc/certs/cert-chain.pem --cacert /etc/certs/root-cert.pem -k'
     200
@@ -130,16 +136,20 @@ Assuming mutual TLS authentication is properly turned on, it should not affect c
     > Istio uses [Kubernetes service accounts](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) as service identity, which offers stronger security than service name (refer [here](/docs/concepts/security/mutual-tls/#identity) for more information). Thus the certificates used in Istio do not have service names, which is the information that `curl` needs to verify server identity. As a result, we use `curl` option `-k` to prevent the `curl` client from aborting when failing to find and verify the server name (i.e., httpbin.ns.svc.cluster.local) in the certificate provided by the server.
 
 1. Request from pod without sidecar. For this demo, let's install another `sleep` service without sidecar. To avoid name conflicts, we put it in different namespace.
+
     ```command
     $ kubectl create ns legacy
     $ kubectl apply -f samples/sleep/sleep.yaml -n legacy
     ```
-Wait after the pod status changes to `Running`, issue the familiar `curl` command. The request should fail as the pod doesn't have a sidecar to help initiate TLS communication.
+
+1. Wait after the pod status changes to `Running`, issue the familiar `curl` command. The request should fail as the pod doesn't have a sidecar to help initiate TLS communication.
+
     ```command
     kubectl exec $(kubectl get pod -l app=sleep -o jsonpath={.items..metadata.name} -n legacy) -c sleep -n legacy -- curl httpbin.default:8000/headers -o /dev/null -s -w '%{http_code}\n'
     000
     command terminated with exit code 56
     ```
+
 ## What's next
 
 * Learn more about the design principles behind Istio's automatic mTLS authentication

content/help/faq/general/what-deployment-environment.md

@@ -4,6 +4,6 @@ weight: 60
 ---
 
 Istio is designed and built to be platform-independent. For our
-{{site.data.istio.version}} release, Istio supports environments running
+{{< istio_version >}} release, Istio supports environments running
 container orchestration platforms such as Kubernetes (v1.7.4 or greater)
 and Nomad (with Consul).