GKE Composites

These composites write Kubernetes YAML with the annotations and settings GKE reads, for Workload Identity, GCE Ingress, Gateway API, Persistent Disk and Filestore, Cloud DNS, Cloud Logging, Cloud Trace and Config Connector. Use them beside the generic composites.

WorkloadIdentityServiceAccount

ServiceAccount annotated for GKE Workload Identity:

import { WorkloadIdentityServiceAccount } from "@intentius/chant-lexicon-k8s";

const { serviceAccount, role, roleBinding } = WorkloadIdentityServiceAccount({
  name: "app-sa",
  gcpServiceAccountEmail: "app@my-project.iam.gserviceaccount.com",
  rbacRules: [
    { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
  ],
  namespace: "prod",
});

• Sets iam.gke.io/gcp-service-account annotation on the ServiceAccount
• Optional RBAC rules create a Role + RoleBinding scoped to the namespace
• Requires Workload Identity enabled on the GKE cluster + an IAM policy binding on the GCP SA

GceIngress

Ingress with GCE ingress class annotations:

import { GceIngress } from "@intentius/chant-lexicon-k8s";

const { ingress } = GceIngress({
  name: "api-ingress",
  hosts: [
    {
      hostname: "api.example.com",
      paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
    },
  ],
  staticIpName: "api-ip",
  managedCertificate: "api-cert",
  namespace: "prod",
});

• Sets kubernetes.io/ingress.class: "gce" annotation
• staticIpName binds a reserved global static IP via kubernetes.io/ingress.global-static-ip-name
• managedCertificate attaches a GKE-managed SSL certificate via networking.gke.io/managed-certificates
• Auto-generates FrontendConfig for SSL redirect when managedCertificate is set (override with sslRedirect: false)
• frontendConfig for explicit FrontendConfig reference
• Works with Config Connector static IP resources

GkeGateway

Gateway API with GKE gateway classes:

import { GkeGateway } from "@intentius/chant-lexicon-k8s";

const { gateway, httpRoute } = GkeGateway({
  name: "api-gateway",
  gatewayClassName: "gke-l7-global-external-managed",
  hosts: [
    {
      hostname: "api.example.com",
      paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
    },
  ],
  certificateName: "api-cert",
  namespace: "prod",
});

Gateway class options:

• gke-l7-global-external-managed — Global external (default)
• gke-l7-regional-external-managed — Regional external
• gke-l7-rilb — Regional internal

GCE Ingress vs Gateway API

GceIngress uses the traditional Ingress API with GCE-specific annotations. It is simpler, matches the EKS and AKS ingress composites, and works with Config Connector static IPs and managed certificates.

GkeGateway uses the newer Gateway API with richer routing capabilities (header matching, traffic splitting, URL rewrites). It’s Google’s recommended path for new projects.

Use GceIngress to match EKS and AKS projects. Use GkeGateway for header matching, traffic splitting or URL rewrites, or for a new GKE project.

GcePdStorageClass

StorageClass for the GCE Persistent Disk CSI driver:

import { GcePdStorageClass } from "@intentius/chant-lexicon-k8s";

const { storageClass } = GcePdStorageClass({
  name: "pd-balanced",
  type: "pd-balanced",
  replicationType: "none",
  allowVolumeExpansion: true,
});

• Provisions pd.csi.storage.gke.io volumes
• Disk types: pd-standard, pd-ssd, pd-balanced (default), pd-extreme
• replicationType controls regional replication (none or regional-pd)

FilestoreStorageClass

StorageClass for the Filestore CSI driver (ReadWriteMany):

import { FilestoreStorageClass } from "@intentius/chant-lexicon-k8s";

const { storageClass } = FilestoreStorageClass({
  name: "filestore-shared",
  tier: "standard",
  network: "my-vpc",
});

• ReadWriteMany access — shared across pods and nodes
• Requires the Filestore CSI driver GKE add-on
• Use GCE PD for ReadWriteOnce (single pod), Filestore for ReadWriteMany (shared)

GkeExternalDnsAgent

ExternalDNS for Cloud DNS integration:

import { GkeExternalDnsAgent } from "@intentius/chant-lexicon-k8s";

const result = GkeExternalDnsAgent({
  gcpServiceAccountEmail: "dns@my-project.iam.gserviceaccount.com",
  gcpProjectId: "my-project",
  domainFilters: ["example.com"],
  txtOwnerId: "my-cluster",
});

• Watches Ingress/Service resources and creates Cloud DNS records
• Uses Workload Identity for authentication
• Shares its ClusterRole with OtelCollector: read access to what k8sattributes needs (pods, namespaces, nodes, replica sets), and nothing for its receivers, since its only receiver is OTLP
• domainFilters restricts which domains ExternalDNS can manage

GkeFluentBitAgent

DaemonSet for Cloud Logging:

import { GkeFluentBitAgent } from "@intentius/chant-lexicon-k8s";

const result = GkeFluentBitAgent({
  clusterName: "my-cluster",
  projectId: "my-project",
  gcpServiceAccountEmail: "logging@my-project.iam.gserviceaccount.com",
});

• Deploys Fluent Bit as a DaemonSet with host path mounts for /var/log
• Forwards container logs to Cloud Logging
• Uses Workload Identity for authentication
• Shares its ClusterRole with OtelCollector: read access to what k8sattributes needs (pods, namespaces, nodes, replica sets), and nothing for its receivers, since its only receiver is OTLP

GkeOtelCollector

OTel collector for Cloud Trace and Cloud Monitoring:

import { GkeOtelCollector } from "@intentius/chant-lexicon-k8s";

const result = GkeOtelCollector({
  clusterName: "my-cluster",
  projectId: "my-project",
  gcpServiceAccountEmail: "monitoring@my-project.iam.gserviceaccount.com",
});

• Deploys OTel collector as a DaemonSet collecting metrics and traces
• Exports to Cloud Monitoring and Cloud Trace
• Uses Workload Identity for authentication
• Shares its ClusterRole with OtelCollector: read access to what k8sattributes needs (pods, namespaces, nodes, replica sets), and nothing for its receivers, since its only receiver is OTLP

ConfigConnectorContext

Config Connector namespace bootstrap:

import { ConfigConnectorContext } from "@intentius/chant-lexicon-k8s";

const { context } = ConfigConnectorContext({
  googleServiceAccountEmail: "cc-sa@my-project.iam.gserviceaccount.com",
  namespace: "config-connector",
  stateIntoSpec: "absent",
});

• Required when using Config Connector to manage GCP resources from within the cluster
• Configures the GCP service account per namespace
• stateIntoSpec controls whether CC writes observed state back into the spec (absent recommended)

CockroachDbRegionStack

All K8s resources for one CockroachDB region, in a single call — the 8-file per-region pattern (namespace, storage, StatefulSet, External Secrets, ingress, TLS, BackendConfig, monitoring) collapsed into one composite. Backs the CockroachDB Multi-Region tutorial and its example, two calls per region:

import { CockroachDbRegionStack } from "@intentius/chant-lexicon-k8s";

export const east = CockroachDbRegionStack({
  region: "east",
  namespace: "crdb-east",
  domain: "east.crdb.example.com",
  internalDomain: "east.crdb.internal",
  publicRootDomain: "crdb.example.com",
  projectId: "my-project",
  clusterName: "gke-crdb-east",
  clusterRegion: "us-east4",
  crdbGsaEmail: "gke-crdb-east-crdb@my-project.iam.gserviceaccount.com",
  externalDnsGsaEmail: "gke-crdb-east-dns@my-project.iam.gserviceaccount.com",
  cockroachdb: {
    locality: "cloud=gcp,region=us-east4",
    joinAddresses: [/* ... */],
    advertiseHostDomain: "east.crdb.internal",
    skipInit: false,
    mountClientCerts: true,
  },
  tls: {
    gcpSecretNames: {
      ca: "crdb-ca-crt",
      nodeCrt: "crdb-node-crt",
      nodeKey: "crdb-node-key",
      clientRootCrt: "crdb-client-root-crt",
      clientRootKey: "crdb-client-root-key",
    },
  },
  cloudArmor: { policyName: "crdb-ui-waf" },
  monitoring: true,
});

It emits: a namespace with resource quota, default limits and default-deny NetworkPolicy; a pd-ssd StorageClass; the CockroachDB StatefulSet, headless + public Services, RBAC and PodDisruptionBudget (via CockroachDbCluster); a ClusterSecretStore and two ExternalSecrets pulling node and client certs from GCP Secret Manager; a ManagedCertificate, FrontendConfig and GceIngress for the public UI; an ExternalDNS agent for both the public and internal (cross-cluster) domains; and, optionally, a Cloud Armor BackendConfig and a Prometheus scrape ConfigMap/Deployment/Service.

The props that matter for a multi-region rollout:

• cockroachdb.advertiseHostDomain — when set, pods advertise ${HOSTNAME}.${advertiseHostDomain} instead of their in-cluster DNS name, so gossip resolves across clusters. Required on every region except a single-cluster deployment.
• cockroachdb.skipInit — only the first region should run the cockroach init Job; every other region sets this true.
• cockroachdb.mountClientCerts — mounts the client cert secret into the CockroachDB pods so kubectl exec ... -- cockroach sql works for multi-region init. Certs still come from TLS/External Secrets either way — this only controls the mount.
• cloudArmor — when set, attaches a Cloud Armor WAF policy to the public UI Service via a generated BackendConfig. Omit it and no BackendConfig is emitted.
• monitoring — emits a lightweight Prometheus scraping /_status/vars (default false); use it or point an existing Prometheus at the same endpoint, not both.

TLS is always sourced from GCP Secret Manager via External Secrets Operator — unlike CockroachDbCluster, CockroachDbRegionStack does not expose skipCertGen; it calls CockroachDbCluster with skipCertGen: true unconditionally, so no self-signed cert Job is ever emitted here.

Regions sharing one K8s cluster

CockroachDbCluster’s ClusterRole and ClusterRoleBinding are named after cockroachdb.name (default "cockroachdb"), and both are cluster-scoped — unlike everything else the stack emits, they are not namespaced. Two regions deployed into separate K8s clusters never collide. Two or three regions deployed into the same K8s cluster do, unless each call gives cockroachdb.name a region-unique value (e.g. "cockroachdb-east"). The stack’s own ClusterSecretStore is similarly fixed-named (gcp-secret-manager) and has the same constraint.

Workload Identity vs key-based auth

Feature	Workload Identity	Key-based (JSON key file)
K8s annotation needed	Yes (iam.gke.io/gcp-service-account)	No
Composite available	WorkloadIdentityServiceAccount	None needed (mount key as Secret)
Setup	GKE cluster WI enabled + IAM binding	Create key → K8s Secret → volume mount
Security	No long-lived credentials, auto-rotated	Static key, must rotate manually
When to use	Always (recommended)	Legacy workloads, non-GKE clusters

Use Workload Identity for GKE workloads. For key-based auth, create a Secret from the JSON key and mount it; no composite is involved.

Note

GKE ships its own metrics-server, so HPA works without the MetricsServer composite.

Config Connector considerations

Config Connector (CC) runs as a GKE add-on and manages GCP resources through Kubernetes CRDs:

• Bootstrap cluster required — CC needs an existing GKE cluster to run in; use npm run bootstrap to create one
• CC service account — a GCP SA with editor/IAM roles, bound to the CC controller pod via Workload Identity
• Reconciliation — CC continuously reconciles; deleting a CC resource deletes the underlying GCP resource
• ConfigConnectorContext — use the composite to configure CC per-namespace (SA email, stateIntoSpec policy)

GKE add-ons

Common add-ons managed via GKE (not K8s manifests):

Add-on	Required for
Config Connector	Managing GCP resources as K8s CRDs
Workload Identity	WorkloadIdentityServiceAccount
GKE Gateway Controller	GkeGateway
GKE managed Prometheus	Alternative to GkeOtelCollector for metrics
GKE Dataplane V2	eBPF-based networking with built-in NetworkPolicy enforcement
Filestore CSI driver	FilestoreStorageClass
Compute Engine PD CSI driver	GcePdStorageClass (enabled by default)

Configure add-ons via the GCP Config Connector lexicon.

Further reading

• GCP GKE + Kubernetes tutorial — full deployment walkthrough
• Deploying to GKE — GCP lexicon bridge page
• Generic composites — WebApp, AutoscaledService, NamespaceEnv, and more