Jaeger Operator for Kubernetes

Installing the operator on Kubernetes

Note	Make sure your kubectl command is properly configured to talk to a valid Kubernetes cluster. If you don’t have one yet, check minikube out.

To install the operator, run:

kubectl create -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/rbac.yaml
kubectl create -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/crd.yaml
kubectl create -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/operator.yaml

At this point, there should be a jaeger-operator deployment available:

$ kubectl get deployment jaeger-operator
NAME              DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
jaeger-operator   1         1         1            1           48s

The operator is now ready to create Jaeger instances!

Installing the operator on OpenShift

The instructions from the previous section also work on OpenShift, but make sure to install the RBAC rules, the CRD and the operator as a privileged user, such as system:admin.

oc login -u system:admin

oc create -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/rbac.yaml
oc create -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/crd.yaml
oc create -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/operator.yaml

Once the operator is installed, grant the role jaeger-operator to users who should be able to install individual Jaeger instances. The following example creates a role binding allowing the user developer to create Jaeger instances:

oc create \
  rolebinding developer-jaeger-operator \
  --role=jaeger-operator \
  --user=developer

After the role is granted, switch back to a non-privileged user.

Creating a new Jaeger instance

The simplest possible way to install is by creating a YAML file like the following:

simplest.yaml

apiVersion: io.jaegertracing/v1alpha1
kind: Jaeger
metadata:
  name: simplest

The YAML file can then be used with kubectl:

kubectl apply -f simplest.yaml

In a few seconds, a new in-memory all-in-one instance of Jaeger will be available, suitable for quick demos and development purposes. To check the instances that were created, list the jaeger objects:

$ kubectl get jaeger
NAME        CREATED AT
simplest    28s

To get the pod name, query for the pods belonging to the simplest Jaeger instance:

$ kubectl get pods -l jaeger=simplest
NAME                        READY     STATUS    RESTARTS   AGE
simplest-6499bb6cdd-kqx75   1/1       Running   0          2m

Similarly, the logs can be queried either from the pod directly using the pod name obtained from the previous example, or from all pods belonging to our instance:

$ kubectl logs -l jaeger=simplest
...
{"level":"info","ts":1535385688.0951214,"caller":"healthcheck/handler.go:133","msg":"Health Check state change","status":"ready"}

For reference, here’s how a more complex all-in-one instance can be created:

all-in-one.yaml

apiVersion: io.jaegertracing/v1alpha1
kind: Jaeger
metadata:
  name: my-jaeger
spec:
  strategy: all-in-one # (1)
  all-in-one:
    image: jaegertracing/all-in-one:1.7 # (2)
    options: # (3)
      log-level: debug # (4)
      memory: # (5)
        max-traces: 100000
    ingress:
      enabled: false # (6)
  agent:
    strategy: DaemonSet # (7)

1. The default strategy is all-in-one. The only other possible value is production.

2. The image to use, in a regular Docker syntax

3. The options to be passed verbatim to the underlying binary.Refer to the Jaeger documentation and/or to the --help option from the related binary for all the available options

4. The option is a simple key: value map. In this case, we want the option --log-level=debug to be passed to the binary.

5. Some options are namespaced and we can alternatively break them into nested objects. We could have specified memory.max-traces: 100000.

6. By default, an ingress object is created for the query service. It can be disabled by setting its enabled option to false. This is also available for the query spec.

7. By default, the operator assumes that agents are deployed as sidecars within the target pods. Specifying the strategy as "DaemonSet" changes that and makes the operator deploy the agent as DaemonSet. Note that your tracer client will probably have to override the "JAEGER_AGENT_HOST" env var to use the node’s IP.

Accessing the UI

The operator creates a Kubernetes ingress route, which is the Kubernetes' standard for exposing a service to the outside world, but it comes with no Ingress providers by default. Check the documentation on what’s the most appropriate way to achieve that for your platform, but the following commands should provide a good start on minikube:

minikube addons enable ingress

Once that is done, the UI can be found by querying the Ingress object:

$ kubectl get ingress
NAME             HOSTS     ADDRESS          PORTS     AGE
simplest-query   *         192.168.122.34   80        3m

In this example, the Jaeger UI is available at http://192.168.122.34

OpenShift

For OpenShift, the preferred approach is to create a route object that will expose the UI under a specific address:

oc create route edge --service simplest-query --port 16686

Check the hostname/port with the following command:

oc get routes

Note	make sure to use https with the hostname/port you get from the command above, otherwise you’ll see a message like: "Application is not available".

Auto injection of Jaeger Agent sidecars

The operator can also inject Jaeger Agent sidecars in Deployment workloads, provided that the deployment has the annotation inject-jaeger-agent with a suitable value. The values can be either "true" (as string), or the Jaeger instance name, as returned by kubectl get jaegers. When "true" is used, there should be exactly one Jaeger instance for the same namespace as the deployment, otherwise, the operator can’t figure out automatically which Jaeger instance to use.

The following snippet shows a simple application that will get a sidecar injected, with the Jaeger Agent pointing to the single Jaeger instance available in the same namespace:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  annotations:
    inject-jaeger-agent: "true" # (1)
spec:
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: acme/myapp:myversion

1. Either "true" (as string) or the Jaeger instance name

Agent as DaemonSet

By default, the Operator expects the agents to be deployed as sidecars to the target applications. This is convenient for several purposes, like in a multi-tenant scenario or to have better load balancing, but there are scenarios where it’s desirable to install the agent as a DaemonSet. In that case, specify the Agent’s strategy to DaemonSet, as follows:

apiVersion: io.jaegertracing/v1alpha1
kind: Jaeger
metadata:
  name: my-jaeger
spec:
  agent:
    strategy: DaemonSet

Important

if you attempt to install two Jaeger instances on the same cluster with DaemonSet as the strategy, only one will end up deploying a DaemonSet, as the agent is required to bind to well-known ports on the node. Because of that, the second daemon set will fail to bind to those ports.

Your tracer client will then most likely need to be told where the agent is located. This is usually done by setting the env var JAEGER_AGENT_HOST and should be set to the value of the Kubernetes node’s IP, like:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: acme/myapp:myversion
        env:
        - name: JAEGER_AGENT_HOST
          valueFrom:
            fieldRef:
              fieldPath: status.hostIP

Removing an instance

To remove an instance, just use the delete command with the file used for the instance creation:

kubectl delete -f simplest.yaml

Alternatively, you can remove a Jaeger instance by running:

kubectl delete jaeger simplest

Note	deleting the instance will not remove the data from a permanent storage used with this instance. Data from in-memory instances, however, will be lost.

Uninstalling the operator

Similar to the installation, just run:

kubectl delete -f deploy/operator.yaml
kubectl delete -f deploy/rbac.yaml