feat: add kubernetes client-gen tool support

[solidDoWant]

This patch introduces support for the Kubernetes client-gen tool, enabling the automated generation of Go clients for all custom resources defined by cloudnative-pg CRDs.

Closes #6585

Release notes

Added support for Kubernetes client-gen, allowing the automated generation of Go clients for all custom resources defined by cloudnative-pg CRDs.

[github-actions]

❗ By default, the pull request is configured to backport to all release branches.

• To stop backporting this pr, remove the label: backport-requested ◀️ or add the label 'do not backport'
• To stop backporting this pr to a certain release branch, remove the specific branch label: release-x.y

[sxd]

Hi @solidDoWant

Can you create some kind of explanation how to reproduce what you're talking about? also probably this may deserve at least some documentation showing how users can use this for their own purposes.

Regards!

[solidDoWant]

Sure thing @sxd! Here's an how I am generating a client-go based client for interacting with CNPG via a Go tool I'm writing.

Note that the git references can be updated to point to a release tag, another commit, another repo, etc.

---

The kubernetes/code-generator project can be used to create a Go client for controllers who have Go structs defined for CRDs. This requires +genclient comments on the CRD structs, which CNPG provides.

Here's an example of how to generate a CNPG Go client for your project:

#!/bin/bash

# 1. Download the codegen script. Note that using the script outside of a Go module directory requires a change that has been merged, but not released yet.
curl -fsSL -o /tmp/kube_codegen.sh https://raw.githubusercontent.com/kubernetes/code-generator/e7e5741e3a3ed0043276619b3f8026526dbed675/kube_codegen.sh


# 2. Clone the CNPG repository
git clone --quiet --branch v1.25.0 --single-branch https://github.com/cloudnative-pg/cloudnative-pg.git /tmp/cnpg-repo

# 3. Create a Go project for use with the client (optional, this can be replaced with an existing project)
mkdir /tmp/cnpg-client-example
pushd /tmp/cnpg-client-example
go mod init github.com/example/cnpg-client-example

# 4. Generate the client
# The generator may produce a `grep: /tmp/cnpg-client-example/generated/clientset: No such file or directory` error, which can be safely ignored.
pushd /tmp/cnpg-repo
KUBE_CODEGEN_TAG=latest . /tmp/kube_codegen.sh
kube::codegen::gen_client --output-dir /tmp/cnpg-client-example/generated --output-pkg github.com/example/cnpg-client-example/generated --boilerplate /dev/null .

# 4.1 FOR THIS PR ONLY, because the change hasn't merged yet, the generated files need to be patched to include the effects of this PR. This should not be included in any docs, as it is unnecessary with these changes.
find /tmp/cnpg-client-example/generated -type f -name '*.go' -exec sed -i 's/SchemeGroupVersion/GroupVersion/' {} \;

# 5. Use the client (optional)
# This example program will list CNPG clusters in the "default" namespace, using a kubeconfig file at `~/.kube/config`.
popd
go get "k8s.io/client-go" # Add deps
go mod tidy
cat << EOF > main.go
package main

import (
	"context"
	"log"
	"os"
	"path/filepath"

	"github.com/example/cnpg-client-example/generated/clientset/versioned"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/client-go/tools/clientcmd"
)

// Adjust these as needed
var kubeconfigPath = filepath.Join(os.Getenv("HOME"), ".kube", "config")
var namespace = "default"

func main() {
	// Simplified but fairly standard way to load a kubeconfig
	config, err := clientcmd.BuildConfigFromFlags("", kubeconfigPath)
	if err != nil {
		log.Fatalf("unable to load kubeconfig from %s: %v", kubeconfigPath, err)
	}

	cnpgClient := versioned.NewForConfigOrDie(config)
	clusters, err := cnpgClient.PostgresqlV1().Clusters(namespace).List(context.Background(), metav1.ListOptions{})
	if err != nil {
		log.Fatalf("unable to list clusters: %v", err)
	}

	for _, cluster := range clusters.Items {
		log.Printf("Cluster: %s", cluster.Name)
	}
}
EOF

Output:

vscode ➜ /tmp/cnpg-client-example $ go run main.go
2025/01/31 20:52:21 Cluster: testing

---

It would be really convenient if the CNPG project managed a generated client, rather than having every consumer maintain (an essentially identical) one. This is what most other projects that I worked with do. Examples:

• cert-manager: https://github.com/cert-manager/cert-manager/tree/master/pkg/client/clientset/versioned
• external-snapshotter: https://github.com/kubernetes-csi/external-snapshotter/tree/master/client/clientset/versioned
• kubernetes: https://github.com/kubernetes/client-go/tree/master/kubernetes

I would be open to adding this feature myself in another PR if CNPG would accept this work. Depending on how CNPG would want this implemented, it could be as easy as adding a single makefile target.

[mnencia]

For reference, here is the issue in Kubebuilder where they are proposing the change to the default scaffolding: kubernetes-sigs/kubebuilder#3692

[mnencia]

I removed this as they are already in the doc.go file

[mnencia]

/test tl=4 d=push

[github-actions]

@mnencia, here's the link to the E2E on CNPG workflow run: https://github.com/cloudnative-pg/cloudnative-pg/actions/runs/13131948187

[mnencia]

/ok-to-merge E2E ok