refactor: align ksvc spec with operator patterns, bump Knative to v1.20.0

pyramation · pyramation · commit 18a048bdca09 · 2026-06-15T19:37:38.000Z
- Add standard k8s labels (managed-by, part-of, component, name, instance)
- Add networking.knative.dev/visibility: cluster-local label
- Add explicit containerPort: 8080
- Add /tmp emptyDir volume + volumeMount (writable scratch space)
- Add autoscaling.knative.dev/target annotation support
- Extract mergeAndReplace() helper shared by seed + sync handler
- Export KnativeServiceSpec type for downstream consumers
- Bump Knative version from v1.17.0 to v1.20.0 in all CI workflows
- Update unit tests to verify labels, ports, volumes, target annotation
diff --git a/.github/workflows/spike-knative-kind.yaml b/.github/workflows/spike-knative-kind.yaml
@@ -36,20 +36,20 @@ jobs:
       # ── Install Knative Serving CRDs + core ──────────────────────────
       - name: Install Knative Serving CRDs
         run: |
-          KNATIVE_VERSION=v1.17.0
+          KNATIVE_VERSION=v1.20.0
           echo "Installing Knative Serving ${KNATIVE_VERSION} CRDs..."
           kubectl apply -f "https://github.com/knative/serving/releases/download/knative-${KNATIVE_VERSION}/serving-crds.yaml"
 
       - name: Install Knative Serving core
         run: |
-          KNATIVE_VERSION=v1.17.0
+          KNATIVE_VERSION=v1.20.0
           echo "Installing Knative Serving ${KNATIVE_VERSION} core..."
           kubectl apply -f "https://github.com/knative/serving/releases/download/knative-${KNATIVE_VERSION}/serving-core.yaml"
 
       # ── Install a networking layer (Kourier is simplest for CI) ──────
       - name: Install Kourier networking
         run: |
-          KNATIVE_VERSION=v1.17.0
+          KNATIVE_VERSION=v1.20.0
           echo "Installing Kourier networking layer..."
           kubectl apply -f "https://github.com/knative/net-kourier/releases/download/knative-${KNATIVE_VERSION}/kourier.yaml"
 
diff --git a/.github/workflows/test-provisioning-e2e.yaml b/.github/workflows/test-provisioning-e2e.yaml
@@ -88,19 +88,19 @@ jobs:
       # ── Knative Serving ────────────────────────────────────────────────
       - name: Install Knative Serving CRDs
         run: |
-          KNATIVE_VERSION=v1.17.0
+          KNATIVE_VERSION=v1.20.0
           echo "Installing Knative Serving ${KNATIVE_VERSION} CRDs..."
           kubectl apply -f "https://github.com/knative/serving/releases/download/knative-${KNATIVE_VERSION}/serving-crds.yaml"
 
       - name: Install Knative Serving core
         run: |
-          KNATIVE_VERSION=v1.17.0
+          KNATIVE_VERSION=v1.20.0
           echo "Installing Knative Serving ${KNATIVE_VERSION} core..."
           kubectl apply -f "https://github.com/knative/serving/releases/download/knative-${KNATIVE_VERSION}/serving-core.yaml"
 
       - name: Install Kourier networking
         run: |
-          KNATIVE_VERSION=v1.17.0
+          KNATIVE_VERSION=v1.20.0
           echo "Installing Kourier networking layer..."
           kubectl apply -f "https://github.com/knative/net-kourier/releases/download/knative-${KNATIVE_VERSION}/kourier.yaml"
 
diff --git a/packages/provisioning-handlers/src/handlers/function-sync-resources.ts b/packages/provisioning-handlers/src/handlers/function-sync-resources.ts
@@ -12,6 +12,7 @@ import { Logger } from '@pgpmjs/logger';
 
 import { getK8sClient, isNotFound } from '../k8s-client';
 import { buildKnativeServiceSpec, resolveNamespaceName } from '../knative';
+import { mergeAndReplace } from '../seed';
 import type { ProvisioningContext, ProvisioningHandler } from '../types';
 
 const log = new Logger('provisioning:function-sync');
@@ -67,26 +68,7 @@ export const handleFunctionSyncResources: ProvisioningHandler = async (
   const serviceSpec = buildKnativeServiceSpec(fnRow, namespaceName);
 
   try {
-    // GET the existing service to retrieve metadata required for PUT
-    const existing = await client.readServingKnativeDevV1NamespacedService({
-      query: {},
-      path: { name: fnName, namespace: namespaceName },
-    });
-    if (serviceSpec.metadata) {
-      serviceSpec.metadata.resourceVersion = existing?.metadata?.resourceVersion;
-      // Preserve Knative-managed annotations (e.g. serving.knative.dev/creator)
-      const existingAnnotations = (existing?.metadata?.annotations ?? {}) as Record<string, string>;
-      serviceSpec.metadata.annotations = { ...existingAnnotations, ...serviceSpec.metadata.annotations };
-      const existingLabels = (existing?.metadata?.labels ?? {}) as Record<string, string>;
-      serviceSpec.metadata.labels = { ...existingLabels, ...serviceSpec.metadata.labels };
-    }
-
-    const svc = await client.replaceServingKnativeDevV1NamespacedService({
-      query: {},
-      path: { name: fnName, namespace: namespaceName },
-      body: serviceSpec,
-    });
-
+    const svc = await mergeAndReplace(client, serviceSpec, fnName, namespaceName);
     const serviceUrl = svc?.status?.url ?? svc?.status?.address?.url ?? null;
     log.info(`updated Knative Service "${fnName}" in namespace "${namespaceName}"`);
 
diff --git a/packages/provisioning-handlers/src/index.ts b/packages/provisioning-handlers/src/index.ts
@@ -4,6 +4,7 @@ export {
   registerProvisioningHandler,
 } from './registry';
 export { getK8sClient, isConflict, isNotFound } from './k8s-client';
+export type { KnativeServiceSpec } from './knative';
 export { buildKnativeServiceSpec, resolveNamespaceName } from './knative';
 export type { ProvisionSeedOptions, ProvisionSeedResult } from './seed';
-export { provision } from './seed';
+export { mergeAndReplace, provision } from './seed';
diff --git a/packages/provisioning-handlers/src/knative.ts b/packages/provisioning-handlers/src/knative.ts
@@ -1,60 +1,142 @@
 /**
  * Shared Knative Service helpers — used by both the seed script
  * and the function:sync-resources queue handler.
+ *
+ * Spec shape mirrors constructive-cloud's Go operator
+ * (operator/internal/resources/knative.go) so the two systems
+ * produce functionally identical Knative Services.
  */
 
 import type { Pool } from 'pg';
 
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const DEFAULT_PORT = 8080;
+const DEFAULT_TIMEOUT = 300;
+const DEFAULT_SCALE_TARGET = 50;
+const MANAGED_BY = 'provisioning-handlers';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface KnativeServiceSpec {
+  apiVersion: 'serving.knative.dev/v1';
+  kind: 'Service';
+  metadata: {
+    name: string;
+    namespace: string;
+    labels: Record<string, string>;
+    annotations: Record<string, string>;
+    resourceVersion?: string;
+  };
+  spec: {
+    template: {
+      metadata: {
+        labels: Record<string, string>;
+        annotations?: Record<string, string>;
+      };
+      spec: {
+        containerConcurrency?: number;
+        timeoutSeconds: number;
+        containers: Array<{
+          image: string;
+          ports: Array<{ containerPort: number }>;
+          envFrom: Array<{ secretRef: { name: string } }>;
+          resources?: Record<string, unknown>;
+          volumeMounts: Array<{ name: string; mountPath: string }>;
+        }>;
+        volumes: Array<{ name: string; emptyDir: Record<string, never> }>;
+      };
+    };
+  };
+}
+
+// ── Labels (matches operator/internal/util/labels.go) ────────────────────────
+
+function componentLabels(namespaceName: string, fnName: string): Record<string, string> {
+  return {
+    'app.kubernetes.io/managed-by': MANAGED_BY,
+    'app.kubernetes.io/part-of': namespaceName,
+    'app.kubernetes.io/component': 'function',
+    'app.kubernetes.io/name': fnName,
+    'app.kubernetes.io/instance': `${namespaceName}-${fnName}`,
+    'networking.knative.dev/visibility': 'cluster-local',
+  };
+}
+
+// ── Builder ──────────────────────────────────────────────────────────────────
+
 /**
- * Build the Knative Service spec from a function definition row.
+ * Build a Knative Service spec from a function definition row.
+ *
+ * Mirrors the operator's `BuildKnativeService()`:
+ *   - Standard k8s labels + cluster-local visibility
+ *   - Autoscaling annotations (minScale, maxScale, target)
+ *   - Explicit containerPort
+ *   - /tmp emptyDir volume (writable scratch space)
+ *   - envFrom bulk secret ref
  */
 export function buildKnativeServiceSpec(
   fnRow: Record<string, unknown>,
   namespaceName: string
-) {
+): KnativeServiceSpec {
+  const fnName = fnRow.name as string;
   const image = fnRow.image as string;
   const concurrency = (fnRow.concurrency as number) ?? 0;
   const scaleMin = (fnRow.scale_min as number) ?? 0;
   const scaleMax = (fnRow.scale_max as number) ?? 0;
-  const timeoutSeconds = (fnRow.timeout_seconds as number) ?? 300;
+  const scaleTarget = (fnRow.scale_target as number) ?? 0;
+  const timeoutSeconds = (fnRow.timeout_seconds as number) ?? DEFAULT_TIMEOUT;
   const resources = (fnRow.resources as Record<string, unknown>) ?? {};
-  const fnName = fnRow.name as string;
 
-  const annotations: Record<string, string> = {};
-  if (scaleMin > 0) annotations['autoscaling.knative.dev/minScale'] = String(scaleMin);
-  if (scaleMax > 0) annotations['autoscaling.knative.dev/maxScale'] = String(scaleMax);
+  // Template-level autoscaling annotations
+  const templateAnnotations: Record<string, string> = {};
+  if (scaleMin > 0) templateAnnotations['autoscaling.knative.dev/minScale'] = String(scaleMin);
+  if (scaleMax > 0) templateAnnotations['autoscaling.knative.dev/maxScale'] = String(scaleMax);
+  if (scaleTarget > 0 || (scaleMin > 0 && scaleMax > 0)) {
+    templateAnnotations['autoscaling.knative.dev/target'] = String(scaleTarget || DEFAULT_SCALE_TARGET);
+  }
+
+  const labels = componentLabels(namespaceName, fnName);
+
+  const container: KnativeServiceSpec['spec']['template']['spec']['containers'][0] = {
+    image,
+    ports: [{ containerPort: DEFAULT_PORT }],
+    envFrom: [{ secretRef: { name: `${namespaceName}-secrets` } }],
+    volumeMounts: [{ name: 'tmp', mountPath: '/tmp' }],
+  };
+
+  if (Object.keys(resources).length > 0) {
+    container.resources = resources;
+  }
 
   return {
     apiVersion: 'serving.knative.dev/v1',
     kind: 'Service',
-    metadata: { name: fnName, namespace: namespaceName } as {
-      name: string;
-      namespace: string;
-      resourceVersion?: string;
-      annotations?: Record<string, string>;
-      labels?: Record<string, string>;
+    metadata: {
+      name: fnName,
+      namespace: namespaceName,
+      labels: { ...labels },
+      annotations: {},
     },
     spec: {
       template: {
         metadata: {
-          annotations: Object.keys(annotations).length > 0 ? annotations : undefined,
+          labels: { ...labels },
+          annotations: Object.keys(templateAnnotations).length > 0 ? templateAnnotations : undefined,
         },
         spec: {
           containerConcurrency: concurrency || undefined,
           timeoutSeconds,
-          containers: [
-            {
-              image,
-              envFrom: [{ secretRef: { name: `${namespaceName}-secrets` } }],
-              ...(Object.keys(resources).length > 0 ? { resources } : {}),
-            },
-          ],
+          containers: [container],
+          volumes: [{ name: 'tmp', emptyDir: {} }],
         },
       },
     },
   };
 }
 
+// ── Namespace resolver ───────────────────────────────────────────────────────
+
 /**
  * Resolve a namespace name from a namespace_id. Returns 'default' if null.
  */
diff --git a/packages/provisioning-handlers/src/seed.ts b/packages/provisioning-handlers/src/seed.ts
@@ -17,10 +17,50 @@ import { Logger } from '@pgpmjs/logger';
 import type { Pool } from 'pg';
 
 import { getK8sClient, isConflict } from './k8s-client';
+import type { KnativeServiceSpec } from './knative';
 import { buildKnativeServiceSpec, resolveNamespaceName } from './knative';
 
 const log = new Logger('provisioning:seed');
 
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * GET → merge immutable metadata → PUT.
+ *
+ * Knative's admission webhook sets immutable annotations
+ * (e.g. serving.knative.dev/creator) and K8s requires
+ * resourceVersion for optimistic-concurrency on PUT.
+ * This helper fetches both from the live object and merges
+ * them into the desired spec before replacing.
+ */
+export async function mergeAndReplace(
+  client: import('@kubernetesjs/ops').InterwebClient,
+  spec: KnativeServiceSpec,
+  name: string,
+  namespace: string
+) {
+  const existing = await client.readServingKnativeDevV1NamespacedService({
+    query: {},
+    path: { name, namespace },
+  });
+
+  spec.metadata.resourceVersion = existing?.metadata?.resourceVersion;
+
+  const existingAnnotations = (existing?.metadata?.annotations ?? {}) as Record<string, string>;
+  spec.metadata.annotations = { ...existingAnnotations, ...spec.metadata.annotations };
+
+  const existingLabels = (existing?.metadata?.labels ?? {}) as Record<string, string>;
+  spec.metadata.labels = { ...existingLabels, ...spec.metadata.labels };
+
+  return client.replaceServingKnativeDevV1NamespacedService({
+    query: {},
+    path: { name, namespace },
+    body: spec,
+  });
+}
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
 export interface ProvisionSeedOptions {
   pool: Pool;
   databaseId: string;
@@ -191,25 +231,7 @@ export async function provision(opts: ProvisionSeedOptions): Promise<ProvisionSe
       result.functions.push({ name: fnName, namespace: namespaceName, serviceUrl, status: 'created' });
     } catch (err: unknown) {
       if (isConflict(err)) {
-        // GET the existing service to retrieve metadata required for PUT
-        const existing = await client.readServingKnativeDevV1NamespacedService({
-          query: {},
-          path: { name: fnName, namespace: namespaceName },
-        });
-        if (serviceSpec.metadata) {
-          serviceSpec.metadata.resourceVersion = existing?.metadata?.resourceVersion;
-          // Preserve Knative-managed annotations (e.g. serving.knative.dev/creator)
-          const existingAnnotations = (existing?.metadata?.annotations ?? {}) as Record<string, string>;
-          serviceSpec.metadata.annotations = { ...existingAnnotations, ...serviceSpec.metadata.annotations };
-          const existingLabels = (existing?.metadata?.labels ?? {}) as Record<string, string>;
-          serviceSpec.metadata.labels = { ...existingLabels, ...serviceSpec.metadata.labels };
-        }
-
-        const svc = await client.replaceServingKnativeDevV1NamespacedService({
-          query: {},
-          path: { name: fnName, namespace: namespaceName },
-          body: serviceSpec,
-        });
+        const svc = await mergeAndReplace(client, serviceSpec, fnName, namespaceName);
         serviceUrl = svc?.status?.url ?? svc?.status?.address?.url ?? null;
         log.info(`replaced Knative Service "${fnName}" in "${namespaceName}"`);
         result.functions.push({ name: fnName, namespace: namespaceName, serviceUrl, status: 'exists' });
diff --git a/tests/integration/provisioning-knative.test.ts b/tests/integration/provisioning-knative.test.ts
