chore: scaffold kubebuilder operator

.custom-gcl.yml

@@ -0,0 +1,11 @@
+# This file configures golangci-lint with module plugins.
+# When you run 'make lint', it will automatically build a custom golangci-lint binary
+# with all the plugins listed below.
+#
+# See: https://golangci-lint.run/plugins/module-plugins/
+version: v2.11.4
+plugins:
+  # logcheck validates structured logging calls and parameters (e.g., balanced key-value pairs)
+  - module: "sigs.k8s.io/logtools"
+    import: "sigs.k8s.io/logtools/logcheck/gclplugin"
+    version: latest

.devcontainer/devcontainer.json

@@ -0,0 +1,35 @@
+{
+  "name": "Kubebuilder DevContainer",
+  "image": "golang:1.25",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {
+      "moby": false,
+      "dockerDefaultAddressPool": "base=172.30.0.0/16,size=24"
+    },
+    "ghcr.io/devcontainers/features/git:1": {},
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "upgradePackages": true
+    }
+  },
+
+  "runArgs": ["--privileged", "--init"],
+
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.shell.linux": "/bin/bash"
+      },
+      "extensions": [
+        "ms-kubernetes-tools.vscode-kubernetes-tools",
+        "ms-azuretools.vscode-docker"
+      ]
+    }
+  },
+
+  "remoteEnv": {
+    "GO111MODULE": "on"
+  },
+
+  "onCreateCommand": "bash .devcontainer/post-install.sh"
+}
+

.devcontainer/post-install.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "===================================="
+echo "Kubebuilder DevContainer Setup"
+echo "===================================="
+
+# Verify running as root (required for installing to /usr/local/bin and /etc)
+if [ "$(id -u)" -ne 0 ]; then
+  echo "ERROR: This script must be run as root"
+  exit 1
+fi
+
+echo ""
+echo "Detecting system architecture..."
+# Detect architecture using uname
+MACHINE=$(uname -m)
+case "${MACHINE}" in
+  x86_64)
+    ARCH="amd64"
+    ;;
+  aarch64|arm64)
+    ARCH="arm64"
+    ;;
+  *)
+    echo "WARNING: Unsupported architecture ${MACHINE}, defaulting to amd64"
+    ARCH="amd64"
+    ;;
+esac
+echo "Architecture: ${ARCH}"
+
+echo ""
+echo "------------------------------------"
+echo "Setting up bash completion..."
+echo "------------------------------------"
+
+BASH_COMPLETIONS_DIR="/usr/share/bash-completion/completions"
+
+# Enable bash-completion in root's .bashrc (devcontainer runs as root)
+if ! grep -q "source /usr/share/bash-completion/bash_completion" ~/.bashrc 2>/dev/null; then
+  echo 'source /usr/share/bash-completion/bash_completion' >> ~/.bashrc
+  echo "Added bash-completion to .bashrc"
+fi
+
+echo ""
+echo "------------------------------------"
+echo "Installing development tools..."
+echo "------------------------------------"
+
+# Install kind
+if ! command -v kind &> /dev/null; then
+  echo "Installing kind..."
+  curl -Lo /usr/local/bin/kind "https://kind.sigs.k8s.io/dl/latest/kind-linux-${ARCH}"
+  chmod +x /usr/local/bin/kind
+  echo "kind installed successfully"
+fi
+
+# Generate kind bash completion
+if command -v kind &> /dev/null; then
+  if kind completion bash > "${BASH_COMPLETIONS_DIR}/kind" 2>/dev/null; then
+    echo "kind completion installed"
+  else
+    echo "WARNING: Failed to generate kind completion"
+  fi
+fi
+
+# Install kubebuilder
+if ! command -v kubebuilder &> /dev/null; then
+  echo "Installing kubebuilder..."
+  curl -Lo /usr/local/bin/kubebuilder "https://go.kubebuilder.io/dl/latest/linux/${ARCH}"
+  chmod +x /usr/local/bin/kubebuilder
+  echo "kubebuilder installed successfully"
+fi
+
+# Generate kubebuilder bash completion
+if command -v kubebuilder &> /dev/null; then
+  if kubebuilder completion bash > "${BASH_COMPLETIONS_DIR}/kubebuilder" 2>/dev/null; then
+    echo "kubebuilder completion installed"
+  else
+    echo "WARNING: Failed to generate kubebuilder completion"
+  fi
+fi
+
+# Install kubectl
+if ! command -v kubectl &> /dev/null; then
+  echo "Installing kubectl..."
+  KUBECTL_VERSION=$(curl -Ls https://dl.k8s.io/release/stable.txt)
+  curl -Lo /usr/local/bin/kubectl "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/${ARCH}/kubectl"
+  chmod +x /usr/local/bin/kubectl
+  echo "kubectl installed successfully"
+fi
+
+# Generate kubectl bash completion
+if command -v kubectl &> /dev/null; then
+  if kubectl completion bash > "${BASH_COMPLETIONS_DIR}/kubectl" 2>/dev/null; then
+    echo "kubectl completion installed"
+  else
+    echo "WARNING: Failed to generate kubectl completion"
+  fi
+fi
+
+# Generate Docker bash completion
+if command -v docker &> /dev/null; then
+  if docker completion bash > "${BASH_COMPLETIONS_DIR}/docker" 2>/dev/null; then
+    echo "docker completion installed"
+  else
+    echo "WARNING: Failed to generate docker completion"
+  fi
+fi
+
+echo ""
+echo "------------------------------------"
+echo "Configuring Docker environment..."
+echo "------------------------------------"
+
+# Wait for Docker to be ready
+echo "Waiting for Docker to be ready..."
+for i in {1..30}; do
+  if docker info >/dev/null 2>&1; then
+    echo "Docker is ready"
+    break
+  fi
+  if [ "$i" -eq 30 ]; then
+    echo "WARNING: Docker not ready after 30s"
+  fi
+  sleep 1
+done
+
+# Create kind network (ignore if already exists)
+if ! docker network inspect kind >/dev/null 2>&1; then
+  if docker network create kind >/dev/null 2>&1; then
+    echo "Created kind network"
+  else
+    echo "WARNING: Failed to create kind network (may already exist)"
+  fi
+fi
+
+echo ""
+echo "------------------------------------"
+echo "Verifying installations..."
+echo "------------------------------------"
+kind version
+kubebuilder version
+kubectl version --client
+docker --version
+go version
+
+echo ""
+echo "===================================="
+echo "DevContainer ready!"
+echo "===================================="
+echo "All development tools installed successfully."
+echo "You can now start building Kubernetes operators."

.dockerignore

@@ -0,0 +1,11 @@
+# More info: https://docs.docker.com/engine/reference/builder/#dockerignore-file
+# Ignore everything by default and re-include only needed files
+**
+
+# Re-include Go source files (but not *_test.go)
+!**/*.go
+**/*_test.go
+
+# Re-include Go module files
+!go.mod
+!go.sum

.github/workflows/lint.yml

@@ -0,0 +1,29 @@
+name: Lint
+
+on:
+  push:
+  pull_request:
+
+permissions: {}
+
+jobs:
+  lint:
+    permissions:
+      contents: read
+    name: Run on Ubuntu
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
+        with:
+          go-version-file: go.mod
+
+      - name: Check linter configuration
+        run: make lint-config
+      - name: Run linter
+        run: make lint

.github/workflows/test-e2e.yml

@@ -0,0 +1,38 @@
+name: E2E Tests
+
+on:
+  push:
+  pull_request:
+
+permissions: {}
+
+jobs:
+  test-e2e:
+    permissions:
+      contents: read
+    name: Run on Ubuntu
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
+        with:
+          go-version-file: go.mod
+
+      - name: Install the latest version of kind
+        run: |
+          curl -Lo ./kind https://kind.sigs.k8s.io/dl/latest/kind-linux-$(go env GOARCH)
+          chmod +x ./kind
+          sudo mv ./kind /usr/local/bin/kind
+
+      - name: Verify kind installation
+        run: kind version
+
+      - name: Running Test e2e
+        run: |
+          go mod tidy
+          make test-e2e

.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+permissions: {}
+
+jobs:
+  test:
+    permissions:
+      contents: read
+    name: Run on Ubuntu
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
+        with:
+          go-version-file: go.mod
+
+      - name: Running Tests
+        run: |
+          go mod tidy
+          make test

.gitignore

@@ -4,6 +4,7 @@
 *.dll
 *.so
 *.dylib
+bin/
 
 # Test binary, built with `go test -c`
 *.test

.golangci.yml

@@ -0,0 +1,61 @@
+version: "2"
+run:
+  allow-parallel-runners: true
+linters:
+  default: none
+  enable:
+    - copyloopvar
+    - dupl
+    - errcheck
+    - ginkgolinter
+    - goconst
+    - gocyclo
+    - govet
+    - ineffassign
+    - lll
+    - modernize
+    - misspell
+    - nakedret
+    - prealloc
+    - revive
+    - staticcheck
+    - unconvert
+    - unparam
+    - unused
+    - logcheck
+  settings:
+    custom:
+      logcheck:
+        type: "module"
+        description: Checks Go logging calls for Kubernetes logging conventions.
+    revive:
+      rules:
+        - name: comment-spacings
+        - name: import-shadowing
+    modernize:
+      disable:
+        - omitzero
+  exclusions:
+    generated: lax
+    rules:
+      - linters:
+          - lll
+        path: api/*
+      - linters:
+          - dupl
+          - lll
+        path: internal/*
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+formatters:
+  enable:
+    - gofmt
+    - goimports
+  exclusions:
+    generated: lax
+    paths:
+      - third_party$
+      - builtin$
+      - examples$