{"id":18429043,"url":"https://github.com/openliberty/guide-istio-intro","last_synced_at":"2025-04-07T17:32:22.642Z","repository":{"id":41588849,"uuid":"129763596","full_name":"OpenLiberty/guide-istio-intro","owner":"OpenLiberty","description":"A guide on how to manage microservice traffic with Istio using blue-green deployment as an example: https://openliberty.io/guides/istio-intro.html","archived":false,"fork":false,"pushed_at":"2025-03-04T16:31:21.000Z","size":529,"stargazers_count":8,"open_issues_count":0,"forks_count":10,"subscribers_count":5,"default_branch":"prod","last_synced_at":"2025-03-22T21:51:07.611Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenLiberty.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-16T15:16:41.000Z","updated_at":"2025-03-04T16:31:26.000Z","dependencies_parsed_at":"2024-02-20T16:02:16.687Z","dependency_job_id":"2c5a253a-bd31-4515-a439-4172fe9898af","html_url":"https://github.com/OpenLiberty/guide-istio-intro","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fguide-istio-intro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fguide-istio-intro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fguide-istio-intro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fguide-istio-intro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenLiberty","download_url":"https://codeload.github.com/OpenLiberty/guide-istio-intro/tar.gz/refs/heads/prod","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247697888,"owners_count":20981267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T05:15:35.755Z","updated_at":"2025-04-07T17:32:22.634Z","avatar_url":"https://github.com/OpenLiberty.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"// INSTRUCTION: Please remove all comments that start INSTRUCTION prior to commit. Most comments should be removed, although not the copyright.\n// INSTRUCTION: The copyright statement must appear at the top of the file\n//\n// Copyright (c) 2017, 2025 IBM Corporation and others.\n// Licensed under Creative Commons Attribution-NoDerivatives\n// 4.0 International (CC BY-ND 4.0)\n//   https://creativecommons.org/licenses/by-nd/4.0/\n//\n// Contributors:\n//     IBM Corporation\n//\n:projectid: istio-intro\n:page-layout: guide-multipane\n:page-duration: 30 minutes\n:page-releasedate: 2019-02-01\n:page-description: Explore how to manage microservice traffic using Istio.\n:page-tags: ['kubernetes', 'docker']\n:page-permalink: /guides/{projectid}\n:page-related-guides: ['docker', 'kubernetes-intro', 'kubernetes-microprofile-config', 'kubernetes-microprofile-health']\n:common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/prod\n:source-highlighter: prettify\n:page-seo-title: Managing traffic in Java microservices using Istio\n:page-seo-description: A getting started tutorial on how to manage Java microservice traffic with an Istio service mesh using Kubernetes blue-green deployment as an example.\n:guide-author: Open Liberty\n= Managing microservice traffic using Istio\n\n[.hidden]\nNOTE: This repository contains the guide documentation source. To view the guide in published form, view it on the https://openliberty.io/guides/{projectid}.html[Open Liberty website].\n\nExplore how to manage microservice traffic using Istio.\n\n:kube: Kubernetes\n:istio: Istio\n:win: WINDOWS\n:mac: MAC\n:linux: LINUX\n:docker: Docker\n:minikube: Minikube\n:maven: Maven\n\n\n== What you'll learn\n\nYou will learn how to deploy an application to a Kubernetes cluster and enable {istio} on it. You will also learn how to configure\n{istio} to shift traffic to implement blue-green deployments for microservices.\n\n=== What is {istio}?\n\nhttps://istio.io/[{istio}^] is a service mesh, meaning that it's a platform for managing\nhow microservices interact with each other and the outside world.\n{istio} consists of a control plane and sidecars that are injected into application pods. The sidecars contain\nthe https://www.envoyproxy.io/[Envoy^] proxy. You can think of Envoy as a sidecar that intercepts\nand controls all the HTTP and TCP traffic to and from your container.\n\nWhile {istio} runs on top of {kube} and that will be the focus of this guide, you can also use {istio} with\nother environments such as https://docs.docker.com/compose/overview/[Docker Compose^]. {istio} has many features such as\ntraffic shifting, request routing, access control, and distributed tracing, but the focus of this guide will be on traffic shifting.\n\n=== Why {istio}?\n\n{istio} provides a collection of features that allows you to manage several aspects of your services.\nOne example is {istio}'s routing features. You can route HTTP requests based on several factors such as HTTP headers or cookies.\nAnother use case for {istio} is telemetry, which you can use to enable distributed tracing. Distributed tracing allows you\nto visualize how HTTP requests travel between different services in your cluster by using a tool such as https://www.jaegertracing.io/[Jaeger^].\nAdditionally, as part of its collection of security features, {istio} allows you to enable mutual TLS between pods in your cluster.\nEnabling TLS between pods secures communication between microservices internally.\n\nhttps://openliberty.io/guides/istio-intro.html#what-are-blue-green-deployments[Blue-green deployments] are a method of deploying your applications such that you have two nearly identical environments where one acts\nas a sort of staging environment and the other is a production environment. This allows you to switch traffic from staging to production\nonce a new version of your application has been verified to work.\nYou'll use {istio} to implement blue-green deployments. The traffic shifting feature allows you to allocate a percentage of\ntraffic to certain versions of services. You can use this feature to shift 100 percent of live traffic to blue deployments and 100 percent\nof test traffic to green deployments. Then, you can shift the traffic to point to the opposite deployments as necessary to\nperform blue-green deployments.\n\nThe microservice you'll deploy is called `system`.\nIt responds with your current system's JVM properties and it returns the app version in the response header.\nYou will increment the version number when you update the application.\nWith this number, you can determine which version of the microservice is running in your production or test environments.\n\n=== What are blue-green deployments?\n\nBlue-green deployments are a way of deploying your applications such that you have two environments where your application runs.\nIn this scenario, you will have a production environment and a test environment.\nAt any point in time, the blue deployment can accept production traffic and the green deployment can accept test traffic, or vice versa.\nWhen you want to deploy a new version of your application, you deploy to the color that is acting as your test environment.\nAfter the new version is verified on the test environment, the traffic is shifted over.\nThus, your live traffic is now being handled by what used to be the test site.\n\n// =================================================================================================\n// Prerequisites\n// =================================================================================================\n\ninclude::{common-includes}/kube-prereq.adoc[]\n\n// =================================================================================================\n// Getting Started\n// =================================================================================================\n\n[role=command]\ninclude::{common-includes}/gitclone.adoc[]\n\n// no \"try what you'll build\" section in this guide because it would be too long due to all setup the user will have to do.\n\n// =================================================================================================\n// Staring and preparing your cluster for deployment\n// =================================================================================================\n// visit https://cdn.dl.k8s.io/release/stable.txt to get the latest stable version\n\n:minikube-start: minikube start --memory=8192 --cpus=4\n:docker-desktop-description: Check your settings to ensure that you have an adequate amount of memory allocated to your Docker Desktop enviornment, 8GB is recommended but 4GB should be adequate if you don't have enough RAM.\n:minikube-description: The memory flag allocates 8GB of memory to your Minikube cluster. If you don't have enough RAM, then 4GB should be adequate.\n[role=command]\ninclude::{common-includes}/kube-start.adoc[]\n\n// =================================================================================================\n// Deploying Istio\n// =================================================================================================\n\ninclude::{common-includes}/istio-start.adoc[]\n// =================================================================================================\n// Deploying v1\n// =================================================================================================\n\n== Deploying version 1 of the system microservice\n\nNavigate to the `guide-{projectid}/start` directory and run the following command to build the application locally.\n[role=command]\n```\nmvn clean package\n```\n\n\n\nNext, run the `docker build` commands to build the container image for your application:\n[role='command']\n```\ndocker build -t system:1.0-SNAPSHOT .\n```\n\nThe command builds a {docker} image for the `system` microservice.\nThe `-t` flag in the `docker build` command allows the Docker image to be labeled (tagged) in the `name[:tag]` format.\nThe tag for an image describes the specific image version.\nIf the optional `[:tag]` tag is not specified, the `latest` tag is created by default.\nYou can verify that this image was created by running the following command: \n\n[role=command]\n```\ndocker images\n```\n\nYou'll see an image called `system:1.0-SNAPSHOT` listed in a table similar to the output.\n\n[source, role=\"no_copy\"]\n----\nREPOSITORY                     TAG                              IMAGE ID        CREATED          SIZE\nsystem                         1.0-SNAPSHOT                     8856039f4c42    9 minutes ago    745MB\nistio/proxyv2                  1.24.2                           7a3aaffcf645    3 weeks ago      347MB\nistio/pilot                    1.24.2                           4974b5b22dcc    3 weeks ago      261MB\nicr.io/appcafe/open-liberty    kernel-slim-java11-openj9-ubi    d6ef646493e1    8 days ago       729MB\n----\n\nTo deploy the `system` microservice to the {kube} cluster, use the following command to deploy the microservice.\n\n[role=command]\n```\nkubectl apply -f system.yaml\n```\n\nYou can see that your resources are created:\n\n[source, role=\"no_copy\"]\n----\ngateway.networking.istio.io/sys-app-gateway created\nservice/system-service created\ndeployment.apps/system-deployment-blue created\ndeployment.apps/system-deployment-green created\ndestinationrule.networking.istio.io/system-destination-rule created\n----\n\nsystem.yaml\n[source, yaml, linenums, role='code_column no_copy']\n----\ninclude::finish/system.yaml[tags=**;]\n----\n\nView the [hotspot file=0]`system.yaml` file. It contains two [hotspot=30-72 file=0]`deployments`, a [hotspot=17-28 file=0]`service`, a [hotspot=1-15 file=0]`gateway`, and a [hotspot=74-87 file=0]`destination rule`. One of the deployments is labeled [hotspot=33 hotspot=39 hotspot=44 file=0]`blue` and the second deployment is labeled [hotspot=55 hotspot=61 hotspot=66 file=0]`green`. The service points to both of these deployments. The {istio} gateway is the entry point for HTTP requests to the cluster. A destination rule is used to apply policies post-routing, in this situation it is used to define service subsets that can be specifically routed to.\n\ntraffic.yaml\n[source, yaml, linenums, role='code_column no_copy']\n----\ninclude::start/traffic.yaml[tags=**;]\n----\n\nView the [hotspot file=1]`traffic.yaml` file. It contains two virtual services. A virtual service defines how requests are routed to your applications. In the virtual services, you can configure the weight, which controls the amount of traffic going to each deployment. In this case, the weights should be 100 or 0, which corresponds to which deployment is live.\n\nDeploy the resources defined in the `traffic.yaml` file.\n\n[role=command]\n```\nkubectl apply -f traffic.yaml\n```\n\nYou can see that the virtual services have been created.\n\n[source, role=\"no_copy\"]\n----\nvirtualservice.networking.istio.io/system-virtual-service created\nvirtualservice.networking.istio.io/system-test-virtual-service created\n----\n\nYou can check that all of the deployments are available by running the following command.\n\n[role=command]\n```\nkubectl get deployments\n```\n\nThe command produces a list of deployments for your microservices that is similar to the following output.\n\n[source, role=\"no_copy\"]\n----\nNAME                     DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE\nsystem-deployment-blue    1         1         1            1           1m\nsystem-deployment-green   1         1         1            1           1m\n----\n\nAfter all the deployments are available, you will make a request to version 1 of the deployed application. As defined in the [hotspot file=0]`system.yaml`, file the [hotspot=1-15 file=0]`gateway` is expecting the host to be `example.com`. However, requests to `example.com` won't be routed to the appropriate IP address. To ensure that the gateway routes your requests appropriately, ensure that the Host header is set to `example.com`. For instance, you can set the `Host` header with the `-H` option of the `curl` command.\n\n\nMake a request to the service by running the following `curl` command.\n\ninclude::{common-includes}/os-tabs.adoc[]\n\n[.tab_content.windows_section]\n--\n[role=command]\n```\ncurl -H \"Host:example.com\" -I http://localhost/system/properties\n```\nIf the `curl` command is unavailable, then use https://www.getpostman.com/[Postman^]. Postman enables you\nto make requests using a graphical interface. To make a request with Postman, enter `\\http://localhost/system/properties`\ninto the URL bar. Next, switch to the `Headers` tab and add a header with key of `Host` and value of `example.com`.\nFinally, click the blue `Send` button to make the request.\n--\n\n[.tab_content.mac_section]\n--\n[role=command]\n```\ncurl -H \"Host:example.com\" -I http://localhost/system/properties\n```\nIf the `curl` command is unavailable, then use https://www.getpostman.com/[Postman^]. Postman enables you\nto make requests using a graphical interface. To make a request with Postman, enter `\\http://localhost/system/properties`\ninto the URL bar. Next, switch to the `Headers` tab and add a header with key of `Host` and value of `example.com`.\nFinally, click the blue `Send` button to make the request.\n--\n\n[.tab_content.linux_section]\n--\n[role=command]\n```\nexport INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name==\"http2\")].nodePort}')\ncurl -H \"Host:example.com\" -I http://`minikube ip`:$INGRESS_PORT/system/properties\n```\n--\n\n\nYou'll see a header called `x-app-version` along with the corresponding version.\n\n[source, role=\"no_copy\"]\n----\nx-app-version: 1.0-SNAPSHOT\n----\n\n// =================================================================================================\n// Deploy v2\n// =================================================================================================\n\n== Deploying version 2 of the system microservice\n\n[role=\"code_command hotspot file=0\", subs=\"quotes\"]\n----\n#Replace the `SystemResource` class.#\n`src/main/java/io/openliberty/guides/system/SystemResource.java`\n----\n\nSystemResource.java\n[source, Java, linenums, role='code_column hide_tags=copyright']\n----\ninclude::finish/src/main/java/io/openliberty/guides/system/SystemResource.java[]\n----\n\nThe `system` microservice is set up to respond with the version that is set in the `SystemResource.java` file.\nThe tag for the {docker} image is also dependent on the version that is specified in the `SystemResource.java` file.\nManually update the [hotspot=version]`APP_VERSION` field of the microservice to `2.0-SNAPSHOT`.\n\nUse Maven to repackage your microservice:\n[role=command]\n```\nmvn clean package\n```\n\nNext, build the new version of the container image as `2.0-SNAPSHOT`:\n[role=command]\n```\ndocker build -t system:2.0-SNAPSHOT .\n```\n\nDeploy the new image to the green deployment.\n\n[role=command]\n```\nkubectl set image deployment/system-deployment-green system-container=system:2.0-SNAPSHOT\n```\n\nYou will work with two environments.\nOne of the environments is a test site that is located at `test.example.com`.\nThe other environment is your production environment that is located at `example.com`.\nTo begin with, the production environment is tied to the blue deployment and the test environment is tied to the green deployment.\n\nTest the updated microservice by making requests to the test site.\nThe `x-app-version` header now has a value of `2.0-SNAPSHOT` on the test site and is still `1.0-SNAPSHOT` on the live site.\n\nMake a request to the service by running the following `curl` command.\n\ninclude::{common-includes}/os-tabs.adoc[]\n\n[.tab_content.windows_section.mac_section]\n--\n[role=command]\n```\ncurl -H \"Host:test.example.com\" -I http://localhost/system/properties\n```\nIf the `curl` command is unavailable, then use https://www.getpostman.com/[Postman^].\n--\n\n[.tab_content.linux_section]\n--\n//Make a request to the service by using `curl`.\n[role=command]\n```\ncurl -H \"Host:test.example.com\" -I http://`minikube ip`:$INGRESS_PORT/system/properties\n```\n--\n\nYou'll see the new version in the `x-app-version` response header.\n\n[source, role=\"no_copy\"]\n----\nx-app-version: 2.0-SNAPSHOT\n----\n\n[role=\"code_command hotspot file=1\", subs=\"quotes\"]\n----\n#Update the `traffic.yaml` file in the `start` directory.#\n`traffic.yaml`\n----\n\ntraffic.yaml\n[source, yaml, linenums, role='code_column', file=1]\n----\ninclude::finish/traffic.yaml[tags=**;]\n----\n\n[role=\"edit_command_text\"]\nAfter you see that the microservice is working on the test site, modify the [hotspot=17 hotspot=23 hotspot=41 hotspot=47 file=1]`weights` in the `traffic.yaml` file to shift 100 percent of the `example.com` traffic to the green deployment, and 100 percent of the `test.example.com` traffic to the blue deployment.\n\n\nDeploy the updated `traffic.yaml` file.\n\n[role=command]\n```\nkubectl apply -f traffic.yaml\n```\n\nEnsure that the live traffic is now being routed to version 2 of the microservice.\n\n\nMake a request to the service by running the following `curl` command.\n\ninclude::{common-includes}/os-tabs.adoc[]\n\n[.tab_content.windows_section]\n--\n[role=command]\n```\ncurl -H \"Host:example.com\" -I http://localhost/system/properties\n```\nIf the `curl` command is unavailable, then use https://www.getpostman.com/[Postman^].\n--\n\n[.tab_content.mac_section]\n--\n[role=command]\n```\ncurl -H \"Host:example.com\" -I http://localhost/system/properties\n```\nIf the `curl` command is unavailable, then use https://www.getpostman.com/[Postman^].\n--\n\n[.tab_content.linux_section]\n--\n[role=command]\n```\ncurl -H \"Host:example.com\" -I http://`minikube ip`:$INGRESS_PORT/system/properties\n```\n--\n\n\nYou'll see the new version in the `x-app-version` response header.\n\n[source, role=\"no_copy\"]\n----\nx-app-version: 2.0-SNAPSHOT\n----\n\n== Testing microservices that are running on {kube}\n\nNext, you will create a test to verify that the correct version of your microservice is running.\n\n[role=\"code_command hotspot\", subs=\"quotes\"]\n----\n#Create the `SystemEndpointIT` class.#\n`src/test/java/it/io/openliberty/guides/system/SystemEndpointIT.java`\n----\nSystemEndpointIT.java\n[source, Java, linenums, role='code_column hide_tags=copyright']\n----\ninclude::finish/src/test/java/it/io/openliberty/guides/system/SystemEndpointIT.java[]\n----\n\nThe [hotspot=testAppVersion]`testAppVersion()` test case verifies that the correct version number is returned in the response headers.\n\nRun the following commands to compile and start the tests:\n\ninclude::{common-includes}/os-tabs.adoc[]\n\n[.tab_content.windows_section.mac_section]\n--\n[role=command]\n```\nmvn test-compile\nmvn failsafe:integration-test\n```\n--\n\n[.tab_content.linux_section]\n--\n[role=command]\n```\nmvn test-compile\nmvn failsafe:integration-test -Dcluster.ip=`minikube ip` -Dport=$INGRESS_PORT\n```\nThe `cluster.ip` and `port` parameters refer to the IP address and port for the {istio} gateway.\n--\n\nIf the tests pass, then you should see output similar to the following example:\n\n[source, role=\"no_copy\"]\n----\n-------------------------------------------------------\n T E S T S\n-------------------------------------------------------\nRunning it.io.openliberty.guides.system.SystemEndpointIT\nTests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.503 s - in it.io.openliberty.guides.system.SystemEndpointIT\n\nResults:\n\nTests run: 3, Failures: 0, Errors: 0, Skipped: 0\n----\n\n== Tearing down your environment\n\nYou might want to teardown all the deployed resources as a cleanup step.\n\nDelete your resources from the cluster:\n\n[role=command]\n```\nkubectl delete -f system.yaml\nkubectl delete -f traffic.yaml\n```\n\nDelete the `istio-injection` label from the default namespace. The hyphen immediately\nafter the label name indicates that the label should be deleted.\n\n[role=command]\n```\nkubectl label namespace default istio-injection-\n```\n\nDelete all {istio} resources from the cluster:\n\n[role=command]\n```\nistioctl uninstall --purge\n```\n\ninclude::{common-includes}/os-tabs.adoc[]\n\n[.tab_content.windows_section]\n--\nNothing more needs to be done for Docker Desktop.\n--\n\n[.tab_content.mac_section]\n--\nNothing more needs to be done for Docker Desktop.\n--\n\n[.tab_content.linux_section]\n--\nPerform the following steps to return your environment to a clean state.\n\n. Point the Docker daemon back to your local machine:\n+\n[role=command]\n```\neval $(minikube docker-env -u)\n```\n\n. Stop and delete your Minikube cluster:\n+\n[role=command]\n```\nminikube stop\nminikube delete\n```\n--\n\n\n// =================================================================================================\n// finish\n// =================================================================================================\n\n== Great work! You're done!\n\nYou have deployed a microservice that runs on Open Liberty to a Kubernetes cluster and used {istio} to implement a blue-green deployment scheme.\n\n// Include the below from the guides-common repo to tell users how they can contribute to the guide\ninclude::{common-includes}/attribution.adoc[subs=\"attributes\"]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenliberty%2Fguide-istio-intro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenliberty%2Fguide-istio-intro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenliberty%2Fguide-istio-intro/lists"}