chore: improve devcontainer experience

.devcontainer/devcontainer.json

@@ -2,25 +2,101 @@
   "name": "retina",
   "image": "mcr.microsoft.com/devcontainers/base:noble",
   "features": {
-    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
-    "ghcr.io/devcontainers/features/github-cli:1": {},
-    "ghcr.io/devcontainers/features/go:1": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2.16.1": {},
+    "ghcr.io/devcontainers/features/github-cli:1.1.0": {},
+    "ghcr.io/devcontainers/features/go:1.3.3": {
       "version": "1.24.11"
     },
-    "ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {},
-    "ghcr.io/devcontainers-extra/features/kind:1": {},
-    "ghcr.io/devcontainers/features/azure-cli:1": {}
+    "ghcr.io/devcontainers/features/kubectl-helm-minikube:1.3.1": {},
+    "ghcr.io/devcontainers-extra/features/kind:1.0.15": {},
+    "ghcr.io/devcontainers/features/azure-cli:1.2.9": {},
+    // LLVM 17 is the minimum version available for Ubuntu Noble on apt.llvm.org.
+    // Provides clang and llvm-strip needed for eBPF compilation.
+    "ghcr.io/devcontainers-community/features/llvm:3.2.0": {
+      "version": "17"
+    }
+  },
+  "hostRequirements": {
+    "cpus": 4,
+    "memory": "8gb",
+    "storage": "32gb"
+  },
+  // Persist Go module and build caches across container rebuilds.
+  "mounts": [
+    {
+      "type": "volume",
+      "source": "retina-gomodcache",
+      "target": "/go/pkg/mod"
+    },
+    {
+      "type": "volume",
+      "source": "retina-gobuildcache",
+      "target": "/home/vscode/.cache/go-build"
+    }
+  ],
+  // These commands run in parallel during container creation.
+  "onCreateCommand": {
+    // The LLVM feature installs versioned binaries (clang-17, llvm-strip-17).
+    // Create unversioned symlinks so the build system can find them.
+    "symlinks": "sudo ln -sf /usr/bin/clang-17 /usr/bin/clang && sudo ln -sf /usr/bin/llvm-strip-17 /usr/bin/llvm-strip",
+    // Fix ownership of volume mounts (created as root) and cache dirs,
+    // then download Go modules.
+    "go-setup": "sudo chown -R vscode:vscode /go /home/vscode/.cache && go mod download",
+    // Install jq (needed by some Makefile targets and scripts).
+    "apt-deps": "sudo apt-get update && sudo apt-get install -y --no-install-recommends jq && sudo rm -rf /var/lib/apt/lists/*"
+  },
+  // Wait for Docker-in-Docker to be ready, then create a Kind cluster for local testing.
+  "postStartCommand": {
+    "kind": "while ! docker info >/dev/null 2>&1; do sleep 1; done && kind create cluster 2>/dev/null || true"
+  },
+  "waitFor": "onCreateCommand",
+  "forwardPorts": [
+    9965,
+    4244,
+    10093
+  ],
+  "portsAttributes": {
+    "9965": {
+      "label": "Hubble Metrics",
+      "onAutoForward": "silent"
+    },
+    "4244": {
+      "label": "Hubble Relay",
+      "onAutoForward": "silent"
+    },
+    "10093": {
+      "label": "Retina Metrics",
+      "onAutoForward": "silent"
+    }
   },
-  "postCreateCommand": "bash .devcontainer/installMoreTools.sh && while ! docker info >/dev/null 2>&1; do sleep 1; done && kind create cluster",
   "customizations": {
     "vscode": {
       "extensions": [
-        "esbenp.prettier-vscode",
         "golang.go",
-        "mutantdino.resourcemonitor",
         "ms-vscode.makefile-tools",
-        "ms-kubernetes-tools.vscode-kubernetes-tools"
-      ]
+        "ms-kubernetes-tools.vscode-kubernetes-tools",
+        "ms-azuretools.vscode-docker",
+        "redhat.vscode-yaml",
+        "mutantdino.resourcemonitor",
+        "DavidAnson.vscode-markdownlint"
+      ],
+      "settings": {
+        "go.lintTool": "golangci-lint",
+        "go.lintFlags": [
+          "--config=.golangci.yaml",
+          "--timeout=10m"
+        ],
+        "go.formatTool": "gofumpt",
+        "files.insertFinalNewline": true,
+        "markdownlint.config": {
+          "extends": ".github/.markdownlint.json"
+        },
+        "[markdown]": {
+          "editor.codeActionsOnSave": {
+            "source.fixAll.markdownlint": "explicit"
+          }
+        }
+      }
     }
   }
 }

.github/workflows/devcontainer.yaml

@@ -0,0 +1,46 @@
+name: DevContainer
+on:
+  merge_group:
+  push:
+    branches: [main]
+    paths:
+      - ".devcontainer/**"
+      - "go.mod"
+  pull_request:
+    branches: [main]
+    paths:
+      - ".devcontainer/**"
+      - "go.mod"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build DevContainer
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Build and validate devcontainer
+        uses: devcontainers/ci@8bf61b26e9c3a98f69cb6ce2f88d24ff59b785c6 # v0.3.1900000417
+        with:
+          runCmd: |
+            clang --version
+            llvm-strip --version
+            go version
+            EXPECTED_GO=$(grep '^go ' go.mod | awk '{print $2}')
+            ACTUAL_GO=$(go version | grep -oP '\d+\.\d+\.\d+')
+            if [ "$EXPECTED_GO" != "$ACTUAL_GO" ]; then
+              echo "::error::Go version mismatch: devcontainer has $ACTUAL_GO but go.mod requires $EXPECTED_GO"
+              exit 1
+            fi
+            kubectl version --client
+            helm version
+            kind version
+            grep -rl 'go:generate.*bpf2go' pkg/plugin/ | xargs -I{} go generate {}

docs/06-Troubleshooting/bpftrace.md

@@ -5,6 +5,7 @@
 The `retina bpftrace` command allows you to trace network issues on a Kubernetes node in real-time using eBPF/bpftrace.
 
 This is useful for debugging connectivity problems such as:
+
 - Packet drops (with reason codes)
 - TCP RST events (connection resets)
 - Socket errors (ECONNREFUSED, ETIMEDOUT, etc.)
@@ -60,6 +61,7 @@ The full list of drop reasons is kernel-version specific and is printed at the s
 ### RST_SENT / RST_RECV - TCP Reset Events
 
 Captures TCP RST packets sent or received. These indicate:
+
 - Connection refused (no service listening)
 - Connection reset by peer
 - Firewall rejecting connections
@@ -78,6 +80,7 @@ Captures socket-level errors reported to applications:
 ### RETRANS - TCP Retransmissions
 
 Captures TCP segment retransmissions, which indicate:
+
 - Packet loss in the network
 - Network congestion
 - Slow or unresponsive peers

docs/08-Contributing/02-development.md

@@ -6,7 +6,22 @@ This document provides steps to set up your dev environment and start contributi
 
 Retina uses a forking workflow. To contribute, fork the repository and create a branch for your changes.
 
-The easiest way to set up your Development Environment is to use the provided GitHub Codespaces configuration.
+### Using a devcontainer (recommended)
+
+The easiest way to get started is to use the provided [devcontainer](https://github.com/microsoft/retina/blob/main/.devcontainer/devcontainer.json), which works with both [GitHub Codespaces](https://github.com/features/codespaces) and [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers).
+
+The devcontainer comes pre-configured with all required tools:
+
+- Go, clang/LLVM (for eBPF compilation), Docker, Helm, kubectl, Kind, Azure CLI, GitHub CLI, and jq
+- Go modules are pre-downloaded; run `make generate` to compile eBPF programs and generate mocks before building
+- A Kind cluster is created on startup for local testing
+- VS Code is configured with golangci-lint and gofumpt so editor feedback matches CI
+
+To launch in Codespaces, click **Code > Codespaces > New codespace** on the repository page. To use locally, open the repository in VS Code and select **Reopen in Container** from the command palette.
+
+### Manual setup
+
+If you prefer to set up your environment manually, see the requirements below.
 
 ## Environment Config