@intentius/chant-lexicon-k8s 0.0.15 → 0.0.18

package/src/composites/composites.test.ts

@@ -15,6 +15,7 @@ import { MonitoredService } from "./monitored-service";
 import { NetworkIsolatedApp } from "./network-isolated-app";
 import { IrsaServiceAccount } from "./irsa-service-account";
 import { AlbIngress } from "./alb-ingress";
+import { GceIngress } from "./gce-ingress";
 import { EbsStorageClass } from "./ebs-storage-class";
 import { EfsStorageClass } from "./efs-storage-class";
 import { FluentBitAgent } from "./fluent-bit-agent";
@@ -1860,6 +1861,79 @@ describe("AlbIngress", () => {
   });
 });
 
+// ── GceIngress ──────────────────────────────────────────────────────
+
+describe("GceIngress", () => {
+  const minProps = {
+    name: "api-ingress",
+    hosts: [{ hostname: "api.example.com", paths: [{ path: "/", serviceName: "api", servicePort: 80 }] }],
+  };
+
+  test("returns ingress with GCE annotations", () => {
+    const result = GceIngress(minProps);
+    expect(result.ingress).toBeDefined();
+    const meta = result.ingress.metadata as any;
+    expect(meta.annotations["kubernetes.io/ingress.class"]).toBe("gce");
+  });
+
+  test("static IP annotation set", () => {
+    const result = GceIngress({ ...minProps, staticIpName: "microservice-ip" });
+    const meta = result.ingress.metadata as any;
+    expect(meta.annotations["kubernetes.io/ingress.global-static-ip-name"]).toBe("microservice-ip");
+  });
+
+  test("managed certificate annotation set", () => {
+    const result = GceIngress({ ...minProps, managedCertificate: "api-cert" });
+    const meta = result.ingress.metadata as any;
+    expect(meta.annotations["networking.gke.io/managed-certificates"]).toBe("api-cert");
+  });
+
+  test("frontendConfig annotation set", () => {
+    const result = GceIngress({ ...minProps, frontendConfig: "my-frontend" });
+    const meta = result.ingress.metadata as any;
+    expect(meta.annotations["networking.gke.io/v1beta1.FrontendConfig"]).toBe("my-frontend");
+  });
+
+  test("managedCertificate sets default FrontendConfig for ssl redirect", () => {
+    const result = GceIngress({ ...minProps, managedCertificate: "api-cert" });
+    const meta = result.ingress.metadata as any;
+    expect(meta.annotations["networking.gke.io/v1beta1.FrontendConfig"]).toBe("api-ingress-frontend-config");
+  });
+
+  test("explicit sslRedirect: false suppresses FrontendConfig even with cert", () => {
+    const result = GceIngress({ ...minProps, managedCertificate: "api-cert", sslRedirect: false });
+    const meta = result.ingress.metadata as any;
+    expect(meta.annotations["networking.gke.io/v1beta1.FrontendConfig"]).toBeUndefined();
+  });
+
+  test("explicit sslRedirect: true sets default FrontendConfig without cert", () => {
+    const result = GceIngress({ ...minProps, sslRedirect: true });
+    const meta = result.ingress.metadata as any;
+    expect(meta.annotations["networking.gke.io/v1beta1.FrontendConfig"]).toBe("api-ingress-frontend-config");
+  });
+
+  test("namespace is set when provided", () => {
+    const result = GceIngress({ ...minProps, namespace: "production" });
+    const meta = result.ingress.metadata as any;
+    expect(meta.namespace).toBe("production");
+  });
+
+  test("host rules are mapped correctly", () => {
+    const result = GceIngress(minProps);
+    const spec = result.ingress.spec as any;
+    expect(spec.rules).toHaveLength(1);
+    expect(spec.rules[0].host).toBe("api.example.com");
+    expect(spec.rules[0].http.paths[0].backend.service.name).toBe("api");
+  });
+
+  test("labels include component: ingress", () => {
+    const result = GceIngress(minProps);
+    const meta = result.ingress.metadata as any;
+    expect(meta.labels["app.kubernetes.io/component"]).toBe("ingress");
+    expect(meta.labels["app.kubernetes.io/managed-by"]).toBe("chant");
+  });
+});
+
 // ── EbsStorageClass ─────────────────────────────────────────────────
 
 describe("EbsStorageClass", () => {
@@ -2691,3 +2765,455 @@ describe("ConfigConnectorContext", () => {
     expect((result.context as any).metadata.namespace).toBe("config-connector");
   });
 });
+
+// ── GkeFluentBitAgent ────────────────────────────────────────────────
+
+describe("GkeFluentBitAgent", () => {
+  const { GkeFluentBitAgent } = require("./gke-fluent-bit-agent");
+
+  const minProps = {
+    clusterName: "test-cluster",
+    projectId: "test-project",
+    gcpServiceAccountEmail: "fluent-bit@test-project.iam.gserviceaccount.com",
+  };
+
+  test("returns all expected resources", () => {
+    const result = GkeFluentBitAgent(minProps);
+    expect(result.daemonSet).toBeDefined();
+    expect(result.serviceAccount).toBeDefined();
+    expect(result.clusterRole).toBeDefined();
+    expect(result.clusterRoleBinding).toBeDefined();
+    expect(result.configMap).toBeDefined();
+  });
+
+  test("SA has GKE Workload Identity annotation", () => {
+    const result = GkeFluentBitAgent(minProps);
+    const meta = result.serviceAccount.metadata as any;
+    expect(meta.annotations["iam.gke.io/gcp-service-account"]).toBe(
+      "fluent-bit@test-project.iam.gserviceaccount.com",
+    );
+  });
+
+  test("SA has no annotation when gcpServiceAccountEmail omitted", () => {
+    const result = GkeFluentBitAgent({
+      clusterName: "test-cluster",
+      projectId: "test-project",
+    });
+    const meta = result.serviceAccount.metadata as any;
+    expect(meta.annotations).toBeUndefined();
+  });
+
+  test("configMap uses stackdriver output", () => {
+    const result = GkeFluentBitAgent(minProps);
+    const data = result.configMap.data as any;
+    expect(data["fluent-bit.conf"]).toContain("stackdriver");
+    expect(data["fluent-bit.conf"]).toContain("test-cluster");
+  });
+
+  test("default namespace is gke-logging", () => {
+    const result = GkeFluentBitAgent(minProps);
+    expect((result.daemonSet.metadata as any).namespace).toBe("gke-logging");
+    expect((result.serviceAccount.metadata as any).namespace).toBe("gke-logging");
+  });
+
+  test("common labels on all resources", () => {
+    const result = GkeFluentBitAgent(minProps);
+    for (const resource of [result.daemonSet, result.serviceAccount, result.clusterRole, result.clusterRoleBinding, result.configMap]) {
+      expect((resource.metadata as any).labels["app.kubernetes.io/managed-by"]).toBe("chant");
+    }
+  });
+
+  test("DaemonSet mounts host log directory", () => {
+    const result = GkeFluentBitAgent(minProps);
+    const spec = (result.daemonSet as any).spec.template.spec;
+    const varlog = spec.volumes.find((v: any) => v.name === "varlog");
+    expect(varlog.hostPath.path).toBe("/var/log");
+  });
+
+  test("container runs as root for log access", () => {
+    const result = GkeFluentBitAgent(minProps);
+    const container = (result.daemonSet as any).spec.template.spec.containers[0];
+    expect(container.securityContext.runAsUser).toBe(0);
+    expect(container.securityContext.readOnlyRootFilesystem).toBe(true);
+  });
+});
+
+// ── GkeOtelCollector ─────────────────────────────────────────────────
+
+describe("GkeOtelCollector", () => {
+  const { GkeOtelCollector } = require("./gke-otel-collector");
+
+  const minProps = {
+    clusterName: "test-cluster",
+    projectId: "test-project",
+    gcpServiceAccountEmail: "otel@test-project.iam.gserviceaccount.com",
+  };
+
+  test("returns all expected resources", () => {
+    const result = GkeOtelCollector(minProps);
+    expect(result.daemonSet).toBeDefined();
+    expect(result.serviceAccount).toBeDefined();
+    expect(result.clusterRole).toBeDefined();
+    expect(result.clusterRoleBinding).toBeDefined();
+    expect(result.configMap).toBeDefined();
+  });
+
+  test("SA has GKE Workload Identity annotation", () => {
+    const result = GkeOtelCollector(minProps);
+    const meta = result.serviceAccount.metadata as any;
+    expect(meta.annotations["iam.gke.io/gcp-service-account"]).toBe(
+      "otel@test-project.iam.gserviceaccount.com",
+    );
+  });
+
+  test("SA has no annotation when gcpServiceAccountEmail omitted", () => {
+    const result = GkeOtelCollector({
+      clusterName: "test-cluster",
+      projectId: "test-project",
+    });
+    const meta = result.serviceAccount.metadata as any;
+    expect(meta.annotations).toBeUndefined();
+  });
+
+  test("configMap uses googlecloud exporter", () => {
+    const result = GkeOtelCollector(minProps);
+    const data = result.configMap.data as any;
+    expect(data["config.yaml"]).toContain("googlecloud");
+    expect(data["config.yaml"]).toContain("test-project");
+  });
+
+  test("default namespace is gke-monitoring", () => {
+    const result = GkeOtelCollector(minProps);
+    expect((result.daemonSet.metadata as any).namespace).toBe("gke-monitoring");
+  });
+
+  test("container exposes OTLP ports", () => {
+    const result = GkeOtelCollector(minProps);
+    const container = (result.daemonSet as any).spec.template.spec.containers[0];
+    const ports = container.ports.map((p: any) => p.containerPort);
+    expect(ports).toContain(4317);
+    expect(ports).toContain(4318);
+  });
+
+  test("container runs as non-root", () => {
+    const result = GkeOtelCollector(minProps);
+    const container = (result.daemonSet as any).spec.template.spec.containers[0];
+    expect(container.securityContext.runAsNonRoot).toBe(true);
+    expect(container.securityContext.runAsUser).toBe(10001);
+  });
+
+  test("common labels on all resources", () => {
+    const result = GkeOtelCollector(minProps);
+    for (const resource of [result.daemonSet, result.serviceAccount, result.clusterRole, result.clusterRoleBinding, result.configMap]) {
+      expect((resource.metadata as any).labels["app.kubernetes.io/managed-by"]).toBe("chant");
+    }
+  });
+});
+
+// ── GkeExternalDnsAgent ──────────────────────────────────────────────
+
+describe("GkeExternalDnsAgent", () => {
+  const { GkeExternalDnsAgent } = require("./gke-external-dns-agent");
+
+  const minProps = {
+    gcpServiceAccountEmail: "external-dns@test-project.iam.gserviceaccount.com",
+    gcpProjectId: "test-project",
+    domainFilters: ["example.com"],
+  };
+
+  test("returns all expected resources", () => {
+    const result = GkeExternalDnsAgent(minProps);
+    expect(result.deployment).toBeDefined();
+    expect(result.serviceAccount).toBeDefined();
+    expect(result.clusterRole).toBeDefined();
+    expect(result.clusterRoleBinding).toBeDefined();
+  });
+
+  test("SA has GKE Workload Identity annotation", () => {
+    const result = GkeExternalDnsAgent(minProps);
+    const meta = result.serviceAccount.metadata as any;
+    expect(meta.annotations["iam.gke.io/gcp-service-account"]).toBe(
+      "external-dns@test-project.iam.gserviceaccount.com",
+    );
+  });
+
+  test("uses google provider", () => {
+    const result = GkeExternalDnsAgent(minProps);
+    const container = (result.deployment as any).spec.template.spec.containers[0];
+    expect(container.args).toContain("--provider=google");
+  });
+
+  test("passes google-project arg", () => {
+    const result = GkeExternalDnsAgent(minProps);
+    const container = (result.deployment as any).spec.template.spec.containers[0];
+    expect(container.args).toContain("--google-project=test-project");
+  });
+
+  test("domain filters are applied", () => {
+    const result = GkeExternalDnsAgent(minProps);
+    const container = (result.deployment as any).spec.template.spec.containers[0];
+    expect(container.args).toContain("--domain-filter=example.com");
+  });
+
+  test("txtOwnerId is applied when set", () => {
+    const result = GkeExternalDnsAgent({ ...minProps, txtOwnerId: "my-cluster" });
+    const container = (result.deployment as any).spec.template.spec.containers[0];
+    expect(container.args).toContain("--txt-owner-id=my-cluster");
+  });
+
+  test("default namespace is kube-system", () => {
+    const result = GkeExternalDnsAgent(minProps);
+    expect((result.deployment.metadata as any).namespace).toBe("kube-system");
+  });
+
+  test("container runs as non-root", () => {
+    const result = GkeExternalDnsAgent(minProps);
+    const container = (result.deployment as any).spec.template.spec.containers[0];
+    expect(container.securityContext.runAsNonRoot).toBe(true);
+    expect(container.securityContext.runAsUser).toBe(65534);
+  });
+});
+
+// ── AksExternalDnsAgent ──────────────────────────────────────────────
+
+describe("AksExternalDnsAgent", () => {
+  const { AksExternalDnsAgent } = require("./aks-external-dns-agent");
+
+  const minProps = {
+    clientId: "00000000-0000-0000-0000-000000000000",
+    resourceGroup: "test-rg",
+    subscriptionId: "11111111-1111-1111-1111-111111111111",
+    tenantId: "22222222-2222-2222-2222-222222222222",
+    domainFilters: ["example.com"],
+  };
+
+  test("returns all expected resources", () => {
+    const result = AksExternalDnsAgent(minProps);
+    expect(result.deployment).toBeDefined();
+    expect(result.serviceAccount).toBeDefined();
+    expect(result.clusterRole).toBeDefined();
+    expect(result.clusterRoleBinding).toBeDefined();
+  });
+
+  test("SA has AKS Workload Identity annotation and label", () => {
+    const result = AksExternalDnsAgent(minProps);
+    const meta = result.serviceAccount.metadata as any;
+    expect(meta.annotations["azure.workload.identity/client-id"]).toBe(
+      "00000000-0000-0000-0000-000000000000",
+    );
+    expect(meta.labels["azure.workload.identity/use"]).toBe("true");
+  });
+
+  test("uses azure provider", () => {
+    const result = AksExternalDnsAgent(minProps);
+    const container = (result.deployment as any).spec.template.spec.containers[0];
+    expect(container.args).toContain("--provider=azure");
+  });
+
+  test("passes azure resource group and subscription", () => {
+    const result = AksExternalDnsAgent(minProps);
+    const container = (result.deployment as any).spec.template.spec.containers[0];
+    expect(container.args).toContain("--azure-resource-group=test-rg");
+    expect(container.args).toContain("--azure-subscription-id=11111111-1111-1111-1111-111111111111");
+  });
+
+  test("container has Azure env vars", () => {
+    const result = AksExternalDnsAgent(minProps);
+    const container = (result.deployment as any).spec.template.spec.containers[0];
+    const envMap = Object.fromEntries(container.env.map((e: any) => [e.name, e.value]));
+    expect(envMap.AZURE_TENANT_ID).toBe("22222222-2222-2222-2222-222222222222");
+    expect(envMap.AZURE_SUBSCRIPTION_ID).toBe("11111111-1111-1111-1111-111111111111");
+    expect(envMap.AZURE_RESOURCE_GROUP).toBe("test-rg");
+  });
+
+  test("pod labels include workload identity use label", () => {
+    const result = AksExternalDnsAgent(minProps);
+    const podLabels = (result.deployment as any).spec.template.metadata.labels;
+    expect(podLabels["azure.workload.identity/use"]).toBe("true");
+  });
+
+  test("domain filters are applied", () => {
+    const result = AksExternalDnsAgent(minProps);
+    const container = (result.deployment as any).spec.template.spec.containers[0];
+    expect(container.args).toContain("--domain-filter=example.com");
+  });
+
+  test("default namespace is kube-system", () => {
+    const result = AksExternalDnsAgent(minProps);
+    expect((result.deployment.metadata as any).namespace).toBe("kube-system");
+  });
+
+  test("container runs as non-root", () => {
+    const result = AksExternalDnsAgent(minProps);
+    const container = (result.deployment as any).spec.template.spec.containers[0];
+    expect(container.securityContext.runAsNonRoot).toBe(true);
+    expect(container.securityContext.runAsUser).toBe(65534);
+  });
+});
+
+// ── CockroachDbCluster ──────────────────────────────────────────────
+
+describe("CockroachDbCluster", () => {
+  const { CockroachDbCluster } = require("./cockroachdb-cluster");
+
+  const minProps = { name: "cockroachdb" };
+
+  test("returns all expected resources", () => {
+    const result = CockroachDbCluster(minProps);
+    expect(result.serviceAccount).toBeDefined();
+    expect(result.role).toBeDefined();
+    expect(result.roleBinding).toBeDefined();
+    expect(result.clusterRole).toBeDefined();
+    expect(result.clusterRoleBinding).toBeDefined();
+    expect(result.publicService).toBeDefined();
+    expect(result.headlessService).toBeDefined();
+    expect(result.pdb).toBeDefined();
+    expect(result.statefulSet).toBeDefined();
+    expect(result.initJob).toBeDefined();
+    expect(result.certGenJob).toBeDefined();
+  });
+
+  test("default replicas is 3", () => {
+    const result = CockroachDbCluster(minProps);
+    const spec = result.statefulSet.spec as any;
+    expect(spec.replicas).toBe(3);
+  });
+
+  test("default image is cockroachdb/cockroach:v24.3.0", () => {
+    const result = CockroachDbCluster(minProps);
+    const container = (result.statefulSet.spec as any).template.spec.containers[0];
+    expect(container.image).toBe("cockroachdb/cockroach:v24.3.0");
+  });
+
+  test("StatefulSet has correct ports (26257+8080)", () => {
+    const result = CockroachDbCluster(minProps);
+    const container = (result.statefulSet.spec as any).template.spec.containers[0];
+    const ports = container.ports.map((p: any) => p.containerPort);
+    expect(ports).toContain(26257);
+    expect(ports).toContain(8080);
+  });
+
+  test("StatefulSet has PVC with default 100Gi storage", () => {
+    const result = CockroachDbCluster(minProps);
+    const vct = (result.statefulSet.spec as any).volumeClaimTemplates[0];
+    expect(vct.spec.resources.requests.storage).toBe("100Gi");
+    expect(vct.spec.accessModes).toEqual(["ReadWriteOnce"]);
+  });
+
+  test("headless service has clusterIP None and publishNotReadyAddresses", () => {
+    const result = CockroachDbCluster(minProps);
+    const spec = result.headlessService.spec as any;
+    expect(spec.clusterIP).toBe("None");
+    expect(spec.publishNotReadyAddresses).toBe(true);
+  });
+
+  test("public service has ClusterIP type with both ports", () => {
+    const result = CockroachDbCluster(minProps);
+    const spec = result.publicService.spec as any;
+    expect(spec.type).toBe("ClusterIP");
+    const ports = spec.ports.map((p: any) => p.port);
+    expect(ports).toContain(26257);
+    expect(ports).toContain(8080);
+  });
+
+  test("PDB has maxUnavailable 1", () => {
+    const result = CockroachDbCluster(minProps);
+    const spec = result.pdb.spec as any;
+    expect(spec.maxUnavailable).toBe(1);
+  });
+
+  test("StatefulSet has pod anti-affinity", () => {
+    const result = CockroachDbCluster(minProps);
+    const affinity = (result.statefulSet.spec as any).template.spec.affinity;
+    expect(affinity.podAntiAffinity).toBeDefined();
+  });
+
+  test("props flow through (replicas, image, storage)", () => {
+    const result = CockroachDbCluster({
+      name: "crdb",
+      replicas: 5,
+      image: "cockroachdb/cockroach:v23.2.0",
+      storageSize: "200Gi",
+    });
+    const spec = result.statefulSet.spec as any;
+    expect(spec.replicas).toBe(5);
+    expect(spec.template.spec.containers[0].image).toBe("cockroachdb/cockroach:v23.2.0");
+    expect(spec.volumeClaimTemplates[0].spec.resources.requests.storage).toBe("200Gi");
+  });
+
+  test("joinAddresses appear in container args", () => {
+    const joins = ["crdb-0.crdb.ns.svc.cluster.local", "crdb-1.crdb.ns.svc.cluster.local"];
+    const result = CockroachDbCluster({ name: "crdb", joinAddresses: joins });
+    const args = (result.statefulSet.spec as any).template.spec.containers[0].args as string[];
+    const joinArg = args.find((a: string) => a.startsWith("--join="));
+    expect(joinArg).toBeDefined();
+    expect(joinArg).toContain("crdb-0.crdb.ns.svc.cluster.local");
+    expect(joinArg).toContain("crdb-1.crdb.ns.svc.cluster.local");
+  });
+
+  test("locality appears in container args when set", () => {
+    const result = CockroachDbCluster({ name: "crdb", locality: "cloud=aws,region=us-east-1" });
+    const args = (result.statefulSet.spec as any).template.spec.containers[0].args as string[];
+    expect(args).toContain("--locality=cloud=aws,region=us-east-1");
+  });
+
+  test("namespace is set on all namespaced resources", () => {
+    const result = CockroachDbCluster({ name: "crdb", namespace: "crdb-eks" });
+    for (const key of ["serviceAccount", "role", "roleBinding", "publicService", "headlessService", "pdb", "statefulSet", "initJob", "certGenJob"] as const) {
+      expect((result[key].metadata as any).namespace).toBe("crdb-eks");
+    }
+  });
+
+  test("cluster-scoped resources do not have namespace", () => {
+    const result = CockroachDbCluster({ name: "crdb", namespace: "crdb-eks" });
+    expect((result.clusterRole.metadata as any).namespace).toBeUndefined();
+    expect((result.clusterRoleBinding.metadata as any).namespace).toBeUndefined();
+  });
+
+  test("includes common labels", () => {
+    const result = CockroachDbCluster(minProps);
+    const meta = result.statefulSet.metadata as any;
+    expect(meta.labels["app.kubernetes.io/name"]).toBe("cockroachdb");
+    expect(meta.labels["app.kubernetes.io/managed-by"]).toBe("chant");
+  });
+
+  test("secure mode mounts certs volume", () => {
+    const result = CockroachDbCluster({ name: "crdb", secure: true });
+    const spec = (result.statefulSet.spec as any).template.spec;
+    expect(spec.volumes).toBeDefined();
+    const certsVol = spec.volumes.find((v: any) => v.name === "certs");
+    expect(certsVol).toBeDefined();
+    expect(certsVol.secret.secretName).toBe("crdb-node-certs");
+  });
+
+  test("insecure mode omits certs volume", () => {
+    const result = CockroachDbCluster({ name: "crdb", secure: false });
+    const spec = (result.statefulSet.spec as any).template.spec;
+    expect(spec.volumes).toBeUndefined();
+    const args = spec.containers[0].args as string[];
+    expect(args).toContain("--insecure");
+  });
+
+  test("storageClassName is set when provided", () => {
+    const result = CockroachDbCluster({ name: "crdb", storageClassName: "gp3-encrypted" });
+    const vct = (result.statefulSet.spec as any).volumeClaimTemplates[0];
+    expect(vct.spec.storageClassName).toBe("gp3-encrypted");
+  });
+
+  test("init job references correct host", () => {
+    const result = CockroachDbCluster({ name: "crdb" });
+    const container = (result.initJob.spec as any).template.spec.containers[0];
+    expect(container.args).toContain("--host=crdb-0.crdb");
+  });
+
+  test("StatefulSet uses Parallel podManagementPolicy", () => {
+    const result = CockroachDbCluster(minProps);
+    expect((result.statefulSet.spec as any).podManagementPolicy).toBe("Parallel");
+  });
+
+  test("cert-gen job uses same image as StatefulSet", () => {
+    const result = CockroachDbCluster({ name: "crdb", image: "cockroachdb/cockroach:v23.2.0" });
+    const container = (result.certGenJob.spec as any).template.spec.containers[0];
+    expect(container.image).toBe("cockroachdb/cockroach:v23.2.0");
+  });
+});

package/src/composites/gce-ingress.ts

@@ -0,0 +1,143 @@
+/**
+ * GceIngress composite — Ingress with GCE Ingress Controller annotations.
+ *
+ * @gke Full `kubernetes.io/ingress.*` and `networking.gke.io/*` annotation set
+ * including static IP, managed certificates, and FrontendConfig.
+ */
+
+export interface GceIngressHost {
+  /** Hostname (e.g., "api.example.com"). */
+  hostname: string;
+  /** Path rules for this host. */
+  paths: Array<{
+    path: string;
+    pathType?: string;
+    serviceName: string;
+    /** Port on the Kubernetes Service (not the container port). */
+    servicePort: number;
+  }>;
+}
+
+export interface GceIngressProps {
+  /** Ingress name — used in metadata and labels. */
+  name: string;
+  /** Host definitions with paths. */
+  hosts: GceIngressHost[];
+  /** Global static IP name reserved in GCP (sets `kubernetes.io/ingress.global-static-ip-name`). */
+  staticIpName?: string;
+  /** GKE managed certificate name (sets `networking.gke.io/managed-certificates`). */
+  managedCertificate?: string;
+  /** FrontendConfig name for SSL policy / redirects (sets `networking.gke.io/v1beta1.FrontendConfig`). */
+  frontendConfig?: string;
+  /** Health check path for backend (sets `cloud.google.com/backend-config` is NOT handled here — use BackendConfig CRD). */
+  healthCheckPath?: string;
+  /** Enable HTTP->HTTPS redirect (default: true when managedCertificate set). */
+  sslRedirect?: boolean;
+  /** Additional annotations on the Ingress. */
+  annotations?: Record<string, string>;
+  /** Additional labels to apply to all resources. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+}
+
+export interface GceIngressResult {
+  ingress: Record<string, unknown>;
+}
+
+/**
+ * Create a GceIngress composite — returns prop objects for
+ * an Ingress with GCE Ingress Controller annotations.
+ *
+ * @gke
+ * @example
+ * ```ts
+ * 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: "microservice-ip",
+ *   managedCertificate: "api-cert",
+ * });
+ * ```
+ */
+export function GceIngress(props: GceIngressProps): GceIngressResult {
+  const {
+    name,
+    hosts,
+    staticIpName,
+    managedCertificate,
+    frontendConfig,
+    healthCheckPath,
+    sslRedirect,
+    annotations: extraAnnotations = {},
+    labels: extraLabels = {},
+    namespace,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // Build GCE annotations
+  const annotations: Record<string, string> = {
+    "kubernetes.io/ingress.class": "gce",
+    ...extraAnnotations,
+  };
+
+  if (staticIpName) {
+    annotations["kubernetes.io/ingress.global-static-ip-name"] = staticIpName;
+  }
+
+  if (managedCertificate) {
+    annotations["networking.gke.io/managed-certificates"] = managedCertificate;
+  }
+
+  if (frontendConfig) {
+    annotations["networking.gke.io/v1beta1.FrontendConfig"] = frontendConfig;
+  }
+
+  if (sslRedirect ?? !!managedCertificate) {
+    annotations["networking.gke.io/v1beta1.FrontendConfig"] =
+      annotations["networking.gke.io/v1beta1.FrontendConfig"] ?? `${name}-frontend-config`;
+  }
+
+  if (healthCheckPath) {
+    annotations["cloud.google.com/neg"] = '{"ingress": true}';
+  }
+
+  const ingressRules = hosts.map((host) => ({
+    host: host.hostname,
+    http: {
+      paths: host.paths.map((p) => ({
+        path: p.path,
+        pathType: p.pathType ?? "Prefix",
+        backend: {
+          service: { name: p.serviceName, port: { number: p.servicePort } },
+        },
+      })),
+    },
+  }));
+
+  const ingressProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "ingress" },
+      annotations,
+    },
+    spec: {
+      rules: ingressRules,
+    },
+  };
+
+  return { ingress: ingressProps };
+}