Skip to main content
Version: 16.x

Kubernetes App Discovery Architecture

Kubernetes application auto-discovery consists of two parts:

  • Periodically polling list of services in a Kubernetes cluster
  • Creating Teleport apps based on that list and proxying requests to them.
note

This will only work when the Teleport agent runs inside the target Kubernetes cluster

Polling Kubernetes services​

The Discovery Service running in a Kubernetes cluster will periodically list services and filter them out according to the matchers specified in kubernetes filed of the service config. You can filter services based on types, namespaces and service labels. Services running in the kube-system and kube-public namespaces are automatically ignored. All services by default currently are considered of an "app" type, but it can be changed for a service by Kubernetes annotation teleport.dev/discovery-type. If type of a service doesn't equal the one specified in the matcher, service is ignored.

By default name of the created Teleport app will consist of Kubernetes service name, namespace and Kubernetes cluster name: $SERVICE_NAME-$NAMESPACE-$KUBE_CLUSTER_NAME. That name can be changed by Kubernetes annotation teleport.dev/name.

Every port that is exposed by the service is considered separately, so one Kubernetes service can result in creation of multiple Teleport app resources, if more than one port is exposed on the service. In that case port name will be added to the app name.

By default, the Discovery Service will only try to expose ports that serve HTTP/HTTPS. To understand if this port serves HTTP, discovery will use several heuristics or will try to probe exposed port with a HEAD HTTP request.

Heuristics for determining if port serves HTTP/HTTPS are:

  • if Kubernetes service port definition has appProtocol field, and it contains values http/https it will be used in the URI.
  • if exposed port's name is https or it has numeric value 443, https will be used.
  • Teleport will perform HTTP request to the port to see if it serves HTTP/HTTPS requests
  • if exposed port's name is http or it has numeric value 80 or 8080, http will be used.

Otherwise, this port is ignored. But if annotation teleport.dev/protocol is used on the service and its value is "tcp", then this port will be exposed as a TCP app.

Creating Teleport apps and proxying requests to them​

After relevant Kubernetes services were listed and filtered, the Discovery Service will create Teleport apps, reconciling existing and new ones:

  • If a discovered app was not present at the Teleport backend, it will be created
  • If a discovered app was already present at the backend, it will be updated
  • If a discovered app was already present at the backend, but it was not found in the Kubernetes cluster anymore, it will be deleted.

App service runs on the Kubernetes cluster and proxies apps based on labels specified in the resources field. All apps created by the Discovery Service will have labels copied from the service of origin. In addition, label teleport.dev/kubernetes-cluster will be set for the app and it will be equal to the name of the Kubernetes cluster of origin. Discovery service uses discovery_group property to get Kubernetes cluster name.