alchemy-hetzner-k3s 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright 2026 toolbar23
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

package/README.md

@@ -0,0 +1,9 @@
+# alchemy-hetzner-k3s
+
+Production-oriented Hetzner K3s clusters that implement Alchemy's
+`Kubernetes.ClusterLike` contract.
+
+See the
+[repository documentation](https://github.com/toolbar23/alchemy-k3s#hetzner-cluster)
+for configuration, Secret encryption migration and recovery, encrypted state
+requirements, Kubernetes Secret handling, upgrades, and deletion details.

package/dist/index.d.mts

@@ -0,0 +1,263 @@
+import * as Hetzner from "alchemy/Hetzner";
+import { Resource, Stage } from "alchemy";
+import * as Effect from "effect/Effect";
+import * as Provider from "alchemy/Provider";
+import * as Redacted from "effect/Redacted";
+import * as Layer from "effect/Layer";
+import * as Kubernetes from "alchemy/Kubernetes";
+import { S3BucketAccess } from "alchemy-s3-access";
+//#region src/providers.d.ts
+declare const Providers_base: Provider.ProviderCollection<Providers, "HetznerK3s">;
+declare class Providers extends Providers_base {}
+declare const providers: () => Layer.Layer<Providers, never, never>;
+//#endregion
+//#region ../shared/src/types.d.ts
+type DayOfWeek = "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday";
+interface UpdateWindow {
+  /** Days on which an update may start. */
+  days: DayOfWeek[];
+  /** Inclusive start in 24-hour HH:mm form. */
+  startTime: `${number}:${number}`;
+  /** Exclusive end in 24-hour HH:mm form. */
+  endTime: `${number}:${number}`;
+  /** IANA time-zone name, for example Europe/Berlin. */
+  timeZone: string;
+}
+interface K3sDefinition {
+  /** A pinned Kubernetes minor channel such as v1.35. */
+  channel: `v1.${number}`;
+  /** Required maintenance window for automatic patch updates. */
+  updateWindow: UpdateWindow;
+  clusterCidr?: string;
+  serviceCidr?: string;
+  clusterDns?: string;
+  addons?: {
+    traefik?: boolean;
+    metricsServer?: boolean;
+  };
+  /** K3s' built-in Flannel data plane. @default "vxlan" */
+  flannelBackend?: "vxlan" | "wireguard-native";
+}
+interface NormalizedK3sDefinition {
+  channel: `v1.${number}`;
+  updateWindow: UpdateWindow;
+  clusterCidr: string;
+  serviceCidr: string;
+  clusterDns: string;
+  addons: {
+    traefik: boolean;
+    metricsServer: boolean;
+  };
+  flannelBackend: "vxlan" | "wireguard-native";
+}
+interface ClusterVersion {
+  node: string;
+  version: string;
+}
+//#endregion
+//#region src/types.d.ts
+interface WorkerPool {
+  name: string;
+  serverType: string;
+  location: string;
+  count: number;
+  /** Changing this value performs a create-first rolling replacement. */
+  replacementToken?: string;
+  labels?: Record<string, string>;
+  taints?: string[];
+}
+interface EtcdSnapshotConfig {
+  /** K3s cron expression. @default "0 * * * *" */
+  schedule?: string;
+  /** @default 24 */
+  retention?: number;
+  /** Prefix owned by this cluster inside the bucket. */
+  folder?: string;
+  /** The bucket is external and must outlive the cluster. */
+  s3?: S3BucketAccess;
+}
+type RecoveryFailurePoint = "after-server-creation" | "after-snapshot-selection" | "after-snapshot-download" | "after-etcd-reset" | "after-normal-start" | "after-state-persistence";
+interface InitialControlPlaneRecovery {
+  /** Explicitly permits a replacement server to restore the old cluster. */
+  restoreOnInitialControlPlaneReplacement: true;
+  /** Reject snapshots older than this many seconds. */
+  maximumSnapshotAge: number;
+  /** Changing this value deliberately replaces only control plane 1. */
+  replacementToken?: string;
+  /** Test-only interruption; repeat the deploy without it to resume. */
+  failureInjection?: RecoveryFailurePoint;
+}
+interface ClusterProps {
+  k3s: K3sDefinition;
+  controlPlane: {
+    count: 1 | 3;
+    serverType: string;
+    /** One location shared by all servers, or exactly one per server. */
+    locations: string | string[];
+  };
+  workerPools: WorkerPool[];
+  state?: {
+    /** Assert provider-side encryption for an unrecognized remote state ID. */
+    encryptionAtRestConfirmed?: boolean;
+  };
+  ssh: {
+    allowedCidrs: string[];
+    /** Verify that this deploy runner is included in allowedCidrs. @default true */
+    validateCurrentIp?: boolean;
+    /** SSH uses the private network and public node ingress is closed. */
+    privateOnly?: boolean;
+  };
+  apiLoadBalancer?: {
+    type?: string;
+    location?: string;
+  };
+  networkCidr?: string;
+  /** @default false */
+  scheduleWorkloadsOnControlPlane?: boolean;
+  /** @default true */
+  protectAgainstDeletion?: boolean;
+  etcdSnapshots?: EtcdSnapshotConfig;
+  recovery?: InitialControlPlaneRecovery;
+  apiAuditLog?: {
+    /** @default true */
+    enabled?: boolean;
+    /** @default 30 */
+    maximumAgeDays?: number;
+    /** @default 10 */
+    maximumBackups?: number;
+    /** @default 100 */
+    maximumSizeMegabytes?: number;
+  };
+  secretsEncryption?: {
+    /**
+     * Required once to encrypt an existing cluster or migrate its provider
+     * from aescbc to secretbox. New clusters use encryption without this flag.
+     * @default false
+     */
+    migrateExisting?: boolean;
+    /** Controlled recovery testing; the next deploy resumes after removal. */
+    failureInjection?: SecretsEncryptionFailurePoint;
+    /** Change this opaque value to perform one dynamic key rotation. */
+    keyRotationToken?: string;
+  };
+}
+type SecretsEncryptionFailurePoint = "after-snapshot" | "after-enable" | "after-control-plane-restarts" | "after-rotate" | "after-final-restarts";
+interface ServerReference {
+  id: number;
+  serverId: number;
+  name: string;
+  ipv4?: string;
+  privateKey?: Redacted.Redacted<string>;
+  /** Address used by the deploy runner (public or private). */
+  managementAddress?: string;
+  /** Pinned OpenSSH host public key created with the server. */
+  hostPublicKey?: string;
+}
+interface NodeReference {
+  logicalName: string;
+  name: string;
+  role: "server" | "agent";
+  serverId: number;
+  privateIp: string;
+  version: string;
+  token?: Redacted.Redacted<string>;
+  /** Kubernetes kube-system UID, persisted for S3 snapshot identity checks. */
+  clusterId?: string;
+  /** Old node object retained until cluster-wide recovery is healthy. */
+  obsoleteNodeName?: string;
+  recovery?: {
+    restoredSnapshot: string;
+    snapshotCreatedAt: string;
+    completedAt: string;
+  };
+  server: ServerReference;
+}
+interface NodeProps {
+  name: string;
+  role: "server" | "agent";
+  initialServer: boolean;
+  /** Internal revision that re-runs bootstrap when node configuration changes. */
+  bootstrapRevision: number;
+  server: ServerReference;
+  bootstrap?: NodeReference;
+  k3s: NormalizedK3sDefinition;
+  networkCidr: string;
+  apiEndpoint: string;
+  scheduleWorkloadsOnControlPlane: boolean;
+  labels?: Record<string, string>;
+  taints?: string[];
+  etcdSnapshots: {
+    schedule: string;
+    retention: number;
+    folder?: string;
+    s3?: S3BucketAccess;
+  };
+  hcloudToken: Redacted.Redacted<string>;
+  privateManagement: boolean;
+  stateId: string;
+  recovery?: InitialControlPlaneRecovery;
+  apiAuditLog: {
+    enabled: boolean;
+    maximumAgeDays: number;
+    maximumBackups: number;
+    maximumSizeMegabytes: number;
+  };
+  secretsEncryption?: {
+    migrateExisting: boolean;
+    failureInjection?: SecretsEncryptionFailurePoint;
+  };
+}
+type NodeResource = Resource<"Hetzner.K3s.Node", NodeProps, NodeReference, never, Providers>;
+interface ClusterStateProps {
+  k3s: NormalizedK3sDefinition;
+  /** Pure dependency edges that hold cluster readiness behind every node. */
+  nodeServerIds: number[];
+  nodeNames: string[];
+  controlPlanes: NodeReference[];
+  loadBalancer: {
+    ipv4: string | null;
+  };
+  hcloudToken: Redacted.Redacted<string>;
+  networkName: string;
+  networkZone: string;
+  protectAgainstDeletion: boolean;
+  topologyFingerprint: string;
+  secretsEncryption: {
+    failureInjection?: SecretsEncryptionFailurePoint;
+    keyRotationToken?: string;
+  };
+  obsoleteNodeNames: string[];
+}
+interface ClusterAttributes {
+  connection: Kubernetes.Connection;
+  endpoint: string;
+  kubeconfigPath: string;
+  currentVersions: ClusterVersion[];
+  channel: `v1.${number}`;
+  topologyFingerprint: string;
+  secretsEncryption: {
+    enabled: boolean;
+    provider: "secretbox" | "aescbc" | undefined;
+    stage: string | undefined;
+    hashesMatch: boolean;
+  };
+  recovery?: {
+    restoredSnapshot: string;
+    snapshotCreatedAt: string;
+    completedAt: string;
+  };
+}
+type ClusterResource = Resource<"Hetzner.K3s.Cluster", ClusterStateProps, ClusterAttributes, never, Providers>;
+/** Public return shape. It is directly accepted by Kubernetes resource inputs. */
+type Cluster$1 = ClusterResource;
+//#endregion
+//#region src/cluster.d.ts
+declare const Cluster: (id: string, props: ClusterProps) => Effect.Effect<ClusterResource, never, Providers | Hetzner.Providers | Stage>;
+//#endregion
+//#region src/cluster-state.d.ts
+declare const ClusterState: import("alchemy").ResourceClass<ClusterResource>;
+//#endregion
+//#region src/node.d.ts
+declare const Node: import("alchemy").ResourceClass<NodeResource>;
+//#endregion
+export { Cluster, type ClusterAttributes, type Cluster$1 as ClusterInstance, type ClusterProps, ClusterState, type EtcdSnapshotConfig, type InitialControlPlaneRecovery, type K3sDefinition, Node, type NodeReference, Providers, type RecoveryFailurePoint, type WorkerPool, providers };