kcc-direct-base-types-implementer

name	kcc-direct-base-types-implementer
description	Base skill containing shared standards for all KCC direct resource types (both greenfield and brownfield).

KCC Direct Base Types Implementer

This skill provides the mandatory baseline standards that apply to all new KRM types (_types.go) for direct resources in Config Connector, regardless of whether they are greenfield or brownfield migrations.

Shared Standards for _types.go

After running the generator (via generate.sh), you must verify and enforce the following baseline requirements on the resulting _types.go file:

• Copyright: The file must start with // Copyright 2026 Google LLC.

• CRD Labels: Include at least these two 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"
  

  (Note: See greenfield/brownfield skills for the correct stability-level label to append.)

• Status Fields: status.observedGeneration must be exactly *int64.

• Reference Fields: Ensure that fields referencing other GCP/KCC resources are implemented as proper KCC reference fields (e.g., using pubsubv1beta1.PubSubTopicRef or refsv1beta1.ProjectRef), following the Ref suffix naming convention. You MUST NOT add new exceptions to tests/apichecks/testdata/exceptions/missingrefs.txt. All reference-like fields must be implemented as proper references.

  • Standard references include:
    • Service accounts should be references to IAMServiceAccount.
    • Cloud Storage buckets should be references to StorageBucket.
    • Service Directory configurations should be references to ServiceDirectoryService.

• Implement a New Reference Types:

  • When a field is a reference to another resource, and that reference resource does not have full KCC support yet, we should support it as external-only reference. The <newkind>Ref must always be defined and implemented in its own separate file named <newkind>_reference.go (e.g., networksecurityinterceptdeploymentgroup_reference.go) under apis/<service>/v1alpha1(e.g., apis/networksecurity/v1alpha1/) directory. This keeps the main type definitions clean and isolated from reference resolution boilerplate. Example external-only reference:

  var _ refsv1beta1.Ref = &NetworkSecurityInterceptDeploymentGroupRef{}
  var NetworkSecurityInterceptDeploymentGroupGVK = GroupVersion.WithKind("NetworkSecurityInterceptDeploymentGroup")
  
  // NetworkSecurityInterceptDeploymentGroupRef is a reference to a NetworkSecurityInterceptDeploymentGroup.
  
  type NetworkSecurityInterceptDeploymentGroupRef struct {
      /* A reference to an externally managed NetworkSecurityInterceptDeploymentGroup resource.
      Should be in the format "projects/{{projectID}}/locations/{{location}}/interceptDeploymentGroups/{{interceptDeploymentGroupID}}". */
      External string `json:"external,omitempty"`
  
      /* NOTYET
      // The name of a NetworkSecurityInterceptDeploymentGroup resource.
      Name string `json:"name,omitempty"`
  
      // The namespace of a NetworkSecurityInterceptDeploymentGroup resource.
      Namespace string `json:"namespace,omitempty"`
      */
  }
  
  func (r *NetworkSecurityInterceptDeploymentGroupRef) GetGVK() schema.GroupVersionKind {
  return NetworkSecurityInterceptDeploymentGroupGVK
  }
  
  func (r *NetworkSecurityInterceptDeploymentGroupRef) GetNamespacedName() types.NamespacedName {
  return types.NamespacedName{}
  }
  
  func (r *NetworkSecurityInterceptDeploymentGroupRef) GetExternal() string {
  return r.External
  }
  
  func (r *NetworkSecurityInterceptDeploymentGroupRef) SetExternal(ref string) {
  r.External = ref
  }
  
  func (r *NetworkSecurityInterceptDeploymentGroupRef) ValidateExternal(ref string) error {
  id := &NetworkSecurityInterceptDeploymentGroupIdentity{}
  if err := id.FromExternal(ref); err != nil {
  return err
  }
  return nil
  }
  
  func (r *NetworkSecurityInterceptDeploymentGroupRef) Normalize(ctx context.Context, reader client.Reader, defaultNamespace string) error {
  if r.External == "" {
  return fmt.Errorf("external reference must be specified for %s", NetworkSecurityInterceptDeploymentGroupGVK.Kind)
  }
  return r.ValidateExternal(r.External)
  }
  

  • Also implement <kind>_identity.go of the new reference resource(e.g., networksecurityinterceptdeploymentgroup_identity.go), as the FromExternal function is used in <kind>_reference.go. Example initial identity:

• Reference Types Location: Whenever a reference type (e.g. <Kind>Ref implementing refsv1beta1.Ref) is needed, it must always be defined and implemented in its own separate file named <kind>_reference.go (e.g., filestorebackup_reference.go) rather than inside _types.go. This keeps the main type definitions clean and isolated from reference resolution boilerplate.

• Service-Generated Fields: Fields that are service-generated values (such as etag) MUST NOT be under spec. They should be put under status (specifically under observedState).

• Acronym Capitalization: Acronyms within field names must be either all in lowercase or all capitalized (e.g., use vertexAISearchRuntimeConfig instead of vertexAiSearchRuntimeConfig).

• Manual Types Isolation: Always move any manually defined/handled types (including complex structs, recursive types, custom schemas, union/oneof configs) from types.generated.go to <kind>_types.go before making any further modifications to them. Note that parent structs do NOT need to be in the manual _types.go file just because their child structs are in the manual file. As long as the child structs (e.g., AuthConfig_APIKeyConfig) are defined in the manual _types.go file, the controllerbuilder toolchain will generate the parent struct (e.g., AuthConfig) cleanly in types.generated.go referencing those manual child structs. Therefore, only keep structs that directly declare reference fields (*Ref) or manual overrides in <kind>_types.go to keep the manual types file as lean as possible.

• CRD Recursion and Commenting: If a schema/type definition has deeply nested or recursive field types (such as parameters and response in function/schema declarations) that trigger OpenAPI validation errors or panics during conversion, comment them out or represent them as simple custom types to preserve CRD stability.

• Preserve Unknown Fields: Avoid using x-kubernetes-preserve-unknown-fields: true except on standard fields of type apiextensionsv1.JSON representing raw/dynamic unstructured user-provided payload structures (such as dynamic parameters/request payloads) where keeping unknown fields is strictly required to prevent data loss. Verify any such usage to ensure it is necessary.

• KCC Proto Annotations: To enable auto-generation of mappers, you must add the correct "kcc:proto" annotations to Go structs in _types.go:

  • The Spec struct must be annotated with // +kcc:spec:proto=<proto_type> (e.g. // +kcc:spec:proto=google.cloud.compute.v1.ServiceAttachment).
  • The ObservedState struct (if present) must be annotated with // +kcc:observedstate:proto=<proto_type>.
  • The Status struct (if there is no separate ObservedState struct) must be annotated with // +kcc:status:proto=<proto_type>.
  • Nested/referenced helper structs (both in Spec and Status) must be annotated with // +kcc:proto=<proto_sub_type> (e.g. // +kcc:proto=google.cloud.compute.v1.ServiceAttachmentConnectedEndpoint).