@highstate/library 0.9.16 → 0.9.19

package/src/k8s/apps/workload.ts

@@ -0,0 +1,214 @@
+import { defineUnit, z } from "@highstate/contract"
+import { pick } from "remeda"
+import { portSchema } from "../../network"
+import { serviceEntity, serviceTypeSchema } from "../service"
+import { deploymentEntity } from "../workload"
+import { optionalSharedInputs, sharedInputs, source } from "./shared"
+
+export const databaseConfigKeySchema = z.enum([
+  "url",
+  "host",
+  "port",
+  "username",
+  "password",
+  "database",
+])
+
+export const environmentVariableSchema = z.union([
+  z.string(),
+  z.object({
+    dependencyKey: z.templateLiteral([
+      z.enum(["mariadb", "postgresql", "mongodb"]),
+      z.literal("."),
+      databaseConfigKeySchema,
+    ]),
+  }),
+  z.object({
+    configKey: z.string(),
+  }),
+  z.object({
+    secretKey: z.string(),
+  }),
+])
+
+/**
+ * The generic Kubernetes workload with optional service and gateway routes.
+ *
+ * May reference known databases and other services.
+ */
+export const workload = defineUnit({
+  type: "k8s.apps.workload.v1",
+
+  args: {
+    /**
+     * The name of the application.
+     *
+     * If not provided, the name of the unit will be used.
+     */
+    appName: z.string().optional(),
+
+    /**
+     * The name of the new namespace to create for the workload.
+     *
+     * If not provided, the `appName` will be used as the namespace name.
+     */
+    namespace: z.string().optional(),
+
+    /**
+     * The name of the existing namespace to use for the workload.
+     */
+    existingNamespace: z.string().optional(),
+
+    /**
+     * The type of the workload to create.
+     */
+    type: z
+      .enum(["Deployment", "StatefulSet", "DaemonSet", "Job", "CronJob"])
+      .default("Deployment"),
+
+    /**
+     * The image to use for the workload.
+     */
+    image: z.string(),
+
+    /**
+     * The port to expose for the workload.
+     *
+     * If specified, a service will be created for the workload.
+     */
+    port: portSchema.optional(),
+
+    /**
+     * The FQDN of the workload.
+     *
+     * If specified, a service and an HTTP route will be created for the workload.
+     */
+    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.
+     *
+     * By default, it is set to 1.
+     */
+    replicas: z.number().default(1),
+
+    /**
+     * The path where the workload data will be stored.
+     *
+     * If specified, a persistent volume claim will be created for the workload.
+     *
+     * If `resticRepo` input is provided, the automatic backup will be enabled for this path.
+     */
+    dataPath: z.string().optional(),
+
+    /**
+     * The environment variables to set for the workload.
+     *
+     * The values can be:
+     * 1. a static string value;
+     * 2. a dependency key to service configuration (e.g., `mariadb.username`);
+     * 3. a config key to reference a configuration value provided via `config` argument;
+     * 4. a secret key to reference a secret value provided via `secretData` secret.
+     */
+    env: z.record(z.string(), environmentVariableSchema).default({}),
+
+    /**
+     * The configuration for the workload.
+     *
+     * If provided, the config map will be created.
+     *
+     * You can reference the configuration values in the environment variables using `configKey`.
+     */
+    config: z.record(z.string(), z.unknown()).default({}),
+
+    /**
+     * The Kubernetes manifest patch for the deployment.
+     *
+     * Will be applied to the deployment manifest before it is created.
+     */
+    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.
+     *
+     * Will be applied to the HTTP route manifest before it is created.
+     */
+    httpRouteManifest: z.record(z.string(), z.unknown()).default({}),
+  },
+
+  secrets: {
+    /**
+     * The password for the MariaDB database.
+     *
+     * If not provided and requested, a random password will be generated.
+     */
+    mariadbPassword: z.string().optional(),
+
+    /**
+     * The password for the PostgreSQL database.
+     *
+     * If not provided and requested, a random password will be generated.
+     */
+    postgresqlPassword: z.string().optional(),
+
+    /**
+     * The password for the MongoDB database.
+     *
+     * If not provided and requested, a random password will be generated.
+     */
+    mongodbPassword: z.string().optional(),
+
+    /**
+     * The password for the backup.
+     *
+     * If not provided and requested, a random password will be generated.
+     */
+    backupPassword: z.string().optional(),
+
+    /**
+     * The secret configuration for the workload.
+     *
+     * If provided, the secret will be created with the specified content.
+     *
+     * You can reference the secret values in the environment variables using `secretKey`.
+     */
+    secretData: z.record(z.string(), z.string()).default({}),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster"]),
+    ...pick(optionalSharedInputs, [
+      "accessPoint",
+      "resticRepo",
+      "mariadb",
+      "postgresql",
+      "mongodb",
+    ]),
+  },
+
+  outputs: {
+    deployment: deploymentEntity,
+    service: serviceEntity,
+  },
+
+  meta: {
+    title: "Kubernetes Workload",
+    icon: "devicon:kubernetes",
+    secondaryIcon: "mdi:cube-outline",
+    category: "Kubernetes",
+  },
+
+  source: source("deployment"),
+})

package/src/k8s/apps/zitadel.ts

@@ -0,0 +1,26 @@
+import { defineUnit } from "@highstate/contract"
+import { pick } from "remeda"
+import { appName, sharedArgs, sharedInputs, source } from "./shared"
+
+/**
+ * The Zitadel IAM deployed on Kubernetes.
+ */
+export const zitadel = defineUnit({
+  type: "k8s.apps.zitadel.v1",
+
+  args: {
+    ...appName("zitadel"),
+    ...pick(sharedArgs, ["fqdn"]),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster", "accessPoint", "postgresql"]),
+  },
+
+  meta: {
+    title: "Zitadel",
+    icon: "hugeicons:access",
+  },
+
+  source: source("zitadel"),
+})

package/src/k8s/cert-manager.ts

@@ -0,0 +1,80 @@
+import { defineUnit, z } from "@highstate/contract"
+import { tlsIssuerEntity } from "../common"
+import * as dns from "../dns"
+import { clusterEntity } from "./shared"
+
+export const tlsIssuerDataSchema = z.object({
+  /**
+   * The Kubernetes cluster to use for creating gateway routes.
+   */
+  cluster: clusterEntity.schema,
+
+  /**
+   * The name of the cluster issuer which should be used to issue TLS certificates.
+   */
+  clusterIssuerName: z.string(),
+})
+
+/**
+ * The cert-manager installed on the Kubernetes cluster.
+ */
+export const certManager = defineUnit({
+  type: "k8s.cert-manager.v1",
+
+  args: {
+    /**
+     * Whether to enable the native support for Gateway API in cert-manager.
+     *
+     * Note that this can conflict with "Gateway API" unit since it is bringing its own CRDs.
+     */
+    enableGatewayApi: z.boolean().default(false),
+  },
+
+  inputs: {
+    k8sCluster: clusterEntity,
+  },
+
+  outputs: {
+    k8sCluster: clusterEntity,
+  },
+
+  meta: {
+    title: "Cert Manager",
+    icon: "simple-icons:letsencrypt",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/k8s",
+    path: "units/cert-manager",
+  },
+})
+
+/**
+ * The DNS01 TLS issuer for issuing certificates using DNS01 challenge.
+ */
+export const dns01TlsIssuer = defineUnit({
+  type: "k8s.dns01-issuer.v1",
+
+  inputs: {
+    k8sCluster: clusterEntity,
+    dnsProvider: dns.providerEntity,
+  },
+
+  outputs: {
+    tlsIssuer: tlsIssuerEntity,
+  },
+
+  meta: {
+    title: "DNS01 Issuer",
+    icon: "mdi:certificate",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/k8s",
+    path: "units/dns01-issuer",
+  },
+})
+
+export type TlsIssuerData = z.infer<typeof tlsIssuerDataSchema>

package/src/k8s/cilium.ts

@@ -0,0 +1,64 @@
+import { defineUnit, z } from "@highstate/contract"
+import { clusterEntity } from "./shared"
+
+/**
+ * The Cilium CNI deployed on Kubernetes.
+ */
+export const cilium = defineUnit({
+  type: "k8s.cilium.v1",
+
+  args: {
+    /**
+     * If set to `true`, the generated network policy will allow
+     * all DNS queries to be resolved, even if they are
+     * for forbidden (non-allowed) FQDNs.
+     *
+     * By default, is `false`.
+     */
+    allowForbiddenFqdnResolution: z.boolean().default(false),
+
+    /**
+     * Whether to enable Hubble Relay and UI for observability.
+     *
+     * By default, this is `true`.
+     *
+     * To expose the Hubble UI, you can use `k8s.apps.hubble-ui` unit.
+     */
+    enableHubble: z.boolean().default(true),
+  },
+
+  inputs: {
+    k8sCluster: clusterEntity,
+  },
+
+  outputs: {
+    k8sCluster: clusterEntity,
+  },
+
+  meta: {
+    title: "Cilium",
+    icon: "simple-icons:cilium",
+    secondaryIcon: "devicon:kubernetes",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/cilium",
+    path: "unit",
+  },
+})
+
+export const ciliumClusterMetadata = z.object({
+  cilium: z.object({
+    /**
+     * If set to `true`, the generated network policy will allow
+     * all DNS queries to be resolved, even if they are
+     * for forbidden (non-allowed) FQDNs.
+     *
+     * By default, is `false`.
+     */
+    allowForbiddenFqdnResolution: z.boolean().default(false),
+  }),
+})
+
+export type CiliumClusterMetadata = z.infer<typeof ciliumClusterMetadata>

package/src/k8s/gateway.ts

@@ -0,0 +1,70 @@
+import { defineUnit, z } from "@highstate/contract"
+import { namespaceEntity } from "./resources"
+import { clusterEntity } from "./shared"
+
+export const gatewayDataSchema = z.object({
+  /**
+   * The Kubernetes cluster to use for creating gateway routes.
+   */
+  cluster: clusterEntity.schema,
+
+  /**
+   * The namespace where the gateway controller of the class is running.
+   */
+  namespace: namespaceEntity.schema,
+
+  /**
+   * The name of the gateway class to use.
+   */
+  className: z.string(),
+
+  /**
+   * The port to use for HTTP in listener.
+   *
+   * If not provided, defaults to 80.
+   */
+  httpPort: z.number().default(80),
+
+  /**
+   * The port to use for HTTPS in listener.
+   *
+   * If not provided, defaults to 443.
+   */
+  httpsPort: z.number().default(443),
+})
+
+export const gatewayImplRefSchema = z.object({
+  package: z.literal("@highstate/k8s"),
+  data: gatewayDataSchema,
+})
+
+/**
+ * Installs the Gateway API CRDs to the cluster.
+ */
+export const gatewayApi = defineUnit({
+  type: "k8s.gateway-api.v1",
+
+  inputs: {
+    k8sCluster: clusterEntity,
+  },
+
+  outputs: {
+    k8sCluster: clusterEntity,
+  },
+
+  meta: {
+    title: "Gateway API",
+    icon: "devicon:kubernetes",
+    secondaryIcon: "mdi:api",
+    secondaryIconColor: "#4CAF50",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/k8s",
+    path: "units/gateway-api",
+  },
+})
+
+export type GatewayData = z.infer<typeof gatewayDataSchema>
+export type GatewayImplRef = z.infer<typeof gatewayImplRefSchema>

package/src/k8s/index.ts

@@ -0,0 +1,9 @@
+export * as apps from "./apps"
+export * from "./cert-manager"
+export * from "./cilium"
+export * from "./gateway"
+export * as obfuscators from "./obfuscators"
+export * from "./resources"
+export * from "./service"
+export * from "./shared"
+export * from "./workload"

package/src/{obfuscators → k8s/obfuscators}/phantun.ts

@@ -1,38 +1,42 @@
 import { defineUnit } from "@highstate/contract"
 import { deobfuscatorSpec, obfuscatorSpec } from "./shared"
 
+/**
+ * The Phantun Deobfuscator deployed on Kubernetes.
+ */
 export const deobfuscator = defineUnit({
-  type: "obfuscators.phantun.deobfuscator",
+  type: "k8s.obfuscators.phantun.deobfuscator.v1",
   ...deobfuscatorSpec,
 
   meta: {
-    displayName: "Phantun Deobfuscator",
-    description: "The Phantun Deobfuscator deployed on Kubernetes.",
-    primaryIcon: "mdi:network-outline",
+    title: "Phantun Deobfuscator",
+    icon: "mdi:network-outline",
     secondaryIcon: "mdi:hide",
     category: "Obfuscators",
   },
 
   source: {
-    package: "@highstate/obfuscators",
+    package: "@highstate/k8s.obfuscators",
     path: "phantun/deobfuscator",
   },
 })
 
+/**
+ * The Phantun Obfuscator deployed on Kubernetes.
+ */
 export const obfuscator = defineUnit({
-  type: "obfuscators.phantun.obfuscator",
+  type: "k8s.obfuscators.phantun.obfuscator.v1",
   ...obfuscatorSpec,
 
   meta: {
-    displayName: "Phantun Obfuscator",
-    description: "The Phantun Obfuscator deployed on Kubernetes.",
-    primaryIcon: "mdi:network-outline",
+    title: "Phantun Obfuscator",
+    icon: "mdi:network-outline",
     secondaryIcon: "mdi:hide",
     category: "Obfuscators",
   },
 
   source: {
-    package: "@highstate/obfuscators",
+    package: "@highstate/k8s.obfuscators",
     path: "phantun/obfuscator",
   },
 })

package/src/{obfuscators → k8s/obfuscators}/shared.ts

@@ -1,6 +1,6 @@
-import { $args, $inputs, $outputs, Type, type Static, type TObject } from "@highstate/contract"
-import { clusterEntity } from "../k8s"
-import { l4EndpointEntity } from "../network"
+import { $args, $inputs, $outputs, type FullComponentArgumentOptions, z } from "@highstate/contract"
+import { l4EndpointEntity } from "../../network"
+import { clusterEntity } from "../shared"
 
 export const deobfuscatorSpec = {
   args: $args({
@@ -9,21 +9,21 @@ export const deobfuscatorSpec = {
      *
      * By default, calculated as `deobfs-{type}-{name}`.
      */
-    appName: Type.Optional(Type.String()),
+    appName: z.string().optional(),
 
     /**
      * The L4 endpoint to forward deobfuscated traffic to.
      *
      * Will take precedence over the `targetEndpoint` input.
      */
-    targetEndpoints: Type.Default(Type.Array(Type.String()), []),
+    targetEndpoints: z.string().array().default([]),
 
     /**
      * Whether to expose the deobfuscator service by "NodePort" or "LoadBalancer".
      *
      * By default, the service is not exposed and only accessible from within the cluster.
      */
-    external: Type.Default(Type.Boolean(), false),
+    external: z.boolean().default(false),
   }),
 
   inputs: $inputs({
@@ -63,21 +63,21 @@ export const obfuscatorSpec = {
      *
      * By default, calculated as `obfs-{type}-{name}`.
      */
-    appName: Type.Optional(Type.String()),
+    appName: z.string().optional(),
 
     /**
      * The endpoint of the deobfuscator to pass obfuscated traffic to.
      *
      * Will take precedence over the `endpoint` input.
      */
-    endpoints: Type.Default(Type.Array(Type.String()), []),
+    endpoints: z.string().array().default([]),
 
     /**
      * Whether to expose the obfuscator service by "NodePort" or "LoadBalancer".
      *
      * By default, the service is not exposed and only accessible from within the cluster.
      */
-    external: Type.Default(Type.Boolean(), false),
+    external: z.boolean().default(false),
   }),
 
   inputs: $inputs({
@@ -109,5 +109,11 @@ export const obfuscatorSpec = {
   }),
 }
 
-export type DeobfuscatorArgs = Static<TObject<(typeof deobfuscatorSpec)["args"]>>
-export type ObfuscatorArgs = Static<TObject<(typeof obfuscatorSpec)["args"]>>
+type ArgsFromSpec<T extends Record<string, FullComponentArgumentOptions>> = z.infer<
+  z.ZodObject<{
+    [K in keyof T]: T[K]["schema"]
+  }>
+>
+
+export type DeobfuscatorArgs = ArgsFromSpec<typeof deobfuscatorSpec.args>
+export type ObfuscatorArgs = ArgsFromSpec<typeof obfuscatorSpec.args>

package/src/k8s/resources.ts

@@ -0,0 +1,111 @@
+import { defineEntity, z } from "@highstate/contract"
+
+/**
+ * The generic metadata schema for Kubernetes resources.
+ */
+export const metadataSchema = z.object({
+  name: z.string(),
+  labels: z.record(z.string(), z.string()).optional(),
+  annotations: z.record(z.string(), z.string()).optional(),
+  uid: z.string(),
+})
+
+/**
+ * The metadata schema for Kubernetes resources that are scoped to a namespace.
+ *
+ * It includes the namespace field.
+ */
+export const scopedMetadataSchema = 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.
+ */
+export const resourceSchema = z.object({
+  clusterId: z.string(),
+  clusterName: z.string(),
+  type: z.string(),
+  metadata: metadataSchema,
+})
+
+/**
+ * The schema for Kubernetes resources that are scoped to a namespace.
+ *
+ * Extends the base resource schema with the scoped metadata.
+ */
+export const scopedResourceSchema = z.object({
+  ...resourceSchema.shape,
+  metadata: scopedMetadataSchema,
+})
+
+/**
+ * The entity which represents a Kubernetes namespace managed by Highstate.
+ */
+export const namespaceEntity = defineEntity({
+  type: "k8s.namespace.v1",
+
+  schema: z.object({
+    ...resourceSchema.shape,
+    type: z.literal("namespace"),
+  }),
+
+  meta: {
+    color: "#9E9E9E",
+  },
+})
+
+/**
+ * The entity which represents a Kubernetes persistent volume claim managed by Highstate.
+ */
+export const persistentVolumeClaimEntity = defineEntity({
+  type: "k8s.persistent-volume-claim.v1",
+
+  schema: z.object({
+    ...scopedResourceSchema.shape,
+    type: z.literal("persistent-volume-claim"),
+  }),
+
+  meta: {
+    color: "#FFC107",
+  },
+})
+
+/**
+ * The entity which represents a Gateway resource from the Gateway API.
+ */
+export const gatewayEntity = defineEntity({
+  type: "k8s.gateway.v1",
+
+  schema: z.object({
+    ...scopedResourceSchema.shape,
+    type: z.literal("gateway"),
+  }),
+
+  meta: {
+    color: "#4CAF50",
+  },
+})
+
+export const certificateEntity = defineEntity({
+  type: "k8s.certificate.v1",
+
+  schema: z.object({
+    ...scopedResourceSchema.shape,
+    type: z.literal("certificate"),
+  }),
+})
+
+export type Metadata = z.infer<typeof metadataSchema>
+export type Resource = z.infer<typeof resourceSchema>
+
+export type ScopedMetadata = z.infer<typeof scopedMetadataSchema>
+export type ScopedResource = z.infer<typeof scopedResourceSchema>
+
+export type Namespace = 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>