k8s-config-connector and the case for GCP resources as Kubernetes objects

Cloud resources as objects in the cluster

Config Connector is a Kubernetes add-on that allows customers to manage Google Cloud resources, Cloud Spanner or Cloud Storage among them, through the cluster's API. You describe the resources declaratively with Kubernetes-style configuration, and Config Connector creates anything new, updates anything that already exists to the specified state, and continuously keeps Google Cloud in sync with what you wrote.

That last clause is the one that separates this from a provisioning script. A script runs once and leaves whatever it created behind. A controller keeps reconciling, so a drift in the cloud resource is corrected, and a change in the manifest is pushed back out to the API. The cost of that guarantee is that you now have a controller loop and its failure modes, which is a different kind of operational surface from a one-off job.

The README is explicit that this repository contains the full source code, and it names the parts: controllers, CRDs, install bundles and sample resource configurations. So it is the whole add-on rather than a client library, which means the Kubernetes API server inside a Google Cloud cluster is running this code.

The audience is a platform team that has already decided to run on Google Cloud and wants its infrastructure to be described the same way as the rest of the estate, in YAML, in version control, reviewed like code and applied by the same deployment tooling.

The same resource model as Istio and Knative

The argument the project makes for its design is that the same resource model is the basis of Istio, of Knative, of Kubernetes itself and of the Google Cloud Services Platform. That is a deliberate positioning, and it carries a real argument rather than a slogan.

If the cloud resources are expressed as custom resources, then the tooling that already exists for Kubernetes applies to them. The same templating or customisation tool can manage a test version of an application and a production version across both Kubernetes and Google Cloud, which is the concrete benefit the README names. A team with a GitOps pipeline, a set of overlays per environment and a promotion process does not need a second mechanism for the database instance or the bucket.

The same argument explains the shape of the repository. There is an apis/ directory for the API types, an operator/ directory, pkg/ for the shared machinery, cmd/ for the entry points, config/ for the manifests, samples/ for the example resources, scripts/ and hack/ for the tooling, tests/ for the test suites, and a mockgcp/ directory used to fake Google Cloud APIs in tests. The replace directives in the go.mod file point at both the mockgcp module and the dev/tools/controllerbuilder module, so those two pieces are resolved from the working tree rather than from a published version.

That mock server is worth noting. A test suite that talks to a fake Google Cloud API can assert on reconciliation behaviour without provisioning anything, and it also means the reference rules used by the tests are the same rules the type generator applies.

The direct resource development guide changes the build loop

The first thing in the README is an announcement rather than a description, and it is about how contributors build resources.

The team launched a major improvement to how Config Connector resources are developed, and the stated effects are a significant enhancement to the reliability of the Config Connector object reconciliation and a more Kubernetes-native development experience. The guide lives in docs/develop-resources/ and is linked from the top of the README.

The reason this is the headline is that resource development is the work most projects in this space do most often. Every new Google Cloud service needs a custom resource, a controller, a CRD and a set of samples, and the quality of that work determines whether the platform is pleasant or a chore. A tooling change that improves reconciliation reliability is not a cosmetic improvement, because a flaky controller produces a cluster where the declared state and the actual state disagree intermittently, which is the worst kind of bug to debug at three in the morning.

The repository supports that work in a visible way. There is a dev/tools/controllerbuilder module in the tree, a generator that produces the typed resources, and a README.ConfigureResourceReferences.md that documents how references between resources are configured, plus a README.Samples.md for the sample side. The apichecks test suite in the tests area is run against the same reference rules the generator applies, which is what stops a generated resource from drifting away from the checked in one.

For an adopter, this matters less directly than for a contributor, but it matters for a different reason. It tells you that the project is investing in the resource authoring path rather than only in the runtime, which is what determines whether coverage keeps up with new Google Cloud services.

A fleet of images, not one controller

The Makefile shows how many distinct binaries this project builds, and the list is more informative than the README.

The images are published under a gcr.io path built from the project ID and a short commit SHA, and there is one for the builder, one for the controller, one for the recorder, one for the webhook, one for the deletion defender, one for the unmanaged detector and one for the config-connector CLI. The names in the Makefile are the controller, the recorder, the webhook, the deletiondefender, the unmanageddetector and the config-connector-cli.

Each of those has a distinct job, and together they describe the failure modes the design is built around. The recorder is what remembers the observed state of a managed resource, so the controller can tell what it created from what it merely found. The deletion defender exists because a controller that deletes a Google Cloud resource by mistake can destroy data, so there is a separate component whose job is to prevent that. The unmanaged detector finds Google Cloud resources that are not managed by Config Connector, which is the guard against adopting a resource by accident. The webhook validates incoming custom resources before they are stored.

That last group is what makes this different from a set of scripts. A controller pattern has to cope with the possibility that the object in the cluster and the object in the cloud are not the same, and the components above are the answers to the specific ways that can go wrong.

The build itself is containerised. The Docker build command uses buildx with the GitHub Actions cache in both directions, with the scope name kcc, and the comment in the Makefile explains that BuildKit is used to allow setcap in the multi-stage builds.

The build reads your project from gcloud

Two shell commands are worth knowing before you build anything, because they are how the Makefile derives the identity of the images.

The first is the project:

gcloud config get-value project

The Makefile assigns that to PROJECT_ID and then uses it to construct the image names, so the images are gcr.io with your project, the component name and the short SHA. The second is the SHA:

git rev-parse --short=7 HEAD

Seven characters, and the result is appended to every image tag, so a build is identified by commit and two builds of the same commit produce the same tag. That is the property you want for a controller, because the thing running in the cluster is traceable to a specific commit of this repository.

The Go version is not hardcoded but derived, with the Makefile reading the go directive out of the go.mod file. That file declares the module as github.com/GoogleCloudPlatform/k8s-config-connector, requires Go 1.26.0 and pins a toolchain of go1.26.4.

Two more details round out the toolchain. The linter is golangci-lint at a pinned version, v2.9.0, with the comment in the Makefile noting that the corresponding action in the GitHub Actions workflow has to be updated in step, which is the kind of note that saves an afternoon. And kustomize is not taken from the system but from the repository, with KUSTOMIZE pointing at ./bin/kustomize, so the manifests are built with a known version.

GitOps and a CLI for the parts that are not declarative

The usage section of the README is mostly pointers, and the pointers tell you where the work is.

There is the config-connector command-line tool, documented in docs/cli/README.md, and there is a guide for managing Config Connector with GitOps using ArgoCD, which covers deploying and upgrading the add-on through GitOps rather than by hand. There is a link to the documentation on choosing an installation type, which exists because there is more than one way to install the thing, and the resource reference for starter examples.

The GitOps guide is the one to read first if you run this at scale, and the reason is that Config Connector is itself a Kubernetes workload. Upgrading it is not like upgrading an application image, because the add-on includes CRDs, a webhook and several controllers, and those have to be updated in an order that keeps the cluster working. Doing that by hand is exactly the kind of task GitOps exists to remove, and the documentation points at a specific guide for it.

The CLI is the complement to the declarative model. Some operations are not resources and should not be modelled as resources, and a CLI that is documented separately from the CRDs is the right shape for that.

The repository also carries the usual governance files, a SECURITY.md, a CONTRIBUTING.md, an OWNERS file, a renovate.json for dependency updates and a golangci configuration, plus a promote.md and a version/ directory that describe how a change is promoted through the release process.

Editorial conclusion

Adopt Config Connector if your team runs workloads on Google Cloud and wants the cloud resources in the same declarative model, and in the same GitOps pipeline, as the Kubernetes objects. Do not adopt it if you need a resource that has no Config Connector kind. Verify three things first: which installation type suits your cluster, since the documentation splits the choices explicitly, that the kinds your manifests reference exist in the version you plan to pin, and that the service account the connector uses has the permissions for the resources you intend to manage. The last push was on 2026-10-19 and the newest release is v1.159.0 from 2026-10-13, so the release train is close to weekly.

Frequently asked questions

Official sources

1. GoogleCloudPlatform/k8s-config-connector on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases