@kustodian/plugin-k0s 1.0.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kustodian/plugin-k0s",
+  "version": "1.0.0",
+  "description": "k0s cluster provider plugin for Kustodian",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "bun run tsc --noEmit"
+  },
+  "keywords": [
+    "kustodian",
+    "plugin",
+    "k0s",
+    "kubernetes",
+    "cluster"
+  ],
+  "author": "Luca Silverentand <luca@onezero.company>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lucasilverentand/kustodian.git",
+    "directory": "plugins/k0s"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "dependencies": {
+    "@kustodian/core": "workspace:*",
+    "@kustodian/nodes": "workspace:*",
+    "@kustodian/plugins": "workspace:*",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {}
+}

package/src/config.ts

@@ -0,0 +1,84 @@
+import type { NodeListType, NodeType, SshConfigType } from '@kustodian/nodes';
+import { get_node_ssh_config, get_primary_controller } from '@kustodian/nodes';
+
+import {
+  type K0sProviderOptionsType,
+  type K0sctlConfigType,
+  type K0sctlHostType,
+  to_k0sctl_role,
+  to_k0sctl_ssh_config,
+} from './types.js';
+
+/**
+ * Generates a k0sctl configuration from node definitions.
+ */
+export function generate_k0sctl_config(
+  node_list: NodeListType,
+  options: K0sProviderOptionsType = {},
+): K0sctlConfigType {
+  const primary_controller = get_primary_controller(node_list.nodes);
+  const default_ssh = options.default_ssh ?? node_list.ssh;
+
+  const hosts: K0sctlHostType[] = node_list.nodes.map((node) =>
+    node_to_k0sctl_host(node, default_ssh),
+  );
+
+  return {
+    apiVersion: 'k0sctl.k0sproject.io/v1beta1',
+    kind: 'Cluster',
+    metadata: {
+      name: node_list.cluster,
+    },
+    spec: {
+      k0s: build_k0s_config(primary_controller, options),
+      hosts,
+    },
+  };
+}
+
+/**
+ * Converts a node to a k0sctl host configuration.
+ */
+export function node_to_k0sctl_host(node: NodeType, default_ssh?: SshConfigType): K0sctlHostType {
+  const ssh_config = get_node_ssh_config(node, default_ssh);
+  const role = to_k0sctl_role(node.role);
+
+  return {
+    role,
+    noTaints: role === 'controller+worker' ? true : undefined,
+    openSSH: to_k0sctl_ssh_config(node.address, ssh_config),
+  };
+}
+
+/**
+ * Builds the k0s configuration block.
+ */
+function build_k0s_config(
+  primary_controller: NodeType | undefined,
+  options: K0sProviderOptionsType,
+) {
+  return {
+    version: options.k0s_version,
+    dynamicConfig: options.dynamic_config,
+    config: {
+      spec: {
+        api: primary_controller
+          ? {
+              external_address: primary_controller.address,
+            }
+          : undefined,
+        telemetry: {
+          enabled: options.telemetry_enabled ?? false,
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Serializes k0sctl config to YAML-compatible object.
+ * Removes undefined values for clean output.
+ */
+export function serialize_k0sctl_config(config: K0sctlConfigType): unknown {
+  return JSON.parse(JSON.stringify(config));
+}

package/src/executor.ts

@@ -0,0 +1,164 @@
+import * as child_process from 'node:child_process';
+import * as util from 'node:util';
+
+import { Errors, type ResultType, failure, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+
+const exec_async = util.promisify(child_process.exec);
+
+/**
+ * Result of a command execution.
+ */
+export interface CommandResultType {
+  stdout: string;
+  stderr: string;
+  exit_code: number;
+}
+
+/**
+ * Options for command execution.
+ */
+export interface ExecOptionsType {
+  cwd?: string | undefined;
+  timeout?: number | undefined;
+  env?: Record<string, string> | undefined;
+}
+
+/**
+ * Executes a shell command and returns the result.
+ */
+export async function exec_command(
+  command: string,
+  args: string[] = [],
+  options: ExecOptionsType = {},
+): Promise<ResultType<CommandResultType, KustodianErrorType>> {
+  const full_command = [command, ...args].join(' ');
+
+  try {
+    const { stdout, stderr } = await exec_async(full_command, {
+      cwd: options.cwd,
+      timeout: options.timeout,
+      env: { ...process.env, ...options.env },
+    });
+
+    return success({
+      stdout,
+      stderr,
+      exit_code: 0,
+    });
+  } catch (error) {
+    if (is_exec_error(error)) {
+      return success({
+        stdout: error.stdout ?? '',
+        stderr: error.stderr ?? '',
+        exit_code: error.code ?? 1,
+      });
+    }
+
+    return failure(Errors.unknown(`Failed to execute command: ${full_command}`, error));
+  }
+}
+
+/**
+ * Type guard for exec errors.
+ */
+function is_exec_error(
+  error: unknown,
+): error is { stdout?: string; stderr?: string; code?: number } {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    ('stdout' in error || 'stderr' in error || 'code' in error)
+  );
+}
+
+/**
+ * Checks if k0sctl is available in the system PATH.
+ */
+export async function check_k0sctl_available(): Promise<ResultType<string, KustodianErrorType>> {
+  const result = await exec_command('k0sctl', ['version']);
+
+  if (!result.success) {
+    return result;
+  }
+
+  if (result.value.exit_code !== 0) {
+    return failure(
+      Errors.bootstrap_error(
+        'k0sctl not found. Please install k0sctl: https://github.com/k0sproject/k0sctl',
+      ),
+    );
+  }
+
+  // Parse version from output (e.g., "version: v0.19.4")
+  const version_match = result.value.stdout.match(/version:\s*v?([\d.]+)/);
+  const version = version_match?.[1] ?? 'unknown';
+
+  return success(version);
+}
+
+/**
+ * Runs k0sctl apply with the given config file.
+ */
+export async function k0sctl_apply(
+  config_path: string,
+  options: ExecOptionsType = {},
+): Promise<ResultType<CommandResultType, KustodianErrorType>> {
+  const result = await exec_command('k0sctl', ['apply', '--config', config_path], options);
+
+  if (!result.success) {
+    return result;
+  }
+
+  if (result.value.exit_code !== 0) {
+    return failure(Errors.bootstrap_error(`k0sctl apply failed: ${result.value.stderr}`));
+  }
+
+  return result;
+}
+
+/**
+ * Runs k0sctl kubeconfig to get the cluster kubeconfig.
+ */
+export async function k0sctl_kubeconfig(
+  config_path: string,
+  options: ExecOptionsType = {},
+): Promise<ResultType<string, KustodianErrorType>> {
+  const result = await exec_command('k0sctl', ['kubeconfig', '--config', config_path], options);
+
+  if (!result.success) {
+    return result;
+  }
+
+  if (result.value.exit_code !== 0) {
+    return failure(Errors.bootstrap_error(`k0sctl kubeconfig failed: ${result.value.stderr}`));
+  }
+
+  return success(result.value.stdout);
+}
+
+/**
+ * Runs k0sctl reset to tear down the cluster.
+ */
+export async function k0sctl_reset(
+  config_path: string,
+  force = false,
+  options: ExecOptionsType = {},
+): Promise<ResultType<CommandResultType, KustodianErrorType>> {
+  const args = ['reset', '--config', config_path];
+  if (force) {
+    args.push('--force');
+  }
+
+  const result = await exec_command('k0sctl', args, options);
+
+  if (!result.success) {
+    return result;
+  }
+
+  if (result.value.exit_code !== 0) {
+    return failure(Errors.bootstrap_error(`k0sctl reset failed: ${result.value.stderr}`));
+  }
+
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+// Plugin exports
+export { create_k0s_plugin, plugin } from './plugin.js';
+export { plugin as default } from './plugin.js';
+
+// Provider exports
+export { create_k0s_provider, validate_k0s_config } from './provider.js';
+
+// Config generation
+export { generate_k0sctl_config, node_to_k0sctl_host, serialize_k0sctl_config } from './config.js';
+
+// Executor
+export {
+  check_k0sctl_available,
+  exec_command,
+  k0sctl_apply,
+  k0sctl_kubeconfig,
+  k0sctl_reset,
+  type CommandResultType,
+  type ExecOptionsType,
+} from './executor.js';
+
+// Types
+export {
+  to_k0sctl_role,
+  to_k0sctl_ssh_config,
+  type K0sApiConfigType,
+  type K0sConfigSpecType,
+  type K0sctlConfigType,
+  type K0sctlHostRoleType,
+  type K0sctlHostType,
+  type K0sctlK0sConfigType,
+  type K0sctlMetadataType,
+  type K0sctlSpecType,
+  type K0sctlSshConfigType,
+  type K0sProviderOptionsType,
+  type K0sTelemetryConfigType,
+  type K0sVersionType,
+} from './types.js';

package/src/plugin.ts

@@ -0,0 +1,82 @@
+import { success } from '@kustodian/core';
+import type {
+  CommandType,
+  HookContextType,
+  HookEventType,
+  KustodianPluginType,
+  PluginCommandContributionType,
+  PluginHookContributionType,
+  PluginManifestType,
+} from '@kustodian/plugins';
+
+import { create_k0s_provider } from './provider.js';
+import type { K0sProviderOptionsType } from './types.js';
+
+/**
+ * k0s plugin manifest.
+ */
+const manifest: PluginManifestType = {
+  name: '@kustodian/plugin-k0s',
+  version: '0.1.0',
+  description: 'k0s cluster provider for Kustodian',
+  capabilities: ['commands', 'hooks'],
+};
+
+/**
+ * Creates the k0s plugin.
+ */
+export function create_k0s_plugin(options: K0sProviderOptionsType = {}): KustodianPluginType {
+  const provider = create_k0s_provider(options);
+
+  return {
+    manifest,
+
+    async activate() {
+      return success(undefined);
+    },
+
+    async deactivate() {
+      return success(undefined);
+    },
+
+    get_commands(): PluginCommandContributionType[] {
+      const k0s_command: CommandType = {
+        name: 'k0s',
+        description: 'k0s cluster management commands',
+        subcommands: [
+          {
+            name: 'info',
+            description: 'Show k0s provider information',
+            handler: async () => {
+              console.log('k0s cluster provider');
+              console.log('Provider name:', provider.name);
+              return success(undefined);
+            },
+          },
+        ],
+      };
+      return [{ command: k0s_command }];
+    },
+
+    get_hooks(): PluginHookContributionType[] {
+      return [
+        {
+          event: 'bootstrap:before',
+          priority: 100,
+          handler: async (_event: HookEventType, ctx: HookContextType) => {
+            // Could add k0s-specific pre-bootstrap validation here
+            return success(ctx);
+          },
+        },
+      ];
+    },
+  };
+}
+
+/**
+ * Default plugin export.
+ * This is loaded when the plugin is discovered and imported.
+ */
+export const plugin = create_k0s_plugin();
+
+export default plugin;

package/src/provider.ts

@@ -0,0 +1,176 @@
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { Errors, type ResultType, failure, is_success, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import type { NodeListType } from '@kustodian/nodes';
+import { get_controllers } from '@kustodian/nodes';
+import type {
+  BootstrapOptionsType,
+  ClusterProviderType,
+  ResetOptionsType,
+} from '@kustodian/plugins';
+import YAML from 'yaml';
+
+import { generate_k0sctl_config, serialize_k0sctl_config } from './config.js';
+import {
+  check_k0sctl_available,
+  k0sctl_apply,
+  k0sctl_kubeconfig,
+  k0sctl_reset,
+} from './executor.js';
+import type { K0sProviderOptionsType } from './types.js';
+
+/**
+ * Validates k0s cluster configuration.
+ */
+export function validate_k0s_config(node_list: NodeListType): ResultType<void, KustodianErrorType> {
+  const controllers = get_controllers(node_list.nodes);
+
+  if (controllers.length === 0) {
+    return failure(Errors.validation_error('k0s cluster requires at least one controller node'));
+  }
+
+  // Validate SSH configuration is present
+  for (const node of node_list.nodes) {
+    const ssh = node.ssh ?? node_list.ssh;
+    if (!ssh?.user) {
+      return failure(
+        Errors.validation_error(`Node '${node.name}' requires SSH user configuration`),
+      );
+    }
+  }
+
+  return success(undefined);
+}
+
+/**
+ * Writes k0sctl config to a temporary file.
+ */
+async function write_k0sctl_config(
+  config: unknown,
+  cluster_name: string,
+): Promise<ResultType<string, KustodianErrorType>> {
+  const temp_dir = os.tmpdir();
+  const config_path = path.join(temp_dir, `k0sctl-${cluster_name}.yaml`);
+
+  try {
+    const yaml_content = YAML.stringify(config);
+    await fs.writeFile(config_path, yaml_content, 'utf-8');
+    return success(config_path);
+  } catch (error) {
+    return failure(Errors.file_write_error(config_path, error));
+  }
+}
+
+/**
+ * Creates the k0s cluster provider.
+ */
+export function create_k0s_provider(options: K0sProviderOptionsType = {}): ClusterProviderType {
+  let config_path: string | undefined;
+
+  return {
+    name: 'k0s',
+
+    validate(node_list: NodeListType): ResultType<void, KustodianErrorType> {
+      return validate_k0s_config(node_list);
+    },
+
+    async install(
+      node_list: NodeListType,
+      bootstrap_options: BootstrapOptionsType,
+    ): Promise<ResultType<void, KustodianErrorType>> {
+      // Check k0sctl is available
+      const k0sctl_check = await check_k0sctl_available();
+      if (!is_success(k0sctl_check)) {
+        return k0sctl_check;
+      }
+
+      // Generate k0sctl config
+      const k0sctl_config = generate_k0sctl_config(node_list, options);
+      const serialized = serialize_k0sctl_config(k0sctl_config);
+
+      // Write config to temp file
+      const write_result = await write_k0sctl_config(serialized, node_list.cluster);
+      if (!is_success(write_result)) {
+        return write_result;
+      }
+
+      config_path = write_result.value;
+
+      // Skip actual installation in dry run mode
+      if (bootstrap_options.dry_run) {
+        return success(undefined);
+      }
+
+      // Run k0sctl apply
+      const apply_result = await k0sctl_apply(config_path, {
+        timeout: bootstrap_options.timeout,
+      });
+
+      if (!is_success(apply_result)) {
+        return apply_result;
+      }
+
+      return success(undefined);
+    },
+
+    async get_kubeconfig(node_list: NodeListType): Promise<ResultType<string, KustodianErrorType>> {
+      // If we have a config path from install, use it
+      if (config_path) {
+        return k0sctl_kubeconfig(config_path);
+      }
+
+      // Otherwise, generate a new config
+      const k0sctl_config = generate_k0sctl_config(node_list, options);
+      const serialized = serialize_k0sctl_config(k0sctl_config);
+
+      const write_result = await write_k0sctl_config(serialized, node_list.cluster);
+      if (!is_success(write_result)) {
+        return write_result;
+      }
+
+      config_path = write_result.value;
+      return k0sctl_kubeconfig(config_path);
+    },
+
+    async reset(
+      node_list: NodeListType,
+      reset_options: ResetOptionsType,
+    ): Promise<ResultType<void, KustodianErrorType>> {
+      // Check k0sctl is available
+      const k0sctl_check = await check_k0sctl_available();
+      if (!is_success(k0sctl_check)) {
+        return k0sctl_check;
+      }
+
+      // Generate k0sctl config if we don't have one
+      if (!config_path) {
+        const k0sctl_config = generate_k0sctl_config(node_list, options);
+        const serialized = serialize_k0sctl_config(k0sctl_config);
+
+        const write_result = await write_k0sctl_config(serialized, node_list.cluster);
+        if (!is_success(write_result)) {
+          return write_result;
+        }
+
+        config_path = write_result.value;
+      }
+
+      // Skip actual reset in dry run mode
+      if (reset_options.dry_run) {
+        return success(undefined);
+      }
+
+      // Run k0sctl reset
+      const reset_result = await k0sctl_reset(config_path, reset_options.force ?? false);
+
+      if (!is_success(reset_result)) {
+        return reset_result;
+      }
+
+      return success(undefined);
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,132 @@
+import type { SshConfigType } from '@kustodian/nodes';
+
+/**
+ * k0s version configuration.
+ */
+export interface K0sVersionType {
+  version?: string;
+  dynamic_config?: boolean;
+}
+
+/**
+ * k0s cluster API configuration.
+ */
+export interface K0sApiConfigType {
+  external_address?: string | undefined;
+  sans?: string[] | undefined;
+}
+
+/**
+ * k0s telemetry configuration.
+ */
+export interface K0sTelemetryConfigType {
+  enabled: boolean;
+}
+
+/**
+ * k0s configuration spec.
+ */
+export interface K0sConfigSpecType {
+  api?: K0sApiConfigType | undefined;
+  telemetry?: K0sTelemetryConfigType | undefined;
+}
+
+/**
+ * k0s host role in k0sctl configuration.
+ */
+export type K0sctlHostRoleType = 'controller' | 'worker' | 'controller+worker' | 'single';
+
+/**
+ * SSH configuration for k0sctl.
+ */
+export interface K0sctlSshConfigType {
+  address: string;
+  user: string;
+  keyPath?: string | undefined;
+  port?: number | undefined;
+}
+
+/**
+ * Host configuration for k0sctl.
+ */
+export interface K0sctlHostType {
+  role: K0sctlHostRoleType;
+  noTaints?: boolean | undefined;
+  openSSH: K0sctlSshConfigType;
+}
+
+/**
+ * k0s configuration block in k0sctl.
+ */
+export interface K0sctlK0sConfigType {
+  version?: string | undefined;
+  dynamicConfig?: boolean | undefined;
+  config?:
+    | {
+        spec?: K0sConfigSpecType | undefined;
+      }
+    | undefined;
+}
+
+/**
+ * k0sctl cluster spec.
+ */
+export interface K0sctlSpecType {
+  k0s?: K0sctlK0sConfigType | undefined;
+  hosts: K0sctlHostType[];
+}
+
+/**
+ * k0sctl cluster metadata.
+ */
+export interface K0sctlMetadataType {
+  name: string;
+}
+
+/**
+ * Complete k0sctl configuration.
+ */
+export interface K0sctlConfigType {
+  apiVersion: 'k0sctl.k0sproject.io/v1beta1';
+  kind: 'Cluster';
+  metadata: K0sctlMetadataType;
+  spec: K0sctlSpecType;
+}
+
+/**
+ * k0s provider options.
+ */
+export interface K0sProviderOptionsType {
+  k0s_version?: string | undefined;
+  telemetry_enabled?: boolean | undefined;
+  dynamic_config?: boolean | undefined;
+  default_ssh?: SshConfigType | undefined;
+}
+
+/**
+ * Converts internal SSH config to k0sctl SSH config format.
+ */
+export function to_k0sctl_ssh_config(address: string, ssh?: SshConfigType): K0sctlSshConfigType {
+  return {
+    address,
+    user: ssh?.user ?? 'root',
+    keyPath: ssh?.key_path,
+    port: ssh?.port,
+  };
+}
+
+/**
+ * Converts internal role to k0sctl role.
+ */
+export function to_k0sctl_role(role: string): K0sctlHostRoleType {
+  switch (role) {
+    case 'controller':
+      return 'controller';
+    case 'worker':
+      return 'worker';
+    case 'controller+worker':
+      return 'controller+worker';
+    default:
+      return 'worker';
+  }
+}