Consuming External TCP Services

Egress rules for TCP traffic

By Vadim Eisenberg / February 6, 2018

In my previous blog post, Consuming External Web Services, I described how external services can be consumed by in-mesh Istio applications via HTTPS. In this post, I demonstrate consuming external services over TCP. I use the Istio Bookinfo sample application, the version in which the book ratings data is persisted in a MySQL database. I deploy this database outside the cluster and will configure the ratings microservice to use it. I define an egress rule to allow the in-mesh applications to access the external database.

Bookinfo sample application with external ratings database

First, I set up a MySQL database instance to hold book ratings data, outside my Kubernetes cluster. Then I modify the Bookinfo sample application to use my database.

Setting up the database for ratings data

For this task I set up an instance of MySQL. Any MySQL instance would do, I use Compose for MySQL. As a MySQL client to feed the ratings data, I use mysqlsh (MySQL Shell).

To initialize the database, I run the following command entering the password when prompted. The command is performed with the credentials of the admin user, created by default by Compose for MySQL.

curl -s https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/src/mysql/mysqldb-init.sql |
mysqlsh --sql --ssl-mode=REQUIRED -u admin -p --host <the database host> --port <the database port>

When using the mysql client and a local MySQL database, I would run:

curl -s https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/src/mysql/mysqldb-init.sql |
mysql -u root -p

Then I create a user with the name bookinfo and grant it SELECT privilege on the test.ratings table:
```
mysqlsh --sql --ssl-mode=REQUIRED -u admin -p --host <the database host> --port <the database port>  \
-e "CREATE USER 'bookinfo' IDENTIFIED BY '<password you choose>'; GRANT SELECT ON test.ratings to 'bookinfo';"
```
OR
For mysql and the local database, the command would be:
```
mysql -u root -p -e \
"CREATE USER 'bookinfo' IDENTIFIED BY '<password you choose>'; GRANT SELECT ON test.ratings to 'bookinfo';"
```
Here I apply the principle of least privilege. It means that I do not use my admin user in the Bookinfo application. Instead, for Bookinfo application I create a special user, bookinfo, with minimal privileges, in this case only the SELECT privilege and only on a single table.
After running the command to create the user, I will clean my bash history by checking the number of the last command and running history -d <the number of the command that created the user>. I do not want the password of the new user to be stored in the bash history. If I would use mysql, I would remove the last command from ~/.mysql_history file as well. Read more about password protection of the newly created user in MySQL documentation.

I inspect the created ratings to see that everything worked as expected:

mysqlsh --sql --ssl-mode=REQUIRED -u bookinfo -p --host <the database host> --port <the database port> \
-e "select * from test.ratings;"

Enter password:
+----------+--------+
| ReviewID | Rating |
+----------+--------+
|        1 |      5 |
|        2 |      4 |
+----------+--------+

For mysql and the local database:

mysql -u bookinfo -p -e "select * from test.ratings;"

Enter password:
+----------+--------+
| ReviewID | Rating |
+----------+--------+
|        1 |      5 |
|        2 |      4 |
+----------+--------+

I set the ratings temporarily to 1 to provide a visual clue when our database is used by the Bookinfo ratings service:

mysqlsh --sql --ssl-mode=REQUIRED -u admin -p --host <the database host> --port <the database port>  \
-e "update test.ratings set rating=1; select * from test.ratings;"

Enter password:
+----------+--------+
| ReviewID | Rating |
+----------+--------+
|        1 |      1 |
|        2 |      1 |
+----------+--------+

For mysql and the local database:

mysql -u root -p -e "update test.ratings set rating=1; select * from  test.ratings;"

Enter password:
+----------+--------+
| ReviewID | Rating |
+----------+--------+
|        1 |      1 |
|        2 |      1 |
+----------+--------+

I used the admin user (and root for the local database) in the last command since the bookinfo user does not have the UPDATE privilege on the test.ratings table.

Now I am ready to deploy a version of the Bookinfo application that will use my database.

Initial setting of Bookinfo application

To demonstrate the scenario of using an external database, I start with a Kubernetes cluster with Istio installed. Then I deploy Istio Bookinfo sample application. This application uses the ratings microservice to fetch book ratings, a number between 1 and 5. The ratings are displayed as stars per each review. There are several versions of the ratings microservice. Some use MongoDB, others use MySQL as their database.

The example commands in this blog post work with Istio version 0.3+, with or without Mutual TLS enabled.

As a reminder, here is the end-to-end architecture of the application from the Bookinfo Guide.

The Original Bookinfo Application

Use the database for ratings data in Bookinfo application

I modify the deployment spec of a version of the ratings microservice that uses a MySQL database, to use my database instance. The spec is in samples/bookinfo/kube/bookinfo-ratings-v2-mysql.yaml of an Istio release archive. I edit the following lines:
```
- name: MYSQL_DB_HOST
  value: mysqldb
- name: MYSQL_DB_PORT
  value: "3306"
- name: MYSQL_DB_USER
  value: root
- name: MYSQL_DB_PASSWORD
  value: password
```
I replace the values in the snippet above, specifying the database host, port, user and password. Note that the correct way to work with passwords in container’s environment variables in Kubernetes is to use secrets. For this example task only, I write the password directly in the deployment spec. Do not do it in a real environment! No need to mention that "password" should not be used as a password.

I apply the modified spec to deploy the version of the ratings microservice, v2-mysql, that will use my database.

kubectl apply -f <(istioctl kube-inject -f samples/bookinfo/kube/bookinfo-ratings-v2-mysql.yaml)

deployment "ratings-v2-mysql" created

I route all the traffic destined to the reviews service, to its v3 version. I do this to ensure that the reviews service always calls the ratings service. In addition, I route all the traffic destined to the ratings service to ratings v2-mysql that uses my database. I add routing for both services above by adding two route rules. These rules are specified in samples/bookinfo/kube/route-rule-ratings-mysql.yaml of an Istio release archive.
```
istioctl create -f samples/bookinfo/kube/route-rule-ratings-mysql.yaml
```
```
Created config route-rule/default/ratings-test-v2-mysql at revision 1918799
Created config route-rule/default/reviews-test-ratings-v2 at revision 1918800
```

The updated architecture appears below. Note that the blue arrows inside the mesh mark the traffic configured according to the route rules we added. According to the route rules, the traffic is sent to reviews v3 and ratings v2-mysql.

The Bookinfo Application with ratings v2-mysql and an external MySQL database

Note that the MySQL database is outside the Istio service mesh, or more precisely outside the Kubernetes cluster. The boundary of the service mesh is marked by a dotted line.

Access the webpage

Let’s access the webpage of the application, after determining the ingress IP and port.

We have a problem… Instead of the rating stars we have the Ratings service is currently unavailable message displayed per each review:

The Ratings service error messages

As in Consuming External Web Services, we experience graceful service degradation, which is good. The application did not crash due to the error in the ratings microservice. The webpage of the application correctly displayed the book information, the details and the reviews, just without the rating stars.

We have the same problem as in Consuming External Web Services, namely all the traffic outside the Kubernetes cluster, both TCP and HTTP, is blocked by default by the sidecar proxies. To enable such traffic for TCP, an egress rule for TCP must be defined.

Egress rule for an external MySQL instance

TCP egress rules come to our rescue. I copy the following YAML spec to a text file, let’s call it egress-rule-mysql.yaml, and edit it to specify the IP of my database instance and its port.

apiVersion: config.istio.io/v1alpha2
kind: EgressRule
metadata:
  name: mysql
  namespace: default
spec:
  destination:
      service: <MySQL instance IP>
  ports:
      - port: <MySQL instance port>
        protocol: tcp

Then I run istioctl to add the egress rule to the service mesh:

istioctl create -f egress-rule-mysql.yaml

Created config egress-rule/default/mysql at revision 1954425

Note that for a TCP egress rule, we specify tcp as the protocol of a port of the rule. Also note that we use an IP of the external service instead of its domain name. I will talk more about TCP Egress Rules below. For now, let’s verify that the egress rule we added fixed the problem. Let’s access the webpage and see if the stars are back.

It worked! Accessing the web page of the application displays the ratings without error:

Book Ratings Displayed Correctly

Note that we see a one-star rating for the both displayed reviews, as expected. I changed the ratings to be one star to provide us a visual clue that our external database is indeed used.

As with egress rules for HTTP/HTTPS, we can delete and create egress rules for TCP using istioctl, dynamically.

Motivation for egress TCP traffic control

Some in-mesh Istio applications must access external services, for example legacy systems. In many cases, the access is not performed over HTTP or HTTPS protocols. Other TCP protocols are used, for example database specific protocols MongoDB Wire Protocol and MySQL CLient/Server Protocol to communicate with external databases.

Note that in case of access to external HTTPS services, as described in the Control Egress TCP Traffic task, an application must issue HTTP requests to the external service. The Envoy sidecar proxy attached to the pod or the VM, will intercept the requests and will open an HTTPS connection to the external service. The traffic will be unencrypted inside the pod or the VM, but it will leave the pod or the VM encrypted.

However, sometimes this approach cannot work due to the following reasons:

The code of the application is configured to use an HTTPS URL and cannot be changed
The code of the application uses some library to access the external service and that library uses HTTPS only
There are compliance requirements that do not allow unencrypted traffic, even if the traffic is unencrypted only inside the pod or the VM

In this case, HTTPS can be treated by Istio as opaque TCP and can be handled in the same way as other TCP non-HTTP protocols.

Next let’s see how we define egress rules for TCP traffic.

Egress rules for TCP traffic

The egress rules for enabling TCP traffic to a specific port must specify TCP as the protocol of the port. Additionally, for the MongoDB Wire Protocol, the protocol can be specified as MONGO, instead of TCP.

For the destination.service field of the rule, an IP or a block of IPs in CIDR notation must be used.

To enable TCP traffic to an external service by its hostname, all the IPs of the hostname must be specified. Each IP must be specified by a CIDR block or as a single IP, each block or IP in a separate egress rule.

Note that all the IPs of an external service are not always known. To enable TCP traffic by IPs, as opposed to the traffic by a hostname, only the IPs that are used by the applications must be specified.

Also note that the IPs of an external service are not always static, for example in the case of CDNs. Sometimes the IPs are static most of the time, but can be changed from time to time, for example due to infrastructure changes. In these cases, if the range of the possible IPs is known, you should specify the range by CIDR blocks, by multiple egress rules if needed, as in the case of wikipedia.org, described in Control Egress TCP Traffic Task. If the range of the possible IPs is not known, egress rules for TCP cannot be used and the external services must be called directly, circumventing the sidecar proxies.

Relation to mesh expansion

Note that the scenario described in this post is different from the mesh expansion scenario, described in the Integrating Virtual Machines guide. In that scenario, a MySQL instance runs on a an external (outside the cluster) machine (a bare metal or a VM), integrated with the Istio service mesh. The MySQL service becomes a first-class citizen of the mesh with all the beneficial features of Istio applicable. Among other things, the service becomes addressable by a local cluster domain name, for example by mysqldb.vm.svc.cluster.local, and the communication to it can be secured by mutual TLS authentication. There is no need to create an egress rule to access this service, however the service has to be registered with Istio. To enable such integration, Istio components (Envoy proxy, node-agent, istio-agent) must be installed on the machine and the Istio control plane (Pilot, Mixer, CA) must be accessible from it. See the Istio Mesh Expansion instructions for more details.

In our case, the MySQL instance can run on any machine or can be provisioned as a service by a cloud provider. There is no requirement to integrate the machine with Istio. The Istio contol plane does not have to be accessible from the machine. In the case of MySQL as a service, the machine which MySQL runs on, may be not accessible and installing on it the required components may be impossible. In our case, the MySQL instance is addressable by its global domain name, which could be beneficial if the consuming applications expect to use that domain name. Especially, when this expectation cannot be changed by the deployment configuration of the consuming applications.

Cleanup

Drop the test database and the bookinfo user:

mysqlsh --sql --ssl-mode=REQUIRED -u admin -p --host <the database host> --port <the database port> \
-e "drop database test; drop user bookinfo;"

For mysql and the local database:

mysql -u root -p -e "drop database test; drop user bookinfo;"

Remove the route rules:

istioctl delete -f samples/bookinfo/kube/route-rule-ratings-mysql.yaml

Deleted config: route-rule/default/ratings-test-v2-mysql
Deleted config: route-rule/default/reviews-test-ratings-v2

Undeploy ratings v2-mysql:

kubectl delete -f <(istioctl kube-inject -f samples/bookinfo/kube/bookinfo-ratings-v2-mysql.yaml)

deployment "ratings-v2-mysql" deleted

Delete the egress rule:

istioctl delete egressrule mysql -n default

Deleted config: egressrule mysql

Future work

In my next blog posts I will show examples of combining route rules and egress rules, and also examples of accessing external services via Kubernetes ExternalName services.

Conclusion

In this blog post I demonstrated how the microservices in an Istio service mesh can consume external services via TCP. By default, Istio blocks all the traffic, TCP and HTTP, to the hosts outside the cluster. To enable such traffic for TCP, TCP egress rules must be created for the service mesh.

What’s next

To read more about Istio egress traffic control:

for TCP, see Control Egress TCP Traffic Task
for HTTP/HTTPS, see Control Egress Traffic Task