TargetSource

A TargetSource reads network devices from an external system and turns them into Target resources. The operator then treats those Target resources like any other: a Pipeline selects them and the Cluster controller pushes them to the gNMIc collectors.

On every run the controller fetches the complete inventory, works out which Target resources to create, update and delete, applies the differences, and writes its status once. Nothing is kept between runs, so a restart loses nothing and a failure cannot leave discovery silently stopped.

Basic configuration

apiVersion: operator.gnmic.dev/v1alpha1
kind: TargetSource
metadata:
  name: inventory
spec:
  interval: 5m
  source:
    type: HTTP
    http:
      url: https://inventory.example.com/api/devices
      auth:
        token:
          secretRef: { name: inventory, key: token }
      mapping:
        items: self.results
        name: item.hostname
        address: item.mgmt_ip
  target:
    profile: default

That is a complete, typical resource. Everything not shown has a default.

Spec fields

target

prune

How a device becomes a Target

1. Defaults. A device without a port gets target.port; one without a profile gets target.profile.
2. Labels. target.labels, then the labels from the source, then the reserved operator labels operator.gnmic.dev/targetsource and operator.gnmic.dev/managed-by, which always win.
3. Sanitising. Every label key and value is made valid: invalid characters become -, values are cut to 63 characters. The original is kept on the Target as the annotation operator.gnmic.dev/label.<key>, and the device is counted in status.sanitized.
4. Naming. The resource is named <targetsource>-<device name>, lowercased and normalised to a valid Kubernetes name. The name the source reported is kept as the annotation operator.gnmic.dev/discovered-name. Two devices that normalise to the same name are reported as DuplicateName; the one whose name sorts first wins.
5. Apply. Each Target is written with server-side apply. Only the fields the source sets are owned: spec.address, spec.profile, the source’s labels and annotations, and the owner reference. Labels and annotations you add to a discovered Target survive every run. A label the source also sets is the source’s and is overwritten.

Renaming the TargetSource renames every Target it manages, and with them the target names gNMIc uses. Treat the name as part of the data plane.

Pruning and its guards

A managed Target whose device is no longer returned is deleted, unless one of three guards holds. None of them is permanent: each clears as soon as the source returns a complete, non-empty, plausible answer, and the run keeps its normal interval.

Ownership and deletion

Every managed Target carries a controller owner reference to its TargetSource. Deleting the TargetSource deletes its Target resources through garbage collection. There is no finalizer.

A Target that already exists under a wanted name and is not owned by this TargetSource is left alone. The device is counted in status.conflicted, the Conflicted condition is set, and an event is recorded.

A managed Target that you delete by hand comes back on the next run.

Status

$ kubectl get targetsources
NAME        TYPE   TARGETS   READY   LAST SYNC   AGE
inventory   HTTP   142       True    2m          3d

Conditions

Retries

After a failed run the next one is scheduled at interval, doubling on each consecutive failure, capped at ten times interval. A source polled every five minutes backs off from five to fifty minutes. A Stalled source waits at the cap; a change to the spec or to a referenced Secret or ConfigMap triggers a run at once.

Reacting faster than the interval

• A change to a ConfigMap or Secret the spec names, whether it is the source itself or holds credentials, triggers a run at once.
• The webhook lets the source itself ask for a run.

Metrics

gnmic_operator_targetsource_sync_duration_seconds{namespace,name,type}
gnmic_operator_targetsource_sync_total{namespace,name,type,result}
gnmic_operator_targetsource_last_success_timestamp_seconds{namespace,name}
gnmic_operator_targetsource_targets{namespace,name,state}

result is success, failure or held (a prune guard). state is managed, invalid or conflicted. Alert on the last-success timestamp not moving for three intervals.

Operator flags