From 6ab6ad9205eed3d2124239b301ede0e39f7f1589 Mon Sep 17 00:00:00 2001 From: Jason Young Date: Tue, 2 May 2017 08:27:02 -0700 Subject: [PATCH 01/18] Update integrating-services-into-istio.md (#89) * Update integrating-services-into-istio.md * fix wording * address review comments * fix formatting and some additional text * clean-up some text * 2nd round of review comments addressed - remove duplicated text - remove mention of core dumps --- .../tasks/integrating-services-into-istio.md | 199 ++++++++++++++++-- 1 file changed, 185 insertions(+), 14 deletions(-) diff --git a/_docs/tasks/integrating-services-into-istio.md b/_docs/tasks/integrating-services-into-istio.md index 5e5f9babb7..4f307181cd 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]({{site.bareurl}}/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]({{site.bareurl}}/docs/tasks/istio-installation.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]({{site.bareurl}}/docs/reference/istioctl/istioctl_kube-inject.html) +* See the [bookinfo sample]({{site.bareurl}}/docs/samples/bookinfo.html) for a more complete example of applications integrated on Kubernetes with Istio. From cc36c241045ca44375bf70d84fa2aefa16c35f69 Mon Sep 17 00:00:00 2001 From: Martin Taillefer Date: Tue, 2 May 2017 09:41:58 -0700 Subject: [PATCH 02/18] Fetch search stuff over https: instead of http: to avoid problems. --- _includes/search-box.html | 2 +- _sass/modules/_nav.scss | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_includes/search-box.html b/_includes/search-box.html index 152f33431e..ddcfb2c59a 100644 --- a/_includes/search-box.html +++ b/_includes/search-box.html @@ -6,5 +6,5 @@ - + 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) { From 7c0c755075f3811f9902857cf7366e55fb19c3c9 Mon Sep 17 00:00:00 2001 From: Martin Taillefer Date: Tue, 2 May 2017 11:16:56 -0700 Subject: [PATCH 03/18] Fix several broken links. --- _docs/concepts/policy-and-control/attributes.md | 2 +- _docs/concepts/traffic-management/rules-configuration.md | 2 +- _docs/concepts/what-is-istio/architecture.md | 2 +- _docs/reference/istioctl/istioctl.md | 2 +- _docs/samples/bookinfo.md | 6 +++--- _docs/tasks/egress.md | 4 ++-- _docs/tasks/ingress.md | 2 +- _docs/tasks/integrating-services-into-istio.md | 8 ++++---- _layouts/base.html | 2 +- faq/index.md | 3 ++- wip/fault-injection.md | 2 +- 11 files changed, 18 insertions(+), 17 deletions(-) diff --git a/_docs/concepts/policy-and-control/attributes.md b/_docs/concepts/policy-and-control/attributes.md index 163dc0cbe4..140ede2d28 100644 --- a/_docs/concepts/policy-and-control/attributes.md +++ b/_docs/concepts/policy-and-control/attributes.md @@ -31,7 +31,7 @@ determined by the set of attribute producers being used in the deployment. The p is Envoy, although specialized Mixer adapters and services can also introduce attributes. The common baseline set of attributes available in most Istio deployments is defined -[here](/docs/reference/attribute-vocabulary.html). +[here](/docs/reference/api/attribute-vocabulary.html). diff --git a/_docs/concepts/traffic-management/rules-configuration.md b/_docs/concepts/traffic-management/rules-configuration.md index cd3816b036..47c52fb816 100644 --- a/_docs/concepts/traffic-management/rules-configuration.md +++ b/_docs/concepts/traffic-management/rules-configuration.md @@ -177,7 +177,7 @@ httpReqRetries: ``` Note that request timeouts and retries can also be -[overridden on a per-request basis](https://istio.io/docs/concepts/traffic-management/handling-failures.html#fine-tuning). +[overridden on a per-request basis](/docs/concepts/traffic-management/handling-failures.html#fine-tuning). See the [request timeouts task](/docs/tasks/request-timeouts.html) for a demonstration of timeout control. diff --git a/_docs/concepts/what-is-istio/architecture.md b/_docs/concepts/what-is-istio/architecture.md index f38bb52f34..58b1e4a7f4 100644 --- a/_docs/concepts/what-is-istio/architecture.md +++ b/_docs/concepts/what-is-istio/architecture.md @@ -50,7 +50,7 @@ Mixer is responsible for enforcing access control and usage policies across the services. The proxy extracts request level attributes which are sent to Mixer for evaluation. More information on the attribute extraction and policy evaluation can be found here. Mixer includes a flexible plugin model enabling it to interface with a variety of host environments and infrastructure backends, abstracting -the Envoy proxy and Istio-managed services from these details. More on Mixer [here](./mixer.html) +the Envoy proxy and Istio-managed services from these details. More on Mixer [here](/docs/reference/policy-and-control/mixer.html) ## Istio-Manager 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/samples/bookinfo.md b/_docs/samples/bookinfo.md index 4e48ab6c03..c82848c837 100644 --- a/_docs/samples/bookinfo.md +++ b/_docs/samples/bookinfo.md @@ -38,7 +38,7 @@ There are 3 versions of the reviews microservice: The end-to-end architecture of the application is shown below. -![Bookinfo app_noistio]({{site.bareurl}}/docs/samples/img/bookinfo/noistio.svg) +![Bookinfo app_noistio](/docs/samples/img/bookinfo/noistio.svg) This application is polyglot, i.e., the microservices are written in different languages. @@ -65,12 +65,12 @@ This application is polyglot, i.e., the microservices are written in different l 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.html#kube-inject). 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: - ![Bookinfo app]({{site.bareurl}}/docs/samples/img/bookinfo/withistio.svg) + ![Bookinfo app](/docs/samples/img/bookinfo/withistio.svg) 1. Confirm all services and pods are correctly defined and running: diff --git a/_docs/tasks/egress.md b/_docs/tasks/egress.md index 21a6206297..41b8b1fb03 100644 --- a/_docs/tasks/egress.md +++ b/_docs/tasks/egress.md @@ -16,7 +16,7 @@ to create an Egress Envoy, define an external service and make requests to the s ## 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). @@ -56,7 +56,7 @@ spec: - port: 443 ``` -Deploy your app(s) using the [istioctl kube-inject]({{site.bareurl}}/docs/reference/istioctl.html#kube-inject) command. +Deploy your app(s) using the [istioctl kube-inject](/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) directory. Each app directory contains an associated README.md providing more details. diff --git a/_docs/tasks/ingress.md b/_docs/tasks/ingress.md index 432f9b6247..c4501e78f0 100644 --- a/_docs/tasks/ingress.md +++ b/_docs/tasks/ingress.md @@ -17,7 +17,7 @@ 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 diff --git a/_docs/tasks/integrating-services-into-istio.md b/_docs/tasks/integrating-services-into-istio.md index 4f307181cd..8b055a1d40 100644 --- a/_docs/tasks/integrating-services-into-istio.md +++ b/_docs/tasks/integrating-services-into-istio.md @@ -10,13 +10,13 @@ type: markdown 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]({{site.bareurl}}/docs/reference/istioctl/istioctl_kube-inject.html) +using [istioctl kube-inject](/docs/reference/istioctl/istioctl_kube-inject.html) ## 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). +[Installation Steps](/docs/tasks/installing-istio.html). ## Injecting Envoy sidecar into a deployment @@ -202,6 +202,6 @@ routing traffic. ## What's next -* Review full documentation for [istioctl kube-inject]({{site.bareurl}}/docs/reference/istioctl/istioctl_kube-inject.html) +* Review full documentation for [istioctl kube-inject](/docs/reference/istioctl/istioctl_kube-inject.html) -* See the [bookinfo sample]({{site.bareurl}}/docs/samples/bookinfo.html) for a more complete example of applications integrated on Kubernetes with Istio. +* See the [bookinfo sample](/docs/samples/bookinfo.html) for a more complete example of applications integrated on Kubernetes with Istio. diff --git a/_layouts/base.html b/_layouts/base.html index 47516abd54..dd3cd12de4 100644 --- a/_layouts/base.html +++ b/_layouts/base.html @@ -32,7 +32,7 @@ layout: compress - + 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/wip/fault-injection.md b/wip/fault-injection.md index a241e79cc3..915d0ed039 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.html) CLI. From f447eec8cbe5684ca71af512440f0e76d7422e79 Mon Sep 17 00:00:00 2001 From: Dave Date: Tue, 2 May 2017 14:51:05 -0400 Subject: [PATCH 04/18] toc CSS and JS fixes (#94) --- _layouts/docs.html | 16 ++++++++-------- _sass/base/_common.scss | 14 +++++++++----- js/common.js | 9 ++++++--- 3 files changed, 23 insertions(+), 16 deletions(-) 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 %} -
-
- {% include doc-side-nav.html %} +
+
+ {% include doc-side-nav.html %} +
+
+
+ {{ content }} +
-
- {{ content }} -
- -
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/js/common.js b/js/common.js index 3eaa4bc6be..45f16075ed 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: 'Table of Contents', 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); } From 55a037737b7a9f1a0f3471f7d52e030dd44ed948 Mon Sep 17 00:00:00 2001 From: Dave Date: Tue, 2 May 2017 17:25:05 -0400 Subject: [PATCH 05/18] TOC display and highlight current document in left nav (#95) * toc CSS and JS fixes * highlight current doc in left nav --- js/navtree.js | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/js/navtree.js b/js/navtree.js index 0a0e589ff6..d773e45f38 100644 --- a/js/navtree.js +++ b/js/navtree.js @@ -75,7 +75,12 @@ function outputNavBarTree(items) { var item = items[i]; if (item.children.length == 0) { - document.write("
  • "); From 72ba0eb4e3675f06d81972aac570537408cc3e1f Mon Sep 17 00:00:00 2001 From: Dave Date: Tue, 2 May 2017 17:25:36 -0400 Subject: [PATCH 06/18] Highlight Tab in Top Nav and Highlight Active Document in Left Nav (#98) * toc CSS and JS fixes * highlight current doc in left nav * highlight current doc in left nav * highlight current doc in left nav * highlight current doc in left nav * highlight tab in doc-top-nav for all documents in category * highlight current doc in left nav * highlight tab in doc-top-nav for all documents in category * highlight current doc in left nav * highlight tab in doc-top-nav for all documents in category --- _includes/doc-top-nav.html | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) 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 @@ From 4fe600682b2d9c97a60eb57926231ccc00f5a25f Mon Sep 17 00:00:00 2001 From: Kuat Date: Tue, 2 May 2017 14:39:38 -0700 Subject: [PATCH 07/18] Update installing-istio.md (#85) --- _docs/tasks/installing-istio.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_docs/tasks/installing-istio.md b/_docs/tasks/installing-istio.md index 3a87c7fb66..3339f81bee 100644 --- a/_docs/tasks/installing-istio.md +++ b/_docs/tasks/installing-istio.md @@ -123,7 +123,8 @@ ServiceGraph addons: ## 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 From 32119f89a93551d3d815712a2b1d3e7865118d9e Mon Sep 17 00:00:00 2001 From: Zack Date: Tue, 2 May 2017 15:11:18 -0700 Subject: [PATCH 08/18] Automate generation of mixer CLI collateral docs (#99) * Automate generation of mixer CLI collateral docs * SEE ALSO -> See Also --- _docs/reference/mixercli/index.md | 9 ++ _docs/reference/mixercli/mixc.md | 231 +++++++++++++++++++++++++++++ _docs/reference/mixercli/mixs.md | 127 ++++++++++++++++ scripts/auto-generate-mixer-cli.sh | 102 +++++++++++++ 4 files changed, 469 insertions(+) create mode 100644 _docs/reference/mixercli/index.md create mode 100644 _docs/reference/mixercli/mixc.md create mode 100644 _docs/reference/mixercli/mixs.md create mode 100755 scripts/auto-generate-mixer-cli.sh 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 +--- + + +## 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 + + +## 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 + + +## 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 + + +## 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 + + +## 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 +--- + + +## 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 + + +## 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 + + +## 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 + + +## 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 + + +## 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 + + +## 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/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 < ${out} + + # insert an anchor and remove the last line of the file, which is a note + # that its auto generated + echo "" >> ${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 "" >> ${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} From 8d24dc9e78d68d02e8220445d2b694e0506f5deb Mon Sep 17 00:00:00 2001 From: Dave Date: Wed, 3 May 2017 00:00:17 -0400 Subject: [PATCH 09/18] Replace large search button with icon (#101) --- _includes/search-box.html | 3 ++- js/search.js | 13 +++++++++++-- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/_includes/search-box.html b/_includes/search-box.html index ddcfb2c59a..a17ba4e2e0 100644 --- a/_includes/search-box.html +++ b/_includes/search-box.html @@ -4,7 +4,8 @@ - + +
    • 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)); From 25fabe16f9de7aead822940cdf952c7bd6779499 Mon Sep 17 00:00:00 2001 From: Martin Taillefer Date: Tue, 2 May 2017 11:51:55 -0700 Subject: [PATCH 10/18] Various fixes - Fix a number of broken links when viewing on a github staging site. - Updated highligthing of "Edit this Page" pencil to match what other buttons use on the site. - Fixed the rendering of buttons on the landing page to have the proper rounded corners to match our style. - Support documents which omit the order: front matter field. Instead of mysterious failues, they are now processed correctly and an error message is inserted in the generated HTML to let the author know to add the missing info. --- _docs/concepts/what-is-istio/architecture.md | 2 +- _docs/index.md | 12 ++++--- .../contribute/writing-a-new-topic.md | 10 +----- _includes/doc-side-nav.html | 6 +++- _includes/search-box.html | 3 +- _layouts/about.html | 5 +++ _layouts/base.html | 2 +- _layouts/community.html | 5 +++ _sass/modules/_buttons.scss | 1 + _sass/modules/_contribute-links.scss | 8 ++++- _sass/modules/_doc-nav.scss | 32 ------------------- community/index.html | 4 +++ js/navtree.js | 11 ++++++- true-index.html | 7 +++- 14 files changed, 55 insertions(+), 53 deletions(-) diff --git a/_docs/concepts/what-is-istio/architecture.md b/_docs/concepts/what-is-istio/architecture.md index 58b1e4a7f4..db6ad24079 100644 --- a/_docs/concepts/what-is-istio/architecture.md +++ b/_docs/concepts/what-is-istio/architecture.md @@ -50,7 +50,7 @@ Mixer is responsible for enforcing access control and usage policies across the services. The proxy extracts request level attributes which are sent to Mixer for evaluation. More information on the attribute extraction and policy evaluation can be found here. Mixer includes a flexible plugin model enabling it to interface with a variety of host environments and infrastructure backends, abstracting -the Envoy proxy and Istio-managed services from these details. More on Mixer [here](/docs/reference/policy-and-control/mixer.html) +the Envoy proxy and Istio-managed services from these details. More on Mixer [here](/docs/concepts/policy-and-control/mixer.html). ## Istio-Manager diff --git a/_docs/index.md b/_docs/index.md index 2226347bf8..3acac52a2b 100644 --- a/_docs/index.md +++ b/_docs/index.md @@ -8,21 +8,25 @@ order: 0 layout: docs type: markdown --- +{% assign home = "" %} +{% if site.github.environment == "dotcom" %} +{% assign home = site.baseurl %} +{% endif %} # Welcome Welcome to Istio's documentation home page. From here you can learn all about Istio by following the links below: -- [Concepts](/docs/concepts). Concepts explain some significant aspect of Istio. This +- [Concepts]({{home}}/docs/concepts/). Concepts explain some significant aspect of Istio. This is where you can learn about what Istio does and how it does it. -- [Tasks](/docs/tasks). Tasks show you how to do a single directed activity with Istio. +- [Tasks]({{home}}/docs/tasks/). Tasks show you how to do a single directed activity with Istio. -- [Samples](/docs/samples). Samples are fully working stand-alone examples +- [Samples]({{home}}/docs/samples/). Samples are fully working stand-alone examples intended to highlight a particular set of Istio's features. -- [Reference](/docs/reference). Detailed exhaustive lists of +- [Reference]({{home}}/docs/reference/). Detailed exhaustive lists of command-line options, configuration options, API definitions, and procedures. We're always looking for help improving our documentation, so please don't hesitate to diff --git a/_docs/reference/contribute/writing-a-new-topic.md b/_docs/reference/contribute/writing-a-new-topic.md index 39d7b34d69..a274c40c81 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 @@ -103,7 +96,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 +107,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/_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/search-box.html b/_includes/search-box.html index a17ba4e2e0..a16d98ee6f 100644 --- a/_includes/search-box.html +++ b/_includes/search-box.html @@ -4,8 +4,7 @@ - - + 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 %} +
    diff --git a/_layouts/base.html b/_layouts/base.html index dd3cd12de4..12ecac71e9 100644 --- a/_layouts/base.html +++ b/_layouts/base.html @@ -28,7 +28,7 @@ layout: compress - + 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 %} +
    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/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 %}

    diff --git a/js/navtree.js b/js/navtree.js index d773e45f38..061ba3a1a8 100644 --- a/js/navtree.js +++ b/js/navtree.js @@ -85,7 +85,12 @@ function outputNavBarTree(items) { document.write(item.doc.url); document.write("'>"); document.write(item.doc.title); - document.writeln(""); + document.writeln(""); + + if (item.doc.order == 9999) { + document.writeln('(please set order: front matter for this document)') + } + document.writeln(""); } } @@ -103,6 +108,10 @@ function outputNavBarTree(items) { } document.writeln(""); + if (item.doc.order == 9999) { + document.writeln('(please set order: front matter for this document)') + } + outputNavBarTree(item.children); document.writeln(""); } 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 %} +

    @@ -20,7 +25,7 @@ title: istio.io

    Resilience across languages and platforms

    Increase reliability by shielding applications from flaky networks and cascading failures in adverse conditions.

    - +
    From 30271f14357c554008bfc314d6d52df5e299ec35 Mon Sep 17 00:00:00 2001 From: Martin Taillefer Date: Wed, 3 May 2017 06:05:05 -0700 Subject: [PATCH 11/18] Fix capitalization of a few headers. --- _docs/concepts/policy-and-control/mixer-config.md | 2 +- _docs/tasks/fault-injection.md | 2 +- _docs/tasks/request-routing.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_docs/concepts/policy-and-control/mixer-config.md b/_docs/concepts/policy-and-control/mixer-config.md index ec0b794862..4bd11b2cd8 100644 --- a/_docs/concepts/policy-and-control/mixer-config.md +++ b/_docs/concepts/policy-and-control/mixer-config.md @@ -211,7 +211,7 @@ at request time in order to produce the metric. Each aspect kind defines its own particular format of configuration data. The exhaustive set of aspect configuration formats can be found in *TBD*. -#### Attribute Expressions +#### Attribute expressions Mixer features a number of independent [request processing phases](/docs/concepts/policy-and-control/mixer.html#request-phases). The *Attribute Processing* phase is responsible for ingesting a set of attributes and producing the adapter parameters diff --git a/_docs/tasks/fault-injection.md b/_docs/tasks/fault-injection.md index 367057d8d3..8df9d162a4 100644 --- a/_docs/tasks/fault-injection.md +++ b/_docs/tasks/fault-injection.md @@ -26,7 +26,7 @@ This task shows how to inject delays and test the resiliency of your application $ 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 diff --git a/_docs/tasks/request-routing.md b/_docs/tasks/request-routing.md index 8eb43c64d3..a90e6b860d 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. From 77a316559f2a61d5a5e9ba6ef94960da4749be2a Mon Sep 17 00:00:00 2001 From: Martin Taillefer Date: Wed, 3 May 2017 06:29:03 -0700 Subject: [PATCH 12/18] More fixes. - Change "Table of Contents" to "On this page..." - Remove the extra magnifying glass in the search input box. --- _docs/tasks/fault-injection.md | 2 +- _sass/modules/_search-box.scss | 6 ------ js/common.js | 2 +- 3 files changed, 2 insertions(+), 8 deletions(-) diff --git a/_docs/tasks/fault-injection.md b/_docs/tasks/fault-injection.md index 8df9d162a4..4f454315a0 100644 --- a/_docs/tasks/fault-injection.md +++ b/_docs/tasks/fault-injection.md @@ -26,7 +26,7 @@ This task shows how to inject delays and test the resiliency of your application $ 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 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/js/common.js b/js/common.js index 45f16075ed..e53801cd64 100644 --- a/js/common.js +++ b/js/common.js @@ -253,7 +253,7 @@ $.getScript("{{ site.baseurl }}/js/jquery.collapsible.js", function(){ $.fn.toc = function(options) { var defaults = { noBackToTopLinks: false, - title: 'Table of Contents', + title: 'On this page...', minimumHeaders: 2, headers: 'h1, h2, h3, h4, h5, h6', listType: 'ol', // values: [ol|ul] From e577e980db31160d07aa319294b178f2d1eb1d12 Mon Sep 17 00:00:00 2001 From: mandarjog Date: Wed, 3 May 2017 06:34:46 -0700 Subject: [PATCH 13/18] rate limiting (#100) * rate limiting * Review comments * Remove configuring-mixer section in favor of specific configuration tasks --- _docs/tasks/configuring-mixer.md | 36 -------------- _docs/tasks/metrics-logs.md | 1 - _docs/tasks/rate-limiting.md | 83 +++++++++++++++++++++++++------- 3 files changed, 66 insertions(+), 54 deletions(-) delete mode 100644 _docs/tasks/configuring-mixer.md 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/metrics-logs.md b/_docs/tasks/metrics-logs.md index 7dacb5a430..7a061b9de7 100644 --- a/_docs/tasks/metrics-logs.md +++ b/_docs/tasks/metrics-logs.md @@ -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..98b006355f 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 @@ -23,21 +23,34 @@ This task shows you how to use Istio to dynamically limit the traffic to a servi ```bash $ istioctl create -f route-rule-all-v1.yaml - $ istioctl replace -f route-rule-reviews-v3.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). From 05fbabce02cc92f0763522b56579773bee204d72 Mon Sep 17 00:00:00 2001 From: Jason Young Date: Wed, 3 May 2017 09:19:30 -0700 Subject: [PATCH 14/18] update links to istioctl reference (#102) --- .../traffic-management/rules-configuration.md | 14 +++++------- _docs/samples/bookinfo.md | 14 ++++++------ _docs/tasks/egress.md | 22 +++++++++---------- _docs/tasks/installing-istio.md | 10 ++++----- wip/fault-injection.md | 6 +---- 5 files changed, 29 insertions(+), 37 deletions(-) diff --git a/_docs/concepts/traffic-management/rules-configuration.md b/_docs/concepts/traffic-management/rules-configuration.md index 47c52fb816..f454e4a8c1 100644 --- a/_docs/concepts/traffic-management/rules-configuration.md +++ b/_docs/concepts/traffic-management/rules-configuration.md @@ -1,7 +1,7 @@ --- title: Rules Configuration overview: Provides a high-level overview of the domain-specific language used by Istio to configure traffic management rules in the service mesh. - + order: 50 layout: docs @@ -34,7 +34,7 @@ routed. In a Kubernetes deployment of Istio, the route *tag* "version: v1" corresponds to a Kubernetes *label* "version: v1". The rule ensures that only Kubernetes pods containing the label "version: v1" will receive traffic. Rules can be configured using the -[istioctl CLI](/docs/reference/istioctl.html). See the +[istioctl CLI](/docs/reference/istioctl/istioctl.html). See the [configuring request routing task](/docs/tasks/request-routing.html) for examples. @@ -62,7 +62,7 @@ destination: reviews.default.svc.cluster.local The *destination* value SHOULD be a fully qualified domain name (FQDN). It is used by Istio-Manager for matching rules to services. For example, in Kubernetes, a fully qualified domain name for a service can be -constructed using the following format: *serviceName.namespace.dnsSuffix*. +constructed using the following format: *serviceName.namespace.dnsSuffix*. ### Qualify rules by source/headers @@ -201,7 +201,7 @@ httpFault: ``` The other kind of fault, abort, can be used to prematurely terminate a request, -for example, to simulate a failure. +for example, to simulate a failure. The following example will return an HTTP 400 error code for 10% of the requests to the "ratings" service "v1". @@ -218,7 +218,7 @@ httpFault: ``` Sometimes delays and abort faults are used together. For example, the following rule will delay -by 5 seconds all requests from the "reviews" service "v2" to the "ratings" service "v1" and +by 5 seconds all requests from the "reviews" service "v2" to the "ratings" service "v1" and then abort 10 percent of them: ```yaml @@ -397,7 +397,3 @@ rules are going to be needed. Therefore, setting a default rule for every service, right from the start, is generally considered a best practice in Istio. - - - - diff --git a/_docs/samples/bookinfo.md b/_docs/samples/bookinfo.md index c82848c837..198f093abe 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 @@ -55,17 +55,17 @@ 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](/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: @@ -86,7 +86,7 @@ This application is polyglot, i.e., the microservices are written in different l ratings 10.0.0.15 9080/TCP 6m reviews 10.0.0.170 9080/TCP 6m ``` - + and ```bash @@ -121,7 +121,7 @@ This application is polyglot, i.e., the microservices are written in different l ``` 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 200 diff --git a/_docs/tasks/egress.md b/_docs/tasks/egress.md index 41b8b1fb03..1fa962346c 100644 --- a/_docs/tasks/egress.md +++ b/_docs/tasks/egress.md @@ -9,7 +9,7 @@ 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. @@ -18,17 +18,17 @@ to create an Egress Envoy, define an external service and make requests to the s 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). -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](/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,7 +67,7 @@ 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 @@ -89,4 +89,4 @@ 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/installing-istio.md b/_docs/tasks/installing-istio.md index 3339f81bee..199912a1c4 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 @@ -45,9 +45,9 @@ clone Istio's [GitHub](https://github.com/istio/istio) repository: ```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 ``` @@ -58,7 +58,7 @@ clone Istio's [GitHub](https://github.com/istio/istio) repository: 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 @@ -127,7 +127,7 @@ for example [bookinfo](/docs/samples/bookinfo.html). Note that the application s 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 .yaml) diff --git a/wip/fault-injection.md b/wip/fault-injection.md index 915d0ed039..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](/docs/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. - - - - From 55a82fbc51157bb682f53bb5439f81726d996608 Mon Sep 17 00:00:00 2001 From: Douglas Reid Date: Wed, 3 May 2017 09:35:14 -0700 Subject: [PATCH 15/18] Add servicegraph bits to BookInfo sample (#93) --- _docs/samples/bookinfo.md | 26 ++++++++++++++++++++ _docs/samples/img/bookinfo/servicegraph.png | Bin 0 -> 23841 bytes 2 files changed, 26 insertions(+) create mode 100644 _docs/samples/img/bookinfo/servicegraph.png diff --git a/_docs/samples/bookinfo.md b/_docs/samples/bookinfo.md index 198f093abe..3f1e313088 100644 --- a/_docs/samples/bookinfo.md +++ b/_docs/samples/bookinfo.md @@ -127,6 +127,32 @@ This application is polyglot, i.e., the microservices are written in different l 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: + + ![Bookinfo servicegraph](/docs/samples/img/bookinfo/servicegraph.png) + + 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 0000000000000000000000000000000000000000..98ef64b65a368597a9895353746ff1934953cba4 GIT binary patch literal 23841 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 Date: Wed, 3 May 2017 10:27:42 -0700 Subject: [PATCH 16/18] Istio auth tutorial (#73) * Add Istio auth configuration instructions. * Improve Istio auth page. * Improve Istio auth tutorial. * Small fixes. * Small fixes. * Fixes according to comments. * Small fixes. --- _docs/tasks/installing-istio.md | 31 ++++++- _docs/tasks/istio-auth.md | 152 +++++++++++++++++++++++++++++--- 2 files changed, 168 insertions(+), 15 deletions(-) diff --git a/_docs/tasks/installing-istio.md b/_docs/tasks/installing-istio.md index 199912a1c4..be7da4ad7f 100644 --- a/_docs/tasks/installing-istio.md +++ b/_docs/tasks/installing-istio.md @@ -40,7 +40,10 @@ 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 @@ -52,6 +55,19 @@ clone Istio's [GitHub](https://github.com/istio/istio) repository: 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 @@ -110,7 +126,8 @@ ServiceGraph addons: (e.g., minikube), the `EXTERNAL-IP` will say `` 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,6 +135,7 @@ 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 @@ -137,10 +155,18 @@ kubectl create -f <(istioctl kube-inject -f .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 @@ -150,4 +176,5 @@ kubectl create -f <(istioctl kube-inject -f .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/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 +``` + +#### 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 .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 .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 -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 -c proxy -- ls /etc/envoy +# Get the config file named "envoy-revX.json". +kubectl exec -c proxy -- cat /etc/envoy/envoy-revX.json | grep ssl_context +# Expect ssl_context in the output. +``` From 52e94ecc59836979fa5818ac30b881e5e72f99e6 Mon Sep 17 00:00:00 2001 From: Martin Taillefer Date: Wed, 3 May 2017 09:57:51 -0700 Subject: [PATCH 17/18] Update Style Guide to include terminology standards. - Update various documents that didn't follow the style guide in various ways. --- _docs/reference/contribute/style-guide.md | 230 ++++++++++-------- .../contribute/writing-a-new-topic.md | 17 +- _docs/reference/istioctl/istioctl_create.md | 2 +- _docs/reference/istioctl/istioctl_delete.md | 4 +- _docs/reference/istioctl/istioctl_replace.md | 2 +- _docs/samples/bookinfo.md | 12 +- _docs/tasks/egress.md | 6 +- _docs/tasks/fault-injection.md | 6 +- _docs/tasks/ingress.md | 4 +- .../tasks/integrating-services-into-istio.md | 12 +- _docs/tasks/metrics-logs.md | 18 +- _docs/tasks/rate-limiting.md | 4 +- _docs/tasks/request-routing.md | 4 +- _docs/tasks/request-timeouts.md | 8 +- 14 files changed, 177 insertions(+), 152 deletions(-) diff --git a/_docs/reference/contribute/style-guide.md b/_docs/reference/contribute/style-guide.md index c9fb27887d..6b7597b382 100644 --- a/_docs/reference/contribute/style-guide.md +++ b/_docs/reference/contribute/style-guide.md @@ -20,12 +20,12 @@ docs, follow the instructions on ## Formatting standards -### Use camel case for API objects +### Use camelCase for API objects 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 -[camel case](https://en.wikipedia.org/wiki/Camel_case). +[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. @@ -33,14 +33,13 @@ PodTemplateList, not Pod Template List. Refer to API objects without saying "object," unless omitting "object" leads to an awkward construction. - - - - - - - -
    DoDon'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 +|--------------------------------------------|------ +|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 ... ### Use angle brackets for placeholders @@ -53,93 +52,126 @@ represents. where `` is the name of one of your pods. -### Use bold for user interface elements +### Use **bold** for user interface elements - - - - -
    DoDon't
    Click Fork.Click "Fork".
    Select Other.Select 'Other'.
    +|Do |Don't +|-----------------|------ +|Click **Fork**. |Click "Fork". +|Select **Other**.|Select 'Other'. -### Use italics to define or introduce new terms +### Use _italics_ to define or introduce new terms - - - - -
    DoDon'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 +|-------------------------------------------|--- +|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**. -### Use code style for filenames, directories, and paths +### Use `code` style for filenames, directories, and paths - - - - - -
    DoDon'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.
    +|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. -## Inline code formatting +### Use `code` style for inline code and commands -### Use code style for inline code and commands +|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". -For inline code in an HTML document, use the `` tag. In a Markdown -document, use the backtick (`). +### Use `code` style for object field names - - - - -
    DoDon'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 - - - - - -
    DoDon'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. - - - - - -
    DoDon'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 - - - -
    DoDon'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 - - - -
    TermUseage
    TBDTBD
    {% 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 - - - -
    DoDon'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 - - - - -
    DoDon'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." - - - - - - -
    DoDon'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" - - - - -
    DoDon'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. - - - - - -
    DoDon'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. - - - - -
    DoDon'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. - - - - -
    DoDon'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 a274c40c81..a8c2b3312b 100644 --- a/_docs/reference/contribute/writing-a-new-topic.md +++ b/_docs/reference/contribute/writing-a-new-topic.md @@ -77,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 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/samples/bookinfo.md b/_docs/samples/bookinfo.md index 3f1e313088..3334945747 100644 --- a/_docs/samples/bookinfo.md +++ b/_docs/samples/bookinfo.md @@ -75,7 +75,7 @@ This application is polyglot, i.e., the microservices are written in different l 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 @@ -90,7 +90,7 @@ This application is polyglot, i.e., the microservices are written in different l 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,21 +109,21 @@ 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 ``` diff --git a/_docs/tasks/egress.md b/_docs/tasks/egress.md index 1fa962346c..2dcb2e217d 100644 --- a/_docs/tasks/egress.md +++ b/_docs/tasks/egress.md @@ -71,7 +71,7 @@ Make a request to the external service using the `name` from the Service spec ab 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,13 +79,13 @@ 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 diff --git a/_docs/tasks/fault-injection.md b/_docs/tasks/fault-injection.md index 4f454315a0..be71b8836e 100644 --- a/_docs/tasks/fault-injection.md +++ b/_docs/tasks/fault-injection.md @@ -22,8 +22,8 @@ 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 @@ -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 c4501e78f0..38cced25d8 100644 --- a/_docs/tasks/ingress.md +++ b/_docs/tasks/ingress.md @@ -76,7 +76,7 @@ spec: 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 ``` @@ -84,7 +84,7 @@ 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. ```bash -$ curl http://192.168.99.100:80/hello +curl http://192.168.99.100:80/hello .. response .. ``` diff --git a/_docs/tasks/integrating-services-into-istio.md b/_docs/tasks/integrating-services-into-istio.md index 8b055a1d40..dc74f83967 100644 --- a/_docs/tasks/integrating-services-into-istio.md +++ b/_docs/tasks/integrating-services-into-istio.md @@ -88,10 +88,10 @@ 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}') +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 +kubectl exec -it ${CLIENT} -c echo -- curl echo:80 | grep x-request-id x-request-id=a641eff7-eb82-4a4f-b67b-53cd3a03c399 ``` @@ -103,14 +103,14 @@ the echo pod's IP. Outbound request on client pod's proxy. ``` -$ kubectl logs ${CLIENT} proxy | grep a641eff7-eb82-4a4f-b67b-53cd3a03c399 +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 +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" ``` @@ -120,7 +120,7 @@ within the same pod when traffic is routed via localhost. This is by design. ```bash -$ kubectl exec -it ${SERVER} -c echo -- curl localhost:8080 | grep x-request-id +kubectl exec -it ${SERVER} -c echo -- curl localhost:8080 | grep x-request-id ``` ## Understanding what happened diff --git a/_docs/tasks/metrics-logs.md b/_docs/tasks/metrics-logs.md index 7a061b9de7..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"} ``` diff --git a/_docs/tasks/rate-limiting.md b/_docs/tasks/rate-limiting.md index 98b006355f..e664f5d8e7 100644 --- a/_docs/tasks/rate-limiting.md +++ b/_docs/tasks/rate-limiting.md @@ -22,8 +22,8 @@ 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-v2-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. diff --git a/_docs/tasks/request-routing.md b/_docs/tasks/request-routing.md index a90e6b860d..e6f3a3c00c 100644 --- a/_docs/tasks/request-routing.md +++ b/_docs/tasks/request-routing.md @@ -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: From 7ac7ba757fe1579a96503d551d690dfb5543fad5 Mon Sep 17 00:00:00 2001 From: Isaiah Snell-Feikema <ijsnellf@users.noreply.github.com> Date: Wed, 3 May 2017 14:29:56 -0500 Subject: [PATCH 18/18] TLS steps 1st pass (#97) --- _docs/tasks/ingress-egress-envoy.md | 37 ------------------------ _docs/tasks/ingress.md | 44 +++++++++++++++++++++++++---- 2 files changed, 39 insertions(+), 42 deletions(-) delete mode 100644 _docs/tasks/ingress-egress-envoy.md diff --git a/_docs/tasks/ingress-egress-envoy.md b/_docs/tasks/ingress-egress-envoy.md deleted file mode 100644 index eca63825d2..0000000000 --- a/_docs/tasks/ingress-egress-envoy.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Configuring Ingress/Egress with Envoy -overview: This task shows you how to setup Envoy as the Kubernetes ingress controller and the egress proxy to external services. - -order: 30 - -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/ingress.md b/_docs/tasks/ingress.md index 38cced25d8..ae62a9c8b0 100644 --- a/_docs/tasks/ingress.md +++ b/_docs/tasks/ingress.md @@ -21,6 +21,8 @@ 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,9 +84,26 @@ 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. @@ -81,11 +113,13 @@ 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 .. response .. +$ curl -k https://192.168.99.100:80/hello +.. response .. ``` ## Understanding ...