@highstate/library 0.15.0 → 0.16.0

package/src/k8s/resources.ts

@@ -1,3 +1,4 @@
+import type { Simplify, SimplifyDeep } from "type-fest"
 import { defineEntity, z } from "@highstate/contract"
 
 /**
@@ -8,6 +9,7 @@ export const metadataSchema = z.object({
   labels: z.record(z.string(), z.string()).optional(),
   annotations: z.record(z.string(), z.string()).optional(),
   uid: z.string(),
+  namespace: z.string().optional(),
 })
 
 /**
@@ -15,31 +17,48 @@ export const metadataSchema = z.object({
  *
  * It includes the namespace field.
  */
-export const scopedMetadataSchema = z.object({
+export const namespacedMetadataSchema = z.object({
   ...metadataSchema.shape,
   namespace: z.string(),
 })
 
 /**
- * The base schema for Kubernetes resources.
- *
- * It includes the cluster ID and name, which are required for all Kubernetes resources.
+ * The entity which represents a Kubernetes resource.
  */
-export const resourceSchema = z.object({
-  clusterId: z.string(),
-  clusterName: z.string(),
-  type: z.string(),
-  metadata: metadataSchema,
+export const resourceEntity = defineEntity({
+  type: "k8s.resource.v1",
+
+  schema: z.intersection(
+    z.object({
+      clusterId: z.string(),
+      clusterName: z.string(),
+      apiVersion: z.string(),
+      kind: z.string(),
+    }),
+    z.union([
+      z.object({
+        isNamespaced: z.literal(false),
+        metadata: metadataSchema,
+      }),
+      z.object({
+        isNamespaced: z.literal(true),
+        metadata: namespacedMetadataSchema,
+      }),
+    ]),
+  ),
 })
 
 /**
- * The schema for Kubernetes resources that are scoped to a namespace.
- *
- * Extends the base resource schema with the scoped metadata.
+ * The entity which represents a Kubernetes resource scoped to a namespace.
  */
-export const scopedResourceSchema = z.object({
-  ...resourceSchema.shape,
-  metadata: scopedMetadataSchema,
+export const namespacedResourceEntity = defineEntity({
+  type: "k8s.namespaced-resource.v1",
+
+  extends: { resourceEntity },
+
+  schema: z.object({
+    isNamespaced: z.literal(true),
+  }),
 })
 
 /**
@@ -48,10 +67,8 @@ export const scopedResourceSchema = z.object({
 export const namespaceEntity = defineEntity({
   type: "k8s.namespace.v1",
 
-  schema: z.object({
-    ...resourceSchema.shape,
-    type: z.literal("namespace"),
-  }),
+  extends: { resourceEntity },
+  schema: z.unknown(),
 
   meta: {
     color: "#9E9E9E",
@@ -64,10 +81,8 @@ export const namespaceEntity = defineEntity({
 export const persistentVolumeClaimEntity = defineEntity({
   type: "k8s.persistent-volume-claim.v1",
 
-  schema: z.object({
-    ...scopedResourceSchema.shape,
-    type: z.literal("persistent-volume-claim"),
-  }),
+  extends: { namespacedResourceEntity },
+  schema: z.unknown(),
 
   meta: {
     color: "#FFC107",
@@ -80,10 +95,8 @@ export const persistentVolumeClaimEntity = defineEntity({
 export const gatewayEntity = defineEntity({
   type: "k8s.gateway.v1",
 
-  schema: z.object({
-    ...scopedResourceSchema.shape,
-    type: z.literal("gateway"),
-  }),
+  extends: { namespacedResourceEntity },
+  schema: z.unknown(),
 
   meta: {
     color: "#4CAF50",
@@ -93,19 +106,49 @@ export const gatewayEntity = defineEntity({
 export const certificateEntity = defineEntity({
   type: "k8s.certificate.v1",
 
-  schema: z.object({
-    ...scopedResourceSchema.shape,
-    type: z.literal("certificate"),
-  }),
+  extends: { namespacedResourceEntity },
+  schema: z.unknown(),
+
+  meta: {
+    color: "#3F51B5",
+  },
+})
+
+export const configMapEntity = defineEntity({
+  type: "k8s.config-map.v1",
+
+  extends: { namespacedResourceEntity },
+  schema: z.unknown(),
+
+  meta: {
+    color: "#FF9800",
+  },
+})
+
+export const secretEntity = defineEntity({
+  type: "k8s.secret.v1",
+
+  extends: { namespacedResourceEntity },
+  schema: z.unknown(),
+
+  meta: {
+    color: "#9C27B0",
+  },
 })
 
 export type Metadata = z.infer<typeof metadataSchema>
-export type Resource = z.infer<typeof resourceSchema>
+export type Resource = z.infer<typeof resourceEntity.schema>
+
+export type NamespacedMetadata = z.infer<typeof namespacedMetadataSchema>
 
-export type ScopedMetadata = z.infer<typeof scopedMetadataSchema>
-export type ScopedResource = z.infer<typeof scopedResourceSchema>
+export type NamespacedResource = SimplifyDeep<
+  z.infer<typeof namespacedResourceEntity.schema>,
+  Record<string, string>
+>
 
-export type Namespace = z.infer<typeof namespaceEntity.schema>
+export type Namespace = Simplify<z.infer<typeof namespaceEntity.schema>>
 export type PersistentVolumeClaim = z.infer<typeof persistentVolumeClaimEntity.schema>
 export type Gateway = z.infer<typeof gatewayEntity.schema>
 export type Certificate = z.infer<typeof certificateEntity.schema>
+export type ConfigMap = z.infer<typeof configMapEntity.schema>
+export type Secret = z.infer<typeof secretEntity.schema>

package/src/k8s/service.ts

@@ -1,8 +1,9 @@
+import type { Simplify } from "type-fest"
 import { defineEntity, z } from "@highstate/contract"
 import { l4EndpointEntity } from "../network"
-import { scopedResourceSchema } from "./resources"
+import { namespacedResourceEntity } from "./resources"
 
-export const endpointServiceMetadataSchema = z.object({
+export const serviceEndpointMetadataSchema = z.object({
   "k8s.service": z.object({
     /**
      * The ID of the cluster where the service is located.
@@ -24,6 +25,11 @@ export const endpointServiceMetadataSchema = z.object({
      */
     namespace: z.string(),
 
+    /**
+     * Whether this endpoint is only accessible within the cluster.
+     */
+    isInternal: z.boolean(),
+
     /**
      * The selector of the service.
      */
@@ -39,18 +45,23 @@ export const endpointServiceMetadataSchema = z.object({
 export const serviceEndpointSchema = z.intersection(
   l4EndpointEntity.schema,
   z.object({
-    metadata: endpointServiceMetadataSchema,
+    metadata: serviceEndpointMetadataSchema,
   }),
 )
 
 export const serviceEntity = defineEntity({
   type: "k8s.service.v1",
 
-  schema: z.object({
-    ...scopedResourceSchema.shape,
-    type: z.literal("service"),
-    endpoints: serviceEndpointSchema.array(),
-  }),
+  extends: { namespacedResourceEntity },
+
+  includes: {
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
+
+  schema: z.unknown(),
 
   meta: {
     color: "#2196F3",
@@ -59,7 +70,7 @@ export const serviceEntity = defineEntity({
 
 export const serviceTypeSchema = z.enum(["NodePort", "LoadBalancer", "ClusterIP"])
 
-export type EndpointServiceMetadata = z.infer<typeof endpointServiceMetadataSchema>
-export type ServiceEndpoint = z.infer<typeof serviceEndpointSchema>
+export type EndpointServiceMetadata = z.infer<typeof serviceEndpointMetadataSchema>
+export type ServiceEndpoint = Simplify<z.infer<typeof serviceEndpointSchema>>
 export type ServiceType = z.infer<typeof serviceTypeSchema>
 export type Service = z.infer<typeof serviceEntity.schema>

package/src/k8s/shared.ts

@@ -1,17 +1,16 @@
 import { $args, defineEntity, defineUnit, z } from "@highstate/contract"
 import { serverEntity } from "../common"
-import * as dns from "../dns"
 import { implementationReferenceSchema } from "../impl-ref"
-import { l3EndpointEntity, l4EndpointEntity } from "../network"
-import { arrayPatchModeSchema } from "../utils"
-import { scopedResourceSchema } from "./resources"
+import { addressEntity, l3EndpointEntity, l4EndpointEntity } from "../network"
+import { metadataSchema } from "../utils"
+import { namespacedResourceEntity } from "./resources"
 
 export const fallbackKubeApiAccessSchema = z.object({
   serverIp: z.string(),
   serverPort: z.number(),
 })
 
-export const tunDevicePolicySchema = z.union([
+export const tunDevicePolicySchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("host"),
   }),
@@ -40,14 +39,14 @@ export const clusterQuirksSchema = z.object({
    *
    * For some runtimes, like Talos's one, the /dev/net/tun device is not available in the host, so the plugin policy should be used.
    */
-  tunDevicePolicy: tunDevicePolicySchema.optional(),
+  tunDevicePolicy: tunDevicePolicySchema.prefault({ type: "host" }),
 
   /**
    * The service type to use for external services.
    *
    * If not provided, the default service type is `NodePort` since `LoadBalancer` may not be available.
    */
-  externalServiceType: externalServiceTypeSchema.optional(),
+  externalServiceType: externalServiceTypeSchema.default("NodePort"),
 })
 
 export const clusterInfoProperties = {
@@ -79,15 +78,6 @@ export const clusterInfoProperties = {
    */
   networkPolicyImplRef: implementationReferenceSchema.optional(),
 
-  /**
-   * The endpoints of the cluster nodes.
-   *
-   * The entry may represent real node endpoint or virtual endpoint (like a load balancer).
-   *
-   * The same node may also be represented by multiple entries (e.g. a node with private and public IP).
-   */
-  endpoints: l3EndpointEntity.schema.array(),
-
   /**
    * The endpoints of the API server.
    *
@@ -100,7 +90,7 @@ export const clusterInfoProperties = {
   /**
    * The external IPs of the cluster nodes allowed to be used for external access.
    */
-  externalIps: z.string().array(),
+  externalIps: addressEntity.schema.array(),
 
   /**
    * The extra quirks of the cluster to improve compatibility.
@@ -110,12 +100,26 @@ export const clusterInfoProperties = {
   /**
    * The extra metadata to attach to the cluster.
    */
-  metadata: z.record(z.string(), z.unknown()).optional(),
+  metadata: metadataSchema.optional(),
 } as const
 
 export const clusterEntity = defineEntity({
   type: "k8s.cluster.v1",
 
+  includes: {
+    /**
+     * The endpoints of the cluster nodes.
+     *
+     * The entry may represent real node endpoint or virtual endpoint (like a load balancer).
+     *
+     * The same node may also be represented by multiple entries (e.g. a node with private and public IP).
+     */
+    endpoints: {
+      entity: l3EndpointEntity,
+      multiple: true,
+    },
+  },
+
   schema: z.object({
     ...clusterInfoProperties,
     kubeconfig: z.string(),
@@ -153,14 +157,6 @@ export const clusterInputs = {
 
 export const clusterOutputs = {
   k8sCluster: clusterEntity,
-  apiEndpoints: {
-    entity: l4EndpointEntity,
-    multiple: true,
-  },
-  endpoints: {
-    entity: l3EndpointEntity,
-    multiple: true,
-  },
 } as const
 
 /**
@@ -171,11 +167,9 @@ export const existingCluster = defineUnit({
 
   args: {
     /**
-     * The list of external IPs of the cluster nodes allowed to be used for external access.
-     *
-     * If not provided, will be automatically detected by querying the cluster nodes.
+     * Whether to auto-detect external IPs of the cluster nodes and merge them with the provided external IPs.
      */
-    externalIps: z.string().array().optional(),
+    autoDetectExternalIps: z.boolean().default(true),
 
     /**
      * The policy for using internal IPs of the nodes as external IPs.
@@ -183,13 +177,44 @@ export const existingCluster = defineUnit({
      * - `always`: always use internal IPs as external IPs;
      * - `public`: use internal IPs as external IPs only if they are (theoretically) routable from the public internet **(default)**;
      * - `never`: never use internal IPs as external IPs.
+     *
+     * Have no effect if `autoDetectExternalIps` is `false`.
      */
     internalIpsPolicy: internalIpsPolicySchema.default("public"),
 
+    /**
+     * The list of external IPs of the cluster nodes allowed to be used for external access.
+     */
+    externalIps: z.string().array().default([]),
+
+    /**
+     * Whether to use all external IPs (auto-detected and provided) as endpoints of the cluster.
+     *
+     * Set to `false` if you want to manage endpoints manually.
+     */
+    useExternalIpsAsEndpoints: z.boolean().default(true),
+
+    /**
+     * The list of endpoints of the cluster nodes.
+     */
+    endpoints: z.string().array().default([]),
+
+    /**
+     * Whether to add endpoints from `kubeconfig` to the list of API endpoints.
+     *
+     * Set to `false` if you want to manage API endpoints manually.
+     */
+    useKubeconfigApiEndpoint: z.boolean().default(true),
+
+    /**
+     * The list of endpoints of the API server.
+     */
+    apiEndpoints: z.string().array().default([]),
+
     /**
      * The extra quirks of the cluster to improve compatibility.
      */
-    quirks: clusterQuirksSchema.optional(),
+    quirks: clusterQuirksSchema.optional().meta({ complex: true }),
   },
 
   secrets: {
@@ -223,38 +248,14 @@ export const clusterPatch = defineUnit({
 
   args: {
     /**
-     * The endpoints of the API server.
-     *
-     * The entry may represent real node endpoint or virtual endpoint (like a load balancer).
-     *
-     * The same node may also be represented by multiple entries (e.g. a node with private and public IP).
-     */
-    apiEndpoints: z.string().array().default([]),
-
-    /**
-     * The mode to use for patching the API endpoints.
-     *
-     * - `prepend`: prepend the new endpoints to the existing ones (default);
-     * - `replace`: replace the existing endpoints with the new ones.
-     */
-    apiEndpointsPatchMode: arrayPatchModeSchema.default("prepend"),
-
-    /**
-     * The endpoints of the cluster nodes.
-     *
-     * The entry may represent real node endpoint or virtual endpoint (like a load balancer).
-     *
-     * The same node may also be represented by multiple entries (e.g. a node with private and public IP).
+     * The endpoints to set on the cluster.
      */
     endpoints: z.string().array().default([]),
 
     /**
-     * The mode to use for patching the endpoints.
-     *
-     * - `prepend`: prepend the new endpoints to the existing ones (default);
-     * - `replace`: replace the existing endpoints with the new ones.
+     * The API endpoints to set on the cluster.
      */
-    endpointsPatchMode: arrayPatchModeSchema.default("prepend"),
+    apiEndpoints: z.string().array().default([]),
   },
 
   inputs: {
@@ -286,37 +287,6 @@ export const clusterPatch = defineUnit({
   },
 })
 
-/**
- * Creates a set of DNS records for the cluster and updates the endpoints.
- */
-export const clusterDns = defineUnit({
-  type: "k8s.cluster-dns.v1",
-
-  args: {
-    ...dns.createArgs(),
-    ...dns.createArgs("api"),
-  },
-
-  inputs: {
-    k8sCluster: clusterEntity,
-    ...dns.inputs,
-  },
-
-  outputs: clusterOutputs,
-
-  meta: {
-    title: "Cluster DNS",
-    icon: "devicon:kubernetes",
-    secondaryIcon: "mdi:dns",
-    category: "Kubernetes",
-  },
-
-  source: {
-    package: "@highstate/k8s",
-    path: "units/cluster-dns",
-  },
-})
-
 export const monitorWorkerResourceGroupSchema = z.object({
   type: z.enum(["deployment", "statefulset", "pod", "service"]),
   namespace: z.string(),
@@ -332,7 +302,7 @@ export const monitorWorkerParamsSchema = z.object({
   /**
    * The resources to monitor in the cluster.
    */
-  resources: scopedResourceSchema.array(),
+  resources: namespacedResourceEntity.schema.array(),
 })
 
 export type Cluster = z.infer<typeof clusterEntity.schema>

package/src/k8s/workload.ts

@@ -1,7 +1,81 @@
 import { defineEntity, z } from "@highstate/contract"
-import { scopedResourceSchema } from "./resources"
+import { l4EndpointEntity } from "../network"
+import { namespacedResourceEntity } from "./resources"
 import { serviceEntity } from "./service"
 
+/**
+ * The entity which represents a Kubernetes workload.
+ */
+export const workloadEntity = defineEntity({
+  type: "k8s.workload.v1",
+
+  extends: { namespacedResourceEntity },
+  schema: z.unknown(),
+
+  meta: {
+    color: "#9C27B0",
+  },
+})
+
+/**
+ * The entity which represents a Kubernetes job managed by Highstate.
+ */
+export const jobEntity = defineEntity({
+  type: "k8s.job.v1",
+
+  extends: { workloadEntity },
+
+  schema: z.unknown(),
+
+  meta: {
+    color: "#FF5722",
+  },
+})
+
+/**
+ * The entity which represents a Kubernetes cron job managed by Highstate.
+ */
+export const cronJobEntity = defineEntity({
+  type: "k8s.cron-job.v1",
+
+  extends: { workloadEntity },
+
+  schema: z.unknown(),
+
+  meta: {
+    color: "#FF9800",
+  },
+})
+
+/**
+ * The entity which represents a Kubernetes workload (optionally) exposed via a service.
+ *
+ * Includes both the workload and its associated service.
+ */
+export const exposableWorkloadEntity = defineEntity({
+  type: "k8s.exposable-workload.v1",
+
+  extends: { workloadEntity },
+
+  includes: {
+    service: {
+      entity: serviceEntity,
+      required: false,
+    },
+
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
+
+  schema: z.unknown(),
+
+  meta: {
+    color: "#4CAF50",
+  },
+})
+
 /**
  * The entity which represents a Kubernetes deployment managed by Highstate.
  *
@@ -10,11 +84,8 @@ import { serviceEntity } from "./service"
 export const deploymentEntity = defineEntity({
   type: "k8s.deployment.v1",
 
-  schema: z.object({
-    ...scopedResourceSchema.shape,
-    type: z.literal("deployment"),
-    service: serviceEntity.schema.optional(),
-  }),
+  extends: { exposableWorkloadEntity },
+  schema: z.unknown(),
 
   meta: {
     color: "#4CAF50",
@@ -29,29 +100,16 @@ export const deploymentEntity = defineEntity({
 export const statefulSetEntity = defineEntity({
   type: "k8s.stateful-set.v1",
 
-  schema: z.object({
-    ...scopedResourceSchema.shape,
-    type: z.literal("stateful-set"),
-    service: serviceEntity.schema,
-  }),
+  extends: { exposableWorkloadEntity },
 
-  meta: {
-    color: "#FFC107",
+  includes: {
+    service: serviceEntity,
   },
-})
-
-/**
- * The entity which represents a Kubernetes workload exposed via a service.
- *
- * It can be either a deployment or a stateful set.
- */
-export const exposableWorkloadEntity = defineEntity({
-  type: "k8s.exposable-workload.v1",
 
-  schema: z.union([deploymentEntity.schema, statefulSetEntity.schema]),
+  schema: z.unknown(),
 
   meta: {
-    color: "#4CAF50",
+    color: "#FFC107",
   },
 })
 
@@ -63,7 +121,7 @@ export const networkInterfaceEntity = defineEntity({
 
   schema: z.object({
     name: z.string(),
-    workload: exposableWorkloadEntity.schema,
+    workload: workloadEntity.schema,
   }),
 
   meta: {
@@ -71,7 +129,10 @@ export const networkInterfaceEntity = defineEntity({
   },
 })
 
+export type Workload = z.infer<typeof workloadEntity.schema>
+export type Job = z.infer<typeof jobEntity.schema>
+export type CronJob = z.infer<typeof cronJobEntity.schema>
+export type ExposableWorkload = z.infer<typeof exposableWorkloadEntity.schema>
 export type Deployment = z.infer<typeof deploymentEntity.schema>
 export type StatefulSet = z.infer<typeof statefulSetEntity.schema>
-export type ExposableWorkload = z.infer<typeof exposableWorkloadEntity.schema>
 export type NetworkInterface = z.infer<typeof networkInterfaceEntity.schema>