@highstate/library 0.7.2 → 0.7.3

package/src/talos.ts

@@ -0,0 +1,116 @@
+import { defineEntity, defineUnit, Type } from "@highstate/contract"
+import { serverEntity } from "./common"
+import { clusterEntity as k8sClusterEntity } from "./k8s"
+
+export const clusterEntity = defineEntity({
+  type: "talos.cluster",
+
+  schema: Type.Object({
+    clientConfiguration: Type.String(),
+    machineSecrets: Type.String(),
+  }),
+
+  meta: {
+    color: "#2d2d2d",
+  },
+})
+
+export const cniSchema = Type.StringEnum(["none", "cilium", "flannel"])
+export const csiSchema = Type.StringEnum(["none", "local-path-provisioner"])
+
+export const cluster = defineUnit({
+  type: "talos.cluster",
+
+  args: {
+    /**
+     * Allow scheduling workloads on the master nodes.
+     *
+     * By default, "true" if no worker nodes are provided.
+     */
+    scheduleOnMasters: Type.Boolean(),
+
+    /**
+     * The endpoint of the cluster.
+     *
+     * By default, the first master node's endpoint is used.
+     */
+    endpoint: Type.Optional(Type.String()),
+
+    /**
+     * The name of the cluster.
+     *
+     * By default, the name of the instance is used.
+     */
+    clusterName: Type.Optional(Type.String()),
+
+    /**
+     * The CNI plugin to use.
+     *
+     * The following options are available:
+     * - "cilium" (default)
+     * - "flannel" (built-in in Talos)
+     * - "none" (disable CNI, must be installed manually)
+     *
+     * The "cilium" CNI plugin is recommended to cover advanced network policies like FQDNs.
+     */
+    cni: { ...cniSchema, default: "cilium" },
+
+    /**
+     * The CSI plugin to use.
+     *
+     * The following options are available:
+     * - "local-path-provisioner" (default)
+     * - "none" (disable CSI, must be installed manually if needed)
+     */
+    csi: { ...csiSchema, default: "local-path-provisioner" },
+
+    /**
+     * The shared configuration patch.
+     * It will be applied to all nodes.
+     */
+    sharedConfigPatch: Type.Optional(Type.Record(Type.String(), Type.Any())),
+
+    /**
+     * The master configuration patch.
+     * It will be applied to all master nodes.
+     */
+    masterConfigPatch: Type.Optional(Type.Record(Type.String(), Type.Any())),
+
+    /**
+     * The worker configuration patch.
+     * It will be applied to all worker nodes.
+     */
+    workerConfigPatch: Type.Optional(Type.Record(Type.String(), Type.Any())),
+  },
+
+  inputs: {
+    masters: {
+      entity: serverEntity,
+      multiple: true,
+    },
+    workers: {
+      entity: serverEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  outputs: {
+    k8sCluster: k8sClusterEntity,
+    talosCluster: clusterEntity,
+  },
+
+  meta: {
+    displayName: "Talos Cluster",
+    description: "A Kubernetes cluster managed by Talos.",
+    category: "Talos",
+    color: "#2d2d2d",
+    primaryIcon: "simple-icons:talos",
+    secondaryIcon: "devicon:kubernetes",
+  },
+
+  source: {
+    package: "@highstate/talos",
+    path: "cluster",
+  },
+})

package/src/wireguard.ts

@@ -0,0 +1,588 @@
+import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
+import {
+  clusterEntity,
+  deploymentEntity,
+  interfaceEntity,
+  serviceEntity,
+  serviceTypeSchema,
+  statefulSetEntity,
+} from "./k8s"
+import { providerEntity } from "./dns"
+
+export const backendSchema = Type.StringEnum(["wireguard", "amneziawg"])
+export const presharedKeyModeSchema = Type.StringEnum(["none", "global", "secure"])
+
+export type Backend = Static<typeof backendSchema>
+export type PresharedKeyMode = Static<typeof presharedKeyModeSchema>
+
+export const networkEntity = defineEntity({
+  type: "wireguard.network",
+
+  schema: Type.Object({
+    backend: Type.Optional(backendSchema),
+    presharedKeyMode: presharedKeyModeSchema,
+    globalPresharedKey: Type.Optional(Type.String()),
+    ipv6: Type.Optional(Type.Boolean()),
+  }),
+})
+
+export const identityEntity = defineEntity({
+  type: "wireguard.identity",
+
+  schema: Type.Object({
+    name: Type.String(),
+    network: Type.Optional(networkEntity.schema),
+    address: Type.Optional(Type.String()),
+    privateKey: Type.String(),
+    presharedKeyPart: Type.Optional(Type.String()),
+    k8sServices: Type.Array(serviceEntity.schema),
+    exitNode: Type.Boolean(),
+    listenPort: Type.Optional(Type.Number()),
+    externalIp: Type.Optional(Type.String()),
+    endpoint: Type.Optional(Type.String()),
+    fqdn: Type.Optional(Type.String()),
+  }),
+
+  meta: {
+    color: "#F44336",
+  },
+})
+
+export const peerEntity = defineEntity({
+  type: "wireguard.peer",
+
+  schema: Type.Object({
+    name: Type.String(),
+    network: Type.Optional(networkEntity.schema),
+    publicKey: Type.String(),
+    address: Type.Optional(Type.String()),
+    allowedIps: Type.Array(Type.String()),
+    endpoint: Type.Optional(Type.String()),
+    presharedKeyPart: Type.Optional(Type.String()),
+    excludedIps: Type.Optional(Type.Array(Type.String())),
+    dns: Type.Optional(Type.Array(Type.String())),
+  }),
+
+  meta: {
+    color: "#673AB7",
+  },
+})
+
+export const k8sNodeEntity = defineEntity({
+  type: "wireguard.node",
+
+  schema: Type.Object({
+    network: Type.String(),
+    address: Type.String(),
+    endpoint: Type.Optional(Type.String()),
+    peers: Type.Array(Type.String()),
+  }),
+})
+
+export type Network = Static<typeof networkEntity.schema>
+export type Identity = Static<typeof identityEntity.schema>
+export type Peer = Static<typeof peerEntity.schema>
+
+/**
+ * The network hols the shared configuration for the WireGuard identities, peers and nodes.
+ */
+export const network = defineUnit({
+  type: "wireguard.network",
+
+  args: {
+    /**
+     * The backend to use for the WireGuard network.
+     *
+     * Possible values are:
+     * 1. `wireguard` - The default backend.
+     * 2. `amneziawg` - The censorship-resistant fork of WireGuard.
+     *
+     * By default, the `wireguard` backend is used.
+     *
+     * @schema
+     */
+    backend: backendSchema,
+
+    /**
+     * The option which defines how to handle pre-shared keys between peers.
+     *
+     * 1. `none` - No pre-shared keys will be used.
+     * 2. `global` - A single pre-shared key will be used for all peer pairs in the network.
+     * 3. `secure` - Each peer pair will have its own pre-shared key.
+     * In this case, each identity generates `presharedKeyPart` and the actual pre-shared key
+     * for each peer pair will be computed as `xor(peer1.presharedKeyPart, peer2.presharedKeyPart)`.
+     *
+     * If the whole network is managed by the HighState, the `secure` mode is recommended.
+     *
+     * By default, the `none` mode is used.
+     *
+     * @schema
+     */
+    presharedKeyMode: Type.Optional(presharedKeyModeSchema),
+
+    /**
+     * The option to enable IPv6 support in the network.
+     *
+     * By default, IPv6 support is disabled.
+     *
+     * @schema
+     */
+    ipv6: Type.Optional(Type.Boolean()),
+  },
+
+  secrets: {
+    /**
+     * The global pre-shared key to use for all peer pairs in the network.
+     *
+     * Will be used only if `presharedKeyMode` is set to `global`.
+     * Will be generated automatically if not provided.
+     *
+     * @schema
+     */
+    globalPresharedKey: Type.Optional(Type.String()),
+  },
+
+  outputs: {
+    network: networkEntity,
+  },
+
+  meta: {
+    description: "The WireGuard network with some shared configuration.",
+    primaryIcon: "simple-icons:wireguard",
+    primaryIconColor: "#88171a",
+    secondaryIcon: "mdi:local-area-network-connect",
+  },
+
+  source: {
+    package: "@highstate/wireguard",
+    path: "network",
+  },
+})
+
+const sharedPeerArgs = {
+  /**
+   * The name of the WireGuard peer.
+   *
+   * If not provided, the peer will be named after the unit.
+   *
+   * @schema
+   */
+  peerName: Type.Optional(Type.String()),
+
+  /**
+   * The address of the WireGuard interface.
+   *
+   * The address may be any IPv4 or IPv6 address. CIDR notation is also supported.
+   *
+   * @schema
+   */
+  address: Type.Optional(Type.String()),
+
+  /**
+   * The list of allowed IPs for the peer.
+   *
+   * @schema
+   */
+  allowedIps: Type.Optional(Type.Array(Type.String())),
+
+  /**
+   * The convenience option to set `allowedIps` to `0.0.0.0/0, ::/0`.
+   *
+   * Will be merged with the `allowedIps` if provided.
+   *
+   * @schema
+   */
+  exitNode: Type.Optional(Type.Boolean()),
+
+  /**
+   * The list of IP ranges to exclude from the tunnel.
+   *
+   * Implementation notes:
+   *
+   * - This list will not be used to generate the allowed IPs for the peer.
+   * - Instead, the node will setup extra direct routes to these IPs via default gateway.
+   * - This allows to use `0.0.0.0/0, ::/0` in the `allowedIps` (and corresponding fwmark magic) and still have some IPs excluded from the tunnel.
+   *
+   * @schema
+   */
+  excludedIps: Type.Optional(Type.Array(Type.String())),
+
+  /**
+   * The convenience option to exclude private IPs from the tunnel.
+   *
+   * For IPv4, the private IPs are:
+   *
+   * - `10.0.0.0/8`
+   * - `172.16.0.0/12`
+   * - `192.168.0.0/16`
+   *
+   * For IPv6, the private IPs are:
+   *
+   * - `fc00::/7`
+   * - `fe80::/10`
+   *
+   * Will be merged with `excludedIps` if provided.
+   *
+   * @schema
+   */
+  excludePrivateIps: Type.Optional(Type.Boolean()),
+
+  /**
+   * The endpoint of the WireGuard peer.
+   *
+   * @schema
+   */
+  endpoint: Type.Optional(Type.String()),
+
+  /**
+   * The DNS servers that should be used by the interface connected to the WireGuard peer.
+   *
+   * If multiple peers define DNS servers, the node will merge them into a single list (but this is discouraged).
+   *
+   * @schema
+   */
+  dns: Type.Optional(Type.Array(Type.String())),
+
+  /**
+   * The convenience option to include the DNS servers to the allowed IPs.
+   *
+   * By default, is `true`.
+   *
+   * @schema
+   */
+  includeDns: Type.Optional(Type.Boolean({ default: true })),
+}
+
+const sharedInterfaceArgs = {
+  /**
+   * The port to listen on.
+   *
+   * Will override the `listenPort` of the identity if provided.
+   *
+   * @schema
+   */
+  listenPort: Type.Optional(Type.Number()),
+
+  /**
+   * The DNS servers that should be used by the interface connected to the WireGuard node.
+   *
+   * Will be merged with the DNS servers of the peers.
+   *
+   * @schema
+   */
+  dns: Type.Optional(Type.Array(Type.String())),
+}
+
+export const peer = defineUnit({
+  type: "wireguard.peer",
+
+  args: {
+    ...sharedPeerArgs,
+
+    /**
+     * The public key of the WireGuard peer.
+     *
+     * @schema
+     */
+    publicKey: Type.String(),
+  },
+
+  inputs: {
+    /**
+     * The network to use for the WireGuard peer.
+     *
+     * If not provided, the peer will use default network configuration.
+     *
+     * @schema
+     */
+    network: {
+      entity: networkEntity,
+      required: false,
+    },
+  },
+
+  outputs: {
+    peer: peerEntity,
+  },
+
+  meta: {
+    description: "The WireGuard peer with the public key.",
+    primaryIcon: "simple-icons:wireguard",
+    primaryIconColor: "#88171a",
+    secondaryIcon: "mdi:badge-account-horizontal",
+  },
+
+  source: {
+    package: "@highstate/wireguard",
+    path: "peer",
+  },
+})
+
+export const identity = defineUnit({
+  type: "wireguard.identity",
+
+  args: {
+    ...sharedPeerArgs,
+
+    /**
+     * The port to listen on.
+     *
+     * Used by the implementation of the identity and to calculate the endpoint of the peer.
+     *
+     * @schema
+     */
+    listenPort: Type.Optional(Type.Number()),
+
+    /**
+     * The external IP address of the WireGuard identity.
+     *
+     * Used by the implementation of the identity and to calculate the endpoint of the peer.
+     *
+     * @schema
+     */
+    externalIp: Type.Optional(Type.String()),
+
+    /**
+     * The endpoint of the WireGuard peer.
+     *
+     * By default, the endpoint is calculated as `externalIp:listenPort`.
+     *
+     * If overridden, does not affect node which implements the identity, but is used in the peer configuration of other nodes.
+     *
+     * @schema
+     */
+    endpoint: Type.Optional(Type.String()),
+
+    /**
+     * The FQDN of the WireGuard identity.
+     * Will be used as endpoint for the peer.
+     *
+     * If `dnsProvider` is provided and `externalIp` is available, the FQDN will be registered automatically.
+     *
+     * @schema
+     */
+    fqdn: Type.Optional(Type.String()),
+  },
+
+  secrets: {
+    /**
+     * The private key of the WireGuard identity.
+     *
+     * If not provided, the key will be generated automatically.
+     *
+     * @schema
+     */
+    privateKey: Type.Optional(Type.String()),
+
+    /**
+     * The part of the pre-shared of the WireGuard identity.
+     *
+     * Will be generated automatically if not provided.
+     *
+     * @schema
+     */
+    presharedKeyPart: Type.Optional(Type.String()),
+  },
+
+  inputs: {
+    /**
+     * The network to use for the WireGuard identity.
+     *
+     * If not provided, the identity will use default network configuration.
+     *
+     * @schema
+     */
+    network: {
+      entity: networkEntity,
+      required: false,
+    },
+
+    /**
+     * The list of Kubernetes services to expose the WireGuard identity.
+     *
+     * Their IP addresses will be added to the `allowedIps` of the identity and passed to the node to set up network policies.
+     *
+     * @schema
+     */
+    k8sServices: {
+      entity: serviceEntity,
+      multiple: true,
+      required: false,
+    },
+
+    dnsProvider: {
+      entity: providerEntity,
+      required: false,
+    },
+  },
+
+  outputs: {
+    identity: identityEntity,
+    peer: peerEntity,
+  },
+
+  meta: {
+    description: "The WireGuard identity with the public key.",
+    primaryIcon: "simple-icons:wireguard",
+    primaryIconColor: "#88171a",
+    secondaryIcon: "mdi:account",
+  },
+
+  source: {
+    package: "@highstate/wireguard",
+    path: "identity",
+  },
+})
+
+export const node = defineUnit({
+  type: "wireguard.node",
+
+  args: {
+    appName: Type.Optional(Type.String()),
+    serviceType: Type.Optional(serviceTypeSchema),
+
+    ...sharedInterfaceArgs,
+
+    /**
+     * The external IP address of the WireGuard node.
+     *
+     * Will override the `externalIp` of the identity if provided.
+     *
+     * @schema
+     */
+    externalIp: Type.Optional(Type.String()),
+
+    /**
+     * The extra specification of the container which runs the WireGuard node.
+     *
+     * Will override any overlapping fields.
+     *
+     * @schema
+     */
+    containerSpec: Type.Optional(Type.Record(Type.String(), Type.Any())),
+  },
+
+  inputs: {
+    identity: identityEntity,
+    k8sCluster: clusterEntity,
+
+    deployment: {
+      entity: deploymentEntity,
+      required: false,
+    },
+
+    statefulSet: {
+      entity: statefulSetEntity,
+      required: false,
+    },
+
+    interface: {
+      entity: interfaceEntity,
+      required: false,
+    },
+
+    peers: {
+      entity: peerEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  outputs: {
+    deployment: {
+      entity: deploymentEntity,
+      required: false,
+    },
+
+    interface: {
+      entity: interfaceEntity,
+      required: false,
+    },
+
+    service: {
+      entity: serviceEntity,
+      required: false,
+    },
+  },
+
+  meta: {
+    description: "The WireGuard node running on the Kubernetes.",
+    primaryIcon: "simple-icons:wireguard",
+    primaryIconColor: "#88171a",
+    secondaryIcon: "mdi:server",
+  },
+
+  source: {
+    package: "@highstate/wireguard",
+    path: "node",
+  },
+})
+
+export const config = defineUnit({
+  type: "wireguard.config",
+
+  args: {
+    ...sharedInterfaceArgs,
+
+    /**
+     * The name of the "default" interface where non-tunneled traffic should go.
+     *
+     * If not provided, the config will not respect `excludedIps`.
+     *
+     * @schema
+     */
+    defaultInterface: Type.Optional(Type.String()),
+  },
+
+  inputs: {
+    identity: identityEntity,
+    peers: {
+      entity: peerEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  meta: {
+    displayName: "WireGuard Config",
+    description: "Just the WireGuard configuration for the identity and peers.",
+    primaryIcon: "simple-icons:wireguard",
+    primaryIconColor: "#88171a",
+    secondaryIcon: "mdi:settings",
+  },
+
+  source: {
+    package: "@highstate/wireguard",
+    path: "config",
+  },
+})
+
+export const configBundle = defineUnit({
+  type: "wireguard.config-bundle",
+
+  inputs: {
+    identity: identityEntity,
+    peers: {
+      entity: peerEntity,
+      multiple: true,
+    },
+    sharedPeers: {
+      entity: peerEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  meta: {
+    displayName: "WireGuard Config Bundle",
+    description: "The WireGuard configuration bundle for the identity and peers.",
+    primaryIcon: "simple-icons:wireguard",
+    primaryIconColor: "#88171a",
+    secondaryIcon: "mdi:folder-settings-variant",
+  },
+
+  source: {
+    package: "@highstate/wireguard",
+    path: "config-bundle",
+  },
+})