feat: allow using existing SSH key instead of creating a new one

Add existing_ssh_key_name config option to networking.ssh that lets
users specify the name of an existing SSH key in the Hetzner project.
When set, the key is validated (exists in Hetzner, fingerprint matches
local public key) and used instead of creating a new one. The key is
also not deleted on cluster deletion. Bump version to 2.5.0.

Author: vitobotta

README.md

@@ -147,7 +147,7 @@ brew install vitobotta/tap/hetzner_k3s
 
 **Linux binary (amd64):**
 ```bash
-wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.4.9/hetzner-k3s-linux-amd64
+wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.5.0/hetzner-k3s-linux-amd64
 chmod +x hetzner-k3s-linux-amd64
 sudo mv hetzner-k3s-linux-amd64 /usr/local/bin/hetzner-k3s
 ```

docs/Creating_a_cluster.md

@@ -22,6 +22,7 @@ networking:
     use_private_ip: false # set to true to connect to nodes via their private IPs
     public_key_path: "~/.ssh/id_ed25519.pub"
     private_key_path: "~/.ssh/id_ed25519"
+    # existing_ssh_key_name: "my-existing-key" # optional: use an existing SSH key in Hetzner instead of creating a new one
   allowed_networks:
     ssh:
       - 0.0.0.0/0
@@ -369,7 +370,7 @@ The `create` command can be run multiple times with the same configuration witho
 - The `networking`.`allowed_networks`.`api` setting specifies which networks can access the Kubernetes API. This works with both single-master and multi-master clusters, but only when `create_load_balancer_for_the_kubernetes_api` is disabled. If the API load balancer is enabled, Hetzner's firewalls do not yet support load balancers, so the API would be exposed to the public internet regardless of the allowed networks configuration.
 - If you enable autoscaling for a nodepool, avoid changing this setting later, as it can cause issues with the autoscaler.
 - Autoscaling is only supported with Ubuntu or other default images, not snapshots.
-- If you already have SSH keys in your Hetzner project, it's best to use a different key for your cluster—unless there's already a key with the same name and fingerprint as the one in your config file.  Hetzner doesn't allow two keys with the same fingerprint in one project. So if you've already added the key from your config but under a different name, Hetzner won't let you add it again. In that case, hetzner-k3s will skip creating the key and won't inject any SSH key into the cluster nodes.  Without an SSH key, Hetzner sets up the nodes with password login instead. That means you'll get an email for each node with its root password. Managing several nodes this way can get tricky. To avoid this, just use a new keypair for your cluster—unless the project already has a key that matches both the name and fingerprint in your config.
+- If you already have SSH keys in your Hetzner project, it's best to use a different key for your cluster—unless there's already a key with the same name and fingerprint as the one in your config file.  Hetzner doesn't allow two keys with the same fingerprint in one project. So if you've already added the key from your config but under a different name, Hetzner won't let you add it again. In that case, hetzner-k3s will skip creating the key and won't inject any SSH key into the cluster nodes.  Without an SSH key, Hetzner sets up the nodes with password login instead. That means you'll get an email for each node with its root password. Managing several nodes this way can get tricky. To avoid this, you can either use a new keypair for your cluster, or set `existing_ssh_key_name` in the SSH config to reference the existing key by name. When using `existing_ssh_key_name`, hetzner-k3s will use the specified key instead of creating a new one, and it won't delete the key when you delete the cluster.
 - SSH keys with passphrases can only be used if you set `networking`.`ssh`.`use_ssh_agent` to `true` and use an SSH agent to access your key. For example, on macOS, you can start an agent like this:
 
 ```bash

docs/Installation.md

@@ -40,14 +40,14 @@ If you prefer not to use Homebrew, install the required dependencies first:
 
 **Apple Silicon:**
 ```bash
-wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.4.9/hetzner-k3s-macos-arm64
+wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.5.0/hetzner-k3s-macos-arm64
 chmod +x hetzner-k3s-macos-arm64
 sudo mv hetzner-k3s-macos-arm64 /usr/local/bin/hetzner-k3s
 ```
 
 **Intel:**
 ```bash
-wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.4.9/hetzner-k3s-macos-amd64
+wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.5.0/hetzner-k3s-macos-amd64
 chmod +x hetzner-k3s-macos-amd64
 sudo mv hetzner-k3s-macos-amd64 /usr/local/bin/hetzner-k3s
 ```
@@ -67,15 +67,15 @@ brew install vitobotta/tap/hetzner_k3s
 ### amd64 (x86_64)
 
 ```bash
-wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.4.9/hetzner-k3s-linux-amd64
+wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.5.0/hetzner-k3s-linux-amd64
 chmod +x hetzner-k3s-linux-amd64
 sudo mv hetzner-k3s-linux-amd64 /usr/local/bin/hetzner-k3s
 ```
 
 ### arm64 (ARM)
 
 ```bash
-wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.4.9/hetzner-k3s-linux-arm64
+wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.5.0/hetzner-k3s-linux-arm64
 chmod +x hetzner-k3s-linux-arm64
 sudo mv hetzner-k3s-linux-arm64 /usr/local/bin/hetzner-k3s
 ```

src/cluster/delete.cr

@@ -118,8 +118,9 @@ class Cluster::Delete
   private def delete_ssh_key
     Hetzner::SSHKey::Delete.new(
       hetzner_client: hetzner_client,
-      ssh_key_name: settings.cluster_name,
-      public_ssh_key_path: settings.networking.ssh.public_key_path
+      ssh_key_name: settings.networking.ssh.ssh_key_name(settings.cluster_name),
+      public_ssh_key_path: settings.networking.ssh.public_key_path,
+      using_existing_ssh_key: settings.networking.ssh.using_existing_ssh_key?
     ).run
   end
 

src/configuration/models/networking_config/ssh.cr

@@ -7,6 +7,7 @@ class Configuration::Models::NetworkingConfig::SSH
   getter use_private_ip : Bool = false
   getter private_key_path : String = "~/.ssh/id_rsa"
   getter public_key_path : String = "~/.ssh/id_rsa.pub"
+  getter existing_ssh_key_name : String = ""
 
   def initialize
   end
@@ -19,6 +20,14 @@ class Configuration::Models::NetworkingConfig::SSH
     absolute_path(@public_key_path)
   end
 
+  def ssh_key_name(cluster_name : String) : String
+    @existing_ssh_key_name.empty? ? cluster_name : @existing_ssh_key_name
+  end
+
+  def using_existing_ssh_key? : Bool
+    !@existing_ssh_key_name.empty?
+  end
+
   private def absolute_path(path)
     home_dir = ENV["HOME"]? || raise "HOME environment variable not set"
     File.expand_path(path.sub("~/", "#{home_dir}/"))

src/configuration/validators/autoscaler_ssh_key.cr

@@ -13,17 +13,19 @@ class Configuration::Validators::AutoscalerSSHKey
   def validate
     return unless autoscaling_in_use?
 
+    ssh_key_name = settings.networking.ssh.ssh_key_name(settings.cluster_name)
+
     begin
-      existing_ssh_key = Hetzner::SSHKey::Find.new(hetzner_client, settings.cluster_name, settings.networking.ssh.public_key_path).run
+      existing_ssh_key = Hetzner::SSHKey::Find.new(hetzner_client, ssh_key_name, settings.networking.ssh.public_key_path).run
     rescue ex
       errors << "Unable to verify SSH key for autoscaler: #{ex.message}"
       return
     end
 
     return unless existing_ssh_key
-    return if existing_ssh_key.name == settings.cluster_name
+    return if existing_ssh_key.name == ssh_key_name
 
-    errors << "Cluster autoscaler requires an SSH key named '#{settings.cluster_name}' in Hetzner. A key with the same fingerprint exists as '#{existing_ssh_key.name}', so hetzner-k3s will not create '#{settings.cluster_name}'. Autoscaled nodes will be created without SSH keys. Rename or delete the existing key, or change cluster_name."
+    errors << "Cluster autoscaler requires an SSH key named '#{ssh_key_name}' in Hetzner. A key with the same fingerprint exists as '#{existing_ssh_key.name}', so hetzner-k3s will not create '#{ssh_key_name}'. Autoscaled nodes will be created without SSH keys. Rename or delete the existing key, or use the existing_ssh_key_name setting to reference it."
   end
 
   private def autoscaling_in_use?

src/configuration/validators/networking_config/ssh.cr

@@ -15,7 +15,12 @@ class Configuration::Validators::NetworkingConfig::SSH
   def validate
     validate_path(errors, ssh.private_key_path, "private")
     validate_path(errors, ssh.public_key_path, "public")
-    validate_ssh_key_fingerprint(errors, hetzner_client, cluster_name)
+
+    if ssh.using_existing_ssh_key?
+      validate_existing_ssh_key(errors, hetzner_client)
+    else
+      validate_ssh_key_fingerprint(errors, hetzner_client, cluster_name)
+    end
   end
 
   private def validate_path(errors, path, key_type)
@@ -36,13 +41,41 @@ class Configuration::Validators::NetworkingConfig::SSH
     end
   end
 
+  private def validate_existing_ssh_key(errors, hetzner_client)
+    unless File.exists?(ssh.public_key_path)
+      errors << "public_key_path is required to validate the fingerprint of existing_ssh_key_name '#{ssh.existing_ssh_key_name}'"
+      return
+    end
+
+    begin
+      existing_ssh_key = Hetzner::SSHKey::Find.new(hetzner_client.not_nil!, ssh.existing_ssh_key_name, ssh.public_key_path).run
+    rescue e
+      errors << "Unable to verify existing SSH key '#{ssh.existing_ssh_key_name}': #{e.message}"
+      return
+    end
+
+    unless existing_ssh_key
+      errors << "The SSH key '#{ssh.existing_ssh_key_name}' specified in existing_ssh_key_name does not exist in Hetzner"
+      return
+    end
+
+    unless existing_ssh_key.name == ssh.existing_ssh_key_name
+      errors << "SSH key mismatch: the key '#{ssh.existing_ssh_key_name}' was not found by name in Hetzner. A key with the same fingerprint exists as '#{existing_ssh_key.name}', but existing_ssh_key_name must match the key name exactly."
+      return
+    end
+
+    config_fingerprint = Util::SSH.calculate_fingerprint(ssh.public_key_path)
+
+    if existing_ssh_key.fingerprint != config_fingerprint
+      errors << "SSH key fingerprint mismatch: the existing key '#{ssh.existing_ssh_key_name}' in Hetzner has a different fingerprint than the local public key at '#{ssh.public_key_path}'. Please ensure the public_key_path points to the corresponding public key."
+    end
+  end
+
   private def find_existing_ssh_key(hetzner_client, cluster_name)
     return nil unless hetzner_client && cluster_name
     ssh_key_finder = Hetzner::SSHKey::Find.new(hetzner_client, cluster_name, ssh.public_key_path)
     ssh_key_finder.run
   rescue e
-    # If we can't fetch existing SSH keys, we'll skip validation
-    # This allows the create command to proceed and handle any API errors
     nil
   end
 end

src/hetzner-k3s.cr

@@ -10,7 +10,7 @@ require "./cluster/run"
 
 module Hetzner::K3s
   class CLI < Admiral::Command
-    VERSION = "2.4.9"
+    VERSION = "2.5.0"
 
     def self.print_banner
       puts "╭─────────────────────────────────────────╮".colorize(:green)

src/hetzner/ssh_key/create.cr

@@ -12,7 +12,7 @@ class Hetzner::SSHKey::Create
   getter ssh_key_finder : Hetzner::SSHKey::Find
 
   def initialize(@hetzner_client, @settings)
-    @ssh_key_name = settings.cluster_name
+    @ssh_key_name = settings.networking.ssh.ssh_key_name(settings.cluster_name)
     @public_ssh_key_path = settings.networking.ssh.public_key_path
     @ssh_key_finder = Hetzner::SSHKey::Find.new(hetzner_client, ssh_key_name, public_ssh_key_path)
   end
@@ -22,6 +22,11 @@ class Hetzner::SSHKey::Create
 
     return ssh_key if ssh_key
 
+    if settings.networking.ssh.using_existing_ssh_key?
+      STDERR.puts "[#{default_log_prefix}] Existing SSH key '#{ssh_key_name}' not found in Hetzner"
+      exit 1
+    end
+
     log_line "Creating SSH key..."
     create_ssh_key
     log_line "...SSH key created"

src/hetzner/ssh_key/delete.cr

@@ -8,12 +8,15 @@ class Hetzner::SSHKey::Delete
   getter hetzner_client : Hetzner::Client
   getter ssh_key_name : String
   getter ssh_key_finder : Hetzner::SSHKey::Find
+  getter using_existing_ssh_key : Bool
 
-  def initialize(@hetzner_client, @ssh_key_name, public_ssh_key_path)
+  def initialize(@hetzner_client, @ssh_key_name, public_ssh_key_path, @using_existing_ssh_key = false)
     @ssh_key_finder = Hetzner::SSHKey::Find.new(hetzner_client, ssh_key_name, public_ssh_key_path)
   end
 
   def run
+    return handle_existing_ssh_key_skip if using_existing_ssh_key
+
     ssh_key = ssh_key_finder.run
 
     return handle_no_ssh_key unless ssh_key
@@ -23,6 +26,11 @@ class Hetzner::SSHKey::Delete
     ssh_key_name
   end
 
+  private def handle_existing_ssh_key_skip
+    log_line "Using existing SSH key '#{ssh_key_name}', skipping delete"
+    ssh_key_name
+  end
+
   private def handle_no_ssh_key
     log_line "SSH key does not exist, skipping delete"
     ssh_key_name