GKE Composites

These composites produce K8s YAML with GKE-specific annotations and configurations. They complement the generic composites by adding GCP service integrations.

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
Pairs naturally 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

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
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

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

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)

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

Workload Identity is the recommended approach for all GKE workloads. Key-based auth requires no K8s-side composite — create a Secret from the JSON key and mount it.

Config Connector considerations

Config Connector (CC) runs as a GKE add-on and manages GCP resources declaratively via K8s 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.