Kubernetes service upstreams in Consul Service mesh
Introduction
The method of addressing service upstreams depends on whether you have Consul's Transparent Proxy enabled.
When Transparent Proxy is not enabled, you must use an explicit declaration via annotation in the K8s deployment. This data element must be placed under spec.template.metadata.annotations. Here's an example of an annotation for an payment-api upstream.
apiVersion: apps/v1
kind: Deployment
spec:
template:
metadata:
annotations:
consul.hashicorp.com/connect-inject: 'true'
consul.hashicorp.com/connect-service-upstreams: 'payment-api:9091'
[...]
When Transparent Proxy is enabled, you can directly address the service in the workload without preconfiguring the deployment. This is done by either using a K8s DNS service like kube-dns or CoreDNS, or Consul Virtual IPs with Consul DNS.
In both cases, the destination hostname is constructed based on the means of reaching the upstream service. For example, if admin partitions or cluster peerings are traversed to reach the upstream service.
Transparent proxy not enabled
Here follow examples of annotations for a payment-api service.
Within an admin partition
- Same namespace, same cluster
| Explicit Declaration in K8s deployment | Connection target in application |
|---|---|
consul.hashicorp.com/connect-service-upstreams: 'payment-api:9091' | localhost:9091 |
- Across namespaces, same cluster
| Explicit Declaration in K8s deployment | Connection target in application |
|---|---|
consul.hashicorp.com/connect-service-upstreams: 'payment-api.<consul-namespace>:9091' | localhost:9091 |
- Same namespace, across cluster peering
| Explicit Declaration in K8s deployment | Connection target in application |
|---|---|
consul.hashicorp.com/connect-service-upstreams: 'payment-api:9091' | localhost:9091 |
Across admin partitions
| Explicit Declaration in K8s deployment | Connection target in application |
|---|---|
consul.hashicorp.com/connect-service-upstreams: 'payment-api.<consul-namespace>.<consul-adminpartition>:9091' | localhost:9091 |
Across K8s clusters over Consul WAN Federation
- Same namespace
| Explicit Declaration in K8s deployment | Connection target in application |
|---|---|
consul.hashicorp.com/connect-service-upstreams: 'payment-api:9091:<consul-datacenter>' | localhost:9091 |
- Across namespaces
| Explicit Declaration in K8s deployment | Connection target in application |
|---|---|
consul.hashicorp.com/connect-service-upstreams: 'payment-api.<consul-namespace>:9091:<consul-datacenter>' | localhost:9091 |
Across K8s clusters over Consul Cluster Peering
| Explicit Declaration in K8s deployment | Connection target in application |
|---|---|
consul.hashicorp.com/connect-service-upstreams: 'payment-api.svc.<consul-namespace>.ns.<consul-datacenter>-<consul-adminpartition>.peer:9091' | localhost:9091 |
Transparent proxy enabled
With Transparent Proxy enabled, you can directly address the service in the workload without preconfiguring the deployment. When choosing between the K8s DNS solutions kube-dns or CoreDNS, we recommend the latter option.
Within an admin partition
- Same namespace, same cluster
| K8S DNS | Consul DNS |
|---|---|
payment-api.<consul-namespace>.svc.cluster.local | payment-api.virtual.consul |
payment-api.virtual.<consul-namespace>.ns.<consul-datacenter>.dc.consul |
- Across namespaces, same cluster
| K8S DNS | Consul DNS |
|---|---|
payment-api.<consul-namespace>.svc.cluster.local | payment-api.virtual.<consul-namespace>.ns.<consul-datacenter>.dc.consul |
- Same namespace, across cluster peering
| K8S DNS | Consul DNS |
|---|---|
| Not supported | payment-api.virtual.consul |
payment-api.virtual.<consul-namespace>.ns.<consul-datacenter>.dc.consul |
Across admin partitions
| K8S DNS | Consul DNS |
|---|---|
| Not supported | payment-api.virtual.<consul-namespace>.ns.<consul-adminpartition>.ap.<consul-datacenter>.dc.consul |
Across K8s clusters over Consul WAN Federation
Directly addressing a service without preconfiguring the deployment is not supported across Kubernetes clusters over WAN federation.
Across K8s clusters over Consul Cluster Peering
- Same namespace
| K8S DNS | Consul DNS |
|---|---|
| Not supported | payment-api.virtual.<consul-adminpartition>.ap.<consul-clusterpeer>.peer.consul |
- Across namespaces
| K8S DNS | Consul DNS |
|---|---|
| Not supported | payment-api.virtual.<consul-namespace>.ns.<consul-adminpartition>.ap.<consul-clusterpeer>.peer.consul |