mirror of https://github.com/istio/istio.io.git
41 lines
22 KiB
HTML
41 lines
22 KiB
HTML
<!DOCTYPE html><html lang="en" itemscope itemtype="https://schema.org/WebPage" style="overflow-y: scroll;"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="title" content="Bookinfo"><meta name="og:title" content="Bookinfo"><meta name="og:image" content="/v0.3/img/logo.png"/><meta name="theme-color" content="#466BB0"/><meta name="description" content="This guide deploys a sample application composed of four separate microservices which will be used to demonstrate various features of the Istio service mesh."><meta name="og:description" content="This guide deploys a sample application composed of four separate microservices which will be used to demonstrate various features of the Istio service mesh."><title>Istioldie 0.3 / Bookinfo</title><script> window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date; ga('create', 'UA-98480406-2', 'auto'); ga('send', 'pageview'); </script> <script async src='https://www.google-analytics.com/analytics.js'></script><link rel="alternate" type="application/rss+xml" title="Istio Blog RSS" href="/v0.3/feed.xml"><link rel="shortcut icon" href="/v0.3/favicons/favicon.ico" ><link rel="apple-touch-icon" href="/v0.3/favicons/apple-touch-icon-180x180.png" sizes="180x180"><link rel="icon" type="image/png" href="/v0.3/favicons/favicon-16x16.png" sizes="16x16"><link rel="icon" type="image/png" href="/v0.3/favicons/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="/v0.3/favicons/android-36x36.png" sizes="36x36"><link rel="icon" type="image/png" href="/v0.3/favicons/android-48x48.png" sizes="48x48"><link rel="icon" type="image/png" href="/v0.3/favicons/android-72x72.png" sizes="72x72"><link rel="icon" type="image/png" href="/v0.3/favicons/android-96x196.png" sizes="96x196"><link rel="icon" type="image/png" href="/v0.3/favicons/android-144x144.png" sizes="144x144"><link rel="icon" type="image/png" href="/v0.3/favicons/android-192x192.png" sizes="192x192"><link rel="manifest" href="/v0.3/manifest.json"><meta name="apple-mobile-web-app-title" content="Istio"><meta name="application-name" content="Istio"><link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:400,100,100italic,300,300italic,400italic,500,500italic,700,700italic,900,900italic"><link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"><link rel="stylesheet" href="/v0.3/css/all.css"><link rel="stylesheet" href="/v0.3/css/prism.css"></head><body class="language-unknown"> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script><div class="nav-hero-container" style="z-index: 200000;"><nav id="header-nav" class="navbar navbar-inverse" role="navigation" style="z-index: 200000;"><div class="container"><div class="row"><div class="col-md-11 nofloat center-block "><div class="navbar-header"> <button type="button" class="hamburger navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-collapse-1" aria-expanded="false"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="/v0.3/"><div> <img src="/v0.3/img/istio-logo.svg" alt="Istio Logo" height="54px"/> <span class="brand-name">Istioldie 0.3</span></div></a></div><div class="collapse navbar-collapse" id="navbar-collapse-1"><ul class="nav navbar-nav navbar-right"><li><a href="/v0.3/about" >About</a></li><li><a href="/v0.3/blog" >Blog</a></li><li><a href="/v0.3/docs/welcome" class='current'>Docs</a></li><li><a href="/v0.3/help" >Help</a></li><li><a href="/v0.3/community" >Community</a></li><li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown" href=""> <i class='fa fa-lg fa-cog'></i> <span class="caret"></span> </a><ul class="dropdown-menu"><h6 class="dropdown-header">Other versions of this site</h6><li> <a href="https://istio.io">Current Release</a></li><li> <a href="https://preliminary.istio.io">Next Release</a></li><li> <a href="https://archive.istio.io">Older Releases</a></li></ul></li><li><form name="cse" id="searchbox_demo" class="navbar-form navbar-right" role="search"> <input type="hidden" name="cx" value="013699703217164175118:iwwf17ikgf4" /> <input type="hidden" name="ie" value="utf-8" /> <input type="hidden" name="hl" value="en" /><div class="form-group"><div class="input-group"> <input name="q" class="form-control search-box" type="text" size="30" /><div class="input-group-addon"> <span class="btn-search glyphicon glyphicon-search"></span></div></div></div></form> <script type="text/javascript" src="https://www.google.com/cse/brand?form=searchbox_demo"></script></li></ul></div></div></div></div></nav></div><div class="container"><div class="row"><div class="col-md-11 nofloat center-block" style="margin-top: 3px;"><ul class="col-sm-10 nav nav-tabs"><li role="presentation" ><a href="/v0.3/docs/welcome/">Welcome</a></li><li role="presentation" ><a href="/v0.3/docs/concepts/">Concepts</a></li><li role="presentation" ><a href="/v0.3/docs/setup/">Setup</a></li><li role="presentation" ><a href="/v0.3/docs/tasks/">Tasks</a></li><li role="presentation" class='active'><a href="/v0.3/docs/guides/">Guides</a></li><li role="presentation" ><a href="/v0.3/docs/reference/">Reference</a></li></ul></div></div></div><script src="/v0.3/js/navtree.min.js"></script><div class="container docs"><div class="row"><div class="col-md-11 nofloat center-block"><div class="row"><div id="sidebar-container" class="col-sm-3"><ul class="doc-side-nav"><li><h5 class='doc-side-nav-title'>Guides</h5></li><script type="text/javascript"> var docs = []; docs.push({path: [ "bookinfo.md", ], url: "/docs/guides/bookinfo.html", title: "Bookinfo", order: 10, overview: "This guide deploys a sample application composed of four separate microservices which will be used to demonstrate various features of the Istio service mesh."}); docs.push({path: [ "index.md", ], url: "/docs/guides/", title: "Guides", order: 30, overview: "Guides include a variety of fully working example uses for Istio that you can experiment with."}); docs.push({path: [ "integrating-vms.md", ], url: "/docs/guides/integrating-vms.html", title: "Integrating Virtual Machines", order: 60, overview: "This sample deploys the Bookinfo services across Kubernetes and a set of virtual machines, and illustrates how to use the Istio service mesh to control this infrastructure as a single mesh."}); docs.push({path: [ "intelligent-routing.md", ], url: "/docs/guides/intelligent-routing.html", title: "Intelligent Routing", order: 20, overview: "This guide demonstrates how to use various traffic management capabilities of an Istio service mesh."}); docs.push({path: [ "telemetry.md", ], url: "/docs/guides/telemetry.html", title: "In-Depth Telemetry", order: 30, overview: "This sample demonstrates how to obtain uniform metrics, logs, traces across different services using Istio Mixer and Istio sidecar."}); genNavBarTree(docs) </script></ul></div><div id="tab-container" class="col-xs-1 tab-neg-margin pull-left"> <a id="sidebar-tab" class="glyphicon glyphicon-chevron-left" href="javascript:void 0;"> </a></div><div id="content-container" class="thin-left-border col-sm-9 markdown"><div id="toc" class="toc"></div><div id="doc-content"><h1>Bookinfo</h1><p>This guide deploys a sample application composed of four separate microservices which will be used to demonstrate various features of the Istio service mesh.</p><h2 id="overview">Overview</h2><p>In this guide we will deploy a simple application that displays information about a book, similar to a single catalog entry of an online book store. Displayed on the page is a description of the book, book details (ISBN, number of pages, and so on), and a few book reviews.</p><p>The BookInfo application is broken into four separate microservices:</p><ul><li><em>productpage</em>. The productpage microservice calls the <em>details</em> and <em>reviews</em> microservices to populate the page.</li><li><em>details</em>. The details microservice contains book information.</li><li><em>reviews</em>. The reviews microservice contains book reviews. It also calls the <em>ratings</em> microservice.</li><li><em>ratings</em>. The ratings microservice contains book ranking information that accompanies a book review.</li></ul><p>There are 3 versions of the reviews microservice:</p><ul><li>Version v1 doesn’t call the ratings service.</li><li>Version v2 calls the ratings service, and displays each rating as 1 to 5 black stars.</li><li>Version v3 calls the ratings service, and displays each rating as 1 to 5 red stars.</li></ul><p>The end-to-end architecture of the application is shown below.</p><figure><img src="./img/bookinfo/noistio.svg" alt="BookInfo Application without Istio" title="BookInfo Application without Istio" /><figcaption>BookInfo Application without Istio</figcaption></figure><p>This application is polyglot, i.e., the microservices are written in different languages. It’s worth noting that these services have no dependencies on Istio, but make an interesting sevice mesh example, particularly because of the multitude of services, languages and versions for the reviews service.</p><h2 id="before-you-begin">Before you begin</h2><p>If you haven’t already done so, setup Istio by following the instructions corresponding to your platform <a href="/v0.3/docs/setup/">installation guide</a>.</p><h2 id="deploying-the-application">Deploying the application</h2><p>To run the sample with Istio requires no changes to the application itself. Instead, we simply need to configure and run the services in an Istio-enabled environment, with Envoy sidecars injected along side each service. The needed commands and configuration vary depending on the runtime environment although in all cases the resulting deployment will look like this:</p><figure><img src="./img/bookinfo/withistio.svg" alt="BookInfo Application" title="BookInfo Application" /><figcaption>BookInfo Application</figcaption></figure><p>All of the microservices will be packaged with an Envoy sidecar that intercepts incoming and outgoing calls for the services, providing the hooks needed to externally control, via the Istio control plane, routing, telemetry collection, and policy enforcement for the application as a whole.</p><p>To start the application, follow the instructions below corresponding to your Istio runtime environment.</p><h3 id="running-on-kubernetes">Running on Kubernetes</h3><blockquote><p>Note: If you use GKE, please ensure your cluster has at least 4 standard GKE nodes. If you use Minikube, please ensure you have at least 4GB RAM.</p></blockquote><ol><li><p>Change directory to the root of the Istio installation directory.</p></li><li><p>Bring up the application containers:</p><p>If you are using <a href="/v0.3/docs/setup/kubernetes/sidecar-injection.html#manual-sidecar-injection">manual sidecar injection</a>, use the folloiwng command instead:</p><pre><code class="language-bash">kubectl apply -f <(istioctl kube-inject -f samples/bookinfo/kube/bookinfo.yaml)
|
||
</code></pre><p>If you are using a cluster with <a href="/v0.3/docs/setup/kubernetes/sidecar-injection.html#automatic-sidecar-injection">automatic sidecar injection</a> enabled, simply deploy the services using <code>kubectl</code>:</p><pre><code class="language-bash">kubectl apply -f samples/bookinfo/kube/bookinfo.yaml
|
||
</code></pre><p>The <code>istioctl kube-inject</code> command is used to manually modify the <code>bookinfo.yaml</code> file before creating the deployments as documented <a href="/v0.3/docs/reference/commands/istioctl.html#istioctl-kube-inject">here</a>.</p><p>Either of the above commands launches all four microservices and creates the gateway ingress resource as illustrated in the above diagram. All 3 versions of the reviews service, v1, v2, and v3, are started.</p><blockquote><p>Note that in a realistic deployment, new versions of a microservice are deployed over time instead of deploying all versions simultaneously.</p></blockquote></li><li><p>Confirm all services and pods are correctly defined and running:</p><pre><code class="language-bash">kubectl get services
|
||
</code></pre><p>which produces the following output:</p><pre><code class="language-bash">NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||
details 10.0.0.31 <none> 9080/TCP 6m
|
||
kubernetes 10.0.0.1 <none> 443/TCP 7d
|
||
productpage 10.0.0.120 <none> 9080/TCP 6m
|
||
ratings 10.0.0.15 <none> 9080/TCP 6m
|
||
reviews 10.0.0.170 <none> 9080/TCP 6m
|
||
</code></pre><p>and</p><pre><code class="language-bash">kubectl get pods
|
||
</code></pre><p>which produces</p><pre><code class="language-bash">NAME READY STATUS RESTARTS AGE
|
||
details-v1-1520924117-48z17 2/2 Running 0 6m
|
||
productpage-v1-560495357-jk1lz 2/2 Running 0 6m
|
||
ratings-v1-734492171-rnr5l 2/2 Running 0 6m
|
||
reviews-v1-874083890-f0qf0 2/2 Running 0 6m
|
||
reviews-v2-1343845940-b34q5 2/2 Running 0 6m
|
||
reviews-v3-1813607990-8ch52 2/2 Running 0 6m
|
||
</code></pre></li></ol><h4 id="determining-the-ingress-ip-and-port">Determining the ingress IP and Port</h4><ol><li><p>If your Kubernetes cluster is running in an environment that supports external load balancers, the IP address of ingress can be obtained by the following command:</p><pre><code class="language-bash">kubectl get ingress -o wide
|
||
</code></pre><p>whose output should be similar to</p><pre><code class="language-bash">NAME HOSTS ADDRESS PORTS AGE
|
||
gateway * 130.211.10.121 80 1d
|
||
</code></pre><p>The address of the ingress service would then be</p><pre><code class="language-bash">export GATEWAY_URL=130.211.10.121:80
|
||
</code></pre></li><li><p><em>GKE:</em> Sometimes when the service is unable to obtain an external IP, <code>kubectl get ingress -o wide</code> may display a list of worker node addresses. In this case, you can use any of the addresses, along with the NodePort, to access the ingress. If the cluster has a firewall, you will also need to create a firewall rule to allow TCP traffic to the NodePort.</p><pre><code class="language-bash">export GATEWAY_URL=<workerNodeAddress>:$(kubectl get svc istio-ingress -n istio-system -o jsonpath='{.spec.ports[0].nodePort}')
|
||
gcloud compute firewall-rules create allow-book --allow tcp:$(kubectl get svc istio-ingress -n istio-system -o jsonpath='{.spec.ports[0].nodePort}')
|
||
</code></pre></li><li><p><em>IBM Cloud Container Service Free Tier:</em> External load balancer is not available for kubernetes clusters in the free tier. You can use the public IP of the worker node, along with the NodePort, to access the ingress. The public IP of the worker node can be obtained from the output of the following command:</p><pre><code class="language-bash">bx cs workers <cluster-name or id>
|
||
export GATEWAY_URL=<public IP of the worker node>:$(kubectl get svc istio-ingress -n istio-system -o jsonpath='{.spec.ports[0].nodePort}')
|
||
</code></pre></li><li><p><em>Minikube:</em> External load balancers are not supported in Minikube. You can use the host IP of the ingress service, along with the NodePort, to access the ingress.</p><pre><code class="language-bash">export GATEWAY_URL=$(kubectl get po -n istio-system -l istio=ingress -n istio-system -o 'jsonpath={.items[0].status.hostIP}'):$(kubectl get svc istio-ingress -n istio-system -n istio-system -o 'jsonpath={.spec.ports[0].nodePort}')
|
||
</code></pre></li></ol><h3 id="running-on-docker-with-consul-or-eureka">Running on Docker with Consul or Eureka</h3><ol><li><p>Change directory to the root of the Istio installation directory.</p></li><li><p>Bring up the application containers.</p><ol><li>To test with Consul, run the following command:<pre><code class="language-bash"> docker-compose -f samples/bookinfo/consul/bookinfo.yaml up -d
|
||
</code></pre></li><li>To test with Eureka, run the following command:<pre><code class="language-bash"> docker-compose -f samples/bookinfo/eureka/bookinfo.yaml up -d
|
||
</code></pre></li></ol></li><li><p>Confirm that all docker containers are running:</p><pre><code class="language-bash">docker ps -a
|
||
</code></pre><blockquote><p>If the Istio Pilot container terminates, re-run the command from the previous step.</p></blockquote></li><li><p>Set the GATEWAY_URL:</p><pre><code class="language-bash">export GATEWAY_URL=localhost:9081
|
||
</code></pre></li></ol><h2 id="whats-next">What’s next</h2><p>To confirm that the BookInfo application is running, run the following <code>curl</code> command:</p><pre><code class="language-bash">curl -o /dev/null -s -w "%{http_code}\n" http://${GATEWAY_URL}/productpage
|
||
</code></pre><pre><code class="language-bash">200
|
||
</code></pre><p>You can also point your browser to <code>http://$GATEWAY_URL/productpage</code> to view the Bookinfo web page. If you refresh the page several times, you should see different versions of reviews shown in productpage, presented in a round robin style (red stars, black stars, no stars), since we haven’t yet used Istio to control the version routing.</p><p>You can now use this sample to experiment with Istio’s features for traffic routing, fault injection, rate limitting, etc.. To proceed, refer to one or more of the <a href="/v0.3/docs/guides">Istio Guides</a>, depending on your interest. <a href="/v0.3/docs/guides/intelligent-routing.html">Intelligent Routing</a> is a good place to start for beginners.</p><h2 id="cleanup">Cleanup</h2><p>When you’re finished experimenting with the BookInfo sample, you can uninstall and clean it up using the following instructions.</p><h3 id="uninstall-from-kubernetes-environment">Uninstall from Kubernetes environment</h3><ol><li><p>Delete the routing rules and terminate the application pods</p><pre><code class="language-bash">samples/bookinfo/kube/cleanup.sh
|
||
</code></pre></li><li><p>Confirm shutdown</p><pre><code class="language-bash">istioctl get routerules #-- there should be no more routing rules
|
||
kubectl get pods #-- the BookInfo pods should be deleted
|
||
</code></pre></li></ol><h3 id="uninstall-from-docker-environment">Uninstall from Docker environment</h3><ol><li><p>Delete the routing rules and application containers</p><ol><li>In a Consul setup, run the following command:</li></ol><pre><code class="language-bash">samples/bookinfo/consul/cleanup.sh
|
||
</code></pre><ol><li>In a Eureka setup, run the following command:</li></ol><pre><code class="language-bash">samples/bookinfo/eureka/cleanup.sh
|
||
</code></pre></li><li><p>Confirm cleanup</p><pre><code class="language-bash">istioctl get routerules #-- there should be no more routing rules
|
||
docker ps -a #-- the BookInfo containers should be deleted
|
||
</code></pre></li></ol></div></div></div></div></div></div><script src="/v0.3/js/sidemenu.min.js"></script><footer><div class="container"><div class="row"><div class="col-lg-2 col-md-2 col-sm-2"></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li><a class="header" href="/v0.3/docs/welcome">Docs</a></li><li><a href="/v0.3/docs/concepts">Concepts</a></li><li><a href="/v0.3/docs/setup">Setup</a></li><li><a href="/v0.3/docs/tasks">Tasks</a></li><li><a href="/v0.3/docs/guides">Guides</a></li><li><a href="/v0.3/docs/reference">Reference</a></li></ul></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li><a class="header" href="/v0.3/help">Help</a></li><li><a href="/v0.3/faq">FAQ</a></li><li><a href="/v0.3/glossary">Glossary</a></li><li><a href="/v0.3/troubleshooting">Troubleshooting</a></li><li><a href="/v0.3/bugs">Report Bugs</a></li><li><a href="https://github.com/istio/istio.github.io/issues/new?title=Issue with _docs/guides/bookinfo.md">Doc Bugs & Gaps</a></li><li><a href="https://github.com/istio/istio.github.io/edit/master/_docs/guides/bookinfo.md">Edit This Page</a></li></ul></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li> <a class="header" href="/v0.3/community">Community</a></li><li> <a href="https://groups.google.com/forum/#!forum/istio-users" target="_blank" rel="noopener">User</a> | <a href="https://groups.google.com/forum/#!forum/istio-dev" target="_blank" rel="noopener">Dev Mailing Lists</a></li><li><a href="https://twitter.com/IstioMesh" target="_blank" rel="noopener">Twitter</a></li><li><a href="https://stackoverflow.com/questions/tagged/istio" target="_blank" rel="noopener">Stack Overflow</a></li><li><a href="https://github.com/istio/community" target="_blank" rel="noopener">GitHub</a></li><li><a href="https://github.com/istio/community/blob/master/WORKING-GROUPS.md" target="_blank" rel="noopener">Working Groups</a></li></ul></div><div class="col-lg-1 col-md-1 col-sm-1"></div></div><div class="row"><p class="description small text-center"> Istio 0.3, Copyright © 2017 Istio Authors<br> Archived on 08-Dec-2017</p></div></div></footer><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-validate/1.15.0/jquery.validate.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.form/4.2.1/jquery.form.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-visible/1.2.0/jquery.visible.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/slick-carousel/1.6.0/slick.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script> <script src="/v0.3/js/common.min.js"></script> <script src="/v0.3/js/search.js"></script> <script src="/v0.3/js/prism.min.js"></script></body></html>
|