OpenParable
Skip to content
← Back to skills

Kcc Direct Brownfield Types Implementer

Development
kcc-direct-brownfield-types-implementer

Kcc Direct Brownfield Types Implementer is an Agent Skill for development published in the GoogleCloudPlatform/k8s-config-connector repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guides the implementation of KRM types and CRD scaffolding for migrating existing resources to "direct" controllers.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/GoogleCloudPlatform/k8s-config-connector/blob/HEAD/.gemini/skills/kcc-direct-brownfield-types-implementer/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/kcc-direct-brownfield-types-implementer, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

KCC Direct Brownfield Types Implementer

This skill provides the mandatory standards for creating the initial KRM types (_types.go) and generation scripts (generate.sh) when migrating an existing (brownfield) resource to the direct controller approach.

Workflow

1. Configure generate.sh

Create or update apis/<service>/v1alpha1/generate.sh. Use a versioned proto source path to ensure stability.

#!/bin/bash
set -o errexit
set -o nounset
set -o pipefail

REPO_ROOT="$(git rev-parse --show-toplevel)"
cd ${REPO_ROOT}/dev/tools/controllerbuilder

# Use the pinned SHA from apis/git.versions or a specific override
PROTO_SHA="<sha>" 
PROTO_OUT="${REPO_ROOT}/.build/googleapis-${PROTO_SHA}.pb"

./generate-proto.sh ${PROTO_SHA} ${PROTO_OUT}

go run . generate-types \
    --service <proto.package> \
    --api-version <service>.cnrm.cloud.google.com/v1alpha1 \
    --resource <Kind>:<ProtoMessage> \
    --proto-source-path ${PROTO_OUT}

2. Standards for _types.go

After running the generator, verify the _types.go file meets these requirements:

  • Copyright: Must be // Copyright 2026 Google LLC.
  • CRD Labels: Include exactly these labels in the type definition:
    // +kubebuilder:metadata:labels="cnrm.cloud.google.com/managed-by-kcc=true"
    // +kubebuilder:metadata:labels="cnrm.cloud.google.com/system=true"
    // +kubebuilder:metadata:labels="cnrm.cloud.google.com/stability-level=alpha"
    
  • Proto Mapping: Ensure +kcc:proto tags are present on the Spec and ObservedState structs to link them to the GCP API definitions.
  • Status Fields: status.observedGeneration must be an *int64.
  • Use Existing References: ALWAYS reuse existing resource reference structures that live in apis/refs/ instead of hand-coding or defining duplicate types.
    • For example, ProjectRef (which lives in apis/refs/v1beta1/project_ref.go) and other resource reference types should be imported from github.com/GoogleCloudPlatform/k8s-config-connector/apis/refs/v1beta1 rather than being defined locally in <kind>_types.go.
  • Strict Schema Compatibility: At the initial stage of creating a direct Go type for an existing resource (transitioning from Terraform/DCL), the Go type should be strictly schema-compatible with the existing CRD definition.
    • Do NOT add new fields like externalRef or observedState under Status yet.
    • Run dev/tasks/diff-crds to verify schema compatibility and ensure no unintended new fields are introduced.

3. Fuzzers

  • Create a fuzzer for the mapper to verify that round-trip conversions (FromProto and ToProto) are lossless and correct.
  • See the kcc-direct-controller-implementer skill for details on implementing fuzzers.

4. Registration

  • Ensure the new Kind is registered in apis/<service>/v1alpha1/register.go.
  • Run dev/tasks/generate-crds and verify the YAML appears in config/crds/resources/.