@highstate/library 0.20.0 → 0.25.0

package/src/k3s.ts

@@ -1,5 +1,7 @@
-import { defineUnit, z } from "@highstate/contract"
+import { defineEntity, defineUnit, type EntityValue, secretSchema, z } from "@highstate/contract"
+import { serverEntity } from "./common"
 import { clusterInputs, clusterOutputs } from "./k8s/shared"
+import { l4EndpointEntity } from "./network"
 
 export const packagedComponents = [
   "coredns",
@@ -22,6 +24,48 @@ export const componentSchema = z.enum([...packagedComponents, ...internalCompone
 
 export const cniSchema = z.enum(["none", "flannel"])
 
+export const clusterEntity = defineEntity({
+  type: "k3s.cluster.v1",
+
+  includes: {
+    /**
+     * The API endpoint workers should use to join the cluster.
+     *
+     * This is the public endpoint when the cluster has one, otherwise the first master endpoint.
+     */
+    bootstrapEndpoint: l4EndpointEntity,
+  },
+
+  schema: z.object({
+    /**
+     * The cluster name.
+     */
+    name: z.string(),
+
+    /**
+     * The agent token workers should use to join the cluster.
+     */
+    agentToken: secretSchema(z.string()),
+
+    /**
+     * The shared K3s agent configuration for workers joining the cluster.
+     */
+    agentConfig: z.record(z.string(), z.unknown()),
+
+    /**
+     * The registry configuration workers should use when joining the cluster.
+     */
+    registries: z.record(z.string(), z.unknown()),
+  }),
+
+  meta: {
+    color: "#326CE5",
+    title: "K3s Cluster",
+    icon: "devicon:k3s",
+    iconColor: "#326CE5",
+  },
+})
+
 /**
  * The K3s cluster created on top of the server.
  */
@@ -78,8 +122,28 @@ export const cluster = defineUnit({
     registries: z.record(z.string(), z.unknown()).optional(),
   },
 
-  inputs: clusterInputs,
-  outputs: clusterOutputs,
+  inputs: {
+    ...clusterInputs,
+
+    /**
+     * The public API endpoint to expose for cluster access.
+     *
+     * If specified, it will be used for the kubeconfig, Kubernetes provider, cluster entity, and TLS SANs.
+     * Node bootstrap still uses the first master endpoint.
+     */
+    publicEndpoint: {
+      entity: l4EndpointEntity,
+      required: false,
+    },
+  },
+  outputs: {
+    ...clusterOutputs,
+
+    /**
+     * The K3s cluster join information for provisioning additional workers.
+     */
+    cluster: clusterEntity,
+  },
 
   meta: {
     title: "K3s Cluster",
@@ -93,3 +157,65 @@ export const cluster = defineUnit({
     path: "cluster",
   },
 })
+
+/**
+ * The group of K3s worker nodes joined to an existing K3s cluster.
+ */
+export const workerGroup = defineUnit({
+  type: "k3s.worker-group.v1",
+
+  args: {
+    /**
+     * The K3s configuration to pass to each worker in the group.
+     *
+     * See: https://docs.k3s.io/installation/configuration
+     */
+    config: z.record(z.string(), z.unknown()).optional(),
+
+    /**
+     * The map of configuration per each worker in the group, where the key is the hostname of the node.
+     *
+     * Note: if multiple nodes have the same hostname, the configuration will be applied to all of them.
+     */
+    nodeConfig: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+  },
+
+  inputs: {
+    /**
+     * The K3s cluster join information.
+     */
+    cluster: clusterEntity,
+
+    /**
+     * The worker servers in the group to join to the cluster.
+     */
+    workers: {
+      entity: serverEntity,
+      multiple: true,
+    },
+  },
+
+  outputs: {
+    /**
+     * The worker servers in the group joined to the cluster.
+     */
+    workers: {
+      entity: serverEntity,
+      multiple: true,
+    },
+  },
+
+  meta: {
+    title: "K3s Worker Group",
+    category: "k3s",
+    icon: "devicon:k3s",
+    secondaryIcon: "mdi:server",
+  },
+
+  source: {
+    package: "@highstate/k3s",
+    path: "worker-group",
+  },
+})
+
+export type Cluster = EntityValue<typeof clusterEntity>

package/src/k8s/apps/envoy-gateway.ts

@@ -0,0 +1,50 @@
+import { defineUnit, z } from "@highstate/contract"
+import { pick } from "remeda"
+import { gatewayEntity } from "../../common"
+import { appName, sharedArgs, sharedInputs, source } from "./shared"
+
+/**
+ * The Envoy Gateway controller and gateway implementation.
+ */
+export const envoyGateway = defineUnit({
+  type: "k8s.apps.envoy-gateway.v1",
+
+  args: {
+    ...appName("envoy-gateway"),
+    ...pick(sharedArgs, ["external", "replicas", "values", "patches", "service", "scheduling"]),
+
+    /**
+     * The name of the GatewayClass to configure for Gateway API resources.
+     *
+     * Defaults to "envoy-gateway".
+     */
+    className: z.string().default("envoy-gateway"),
+
+    /**
+     * The Gateway API controller name for Envoy Gateway.
+     */
+    controllerName: z.string().default("gateway.envoyproxy.io/gatewayclass-controller"),
+
+    /**
+     * Whether to install CRDs bundled with the Envoy Gateway Helm chart.
+     */
+    installCrds: z.boolean().default(true),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster"]),
+  },
+
+  outputs: {
+    gateway: gatewayEntity,
+  },
+
+  meta: {
+    title: "Envoy Gateway",
+    icon: "simple-icons:envoyproxy",
+    iconColor: "#AC6199",
+    category: "Network",
+  },
+
+  source: source("envoy-gateway"),
+})

package/src/k8s/apps/etcd.ts

@@ -18,7 +18,7 @@ export const etcd = defineUnit({
 
   args: {
     ...appName("etcd"),
-    ...pick(sharedArgs, ["external"]),
+    ...pick(sharedArgs, ["external", "values", "patches", "service", "scheduling"]),
   },
 
   secrets: {

package/src/k8s/apps/grafana.ts

@@ -11,7 +11,7 @@ export const grafana = defineUnit({
 
   args: {
     ...appName("grafana"),
-    ...pick(sharedArgs, ["fqdn"]),
+    ...pick(sharedArgs, ["fqdn", "values", "patches", "service", "scheduling"]),
 
     /**
      * The list of plugins to install on Grafana.

package/src/k8s/apps/index.ts

@@ -1,4 +1,5 @@
 export * from "./code-server"
+export * from "./envoy-gateway"
 export * from "./etcd"
 export * from "./grafana"
 export * from "./grocy"
@@ -11,6 +12,7 @@ export * from "./portal"
 export * from "./postgresql"
 export * from "./refluxdb"
 export * from "./remnawave"
+export * from "./rustfs"
 export {
   appName,
   optionalSharedArgs,
@@ -19,11 +21,13 @@ export {
   sharedInputs,
   sharedSecrets,
 } from "./shared"
+export * from "./signoz"
 export * from "./syncthing"
 // export * from "./zitadel"
 // export * from "./gitea"
 export * from "./traefik"
 export * from "./valkey"
+export * from "./vault"
 export * from "./vaultwarden"
 export * from "./wg-feed-server"
 export * from "./workload"

package/src/k8s/apps/mariadb.ts

@@ -19,7 +19,7 @@ export const mariadb = defineUnit({
 
   args: {
     ...appName("mariadb"),
-    ...pick(sharedArgs, ["external"]),
+    ...pick(sharedArgs, ["external", "values", "patches", "service", "scheduling"]),
   },
 
   secrets: {

package/src/k8s/apps/matrix-stack.ts

@@ -1,7 +1,7 @@
 import { defineUnit, z } from "@highstate/contract"
 import { pick } from "remeda"
 import { postgresql } from "../../databases"
-import { appName, sharedInputs, source } from "./shared"
+import { appName, sharedArgs, sharedInputs, source } from "./shared"
 
 /**
  * The Matrix stack deployed on Kubernetes.
@@ -11,6 +11,7 @@ export const matrixStack = defineUnit({
 
   args: {
     ...appName("matrix-stack"),
+    ...pick(sharedArgs, ["values", "patches", "service"]),
 
     /**
      * The base domain for the Matrix stack services.

package/src/k8s/apps/minio.ts

@@ -20,8 +20,8 @@ export const minio = defineUnit({
 
   args: {
     ...appName("minio"),
-    ...pick(optionalSharedArgs, ["fqdn"]),
-    ...pick(sharedArgs, ["external"]),
+    ...pick(optionalSharedArgs, ["fqdn", "namespace"]),
+    ...pick(sharedArgs, ["external", "values", "patches", "service", "scheduling"]),
 
     /**
      * The FQDN of the MinIO console.

package/src/k8s/apps/mongodb.ts

@@ -19,7 +19,7 @@ export const mongodb = defineUnit({
 
   args: {
     ...appName("mongodb"),
-    ...pick(sharedArgs, ["external"]),
+    ...pick(sharedArgs, ["external", "values", "patches", "service", "scheduling"]),
   },
 
   secrets: {

package/src/k8s/apps/postgresql.ts

@@ -19,7 +19,7 @@ export const postgresql = defineUnit({
 
   args: {
     ...appName("postgresql"),
-    ...pick(sharedArgs, ["namespace", "external"]),
+    ...pick(sharedArgs, ["namespace", "external", "values", "patches", "service", "scheduling"]),
   },
 
   secrets: {

package/src/k8s/apps/rustfs.ts

@@ -0,0 +1,119 @@
+import { defineUnit, z } from "@highstate/contract"
+import { pick } from "remeda"
+import { connectionEntity } from "../../databases/rustfs"
+import { workloadEntity } from "../workload"
+import {
+  appName,
+  optionalSharedArgs,
+  optionalSharedInputs,
+  sharedArgs,
+  sharedInputs,
+  sharedSecrets,
+  source,
+} from "./shared"
+
+/**
+ * The RustFS S3-compatible object storage deployed on Kubernetes.
+ */
+export const rustfs = defineUnit({
+  type: "k8s.apps.rustfs.v1",
+
+  args: {
+    ...appName("rustfs"),
+    ...pick(optionalSharedArgs, ["fqdn", "namespace"]),
+    ...pick(sharedArgs, ["external", "values", "patches", "service", "scheduling"]),
+
+    /**
+     * The deployment topology to use.
+     *
+     * Standalone mode deploys one pod with one data volume.
+     * Distributed mode deploys an erasure-coded StatefulSet across multiple pods and volumes.
+     */
+    mode: z.enum(["standalone", "distributed"]).default("distributed"),
+
+    /**
+     * The FQDN of the RustFS console.
+     *
+     * If not provided, the console will only be available inside the cluster.
+     */
+    consoleFqdn: z.string().optional(),
+
+    /**
+     * The number of nodes in a distributed deployment.
+     *
+     * Ignored in standalone mode.
+     */
+    replicas: z.number().int().min(2).default(4),
+
+    /**
+     * The number of data volumes attached to each distributed node.
+     *
+     * Ignored in standalone mode.
+     */
+    drivesPerNode: z.number().int().min(1).default(4),
+
+    /**
+     * Whether to bypass RustFS validation that each data volume uses a distinct physical disk.
+     *
+     * This sets `RUSTFS_UNSAFE_BYPASS_DISK_CHECK=true` and must only be used for local testing or CI.
+     * Enabling it in production can cause correlated data loss because multiple erasure-coded drives
+     * may actually share one physical device.
+     */
+    unsafeBypassDiskCheck: z.boolean().default(false),
+
+    /**
+     * Whether distributed RustFS pods may share Kubernetes nodes.
+     *
+     * By default, RustFS requires each replica to run on a different node for failure isolation.
+     * Enable this when the Kubernetes cluster has fewer eligible nodes than RustFS replicas.
+     * Pods will still prefer separate nodes, but the scheduler may place multiple replicas on one node.
+     * This reduces fault tolerance because one node failure can make multiple RustFS replicas unavailable.
+     *
+     * Ignored in standalone mode.
+     */
+    allowLessNodes: z.boolean().default(false),
+
+    /**
+     * The Kubernetes StorageClass used for RustFS volumes.
+     */
+    storageClass: z.string().default("local-path"),
+
+    /**
+     * The requested capacity of each data volume.
+     */
+    dataStorageSize: z.string().default("100Gi"),
+
+    /**
+     * The requested capacity of each log volume.
+     */
+    logStorageSize: z.string().default("1Gi"),
+
+    /**
+     * The S3 region reported by RustFS.
+     */
+    region: z.string().default("us-east-1"),
+  },
+
+  secrets: {
+    ...pick(sharedSecrets, ["adminPassword", "backupKey"]),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster"]),
+    ...pick(optionalSharedInputs, ["accessPoint", "resticRepo"]),
+  },
+
+  outputs: {
+    connection: connectionEntity,
+    workload: workloadEntity,
+  },
+
+  meta: {
+    title: "RustFS",
+    icon: "simple-icons:rust",
+    secondaryIcon: "mdi:bucket",
+    category: "Databases",
+  },
+
+  source: source("rustfs"),
+})

package/src/k8s/apps/shared.ts

@@ -16,7 +16,18 @@ import { etcd, mongodb, mysql, postgresql, redis } from "../../databases"
 import { providerEntity } from "../../dns"
 import { repositoryEntity } from "../../restic"
 import { namespaceEntity, persistentVolumeClaimEntity } from "../resources"
-import { clusterEntity } from "../shared"
+import { clusterEntity, helmExtensionArgs, schedulingArg, serviceArg } from "../shared"
+
+export {
+  helmExtensionArgs,
+  type JsonPatchOperation,
+  jsonPatchOperationSchema,
+  type Scheduling,
+  type ServiceArgs,
+  schedulingArg,
+  schedulingSchema,
+  serviceArg,
+} from "../shared"
 
 export const sharedArgs = $args({
   /**
@@ -47,6 +58,10 @@ export const sharedArgs = $args({
    * If not provided, defaults to the appName.
    */
   namespace: z.string().optional(),
+
+  ...helmExtensionArgs,
+  ...serviceArg,
+  ...schedulingArg,
 })
 
 type ToOptionalArgs<T extends Record<string, FullComponentArgumentOptions>> = Simplify<{

package/src/k8s/apps/signoz.ts

@@ -0,0 +1,32 @@
+import { defineUnit } from "@highstate/contract"
+import { pick } from "remeda"
+import { serviceEntity } from "../service"
+import { appName, sharedArgs, sharedInputs, source } from "./shared"
+
+/**
+ * SigNoz deployed on Kubernetes.
+ */
+export const signoz = defineUnit({
+  type: "k8s.apps.signoz.v1",
+
+  args: {
+    ...appName("signoz"),
+    ...pick(sharedArgs, ["fqdn", "namespace", "values", "patches", "service", "scheduling"]),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster", "accessPoint", "postgresql"]),
+  },
+
+  outputs: {
+    service: serviceEntity,
+  },
+
+  meta: {
+    title: "SigNoz",
+    icon: "selfhst:signoz",
+    category: "Observability",
+  },
+
+  source: source("signoz"),
+})

package/src/k8s/apps/traefik.ts

@@ -13,7 +13,7 @@ export const traefik = defineUnit({
 
   args: {
     ...appName("traefik"),
-    ...pick(sharedArgs, ["external", "replicas"]),
+    ...pick(sharedArgs, ["external", "replicas", "values", "patches", "service", "scheduling"]),
 
     /**
      * The name of the class to configure for ingress and gateway resources.
@@ -23,14 +23,14 @@ export const traefik = defineUnit({
     className: z.string().default("traefik"),
 
     /**
-     * The node selector to apply to all Traefik pods.
+     * Whether to create and enable reconciliation for Traefik CRDs.
      */
-    nodeSelector: z.record(z.string(), z.string()).default({}),
+    enableTraefikCrds: z.boolean().default(true),
 
     /**
-     * Whether to create and enable reconciliation for Traefik CRDs.
+     * Whether to install CRDs bundled with the Traefik Helm chart.
      */
-    enableTraefikCrds: z.boolean().default(true),
+    installCrds: z.boolean().default(true),
 
     /**
      * Whether to enable reconciliation for Ingress resources and create ingress class.

package/src/k8s/apps/valkey.ts

@@ -19,7 +19,7 @@ export const valkey = defineUnit({
 
   args: {
     ...appName("valkey"),
-    ...pick(sharedArgs, ["external"]),
+    ...pick(sharedArgs, ["external", "values", "patches", "service", "scheduling"]),
   },
 
   secrets: {

package/src/k8s/apps/vault.ts

@@ -0,0 +1,113 @@
+import { defineUnit, z } from "@highstate/contract"
+import { pick } from "remeda"
+import { connectionEntity } from "../../apps/vault"
+import { s3 } from "../../databases"
+import { statefulSetEntity } from "../workload"
+import {
+  appName,
+  optionalSharedInputs,
+  sharedArgs,
+  sharedInputs,
+  sharedSecrets,
+  source,
+} from "./shared"
+
+/**
+ * The HashiCorp Vault deployed on Kubernetes using the official Helm chart.
+ */
+export const vault = defineUnit({
+  type: "k8s.apps.vault.v1",
+
+  args: {
+    ...appName("vault"),
+    ...pick(sharedArgs, [
+      "fqdn",
+      "external",
+      "namespace",
+      "values",
+      "patches",
+      "service",
+      "scheduling",
+    ]),
+
+    /**
+     * The storage backend to use for Vault.
+     *
+     * The options are:
+     * - `file`: uses a persistent volume claim and supports restic backups (default);
+     * - `s3`: uses an external S3-compatible bucket; expects `s3Bucket` input.
+     */
+    backend: z.enum(["file", "s3"]).default("file"),
+
+    /**
+     * The automatic Vault initialization configuration.
+     */
+    autoInit: z
+      .object({
+        /**
+         * Whether to initialize Vault automatically using the Vault CLI.
+         */
+        enabled: z.boolean().default(true),
+
+        /**
+         * The number of unseal key shares to create.
+         */
+        shares: z.number().int().positive().default(1),
+
+        /**
+         * The number of unseal key shares required to unseal Vault.
+         */
+        threshold: z.number().int().positive().default(1),
+      })
+      .refine(autoInit => autoInit.threshold <= autoInit.shares, {
+        message: "threshold must be less than or equal to shares",
+        path: ["threshold"],
+      })
+      .default({
+        enabled: true,
+        shares: 1,
+        threshold: 1,
+      }),
+  },
+
+  secrets: {
+    ...pick(sharedSecrets, ["backupKey"]),
+
+    /**
+     * The root token returned by `vault operator init`.
+     */
+    rootToken: z.string().optional(),
+
+    /**
+     * The unseal key shares returned by `vault operator init`.
+     */
+    unsealKeys: z.string().array().meta({ complex: true }).optional(),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster", "accessPoint"]),
+
+    /**
+     * When `backend` is `s3`, supply an existing S3 bucket connection (see `s3.bucketEntity`).
+     */
+    s3Bucket: {
+      entity: s3.bucketEntity,
+      required: false, // only required if backend is s3, will validate presence later
+    },
+
+    ...pick(optionalSharedInputs, ["resticRepo", "volume"]),
+  },
+
+  outputs: {
+    connection: connectionEntity,
+    statefulSet: statefulSetEntity,
+  },
+
+  meta: {
+    title: "Vault",
+    icon: "simple-icons:vault",
+    category: "Security",
+  },
+
+  source: source("vault"),
+})

package/src/k8s/apps/vaultwarden.ts

@@ -1,6 +1,13 @@
-import { defineUnit } from "@highstate/contract"
+import { defineUnit, z } from "@highstate/contract"
 import { pick } from "remeda"
-import { appName, sharedArgs, sharedInputs, source } from "./shared"
+import {
+  appName,
+  optionalSharedInputs,
+  sharedArgs,
+  sharedInputs,
+  sharedSecrets,
+  source,
+} from "./shared"
 
 /**
  * The Vaultwarden password manager deployed on Kubernetes.
@@ -11,10 +18,32 @@ export const vaultwarden = defineUnit({
   args: {
     ...appName("vaultwarden"),
     ...pick(sharedArgs, ["fqdn"]),
+
+    /**
+     * Whether signup is allowed for the Vaultwarden instance. Defaults to `false` for security reasons.
+     */
+    allowSignup: z.boolean().default(false),
+
+    /**
+     * Whether admin panel is enabled. Defaults to `true`.
+     */
+    enableAdminPanel: z.boolean().default(true),
+  },
+
+  secrets: {
+    /**
+     * The admin token for the Vaulwarden instance.
+     *
+     * Will be automatically generated if `enableAdminPanel` is `true`.
+     */
+    adminToken: z.string().optional(),
+
+    ...pick(sharedSecrets, ["backupKey"]),
   },
 
   inputs: {
     ...pick(sharedInputs, ["k8sCluster", "accessPoint", "mysql"]),
+    ...pick(optionalSharedInputs, ["resticRepo"]),
   },
 
   meta: {