Skip to main content
logoTetrate Istio SubscriptionVersion: Next


This guide will walk you through setting up istio-registry-sync integration with Consul.


Before you begin, you will need the following:

  • A Kubernetes cluster with Istio installed. If you do not have a cluster with TIS Istio installed, you can follow the Installing TIS Guide.
    • You must enable the DNS proxy in Istio. If you use Helm, you can do this by using the following Istio Helm's values.yaml:
      Then install or update Istio with the following command:
      helm upgrade --install istiod tetratelabs/istiod -n istio-system -f values.yaml
  • kubectl and helm are installed and configured with the correct credentials.

Integration Steps

Following are steps to set up istio-registry-sync integration with Consul:


You can skip the first two steps if you already have Consul installed and it has registered services. Note that your Kubernetes cluster must be able to reach service endpoints that are registered in Consul.

Before continuing, let's set up some environment variables:

export CONSUL_NS=consul
export SLEEP_NS=sleep
export TIS_NS=tis

1. Install Consul


The following Consul installation is for demo purposes only. Please refer to the Consul documentation for production installation.

Run the following commands to install Consul in the Kubernetes cluster. It is assumed that Consul is installed in the same cluster as Istio.

kubectl create ns $CONSUL_NS
kubectl run consul -n $CONSUL_NS --image consul:1.15.4
kubectl wait --for=condition=Ready pod/consul -n $CONSUL_NS --timeout=120s
CONSUL_ENDPOINT=http://$(kubectl get pod -n $CONSUL_NS consul --template '{{.status.podIP}}'):8500

2. Register Services

Deploy a sample nginx service on Kubernetes and register it with Consul.

kubectl run -n $CONSUL_NS nginx --image=nginx:1.24
kubectl wait --for=condition=Ready pod/nginx -n $CONSUL_NS --timeout=120s
NGINX_IP=$(kubectl get pod -n $CONSUL_NS nginx --template '{{.status.podIP}}')
kubectl exec -n $CONSUL_NS -it consul -- consul services register -address=$NGINX_IP -port=80

Check that the service has been registered.

kubectl exec -n $CONSUL_NS -it consul -- curl

3. Obtain Consul Token

If resources in the Consul registry are secured with ACLs then a token is required to access those resources. For more information about Consul ACL and how to create a token refer to the official documentation.

If the Consul is not secured with ACLs then you can skip this step.

4. Install Istio Registry Sync

Create the following values.yaml file with the correct values for your environment. Note that you use credentials to pull images that you created before.

cat <<EOF > values.yaml

publishNamespace: $SLEEP_NS

- name: tetrate-addons-creds

Run the following command to deploy istio-registry-sync to your cluster using Helm.

helm upgrade --install istio-registry-sync tis-addons/istio-registry-sync \
--namespace $TIS_NS --create-namespace \
-f values.yaml

Make sure the istio-registry-sync pod is running:

kubectl get pods -n $TIS_NS

istio-registry-sync-64f77bdb77-l9hrb 1/1 Running 0 1m

5. Verify Istio Registry Sync

Install the sleep sample app and verify that it can reach the Nginx service registered in Consul.

kubectl create ns $SLEEP_NS
kubectl label namespace $SLEEP_NS istio-injection=enabled
kubectl apply -n $SLEEP_NS -f

If everything is set up correctly, you should see the following output:

kubectl get serviceentry -n $SLEEP_NS

consul-consul ["consul"] STATIC 1m [""] STATIC 1m

This means that istio-registry-sync has successfully synced the service registered with Consul to Istio ServiceEntry.

Request to should be successful:

kubectl exec -n $SLEEP_NS -it deploy/sleep -- curl


# Delete istio-registry-sync
helm delete -n $TIS_NS istio-registry-sync

# Delete Consul
kubectl delete pod -n $CONSUL_NS consul
kubectl delete pod -n $CONSUL_NS nginx
kubectl delete ns $CONSUL_NS

# Remove sleep app
kubectl delete -n $SLEEP_NS -f
kubectl delete ns $SLEEP_NS