K8s service discovery hook

Simple library which implements an agent that listens for Kubernetes svc events and provides a callback to receive service metadata. It's polling the Kubernetes API endpoint /api/v1/services endpoint for services

Contributions

This is a young but very active project and absolutely needs your help. Good ways to contribute include:

• Raising bugs and feature requests
• Fixing bugs
• Improving the performance
• Adding to the documentation

Quick start

Setup

Latest stable release is 0.6 and is available on Maven Central. Just add the following dependency:

libraryDependencies ++= Seq(
  "com.github.jeroenr" %% "k8s-svc-discovery" % "0.6"
)

Or if you want to be on the bleeding edge using snapshots, latest snapshot release is 0.7-SNAPSHOT. Add the following repository and dependency:

resolvers += "Sonatype Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots/"

libraryDependencies ++= Seq(
  "com.github.jeroenr" %% "k8s-svc-discovery" % "0.7-SNAPSHOT"
)

Usage

You can simply initiate the ServiceDiscoveryAgent actor and pass an instance of KubernetesServiceDiscoveryClient along with your callback function of signature (List[T <: ServiceUpdate]) => Any

import com.github.jeroenr.service.discovery._
import com.github.jeroenr.service.discovery.health._

implicit val system = ActorSystem()

// some callback function to do something useful with the list of service updates
def handleServiceUpdates[T <: ServiceUpdate](allServiceUpdates: List[T]) = {
  println(s"Service updates: $allServiceUpdates")
}

val serviceDiscoveryAgent =
    system.actorOf(Props(new ServiceDiscoveryAgent[KubernetesServiceUpdate](new KubernetesServiceDiscoveryClient, handleServiceUpdates)))

  // start watching services
  serviceDiscoveryAgent ! ServiceDiscoveryAgent.WatchServices

Example usage in a real project: https://github.com/jeroenr/api-gateway#automatic-service-discovery

Configuration

When using this library you need to configure the Kubernetes API endpoint.

service-discovery {
  kubernetes {
    host = "localhost"
    host = ${?K8S_API_HOST}
    port = 8001 // default kube-proxy port
    port = ${?K8S_API_PORT}
    token = ""
    token = ${?K8S_API_TOKEN}  // you need a valid API token to access the Kubernetes API 
    # namespaces that are filtered down to in the client
    namespaces = ["default"] // list of namespaces to monitor
  }

  polling.interval = 2 seconds
}

Most important is to set the Kubernetes API token. Conveniently you can easily do all this through environment variables in your Kubernetes deployment descriptor.

Authenticating K8s API calls

You need a valid API token to access the Kubernetes API. There's many different options for this. My favourite is through service accounts. The steps below will create a service account and associated secret

$ kubectl create serviceaccount my-service-account
serviceaccount "my-service-account" created

Great, now a new service account has been created and under the hood also an associated secret which we can retrieve by:

$ kubectl get serviceaccounts my-service-account -o yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  # ...
secrets:
- name: my-service-account-token-1yvwg

As you can see in our example the generated secret is called "my-service-account-token-1yvwg". You can use this secret to set the value of the K8S_API_TOKEN environment variable. Example K8s deployment descriptor:

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: my-deployment
spec:
  template:
    spec:
      containers:
      - name: my-container
        image: my-container-image
        env:
        - name: K8S_API_TOKEN
          valueFrom:
            secretKeyRef:
              name: my-serviceaccount-token-secret
              key: token
        - name: K8S_API_HOST
          value: "kubernetes.default.svc.cluster.local"
        - name: K8S_API_PORT
          value: "443"
        args: [
          "-Djava.security.egd=file:/dev/./urandom",
          "-Dintegration.kubernetes.namespaces.0=my-env",
        ]