// INSTRUCTION: Please remove all comments that start INSTRUCTION prior to commit. Most comments should be removed, although not the copyright. // INSTRUCTION: The copyright statement must appear at the top of the file // // Copyright (c) 2017, 2024 IBM Corporation and others. // Licensed under Creative Commons Attribution-NoDerivatives // 4.0 International (CC BY-ND 4.0) // https://creativecommons.org/licenses/by-nd/4.0/ // // Contributors: // IBM Corporation // :projectid: istio-intro :page-layout: guide-multipane :page-duration: 30 minutes :page-releasedate: 2019-02-01 :page-description: Explore how to manage microservice traffic using Istio. :page-tags: ['kubernetes', 'docker'] :page-permalink: /guides/{projectid} :page-related-guides: ['docker', 'kubernetes-intro', 'kubernetes-microprofile-config', 'kubernetes-microprofile-health'] :common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/prod :source-highlighter: prettify :page-seo-title: Managing traffic in Java microservices using Istio :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. :guide-author: Open Liberty = Managing microservice traffic using Istio
[.hidden] NOTE: 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].
Explore how to manage microservice traffic using Istio.
:kube: Kubernetes :istio: Istio :win: WINDOWS :mac: MAC :linux: LINUX :docker: Docker :minikube: Minikube :maven: Maven
== What you'll learn
You will learn how to deploy an application to a Kubernetes cluster and enable {istio} on it. You will also learn how to configure {istio} to shift traffic to implement blue-green deployments for microservices.
=== What is {istio}?
https://istio.io/[{istio}^] is a service mesh, meaning that it's a platform for managing how microservices interact with each other and the outside world. {istio} consists of a control plane and sidecars that are injected into application pods. The sidecars contain the https://www.envoyproxy.io/[Envoy^] proxy. You can think of Envoy as a sidecar that intercepts and controls all the HTTP and TCP traffic to and from your container.
While {istio} runs on top of {kube} and that will be the focus of this guide, you can also use {istio} with other environments such as https://docs.docker.com/compose/overview/[Docker Compose^]. {istio} has many features such as traffic shifting, request routing, access control, and distributed tracing, but the focus of this guide will be on traffic shifting.
=== Why {istio}?
{istio} provides a collection of features that allows you to manage several aspects of your services. One example is {istio}'s routing features. You can route HTTP requests based on several factors such as HTTP headers or cookies. Another use case for {istio} is telemetry, which you can use to enable distributed tracing. Distributed tracing allows you to visualize how HTTP requests travel between different services in your cluster by using a tool such as https://www.jaegertracing.io/[Jaeger^]. Additionally, as part of its collection of security features, {istio} allows you to enable mutual TLS between pods in your cluster. Enabling TLS between pods secures communication between microservices internally.
https://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 as a sort of staging environment and the other is a production environment. This allows you to switch traffic from staging to production once a new version of your application has been verified to work. You'll use {istio} to implement blue-green deployments. The traffic shifting feature allows you to allocate a percentage of traffic to certain versions of services. You can use this feature to shift 100 percent of live traffic to blue deployments and 100 percent of test traffic to green deployments. Then, you can shift the traffic to point to the opposite deployments as necessary to perform blue-green deployments.
The microservice you'll deploy is called system.
It responds with your current system's JVM properties and it returns the app version in the response header.
You will increment the version number when you update the application.
With this number, you can determine which version of the microservice is running in your production or test environments.
=== What are blue-green deployments?
Blue-green deployments are a way of deploying your applications such that you have two environments where your application runs. In this scenario, you will have a production environment and a test environment. At any point in time, the blue deployment can accept production traffic and the green deployment can accept test traffic, or vice versa. When you want to deploy a new version of your application, you deploy to the color that is acting as your test environment. After the new version is verified on the test environment, the traffic is shifted over. Thus, your live traffic is now being handled by what used to be the test site.
// ================================================================================================= // Prerequisites // =================================================================================================
include::{common-includes}/kube-prereq.adoc[]
// ================================================================================================= // Getting Started // =================================================================================================
[role=command] include::{common-includes}/gitclone.adoc[]
// 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.
// ================================================================================================= // Staring and preparing your cluster for deployment // ================================================================================================= // visit https://cdn.dl.k8s.io/release/stable.txt to get the latest stable version
:minikube-start: minikube start --memory=8192 --cpus=4 :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. :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. [role=command] include::{common-includes}/kube-start.adoc[]
// ================================================================================================= // Deploying Istio // =================================================================================================
include::{common-includes}/istio-start.adoc[] // ================================================================================================= // Deploying v1 // =================================================================================================
== Deploying version 1 of the system microservice
Navigate to the guide-{projectid}/start directory and run the following command to build the application locally.
[role=command]
mvn clean packageNext, run the docker build commands to build the container image for your application:
[role='command']
docker build -t system:1.0-SNAPSHOT .The command builds a {docker} image for the system microservice.
The -t flag in the docker build command allows the Docker image to be labeled (tagged) in the name[:tag] format.
The tag for an image describes the specific image version.
If the optional [:tag] tag is not specified, the latest tag is created by default.
You can verify that this image was created by running the following command:
[role=command]
docker imagesYou'll see an image called system:1.0-SNAPSHOT listed in a table similar to the output.
To deploy the system microservice to the {kube} cluster, use the following command to deploy the microservice.
[role=command]
kubectl apply -f system.yamlYou can see that your resources are created:
View 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.
View 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.
Deploy the resources defined in the traffic.yaml file.
[role=command]
kubectl apply -f traffic.yamlYou can see that the virtual services have been created.
You can check that all of the deployments are available by running the following command.
[role=command]
kubectl get deploymentsThe command produces a list of deployments for your microservices that is similar to the following output.
After 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.
Make a request to the service by running the following curl command.
include::{common-includes}/os-tabs.adoc[]
[role=command]
curl -H "Host:example.com" -I http://localhost/system/propertiescurl command is unavailable, then use https://www.getpostman.com/[Postman^]. Postman enables you
to make requests using a graphical interface. To make a request with Postman, enter \http://localhost/system/properties
into the URL bar. Next, switch to the Headers tab and add a header with key of Host and value of example.com.
Finally, click the blue Send button to make the request.[role=command]
curl -H "Host:example.com" -I http://localhost/system/propertiescurl command is unavailable, then use https://www.getpostman.com/[Postman^]. Postman enables you
to make requests using a graphical interface. To make a request with Postman, enter \http://localhost/system/properties
into the URL bar. Next, switch to the Headers tab and add a header with key of Host and value of example.com.
Finally, click the blue Send button to make the request.[role=command]
export INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].nodePort}')
curl -H "Host:example.com" -I http://`minikube ip`:$INGRESS_PORT/system/properties--
You'll see a header called x-app-version along with the corresponding version.
// ================================================================================================= // Deploy v2 // =================================================================================================
== Deploying version 2 of the system microservice
SystemResource class.src/main/java/io/openliberty/guides/system/SystemResource.javaThe system microservice is set up to respond with the version that is set in the SystemResource.java file.
The tag for the {docker} image is also dependent on the version that is specified in the SystemResource.java file.
Manually update the [hotspot=version]APP_VERSION field of the microservice to 2.0-SNAPSHOT.
Use Maven to repackage your microservice: [role=command]
mvn clean packageNext, build the new version of the container image as 2.0-SNAPSHOT:
[role=command]
docker build -t system:2.0-SNAPSHOT .Deploy the new image to the green deployment.
[role=command]
kubectl set image deployment/system-deployment-green system-container=system:2.0-SNAPSHOTYou will work with two environments.
One of the environments is a test site that is located at test.example.com.
The other environment is your production environment that is located at example.com.
To begin with, the production environment is tied to the blue deployment and the test environment is tied to the green deployment.
Test the updated microservice by making requests to the test site.
The 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.
Make a request to the service by running the following curl command.
include::{common-includes}/os-tabs.adoc[]
[role=command]
curl -H "Host:test.example.com" -I http://localhost/system/propertiescurl command is unavailable, then use https://www.getpostman.com/[Postman^].//Make a request to the service by using curl.
[role=command]
curl -H "Host:test.example.com" -I http://`minikube ip`:$INGRESS_PORT/system/properties--
You'll see the new version in the x-app-version response header.
traffic.yaml file in the start directory.traffic.yaml[role="edit_command_text"]
After 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.
Deploy the updated traffic.yaml file.
[role=command]
kubectl apply -f traffic.yamlEnsure that the live traffic is now being routed to version 2 of the microservice.
Make a request to the service by running the following curl command.
include::{common-includes}/os-tabs.adoc[]
[role=command]
curl -H "Host:example.com" -I http://localhost/system/propertiescurl command is unavailable, then use https://www.getpostman.com/[Postman^].[role=command]
curl -H "Host:example.com" -I http://localhost/system/propertiescurl command is unavailable, then use https://www.getpostman.com/[Postman^].[role=command]
curl -H "Host:example.com" -I http://`minikube ip`:$INGRESS_PORT/system/properties--
You'll see the new version in the x-app-version response header.
== Testing microservices that are running on {kube}
Next, you will create a test to verify that the correct version of your microservice is running.
SystemEndpointIT class.src/test/java/it/io/openliberty/guides/system/SystemEndpointIT.javaThe [hotspot=testAppVersion]testAppVersion() test case verifies that the correct version number is returned in the response headers.
Run the following commands to compile and start the tests:
include::{common-includes}/os-tabs.adoc[]
[role=command]
mvn test-compile
mvn failsafe:integration-test--
[role=command]
mvn test-compile
mvn failsafe:integration-test -Dcluster.ip=`minikube ip` -Dport=$INGRESS_PORTcluster.ip and port parameters refer to the IP address and port for the {istio} gateway.If the tests pass, then you should see output similar to the following example:
Running it.io.openliberty.guides.system.SystemEndpointIT Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.503 s - in it.io.openliberty.guides.system.SystemEndpointIT
Results:
== Tearing down your environment
You might want to teardown all the deployed resources as a cleanup step.
Delete your resources from the cluster:
[role=command]
kubectl delete -f system.yaml
kubectl delete -f traffic.yamlDelete the istio-injection label from the default namespace. The hyphen immediately
after the label name indicates that the label should be deleted.
[role=command]
kubectl label namespace default istio-injection-Delete all {istio} resources from the cluster:
[role=command]
istioctl uninstall --purgeinclude::{common-includes}/os-tabs.adoc[]
Perform the following steps to return your environment to a clean state.
. Point the Docker daemon back to your local machine: + [role=command]
eval $(minikube docker-env -u). Stop and delete your Minikube cluster: + [role=command]
minikube stop
minikube delete--
// ================================================================================================= // finish // =================================================================================================
== Great work! You're done!
You have deployed a microservice that runs on Open Liberty to a Kubernetes cluster and used {istio} to implement a blue-green deployment scheme.
// Include the below from the guides-common repo to tell users how they can contribute to the guide include::{common-includes}/attribution.adoc[subs="attributes"]