Installing Istio Command-Line Tooling

The last thing that you need to do is make istioctl available on the command line. istioctl is the Istio command-line tool that you can use to manually inject the istio-proxy sidecar as well as create, update, and delete Istio resources files. When you unzip the Istio distribution, you’ll have a folder named /bin that has the istioctl binary. You can add that to your path like this:

export ISTIO_HOME=~/istio-0.5.1
export PATH=$ISTIO_HOME/bin:$PATH

Now, from your command line you should be able to type the following and see a valid response:

istioctl version
Version: 0.5.1
GitRevision: c9debceacb63a14a9ae24df433e2ec3ce1f16fc7
User: root@211b132eb7f1
Hub: docker.io/istio
GolangVersion: go1.9
BuildStatus: Clean

At this point, you’re ready to move on to installing the sample services.

Navigating the Code Base

If you navigate into the istio-tutorial subfolder that you just cloned, you should see a handful of folders. You should see the customer, preference, and recommendation folders. These folders each hold the source code the respective services we’ll use to demonstrate Istio capabilities.

The customer and preference services are both Java Spring Boot implementations. Have a look at the source code. You should see fairly straightforward implementations of REST services. For example, here’s the endpoint for the customer service:

@RequestMapping("/")
public ResponseEntity<String> getCustomer() {
  try {
    String response = restTemplate.getForObject(remoteURL,
         String.class);
    return ResponseEntity.ok(String.format(RESPONSE_STRING_FORMAT,
         response.trim()));
  } catch (HttpStatusCodeException ex) { ....  }
}

We’ve left out the exception handling for a moment. You can see that this HTTP endpoint simply calls out to the preference service and returns the response from preference prepended with a fixed string of customer => %s. Note that there are no additional libraries that we use beyond Spring’s RestTemplate. We do not wrap these calls in circuit breaking, retry, client-side load balancing libraries, and so on. We’re not adding any special request-tracking or request-mirroring functionality. This is a crucial point. We want you to write code that allows you to build powerful business logic without having to comingle application-networking concerns into your code base and dependency trees.

In the preceding example, we’ve left out the exception handling for brevity, but the exception handling is also an important part of the code. Most languages provide some mechanism for detecting and handling runtime failures. When you try to call methods in your code that you know could fail, you should take care to catch those exceptional behaviors and deal with them appropriately. In the case of the customer HTTP endpoint, you are trying to make a call over the network to the preferences service. This call could fail, and you need to wrap it with some exception handling. You could do interesting things in this exception handler like reach into a cache or call a different service. For instance, we can envision developers doing business-logic type things when they cannot get a preference like returning a list of canned preferences, and so on. This type of alternative path processing is sometimes termed fallback in the face of negative path behavior. You don’t need special libraries to do this for you.

If you peruse the code base for the customer service a bit more, you might stumble upon two classes named HttpHeaderForwarderHandlerInterceptor and HttpHeaderForwarderClientHttpRequestInterceptor. These classes work together to intercept any incoming headers used for tracing and propagates them for further downstream requests. These headers are the OpenTracing headers and are defined in this immutable variable:

    private static final Set<String> FORWARDED_HEADER_NAMES =
         ImmutableSet.of(
            "x-request-id",
            "x-b3-traceid",
            "x-b3-spanid",
            "x-b3-parentspanid",
            "x-b3-sampled",
            "x-b3-flags",
            "x-ot-span-context",
            "user-agent"
    );

These headers are used to correlate requests together, submit spans to tracing systems, and can be used for request/response timing analysis, diagnostics, and debugging. Although our little helper interceptor is responsible for shuffling the x-b3-* headers along it does not communicate with the tracing system directly. In fact, you don’t need to include any tracing libraries in your application code or dependency tree. When you propagate these headers, Istio is smart enough to recognize them and submit the proper spans to your tracing backend. Throughout the examples and use cases in this book, we use the Jaeger Tracing project from the Cloud Native Computing Foundation (CNCF). You can learn more about Jaeger Tracing at http://jaegertracing.io/. You installed Jaeger as part of the Istio installation in the previous section.

Now that you’ve had a moment to peruse the code base, let’s build these applications and run them in containers on our Kubernetes/Openshift deployment system.

Before you deploy your services, make sure that you create the target namespace/project and apply the correct security permissions:

oc new-project tutorial
oc adm policy add-scc-to-user privileged -z default -n tutorial

Building and Deploying the Customer Service

Now, let’s build and deploy the customer service. Make sure you’re logged in to minishift which you installed earlier, in the section Istio Installation. You can verify your status by using the following command:

oc status

Navigate to the customer directory and build the source just as you would any Maven Java project:

cd customer
mvn clean package

Now you have built your project. Next, you will package your application as a Docker image so that you can run it on Kubernetes:

docker build -t example/customer .

This will build your customer service into a docker image. You can see the results of the Docker build command by using the following:

docker images | grep example

In the customer/src/main/kubernetes directory, there are two Kubernetes resource files named Deployment.yml and Service.yml. Deploy the service and also deploy your application with the Istio sidecar proxy injected into it. Try running the following command to see what the injected sidecar looks like with your deployment:

istioctl kube-inject -f src/main/kubernetes/Deployment.yml

Examine this output and compare it to the unchanged Deployment.yml. You should see the sidecar that has been injected that looks like this:

      - args:
        - proxy
        - sidecar
        - --configPath
        - /etc/istio/proxy
        - --binaryPath
        - /usr/local/bin/envoy
        - --serviceCluster
        - customer
        - --drainDuration
        - 2s
        - --parentShutdownDuration
        - 3s
        - --discoveryAddress
        - istio-pilot.istio-system:15003
        - --discoveryRefreshDelay
        - 1s
        - --zipkinAddress
        - zipkin.istio-system:9411
        - --connectTimeout
        - 1s
        - --statsdUdpAddress
        - istio-mixer.istio-system:9125
        - --proxyAdminPort
        - "15000"
        - --controlPlaneAuthPolicy
        - NONE
        env:
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: INSTANCE_IP
          valueFrom:
            fieldRef:
              fieldPath: status.podIP
        image: docker.io/istio/proxy:0.5.1
        imagePullPolicy: IfNotPresent
        name: istio-proxy
        resources: {}
        securityContext:
          privileged: false
          readOnlyRootFilesystem: true
          runAsUser: 1337
        volumeMounts:
        - mountPath: /etc/istio/proxy
          name: istio-envoy
        - mountPath: /etc/certs/
          name: istio-certs
          readOnly: true

You will see a second container injected into your deployment with configurations for finding the Istio control plane, volume mounts which mount in any additional secrets, and you should see the name of this container is istio-proxy.

Now you can create the Kubernetes service and inject the sidecar into your deployment:

oc apply -f <(istioctl kube-inject -f 
src/main/kubernetes/Deployment.yml)  -n tutorial

oc create -f src/main/kubernetes/Service.yml -n tutorial

Because customer is the forwardmost microservice (customer > preference > recommendation), you should add an OpenShift Route that exposes that endpoint:

oc expose service customer
curl customer-tutorial.$(minishift ip).nip.io

Note we’re using the nip.io service which is basically a wildcard DNS system that returns the IP address that you specify in the URL.

You should see the following error because preference and recommendation are not yet deployed:

customer => I/O error on GET request for "http://preference:8080":
preference; nested exception is java.net.UnknownHostException: preference

Now you can deploy the rest of the services in this example.

Building and Deploying the Preference Service

Just like you did for the customer service, in this section you will build, package, and deploy your preference service:

cd preference

mvn clean package

docker build -t example/preference .

You can also inject the Istio sidecar proxy into your deployment for the preference service as you did previously for the customer service:

oc apply -f <(istioctl kube-inject -f 
src/main/kubernetes/Deployment.yml) -n tutorial

oc create -f src/main/kubernetes/Service.yml

Finally, try to curl your customer service once more:

curl customer-tutorial.$(minishift ip).nip.io

The response still fails, but a little bit differently this time:

customer => 503 preference => I/O error on GET request for
"http://recommendation:8080": recommendation; nested exception is
java.net.UnknownHostException: recommendation

This time the failure is because the preference service cannot reach the recommendation service. As such, you will build and deploy the recommendation service next.

Building and Deploying the Recommendation Service

The last step to get the full cooperation of our services working nicely is to deploy the recommendation service. Just like in the previous services, you will build, package, and deploy onto Kubernetes by using a couple of steps:

cd recommendation

mvn clean package

docker build -t example/recommendation:v1 .

oc apply -f <(istioctl kube-inject -f 
src/main/kubernetes/Deployment.yml) -n tutorial

oc create -f src/main/kubernetes/Service.yml

oc get pods -w

Look for “2/2” under the Ready column. Ctrl-C to break out of the wait, and now when you do the curl, you should see a better response:

curl customer-tutorial.$(minishift ip).nip.io

customer => preference => recommendation v1 from '99634814-sf4cl': 1

Success! The chain of calls between the three services works as expected. Now that you have your services calling one another, we move on to discussing some of the core capabilities of Istio and the power it brings for solving the problems that arise between services.

Building and Deploying to Kubernetes

Kubernetes deploys and manages applications that have been built as Docker containers. In the preceding examples, you built and packaged the applications into Docker containers at each step. There are alternatives to the fully manual deployment process of docker build and oc create -f someyaml.yml. These alternatives include oc new-app and a capability known as source-to-image (S2I). S2I is an OpenShift-only feature that is not compatible with vanilla Kubernetes. There is also the fabric8-maven-plugin, which is a maven plug-in for Java applications. fabric8-maven-plugin allows you to live comfortably in your existing Java tooling and still build Docker images and interact with Kubernetes without having to know about Dockerfiles or Kubernetes resource files. The maven plug-in automatically builds the Kubernetes resource files and you can also use it to quickly deploy, undeploy, and debug your Java application running in Kubernetes.