@highstate/library 0.9.4 → 0.9.6

package/src/k8s.ts

@@ -1,6 +1,14 @@
 import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
 import { Literal } from "@sinclair/typebox"
-import { providerEntity } from "./dns"
+import * as dns from "./dns"
+import { l3EndpointEntity, l4EndpointEntity } from "./network"
+import { serverEntity } from "./common"
+import { arrayPatchModeSchema } from "./utils"
+
+export const fallbackKubeApiAccessSchema = Type.Object({
+  serverIp: Type.String(),
+  serverPort: Type.Number(),
+})
 
 export const tunDevicePolicySchema = Type.Union([
   Type.Object({
@@ -13,14 +21,19 @@ export const tunDevicePolicySchema = Type.Union([
   }),
 ])
 
-export const clusterInfoSchema = Type.Object({
-  id: Type.String(),
-  name: Type.String(),
-  cni: Type.Optional(Type.String()),
-  externalIps: Type.Array(Type.String()),
-  fqdn: Type.Optional(Type.String()),
-  kubeApiServerIp: Type.Optional(Type.String()),
-  kubeApiServerPort: Type.Optional(Type.Number()),
+export const externalServiceTypeSchema = Type.StringEnum(["NodePort", "LoadBalancer"])
+export const scheduleOnMastersPolicySchema = Type.StringEnum(["always", "when-no-workers", "never"])
+export const cniSchema = Type.StringEnum(["cilium", "other"])
+
+export const clusterQuirksSchema = Type.Object({
+  /**
+   * The IP and port of the kube-apiserver available from the cluster.
+   *
+   * Will be used to create fallback network policy in CNIs which does not support allowing access to the kube-apiserver.
+   *
+   * @schema
+   */
+  fallbackKubeApiAccess: Type.Optional(fallbackKubeApiAccessSchema),
 
   /**
    * Specifies the policy for using the tun device inside containers.
@@ -28,33 +41,96 @@ export const clusterInfoSchema = Type.Object({
    * If not provided, the default policy is `host` which assumes just mounting /dev/net/tun from the host.
    *
    * 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.
+   *
+   * @schema
    */
   tunDevicePolicy: Type.Optional(tunDevicePolicySchema),
+
+  /**
+   * The service type to use for external services.
+   *
+   * If not provided, the default service type is `NodePort` since `LoadBalancer` may not be available.
+   *
+   * @schema
+   */
+  externalServiceType: Type.Optional(externalServiceTypeSchema),
 })
 
+export const clusterInfoProperties = {
+  /**
+   * The unique identifier of the cluster.
+   *
+   * Should be defined as a UUID of the `kube-system` namespace which is always present in the cluster.
+   *
+   * @schema
+   */
+  id: Type.String(),
+
+  /**
+   * The name of the cluster.
+   *
+   * @schema
+   */
+  name: Type.String(),
+
+  /**
+   * The name of the CNI plugin used by the cluster.
+   *
+   * Supported values are:
+   * - `cilium`
+   * - `other`
+   *
+   * @schema
+   */
+  cni: cniSchema,
+
+  /**
+   * 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).
+   *
+   * @schema
+   */
+  endpoints: Type.Array(l3EndpointEntity.schema),
+
+  /**
+   * 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: Type.Array(l4EndpointEntity.schema),
+
+  /**
+   * The external IPs of the cluster nodes allowed to be used for external access.
+   *
+   * @schema
+   */
+  externalIps: Type.Array(Type.String()),
+
+  /**
+   * The extra quirks of the cluster to improve compatibility.
+   *
+   * @schema
+   */
+  quirks: Type.Optional(clusterQuirksSchema),
+} as const
+
 export const serviceTypeSchema = Type.StringEnum(["NodePort", "LoadBalancer", "ClusterIP"])
 
 export const metadataSchema = Type.Object({
-  namespace: Type.Optional(Type.String()),
   name: Type.String(),
+  namespace: Type.String(),
   labels: Type.Optional(Type.Record(Type.String(), Type.String())),
   annotations: Type.Optional(Type.Record(Type.String(), Type.String())),
 })
 
-export const servicePortSchema = Type.Object({
-  name: Type.Optional(Type.String()),
-  port: Type.Optional(Type.Number()),
-  targetPort: Type.Optional(Type.Union([Type.Number(), Type.String()])),
-  protocol: Type.Optional(Type.String()),
-})
-
-export const serviceSpecSchema = Type.Object({
-  type: Type.Optional(Type.String()),
-  selector: Type.Record(Type.String(), Type.String()),
-  ports: Type.Array(servicePortSchema),
-  clusterIP: Type.Optional(Type.String()),
-  clusterIPs: Type.Optional(Type.Array(Type.String())),
-  externalIPs: Type.Optional(Type.Array(Type.String())),
+export const resourceSchema = Type.Object({
+  clusterId: Type.String(),
+  metadata: metadataSchema,
 })
 
 export const serviceEntity = defineEntity({
@@ -62,9 +138,8 @@ export const serviceEntity = defineEntity({
 
   schema: Type.Object({
     type: Type.Literal("k8s.service"),
-    clusterInfo: clusterInfoSchema,
-    metadata: metadataSchema,
-    spec: serviceSpecSchema,
+    ...resourceSchema.properties,
+    endpoints: Type.Array(l4EndpointEntity.schema),
   }),
 
   meta: {
@@ -76,7 +151,7 @@ export const clusterEntity = defineEntity({
   type: "k8s.cluster",
 
   schema: Type.Object({
-    info: clusterInfoSchema,
+    ...clusterInfoProperties,
     kubeconfig: Type.String(),
   }),
 
@@ -87,62 +162,73 @@ export const clusterEntity = defineEntity({
 
 export const internalIpsPolicySchema = Type.StringEnum(["always", "public", "never"])
 
-export const sharedClusterArgs = {
+export const scheduleOnMastersPolicyArgs = {
   /**
-   * The list of external IPs of the cluster nodes allowed to be used for external access.
+   * The policy for scheduling workloads on master nodes.
    *
-   * If not provided, will be automatically detected by querying the cluster nodes.
+   * - `always`: always schedule workloads on master nodes regardless of the number of workers;
+   * - `when-no-workers`: schedule workloads on master nodes only if there are no workers (default);
+   * - `never`: never schedule workloads on master nodes.
    *
    * @schema
    */
-  externalIps: Type.Optional(Type.Array(Type.String())),
-
-  /**
-   * The policy for using internal IPs of the nodes as external IPs.
-   *
-   * - `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.
-   *
-   * @schema
-   */
-  internalIpsPolicy: { ...internalIpsPolicySchema, default: "public" },
+  scheduleOnMastersPolicy: Type.Default(scheduleOnMastersPolicySchema, "when-no-workers"),
+}
 
-  /**
-   * The FQDN to register the cluster nodes with.
-   *
-   * If provided and `registerFqdn` is set to `true`, the corresponding DNS provider must be provided to set up the DNS records.
-   *
-   * @schema
-   */
-  fqdn: Type.Optional(Type.String()),
+export const clusterInputs = {
+  masters: {
+    entity: serverEntity,
+    multiple: true,
+  },
+  workers: {
+    entity: serverEntity,
+    multiple: true,
+    required: false,
+  },
+} as const
 
-  /**
-   * Whether to register the cluster nodes with the provided FQDN.
-   *
-   * By default, `true`.
-   *
-   * @schema
-   */
-  registerFqdn: Type.Boolean({ default: true }),
-}
+export const clusterOutputs = {
+  k8sCluster: clusterEntity,
+  apiEndpoints: {
+    entity: l4EndpointEntity,
+    multiple: true,
+  },
+  endpoints: {
+    entity: l3EndpointEntity,
+    multiple: true,
+  },
+} as const
 
 export const existingCluster = defineUnit({
   type: "k8s.existing-cluster",
 
   args: {
-    ...sharedClusterArgs,
+    /**
+     * 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.
+     *
+     * @schema
+     */
+    externalIps: Type.Optional(Type.Array(Type.String())),
 
     /**
-     * The policy for using the tun device inside containers.
+     * The policy for using internal IPs of the nodes as external IPs.
      *
-     * If not provided, the default policy is `host` which assumes just mounting /dev/net/tun from the host.
+     * - `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.
      *
-     * 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.
+     * @schema
+     */
+    internalIpsPolicy: Type.Default(internalIpsPolicySchema, "public"),
+
+    /**
+     * The extra quirks of the cluster to improve compatibility.
      *
      * @schema
      */
-    tunDevicePolicy: Type.Optional(tunDevicePolicySchema),
+    quirks: Type.Optional(clusterQuirksSchema),
   },
 
   secrets: {
@@ -156,14 +242,13 @@ export const existingCluster = defineUnit({
     kubeconfig: Type.Record(Type.String(), Type.Any()),
   },
 
-  outputs: {
-    cluster: clusterEntity,
-  },
+  outputs: clusterOutputs,
 
   meta: {
     displayName: "Existing Cluster",
     description: "An existing Kubernetes cluster.",
-    primaryIcon: "mdi:kubernetes",
+    primaryIcon: "devicon:kubernetes",
+    category: "Kubernetes",
   },
 
   source: {
@@ -172,16 +257,117 @@ export const existingCluster = defineUnit({
   },
 })
 
+export const clusterPatch = defineUnit({
+  type: "k8s.cluster-patch",
+
+  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).
+     *
+     * @schema
+     */
+    apiEndpoints: Type.Default(Type.Array(Type.String()), []),
+
+    /**
+     * 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: Type.Default(arrayPatchModeSchema, "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).
+     *
+     * @schema
+     */
+    endpoints: Type.Default(Type.Array(Type.String()), []),
+
+    /**
+     * 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.
+     */
+    endpointsPatchMode: Type.Default(arrayPatchModeSchema, "prepend"),
+  },
+
+  inputs: {
+    k8sCluster: clusterEntity,
+    apiEndpoints: {
+      entity: l4EndpointEntity,
+      required: false,
+      multiple: true,
+    },
+    endpoints: {
+      entity: l3EndpointEntity,
+      required: false,
+      multiple: true,
+    },
+  },
+
+  outputs: clusterOutputs,
+
+  meta: {
+    displayName: "Cluster Patch",
+    description: "Patches some properties of the cluster.",
+    primaryIcon: "devicon:kubernetes",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/k8s",
+    path: "units/cluster-patch",
+  },
+})
+
+export const clusterDns = defineUnit({
+  type: "cluster-dns",
+
+  args: {
+    ...dns.createArgs(),
+    ...dns.createArgs("api"),
+  },
+
+  inputs: {
+    k8sCluster: clusterEntity,
+    ...dns.inputs,
+  },
+
+  outputs: clusterOutputs,
+
+  meta: {
+    displayName: "Cluster DNS",
+    description: "Creates DNS records for the cluster and updates endpoints.",
+    primaryIcon: "devicon:kubernetes",
+    secondaryIcon: "mdi:dns",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/k8s",
+    path: "units/cluster-dns",
+  },
+})
+
 export const gatewayEntity = defineEntity({
   type: "k8s.gateway",
 
   schema: Type.Object({
-    clusterInfo: clusterInfoSchema,
+    clusterId: Type.String(),
     gatewayClassName: Type.String(),
     httpListenerPort: Type.Number(),
     httpsListenerPort: Type.Number(),
-    ip: Type.String(),
-    service: Type.Optional(serviceEntity.schema),
+    endpoints: Type.Array(l3EndpointEntity.schema),
   }),
 
   meta: {
@@ -193,7 +379,7 @@ export const tlsIssuerEntity = defineEntity({
   type: "k8s.tls-issuer",
 
   schema: Type.Object({
-    clusterInfo: clusterInfoSchema,
+    clusterId: Type.String(),
     clusterIssuerName: Type.String(),
   }),
 
@@ -206,9 +392,10 @@ export const accessPointEntity = defineEntity({
   type: "k8s.access-point",
 
   schema: Type.Object({
+    clusterId: Type.String(),
     gateway: gatewayEntity.schema,
     tlsIssuer: tlsIssuerEntity.schema,
-    dnsProviders: Type.Array(providerEntity.schema),
+    dnsProviders: Type.Array(dns.providerEntity.schema),
   }),
 
   meta: {
@@ -223,7 +410,7 @@ export const accessPoint = defineUnit({
     gateway: gatewayEntity,
     tlsIssuer: tlsIssuerEntity,
     dnsProviders: {
-      entity: providerEntity,
+      entity: dns.providerEntity,
       multiple: true,
     },
   },
@@ -236,6 +423,7 @@ export const accessPoint = defineUnit({
     displayName: "Access Point",
     description: "An access point which can be used to connect to services.",
     primaryIcon: "mdi:access-point",
+    category: "Kubernetes",
   },
 
   source: {
@@ -259,6 +447,7 @@ export const certManager = defineUnit({
     displayName: "Cert Manager",
     description: "A certificate manager for managing TLS certificates.",
     primaryIcon: "simple-icons:letsencrypt",
+    category: "Kubernetes",
   },
 
   source: {
@@ -284,7 +473,7 @@ export const dns01TlsIssuer = defineUnit({
   inputs: {
     k8sCluster: clusterEntity,
     dnsProviders: {
-      entity: providerEntity,
+      entity: dns.providerEntity,
       multiple: true,
     },
   },
@@ -297,6 +486,7 @@ export const dns01TlsIssuer = defineUnit({
     displayName: "DNS01 Issuer",
     description: "A TLS issuer for issuing certificate using DNS01 challenge.",
     primaryIcon: "mdi:certificate",
+    category: "Kubernetes",
   },
 
   source: {
@@ -305,34 +495,12 @@ export const dns01TlsIssuer = defineUnit({
   },
 })
 
-export const containerSchema = Type.Object({
-  name: Type.String(),
-  image: Type.String(),
-})
-
-export const labelSelectorSchema = Type.Object({
-  matchLabels: Type.Record(Type.String(), Type.String()),
-})
-
-export const deploymentSpecSchema = Type.Object({
-  replicas: Type.Number(),
-  selector: labelSelectorSchema,
-  template: Type.Object({
-    metadata: metadataSchema,
-    spec: Type.Object({
-      containers: Type.Array(containerSchema),
-    }),
-  }),
-})
-
 export const deploymentEntity = defineEntity({
   type: "k8s.deployment",
 
   schema: Type.Object({
     type: Type.Literal("k8s.deployment"),
-    clusterInfo: clusterInfoSchema,
-    metadata: metadataSchema,
-
+    ...resourceSchema.properties,
     service: Type.Optional(serviceEntity.schema),
   }),
 
@@ -346,10 +514,8 @@ export const statefulSetEntity = defineEntity({
 
   schema: Type.Object({
     type: Type.Literal("k8s.stateful-set"),
-    clusterInfo: clusterInfoSchema,
-    metadata: metadataSchema,
-
-    service: Type.Optional(serviceEntity.schema),
+    ...resourceSchema.properties,
+    service: serviceEntity.schema,
   }),
 
   meta: {
@@ -357,13 +523,22 @@ export const statefulSetEntity = defineEntity({
   },
 })
 
+export const exposableWorkloadEntity = defineEntity({
+  type: "k8s.exposable-workload",
+
+  schema: Type.Union([deploymentEntity.schema, statefulSetEntity.schema]),
+
+  meta: {
+    color: "#4CAF50",
+  },
+})
+
 export const persistentVolumeClaimEntity = defineEntity({
   type: "k8s.persistent-volume-claim",
 
   schema: Type.Object({
     type: Type.Literal("k8s.persistent-volume-claim"),
-    clusterInfo: clusterInfoSchema,
-    metadata: metadataSchema,
+    ...resourceSchema.properties,
   }),
 
   meta: {
@@ -376,7 +551,7 @@ export const interfaceEntity = defineEntity({
 
   schema: Type.Object({
     name: Type.String(),
-    deployment: deploymentEntity.schema,
+    workload: exposableWorkloadEntity.schema,
   }),
 
   meta: {
@@ -400,8 +575,10 @@ export const gatewayApi = defineUnit({
   meta: {
     displayName: "Gateway API",
     description: "Installs the Gateway API CRDs to the cluster.",
-    primaryIcon: "mdi:kubernetes",
-    primaryIconColor: "#4CAF50",
+    primaryIcon: "devicon:kubernetes",
+    secondaryIcon: "mdi:api",
+    secondaryIconColor: "#4CAF50",
+    category: "Kubernetes",
   },
 
   source: {
@@ -410,7 +587,7 @@ export const gatewayApi = defineUnit({
   },
 })
 
-export type ClusterInfo = Static<typeof clusterInfoSchema>
+export type CNI = Static<typeof cniSchema>
 export type Cluster = Static<typeof clusterEntity.schema>
 
 export type Gateway = Static<typeof gatewayEntity.schema>
@@ -418,15 +595,13 @@ export type TlsIssuer = Static<typeof tlsIssuerEntity.schema>
 export type AccessPoint = Static<typeof accessPointEntity.schema>
 
 export type Metadata = Static<typeof metadataSchema>
+export type Resource = Static<typeof resourceSchema>
 
 export type ServiceType = Static<typeof serviceTypeSchema>
-export type ServicePort = Static<typeof servicePortSchema>
-export type ServiceSpec = Static<typeof serviceSpecSchema>
 export type Service = Static<typeof serviceEntity.schema>
 
-export type Container = Static<typeof containerSchema>
-export type DeploymentSpec = Static<typeof deploymentSpecSchema>
 export type Deployment = Static<typeof deploymentEntity.schema>
+export type ExposableWorkload = Static<typeof exposableWorkloadEntity.schema>
 
 export type PersistentVolumeClaim = Static<typeof persistentVolumeClaimEntity.schema>
 export type StatefulSet = Static<typeof statefulSetEntity.schema>

package/src/mullvad.ts

@@ -1,19 +1,12 @@
 import { defineUnit, Type } from "@highstate/contract"
 import { networkEntity, peerEntity } from "./wireguard"
-import { l4EndpointEntity } from "./common"
-
-export const endpointType = Type.Union([
-  Type.Literal("fqdn"),
-  Type.Literal("ipv4"),
-  Type.Literal("ipv6"),
-])
+import { l4EndpointEntity } from "./network"
 
 export const peer = defineUnit({
   type: "mullvad.peer",
 
   args: {
     hostname: Type.Optional(Type.String()),
-    endpointType: Type.Optional({ ...endpointType, default: "fqdn" }),
 
     /**
      * Whether to include Mullvad DNS servers in the peer configuration.
@@ -37,7 +30,11 @@ export const peer = defineUnit({
 
   outputs: {
     peer: peerEntity,
-    l4Endpoint: l4EndpointEntity,
+
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
   },
 
   meta: {
@@ -46,6 +43,7 @@ export const peer = defineUnit({
     primaryIcon: "simple-icons:mullvad",
     secondaryIcon: "cib:wireguard",
     secondaryIconColor: "#88171a",
+    category: "VPN",
   },
 
   source: {