| 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 ContainerStateTerminateds ... |
| Do | Don't |
|---|---|
| Click Fork. | Click "Fork". |
| Select Other. | Select 'Other'. |
| Do | Don't |
|---|---|
| A cluster is a set of nodes ... | A "cluster" is a set of nodes ... |
| These components form the control plane. | These components form the control plane. |
| Do | Don't |
|---|---|
Open the envars.yaml file. | Open the envars.yaml file. |
Go to the /docs/tutorials directory. | Go to the /docs/tutorials directory. |
Open the /_data/concepts.yaml file. | Open the /_data/concepts.yaml file. |
` tag. In a Markdown
-document, use the backtick (`).
+### Use `code` style for object field names
-
- Do Don't The kubectl run command creates a Deployment. The "kubectl run" command creates a Deployment. For declarative management, use kubectl apply. For declarative management, use "kubectl apply".
-
-### Use code style for object field names
-
-
- 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.
+|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.
+|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
+
+For any headings, only apply an uppercase letter to the first word of the heading,
+except is a word is a proper noun or an acronym.
+
+|Do | Don't
+|------------------------|-----
+|Configuring rate limits | Configuring Rate Limits
+|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
+|Do | Don't
+|-----------------|------
+|kubectl get pods | $ kubectl get pods
### Separate commands from output
Verify that the pod is running on your chosen node:
- kubectl get pods --output=wide
-
+```bash
+kubectl get pods --output=wide
+```
The output is similar to this:
- NAME READY STATUS RESTARTS AGE IP NODE
- nginx 1/1 Running 0 13s 10.200.0.4 worker0
+```bash
+NAME READY STATUS RESTARTS AGE IP NODE
+nginx 1/1 Running 0 13s 10.200.0.4 worker0
+```
+## Terminology standards
-{% comment %}## istio.io word list
+Some standard terms we want to use consistently within the documentation for clarity.
-A list of Istio-specific terms and words to be used consistently across the site.
+### Envoy
-
- Term Useage TBD TBD
{% endcomment %}
+We prefer to use “Envoy” as it’s a more concrete term than "proxy" and will resonate if used
+consistently throughout the docs.
+Synonyms:
+
+- “Envoy sidecar” - ok
+- “Envoy proxy” - ok
+- “The Istio proxy” -- best to avoid unless you’re talking about advanced scenarios where another proxy might be used.
+- “Sidecar” -- mostly restricted to conceptual docs
+- “Proxy -- only if context is obvious
+
+Related Terms
+
+- Proxy agent - This is a minor infrastructural component and should only show up in low-level detail documentation.
+It is not a proper noun.
+
+### Mixer
+
+Mixer is a proper noun and should be used as such:
+
+- “You configure Mixer by ….”
+- “Mixer provides a standard vehicle for implementing organizational wide policy”
+
+### Attributes
+
+Not a proper noun but we should attempt to consistently use the term to describe inputs to Mixer and NOT use the term when talking about other
+forms of configuration.
+
+### Service mesh
+
+Not a proper noun. Use in place of service fabric.
+
+### Service version
+
+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
@@ -147,21 +179,19 @@ This section contains suggested best practices for clear, concise, and consisten
### Use present tense
-
- Do Don't This command starts a proxy. This command will start a proxy.
+|Do | Don't
+|-----------------------------|------
+|This command starts a proxy. | This command will start a proxy.
Exception: Use future or past tense if it is required to convey the correct
meaning.
### Use active voice
-
- Do Don't You can explore the API using a browser. The API can be explored using a browser. The YAML file specifies the replica count. The replica count is specified in the YAML file.
+|Do | Don't
+|-------------------------------------------|------
+|You can explore the API using a browser. | The API can be explored using a browser.
+|The YAML file specifies the replica count. | The replica count is specified in the YAML file.
Exception: Use passive voice if active voice leads to an awkward construction.
@@ -169,21 +199,18 @@ Exception: Use passive voice if active voice leads to an awkward construction.
Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."
-
- Do Don't To create a ReplicaSet, ... In order to create a ReplicaSet, ... See the configuration file. Please see the configuration file. View the Pods. With this next command, we'll view the Pods.
+|Do | Don't
+|----------------------------|------
+|To create a ReplicaSet, ... | In order to create a ReplicaSet, ...
+|See the configuration file. | Please see the configuration file.
+|View the Pods. | With this next command, we'll view the Pods.
### Address the reader as "you"
-
- Do Don't You can create a Deployment by ... We'll create a Deployment by ... In the preceding output, you can see... In the preceding output, we can see ...
+|Do | Don't
+|---------------------------------------|------
+|You can create a Deployment by ... | We'll create a Deployment by ...
+|In the preceding output, you can see...| In the preceding output, we can see ...
## Patterns to avoid
@@ -192,22 +219,20 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying
Using "we" in a sentence can be confusing, because the reader might not know
whether they're part of the "we" you're describing.
-
- Do Don't Version 1.4 includes ... In version 1.4, we have added ... Kubernetes provides a new feature for ... We provide a new feature ... This page teaches you how to use pods. In this page, we are going to learn about pods.
+|Do | Don't
+|------------------------------------------|------
+|Version 1.4 includes ... | In version 1.4, we have added ...
+|Kubernetes provides a new feature for ... | We provide a new feature ...
+|This page teaches you how to use pods. | In this page, we are going to learn about pods.
### Avoid jargon and idioms
Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier.
-
- Do Don't Internally, ... Under the hood, ... Create a new cluster. Turn up a new cluster.
+|Do | Don't
+|----------------------|------
+|Internally, ... | Under the hood, ...
+|Create a new cluster. | Turn up a new cluster.
### Avoid statements about the future
@@ -220,8 +245,7 @@ information.
Avoid words like "currently" and "new." A feature that is new today might not be
considered new in a few months.
-
- Do Don't In version 1.4, ... In the current version, ... The Federation feature provides ... The new Federation feature provides ...
+|Do | Don't
+|------------------------------------|------
+|In version 1.4, ... | In the current version, ...
+|The Federation feature provides ... | The new Federation feature provides ...
diff --git a/_docs/reference/contribute/writing-a-new-topic.md b/_docs/reference/contribute/writing-a-new-topic.md
index 39d7b34d69..a8c2b3312b 100644
--- a/_docs/reference/contribute/writing-a-new-topic.md
+++ b/_docs/reference/contribute/writing-a-new-topic.md
@@ -49,13 +49,6 @@ is the best fit for your content:
A task page shows how to do a single thing, typically by giving a short sequence of steps. Task pages have minimal
explanation, but often provide links to conceptual topics that provide related background and knowledge.
-
-
- Tutorial
- A tutorial page shows how to accomplish a goal that is larger than a single task. Typically a tutorial
- page has several sections, each of which has a sequence of steps. Tutorials can include surface-level explanations,
- but should link to related conceptual topics for deep explanations.
-
Each page type has a template file located in the corresponding directory which shows
@@ -84,18 +77,19 @@ The front matter is a block of YAML that is between the
triple-dashed lines at the top of each file. Here's the
chunk of front matter you should start with:
- ---
- title: TITLE_TBD
- overview: OVERVIEW_TBD
+```
+---
+title:
+overview: <overview>
- order: ORDER_TBD
+order: <order>
- layout: docs
- type: markdown
- ---
+layout: docs
+type: markdown
+```
Copy the above at the start of your new markdown file and update
-the TBD fields for your particular file. The available front
+the `<title>`, `<overview>` and `<order>` fields for your particular file. The available front
matter fields are:
|Field | Description
@@ -103,7 +97,7 @@ matter fields are:
|`title` | The short title of the page
|`overview` | a one-line description of what the topic is about
|`order` | integer used for sort order
-|`layout' | indicates which of the Jekyll layouts this page uses
+|`layout` | indicates which of the Jekyll layouts this page uses
|`index` | indicates whether the page should appear in the doc's top nav tabs
## Choosing a directory
@@ -114,7 +108,6 @@ Depending on your page type, put your new file in a subdirectory of one of these
* _docs/reference/
* _docs/samples/
* _docs/tasks/
-* _docs/tutorials/
You can put your file in an existing subdirectory, or you can create a new
subdirectory.
diff --git a/_docs/reference/istioctl/istioctl.md b/_docs/reference/istioctl/istioctl.md
index 2047c87d3a..454c232029 100644
--- a/_docs/reference/istioctl/istioctl.md
+++ b/_docs/reference/istioctl/istioctl.md
@@ -18,7 +18,7 @@ Istio configuration command line utility.
Create, list, modify, and delete configuration resources in the Istio system.
Available routing and traffic management configuration types: [destination-policy ingress-rule route-rule]. See
-https://istio.io/docs/reference/routing-and-traffic-management.html
+[here](/docs/reference/traffic-management/routing-and-traffic-management.html)
for an overview of the routing and traffic DSL.
More information on the mixer API configuration can be found under the
diff --git a/_docs/reference/istioctl/istioctl_create.md b/_docs/reference/istioctl/istioctl_create.md
index fe86c53810..2d038819ee 100644
--- a/_docs/reference/istioctl/istioctl_create.md
+++ b/_docs/reference/istioctl/istioctl_create.md
@@ -16,7 +16,7 @@ Create policies and rules
Example usage:
# Create a rule using the definition in example-routing.yaml.
- $ istioctl create -f example-routing.yaml
+ istioctl create -f example-routing.yaml
```
diff --git a/_docs/reference/istioctl/istioctl_delete.md b/_docs/reference/istioctl/istioctl_delete.md
index 2acb3767b9..07dcc88434 100644
--- a/_docs/reference/istioctl/istioctl_delete.md
+++ b/_docs/reference/istioctl/istioctl_delete.md
@@ -16,10 +16,10 @@ Delete policies or rules
Example usage:
# Delete a rule using the definition in example-routing.yaml.
- $ istioctl delete -f example-routing.yaml
+ istioctl delete -f example-routing.yaml
# Delete the rule productpage-default
- $ istioctl delete route-rule productpage-default
+ istioctl delete route-rule productpage-default
```
diff --git a/_docs/reference/istioctl/istioctl_replace.md b/_docs/reference/istioctl/istioctl_replace.md
index 66005c6426..6d836218cd 100644
--- a/_docs/reference/istioctl/istioctl_replace.md
+++ b/_docs/reference/istioctl/istioctl_replace.md
@@ -16,7 +16,7 @@ Replace existing policies and rules
Example usage:
# Create a rule using the definition in example-routing.yaml.
- $ istioctl replace -f example-routing.yaml
+ istioctl replace -f example-routing.yaml
```
diff --git a/_docs/reference/mixercli/index.md b/_docs/reference/mixercli/index.md
new file mode 100644
index 0000000000..21581aa443
--- /dev/null
+++ b/_docs/reference/mixercli/index.md
@@ -0,0 +1,9 @@
+---
+title: The Mixer CLI
+overview: Options showing how to use the Mixer's CLIs.
+order: 30
+layout: docs
+type: markdown
+---
+{% include section-index.html %}
+
diff --git a/_docs/reference/mixercli/mixc.md b/_docs/reference/mixercli/mixc.md
new file mode 100644
index 0000000000..454b6e7252
--- /dev/null
+++ b/_docs/reference/mixercli/mixc.md
@@ -0,0 +1,231 @@
+---
+title: mixc
+overview: Utility to trigger direct calls to Mixer's API
+layout: docs
+order: 1
+type: markdown
+---
+
+<a name="mixc"></a>
+## mixc
+
+Utility to trigger direct calls to Mixer's API
+
+### Synopsis
+
+
+This command lets you interact with a running instance of
+Mixer. Note that you need a pretty good understanding of Mixer's
+API in order to use this command.
+
+### Options
+
+```
+ --alsologtostderr log to standard error as well as files
+ -a, --attributes string List of name/value auto-sensed attributes specified as name1=value1,name2=value2,...
+ -b, --bool_attributes string List of name/value bool attributes specified as name1=value1,name2=value2,...
+ --bytes_attributes string List of name/value bytes attributes specified as name1=b0:b1:b3,name2=b4:b5:b6,...
+ -d, --double_attributes string List of name/value float64 attributes specified as name1=value1,name2=value2,...
+ --duration_attributes string List of name/value duration attributes specified as name1=value1,name2=value2,...
+ -i, --int64_attributes string List of name/value int64 attributes specified as name1=value1,name2=value2,...
+ --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0)
+ --log_dir string If non-empty, write log files in this directory
+ --logtostderr log to standard error instead of files
+ -m, --mixer string Address and port of a running Mixer instance (default "localhost:9091")
+ -r, --repeat int Sends the specified number of requests in quick succession (default 1)
+ --stderrthreshold severity logs at or above this threshold go to stderr (default 2)
+ -s, --string_attributes string List of name/value string attributes specified as name1=value1,name2=value2,...
+ --stringmap_attributes string List of name/value string map attributes specified as name1=k1:v1;k2:v2,name2=k3:v3...
+ -t, --timestamp_attributes string List of name/value timestamp attributes specified as name1=value1,name2=value2,...
+ --trace Whether to trace rpc executions
+ -v, --v Level log level for V logs
+ --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging
+```
+
+### See Also
+* [mixc check](#mixc_check) - Invokes Mixer's Check API to perform precondition checks.
+* [mixc quota](#mixc_quota) - Invokes Mixer's Quota API in order to perform quota management.
+* [mixc report](#mixc_report) - Invokes Mixer's Report API to generate telemetry.
+* [mixc version](#mixc_version) - Prints out build version information
+
+<a name="mixc_check"></a>
+## mixc check
+
+Invokes Mixer's Check API to perform precondition checks.
+
+### Synopsis
+
+
+The Check method is used to perform precondition checks. Mixer
+expects a set of attributes as input, which it uses, along with
+its configuration, to determine which adapters to invoke and with
+which parameters in order to perform the precondition check.
+
+```
+mixc check
+```
+
+### Options inherited from parent commands
+
+```
+ --alsologtostderr log to standard error as well as files
+ -a, --attributes string List of name/value auto-sensed attributes specified as name1=value1,name2=value2,...
+ -b, --bool_attributes string List of name/value bool attributes specified as name1=value1,name2=value2,...
+ --bytes_attributes string List of name/value bytes attributes specified as name1=b0:b1:b3,name2=b4:b5:b6,...
+ -d, --double_attributes string List of name/value float64 attributes specified as name1=value1,name2=value2,...
+ --duration_attributes string List of name/value duration attributes specified as name1=value1,name2=value2,...
+ -i, --int64_attributes string List of name/value int64 attributes specified as name1=value1,name2=value2,...
+ --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0)
+ --log_dir string If non-empty, write log files in this directory
+ --logtostderr log to standard error instead of files
+ -m, --mixer string Address and port of a running Mixer instance (default "localhost:9091")
+ -r, --repeat int Sends the specified number of requests in quick succession (default 1)
+ --stderrthreshold severity logs at or above this threshold go to stderr (default 2)
+ -s, --string_attributes string List of name/value string attributes specified as name1=value1,name2=value2,...
+ --stringmap_attributes string List of name/value string map attributes specified as name1=k1:v1;k2:v2,name2=k3:v3...
+ -t, --timestamp_attributes string List of name/value timestamp attributes specified as name1=value1,name2=value2,...
+ --trace Whether to trace rpc executions
+ -v, --v Level log level for V logs
+ --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging
+```
+
+### See Also
+* [mixc](#mixc) - Utility to trigger direct calls to Mixer's API
+
+<a name="mixc_quota"></a>
+## mixc quota
+
+Invokes Mixer's Quota API in order to perform quota management.
+
+### Synopsis
+
+
+The Quota method is used to perform quota management. Mixer
+expects a set of attributes as input, which it uses, along with
+its configuration, to determine which adapters to invoke and with
+which parameters in order to perform the quota operations.
+
+```
+mixc quota
+```
+
+### Options
+
+```
+ --amount int The amount of quota to request (default 1)
+ --bestEffort Whether to use all-or-nothing or best effort semantics
+ --name string The name of the quota to allocate
+```
+
+### Options inherited from parent commands
+
+```
+ --alsologtostderr log to standard error as well as files
+ -a, --attributes string List of name/value auto-sensed attributes specified as name1=value1,name2=value2,...
+ -b, --bool_attributes string List of name/value bool attributes specified as name1=value1,name2=value2,...
+ --bytes_attributes string List of name/value bytes attributes specified as name1=b0:b1:b3,name2=b4:b5:b6,...
+ -d, --double_attributes string List of name/value float64 attributes specified as name1=value1,name2=value2,...
+ --duration_attributes string List of name/value duration attributes specified as name1=value1,name2=value2,...
+ -i, --int64_attributes string List of name/value int64 attributes specified as name1=value1,name2=value2,...
+ --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0)
+ --log_dir string If non-empty, write log files in this directory
+ --logtostderr log to standard error instead of files
+ -m, --mixer string Address and port of a running Mixer instance (default "localhost:9091")
+ -r, --repeat int Sends the specified number of requests in quick succession (default 1)
+ --stderrthreshold severity logs at or above this threshold go to stderr (default 2)
+ -s, --string_attributes string List of name/value string attributes specified as name1=value1,name2=value2,...
+ --stringmap_attributes string List of name/value string map attributes specified as name1=k1:v1;k2:v2,name2=k3:v3...
+ -t, --timestamp_attributes string List of name/value timestamp attributes specified as name1=value1,name2=value2,...
+ --trace Whether to trace rpc executions
+ -v, --v Level log level for V logs
+ --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging
+```
+
+### See Also
+* [mixc](#mixc) - Utility to trigger direct calls to Mixer's API
+
+<a name="mixc_report"></a>
+## mixc report
+
+Invokes Mixer's Report API to generate telemetry.
+
+### Synopsis
+
+
+The Report method is used to produce telemetry. Mixer
+expects a set of attributes as input, which it uses, along with
+its configuration, to determine which adapters to invoke and with
+which parameters in order to output the telemetry.
+
+```
+mixc report
+```
+
+### Options inherited from parent commands
+
+```
+ --alsologtostderr log to standard error as well as files
+ -a, --attributes string List of name/value auto-sensed attributes specified as name1=value1,name2=value2,...
+ -b, --bool_attributes string List of name/value bool attributes specified as name1=value1,name2=value2,...
+ --bytes_attributes string List of name/value bytes attributes specified as name1=b0:b1:b3,name2=b4:b5:b6,...
+ -d, --double_attributes string List of name/value float64 attributes specified as name1=value1,name2=value2,...
+ --duration_attributes string List of name/value duration attributes specified as name1=value1,name2=value2,...
+ -i, --int64_attributes string List of name/value int64 attributes specified as name1=value1,name2=value2,...
+ --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0)
+ --log_dir string If non-empty, write log files in this directory
+ --logtostderr log to standard error instead of files
+ -m, --mixer string Address and port of a running Mixer instance (default "localhost:9091")
+ -r, --repeat int Sends the specified number of requests in quick succession (default 1)
+ --stderrthreshold severity logs at or above this threshold go to stderr (default 2)
+ -s, --string_attributes string List of name/value string attributes specified as name1=value1,name2=value2,...
+ --stringmap_attributes string List of name/value string map attributes specified as name1=k1:v1;k2:v2,name2=k3:v3...
+ -t, --timestamp_attributes string List of name/value timestamp attributes specified as name1=value1,name2=value2,...
+ --trace Whether to trace rpc executions
+ -v, --v Level log level for V logs
+ --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging
+```
+
+### See Also
+* [mixc](#mixc) - Utility to trigger direct calls to Mixer's API
+
+<a name="mixc_version"></a>
+## mixc version
+
+Prints out build version information
+
+### Synopsis
+
+
+Prints out build version information
+
+```
+mixc version
+```
+
+### Options inherited from parent commands
+
+```
+ --alsologtostderr log to standard error as well as files
+ -a, --attributes string List of name/value auto-sensed attributes specified as name1=value1,name2=value2,...
+ -b, --bool_attributes string List of name/value bool attributes specified as name1=value1,name2=value2,...
+ --bytes_attributes string List of name/value bytes attributes specified as name1=b0:b1:b3,name2=b4:b5:b6,...
+ -d, --double_attributes string List of name/value float64 attributes specified as name1=value1,name2=value2,...
+ --duration_attributes string List of name/value duration attributes specified as name1=value1,name2=value2,...
+ -i, --int64_attributes string List of name/value int64 attributes specified as name1=value1,name2=value2,...
+ --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0)
+ --log_dir string If non-empty, write log files in this directory
+ --logtostderr log to standard error instead of files
+ -m, --mixer string Address and port of a running Mixer instance (default "localhost:9091")
+ -r, --repeat int Sends the specified number of requests in quick succession (default 1)
+ --stderrthreshold severity logs at or above this threshold go to stderr (default 2)
+ -s, --string_attributes string List of name/value string attributes specified as name1=value1,name2=value2,...
+ --stringmap_attributes string List of name/value string map attributes specified as name1=k1:v1;k2:v2,name2=k3:v3...
+ -t, --timestamp_attributes string List of name/value timestamp attributes specified as name1=value1,name2=value2,...
+ --trace Whether to trace rpc executions
+ -v, --v Level log level for V logs
+ --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging
+```
+
+### See Also
+* [mixc](#mixc) - Utility to trigger direct calls to Mixer's API
+
diff --git a/_docs/reference/mixercli/mixs.md b/_docs/reference/mixercli/mixs.md
new file mode 100644
index 0000000000..cf71241dfc
--- /dev/null
+++ b/_docs/reference/mixercli/mixs.md
@@ -0,0 +1,127 @@
+---
+title: mixs
+overview: Mixer provides control plane functionality to the Istio proxy and services
+layout: docs
+order: 2
+type: markdown
+---
+
+<a name="mixs"></a>
+## mixs
+
+Mixer provides control plane functionality to the Istio proxy and services
+
+### Synopsis
+
+
+Mixer provides control plane functionality to the Istio proxy and services
+
+### See Also
+* [mixs inventory](#mixs_inventory) - Inventory of available adapters and aspects in Mixer
+* [mixs server](#mixs_server) - Starts Mixer as a server
+* [mixs version](#mixs_version) - Prints out build version information
+
+<a name="mixs_inventory_adapter"></a>
+## mixs inventory adapter
+
+List available adapter builders
+
+### Synopsis
+
+
+List available adapter builders
+
+```
+mixs inventory adapter
+```
+
+### See Also
+* [mixs inventory](#mixs_inventory) - Inventory of available adapters and aspects in Mixer
+
+<a name="mixs_inventory_aspect"></a>
+## mixs inventory aspect
+
+List available aspects
+
+### Synopsis
+
+
+List available aspects
+
+```
+mixs inventory aspect
+```
+
+### See Also
+* [mixs inventory](#mixs_inventory) - Inventory of available adapters and aspects in Mixer
+
+<a name="mixs_inventory"></a>
+## mixs inventory
+
+Inventory of available adapters and aspects in Mixer
+
+### Synopsis
+
+
+Inventory of available adapters and aspects in Mixer
+
+### See Also
+* [mixs](#mixs) - Mixer provides control plane functionality to the Istio proxy and services
+* [mixs inventory adapter](#mixs_inventory_adapter) - List available adapter builders
+* [mixs inventory aspect](#mixs_inventory_aspect) - List available aspects
+
+<a name="mixs_server"></a>
+## mixs server
+
+Starts Mixer as a server
+
+### Synopsis
+
+
+Starts Mixer as a server
+
+```
+mixs server
+```
+
+### Options
+
+```
+ --adapterWorkerPoolSize int Max # of goroutines in the adapter worker pool (default 1024)
+ --apiWorkerPoolSize int Max # of goroutines in the API worker pool (default 1024)
+ --clientCertFiles string A set of comma-separated client X509 cert files
+ --compressedPayload Whether to compress gRPC messages
+ --configAPIPort uint16 HTTP port to use for Mixer's Configuration API (default 9094)
+ --configFetchInterval uint Configuration fetch interval in seconds (default 5)
+ --configStoreURL string URL of the config store. May be fs:// for file system, or redis:// for redis url
+ --globalConfigFile string Global Config
+ --maxConcurrentStreams uint Maximum supported number of concurrent gRPC streams (default 32)
+ --maxMessageSize uint Maximum size of individual gRPC messages (default 1048576)
+ -p, --port uint16 TCP port to use for Mixer's gRPC API (default 9091)
+ --serverCertFile string The TLS cert file
+ --serverKeyFile string The TLS key file
+ --serviceConfigFile string Combined Service Config
+ --singleThreaded Whether to run Mixer in single-threaded mode (useful for debugging)
+ --trace Whether to trace rpc executions
+```
+
+### See Also
+* [mixs](#mixs) - Mixer provides control plane functionality to the Istio proxy and services
+
+<a name="mixs_version"></a>
+## mixs version
+
+Prints out build version information
+
+### Synopsis
+
+
+Prints out build version information
+
+```
+mixs version
+```
+
+### See Also
+* [mixs](#mixs) - Mixer provides control plane functionality to the Istio proxy and services
+
diff --git a/_docs/samples/bookinfo.md b/_docs/samples/bookinfo.md
index 4e48ab6c03..3334945747 100644
--- a/_docs/samples/bookinfo.md
+++ b/_docs/samples/bookinfo.md
@@ -1,7 +1,7 @@
---
title: BookInfo
overview: This sample deploys a simple application composed of four separate microservices which will be used to demonstrate various features of the Istio service mesh.
-
+
order: 10
layout: docs
@@ -10,7 +10,7 @@ type: markdown
This sample deploys a simple application composed of four separate microservices which will be used
to demonstrate various features of the Istio service mesh.
-
+
## Before you begin
Setup Istio by following the instructions in the
@@ -38,7 +38,7 @@ There are 3 versions of the reviews microservice:
The end-to-end architecture of the application is shown below.
-
+
This application is polyglot, i.e., the microservices are written in different languages.
@@ -55,27 +55,27 @@ This application is polyglot, i.e., the microservices are written in different l
```bash
kubectl apply -f <(istioctl kube-inject -f bookinfo.yaml)
```
-
+
The above command launches four microservices and creates the gateway
ingress resource as illustrated in the diagram above.
The reviews microservice has 3 versions: v1, v2, and v3.
-
+
> Note that in a realistic deployment, new versions of a microservice are deployed
over time instead of deploying all versions simultaneously.
Notice that the `istioctl kube-inject` command is used to modify the `bookinfo.yaml`
file before creating the deployments. This injects Envoy into Kubernetes resources
- as documented [here]({{site.bareurl}}/docs/reference/istioctl.html#kube-inject).
+ as documented [here](/docs/reference/istioctl/istioctl_kube-inject.html).
Consequently, all of the microservices are now packaged with an Envoy sidecar
that manages incoming and outgoing calls for the service. The updated diagram looks
like this:
- 
+ 
1. Confirm all services and pods are correctly defined and running:
```bash
- $ kubectl get services
+ kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
details 10.0.0.31 <none> 9080/TCP 6m
istio-ingress 10.0.0.122 <pending> 80:31565/TCP 8m
@@ -86,11 +86,11 @@ This application is polyglot, i.e., the microservices are written in different l
ratings 10.0.0.15 <none> 9080/TCP 6m
reviews 10.0.0.170 <none> 9080/TCP 6m
```
-
+
and
```bash
- $ kubectl get pods
+ kubectl get pods
NAME READY STATUS RESTARTS AGE
details-v1-1520924117-48z17 2/2 Running 0 6m
istio-ingress-3181829929-xrrk5 1/1 Running 0 8m
@@ -109,24 +109,50 @@ This application is polyglot, i.e., the microservices are written in different l
use the ingress' external address:
```bash
- $ kubectl get ingress -o wide
+ kubectl get ingress -o wide
NAME HOSTS ADDRESS PORTS AGE
gateway * 130.211.10.121 80 1d
- $ export GATEWAY_URL=130.211.10.121:80
+ export GATEWAY_URL=130.211.10.121:80
```
If loadbalancers are not supported, use the service NodePort instead:
```bash
- $ export GATEWAY_URL=$(kubectl get po -l istio=ingress -o jsonpath={.items[0].status.hostIP}):$(kubectl get svc istio-ingress -o jsonpath={.spec.ports[0].nodePort})
+ export GATEWAY_URL=$(kubectl get po -l istio=ingress -o jsonpath={.items[0].status.hostIP}):$(kubectl get svc istio-ingress -o jsonpath={.spec.ports[0].nodePort})
```
1. Confirm that the bookinfo application is running with the following `curl` command:
-
+
```bash
- $ curl -o /dev/null -s -w "%{http_code}\n" http://$GATEWAY_URL/productpage
+ curl -o /dev/null -s -w "%{http_code}\n" http://$GATEWAY_URL/productpage
200
```
+1. If you have installed the Istio addons, in particular the servicegraph addon, from the
+ [Installation guide](/docs/tasks/installing-istio.html), a generated servicegraph
+ of the cluster is available.
+
+ Get the external IP Address (and port) of the servicegraph service:
+ ```bash
+ $ kubectl get svc servicegraph
+ NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
+ servicegraph 10.75.240.195 104.196.248.114 8088:32556/TCP 23m
+ ```
+
+ The servicegraph service provides both a textual (JSON) representation (via `/graph`)
+ and a graphical visualization (via `/dotviz`) of the underlying servicegraph.
+
+ To view the graphical visualization, visit `http://EXTERNAL-IP:PORT/dotviz` (here:
+ http://104.196.248.114:8088/dotviz). After the single `curl` request from an earlier step,
+ the resulting image will look something like:
+
+ 
+
+ The servicegraph should show very low (or zero) QPS values, as only a single request has been sent. The
+ service uses a default time window of 5 minutes for calculating moving QPS averages. Send a consistent
+ flow of traffic through the example application and refresh the servicegraph to view updated QPS values
+ that match the generated level of traffic.
+
+
## What's next
Now that you have the bookinfo sample up and running, you can use Istio to control traffic routing,
diff --git a/_docs/samples/img/bookinfo/servicegraph.png b/_docs/samples/img/bookinfo/servicegraph.png
new file mode 100644
index 0000000000..98ef64b65a
Binary files /dev/null and b/_docs/samples/img/bookinfo/servicegraph.png differ
diff --git a/_docs/tasks/configuring-mixer.md b/_docs/tasks/configuring-mixer.md
deleted file mode 100644
index a848dc5fe7..0000000000
--- a/_docs/tasks/configuring-mixer.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: Configuring Mixer
-overview: This task shows you how to configure Mixer.
-
-order: 110
-
-layout: docs
-type: markdown
----
-
-This task shows how to do X in a Kubernetes cluster. You'll learn
-how to ...
-
-
-## Before you begin
-* Do this.
-* Do this too.
-
-## Doing ...
-
-1. Do this.
-1. Do this next. Possibly read this [related explanation](...).
-
-
-
-## Understanding ...
-
-Here's an interesting thing to know about the steps you just did.
-
-
-## What's next
-* Learn more about [this](...).
-* See this [related task](...).
-
-
-
diff --git a/_docs/tasks/egress.md b/_docs/tasks/egress.md
index 21a6206297..2dcb2e217d 100644
--- a/_docs/tasks/egress.md
+++ b/_docs/tasks/egress.md
@@ -9,26 +9,26 @@ type: markdown
---
-This task describes how to configure Istio to expose an external service to a Kubernetes cluster. You'll learn how
+This task describes how to configure Istio to expose an external service to a Kubernetes cluster. You'll learn how
to create an Egress Envoy, define an external service and make requests to the service from within the cluster.
## Before you begin
This task assumes you have deployed Istio on Kubernetes. If you have not done so, please first complete
-the [Installation Steps]({{site.bareurl}}/docs/tasks/istio-installation.html).
+the [Installation Steps](/docs/tasks/installing-istio.html).
-This task also assumes you have a publicly accessible service to call from within the cluster
-(or [httpbin.org](http://httpbin.org) can be used as an example).
+This task also assumes you have a publicly accessible service to call from within the cluster
+(or [httpbin.org](http://httpbin.org) can be used as an example).
### Setup the environment
-Create the external service definition for your external service or use one of the samples below. The `metadata.name`
-field is the url your internal apps will use when calling the external service. The `spec.externalName` should be the
-DNS name for the external service. Egress Envoy expects external services to be listening on either port `80` for
+Create the external service definition for your external service or use one of the samples below. The `metadata.name`
+field is the url your internal apps will use when calling the external service. The `spec.externalName` should be the
+DNS name for the external service. Egress Envoy expects external services to be listening on either port `80` for
HTTP or port `443` for HTTPS.
-HTTP Example:
+HTTP Example:
```yaml
apiVersion: v1
@@ -56,8 +56,8 @@ spec:
- port: 443
```
-Deploy your app(s) using the [istioctl kube-inject]({{site.bareurl}}/docs/reference/istioctl.html#kube-inject) command.
-You can use your own app, or try one of the example apps from [demos](https://github.com/istio/istio/tree/master/demos)
+Deploy your app(s) using the [istioctl kube-inject](/docs/reference/istioctl/istioctl_kube-inject.html) command.
+You can use your own app, or try one of the example apps from [demos](https://github.com/istio/istio/tree/master/demos)
directory. Each app directory contains an associated README.md providing more details.
```bash
@@ -67,11 +67,11 @@ kubectl apply -f <(istioctl kube-inject -f {resource.yaml})
### Make a request to the external service
-Make a request to the external service using the `name` from the Service spec above followed by the path to the
+Make a request to the external service using the `name` from the Service spec above followed by the path to the
desired API endpoint.
```bash
-$ kubectl exec -it {APP_POD_NAME} curl http://httpbin/headers
+kubectl exec -it {APP_POD_NAME} curl http://httpbin/headers
.. response ..
```
@@ -79,14 +79,14 @@ For external services of type HTTPS, the port must be specified in the request.
over HTTP since the Egress Envoy will initiate HTTPS with the external service:
```bash
-$ kubectl exec -it {APP_POD_NAME} curl http://securegoogle:443
+kubectl exec -it {APP_POD_NAME} curl http://securegoogle:443
.. response ..
```
## Understanding ...
-Here's an interesting thing to know about the steps you just did.
+/Here's an interesting thing to know about the steps you just did.
## What's next
-* See how to make requests to services inside a cluster by using the [Ingress Controller](/docs/tasks/ingress.html).
\ No newline at end of file
+* See how to make requests to services inside a cluster by using the [Ingress Controller](/docs/tasks/ingress.html).
diff --git a/_docs/tasks/fault-injection.md b/_docs/tasks/fault-injection.md
index 367057d8d3..be71b8836e 100644
--- a/_docs/tasks/fault-injection.md
+++ b/_docs/tasks/fault-injection.md
@@ -22,11 +22,11 @@ This task shows how to inject delays and test the resiliency of your application
commands:
```bash
- $ istioctl create -f route-rule-all-v1.yaml
- $ istioctl create -f route-rule-reviews-test-v2.yaml
+ istioctl create -f route-rule-all-v1.yaml
+ istioctl create -f route-rule-reviews-test-v2.yaml
```
-### Fault Injection
+## Fault injection
To test our bookinfo application microservices for resiliency, we will _inject a 7s delay_
between the reviews:v2 and ratings microservices. Since the _reviews:v2_ service has a
@@ -42,7 +42,7 @@ continue without any errors.
Confirm the rule is created:
```yaml
- $ istioctl get route-rule ratings-test-delay
+ istioctl get route-rule ratings-test-delay
destination: ratings.default.svc.cluster.local
httpFault:
delay:
diff --git a/_docs/tasks/ingress.md b/_docs/tasks/ingress.md
index 432f9b6247..ae62a9c8b0 100644
--- a/_docs/tasks/ingress.md
+++ b/_docs/tasks/ingress.md
@@ -17,10 +17,12 @@ In a Kubernetes environment, Istio uses [Kubernetes Ingress Resources](https://k
## Before you begin
This task assumes you have deployed Istio on Kubernetes. If you have not done so, please first complete
-the [Installation Steps]({{site.bareurl}}/docs/tasks/istio-installation.html).
+the [Installation Steps](/docs/tasks/installing-istio.html).
## Configuring Ingress
+The following sections describe how to create
+
### Setup the environment
Create an example service.
@@ -46,13 +48,26 @@ spec:
spec:
containers:
- name: app
- image: <image name>
+ image: <echo server image name>
imagePullPolicy: Always
ports:
- containerPort: 80
```
-Create an Ingress Resource. See [Kubernetes Ingress Resources](https://kubernetes.io/docs/concepts/services-networking/ingress/) for more information.
+### Generate keys
+If necessary, a private key and certificate can be created for testing using [OpenSSL](https://www.openssl.org/).
+```
+openssl req -newkey rsa:2048 -nodes -keyout cert.key -x509 -days -out='cert.crt' -subj '/C=US/ST=Seattle/O=Example/CN=secure.example.io'
+```
+
+### Create the secret
+Create the secret using `kubectl`.
+```bash
+kubectl create secret generic ingress-secret --from-file=tls.key=cert.key --from-file=tls.crt=cert.crt
+```
+
+### Create Ingress Resources
+See [Kubernetes Ingress Resources](https://kubernetes.io/docs/concepts/services-networking/ingress/) for more information.
```yaml
apiVersion: extensions/v1beta1
@@ -60,7 +75,7 @@ kind: Ingress
metadata:
name: istio-ingress
annotations:
- kubernetes.io/ingress.class: "istio"
+ kubernetes.io/ingress.class: istio
spec:
rules:
- http:
@@ -69,22 +84,41 @@ spec:
backend:
serviceName: helloworld
servicePort: 80
+---
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ name: secured-ingress
+ annotations:
+ kubernetes.io/ingress.class: istio
+spec:
+ tls:
+ - secretName: ingress-secret
+ rules:
+ - http:
+ paths:
+ - path: /hello
+ backend:
+ serviceName: helloworld
+ servicePort: 80
```
-### Make a request to the service
+### Make requests to the services
Get the Ingress controller IP.
```bash
-$ kubectl get ingress istio-ingress
+kubectl get ingress istio-ingress
NAME HOSTS ADDRESS PORTS AGE
ingress * 192.168.99.100 80 2m
```
-Make a request to the HelloWorld service using the Ingress controller IP and the path configured in the Ingress Resource.
+Make a requests to the HelloWorld service using the Ingress controller IP and the path configured in the Ingress Resources.
```bash
-$ curl http://192.168.99.100:80/hello
+curl http://192.168.99.100:80/hello
+.. response ..
+$ curl -k https://192.168.99.100:80/hello
.. response ..
```
diff --git a/_docs/tasks/installing-istio.md b/_docs/tasks/installing-istio.md
index 3a87c7fb66..be7da4ad7f 100644
--- a/_docs/tasks/installing-istio.md
+++ b/_docs/tasks/installing-istio.md
@@ -1,7 +1,7 @@
---
title: Installing Istio
overview: This task shows you how to setup the Istio service mesh.
-
+
order: 10
layout: docs
@@ -40,25 +40,41 @@ clone Istio's [GitHub](https://github.com/istio/istio) repository:
cd istio
```
-3. Install Istio's core components (Istio-Manager, Mixer, and Ingress-Controller):
+3. Install Istio's core components
+ (Istio-Manager, Mixer, Ingress-Controller, and Istio CA if auth is enabled):
+
+ **If you would like to disable Istio Auth**:
```bash
kubectl apply -f ./kubernetes/istio-15.yaml # for Kubernetes 1.5
```
-
+
or
-
+
```bash
kubectl apply -f ./kubernetes/istio-16.yaml # for Kubernetes 1.6 or later
```
+ **If you would like to enable Istio Auth** (For more information, please see
+ [Istio Auth installation guide](/docs/tasks/istio-auth.html)):
+
+ ```bash
+ kubectl apply -f ./kubernetes/istio-auth-15.yaml # for Kubernetes 1.5
+ ```
+
+ or
+
+ ```bash
+ kubectl apply -f ./kubernetes/istio-auth-16.yaml # for Kubernetes 1.6 or later
+ ```
+
4. Source the Istio configuration file:
```bash
source istio.VERSION
```
-5. Download one of the [`istioctl`](/docs/reference/istioctl.html) client binaries corresponding to your OS: `istioctl-osx`, `istioctl-win.exe`,
+5. Download one of the [`istioctl`](/docs/reference/istioctl/istioctl.html) client binaries corresponding to your OS: `istioctl-osx`, `istioctl-win.exe`,
`istioctl-linux`, targeted at Mac, Windows or Linux users respectively. For example, run the following commands on a Mac system:
```bash
@@ -110,7 +126,8 @@ ServiceGraph addons:
(e.g., minikube), the `EXTERNAL-IP` will say `<pending>` and you will need to access the
application using the service NodePort instead.
-2. Check the corresponding Kubernetes pods were deployed: "istio-manager-\*", "istio-mixer-\*", "istio-ingress-\*".
+2. Check the corresponding Kubernetes pods were deployed: "istio-manager-\*", "istio-mixer-\*", "istio-ingress-\*" and
+ "istio-ca-\*" (if Istio Auth is enabled).
```bash
kubectl get pods
@@ -118,15 +135,17 @@ ServiceGraph addons:
istio-ingress-594763772-j7jbz 1/1 Running 0 49m
istio-manager-373576132-p2t9k 1/1 Running 0 49m
istio-mixer-1154414227-56q3z 1/1 Running 0 49m
+ istio-ca-1726969296-9srv2 1/1 Running 0 49m
```
## Deploy your application
You can now deploy your own application or one of the Istio sample applications,
-for example [bookinfo](/docs/samples/bookinfo.html).
+for example [bookinfo](/docs/samples/bookinfo.html). Note that the application should use HTTP/1.1
+or HTTP/2.0 protocol for all its HTTP traffic.
When deploying the application,
-use [kube-inject](/docs/reference/istioctl.html##kube-inject) to automatically inject
+use [kube-inject](/docs/reference/istioctl/istioctl_kube-inject.html) to automatically inject
Envoy containers in the pods running the services:
```bash
kubectl create -f <(istioctl kube-inject -f <your-app-spec>.yaml)
@@ -136,10 +155,18 @@ kubectl create -f <(istioctl kube-inject -f <your-app-spec>.yaml)
1. Uninstall Istio:
+ **If Istio has auth disabled:**
+
```bash
kubectl delete -f ./kubernetes/istio-16.yaml
```
+ **If Istio has auth enabled:**
+
+ ```bash
+ kubectl delete -f ./kubernetes/istio-auth-16.yaml
+ ```
+
2. Delete the istioctl client:
```bash
@@ -149,4 +176,5 @@ kubectl create -f <(istioctl kube-inject -f <your-app-spec>.yaml)
## What's next
* Learn more about how to enable [authentication](/docs/tasks/istio-auth.html).
+
* See the sample [bookinfo](/docs/samples/bookinfo.html) application.
diff --git a/_docs/tasks/integrating-services-into-istio.md b/_docs/tasks/integrating-services-into-istio.md
index 5e5f9babb7..dc74f83967 100644
--- a/_docs/tasks/integrating-services-into-istio.md
+++ b/_docs/tasks/integrating-services-into-istio.md
@@ -1,36 +1,207 @@
---
title: Integrating Services into the Mesh
overview: This task shows you how to integrate your applications with the Istio service mesh.
-
+
order: 20
layout: docs
type: markdown
---
-This task shows how to do X in a Kubernetes cluster. You'll learn
-how to ...
-
+This task shows how to integrate applications on Kubernetes with
+Istio. You'll learn how to inject the Envoy sidecar into deployments
+using [istioctl kube-inject](/docs/reference/istioctl/istioctl_kube-inject.html)
## Before you begin
-* Do this.
-* Do this too.
-## Doing ...
+This task assumes you have deployed Istio on Kubernetes.
+If you have not done so, please first complete the
+[Installation Steps](/docs/tasks/installing-istio.html).
-1. Do this.
-1. Do this next. Possibly read this [related explanation](...).
+## Injecting Envoy sidecar into a deployment
+
+Example deployment and service to demonstrate this task. Save this as
+echo.yaml.
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+ name: echo
+ labels:
+ app: echo
+spec:
+ ports:
+ - port: 80
+ targetPort: 8080
+ name: http
+ selector:
+ app: echo
+---
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+ name: echo
+spec:
+ replicas: 1
+ template:
+ metadata:
+ labels:
+ app: echo
+ spec:
+ containers:
+ - name: echo
+ image: gcr.io/google_containers/echoserver:1.4
+ ports:
+ - containerPort: 8080
+---
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+ name: busybox
+spec:
+ replicas: 1
+ template:
+ metadata:
+ labels:
+ app: busybox
+ spec:
+ containers:
+ - name: busybox
+ image: radial/busyboxplus:curl
+```
+
+[Kubernetes Services](https://kubernetes.io/docs/concepts/services-networking/service/)
+are required for properly functioning Istio service. Service ports
+must be named and these names must begin with _http_ or _grpc_ prefix
+to take advantage of Istio's L7 routing features, e.g. `name: httpFoo`
+is good. Services with non-named ports or with ports that do not have
+a _http_ or _grpc_ prefix will be routed as L4 traffic.
+
+Submit a YAML resource to API server with injected Envoy sidecar. Any
+one of the following methods will work.
+
+```bash
+kubectl apply -f <(istioctl kube-inject -f echo.yaml)
+```
+
+Make a request from the client (busybox) to the server (echo).
+
+```bash
+CLIENT=$(kubectl get pod -l app=busybox -o jsonpath='{.items[0].metadata.name}')
+SERVER=$(kubectl get pod -l app=echo -o jsonpath='{.items[0].metadata.name}')
+
+kubectl exec -it ${CLIENT} -c echo -- curl echo:80 | grep x-request-id
+x-request-id=a641eff7-eb82-4a4f-b67b-53cd3a03c399
+```
+
+Verify traffic is intercepted by the Envoy sidecar. Compare
+`x-request-id` in the HTTP response with the sidecar's access
+logs. `x-request-id` is random. The IP in the inbound request logs is
+the echo pod's IP.
+
+Outbound request on client pod's proxy.
+
+```
+kubectl logs ${CLIENT} proxy | grep a641eff7-eb82-4a4f-b67b-53cd3a03c399
+[2017-05-01T22:08:39.310Z] "GET / HTTP/1.1" 200 - 0 398 2 0 "-" "curl/7.47.0" "a641eff7-eb82-4a4f-b67b-53cd3a03c399" "echo" "127.0.0.1:8080"
+```
+
+Inbound request on server pod's proxy.
+
+```
+kubectl logs ${SERVER} proxy | grep a641eff7-eb82-4a4f-b67b-53cd3a03c399
+[2017-05-01T22:08:39.310Z] "GET / HTTP/1.1" 200 - 0 398 3 3 "-" "curl/7.47.0" "a641eff7-eb82-4a4f-b67b-53cd3a03c399" "echo" "10.4.180.7:8080"
+```
+The Envoy sidecar does _not_ intercept container-to-container traffic
+within the same pod when traffic is routed via localhost. This is by
+design.
-## Understanding ...
+```bash
+kubectl exec -it ${SERVER} -c echo -- curl localhost:8080 | grep x-request-id
+```
-Here's an interesting thing to know about the steps you just did.
+## Understanding what happened
+`istioctl kube-inject` injects additional containers into YAML
+resource on the client _before_ submitting to the Kubernetes API
+server. This will eventually be replaced by server-side injection via
+admission controller. Use `kubectl get deployment echo -o yaml` to
+inspect the modified deployment and look for the following:
+
+* A proxy container which includes the Envoy proxy and agent to manage
+ local proxy configuration.
+
+* An [init-container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/)
+ to program [iptables](https://en.wikipedia.org/wiki/Iptables).
+
+The proxy container runs with a specific UID so that the iptables can
+differentiate outbound traffic from the proxy itself from the
+applications which are redirected to proxy.
+
+```yaml
+- args:
+ - proxy
+ - sidecar
+ - "-v"
+ - "2"
+ env:
+ -
+ name: POD_NAME
+ valueFrom:
+ fieldRef:
+ apiVersion: v1
+ fieldPath: metadata.name
+ -
+ name: POD_NAMESPACE
+ valueFrom:
+ fieldRef:
+ apiVersion: v1
+ fieldPath: metadata.namespace
+ -
+ name: POD_IP
+ valueFrom:
+ fieldRef:
+ apiVersion: v1
+ fieldPath: status.podIP
+ image: "docker.io/istio/proxy:<...tag... >"
+ imagePullPolicy: Always
+ name: proxy
+ securityContext:
+ runAsUser: 1337
+
+```
+
+iptables is used to transparently redirect all inbound and outbound
+traffic to the proxy. An init-container is used for two reasons:
+
+1. iptables requires
+[NET_CAP_ADMIN](http://man7.org/linux/man-pages/man7/capabilities.7.html).
+
+2. The sidecar iptable rules are fixed and don't need to be updated
+after pod creation. The proxy container is responsible for dynamically
+routing traffic.
+
+```json
+{
+ "name":"init",
+ "image":"docker.io/istio/init:<..tag...>",
+ "args":[ "-p", "15001", "-u", "1337" ],
+ "imagePullPolicy":"Always",
+ "securityContext":{
+ "capabilities":{
+ "add":[
+ "NET_ADMIN"
+ ]
+ }
+ }
+},
+```
## What's next
-* Learn more about [this](...).
-* See this [related task](...).
-
+* Review full documentation for [istioctl kube-inject](/docs/reference/istioctl/istioctl_kube-inject.html)
+* See the [bookinfo sample](/docs/samples/bookinfo.html) for a more complete example of applications integrated on Kubernetes with Istio.
diff --git a/_docs/tasks/istio-auth.md b/_docs/tasks/istio-auth.md
index b4e448fbe1..319cecf334 100644
--- a/_docs/tasks/istio-auth.md
+++ b/_docs/tasks/istio-auth.md
@@ -1,36 +1,162 @@
---
title: Enabling Istio Auth
overview: This task shows you how to setup Istio-Auth to provide mutual TLS authentication between services.
-
+
order: 70
layout: docs
type: markdown
---
-This task shows how to do X in a Kubernetes cluster. You'll learn
-how to ...
+This task shows how to set up Istio Auth in a Kubernetes cluster. You'll learn
+how to:
+
+* Enable Istio Auth
+
+* Disable Istio Auth
+
+* Verify Istio Auth setup
## Before you begin
-* Do this.
-* Do this too.
+This task assumes you have:
-## Doing ...
+* Read the [Istio Auth concepts](/docs/concepts/network-and-auth/index.html).
-1. Do this.
-1. Do this next. Possibly read this [related explanation](...).
+* Cloned https://github.com/istio/istio to your local machine
+ (Step 1 in [the Istio installation guide](/docs/tasks/installing-istio.html#installing-on-an-existing-cluster)).
+In real world systems, only a single Istio CA should be present in a Kubernetes cluster,
+which is always deployed in a dedicated namespace. The Istio CA issues certificates/keys to
+all pods in the Kubernetes cluster. This offers strong security and automatic trust between namespaces in the same cluster.
+However, this task also instructs how to deploy a namespace-scoped Istio CA,
+for easy setup and clean up during the experiments.
+## Enabling Istio Auth
-## Understanding ...
+### Option 1: using per-namespace CA
-Here's an interesting thing to know about the steps you just did.
+Per namespace CA is convenient for doing experiments.
+Because each Istio CA is scoped within a namespace, Istio CAs in different namespaces will not interfere with each other
+and they are easy to clean up through a single command.
+We have the YAML files *istio-auth-X.yaml* for deploying all Istio components including Istio CA into the namespace.
+Follow [the Istio installation guide](/docs/tasks/installing-istio.html),
+and **choose "If you would like to enable Istio Auth" in step 3**.
-## What's next
-* Learn more about [this](...).
-* See this [related task](...).
+### Option 2: (recommended) using per-cluster CA
+Only a single Istio CA is deployed for the Kubernetes cluster, in a dedicated namespace.
+Doing this offers the following benefits:
+* In the near future, the dedicated namespace will use
+[Kubernetes RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) (beta in Kubernetes V1.6) to provide security
+boundary. This will offer strong security for Istio CA.
+
+* Services in the same Kubernetes cluster but different namespaces are able to talk to each other through Istio Auth
+without extra trust setup.
+
+#### Deplying CA
+
+The following command creates namespace *istio-system* and deploys CA into the namespace:
+
+```bash
+kubectl apply -f ./kubernetes/istio-auth/istio-cluster-ca.yaml
+```
+
+#### <a name="istioconfig"></a>Enabling Istio Auth in Istio config
+
+The following command uncomments the line *authPolicy: MUTUAL_TLS* in the file *kubernetes/istio-X.yaml*,
+and backs up the original file as *istio-X.yaml.bak*
+(*X* corresponds to the Kubernetes server version, choose "15" or "16").
+
+```bash
+sed "s/# authPolicy: MUTUAL_TLS/authPolicy: MUTUAL_TLS/" ./kubernetes/istio-X.yaml > ./kubernetes/istio-auth-X.yaml
+```
+
+#### Deploying other services
+
+Follow [the general Istio installation guide](/docs/tasks/installing-istio.html),
+and **choose "If you would like to enable Istio Auth" in step 3**.
+
+## Disabling Istio Auth
+
+Disabling Istio Auth requires all Istio services and applications to be reconfigured and restarted without auth config.
+
+### For per-namespace CA Istio Auth
+
+Run the following command to uninstall Istio, and redeploy Istio without auth:
+
+```bash
+kubectl delete -f ./kubernetes/istio-auth-X.yaml
+kubectl apply -f ./kubernetes/istio-X.yaml
+```
+
+Also, redeploy your application by running:
+
+```bash
+kubectl replace -f <(istioctl kube-inject -f <your-app-spec>.yaml)
+```
+
+### For per-cluster CA Istio Auth
+
+#### Removing per-cluster Istio CA
+
+The following command removes Istio CA and its namespace *istio-system*.
+
+```bash
+kubectl delete -f ./kubernetes/istio-auth/istio-cluster-ca.yaml
+```
+
+#### Redeploying Istio and applications
+
+Run the following command to uninstall Istio, and redeploy Istio without auth:
+
+```bash
+kubectl delete -f ./kubernetes/istio-auth-X.yaml
+kubectl apply -f ./kubernetes/istio-X.yaml
+```
+
+Also, redeploy your application by running:
+
+```bash
+kubectl replace -f <(istioctl kube-inject -f <your-app-spec>.yaml)
+```
+
+#### Recovering the original config files
+
+The following command will recover the original *istio-auth-X.yaml* file.
+
+```bash
+git checkout ./kubernetes/istio-auth-X.yaml
+```
+
+## Verifying Istio Auth setup
+
+The following instructions assume the applications are deployed in the "default" namespace.
+They can be modified for deployments in a separate namespace.
+
+Verify AuthPolicy setting in ConfigMap:
+
+```bash
+kubectl get configmap istio -o yaml | grep authPolicy
+# Istio Auth is enabled if the line "authPolicy: MUTUAL_TLS" is uncommented.
+```
+
+Check the certificate and key files are mounted onto the application pod *app-pod*:
+
+```bash
+kubectl exec <app-pod> -c proxy -- ls /etc/certs
+# Expected files: cert-chain.pem, key.pem and root-cert.pem.
+```
+
+When Istio Auth is enabled for a pod, *ssl_context* stanzas should be in the pod's proxy config.
+The following commands verifies the proxy config on *app-pod* has *ssl_context* configured:
+
+```bash
+kubectl exec <app-pod> -c proxy -- ls /etc/envoy
+# Get the config file named "envoy-revX.json".
+kubectl exec <app-pod> -c proxy -- cat /etc/envoy/envoy-revX.json | grep ssl_context
+# Expect ssl_context in the output.
+```
diff --git a/_docs/tasks/metrics-logs.md b/_docs/tasks/metrics-logs.md
index 7dacb5a430..8eba941d81 100644
--- a/_docs/tasks/metrics-logs.md
+++ b/_docs/tasks/metrics-logs.md
@@ -29,7 +29,7 @@ as the example application throughout this task.
subject. These rules apply to all requests within the Istio cluster.
```bash
- $ istioctl mixer rule get global global
+ istioctl mixer rule get global global
revision: "2022"
rules:
- aspects:
@@ -110,15 +110,15 @@ as the example application throughout this task.
setting up port-forwarding to the Mixer Config API port (typically, 9094).
```bash
- $ kubectl port-forward $(kubectl get pod -l istio=mixer -o jsonpath='{.items[0].metadata.name}') 9094:9094 &
- $ export ISTIO_MIXER_API_SERVER=localhost:9094
+ kubectl port-forward $(kubectl get pod -l istio=mixer -o jsonpath='{.items[0].metadata.name}') 9094:9094 &
+ export ISTIO_MIXER_API_SERVER=localhost:9094
```
1. Create a new YAML file (`new_rule.yml`) to hold configuration for
the new metrics that Istio will collect automatically.
```bash
- $ cat <<EOF >new_rule.yml
+ cat <<EOF >new_rule.yml
revision: "1"
rules:
- aspects:
@@ -182,7 +182,7 @@ as the example application throughout this task.
already applied with `istioctl`.
```bash
- $ istioctl mixer rule get global reviews.default.svc.cluster.local
+ istioctl mixer rule get global reviews.default.svc.cluster.local
Error: Not Found
```
@@ -195,7 +195,7 @@ as the example application throughout this task.
`istioctl`.
```bash
- $ istioctl mixer rule create global reviews.default.svc.cluster.local -f new_rule.yml
+ istioctl mixer rule create global reviews.default.svc.cluster.local -f new_rule.yml
```
1. Send traffic to that service.
@@ -209,7 +209,7 @@ as the example application throughout this task.
The simplest way to do that is to port-forward and visit via `localhost`.
```bash
- $ kubectl port-forward $(kubectl get pod -l istio=mixer -o jsonpath='{.items[0].metadata.name}') 42422:42422 &
+ kubectl port-forward $(kubectl get pod -l istio=mixer -o jsonpath='{.items[0].metadata.name}') 42422:42422 &
```
Browse to `localhost:42422/metrics`. Search for `request_size`. You
@@ -253,7 +253,7 @@ as the example application throughout this task.
Find the pod for Mixer as follows:
```bash
- $ kubectl get pods
+ kubectl get pods
NAME READY STATUS RESTARTS AGE
...
istio-mixer-88439463-xnllx 1/1 Running 0 14m
@@ -263,7 +263,7 @@ as the example application throughout this task.
Then, look through the logs for the pod as follows:
```bash
- $ kubectl logs istio-mixer-88439463-xnllx | grep \"combined_log\"
+ kubectl logs istio-mixer-88439463-xnllx | grep \"combined_log\"
{"logName":"combined_log","labels":{"referer":"","responseSize":871,"timestamp":"2017-04-29T02:11:54.989466058Z","url":"/reviews","userAgent":"python-requests/2.11.1"},"textPayload":"- - - [29/Apr/2017:02:11:54 +0000] \"- /reviews -\" - 871 - python-requests/2.11.1"}
```
@@ -367,4 +367,3 @@ Config API to add support for creating new descriptors.
* Learn more about [Mixer](/docs/concepts/policy-and-control/mixer.html) and [Mixer Config](/docs/concepts/policy-and-control/mixer-config.html).
* Discover the full [Attribute Vocabulary](/docs/reference/attribute-vocabulary.html).
* Read the reference guide to [Writing Config](/docs/reference/writing-config.html).
-* See the [Configuring Mixer](/docs/tasks/configuring-mixer.html) task.
diff --git a/_docs/tasks/rate-limiting.md b/_docs/tasks/rate-limiting.md
index 22005bd38c..e664f5d8e7 100644
--- a/_docs/tasks/rate-limiting.md
+++ b/_docs/tasks/rate-limiting.md
@@ -1,5 +1,5 @@
---
-title: Rate Limiting
+title: Enabling Rate Limits
overview: This task shows you how to use Istio to dynamically limit the traffic to a service.
order: 40
@@ -22,22 +22,35 @@ This task shows you how to use Istio to dynamically limit the traffic to a servi
commands:
```bash
- $ istioctl create -f route-rule-all-v1.yaml
- $ istioctl replace -f route-rule-reviews-v3.yaml
+ istioctl create -f route-rule-all-v1.yaml
+ istioctl replace -f route-rule-reviews-v2-v3.yaml
```
+* Ensure that you can use [istioctl mixer](/docs/reference/istioctl/istioctl_mixer.html#synopsis) by setting up port forwading if needed.
-### Rate Limiting [WIP]
+## Rate limits
-We will pretend that `ratings` is an external service for which we are paying
-(like going to rotten tomatoes), so we will set a rate limit on the service
-such that the load remains under the Free quota (5q/s).
+Istio enables users to rate limit traffic to a service.
+
+Consider `ratings` as an external paid service like Rotten Tomatoes® with `5qps` free quota.
+Using Istio we can ensure that `5qps` is not breached.
1. Configure mixer with the rate limit:
```bash
- # (TODO) istioctl create -f mixer-rule-ratings-ratelimit.yaml
- kubectl apply -f ../../mixer-config-quota-bookinfo.yaml
+ istioctl mixer rule create global ratings.default.svc.cluster.local -f ratelimit.yml
```
+ where ratelimit.yml is
+ ```yaml
+ rules:
+ - aspects:
+ - kind: quotas
+ params:
+ quotas:
+ - descriptorName: RequestCount
+ maxAmount: 5
+ expiration: 1s
+ ```
+ `istioctl` sets configuration for `subject=ratings.default.svc.cluster.local`
2. Generate load on the `productpage` with the following command:
@@ -45,17 +58,53 @@ such that the load remains under the Free quota (5q/s).
while true; do curl -s -o /dev/null http://$GATEWAY_URL/productpage; done
```
- If you now refresh the `productpage` (http://$GATEWAY_URL/productpage)
- you'll see that while the load generator is running
- (i.e., generating more than 5 req/s), we stop seeing stars.
+ If you refresh the `productpage` (http://$GATEWAY_URL/productpage) while the load
+ generator is running (i.e., generating more than 5 req/s), the traffic generated by
+ your browser will be rate limited. When `reviews` service is unable to access `ratings`
+ service you stop seeing stars on the UI.
-## Understanding ...
+## Conditional rate limits
-Here's an interesting thing to know about the steps you just did.
+In the previous example we applied a rate limit to the `ratings` service without regard
+to any other attributes. It is possible to conditionally apply rate limits based on
+attributes like the source of the traffic.
+
+The following configuration applies a `5qps` rate limit only to version `v3` of `reviews`.
+
+1. Configure mixer with the conditional rate limit:
+
+ ```bash
+ istioctl mixer rule create global ratings.default.svc.cluster.local -f ratelimit-conditional.yml
+ ```
+ where ratelimit-conditional.yml is
+ ```yaml
+ rules:
+ - selector: source.labels["app"]=="reviews" && source.labels["version"] == "v3"
+ aspects:
+ - kind: quotas
+ params:
+ quotas:
+ - descriptorName: RequestCount
+ maxAmount: 5
+ expiration: 1s
+ ```
+2. Generate load on the `productpage` with the following command:
+
+ ```bash
+ while true; do curl -s -o /dev/null http://$GATEWAY_URL/productpage; done
+ ```
+
+ If you refresh the `productpage` (http://$GATEWAY_URL/productpage) while the load
+ generator is running (i.e., generating more than 5 req/s), the traffic generated by
+ your browser will be rate limited.
+
+ Since the `reviews-v3` service is unable to access `ratings` we stop seeing `red` stars on the UI.
+
+
+## Dimensioned rate limits [WIP]
## What's next
-* Learn more about [this](...).
-* See this [related task](...).
-
-
+* Learn more about [Mixer](/docs/concepts/policy-and-control/mixer.html) and [Mixer Config](/docs/concepts/policy-and-control/mixer-config.html).
+* Discover the full [Attribute Vocabulary](/docs/reference/attribute-vocabulary.html).
+* Read the reference guide to [Writing Config](/docs/reference/writing-config.html).
diff --git a/_docs/tasks/request-routing.md b/_docs/tasks/request-routing.md
index 8eb43c64d3..e6f3a3c00c 100644
--- a/_docs/tasks/request-routing.md
+++ b/_docs/tasks/request-routing.md
@@ -17,7 +17,7 @@ This task shows you how to configure dynamic request routing based on weights an
* Deploy the [bookinfo](/docs/samples/bookinfo.html) sample application.
-## Content Based Routing
+## Content-based routing
Because the bookinfo sample deploys 3 versions of the reviews microservice,
we need to set a default route.
@@ -35,7 +35,7 @@ route requests to all available versions of a service in a random fashion.
You can display the routes that are defined with the following command:
```yaml
- $ istioctl get route-rules -o yaml
+ istioctl get route-rules -o yaml
kind: route-rule
name: ratings-default
namespace: default
@@ -102,7 +102,7 @@ route requests to all available versions of a service in a random fashion.
Confirm the rule is created:
```yaml
- $ istioctl get route-rule reviews-test-v2
+ istioctl get route-rule reviews-test-v2
destination: reviews.default.svc.cluster.local
match:
httpHeaders:
diff --git a/_docs/tasks/request-timeouts.md b/_docs/tasks/request-timeouts.md
index ae6bd39b11..79849b466c 100644
--- a/_docs/tasks/request-timeouts.md
+++ b/_docs/tasks/request-timeouts.md
@@ -21,7 +21,7 @@ This task shows you how to setup request timeouts in Envoy using Istio.
* Initialize the application version routing by running the following command:
```bash
- $ istioctl create -f route-rule-all-v1.yaml
+ istioctl create -f route-rule-all-v1.yaml
```
## Request timeouts
@@ -35,7 +35,7 @@ to the `ratings` service.
1. Route requests to v2 of the `reviews` service, i.e., a version that calls the `ratings` service
```bash
- $ cat <<EOF | istioctl replace
+ cat <<EOF | istioctl replace
type: route-rule
name: reviews-default
spec:
@@ -49,7 +49,7 @@ to the `ratings` service.
1. Add a 2 second delay to calls to the `ratings` service:
```bash
- $ cat <<EOF | istioctl replace
+ cat <<EOF | istioctl replace
type: route-rule
name: ratings-default
spec:
@@ -72,7 +72,7 @@ to the `ratings` service.
1. Now add a 1 second request timeout for calls to the `reviews` service
```bash
- $ cat <<EOF | istioctl replace
+ cat <<EOF | istioctl replace
type: route-rule
name: reviews-default
spec:
diff --git a/_includes/doc-side-nav.html b/_includes/doc-side-nav.html
index 12c5833f7e..4fa8a2b1fe 100644
--- a/_includes/doc-side-nav.html
+++ b/_includes/doc-side-nav.html
@@ -29,7 +29,11 @@
"{{ comp }}",
{% endif %}
{% endfor %}
- ], url: "{{d.url}}", title: "{{d.title}}", order: {{d.order}}, overview: "{{d.overview}}"});
+ {% assign order = d.order %}
+ {% if d.order == nil %}
+ {% assign order = 9999 %}
+ {% endif %}
+ ], url: "{{d.url}}", title: "{{d.title}}", order: {{order}}, overview: "{{d.overview}}"});
{% endif %}
{% endfor %}
diff --git a/_includes/doc-top-nav.html b/_includes/doc-top-nav.html
index b3b66fd2f6..9d3f04d937 100644
--- a/_includes/doc-top-nav.html
+++ b/_includes/doc-top-nav.html
@@ -4,10 +4,11 @@
<ul class="col-sm-10 nav nav-tabs">
{% assign cats = site.docs | where:"index","true" | sort:"order" %}
{% for cat in cats %}
- {% assign active = cat.url | downcase | split: '/' %}
+ {% assign cat_path = cat.url | downcase | split: '/' %}
+ {% assign page_path = page.url | downcase | split: '/' %}
{% assign cat_name = cat.title | default: "EMPTY" %}
- {% if cat.url contains "index" and cat_name != "EMPTY" %}
- <li role="presentation" {% if page.url == cat.url %}class='active'{% endif %}><a href="{{home}}{{ cat.url }}">{{ cat_name }}</a></li>
+ {% if cat_name != "EMPTY" %}
+ <li role="presentation" {% if cat_path[2] == page_path[2] %}class='active'{% endif %}><a href="{{home}}{{ cat.url }}">{{ cat_name }}</a></li>
{% endif %}
{% endfor %}
</ul>
diff --git a/_includes/search-box.html b/_includes/search-box.html
index 152f33431e..a16d98ee6f 100644
--- a/_includes/search-box.html
+++ b/_includes/search-box.html
@@ -4,7 +4,7 @@
<input type="hidden" name="ie" value="utf-8" />
<input type="hidden" name="hl" value="en" />
<input name="q" type="text" size="30" />
- <input class="formbutton" value="Search" type="submit" name="sa" />
+ <span class="btn-search lead glyphicon glyphicon-search" style="color: #aaa; cursor:pointer"></span>
</form>
- <script type="text/javascript" src="http://www.google.com/cse/brand?form=searchbox_demo"></script>
+ <script type="text/javascript" src="https://www.google.com/cse/brand?form=searchbox_demo"></script>
</div>
diff --git a/_layouts/about.html b/_layouts/about.html
index f0ecfaf06e..89ab3708bc 100644
--- a/_layouts/about.html
+++ b/_layouts/about.html
@@ -1,6 +1,11 @@
---
layout: default
---
+{% assign home = "" %}
+{% if site.github.environment == "dotcom" %}
+{% assign home = site.baseurl %}
+{% endif %}
+
<div class="container">
<div class="row">
<div class="col-md-11 nofloat center-block ">
diff --git a/_layouts/base.html b/_layouts/base.html
index 47516abd54..12ecac71e9 100644
--- a/_layouts/base.html
+++ b/_layouts/base.html
@@ -28,11 +28,11 @@ layout: compress
<!-- Webfont -->
<link href='https://fonts.googleapis.com/css?family=Roboto:400,100,100italic,300,300italic,400italic,500,500italic,700,700italic,900,900italic' rel='stylesheet' type='text/css'>
- <link rel="alternate" type="application/rss+xml" title="Istio Blog RSS" href="/feed.xml">
+ <link rel="alternate" type="application/rss+xml" title="Istio Blog RSS" href="{{home}}/feed.xml">
<!-- Favicons -->
<link rel="apple-touch-icon" href="{{home}}/favicons/apple-touch-icon.png" sizes="180x180">
- <link rel="icon" type="image/png" href={{home}}/favicons/android-chrome-96x96.png" sizes="96x96" >
+ <link rel="icon" type="image/png" href="{{home}}/favicons/android-chrome-96x96.png" sizes="96x96" >
<link rel="icon" type="image/png" href="{{home}}/favicons/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="{{home}}/favicons/favicon-16x16.png" sizes="16x16">
<link rel="manifest" href="{{home}}/favicons/manifest.json"">
diff --git a/_layouts/community.html b/_layouts/community.html
index 171846fc0b..e8a9261d95 100644
--- a/_layouts/community.html
+++ b/_layouts/community.html
@@ -1,6 +1,11 @@
---
layout: default
---
+{% assign home = "" %}
+{% if site.github.environment == "dotcom" %}
+{% assign home = site.baseurl %}
+{% endif %}
+
<div class="container">
<div class="row">
<div class="col-md-11 nofloat center-block">
diff --git a/_layouts/docs.html b/_layouts/docs.html
index 89a3e2b911..b021ace392 100644
--- a/_layouts/docs.html
+++ b/_layouts/docs.html
@@ -8,18 +8,18 @@ layout: default
{% endif %}
{% include doc-top-nav.html %}
-
<div class="container">
<div class="row">
<div class="col-md-11 nofloat center-block ">
- <div class="col-sm-3">
- {% include doc-side-nav.html %}
+ <div class="row">
+ <div class="col-sm-3">
+ {% include doc-side-nav.html %}
+ </div>
+ <div class="col-sm-9 {{ page.type }}">
+ <div id="toc" class=""></div>
+ {{ content }}
+ </div>
</div>
- <div class="col-sm-7 {{ page.type }}">
- {{ content }}
- </div>
-
- <div id="toc" class="toc"></div>
</div>
</div>
</div>
diff --git a/_sass/base/_common.scss b/_sass/base/_common.scss
index db9d3015aa..19fee79d33 100644
--- a/_sass/base/_common.scss
+++ b/_sass/base/_common.scss
@@ -30,12 +30,15 @@
}
.toc {
- border-left: 2px solid $light-gray;
+ background-color: $light-gray;
+ border: 1px solid $gray;
+ border-radius: 6px;
display: none !important;
- padding: 0;
- position: absolute;
+ padding: 15px;
+ float: right;
+ //position: absolute;
right: 45px;
- margin-top: 10px;
+ margin-top: 15px;
@media (min-width: 768px) {
display: block !important;
@@ -44,11 +47,12 @@
ul {
list-style-type: none !important;
- padding-left: 10px;
+ //padding-left: 10px;
font-size: 90%;
ul {
font-size: 90%;
+ padding-left: 10px;
}
a {
diff --git a/_sass/modules/_buttons.scss b/_sass/modules/_buttons.scss
index a5302574e3..a65f5b1bb4 100644
--- a/_sass/modules/_buttons.scss
+++ b/_sass/modules/_buttons.scss
@@ -10,6 +10,7 @@
color: $white;
font-weight: 300;
letter-spacing: 1px;
+ border-radius: 4px;
a {
color: $white;
diff --git a/_sass/modules/_contribute-links.scss b/_sass/modules/_contribute-links.scss
index 298cacd3e7..9a34d42e1e 100644
--- a/_sass/modules/_contribute-links.scss
+++ b/_sass/modules/_contribute-links.scss
@@ -28,8 +28,14 @@
&:hover {
&:before {
- background-color: $thirdBrandColor;
+ background-color: $popBrandColor;
}
}
+
+ &.inverse {
+ background-color: transparent;
+ border: 2px solid $mainBrandColor;
+ color: $mainBrandColor;
+ }
}
}
diff --git a/_sass/modules/_doc-nav.scss b/_sass/modules/_doc-nav.scss
index abdce69a51..6edbfcb4a8 100644
--- a/_sass/modules/_doc-nav.scss
+++ b/_sass/modules/_doc-nav.scss
@@ -87,37 +87,5 @@
display: inline-block;
padding: 2px $spacing--s;
width: 100%;
-
- a {
- font-weight: 400;
- }
}
-
- h6 {
- color: $mainBrandColor;
- font-size: 100%;
- font-weight: 400;
- line-height: 22px;
- }
-
- .submenu {
- padding: 2px 15px;
- }
-
- .submenu-link {
- display: block;
- font-size: 100%;
- font-weight: 400;
- line-height: 22px;
- color: $mainBrandColor;
-
- &.active:before {
- margin-left: -0.80em;
- content: '> ';
- }
-
- &.active {
- line-height: 30px;
- }
- }
}
diff --git a/_sass/modules/_nav.scss b/_sass/modules/_nav.scss
index 7d76f22ebc..db5dcea9c7 100644
--- a/_sass/modules/_nav.scss
+++ b/_sass/modules/_nav.scss
@@ -109,7 +109,7 @@
right: 0;
top: 0;
transition: $transition--secondary;
- width: 300px;
+ width: 220px;
z-index: $z-above-top;
@media (min-width: $tablet) {
diff --git a/_sass/modules/_search-box.scss b/_sass/modules/_search-box.scss
index 9b8bd4e3d4..79cee8e680 100644
--- a/_sass/modules/_search-box.scss
+++ b/_sass/modules/_search-box.scss
@@ -12,16 +12,10 @@
font-size: 16px;
vertical-align: top;
background: #fff;
- text-indent: 18px;
border-color: $mainBrandColor;
border-radius: 4px;
border-width: 1px;
-
- background-image: url(/img/search-icon.svg);
- background-repeat: no-repeat;
- background-size: 16px 16px;
- background-position: 4px 6px;
}
input::placeholder {
diff --git a/community/index.html b/community/index.html
index b191cb0789..58542bc146 100644
--- a/community/index.html
+++ b/community/index.html
@@ -3,6 +3,10 @@ title: Community
overview: Information on the various ways to participate and interact with the Istio community.
layout: community
---
+{% assign home = "" %}
+{% if site.github.environment == "dotcom" %}
+{% assign home = site.baseurl %}
+{% endif %}
<section class="lead">
<p>
diff --git a/faq/index.md b/faq/index.md
index acdff9c580..4f2a56afce 100644
--- a/faq/index.md
+++ b/faq/index.md
@@ -31,7 +31,8 @@ Traditionally, much of the logic handled by Istio has been built directly into a
We recommend starting with the [BookInfo sample](/docs/samples/bookinfo.html). The BookInfo example walks through setting up a cluster with four distinct microservices managed by Istio. It exercises some basic features, including content-based routing, fault injection, and rate-limiting.
-After you have mastered the BookInfo sample, you are ready to begin using Istio for your own services. To start using Istio on your existing Kubernetes cluster, please refer to our [Installation](/docs/tasks/istio-installation.html) task guide.
+After you have mastered the BookInfo sample, you are ready to begin using Istio for your own services. To start using Istio on your existing Kubernetes
+cluster, please refer to our [Installation](/docs/tasks/installing-istio.html) task guide.
#### What is the license?
diff --git a/js/common.js b/js/common.js
index 3eaa4bc6be..e53801cd64 100644
--- a/js/common.js
+++ b/js/common.js
@@ -196,7 +196,7 @@ $(document).ready(function() {
$('.slick-prev').addClass('active');
});
- $('.toc').toc({ listType: 'ul' });
+ $('#toc').toc({ listType: 'ul' });
$('.nav-toggle, .hamburger').on('click', function(){
$('.top-nav').toggleClass('right');
@@ -253,7 +253,7 @@ $.getScript("{{ site.baseurl }}/js/jquery.collapsible.js", function(){
$.fn.toc = function(options) {
var defaults = {
noBackToTopLinks: false,
- title: '',
+ title: 'On this page...',
minimumHeaders: 2,
headers: 'h1, h2, h3, h4, h5, h6',
listType: 'ol', // values: [ol|ul]
@@ -285,7 +285,10 @@ $.getScript("{{ site.baseurl }}/js/jquery.collapsible.js", function(){
}
var render = {
- show: function() { output.hide().html(html).show(settings.showSpeed); },
+ show: function() {
+ $('#toc').addClass('toc');
+ output.hide().html(html).show(settings.showSpeed);
+ },
slideDown: function() { output.hide().html(html).slideDown(settings.showSpeed); },
fadeIn: function() { output.hide().html(html).fadeIn(settings.showSpeed); },
none: function() { output.html(html); }
diff --git a/js/navtree.js b/js/navtree.js
index 0a0e589ff6..061ba3a1a8 100644
--- a/js/navtree.js
+++ b/js/navtree.js
@@ -75,12 +75,22 @@ function outputNavBarTree(items) {
var item = items[i];
if (item.children.length == 0) {
- document.write("<li class='doc-side-nav-list-item'><a href='");
+ if (item.doc.url == location.pathname) {
+ document.write("<li class='doc-side-nav-list-item'><a class='current' href='");
+ }
+ else {
+ document.write("<li class='doc-side-nav-list-item'><a href='");
+ }
document.write("{{home}}");
document.write(item.doc.url);
document.write("'>");
document.write(item.doc.title);
- document.writeln("</a></li>");
+ document.writeln("</a>");
+
+ if (item.doc.order == 9999) {
+ document.writeln('(please set order: front matter for this document)')
+ }
+ document.writeln("</li>");
}
}
@@ -98,6 +108,10 @@ function outputNavBarTree(items) {
}
document.writeln("</label>");
+ if (item.doc.order == 9999) {
+ document.writeln('(please set order: front matter for this document)')
+ }
+
outputNavBarTree(item.children);
document.writeln("</li>");
}
diff --git a/js/search.js b/js/search.js
index c099701961..0d8a2355ae 100644
--- a/js/search.js
+++ b/js/search.js
@@ -1,9 +1,18 @@
(function ($) {
+ function doSearch() {
+ var url = '/docs/search/?q=' + document.getElementsByName('q')[0].value;
+ window.location.assign(url);
+ }
+
$(document).ready(function() {
$('#searchbox_demo').on('submit', function(e) {
e.preventDefault();
- var url = '/docs/search/?q=' + document.getElementsByName('q')[0].value;
- window.location.assign(url);
+ doSearch();
+ });
+
+ $('.btn-search').on('click', function(e) {
+ e.preventDefault();
+ doSearch();
});
});
}(jQuery));
diff --git a/scripts/auto-generate-mixer-cli.sh b/scripts/auto-generate-mixer-cli.sh
new file mode 100755
index 0000000000..04795468af
--- /dev/null
+++ b/scripts/auto-generate-mixer-cli.sh
@@ -0,0 +1,102 @@
+#!/bin/sh
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+if [[ -z "${MIXCOL_CLI}" ]]; then
+ echo "No mixcol command defined via the environment variable MIXCOL_CLI"
+ exit 1
+fi
+
+ISTIO_BASE=$(cd "$(dirname "$0")" ; pwd -P)/..
+MIXER_CLI_DIR=$(readlink -f ${ISTIO_BASE}/_docs/reference/mixercli/)
+WORKING_DIR=$(mktemp -d)
+
+function pageHeader() {
+ title=${1}
+ overview=${2}
+ order=${3}
+ cat <<EOF
+---
+title: ${title}
+overview: ${overview}
+layout: docs
+order: ${order}
+type: markdown
+---
+
+EOF
+}
+
+function generateIndex() {
+ cat <<EOF
+---
+title: The Mixer CLI
+overview: Options showing how to use the Mixer's CLIs.
+order: 30
+layout: docs
+type: markdown
+---
+{% include section-index.html %}
+
+EOF
+}
+
+# combines the collateral files of a single binary, updating links
+function processPerBinaryFiles() {
+ # mixcol produces a top level markdown file named ${commandName}.md which
+ # serves as our base file. We'll cat the other files into it after
+ # processing.
+ commandName=${1}
+ order=${2}
+ primaryFile=${WORKING_DIR}/${commandName}.md
+ if [[ -z ${primaryFile} ]]; then
+ echo "could not find ${primaryFile}, skipping processing ${commandName}"
+ return
+ fi
+
+ out=$(mktemp)
+ overview=$(sed -n '/^[^#]/ {p;q;}' ${primaryFile})
+ pageHeader "${commandName}" "${overview}" "${order}" > ${out}
+
+ # insert an anchor and remove the last line of the file, which is a note
+ # that its auto generated
+ echo "<a name=\"${commandName}\"></a>" >> ${out}
+ head -n -1 ${primaryFile} >> ${out}
+ # this pattern matches only subcommands of ${commandName}, and not
+ # ${commandName}'s output file itself
+ for file in ${WORKING_DIR}/${commandName}_*.md; do
+ fullFileName=$(basename ${file})
+ noext=${fullFileName%%.*}
+ # synthesize an anchor to replace the generated links to separate pages
+ echo "<a name=\"${noext}\"></a>" >> ${out}
+ head -n -1 ${file} >> ${out}
+ done
+ # We can't rely on ordering, so we need to iterate over the files twice to be sure
+ # we update all links.
+ for file in ${WORKING_DIR}/${commandName}_*.md; do
+ fullFileName=$(basename ${file})
+ noext=${fullFileName%%.*}
+ # change links to refer to anchors
+ sed -i "s,${fullFileName},#${noext},g" ${out};
+ done
+ # final pass updating the subcommand's "SEE ALSO" links to the command itself
+ sed "s,${commandName}.md,#${commandName},g;s/SEE ALSO/See Also/g" ${out};
+}
+
+# Generate markdown files with mixcol. We create a subdirectory so we can grab
+# all *.md files out of it without having to worry about random *.md files
+# added to the root of the mixer git repo.
+mkdir -p ${WORKING_DIR}
+${MIXCOL_CLI} -o ${WORKING_DIR}
+
+# Clean up the target directory
+mkdir -p ${MIXER_CLI_DIR}
+rm -f ${MIXER_CLI_DIR}/*
+
+generateIndex > ${MIXER_CLI_DIR}/index.md
+processPerBinaryFiles "mixc" 1 > ${MIXER_CLI_DIR}/mixc.md
+processPerBinaryFiles "mixs" 2 > ${MIXER_CLI_DIR}/mixs.md
+
+rm -rfd ${WORKING_DIR}
diff --git a/true-index.html b/true-index.html
index f9dda6ab6a..6b7c8b68e8 100644
--- a/true-index.html
+++ b/true-index.html
@@ -2,6 +2,11 @@
layout: landing
title: istio.io
---
+{% assign home = "" %}
+{% if site.github.environment == "dotcom" %}
+{% assign home = site.baseurl %}
+{% endif %}
+
<div id="landing-content" class="container landing-content-container">
<div class="row" >
<div class="col-md-11 nofloat center-block landing-row">
@@ -20,7 +25,7 @@ title: istio.io
<h3 class="col-sm-7 landing-row-title">Resilience across languages and platforms</h3>
<p class="col-sm-7">Increase reliability by shielding applications from flaky networks and cascading failures in adverse conditions.</p>
<div class="col-sm-7">
- <a href="{{home}}/about#osp"><button class="btn btn-grpc waves-effect waves-light btn-read-more">READ MORE</button></a>
+ <a href="{{home}}/about"><button class="btn btn-grpc waves-effect waves-light btn-read-more">READ MORE</button></a>
</div>
</div>
</div>
diff --git a/wip/fault-injection.md b/wip/fault-injection.md
index a241e79cc3..d808ce6b06 100644
--- a/wip/fault-injection.md
+++ b/wip/fault-injection.md
@@ -34,7 +34,7 @@ cd istio
kubectl apply -f ./kubernetes/istio-install
```
-You should also have installed the [istioctl]({{site.baseurl}}/reference/istioctl.html) CLI.
+You should also have installed the [istioctl](/docs/reference/istioctl/istioctl.html) CLI.
@@ -129,7 +129,3 @@ kubectl delete -f {{site.baseurl}}/docs/tasks/nginx-httpbin.yaml
We have seen two microservices, httpbin and NGINX, connected via an Istio service mesh. We have
used the service mesh to introduce a maximum delay using a timeout in all communications to httpbin.
-
-
-
-