feat(server-side-apply/v1-alpha): Add plugin to scaffold APIs with Server-Side Apply

Adds optional server-side-apply plugin that scaffolds APIs with controllers
using Server-Side Apply patterns. Plugin enables per-API choice between
traditional Update and Server-Side Apply approaches.

Genereted-by: Cursor/Claude

Author: camilamacedo86

.github/workflows/lint-sample.yml

@@ -28,6 +28,7 @@ jobs:
           "testdata/project-v4-multigroup",
           "docs/book/src/cronjob-tutorial/testdata/project",
           "docs/book/src/getting-started/testdata/project",
+          "docs/book/src/getting-started-ssa/testdata/project",
           "docs/book/src/multiversion-tutorial/testdata/project"
         ]
     if: (github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository)

.github/workflows/test-book.yml

@@ -4,15 +4,17 @@ on:
   push:
     paths:
       - 'docs/book/src/getting-started/testdata/project/**'
+      - 'docs/book/src/getting-started-ssa/testdata/project/**'
       - 'docs/book/src/cronjob-tutorial/testdata/project/**'
       - 'docs/book/src/multiversion-tutorial/testdata/project/**'
-      - '.github/workflows/test-e2e-book.yml'
+      - '.github/workflows/test-book.yml'
   pull_request:
     paths:
       - 'docs/book/src/getting-started/testdata/project/**'
+      - 'docs/book/src/getting-started-ssa/testdata/project/**'
       - 'docs/book/src/cronjob-tutorial/testdata/project/**'
       - 'docs/book/src/multiversion-tutorial/testdata/project/**'
-      - '.github/workflows/test-e2e-book.yml'
+      - '.github/workflows/test-book.yml'
 
 permissions: {}
 
@@ -26,6 +28,7 @@ jobs:
       matrix:
         folder: [
           "docs/book/src/getting-started/testdata/project",
+          "docs/book/src/getting-started-ssa/testdata/project",
           "docs/book/src/cronjob-tutorial/testdata/project",
           "docs/book/src/multiversion-tutorial/testdata/project"
         ]

.github/workflows/test-helm-book.yml

@@ -5,12 +5,14 @@ on:
     paths:
       - "docs/book/src/cronjob-tutorial/testdata/project/**"
       - "docs/book/src/getting-started/testdata/project/**"
+      - "docs/book/src/getting-started-ssa/testdata/project/**"
       - "docs/book/src/multiversion-tutorial/testdata/project/**"
       - ".github/workflows/test-helm-book.yml"
   pull_request:
     paths:
-      - "docs/book/src/cronjob-tutorial/testdata/project/** "
+      - "docs/book/src/cronjob-tutorial/testdata/project/**"
       - "docs/book/src/getting-started/testdata/project/**"
+      - "docs/book/src/getting-started-ssa/testdata/project/**"
       - "docs/book/src/multiversion-tutorial/testdata/project/**"
       - ".github/workflows/test-helm-book.yml"
 
@@ -26,6 +28,7 @@ jobs:
       matrix:
         folder: [
           "docs/book/src/getting-started/testdata/project",
+          "docs/book/src/getting-started-ssa/testdata/project",
           "docs/book/src/cronjob-tutorial/testdata/project",
           "docs/book/src/multiversion-tutorial/testdata/project"
         ]

docs/book/src/SUMMARY.md

@@ -122,6 +122,7 @@
     - [helm/v1-alpha](./plugins/available/helm-v1-alpha.md)
     - [helm/v2-alpha](./plugins/available/helm-v2-alpha.md)
     - [kustomize/v2](./plugins/available/kustomize-v2.md)
+    - [ssa/v1-alpha](./plugins/available/ssa-v1-alpha.md)
   - [Extending](./plugins/extending.md)
     - [CLI and Plugins](./plugins/extending/extending_cli_features_and_plugins.md)
     - [External Plugins](./plugins/extending/external-plugins.md)

docs/book/src/cronjob-tutorial/testdata/project/AGENTS.md

@@ -90,6 +90,18 @@ kubebuilder create api --group example.com --version v1alpha1 --kind Memcached \
 
 Scaffolds good-practice code: reconciliation logic, status conditions, finalizers, RBAC. Use as a reference implementation.
 
+### Server-Side Apply Plugin (scaffold controllers using Server-Side Apply)
+
+Generate a controller that uses Server-Side Apply for declarative field management:
+
+```bash
+# Example: API with Server-Side Apply
+kubebuilder create api --group <group> --version <version> --kind <Kind> \
+  --plugins=ssa/v1-alpha
+```
+
+Scaffolds a controller using Server-Side Apply patterns for conflict-free multi-actor field management.
+
 
 ### Create Webhooks
 ```bash

docs/book/src/faq.md

@@ -105,9 +105,7 @@ However, note that this problem is fixed and will not occur if you deploy the pr
 
 When attempting to run `make install` to apply the CRD manifests, the error `Too long: must have at most 262144 bytes may be encountered.` This error arises due to a size limit enforced by the Kubernetes API. Note that the `make install` target will apply the CRD manifest under `config/crd` using `kubectl apply -f -`. Therefore, when the apply command is used, the API annotates the object with the `last-applied-configuration` which contains the entire previous configuration. If this configuration is too large, it will exceed the allowed byte size. ([More info][k8s-obj-creation])
 
-In ideal approach might use client-side apply might seem like the perfect solution since with the entire object configuration doesn't have to be stored as an annotation (last-applied-configuration) on the server. However, it's worth noting that as of now, it isn't supported by controller-gen or kubebuilder. For more on this, refer to: [Controller-tool-discussion][controller-tool-pr].
-
-Therefore, you have a few options to workround this scenario such as:
+You have a few options to work around this scenario such as:
 
 **By removing the descriptions from CRDs:**
 
@@ -127,6 +125,14 @@ Your CRDs are generated using [controller-gen][controller-gen]. By using the opt
 
 You can review the design of your APIs and see if it has not more specs than should be by hurting single responsibility principle for example. So that you might to re-design them.
 
+**By using Server-Side Apply for CRD installation:**
+
+Since this issue happens when CRDs are installed with client-side apply, another option is to install or update the CRDs with Server-Side Apply instead, for example by using `kubectl apply --server-side -f ...`. This avoids storing the full manifest in the `kubectl.kubernetes.io/last-applied-configuration` annotation and can prevent the size-limit failure.
+
+If you are updating existing CRDs, `kubectl replace -f ...` may also help, depending on your workflow.
+
+Note that the [Server-Side Apply plugin][server-side-apply-plugin] is related to how controllers manage resources at runtime. It can be useful when a controller shares ownership of fields with users or other controllers, but it does not change how `make install` applies CRDs.
+
 ## How can I validate and parse fields in CRDs effectively?
 
 To enhance user experience, it is recommended to use [OpenAPI v3 schema](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schemaObject) validation when writing your CRDs. However, this approach can sometimes require an additional parsing step.
@@ -168,4 +174,4 @@ type StructName struct {
 [permission-issue]: https://github.com/kubernetes/kubernetes/issues/82573
 [permission-PR]: https://github.com/kubernetes/kubernetes/pull/89193
 [controller-gen]: ./reference/controller-gen.html
-[controller-tool-pr]: https://github.com/kubernetes-sigs/controller-tools/pull/536
+[server-side-apply-plugin]: ./plugins/available/ssa-v1-alpha.md

docs/book/src/getting-started-ssa/testdata/project/.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.8.0
+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

docs/book/src/getting-started-ssa/testdata/project/.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"
+}
+

docs/book/src/getting-started-ssa/testdata/project/.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."

docs/book/src/getting-started-ssa/testdata/project/.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