@highstate/k8s 0.9.18 → 0.9.20

package/src/namespace.ts

@@ -1,34 +1,46 @@
 import type { k8s } from "@highstate/library"
+import { getOrCreate } from "@highstate/contract"
+import { toPromise } from "@highstate/pulumi"
 import { core, type types } from "@pulumi/kubernetes"
 import {
   ComponentResource,
-  output,
-  Output,
   type ComponentResourceOptions,
   type Input,
   type Inputs,
+  type Output,
+  output,
   type Unwrap,
 } from "@pulumi/pulumi"
-import { getProvider, mapMetadata, type CommonArgs } from "./shared"
+import { getProvider, mapMetadata, type ScopedResourceArgs, validateCluster } from "./shared"
+
+export type NamespaceArgs = Omit<ScopedResourceArgs, "namespace"> & {
+  /**
+   * The cluster where the namespace is located.
+   */
+  cluster: Input<k8s.Cluster>
 
-export type NamespaceArgs = Omit<CommonArgs, "namespace"> & {
   /**
    * Whether to apply "pod-security.kubernetes.io/enforce=privileged" label to the namespace.
    */
   privileged?: boolean
 }
 
-export type CreateOrPatchNamespaceArgs = NamespaceArgs & {
+export type CreateOrGetNamespaceArgs = NamespaceArgs & {
   /**
    * The resource to use to determine the name of the namespace.
    *
    * If not provided, the namespace will be created, otherwise it will be retrieved/patched.
    */
-  resource: Input<k8s.Resource> | undefined
+  resource?: Input<k8s.ScopedResource>
+
+  /**
+   * The namespace entity to patch/retrieve.
+   */
+  existing?: Input<k8s.Namespace> | undefined
 }
 
 export abstract class Namespace extends ComponentResource {
-  protected constructor(
+  constructor(
     type: string,
     name: string,
     args: Inputs,
@@ -57,6 +69,18 @@ export abstract class Namespace extends ComponentResource {
     super(type, name, args, opts)
   }
 
+  /**
+   * The Highstate namespace entity.
+   */
+  get entity(): Output<k8s.Namespace> {
+    return output({
+      type: "namespace",
+      clusterId: this.cluster.id,
+      clusterName: this.cluster.name,
+      metadata: this.metadata,
+    })
+  }
+
   /**
    * Creates a new namespace.
    */
@@ -65,71 +89,78 @@ export abstract class Namespace extends ComponentResource {
   }
 
   /**
-   * Creates a new namespace or patches an existing one.
-   *
-   * Will throw an error if the namespace does not exist when `args.resource` is provided.
+   * Wraps an existing Kubernetes namespace.
    */
-  static createOrPatch(
+  static wrap(
     name: string,
-    args: CreateOrPatchNamespaceArgs,
+    args: WrappedNamespaceArgs,
     opts?: ComponentResourceOptions,
   ): Namespace {
-    if (!args.resource) {
-      return new CreatedNamespace(name, args, opts)
+    return new WrappedNamespace(name, args, opts)
+  }
+
+  /**
+   * Creates a new namespace or gets an existing one.
+   *
+   * @param name The name of the resource. May not be the same as the namespace name. Will not be used when existing namespace is retrieved.
+   * @param args The arguments to create or get the namespace with.
+   * @param opts Optional resource options.
+   */
+  static async createOrGet(
+    name: string,
+    args: CreateOrGetNamespaceArgs,
+    opts?: ComponentResourceOptions,
+  ): Promise<Namespace> {
+    if (args.resource) {
+      return await Namespace.forResourceAsync(args.resource, args.cluster)
     }
 
-    return new NamespacePatch(
-      name,
-      {
-        ...args,
-        name: output(args).apply(args => {
-          if (args.resource!.clusterId !== args.cluster.id) {
-            throw new Error(
-              `Cluster mismatch when patching namespace "${name}": "${args.resource!.clusterId}" != "${args.cluster.id}"`,
-            )
-          }
-
-          return args.resource!.metadata.namespace
-        }),
-      },
-      opts,
-    )
+    if (args.existing) {
+      return await Namespace.forAsync(args.existing, args.cluster)
+    }
+
+    return new CreatedNamespace(name, args, opts)
   }
 
   /**
-   * Creates a new namespace or gets an existing one.
+   * Creates a new namespace or patches an existing one.
    *
-   * Will throw an error if the namespace does not exist when `args.resource` is provided.
+   * @param name The name of the resource. May not be the same as the namespace name.
+   * @param args The arguments to create or patch the namespace with.
+   * @param opts Optional resource options.
    */
-  static createOrGet(
+  static createOrPatch(
     name: string,
-    args: CreateOrPatchNamespaceArgs,
+    args: CreateOrGetNamespaceArgs,
     opts?: ComponentResourceOptions,
   ): Namespace {
-    if (!args.resource) {
-      return new CreatedNamespace(name, args, opts)
+    if (args.resource) {
+      return new NamespacePatch(name, {
+        ...args,
+        name: output(args.resource).metadata.namespace,
+        cluster: validateCluster(args.resource, args.cluster),
+      })
     }
 
-    return new ExternalNamespace(
-      name,
-      output(args).apply(args => {
-        if (args.resource!.clusterId !== args.cluster.id) {
-          throw new Error(
-            `Cluster mismatch when receiving namespace "${name}": "${args.resource!.clusterId}" != "${args.cluster.id}"`,
-          )
-        }
-
-        return args.resource!.metadata.namespace
-      }),
-      args.cluster,
-      opts,
-    )
+    if (args.existing) {
+      return new NamespacePatch(name, {
+        ...args,
+        name: output(args.existing).metadata.name,
+        cluster: validateCluster(args.existing, args.cluster),
+      })
+    }
+
+    return new CreatedNamespace(name, args, opts)
   }
 
   /**
    * Patches an existing namespace.
    *
    * Will throw an error if the namespace does not exist.
+   *
+   * @param name The name of the resource. May not be the same as the namespace name.
+   * @param args The arguments to patch the namespace with.
+   * @param opts Optional resource options.
    */
   static patch(name: string, args: NamespaceArgs, opts?: ComponentResourceOptions): Namespace {
     return new NamespacePatch(name, args, opts)
@@ -139,43 +170,125 @@ export abstract class Namespace extends ComponentResource {
    * Gets an existing namespace.
    *
    * Will throw an error if the namespace does not exist.
+   *
+   * @param name The name of the resource. May not be the same as the namespace name.
+   * @param args The arguments to get the namespace with.
+   * @param opts Optional resource options.
    */
   static get(
     name: string,
-    id: Input<string>,
-    cluster: Input<k8s.Cluster>,
+    args: ExternalNamespaceArgs,
     opts?: ComponentResourceOptions,
   ): Namespace {
-    return new ExternalNamespace(name, id, cluster, opts)
+    return new ExternalNamespace(name, args, opts)
   }
-}
 
-function mapNamespaceMetadata(
-  args: Unwrap<NamespaceArgs>,
-  name: string,
-): types.input.meta.v1.ObjectMeta {
-  const labels: Record<string, string> = args.metadata?.labels ?? {}
+  private static readonly namespaceCache = new Map<string, Namespace>()
+
+  /**
+   * Gets an existing namespace for a given entity.
+   * Prefer this method over `get` when possible.
+   *
+   * It automatically names the resource with the following format: `{clusterName}.{namespace}.{clusterId}`.
+   *
+   * This method it idempotent and will return the same instance for the same entity.
+   *
+   * @param entity The entity to get the namespace for.
+   * @param cluster The cluster where the namespace is located.
+   */
+  static for(entity: k8s.Namespace, cluster: Input<k8s.Cluster>): Namespace {
+    return getOrCreate(
+      Namespace.namespaceCache,
+      `${entity.clusterName}.${entity.metadata.name}.${entity.clusterId}`,
+      name => {
+        return Namespace.get(name, {
+          name: entity.metadata.name,
+          cluster: validateCluster(entity, cluster),
+        })
+      },
+    )
+  }
 
-  if (args.privileged) {
-    labels["pod-security.kubernetes.io/enforce"] = "privileged"
+  /**
+   * Gets an existing namespace for a given entity.
+   * Prefer this method over `get` when possible.
+   *
+   * @param entity The entity to get the namespace for.
+   * @param cluster The cluster where the namespace is located.
+   */
+  static async forAsync(
+    entity: Input<k8s.Namespace>,
+    cluster: Input<k8s.Cluster>,
+  ): Promise<Namespace> {
+    const resolvedEntity = await toPromise(entity)
+
+    return Namespace.for(resolvedEntity, cluster)
   }
 
-  return { ...mapMetadata(args, name), labels }
+  /**
+   * Gets an existing namespace where the provided resource is located.
+   * Prefer this method over `get` when possible.
+   *
+   * It automatically names the resource with the following format: `{clusterName}.{namespace}.{clusterId}`.
+   *
+   * This method it idempotent and will return the same instance for the same resource.
+   *
+   * @param resource The resource to get the namespace for.
+   * @param cluster The cluster where the namespace is located.
+   */
+  static forResource(resource: k8s.ScopedResource, cluster: Input<k8s.Cluster>): Namespace {
+    return getOrCreate(
+      Namespace.namespaceCache,
+      `${resource.clusterName}.${resource.metadata.namespace}.${resource.clusterId}`,
+      name => {
+        return Namespace.get(name, {
+          name: resource.metadata.namespace,
+          cluster: validateCluster(resource, cluster),
+        })
+      },
+    )
+  }
+
+  /**
+   * Gets an existing namespace for a given entity.
+   * Prefer this method over `get` when possible.
+   *
+   * @param resource The resource to get the namespace for.
+   * @param cluster The cluster where the namespace is located.
+   */
+  static async forResourceAsync(
+    resource: Input<k8s.ScopedResource>,
+    cluster: Input<k8s.Cluster>,
+  ): Promise<Namespace> {
+    const resolvedResource = await toPromise(resource)
+
+    return Namespace.forResource(resolvedResource, cluster)
+  }
+}
+
+function mapNamespaceMetadata(
+  args: NamespaceArgs,
+  fallbackName: string,
+): Output<Unwrap<types.input.meta.v1.ObjectMeta>> {
+  return mapMetadata(args, fallbackName).apply(metadata => {
+    if (args.privileged) {
+      metadata.labels = {
+        ...metadata.labels,
+        "pod-security.kubernetes.io/enforce": "privileged",
+      }
+    }
+
+    return metadata
+  })
 }
 
 class CreatedNamespace extends Namespace {
   constructor(name: string, args: NamespaceArgs, opts?: ComponentResourceOptions) {
-    const namespace = output(args).apply(async args => {
+    const namespace = output(args.cluster).apply(cluster => {
       return new core.v1.Namespace(
         name,
-        {
-          metadata: mapNamespaceMetadata(args, name),
-        },
-        {
-          ...opts,
-          parent: this,
-          provider: await getProvider(args.cluster),
-        },
+        { metadata: mapNamespaceMetadata(args, name) },
+        { ...opts, parent: this, provider: getProvider(cluster) },
       )
     })
 
@@ -194,17 +307,11 @@ class CreatedNamespace extends Namespace {
 
 class NamespacePatch extends Namespace {
   constructor(name: string, args: NamespaceArgs, opts?: ComponentResourceOptions) {
-    const namespace = output(args).apply(async args => {
+    const namespace = output(args.cluster).apply(cluster => {
       return new core.v1.NamespacePatch(
         name,
-        {
-          metadata: mapNamespaceMetadata(args, name),
-        },
-        {
-          ...opts,
-          parent: this,
-          provider: await getProvider(args.cluster),
-        },
+        { metadata: mapNamespaceMetadata(args, name) },
+        { ...opts, parent: this, provider: getProvider(cluster) },
       )
     })
 
@@ -221,35 +328,65 @@ class NamespacePatch extends Namespace {
   }
 }
 
+export type WrappedNamespaceArgs = {
+  /**
+   * The underlying Kubernetes namespace to wrap.
+   */
+  namespace: Input<core.v1.Namespace>
+
+  /**
+   * The cluster where the namespace is located.
+   */
+  cluster: Input<k8s.Cluster>
+}
+
+export type ExternalNamespaceArgs = {
+  /**
+   * The real name of the namespace in the cluster.
+   */
+  name: Input<string>
+
+  /**
+   * The cluster where the namespace is located.
+   */
+  cluster: Input<k8s.Cluster>
+}
+
 class ExternalNamespace extends Namespace {
-  constructor(
-    name: string,
-    id: Input<string>,
-    cluster: Input<k8s.Cluster>,
-    opts?: ComponentResourceOptions,
-  ) {
-    const namespace = output(id).apply(async realName => {
-      return core.v1.Namespace.get(
-        //
-        name,
-        realName,
-        {
-          ...opts,
-          parent: this,
-          provider: await getProvider(cluster),
-        },
-      )
+  constructor(name: string, args: ExternalNamespaceArgs, opts?: ComponentResourceOptions) {
+    const namespace = output(args.cluster).apply(cluster => {
+      return core.v1.Namespace.get(name, args.name, {
+        ...opts,
+        parent: this,
+        provider: getProvider(cluster),
+      })
     })
 
     super(
       "highstate:k8s:ExternalNamespace",
       name,
-      { id, cluster },
+      args,
       opts,
-      output(cluster),
+      output(args.cluster),
       namespace.metadata,
       namespace.spec,
       namespace.status,
     )
   }
 }
+
+class WrappedNamespace extends Namespace {
+  constructor(name: string, args: WrappedNamespaceArgs, opts?: ComponentResourceOptions) {
+    super(
+      "highstate:k8s:WrappedNamespace",
+      name,
+      args,
+      opts,
+
+      output(args.cluster),
+      output(args.namespace).metadata,
+      output(args.namespace).spec,
+      output(args.namespace).status,
+    )
+  }
+}