​
How Sources work

Source custom resource objects are created as a reference to a workload or namespace (“entities”).

Odigos reacts to changes in these custom resource objects to configure instrumentation for the referenced entity.

On this page, “Sources” refers to the custom resource object, while “workload”, “namespace”, or “entity” refers to the application being instrumented.

See the API Reference for the full structure of Source objects and their fields.

​
Supported Entities

Odigos supports the following Kubernetes entities:

  • Kubernetes Deployment
  • Kubernetes DaemonSet
  • Kubernetes StatefulSet
  • Kubernetes Namespace

​
Types of Sources

A Source object can be either:

  • A Workload Source, which controls instrumentation for a single workload (Deployment, DaemonSet, or StatefulSet)
  • A Namespace Source, which controls instrumentation for every workload in a namespace.

​
Workload Sources

Workload Sources specify a single workload, and the Source represents the instrumentation configuration for that workload.

Use Workload Sources to control instrumentation and configuration for individual Deployments, StatefulSets, or DaemonSets with unique requirements.

Example:

apiVersion: odigos.io/v1alpha1
kind: Source
metadata:
  name: my-workload
  namespace: default
spec:
  workload:
    kind: DaemonSet
    name: sample-app
    namespace: default

​
Namespace Sources

Namespace Sources represent instrumentation settings for an entire namespace. Namespace Sources are created by setting spec.workload.kind: Namespace along with spec.workload.name and spec.workload.namespace equal to the name of the namespace to control.

Use Namespace Sources to control instrumentation for multiple Deployments, StatefulSets, and DaemonSets from a single spot.

Example:

apiVersion: odigos.io/v1alpha1
kind: Source
metadata:
  name: my-namespace
  namespace: default
spec:
  workload:
    kind: Namespace
    name: default
    namespace: default

​
Using multiple Sources

Workload Sources are intended to be combined with Namespace Sources for flexible, fine-grained control. For example, you may choose to create a Namespace Source to enable instrumentation for namespace foo, but want to exclude deployment bar. In this case, you can create a Workload Source for deployment bar with disableInstrumentation: true:

apiVersion: odigos.io/v1alpha1
kind: Source
metadata:
  name: my-namespace
  namespace: foo
spec:
  workload:
    kind: Namespace
    name: foo
    namespace: foo
---
apiVersion: odigos.io/v1alpha1
kind: Source
metadata:
  name: exclude-bar
  namespace: foo
spec:
  disableInstrumentation: true
  workload:
    kind: Deployment
    name: bar
    namespace: foo

The opposite is also possible: you could disable instrumentation for namespace foo with a Namespace Source but choose to explicitly enable deployment bar via a Workload Source that sets disableInstrumentation: false (the default).

This is because Workload Sources take priority over Namespace Sources, and any settings in a Workload Source will override those in a parent Namespace Source.

​
Source Workflows

Sources are intended to control and configure instrumentation as objects that are completely decoupled from their target workloads. When working with Sources, they should be treated as such.

The only requirements for a Source to identify a workload are:

  • The Source must set spec.workload.name, spec.workload.namespace, and spec.workload.kind to match the workload (or namespace).
  • The Source must exist in the same namespace as the target workload (or namespace).

Besides these requirements, you are encouraged to manage your Sources as their own objects.

For example, when creating Sources from YAML manifests, consider storing them together in their own file such as sources.yaml, separate from your workload manifests. This separation of concerns allows you to declaratively control your application’s observability without tying it to your application manifests.

You should also define RBAC policies that restrict access to only what is needed to work with Source objects. In other words, your observability team may not require the ability to view deployments in a namespace to manage the instrumentation for those deployments.

For example, the following Role grants full editor permissions for Sources:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: source-editor
rules:
- apiGroups: ["odigos.io"]
  resources: ["sources"]
  verbs: ["*"]

​
Source Labels

Odigos uses mutating webhooks to automatically copy the values of spec.workload to matching labels. It is encouraged to use these labels to manage Sources in a cluster:

  • odigos.io/workload-name
  • odigos.io/workload-namespace
  • odigos.io/workload-kind

The value of these labels will be validated to always match the corresponding fields in spec.workload. They can be used to group and list Sources, for example:

kubectl get sources -l odigos.io/workload-kind=Deployment

This will list all Sources for Deployments.

​
Automatically created Sources

In some scenarios, Odigos may create Sources for you automatically.

  • When instrumenting workloads in the UI, Odigos will create a Workload Source for each workload.
  • When choosing Include future workloads in the UI, Odigos will create a Namespace Source for the namespace.
  • When creating a Source grouping in the UI, Odigos will create a Workload Source for each Workload in the group.
  • In v1.0.144+, when setting the odigos-instrumentation label on a workload or namespace, Odigos will automatically create a Source to migrate from the legacy label to Sources. Note that deleting the label will not remove the Source once it is automatically created.

In all of these cases, if a Source already exists, Odigos will either patch the existing Source or return an error if it can’t.

ConfigurationAdd Sources