Injector Dev

injector-dev

injector-dev is a CLI that turns the manual loop of build image → push → manage a cluster → deploy workloads by hand into a single declarative command. You describe a scenario in YAML — which Agent components to deploy, how to configure them, and what test workloads to run — and injector-dev apply brings the whole environment up on a local Kubernetes cluster.

Scenarios are reproducible and shareable: tear an environment down and recreate it identically at any time.

When to use this skill

• Iterating on local datadog-agent, datadog-operator, or Helm chart changes and needing them running on a real cluster.
• Reproducing an APM auto-instrumentation / injection bug locally.
• Writing, editing, or debugging a scenario.yaml.
• Pinning a test environment against a specific released version, a CI pipeline artifact, or the agent main branch.

Prerequisites

• A local Kubernetes platform. Supported drivers: kind (recommended), colima, minikube, nvkind, and none (use an existing cluster/context). kind is fast, reliable across machines, and the easiest to reset. There is also a workspace driver that runs the cluster on a remote Datadog Workspace VM — see Remote clusters.
• A Docker runtime installed and running.
• helm and kubectl on your PATH. kind must be installed to use the recommended kind platform.
• Datadog API + App keys (a real API key is needed for the Agent to report). Set them however you prefer:

  export DD_API_KEY="<your-api-key>"
  export DD_APP_KEY="<your-app-key>"

If you already have colima and/or minikube running, shut them down before using injector-dev to avoid conflicts.

Installation

git clone https://github.com/DataDog/injector-dev
cd injector-dev
make install   # builds and installs the binary to /usr/local/bin (uses sudo)

Configuration (~/.injector-dev/config.yaml)

A practical starting config:

---
platform: kind              # kind (recommended) | colima | minikube | nvkind | workspace | none
builder:
  code_root: "/Users/<USER>/dd"   # parent dir containing datadog-agent/, auto_inject/, datadog-operator/, ...
  dev_container:
    name: "injector-dev-builder"
    enabled: true
    persist: true           # keep the build container alive between builds → much faster rebuilds
installer:
  repo_root: "/Users/<USER>/dd/injector-dev"
  # api_key / app_key are optional here; DD_API_KEY / DD_APP_KEY env vars are the fallback.

Key points:

• builder.code_root — parent directory holding your component repos. The tool derives each repo path as code_root/<repo-name> (e.g. code_root/datadog-agent), so all repos must be siblings under this dir.
• builder.dev_container.persist: true — leaves the build container running between applies. First build takes several minutes (installing deps); later builds drop to ~30 seconds.
• installer.repo_root — path to your local injector-dev checkout.
• Every config key can be overridden by env var: prefix with INJECTOR_DEV_ and replace dots with underscores, e.g. INJECTOR_DEV_INSTALLER_API_KEY, INJECTOR_DEV_BUILDER_CODE_ROOT.
• API/App key resolution order: config.yaml (installer.api_key/app_key) → then DD_API_KEY / DD_APP_KEY env vars.

Profiles (multiple configs)

To manage several environments (staging, sandbox, org2, …), drop additional config files at ~/.injector-dev/<profile>.yaml and select one per command:

injector-dev apply -f scenario.yaml --profile sandbox

Omitting --profile uses config.yaml.

Remote clusters: the workspace platform

Instead of a local cluster, injector-dev can run the kind cluster on a remote Datadog Workspace VM. Image builds still happen locally — only the cluster and workloads run on the workspace. Useful when your laptop is resource-constrained or you want a beefier, disposable environment.

How it works: docker build runs locally; the image is streamed to the workspace (docker save | ssh … kind load); kind is installed on the workspace automatically on first use (workspaces ship with docker but not kind); and the remote cluster's API server is exposed to your machine through a persistent SSH tunnel, with an injector-dev-ws-<name> context merged into ~/.kube/config and made current — so local kubectl/helm/k9s work against it transparently.

Prerequisites

• A workspace reachable over SSH as ssh workspace-<name> (be connected to Appgate). Create one with:

  workspaces create <name> --repo dd/datadog-agent

  injector-dev does not create the workspace; if it's missing it fails fast and prints this command.
• Local docker for building images, as usual. The workspace only needs docker (kind is installed for you).

Selecting the workspace

The workspace name comes from the --workspace flag or a scenario's platform.workspace (flag wins). It is intentionally not read from the global config.yaml.

In a scenario (picked up by apply):

platform:
  type: workspace
  workspace: firstname-lastname   # SSH host = workspace-firstname-lastname
  name: my-cluster                # optional kind cluster name on the VM (default: "kind")
  reset: false
helm:
  # ... same as any other scenario ...

Or by flag — required for start/stop/reset, which don't read a scenario:

injector-dev apply -f scenario.yaml --workspace firstname-lastname --build
injector-dev stop  --platform=workspace --workspace firstname-lastname

Usage

# bring the remote cluster up + deploy (build local, load remote)
injector-dev apply -f scenario.yaml --workspace <name> --build

# local kubectl now targets the remote cluster through the tunnel
kubectl get pods -A

# tear down the remote cluster, tunnel, and kube-context
injector-dev stop --platform=workspace --workspace <name>

Notes

• start/apply are non-destructive when the cluster already exists: they reuse it and just re-establish the tunnel and switch your kube-context (so apply --reset=false still re-points kubectl at the workspace).
• The SSH tunnel is persistent (survives after the command exits) so local kubectl keeps working. injector-dev stop closes it.
• Inspect open tunnels: ls ~/.injector-dev/*.sock, and check one with ssh -O check -S ~/.injector-dev/workspace-<name>.sock workspace-<name>.
• You can also inspect the cluster on the workspace directly: ssh workspace-<name> then kubectl (kind writes a kubeconfig there too).

The core loop: apply

apply is the primary command. It (optionally) resets/starts the cluster, installs the Datadog stack via Helm or the Operator, deploys any apps/manifests, and waits for health.

injector-dev apply -f workloads/my-feature/scenario.yaml            # deploy
injector-dev apply -f workloads/my-feature/scenario.yaml --build    # build local source first

apply flags

Scenario files

A scenario is helm: or operator:, optionally preceded by a platform: block. Keep each scenario in its own directory alongside its manifests:

workloads/
├── hello-world/
│   └── scenario.yaml
├── my-feature/
│   ├── scenario.yaml
│   └── redis.yaml

Generate a starter template with injector-dev new --type helm --output scenario.yaml (add --edit to open it in $EDITOR).