[WIP] Tutorial #1035
[WIP] Tutorial #1035
Conversation
|
So I think this is great stuff! This is straight forward enough and directly works with bookinfo that i think moving it to istio/contrib or somewhere in the istio repo makes sense. I'd be happy to contribute to it also. One observation: On this step (https://github.com/vadimeisenbergibm/introduction-to-microservices-with-istio-bookinfo/tree/master/modules/06-add-istio-and-redeploy-bookinfo) we undeploy bookinfo and redeploy with istio Wonder if there's an opportunity to show how to gradually phase in istio to an existing application? |
We should weigh the tradeoff of making the tutorial more complicated vs. showing more features. I presented this tutorial yesterday, and this was the question I was asked at this step - do we have to redeploy the whole Bookinfo app? Can we do it gradually? The tutorial took two hours, with discussions and questions at each step. I think it is actually a good idea, thanks! In the modules 07-09 and 11, it seems only productpage should be Istio enabled to route to reviews v1, v2 and v3. I will rewrite the module 06 to redeploy only the productpage. |
|
@christian-posta and we also can consider to add an Advanced Tutorial section, to add more modules to demonstrate more Istio features in the same style. You are very welcome to contribute. |
|
@christian-posta @vadimeisenbergibm I agree, that is a great idea to show how to move some services into the mesh while the others are outside of the mesh. I would be fine to have this in another tutorial tho so this one focus on introduce the value of Istio. @vadimeisenbergibm really good work here! |
|
This is very nice. What would you think about making this a top-level section in our docs? That is, adding a Tutorial section as a sibling of Tasks and Guides? Each module could be a separate page, and the YAML files would be in istio/istio/tutorial |
@geeknoid Sounds perfect! Let me do it. |
|
Let me know if you need help to add the Tutorial section. It should mostly
'just work' just by adding the directory under _docs.
…On Tue, Feb 27, 2018 at 8:51 AM Vadim Eisenberg ***@***.***> wrote:
What would you think about making this a top-level section in our docs?
That is, adding a Tutorial section as a sibling of Tasks and Guides? Each
module could be a separate page, and the YAML files would be in
istio/istio/tutorial
@geeknoid <https://github.com/geeknoid> Sounds perfect! Let me do it.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#1035 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AVucHSMYKQusQ34UOGjIvQtcZ1K-ZFOhks5tZDJ5gaJpZM4STdGK>
.
|
|
@geeknoid yes, will do, thanks. |
for the Istio tutorial to be published - istio/istio.io#1035
_docs/tutorial/00-setup.md
Outdated
| --- | ||
| {% include home.html %} | ||
|
|
||
| # Introduction to microservices with Bookinfo sample application, Kubernetes and Istio |
There was a problem hiding this comment.
Don't add any single # titles, the website infra automatically takes the title: and inserts a level 1 heading with it.
_docs/tutorial/00-setup.md
Outdated
|
|
||
| 1. Download Istio and Bookinfo source: | ||
| ```bash | ||
| make setup |
There was a problem hiding this comment.
Maybe include the git clone + cd commands?
_docs/tutorial/00-setup.md
Outdated
| ```bash | ||
| alias istioctl=$(pwd)/istio-*/bin/istioctl | ||
| ``` | ||
| 2. Go over `modules`, by their prefix number, issuing `cd` to each modules's directory. |
There was a problem hiding this comment.
How about adding a Previous/Next links at the bottom of each page? Something like:
## What's next
* Next Module: <title of next module>
* Previous Module: <title of previous module>
_docs/tutorial/01-ratings-service.md
Outdated
| npm start 9080 | ||
| ``` | ||
|
|
||
| 1. Access http://localhost:9080/ratings/7 |
There was a problem hiding this comment.
Here and elsewhere, maybe show a curl command?
| @@ -0,0 +1,37 @@ | |||
| --- | |||
| title: Run ratings in docker | |||
| istioctl create -f ../../istio-*/samples/bookinfo/kube/route-rule-reviews-test-v2.yaml | ||
| ``` | ||
|
|
||
| 5. Let's login as `jason` (any password would do). We will see that now the reviews have black stars (our new version is used). Now we can let a human tester or a testing tool test our new version on the whole application |
| @@ -0,0 +1,51 @@ | |||
| --- | |||
| title: Enable istio on all the microservices | |||
| overview: Overview | |||
There was a problem hiding this comment.
Here and elsewhere: needs an overview.
This overview is displayed when you hover over the title of the article in the left-hand nav area.
| layout: docs | ||
| type: markdown | ||
| --- | ||
| {% include home.html %}\n# In this module we will enable Istio on our whole application and on the Ingress. |
There was a problem hiding this comment.
Here and elsewhere, remove \n#
|
|
||
| Previously we deployed the Istio control plane and enabled Istio on a single microservice, _productpage_. We can proceed to enable Istio on the microservices incrementally, one by one, to get the functionality provided by Istio for more and more microservices. For the purpose of this tutorial, we will just enable Istio on the remaining microservices in one stroke. We will also enable Istio on our pod that we use for testing. | ||
|
|
||
| 1. Redeploy Bookinfo application, Istio-enabled. _productpage_ will not be redeployed since it already has Istio injected, its pods will not be changed. |
|
|
||
| 1. Access the application after determining Ingress IP and port. Note that Istio was added **transparently**, the original application did not change. It was added on the fly, without the need to undeploy and redeploy the whole application, without hurting the application's availability. | ||
|
|
||
| 2. Check the application pods and verify that now each pod has two containers. One container is the microservice itself, the other is the sidecar proxy attached to it. |
There was a problem hiding this comment.
Show command with sample output?
|
can you refactor rather than copy/clone the existing samples; it'll be a maintenance nightmare |
|
@ldemailly I cannot refactor the existing tasks since the tasks serve the different purposes from the tutorial. In my opinion, both the tasks and the tutorial are needed. I explained the differences in the first comment of the PR:
|
|
this looks great btw, what's the preview link ? also what's the conclusion on blog vs tutorial vs tasks vs guides - I think we should not have a new top level but maybe we can rename guides to tutorials or some such |
|
@ldemailly let me finalize it and publish a link. @geeknoid proposed to have a new top level - Tutorial. I would like us to decide on the guidelines: Tasks vs. Guides vs. Blog vs. Tutorial. I do not know how we should proceed. |
|
@ldemailly I don't think that we should merge guides and tutorials, since they serve different purposes. Guides are supposed to just be recommended "guided views" through tasks (i.e., do task a, then b, then c to understand some feature of Istio). This tutorial, on the other hand, is a complete standalone learning exercise. |
|
sgtm so do you want to move this out of a blog ? I am assuming it would show up here on the left with others as new sub-toplevel under docs? |
|
@ldemailly @geeknoid @frankbu @christian-posta @linsun @ZackButcher please check Tutorial at https://vadimeisenbergibm.github.io/docs/ Your comments are welcome. |
_docs/tutorial/00-setup.md
Outdated
|
|
||
| 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), [curl](https://curl.haxx.se/download.html), [node.js](https://nodejs.org/en/download/), [Docker](https://docs.docker.com/install/) | ||
| and get access to a [Kubernetes](https://kubernetes.io) cluster. | ||
| For example, you can try the [IBM Cloud Container Service](https://console.bluemix.net/docs/containers/container_index.html#container_index). |
There was a problem hiding this comment.
should we put all or none of the providers ? or the main contributor's providers (ie both GCP and IBM)?
There was a problem hiding this comment.
I propose that we start with this PR with IBM. Then we add all other providers as separate PRs, by the provider people. If you think we should add GCP right now, please submit a PR to my branch with GCP instructions.
_docs/tutorial/00-setup.md
Outdated
|
|
||
| 1. This tutorial assumes that you perform the commands of the steps in the Istio directory that you downloaded and extracted in the steps 1 and 2 of the [Installation Steps of the Kubernetes Quick Start instructions]({{home}}/docs/setup/kubernetes/quick-start.html#installation-steps). | ||
|
|
||
| 1. Download Istio sources into the Istio directory. **Note** that Istio source code is under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license. |
There was a problem hiding this comment.
Why are the sources needed? It should work with just the release tgz
the review of the sources could just be links into github
I don't think "git clone..." should be part of user facing instructions - it can only lead to issue with mismatch between release version and state of master etc
the install istio step for instance will not work from source
There was a problem hiding this comment.
Good point. The sources are needed for the only one reason: to run ratings as a node.js application, and as a Docker container. So basically, only https://github.com/istio/istio/tree/master/samples/bookinfo/src/ratings is needed. I will instruct the users to download the source code from https://github.com/istio/istio/releases, so the source code will always match the release.
There was a problem hiding this comment.
or you could just point them to https://github.com/istio/istio/blob/master/samples/bookinfo/src/ratings/ratings.js as it's just one file ?
or wget -r https://github.com/istio/istio/blob/master/samples/bookinfo/src/ratings/
if you also want the Dockerfile etc (why would you ?)
There was a problem hiding this comment.
I changed the setup to instruct to download the sources from https://github.com/istio/istio/releases, please check.
The sources are already packaged there, they match the release, no need to install wget.
I need the Docker file for the step 2, Running a single microservice in a Docker container.
|
also please update your branch and run "rake test" / fix bad links (martin made using {{home}} instead of / mandatory for the https://archive.istio.io/ sites to work well. you can use relative links instead if you want) |
_docs/tutorial/00-setup.md
Outdated
|
|
||
| 1. This tutorial assumes that you perform the commands of the steps in the Istio directory that you downloaded and extracted in the steps 1 and 2 of the [Installation Steps of the Kubernetes Quick Start instructions]({{home}}/docs/setup/kubernetes/quick-start.html#installation-steps). | ||
|
|
||
| 1. Download Istio sources from [https://github.com/istio/istio/releases](https://github.com/istio/istio/releases). **Note** that Istio source code is under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license. Uncompress the sources into `istio_sources` directory inside the Istio directory (see the previous list item). |
There was a problem hiding this comment.
add "matching your binary release version" ?
_docs/tutorial/00-setup.md
Outdated
|
|
||
| 1. This tutorial assumes that you perform the commands of the steps in the Istio directory that you downloaded and extracted in the steps 1 and 2 of the [Installation Steps of the Kubernetes Quick Start instructions]({{home}}/docs/setup/kubernetes/quick-start.html#installation-steps). | ||
|
|
||
| 1. Download Istio sources matching your Istio release version from [https://github.com/istio/istio/releases](https://github.com/istio/istio/releases). **Note** that Istio source code is under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license. Uncompress the sources into `istio_sources` directory inside the Istio directory (see the previous list item). |
There was a problem hiding this comment.
I would remove the note about the Apache license, this is not necessary.
_docs/tutorial/index.md
Outdated
|
|
||
| The ideas and scenarios were taken from the [Production-Ready Microservices](http://shop.oreilly.com/product/0636920053675.do) book of Susan Fowler and from the [istio.io]({{home}}) [guides]({{home}}/docs/guides), [tasks]({{home}}/docs/tasks) and [the istio.io blog]({{home}}/blog). | ||
|
|
||
| If you are not yet familiar with the microservices concept, [the article of James Lewis and Martin Fowler](https://martinfowler.com/articles/microservices.html) is a good place to start. |
_docs/tutorial/00-setup.md
Outdated
| ``` | ||
|
|
||
| ## What's next | ||
| {% if page.next.url %} |
There was a problem hiding this comment.
The conditional is not needed here.
_docs/tutorial/01-ratings-service.md
Outdated
|
|
||
| This step demonstrates the work on a single microservice, on a local developer machine. The microservice is written in node.js and is a small web app on its own. Being a web app, it listens to a port, expects for HTTP GET requests on the path `/ratings/{productID}` and returns the product ratings by the reviewers. | ||
|
|
||
| 1. Review the code of the service. Note the "embedded" Web Server and the aspects related to HTTP, such as the headers, the path, the status code. |
There was a problem hiding this comment.
the code of the service -> the service's code
| @@ -0,0 +1,39 @@ | |||
| --- | |||
| title: Run Bookinfo with Kubernetes | |||
| overview: Deploy Bookinfo application that uses the ratings microservice in Kubernetes. | |||
| kubectl port-forward -n istio-system $(kubectl get pod -n istio-system -l app=zipkin -o jsonpath='{.items[0].metadata.name}') 9411:9411 & | ||
| ``` | ||
|
|
||
| 3. Access the Zipkin dashboard on local machine: http://localhost:9411 |
| ```bash | ||
| kubectl apply -f install/kubernetes/addons/servicegraph.yaml | ||
| ``` | ||
| 2. Check the pods at istio-system namespaces and wait for the pod of Zipkin to start running: |
There was a problem hiding this comment.
pod of Zipkin -> Servicegraph's pod
|
|
||
| ``` | ||
|
|
||
| 3. Access the generated service graph on the local machine: http://localhost:8088/dotviz |
_docs/tutorial/98-summary.md
Outdated
| @@ -0,0 +1,27 @@ | |||
| --- | |||
| title: Summary | |||
| overview: Tutorial summary and the next steps. | |||
_docs/tutorial/99-cleanup.md
Outdated
| ``` | ||
|
|
||
| ## What's next | ||
| {% if page.previous.url %} |
There was a problem hiding this comment.
No need for the conditional.
1. replace Kiali images 2. rewrite the description of Kiali images (the services turned orange and not red, no errors appear on the right tab 3. remove Jaeger since only two spans are shown 4. add final access to the application's webpage to show that the errors disappear, though there is slight delay (injected)
…RBAC change the Kubernetes RBAC to use security.istio.io instead of rbac.istio.io
that creates v-unavailable deployment and a destination rule for it
since the minimal interval is now 10s in Kiali
|
@vadimeisenbergibm: The following test failed, say
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here. |
this is to enable working without Istio ingress gateway
|
🚧 This issue or pull request has been closed due to not having had activity from an Istio team member since 2019-06-04. If you feel this issue or pull request deserves attention, please reopen the issue. Please see this wiki page for more information. Thank you for your contributions. Created by the issue and PR lifecycle manager. |
The tutorial is different from the set of tasks/examples at istio.io in the following way:
I taught this tutorial in a class with 17 participants, it took about 8 hours net time. Currently it contains 26 modules, not counting introduction/setup/cleanup/summary. It can be previewed here.