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" |>>

Customize target_user in order to store authorized key under different account than it was exported from.

pubkey::ssh { 'bob_ed25519':
  user        => 'bob', # auto-detected from title
  target_user => 'deploy', # user account under which authorized key will be stored
  tags        => ['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:

• puppetlabs/stdlib
• puppetlabs/sshkeys_core

Acceptance test

Run with specific set:

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

Reference

Table of Contents

Classes

• pubkey: Common configuration

Defined types

Public Defined types

• pubkey::ssh: Generate ssh key pair and exports public ssh key

Private Defined types

• pubkey::keygen: Internal class to validate detected parameters

Data types

• Pubkey::Type: Supported ssh key types

Classes

pubkey

Common configuration

Examples

include pubkey

Parameters

The following parameters are available in the pubkey class:

• cache_owner
• cache_group
• export_keys

cache_owner

Data type: String

Owner of the cache directory

cache_group

Data type: String

Group of the cache directory

export_keys

Data type: Boolean

Whether manage directory for exported keys. Note in order to disable pubkey::ssh::export_key should be set to false on each key.

Defined types

pubkey::ssh

Exports public ssh key to Puppetserver

Examples

pubkey::ssh { 'john_rsa': }

pubkey::ssh { 'johndoe':
  type    => 'ed25519',
  comment => 'johndoe_ed25519',
  tags    => ['users'],
}

pubkey::ssh { 'bob_ed25519':
  user        => 'bob', # auto-detected from title
  target_user => 'deploy', # user account under which authorized key will be stored
  tags        => ['users'],
}

Parameters

The following parameters are available in the pubkey::ssh defined type:

• generate
• user
• target_user
• type
• home
• prefix
• comment
• size
• tags
• export_key
• path
• hostname
• separator

generate

Data type: Boolean

Whether missing key should be generated

Default value: true

user

Data type: Optional[String[1]]

account name where ssh key is (optionally) generated and public key stored into exported resource

Default value: undef

target_user

Data type: Optional[String[1]]

account name under which we will store the authorized key (by default same as user)

Default value: undef

type

Data type: Optional[Pubkey::Type]

ssh key type one of: 'dsa', 'rsa', 'ecdsa', 'ed25519', 'ecdsa-sk', 'ed25519-sk'

Default value: undef

home

Data type: Optional[Stdlib::UnixPath]

user's home directory, assuming .ssh is located in $HOME/.ssh

Default value: undef

prefix

Data type: Optional[String[1]]

custom key file prefix for the ssh key file (default: 'id')

Default value: undef

comment

Data type: Optional[String[1]]

ssh key's comment

Default value: undef

size

Data type: Optional[Integer]

number of bits for generated ssh key

Default value: undef

tags

Data type: Optional[Array[String]]

optional tags added to the exported key

Default value: undef

export_key

Data type: Boolean

whether export the generated key (default: true)

Default value: true

path

Data type: Stdlib::AbsolutePath

standard unix path to look for ssh-keygen

Default value: $facts['path']

hostname

Data type: String

that will be part of exported resource

Default value: $facts['networking']['fqdn']

separator

Data type: String[1]

A character for user and type auto-detection (default: '_')

Default value: '_'

Data types

Pubkey::Type

Supported ssh key types

Alias of Enum['dsa', 'rsa', 'ecdsa', 'ed25519', 'ecdsa-sk', 'ed25519-sk']

Changelog

All notable changes to this project will be documented in this file.

[2025-08-15] Release 1.0.0

Changes

• Support custom target_user (#7)
• Drop Debian 10, Ubuntu 18.04 support
• Support Ubuntu 24.04

Bugfixes

• Fix username regex to include underscore (#6)

  Full changes

[2024-03-15] Release 0.9.0

Changes

• Require puppetlabs/sshkeys_core >= 2.1.0 in order to support keys introduced in OpenSSH 8.2
• Add param generate to make generating key optional

Bugfixes

• Avoid exporting invalid key

  Full changes

[2024-03-12] Release 0.8.3

Bugfixes

• Actually support sk-ssh-ed25519 key (#4)

  Full changes

[2024-03-12] Release 0.8.1

Bugfixes

• Fix ssh key type with prefix sk- (#4)

  Full changes

[2024-03-11] Release 0.8.0

Features

• Added main pubkey class for common configuration

Bugfixes

• Fixed duplicate resource declaration for cache dir

  Full changes

[2023-12-20] Release 0.7.0

Features

• Support Puppet 8

• Support Debian 12

• Support stdlib 9.x

  Full changes

[2023-02-15] Release 0.6.0

Features

• Allow custom separator for splitting user-key type.
• Support root account without overriding home
• Added acceptance tests

Bugfixes

• Added missing sshkeys_core dependency

• export might conflict with metaparam (#1)

  Full changes

[2023-02-15] Release 0.5.0

Features

• Replace custom function by simple puppet code
• Support custom key file prefix

Bugfixes

• Fixed ensure on cache file

• Don't allow passing empty strings

  Full changes

[2023-02-15] Release 0.4.0

Bugfixes

• Ensure cache file exists, before adding to it

• Return empty hash if the public key doesn't exist

  Full changes

[2023-02-15] Release 0.3.0

Bugfixes

• Fixed test

  Full changes

[2023-02-15] Release 0.2.0

Features

• Removed inifile module dependency

Bugfixes

• Fixed validation of empty username

• Gracefuly ignore missing ssh key

  Full changes

[2023-02-14] Release 0.1.0

Features

• Initial implementation, supports generating and exporting public ssh keys