@highstate/library 0.21.1 → 0.25.0

package/src/k8s/apps/workload.ts

@@ -2,9 +2,15 @@ import { defineUnit, z } from "@highstate/contract"
 import { pick } from "remeda"
 import { portSchema } from "../../network"
 import { namespaceEntity } from "../resources"
-import { serviceTypeSchema } from "../service"
 import { workloadEntity } from "../workload"
-import { optionalSharedInputs, sharedInputs, source } from "./shared"
+import {
+  optionalSharedInputs,
+  schedulingArg,
+  serviceArg,
+  sharedArgs,
+  sharedInputs,
+  source,
+} from "./shared"
 
 export const databaseConfigKeySchema = z.enum([
   "url",
@@ -60,6 +66,10 @@ export const workload = defineUnit({
      */
     existingNamespace: z.string().optional(),
 
+    ...pick(sharedArgs, ["external"]),
+    ...serviceArg,
+    ...schedulingArg,
+
     /**
      * The type of the workload to create.
      */
@@ -91,11 +101,6 @@ export const workload = defineUnit({
      */
     fqdn: z.string().optional(),
 
-    /**
-     * The type of the service to create for the workload.
-     */
-    serviceType: serviceTypeSchema.default("ClusterIP"),
-
     /**
      * The number of replicas for the workload.
      *
@@ -144,13 +149,6 @@ export const workload = defineUnit({
      */
     manifest: z.record(z.string(), z.unknown()).default({}),
 
-    /**
-     * The Kubernetes service manifest for the deployment.
-     *
-     * Will be applied to the service manifest before it is created.
-     */
-    serviceManifest: z.record(z.string(), z.unknown()).default({}),
-
     /**
      * The Kubernetes HTTP route manifest for the deployment.
      *

package/src/k8s/cert-manager.ts

@@ -1,7 +1,8 @@
 import { defineUnit, z } from "@highstate/contract"
+import * as vault from "../apps/vault"
 import { tlsIssuerEntity } from "../common"
 import * as dns from "../dns"
-import { clusterEntity } from "./shared"
+import { clusterEntity, helmExtensionArgs, schedulingArg } from "./shared"
 
 export const tlsIssuerDataSchema = z.object({
   /**
@@ -22,6 +23,9 @@ export const certManager = defineUnit({
   type: "k8s.cert-manager.v1",
 
   args: {
+    ...helmExtensionArgs,
+    ...schedulingArg,
+
     /**
      * Whether to enable the native support for Gateway API in cert-manager.
      *
@@ -89,7 +93,9 @@ export const dns01TlsIssuer = defineUnit({
 
   meta: {
     title: "DNS01 Issuer",
-    icon: "mdi:certificate",
+    icon: "iconoir:dns",
+    iconColor: "#2196F3",
+    secondaryIcon: "mdi:certificate",
     category: "Kubernetes",
   },
 
@@ -99,4 +105,40 @@ export const dns01TlsIssuer = defineUnit({
   },
 })
 
+/**
+ * The Vault TLS issuer for issuing certificates using a Vault PKI backend.
+ */
+export const vaultTlsIssuer = defineUnit({
+  type: "k8s.vault-issuer.v1",
+
+  inputs: {
+    /**
+     * The Kubernetes cluster where the Vault issuer should be configured.
+     */
+    k8sCluster: clusterEntity,
+
+    /**
+     * The Vault PKI issuer to use for issuing certificates.
+     */
+    vaultPkiIssuer: vault.pkiIssuerEntity,
+  },
+
+  outputs: {
+    tlsIssuer: tlsIssuerEntity,
+  },
+
+  meta: {
+    title: "Vault Issuer",
+    icon: "simple-icons:vault",
+    iconColor: "#2196F3",
+    secondaryIcon: "mdi:certificate",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/k8s",
+    path: "units/vault-issuer",
+  },
+})
+
 export type TlsIssuerData = z.infer<typeof tlsIssuerDataSchema>

package/src/k8s/cilium.ts

@@ -1,5 +1,5 @@
 import { defineUnit, z } from "@highstate/contract"
-import { clusterEntity, tolerationSchema } from "./shared"
+import { clusterEntity, helmExtensionArgs, schedulingArg } from "./shared"
 
 /**
  * The Cilium CNI deployed on Kubernetes.
@@ -25,21 +25,8 @@ export const cilium = defineUnit({
      * To expose the Hubble UI, you can use `k8s.apps.hubble-ui` unit.
      */
     enableHubble: z.boolean().default(true),
-
-    /**
-     * The tolerations of the cilium agent in the cluster.
-     */
-    agentTolerations: tolerationSchema.array().optional(),
-
-    /**
-     * The tolerations of the cilium envoy in the cluster.
-     */
-    envoyTolerations: tolerationSchema.array().optional(),
-
-    /**
-     * The tolerations of the cilium operator in the cluster.
-     */
-    operatorTolerations: tolerationSchema.array().optional(),
+    ...helmExtensionArgs,
+    ...schedulingArg,
   },
 
   inputs: {

package/src/k8s/coredns.ts

@@ -0,0 +1,62 @@
+import { defineUnit, z } from "@highstate/contract"
+import { clusterEntity, schedulingArg } from "./shared"
+
+/**
+ * The CoreDNS cluster DNS service installed on the Kubernetes cluster.
+ */
+export const coreDns = defineUnit({
+  type: "k8s.coredns.v1",
+
+  args: {
+    ...schedulingArg,
+
+    /**
+     * The mode to use for CoreDNS deployment.
+     *
+     * `cluster` creates a regular Deployment with a small replica count.
+     * It is the default Kubernetes model and fits clusters with reliable pod/service networking between nodes.
+     *
+     * `node` creates a DaemonSet and configures the DNS Service to route only to node-local endpoints.
+     * It fits edge, NATed, or partitioned clusters where each node should answer DNS locally and avoid cross-node DNS traffic.
+     */
+    mode: z.enum(["cluster", "node"]).default("cluster"),
+
+    /**
+     * The Kubernetes cluster DNS domain served by CoreDNS.
+     */
+    clusterDomain: z.string().default("cluster.local"),
+
+    /**
+     * The stable Service IP to reserve for cluster DNS.
+     *
+     * The default matches the common K3s service CIDR.
+     */
+    clusterIP: z.string().default("10.43.0.10"),
+
+    /**
+     * Whether CoreDNS should connect through the best external Kubernetes API endpoint.
+     *
+     * By default, CoreDNS uses the in-cluster Kubernetes service endpoint.
+     */
+    useExternalKubeApi: z.boolean().default(false),
+  },
+
+  inputs: {
+    k8sCluster: clusterEntity,
+  },
+
+  outputs: {
+    k8sCluster: clusterEntity,
+  },
+
+  meta: {
+    title: "CoreDNS",
+    icon: "selfhst:coredns-light",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/k8s",
+    path: "units/coredns",
+  },
+})

package/src/k8s/gateway.ts

@@ -1,7 +1,12 @@
 import { defineUnit, z } from "@highstate/contract"
+import { implementationReferenceSchema } from "../impl-ref"
 import { namespaceEntity } from "./resources"
 import { clusterEntity } from "./shared"
 
+const semverVersionSchema = z
+  .string()
+  .regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/)
+
 export const gatewayDataSchema = z.object({
   /**
    * The Kubernetes cluster to use for creating gateway routes.
@@ -31,6 +36,11 @@ export const gatewayDataSchema = z.object({
    * If not provided, defaults to 443.
    */
   httpsPort: z.number().default(443),
+
+  /**
+   * The nested implementation reference for the Gateway API controller.
+   */
+  controllerImplRef: implementationReferenceSchema.optional(),
 })
 
 export const gatewayImplRefSchema = z.object({
@@ -44,6 +54,21 @@ export const gatewayImplRefSchema = z.object({
 export const gatewayApi = defineUnit({
   type: "k8s.gateway-api.v1",
 
+  args: {
+    /**
+     * The Gateway API release channel to install.
+     */
+    channel: z.enum(["stable", "experimental"]).default("stable"),
+
+    /**
+     * The Gateway API version to install.
+     *
+     * Defaults to the latest stable version when using the stable channel.
+     * Must be specified when using the experimental channel.
+     */
+    version: semverVersionSchema.optional(),
+  },
+
   inputs: {
     k8sCluster: clusterEntity,
   },

package/src/k8s/index.ts

@@ -1,6 +1,7 @@
 export * as apps from "./apps"
 export * from "./cert-manager"
 export * from "./cilium"
+export * from "./coredns"
 export * as gameServers from "./game-servers"
 export * from "./gateway"
 export * as obfuscators from "./obfuscators"

package/src/k8s/scheduling.ts

@@ -0,0 +1,87 @@
+import { $args, z } from "@highstate/contract"
+
+export const labelSelectorRequirementSchema = z.object({
+  key: z.string(),
+  operator: z.enum(["DoesNotExist", "Exists", "In", "NotIn"]),
+  values: z.string().array().optional(),
+})
+
+export const labelSelectorSchema = z.object({
+  matchExpressions: labelSelectorRequirementSchema.array().optional(),
+  matchLabels: z.record(z.string(), z.string()).optional(),
+})
+
+export const nodeSelectorRequirementSchema = z.object({
+  key: z.string(),
+  operator: z.enum(["DoesNotExist", "Exists", "Gt", "In", "Lt", "NotIn"]),
+  values: z.string().array().optional(),
+})
+
+export const nodeSelectorTermSchema = z.object({
+  matchExpressions: nodeSelectorRequirementSchema.array().optional(),
+  matchFields: nodeSelectorRequirementSchema.array().optional(),
+})
+
+export const nodeAffinitySchema = z.object({
+  preferredDuringSchedulingIgnoredDuringExecution: z
+    .object({
+      preference: nodeSelectorTermSchema,
+      weight: z.number(),
+    })
+    .array()
+    .optional(),
+  requiredDuringSchedulingIgnoredDuringExecution: z
+    .object({
+      nodeSelectorTerms: nodeSelectorTermSchema.array(),
+    })
+    .optional(),
+})
+
+export const podAffinityTermSchema = z.object({
+  labelSelector: labelSelectorSchema.optional(),
+  matchLabelKeys: z.string().array().optional(),
+  mismatchLabelKeys: z.string().array().optional(),
+  namespaceSelector: labelSelectorSchema.optional(),
+  namespaces: z.string().array().optional(),
+  topologyKey: z.string(),
+})
+
+export const podAffinitySchema = z.object({
+  preferredDuringSchedulingIgnoredDuringExecution: z
+    .object({
+      podAffinityTerm: podAffinityTermSchema,
+      weight: z.number(),
+    })
+    .array()
+    .optional(),
+  requiredDuringSchedulingIgnoredDuringExecution: podAffinityTermSchema.array().optional(),
+})
+
+export const affinitySchema = z.object({
+  nodeAffinity: nodeAffinitySchema.optional(),
+  podAffinity: podAffinitySchema.optional(),
+  podAntiAffinity: podAffinitySchema.optional(),
+})
+
+export const tolerationSchema = z.object({
+  effect: z.enum(["NoExecute", "NoSchedule", "PreferNoSchedule"]).optional(),
+  key: z.string().optional(),
+  operator: z.enum(["Equal", "Exists"]).optional(),
+  tolerationSeconds: z.number().optional(),
+  value: z.string().optional(),
+})
+
+export const schedulingSchema = z.object({
+  affinity: affinitySchema.optional(),
+  nodeSelector: z.record(z.string(), z.string()).optional(),
+  tolerations: tolerationSchema.array().optional(),
+})
+
+export const schedulingArg = $args({
+  /**
+   * The Kubernetes scheduling options to apply to every pod created by the unit.
+   */
+  scheduling: schedulingSchema.default({}).meta({ complex: true }),
+})
+
+export type Scheduling = z.infer<typeof schedulingSchema>

package/src/k8s/service-args.ts

@@ -0,0 +1,109 @@
+import { $args, z } from "@highstate/contract"
+
+export const managedFieldsEntrySchema = z.object({
+  apiVersion: z.string().optional(),
+  fieldsType: z.string().optional(),
+  fieldsV1: z.unknown().optional(),
+  manager: z.string().optional(),
+  operation: z.string().optional(),
+  subresource: z.string().optional(),
+  time: z.string().optional(),
+})
+
+export const ownerReferenceSchema = z.object({
+  apiVersion: z.string(),
+  blockOwnerDeletion: z.boolean().optional(),
+  controller: z.boolean().optional(),
+  kind: z.string(),
+  name: z.string(),
+  uid: z.string(),
+})
+
+export const objectMetaSchema = z.object({
+  annotations: z.record(z.string(), z.string()).optional(),
+  creationTimestamp: z.string().optional(),
+  deletionGracePeriodSeconds: z.number().optional(),
+  deletionTimestamp: z.string().optional(),
+  finalizers: z.string().array().optional(),
+  generateName: z.string().optional(),
+  generation: z.number().optional(),
+  labels: z.record(z.string(), z.string()).optional(),
+  managedFields: managedFieldsEntrySchema.array().optional(),
+  name: z.string().optional(),
+  namespace: z.string().optional(),
+  ownerReferences: ownerReferenceSchema.array().optional(),
+  resourceVersion: z.string().optional(),
+  selfLink: z.string().optional(),
+  uid: z.string().optional(),
+})
+
+export const servicePortSchema = z.object({
+  appProtocol: z.string().optional(),
+  name: z.string().optional(),
+  nodePort: z.number().optional(),
+  port: z.number(),
+  protocol: z.enum(["SCTP", "TCP", "UDP"]).optional(),
+  targetPort: z.union([z.number(), z.string()]).optional(),
+})
+
+export const sessionAffinityConfigSchema = z.object({
+  clientIP: z
+    .object({
+      timeoutSeconds: z.number().optional(),
+    })
+    .optional(),
+})
+
+export const serviceArgsSchema = z.object({
+  /**
+   * The name of the service.
+   */
+  name: z.string().optional(),
+
+  /**
+   * The metadata to apply to the service.
+   */
+  metadata: objectMetaSchema.optional(),
+
+  /**
+   * The port to expose the service on.
+   */
+  port: servicePortSchema.optional(),
+
+  /**
+   * Whether the service should be exposed by NodePort or LoadBalancer.
+   */
+  external: z.boolean().optional(),
+
+  allocateLoadBalancerNodePorts: z.boolean().optional(),
+  clusterIP: z.string().optional(),
+  clusterIPs: z.string().array().optional(),
+  externalIPs: z.string().array().optional(),
+  externalName: z.string().optional(),
+  externalTrafficPolicy: z.enum(["Cluster", "Local"]).optional(),
+  healthCheckNodePort: z.number().optional(),
+  internalTrafficPolicy: z.enum(["Cluster", "Local"]).optional(),
+  ipFamilies: z.enum(["IPv4", "IPv6"]).array().optional(),
+  ipFamilyPolicy: z.enum(["PreferDualStack", "RequireDualStack", "SingleStack"]).optional(),
+  loadBalancerClass: z.string().optional(),
+  loadBalancerIP: z.string().optional(),
+  loadBalancerSourceRanges: z.string().array().optional(),
+  ports: servicePortSchema.array().optional(),
+  publishNotReadyAddresses: z.boolean().optional(),
+  selector: z.record(z.string(), z.string()).optional(),
+  sessionAffinity: z.enum(["ClientIP", "None"]).optional(),
+  sessionAffinityConfig: sessionAffinityConfigSchema.optional(),
+  trafficDistribution: z.string().optional(),
+  type: z.enum(["ClusterIP", "ExternalName", "LoadBalancer", "NodePort"]).optional(),
+})
+
+export const serviceArg = $args({
+  /**
+   * The extra arguments to apply to the component service.
+   *
+   * Accepts Kubernetes Service spec fields and Highstate service helper arguments.
+   */
+  service: serviceArgsSchema.default({}).meta({ complex: true }),
+})
+
+export type ServiceArgs = z.infer<typeof serviceArgsSchema>

package/src/k8s/shared.ts

@@ -12,6 +12,9 @@ import { addressEntity, l3EndpointEntity, l4EndpointEntity } from "../network"
 import { metadataSchema } from "../utils"
 import { namespacedResourceEntity } from "./resources"
 
+export { type Scheduling, schedulingArg, schedulingSchema } from "./scheduling"
+export { type ServiceArgs, serviceArg, serviceArgsSchema } from "./service-args"
+
 export const fallbackKubeApiAccessSchema = z.object({
   serverIp: z.string(),
   serverPort: z.number(),
@@ -31,6 +34,29 @@ export const tunDevicePolicySchema = z.discriminatedUnion("type", [
 export const externalServiceTypeSchema = z.enum(["NodePort", "LoadBalancer"])
 export const scheduleOnMastersPolicySchema = z.enum(["always", "when-no-workers", "never"])
 
+export const jsonPatchOperationSchema = z.discriminatedUnion("op", [
+  z.object({ op: z.literal("add"), path: z.string(), value: z.unknown() }),
+  z.object({ op: z.literal("remove"), path: z.string() }),
+  z.object({ op: z.literal("replace"), path: z.string(), value: z.unknown() }),
+  z.object({ op: z.literal("move"), path: z.string(), from: z.string() }),
+  z.object({ op: z.literal("copy"), path: z.string(), from: z.string() }),
+  z.object({ op: z.literal("test"), path: z.string(), value: z.unknown() }),
+])
+
+export const helmExtensionArgs = $args({
+  /**
+   * The values to deep merge over the component-provided Helm values.
+   */
+  values: z.record(z.string(), z.unknown()).default({}).meta({ complex: true }),
+
+  /**
+   * The JSON Patch operations to apply to the merged Helm values in order.
+   */
+  patches: jsonPatchOperationSchema.array().default([]).meta({ complex: true }),
+})
+
+export type JsonPatchOperation = z.infer<typeof jsonPatchOperationSchema>
+
 export const clusterQuirksSchema = z.object({
   /**
    * The IP and port of the kube-apiserver available from the cluster.

package/src/k8s/workload.ts

@@ -101,6 +101,25 @@ export const deploymentEntity = defineEntity({
   },
 })
 
+/**
+ * The entity which represents a Kubernetes daemon set managed by Highstate.
+ *
+ * Also includes a service associated with the daemon set.
+ */
+export const daemonSetEntity = defineEntity({
+  type: "k8s.daemon-set.v1",
+
+  extends: { workloadEntity },
+  schema: z.unknown(),
+
+  meta: {
+    color: "#2196F3",
+    title: "Daemon Set",
+    icon: "devicon:kubernetes",
+    iconColor: "#2196F3",
+  },
+})
+
 /**
  * The entity which represents a Kubernetes stateful set managed by Highstate.
  *
@@ -155,6 +174,8 @@ export type CronJob = EntityValue<typeof cronJobEntity>
 export type CronJobInput = EntityInput<typeof cronJobEntity>
 export type Deployment = EntityValue<typeof deploymentEntity>
 export type DeploymentInput = EntityInput<typeof deploymentEntity>
+export type DaemonSet = EntityValue<typeof daemonSetEntity>
+export type DaemonSetInput = EntityInput<typeof daemonSetEntity>
 export type StatefulSet = EntityValue<typeof statefulSetEntity>
 export type StatefulSetInput = EntityInput<typeof statefulSetEntity>
 export type NetworkInterface = EntityValue<typeof networkInterfaceEntity>