<commit_before>---
title: Bookinfo Application
description: Deploys a sample application composed of four separate microservices used to demonstrate various Istio features.
weight: 10
aliases:
    - /docs/samples/bookinfo.html
    - /docs/guides/bookinfo/index.html
    - /docs/guides/bookinfo.html
---

This example deploys a sample application composed of four separate microservices used
to demonstrate various Istio features. The application 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.

The Bookinfo application is broken into four separate microservices:

* `productpage`. The `productpage` microservice calls the `details` and `reviews` microservices to populate the page.
* `details`. The `details` microservice contains book information.
* `reviews`. The `reviews` microservice contains book reviews. It also calls the `ratings` microservice.
* `ratings`. The `ratings` microservice contains book ranking information that accompanies a book review.

There are 3 versions of the `reviews` microservice:

* Version v1 doesn't call the `ratings` service.
* Version v2 calls the `ratings` service, and displays each rating as 1 to 5 black stars.
* Version v3 calls the `ratings` service, and displays each rating as 1 to 5 red stars.

The end-to-end architecture of the application is shown below.

{{< image width="80%" link="./noistio.svg" caption="Bookinfo Application without Istio" >}}

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
service mesh example, particularly because of the multitude of services, languages and versions
for the `reviews` service.

## Before you begin

If you haven't already done so, setup Istio by following the instructions
corresponding to your platform [installation guide](/docs/setup/).

## Deploying the application

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:

{{< image width="80%" link="./withistio.svg" caption="Bookinfo Application" >}}

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.

To start the application, follow the instructions corresponding to your Istio runtime environment.

* [If you are running on Kubernetes](#if-you-are-running-on-kubernetes)
* [If you are running on Docker with Consul](#if-you-are-running-on-docker-with-consul)

### If you are running on Kubernetes

{{< tip >}}
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.
{{< /tip >}}

1.  Change directory to the root of the Istio installation.

1.  The default Istio installation uses [automatic sidecar injection](/docs/setup/kubernetes/additional-setup/sidecar-injection/#automatic-sidecar-injection).
    Label the namespace that will host the application with `istio-injection=enabled`:

    {{< text bash >}}
    $ kubectl label namespace default istio-injection=enabled
    {{< /text >}}

1.  Deploy your application using the `kubectl` command:

    {{< text bash >}}
    $ kubectl apply -f @samples/bookinfo/platform/kube/bookinfo.yaml@
    {{< /text >}}

    {{< warning >}}
    If you disabled automatic sidecar injection during installation and rely on [manual sidecar injection]
    (/docs/setup/kubernetes/additional-setup/sidecar-injection/#manual-sidecar-injection),
    use the `istioctl kube-inject` command to modify the `bookinfo.yaml`
    file before deploying your application. For more information please
    visit the `istioctl` [reference documentation](/docs/reference/commands/istioctl/#istioctl-kube-inject).

    {{< text bash >}}
    $ kubectl apply -f <(istioctl kube-inject -f @samples/bookinfo/platform/kube/bookinfo.yaml@)
    {{< /text >}}

    {{< /warning >}}

    The command launches all four services shown in the `bookinfo` application architecture diagram.
    All 3 versions of the reviews service, v1, v2, and v3, are started.

    {{< tip >}}
    In a realistic deployment, new versions of a microservice are deployed
    over time instead of deploying all versions simultaneously.
    {{< /tip >}}

1.  Confirm all services and pods are correctly defined and running:

    {{< text bash >}}
    $ kubectl get services
    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
    {{< /text >}}

    and

    {{< text bash >}}
    $ kubectl get pods
    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
    {{< /text >}}

1.  To confirm that the Bookinfo application is running, send a request to it by a `curl` command from some pod, for
    example from `ratings`:

    {{< text bash >}}
    $ kubectl exec -it $(kubectl get pod -l app=ratings -o jsonpath='{.items[0].metadata.name}') -c ratings -- curl productpage:9080/productpage | grep -o "<title>.*</title>"
    <title>Simple Bookstore App</title>
    {{< /text >}}

#### Determining the ingress IP and port

Now that the Bookinfo services are up and running, you need to make the application accessible from outside of your
Kubernetes cluster, e.g., from a browser. An [Istio Gateway](/docs/concepts/traffic-management/#gateways)
is used for this purpose.

1.  Define the ingress gateway for the application:

    {{< text bash >}}
    $ kubectl apply -f @samples/bookinfo/networking/bookinfo-gateway.yaml@
    {{< /text >}}

1.  Confirm the gateway has been created:

    {{< text bash >}}
    $ kubectl get gateway
    NAME               AGE
    bookinfo-gateway   32s
    {{< /text >}}

1.  Follow [these instructions](/docs/tasks/traffic-management/ingress/#determining-the-ingress-ip-and-ports) to set the `INGRESS_HOST` and `INGRESS_PORT` variables for accessing the gateway. Return here, when they are set.

1.  Set `GATEWAY_URL`:

    {{< text bash >}}
    $ export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT
    {{< /text >}}

1.  Proceed to [Confirm the app is running](#confirm-the-app-is-accessible-from-outside-the-cluster), below.

### If you are running on Docker with Consul

1.  Change directory to the root of the Istio installation directory.

1.  Bring up the application containers.

    To test with Consul, run the following commands:

    {{< text bash >}}
    $ docker-compose -f @samples/bookinfo/platform/consul/bookinfo.yaml@ up -d
    {{< /text >}}

1.  Confirm that all docker containers are running:

    {{< text bash >}}
    $ docker ps -a
    {{< /text >}}<commit_msg>re-add deleted step for docker with consul setup (#4107)<commit_after>---
title: Bookinfo Application
description: Deploys a sample application composed of four separate microservices used to demonstrate various Istio features.
weight: 10
aliases:
    - /docs/samples/bookinfo.html
    - /docs/guides/bookinfo/index.html
    - /docs/guides/bookinfo.html
---

This example deploys a sample application composed of four separate microservices used
to demonstrate various Istio features. The application 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.

The Bookinfo application is broken into four separate microservices:

* `productpage`. The `productpage` microservice calls the `details` and `reviews` microservices to populate the page.
* `details`. The `details` microservice contains book information.
* `reviews`. The `reviews` microservice contains book reviews. It also calls the `ratings` microservice.
* `ratings`. The `ratings` microservice contains book ranking information that accompanies a book review.

There are 3 versions of the `reviews` microservice:

* Version v1 doesn't call the `ratings` service.
* Version v2 calls the `ratings` service, and displays each rating as 1 to 5 black stars.
* Version v3 calls the `ratings` service, and displays each rating as 1 to 5 red stars.

The end-to-end architecture of the application is shown below.

{{< image width="80%" link="./noistio.svg" caption="Bookinfo Application without Istio" >}}

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
service mesh example, particularly because of the multitude of services, languages and versions
for the `reviews` service.

## Before you begin

If you haven't already done so, setup Istio by following the instructions
corresponding to your platform [installation guide](/docs/setup/).

## Deploying the application

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:

{{< image width="80%" link="./withistio.svg" caption="Bookinfo Application" >}}

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.

To start the application, follow the instructions corresponding to your Istio runtime environment.

* [If you are running on Kubernetes](#if-you-are-running-on-kubernetes)
* [If you are running on Docker with Consul](#if-you-are-running-on-docker-with-consul)

### If you are running on Kubernetes

{{< tip >}}
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.
{{< /tip >}}

1.  Change directory to the root of the Istio installation.

1.  The default Istio installation uses [automatic sidecar injection](/docs/setup/kubernetes/additional-setup/sidecar-injection/#automatic-sidecar-injection).
    Label the namespace that will host the application with `istio-injection=enabled`:

    {{< text bash >}}
    $ kubectl label namespace default istio-injection=enabled
    {{< /text >}}

1.  Deploy your application using the `kubectl` command:

    {{< text bash >}}
    $ kubectl apply -f @samples/bookinfo/platform/kube/bookinfo.yaml@
    {{< /text >}}

    {{< warning >}}
    If you disabled automatic sidecar injection during installation and rely on [manual sidecar injection]
    (/docs/setup/kubernetes/additional-setup/sidecar-injection/#manual-sidecar-injection),
    use the `istioctl kube-inject` command to modify the `bookinfo.yaml`
    file before deploying your application. For more information please
    visit the `istioctl` [reference documentation](/docs/reference/commands/istioctl/#istioctl-kube-inject).

    {{< text bash >}}
    $ kubectl apply -f <(istioctl kube-inject -f @samples/bookinfo/platform/kube/bookinfo.yaml@)
    {{< /text >}}

    {{< /warning >}}

    The command launches all four services shown in the `bookinfo` application architecture diagram.
    All 3 versions of the reviews service, v1, v2, and v3, are started.

    {{< tip >}}
    In a realistic deployment, new versions of a microservice are deployed
    over time instead of deploying all versions simultaneously.
    {{< /tip >}}

1.  Confirm all services and pods are correctly defined and running:

    {{< text bash >}}
    $ kubectl get services
    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
    {{< /text >}}

    and

    {{< text bash >}}
    $ kubectl get pods
    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
    {{< /text >}}

1.  To confirm that the Bookinfo application is running, send a request to it by a `curl` command from some pod, for
    example from `ratings`:

    {{< text bash >}}
    $ kubectl exec -it $(kubectl get pod -l app=ratings -o jsonpath='{.items[0].metadata.name}') -c ratings -- curl productpage:9080/productpage | grep -o "<title>.*</title>"
    <title>Simple Bookstore App</title>
    {{< /text >}}

#### Determining the ingress IP and port

Now that the Bookinfo services are up and running, you need to make the application accessible from outside of your
Kubernetes cluster, e.g., from a browser. An [Istio Gateway](/docs/concepts/traffic-management/#gateways)
is used for this purpose.

1.  Define the ingress gateway for the application:

    {{< text bash >}}
    $ kubectl apply -f @samples/bookinfo/networking/bookinfo-gateway.yaml@
    {{< /text >}}

1.  Confirm the gateway has been created:

    {{< text bash >}}
    $ kubectl get gateway
    NAME               AGE
    bookinfo-gateway   32s
    {{< /text >}}

1.  Follow [these instructions](/docs/tasks/traffic-management/ingress/#determining-the-ingress-ip-and-ports) to set the `INGRESS_HOST` and `INGRESS_PORT` variables for accessing the gateway. Return here, when they are set.

1.  Set `GATEWAY_URL`:

    {{< text bash >}}
    $ export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT
    {{< /text >}}

1.  Proceed to [Confirm the app is running](#confirm-the-app-is-accessible-from-outside-the-cluster), below.

### If you are running on Docker with Consul

1.  Change directory to the root of the Istio installation directory.

1.  Bring up the application containers.

    To test with Consul, run the following commands:

    {{< text bash >}}
    $ docker-compose -f @samples/bookinfo/platform/consul/bookinfo.yaml@ up -d
    $ docker-compose -f samples/bookinfo/platform/consul/bookinfo.sidecars.yaml up -d
    {{< /text >}}

1.  Confirm that all docker containers are running:

    {{< text bash >}}
    $ docker ps -a
    {{< /text >}}
{'fraction_non_alphanumeric': 0.08808130582075763, 'fraction_numerical': 0.024391746227286727, 'mean_word_length': 2.874015748031496, 'pattern_counts': {'":': 0, '<': 83, '<?xml version=': 0, '>': 81, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 10, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '961542', 'n_tokens_mistral': 4864, 'n_tokens_neox': 4528, 'n_words': 1795}