feat!: only allow creation of one UDSPackage per namespace

docs/reference/configuration/UDS operator/package.md

@@ -5,7 +5,12 @@ title: UDS Package
 ![UDS Operator Package Flowchart](https://github.com/defenseunicorns/uds-core/blob/main/docs/.images/diagrams/uds-core-operator-uds-package.svg?raw=true)
 
 ## Package
+:::note
+Only one UDS Package Custom Resource can exist in a namespace. This pattern was chosen by design to better enable workload isolation and to reduce complexity.
+:::
+Namespaces are a common boundary for isolating workloads in multi-tenant clusters. When defining a UDS Package resource, consider the implications for all workloads that exist in the target namespace. If the UDS Package that you are defining has configurations that conflict with each other or would be simplified by using a separate UDS Package definition, consider using a separate Kubernetes namespace. Read more about namespaces and mulitenancy [here](https://kubernetes.io/docs/concepts/security/multi-tenancy/).
 
+The UDS Operator seamlessly enables the following enhancements and protections for your workloads:
 - **Enabling Istio Sidecar Injection:**
   - The operator facilitates the activation of Istio sidecar injection within namespaces where the CR is deployed.
 - **Support for Istio Ambient Mode:**

pepr.ts

@@ -10,11 +10,12 @@ import cfg from "./package.json";
 import { Component, setupLogger } from "./src/pepr/logger";
 import { operator } from "./src/pepr/operator";
 import { setupAuthserviceSecret } from "./src/pepr/operator/controllers/keycloak/authservice/config";
+import { setupKeycloakClientSecret } from "./src/pepr/operator/controllers/keycloak/config";
+import { startPackageWatch } from "./src/pepr/operator/controllers/packages/packages";
 import { registerCRDs } from "./src/pepr/operator/crd/register";
 import { patches } from "./src/pepr/patches";
 import { policies, startExemptionWatch } from "./src/pepr/policies";
 import { prometheus } from "./src/pepr/prometheus";
-import { setupKeycloakClientSecret } from "./src/pepr/operator/controllers/keycloak/config";
 
 const log = setupLogger(Component.STARTUP);
 
@@ -23,6 +24,7 @@ const log = setupLogger(Component.STARTUP);
   await registerCRDs();
   // KFC watch for exemptions and update in-memory map
   await startExemptionWatch();
+  await startPackageWatch();
   await setupAuthserviceSecret();
   await setupKeycloakClientSecret();
   new PeprModule(cfg, [

src/pepr/logger.ts

@@ -17,6 +17,7 @@ export enum Component {
   OPERATOR_AUTHSERVICE = "operator.authservice",
   OPERATOR_MONITORING = "operator.monitoring",
   OPERATOR_NETWORK = "operator.network",
+  OPERATOR_PACKAGES = "operator.packages",
   OPERATOR_GENERATORS = "operator.generators",
   OPERATOR_CRD = "operator.crd",
   OPERATOR_RECONCILERS = "operator.reconcilers",

src/pepr/operator/controllers/packages/package-store.spec.ts

@@ -0,0 +1,77 @@
+/**
+ * Copyright 2025 Defense Unicorns
+ * SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial
+ */
+
+import { describe, expect, it } from "@jest/globals";
+import { PeprValidateRequest } from "pepr";
+import { UDSPackage } from "../../crd";
+import { PackageStore } from "./package-store";
+PackageStore.init();
+
+const makeMockReq = (pkg: Partial<UDSPackage>) => {
+  const defaultPkg: UDSPackage = {
+    metadata: {
+      namespace: "application-system",
+      name: "application",
+    },
+    spec: {
+      network: {
+        expose: [],
+        allow: [],
+      },
+      sso: [],
+      monitor: [],
+    },
+  };
+  return {
+    Raw: { ...defaultPkg, ...pkg },
+  } as unknown as PeprValidateRequest<UDSPackage>;
+};
+
+describe("Package Store", () => {
+  it("Should add a package", async () => {
+    const mockReq = makeMockReq({});
+    const ns = mockReq.Raw.metadata?.namespace || "";
+    PackageStore.add(mockReq.Raw);
+    expect(PackageStore.hasKey(ns)).toEqual(true);
+  });
+
+  it("Should add multiple unique packages", async () => {
+    const mockReq = makeMockReq({});
+    const ns = mockReq.Raw.metadata?.namespace || "";
+    const mockReqNewPkg = makeMockReq({ metadata: { namespace: "test", name: "other-package" } });
+    const nsNewPkg = mockReqNewPkg.Raw.metadata?.namespace || "";
+    PackageStore.add(mockReqNewPkg.Raw);
+    let pkgsExist = false;
+    if (PackageStore.hasKey(ns) && PackageStore.hasKey(nsNewPkg)) {
+      pkgsExist = true;
+    }
+    expect(pkgsExist).toEqual(true);
+  });
+
+  it("Should return the first package in the namespace", async () => {
+    const mockReq = makeMockReq({});
+    const ns = mockReq.Raw.metadata?.namespace || "";
+    const pkgName = mockReq.Raw.metadata?.name || "";
+    expect(PackageStore.getPkgName(ns)).toEqual(pkgName);
+  });
+
+  it("Should update an existing package", async () => {
+    const mockReq = makeMockReq({
+      metadata: { namespace: "test", name: "other-package", labels: { test: "value" } },
+    });
+    const ns = mockReq.Raw.metadata?.namespace || "";
+    const pkgName = mockReq.Raw.metadata?.name || "";
+    PackageStore.add(mockReq.Raw);
+    const updatedPackage = PackageStore.getPkgName(ns);
+    expect(updatedPackage).toEqual(pkgName);
+  });
+
+  it("Should remove a package", async () => {
+    const mockReq = makeMockReq({});
+    const ns = mockReq.Raw.metadata?.namespace || "";
+    PackageStore.remove(mockReq.Raw);
+    expect(PackageStore.hasKey(ns)).toEqual(false);
+  });
+});

src/pepr/operator/controllers/packages/package-store.ts

@@ -0,0 +1,143 @@
+/**
+ * Copyright 2025 Defense Unicorns
+ * SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial
+ */
+
+/**
+ * A collection of functions related to watching UDSPackages
+ * Manages an in-memory map of UDSPackage resources
+ * Used in Pepr Validating Webhook Pods when vetting UDS Package resources for admission
+ */
+import { Component, setupLogger } from "../../../logger";
+import { UDSPackage } from "../../crd";
+const log = setupLogger(Component.OPERATOR_PACKAGES);
+
+// Map structure: namespace -> (package name -> package)
+export type PackageNamespaceMap = Map<string, Map<string, UDSPackage>>;
+let packageNamespaceMap: PackageNamespaceMap;
+
+/**
+ * Initializes the package namespace map.
+ *
+ * This function creates a new `Map` object and assigns it to the `packageNamespaceMap` variable.
+ * The `packageNamespaceMap` is used to store packages, using their namespace as the key.
+ */
+function init(): void {
+  packageNamespaceMap = new Map();
+}
+
+/**
+ * Adds a package to the package namespace map.
+ *
+ * @param {UDSPackage} pkg - The package to be added. It should contain metadata with a namespace and name.
+ * @param {boolean} [logger=true] - Optional flag to enable logging. Defaults to true.
+ *
+ * This function retrieves the namespace and name from the package metadata and adds the package
+ * to the packageNamespaceMap. If the namespace doesn't exist, it creates a new map for that namespace.
+ * The function then adds or updates the package in the namespace map using the package name as the key.
+ */
+function add(pkg: UDSPackage, logger: boolean = true): void {
+  if (!pkg.metadata?.namespace || !pkg.metadata.name) {
+    throw new Error(`Invalid Package definition, missing namespace or name`);
+  }
+  const namespace = pkg.metadata.namespace;
+  const name = pkg.metadata.name;
+
+  // Get or create the namespace map
+  if (!packageNamespaceMap.has(namespace)) {
+    packageNamespaceMap.set(namespace, new Map());
+  }
+
+  const namespaceMap = packageNamespaceMap.get(namespace)!;
+  const isUpdate = namespaceMap.has(name);
+
+  // Set the package
+  namespaceMap.set(name, pkg);
+
+  if (logger) {
+    if (isUpdate) {
+      log.debug(`Updating PackageStore for package ${name} in namespace ${namespace}.`);
+    } else {
+      log.debug(`Added package: ${namespace}/${name} to package map`);
+    }
+  }
+}
+
+/**
+ * Removes a package from the package namespace map.
+ *
+ * @param {UDSPackage} pkg - The package to be removed. It should contain metadata with a namespace and name.
+ * @param {boolean} [logger=true] - Optional flag to enable logging. Defaults to true.
+ *
+ * This function retrieves the namespace and name from the package metadata and removes the package
+ * from the packageNamespaceMap. If the namespace map becomes empty after removal, the namespace
+ * is also removed from the packageNamespaceMap.
+ */
+function remove(pkg: UDSPackage, logger: boolean = true): void {
+  if (!pkg.metadata?.namespace || !pkg.metadata.name) {
+    throw new Error(`Invalid Package definition, missing namespace or name`);
+  }
+
+  const namespace = pkg.metadata.namespace;
+  const name = pkg.metadata.name;
+
+  const namespaceMap = packageNamespaceMap.get(namespace);
+  if (!namespaceMap) {
+    // Namespace doesn't exist, nothing to remove
+    return;
+  }
+
+  // Remove the package
+  namespaceMap.delete(name);
+
+  // If namespace map is empty, remove the namespace
+  if (namespaceMap.size === 0) {
+    packageNamespaceMap.delete(namespace);
+  }
+
+  if (logger) {
+    log.debug(`Removed package: ${namespace}/${name} from package map`);
+  }
+}
+
+/**
+ * Checks if a given namespace exists within the package namespace map.
+ *
+ * This function determines whether a namespace has been previously registered
+ * in the `packageNamespaceMap`.  It provides a way to verify the existence
+ * of a package in a given namespace.
+ *
+ * @param namespace The namespace to check for existence.
+ * @returns `true` if the namespace exists in the map; otherwise, `false`.
+ */
+function hasKey(namespace: string): boolean {
+  return packageNamespaceMap.has(namespace);
+}
+
+/**
+ * Retrieves the package name associated with a given namespace.
+ *
+ * This function looks up the namespace in the `packageNamespaceMap` and, if found,
+ * returns the name of the first package in that namespace.
+ * If the namespace is not found or there are no packages, it returns null.
+ *
+ * @param namespace The namespace to look up in the `packageNamespaceMap`.
+ * @returns The package name associated with the namespace, or null if not found.
+ */
+function getPkgName(namespace: string): string | null {
+  const namespaceMap = packageNamespaceMap.get(namespace);
+  if (!namespaceMap || namespaceMap.size === 0) {
+    return null;
+  }
+
+  // Return the name of the first package in the namespace
+  return Array.from(namespaceMap.keys())[0];
+}
+
+export const PackageStore = {
+  init,
+  add,
+  hasKey,
+  getPkgName,
+  remove,
+};

src/pepr/operator/controllers/packages/packages.spec.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright 2025 Defense Unicorns
+ * SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial
+ */
+
+import { WatchPhase } from "kubernetes-fluent-client/dist/fluent/types";
+import { PeprValidateRequest } from "pepr";
+import { UDSPackage } from "../../crd";
+import { PackageStore } from "./package-store";
+import { processPackages } from "./packages";
+
+PackageStore.init();
+
+const makeMockReq = (pkg: Partial<UDSPackage>) => {
+  const defaultPkg: UDSPackage = {
+    metadata: {
+      namespace: "application-system",
+      name: "application",
+    },
+    spec: {
+      network: {
+        expose: [],
+        allow: [],
+      },
+      sso: [],
+      monitor: [],
+    },
+  };
+  return {
+    Raw: { ...defaultPkg, ...pkg },
+  } as unknown as PeprValidateRequest<UDSPackage>;
+};
+
+describe("Package Watch", () => {
+  it("Should add a package", async () => {
+    const mockReq = makeMockReq({});
+    const ns = mockReq.Raw.metadata?.namespace || "";
+    processPackages(mockReq.Raw, WatchPhase.Added);
+    const addedPackage = PackageStore.hasKey(ns);
+    expect(addedPackage).toBe(true);
+  });
+
+  it("Should add multiple unique packages", async () => {
+    const mockReq = makeMockReq({});
+    const ns = mockReq.Raw.metadata?.namespace || "";
+    const mockReqNewPkg = makeMockReq({ metadata: { namespace: "test", name: "other-package" } });
+    const nsNewPkg = mockReqNewPkg.Raw.metadata?.namespace || "";
+    processPackages(mockReqNewPkg.Raw, WatchPhase.Added);
+    let pkgsExist = false;
+    if (PackageStore.hasKey(ns) && PackageStore.hasKey(nsNewPkg)) {
+      pkgsExist = true;
+    }
+    expect(pkgsExist).toBe(true);
+  });
+
+  it("Should remove packages", async () => {
+    const mockReq = makeMockReq({});
+    const mockReqNewPkg = makeMockReq({ metadata: { namespace: "test", name: "other-package" } });
+    const ns = mockReq.Raw.metadata?.namespace || "";
+    const nsNewPkg = mockReqNewPkg.Raw.metadata?.namespace || "";
+    processPackages(mockReq.Raw, WatchPhase.Deleted);
+    processPackages(mockReqNewPkg.Raw, WatchPhase.Deleted);
+    let pkgsExist = false;
+    if (PackageStore.hasKey(ns) && PackageStore.hasKey(nsNewPkg)) {
+      pkgsExist = true;
+    }
+    expect(pkgsExist).toBe(false);
+  });
+});