dev: Add devcontainer.json configuration

.devcontainer/Dockerfile

@@ -0,0 +1,114 @@
+# Tetragon Development Container
+#
+# Provides a complete development environment for building, testing, and
+# debugging Tetragon. Includes Go, Clang/LLVM for BPF compilation, and
+# all required system libraries.
+#
+# Tool versions are kept in sync with CI (Makefile, Dockerfile, Dockerfile.clang).
+
+FROM docker.io/library/golang:1.25.7-bookworm
+
+ARG TARGETARCH
+
+# ──────────────────────────────────────────────────────────────────────────────
+# System packages required by Tetragon builds and tests
+# (mirrors Dockerfile.dev + additions for interactive development)
+# ──────────────────────────────────────────────────────────────────────────────
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    # Build essentials
+    build-essential \
+    pkg-config \
+    # BPF / kernel development
+    linux-libc-dev \
+    libelf-dev \
+    libcap-dev \
+    zlib1g-dev \
+    flex \
+    bison \
+    autoconf \
+    bc \
+    # Utilities used by Makefile / tests
+    rpm2cpio \
+    cpio \
+    git \
+    curl \
+    wget \
+    netcat-traditional \
+    file \
+    strace \
+    jq \
+    less \
+    sudo \
+    iproute2 \
+    # Editor / IDE support
+    vim \
+    # Code navigation for BPF C code
+    cscope \
+    bear \
+    # LLVM apt repository prerequisites
+    lsb-release \
+    software-properties-common \
+    gnupg \
+    && rm -rf /var/lib/apt/lists/*
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Clang/LLVM 20 (matches Dockerfile.clang)
+# Used for LOCAL_CLANG=1 BPF compilation
+# ──────────────────────────────────────────────────────────────────────────────
+RUN curl -fsSL https://apt.llvm.org/llvm-snapshot.gpg.key | gpg --dearmor -o /usr/share/keyrings/llvm-archive-keyring.gpg && \
+    echo "deb [signed-by=/usr/share/keyrings/llvm-archive-keyring.gpg] http://apt.llvm.org/bookworm/ llvm-toolchain-bookworm-20 main" \
+      > /etc/apt/sources.list.d/llvm-20.list && \
+    apt-get update && apt-get install -y --no-install-recommends \
+    clang-20 \
+    libclang-common-20-dev \
+    llvm-20 \
+    llvm-20-runtime \
+    llvm-20-linker-tools \
+    && rm -rf /var/lib/apt/lists/* \
+    && ln -sf /usr/lib/llvm-20/bin/clang /usr/bin/clang \
+    && ln -sf /usr/lib/llvm-20/bin/llc /usr/bin/llc \
+    && ln -sf /usr/bin/clang-format-18 /usr/bin/clang-format
+
+# ──────────────────────────────────────────────────────────────────────────────
+# bpftool (pre-built, with LLVM disassembler)
+# Version matches Dockerfile: v7.2.0-snapshot.0
+# ──────────────────────────────────────────────────────────────────────────────
+ARG BPFTOOL_TAG=v7.2.0-snapshot.0
+RUN ARCH=$(dpkg --print-architecture) && \
+    curl -fsSL "https://github.com/libbpf/bpftool/releases/download/${BPFTOOL_TAG}/bpftool-${BPFTOOL_TAG}-${ARCH}.tar.gz" \
+      | tar xz -C /usr/local/bin && \
+    chmod +x /usr/local/bin/bpftool
+
+# ──────────────────────────────────────────────────────────────────────────────
+# golangci-lint (matches Makefile: v2.9.0)
+# ──────────────────────────────────────────────────────────────────────────────
+ARG GOLANGCILINT_VERSION=v2.9.0
+RUN curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh \
+      | sh -s -- -b /usr/local/bin ${GOLANGCILINT_VERSION}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Go tools for development
+# ──────────────────────────────────────────────────────────────────────────────
+RUN go install golang.org/x/tools/cmd/goimports@latest && \
+    go install github.com/google/gops@v0.3.29 && \
+    go clean -cache -modcache
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Kubernetes development tools (optional, for e2e / kind workflows)
+# ──────────────────────────────────────────────────────────────────────────────
+RUN curl -fsSL https://dl.k8s.io/release/$(curl -fsSL https://dl.k8s.io/release/stable.txt)/bin/linux/$(dpkg --print-architecture)/kubectl \
+      -o /usr/local/bin/kubectl && chmod +x /usr/local/bin/kubectl && \
+    curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash && \
+    curl -fsSL -o /usr/local/bin/kind \
+      "https://kind.sigs.k8s.io/dl/v0.25.0/kind-linux-$(dpkg --print-architecture)" && \
+    chmod +x /usr/local/bin/kind
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Runtime directories expected by Tetragon
+# ──────────────────────────────────────────────────────────────────────────────
+RUN mkdir -p /var/lib/tetragon && \
+    mkdir -p /etc/tetragon/tetragon.conf.d && \
+    mkdir -p /etc/tetragon/tetragon.tp.d
+
+# Default workspace
+WORKDIR /workspaces/tetragon

.devcontainer/devcontainer.json

@@ -0,0 +1,100 @@
+{
+  "name": "Tetragon Development",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "workspaceFolder": "/workspaces/tetragon",
+
+  // BPF development requires privileged access to the kernel.
+  // This enables kprobes, BPF program loading, debugfs, and running tests.
+  "privileged": true,
+  "runArgs": [
+    "--pid=host"
+  ],
+  "capAdd": [
+    "SYS_ADMIN",
+    "SYS_PTRACE",
+    "NET_ADMIN",
+    "BPF",
+    "PERFMON"
+  ],
+
+  // Mount host kernel headers and debug filesystem for BPF development
+  "mounts": [
+    "source=/lib/modules,target=/lib/modules,type=bind,readonly",
+    "source=/sys/kernel/debug,target=/sys/kernel/debug,type=bind",
+    "source=/sys/fs/bpf,target=/sys/fs/bpf,type=bind"
+  ],
+
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        // Go development
+        "golang.go",
+        // C/C++ for BPF code
+        "llvm-vs-code-extensions.vscode-clangd",
+        // Protocol Buffers
+        "zxh404.vscode-proto3",
+        // YAML (Kubernetes manifests, TracingPolicies)
+        "redhat.vscode-yaml",
+        // Docker
+        "ms-azuretools.vscode-docker",
+        // Kubernetes
+        "ms-kubernetes-tools.vscode-kubernetes-tools",
+        // Git
+        "eamodio.gitlens",
+        // Makefile support
+        "ms-vscode.makefile-tools",
+        // EditorConfig
+        "editorconfig.editorconfig"
+      ],
+      "settings": {
+        // Go settings
+        "go.gopath": "/go",
+        "go.buildFlags": ["-mod=vendor"],
+        "go.testFlags": ["-mod=vendor", "-count=1"],
+        "go.lintTool": "golangci-lint",
+        "go.lintFlags": ["--fast"],
+        "go.useLanguageServer": true,
+        "gopls": {
+          "build.buildFlags": ["-mod=vendor"]
+        },
+
+        // C/C++ settings for BPF code
+        "clangd.arguments": [
+          "--compile-commands-dir=${workspaceFolder}",
+          "--background-index"
+        ],
+
+        // File associations
+        "files.associations": {
+          "*.h": "c",
+          "*.bpf.c": "c"
+        },
+
+        // Terminal
+        "terminal.integrated.defaultProfile.linux": "bash"
+      }
+    }
+  },
+
+  // Forwarded ports
+  "forwardPorts": [
+    54321,  // gRPC server
+    2112,   // Prometheus metrics
+    6789    // Health check
+  ],
+  "portsAttributes": {
+    "54321": { "label": "Tetragon gRPC" },
+    "2112":  { "label": "Metrics" },
+    "6789":  { "label": "Health" }
+  },
+
+  // Features
+  "features": {
+    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
+  }
+}

.devcontainer/post-create.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Post-create setup for Tetragon devcontainer.
+# Compiles BPF programs, builds Go binaries, and prepares the environment.
+
+set -euo pipefail
+
+echo "=============================================="
+echo " Tetragon Development Container Setup"
+echo "=============================================="
+
+JOBS=$(nproc)
+
+# ── Compile BPF programs (using local Clang) ────────────────────────────────
+echo ""
+echo "[1/4] Compiling BPF programs (LOCAL_CLANG=1) ..."
+make tetragon-bpf LOCAL_CLANG=1 -j"${JOBS}"
+
+# ── Build Go binaries ───────────────────────────────────────────────────────
+echo ""
+echo "[2/4] Building tetragon and tetra ..."
+make tetragon tetra -j"${JOBS}"
+
+# ── Compile tester programs ─────────────────────────────────────────────────
+echo ""
+echo "[3/4] Compiling test helper programs ..."
+make tester-progs -j"${JOBS}"
+
+# ── Copy BPF objects to runtime directory ───────────────────────────────────
+echo ""
+echo "[4/4] Installing BPF objects to /var/lib/tetragon/ ..."
+cp -f bpf/objs/*.o /var/lib/tetragon/ 2>/dev/null || true
+
+# ── Generate compile_commands.json for C/BPF IDE support ────────────────────
+if command -v bear &>/dev/null; then
+  echo ""
+  echo "[bonus] Generating compile_commands.json for IDE support ..."
+  make -C ./bpf clean
+  bear -- make tetragon-bpf LOCAL_CLANG=1 -j"${JOBS}" || true
+fi
+
+echo ""
+echo "=============================================="
+echo " Setup complete!"
+echo "=============================================="
+echo ""
+echo " Common targets:"
+echo "   make tetragon            Build the agent"
+echo "   make tetra               Build the CLI client"
+echo "   make tetragon-bpf        Compile BPF programs (uses local Clang)"
+echo "   make test                Run unit tests (requires sudo)"
+echo "   make check               Run linters"
+echo "   make format              Format Go + BPF code"
+echo "   make kind-setup          Create Kind cluster + install Tetragon"
+echo ""
+echo " BPF compilation uses LOCAL_CLANG=1 by default in this container."
+echo " For debug builds: make tetragon-bpf DEBUG=1"
+echo ""

README.md

@@ -69,8 +69,13 @@ questions and share your experiences.
 ## How to Contribute
 
 For getting started with local development, you can refer to the
-[Contribution Guide](https://tetragon.io/docs/contribution-guide/). If
-you plan to submit a PR, please ["sign-off"](https://tetragon.io/docs/contribution-guide/developer-certificate-of-origin/)
+[Contribution Guide](https://tetragon.io/docs/contribution-guide/).
+The repository includes a [devcontainer](.devcontainer/) for a
+ready-to-use development environment — open the project in VS Code and
+select **"Reopen in Container"** to get started instantly.
+
+If you plan to submit a PR, please
+["sign-off"](https://tetragon.io/docs/contribution-guide/developer-certificate-of-origin/)
 your commits.
 
 ## Adopters

docs/content/en/docs/contribution-guide/development-setup.md

@@ -4,6 +4,48 @@ weight: 1
 description: "This will help you getting started with your development setup to build Tetragon"
 ---
 
+## Development container
+
+The repository includes a [devcontainer](https://containers.dev/) configuration
+that provides a complete, pre-configured development environment with all
+required tooling (Go, Clang/LLVM, bpftool, golangci-lint, etc.).
+
+### VS Code / GitHub Codespaces
+
+1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+2. Open the Tetragon repository in VS Code.
+3. When prompted, click **"Reopen in Container"** (or run the command
+   `Dev Containers: Reopen in Container`).
+4. The container will build and automatically compile BPF programs and Go
+   binaries on first start.
+
+### CLI (devcontainer CLI)
+
+```shell
+devcontainer up --workspace-folder .
+devcontainer exec --workspace-folder . bash
+```
+
+### What's included
+
+The devcontainer runs a Debian-based image with:
+
+- **Go** matching the version in `go.mod`
+- **Clang/LLVM 20** for BPF compilation (`LOCAL_CLANG=1`)
+- **bpftool**, **golangci-lint**, **goimports**, **gops**
+- **kubectl**, **helm**, **kind** for Kubernetes development
+- **Docker-outside-of-Docker** for building container images
+
+The container runs in privileged mode with the required Linux capabilities
+(`SYS_ADMIN`, `BPF`, `PERFMON`) and kernel mounts (`/sys/kernel/debug`,
+`/sys/fs/bpf`, `/lib/modules`) for eBPF development and testing.
+
+{{< note >}}
+The devcontainer requires a Linux host (or a Linux VM on macOS) with a
+BTF-enabled kernel (5.0+). Docker Desktop on macOS and Windows provides a
+suitable Linux kernel.
+{{< /note >}}
+
 ## Building and running Tetragon
 
 For local development, you will likely want to build and run bare-metal Tetragon.