istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

(cherry picked from commit de871cb)
This commit is contained in:
Martin Taillefer 2018-06-02 22:29:14 -07:00 committed by mtail
parent 677dfdc5c5
commit 9b614f4853
8 changed files with 81 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.spelling
View File

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

84
content/about/contribute/style-guide.md
View File

@ -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 gives writing style guidelines for the Istio documentation.
These are guidelines, not rules. Use your best judgment, and feel free to
This page provides content guidelines for the Istio documentation.
These are guidelines, not rules, so 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
that are used in the actual object name. Typically, the names of API
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` ...
Don't split configuration type names into separate words and follow the original capitalization. For
example, use `IstioRoleBinding`, not `Istio Role Binding` or `istio role binding`.
### Use angle brackets for placeholders
@ -71,9 +49,9 @@ represents.
|Do | Don't
|-------------------------------------|------
|Open the `envars.yaml` file. | Open the envars.yaml file.
|Go to the `/_docs/tasks` directory. | Go to the /docs/tasks directory.
|Open the `_data/concepts.yaml` file. | Open the /_data/concepts.yaml file.
|Open the `istio.yaml` file. | Open the istio.yaml file.
|Go to the `/content/docs/tasks` directory. | Go to the /content/docs/tasks directory.
|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.
|The value of the `exec` field is an ExecAction object. | The value of the "exec" field is an ExecAction 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`.
|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 `rule` field is a `Rule` object. | The value of the "rule" field is a `Rule` object.
### 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
This section contains suggested best practices for clear, concise, and consistent content.
## Best practices
### 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/).

2
content/about/release-cadence.md
View File

@ -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>

24
content/docs/setup/kubernetes/quick-start.md
View File

@ -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
```
```command
$ kubectl delete -f install/kubernetes/istio-demo.yaml
```
_**OR**_
b) : [Uninstall Istio with Helm](/docs/setup/kubernetes/helm-install/#uninstall).
otherwise [uninstall Istio with Helm](/docs/setup/kubernetes/helm-install/#uninstall).
## What's next

4
content/docs/setup/kubernetes/upgrading-istio.md
View File

@ -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:

5
content/docs/tasks/security/https-overlay.md
View File

@ -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
```

82
content/docs/tasks/security/mutual-tls.md
View File

@ -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
```
@ -71,31 +72,33 @@ Citadel is up if the "AVAILABLE" column is 1.
Istio automatically installs necessary keys and certificates for mutual TLS authentication in all sidecar containers.
```command
$ kubectl exec $(kubectl get pod -l app=httpbin -o jsonpath={.items..metadata.name}) -c istio-proxy -- ls /etc/certs
cert-chain.pem
key.pem
root-cert.pem
```
```command
$ kubectl exec $(kubectl get pod -l app=httpbin -o jsonpath={.items..metadata.name}) -c istio-proxy -- ls /etc/certs
cert-chain.pem
key.pem
root-cert.pem
```
> `cert-chain.pem` is Envoy's cert that needs to be presented to the other side. `key.pem` is Envoy's private key
paired with Envoy's cert in `cert-chain.pem`. `root-cert.pem` is the root cert to verify the peer's cert.
In this example, we only have one Citadel in a cluster, so all Envoys have the same `root-cert.pem`.
> `cert-chain.pem` is Envoy's cert that needs to be presented to the other side. `key.pem` is Envoy's private key
paired with Envoy's cert in `cert-chain.pem`. `root-cert.pem` is the root cert to verify the peer's cert.
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
Not Before: May 17 23:02:11 2018 GMT
Not After : Aug 15 23:02:11 2018 GMT
```
```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
Not Before: May 17 23:02:11 2018 GMT
Not After : Aug 15 23:02:11 2018 GMT
```
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:
URI:spiffe://cluster.local/ns/default/sa/default
```
```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:
URI:spiffe://cluster.local/ns/default/sa/default
```
Please check [secure naming](/docs/concepts/security/mutual-tls/#workflow) for more information about _service identity_ in Istio.
@ -104,24 +107,27 @@ 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
```
```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
command terminated with exit code 56
```
```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'
000
command terminated with exit code 77
```
```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
command terminated with exit code 56
```
```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'
000
command terminated with exit code 77
```
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

2
content/help/faq/general/what-deployment-environment.md
View File

@ -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).