> ## Documentation Index
> Fetch the complete documentation index at: https://docs.odigos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Sources are a Custom Resource that define which Kubernetes workloads should be auto-instrumented by Odigos.

## 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](../../api-reference/odigos.io.v1alpha1#source) 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:

```yaml theme={null}
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:

```yaml theme={null}
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`:

```yaml theme={null}
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:

```yaml theme={null}
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:

```shell theme={null}
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 all of these cases, if a Source already exists, Odigos will either patch the existing Source or
return an error if it can't.