puppet-pubkey

Puppet module that allows generating ssh key pair and exchanging the public key via exported Puppet resource.

Usage

As simple as:

pubkey::ssh { 'bob_rsa': }

will generate /home/bob/.ssh/id_rsa key with default size and export the public key /home/bob/.ssh/id_rsa.pub.

Auto-detection expects name in format {username}_{type}.

Parameters

generate Whether missing key should be generated (default: true)
user account name under which we will store the ssh key
type ssh key type one of: dsa, rsa, ecdsa, ed25519, ecdsa-sk, ed25519-sk
home user's home directory, assuming .ssh is located in $HOME/.ssh
prefix custom key file prefix for the ssh key file (default: id)
comment ssh key's comment
size number of bits for generated ssh key
tags optional tags added to the exported key
export_key whether export the generated public key as ssh_authorized_key (default: true)
path standard unix path to look for ssh-keygen
hostname that will be part of exported resource (default: FQDN fact)
separator A character for user and key type auto-detection (default: _)

Ssh key type depends on ssh-keygen version, see ssh-keygen --help for list of supported types on your system.

Advanced configuration

Optionally provide override any parameter

pubkey::ssh { 'alice_key':
  user       => 'alice',
  type       => 'ed25519',
  home       => '/home/alice',
  comment    => 'alice_ed25519@foo.bar',
  hostname   => 'foo'
  export_key => false,
  tags       => ['tag_users', 'bar'],
}

The key will be exported as alice_key@foo (suffix is taken from the hostname parameter). In order to import the key on other machine use e.g.:

Ssh_authorized_key <<| tag == "tag_users" |>>

All Puppet variables are documented in REFERENCE.md.

How does this work?

On the first run ssh-keygen is executed, if the desired ssh key pair doen't exist yet.

Puppet compiles code remotely, on a puppetserver. Which means that the local files are not available at the compile time. Local files (like public ssh keys) can be accessed from Facter code that is evaluated before applying the Puppet catalog. However Facter doesn't accept any arguments, so we don't know which keys to load before evaluating the Puppet code. An intermediate cache file /var/cache/pubkey/exported_keys is used to store location of exported keys. During next run the keys are fetched and exported under pubkey fact.

Exported ssh keys are stored as hierarchical fact. See facter --puppet -y pubkey

pubkey:
  bob_ed25519:
    comment: "bob_ed25519"
    key: "AAAAC3NzaC1lZDI1NTE5AAAAIHBqbh2bZtW2jyX5BnsbAahP3KwGSVKVisggLDqJKnkQ"
    type: ssh-ed25519

From Puppet code the key is available via $fact['pubkey']['bob_ed25519']['key'].

Limitations

Two consecutives Puppet runs are required to export the key. During the first run ssh key will be generated, during the second one it will be fetched from disk, exported and available as a fact.

Dependencies

ssh-keygen needs to be installed on the system.

Module dependencies:

Acceptance test

Run with specific set:

BEAKER_destroy=no BEAKER_setfile=debian10-64 bundle exec rake beaker

deric / puppet-pubkey