migrate_nodes

Module containing a plan to migrate nodes from one Puppet Primary server to another. Useful for migrations.

Table of Contents

1. Description
2. Setup - The basics of getting started with migrate_nodes
   • What migrate_nodes affects
   • Beginning with migrate_nodes
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

There is currently no fully automated process to migrate Puppet nodes between Puppet Primary servers. This plan automates the process while preserving trusted facts contained on the nodes certificate.

Setup

What migrate_nodes affects

This modules plan affects the following

• Enables long file path support for Windows
• Updates csr_attributes.yaml with facts currently present on the agent certificate.
• Reconfigures puppet.conf on target nodes to point to the target Puppet primary.
• Deletes local agent certificate and ca.pem file.
• Reboots Puppet service on target.
• Purges target node from source primary server.

Warning: Do not migrate Puppet infrastructure components. This will break your Puppet installation. A built in check has been included to avoid this situation which relies on the 'is_pe' fact.

Beginning with migrate_nodes

Include the module within your Puppetfile.

mod 'benjaminrobertson-migrate_nodes'

Usage

Run the plan migrate_nodes::migrate_node from the Puppet Enterprise console.

Required parameters

• target_pe_address (Array/Sting - either compiler address or FQDN of Primary server. Use array to specify multiple compilers.)

Optional parameters

• targets (TargetSpec - see here)
• origin_pe_primary_server (String - Puppet Primary server the node is being migrated from. Must match Primary server FQDN(Certname))
• fact_name (String)
• fact_value (String)
• ignore_infra_status_error (Boolean - Ignore errors from puppet infrastructure status command. May allow the plan to operate if some Puppet infrastructure components are failing)
• bypass_connectivity_check (Boolean - Do not perform connectivity check to target Primary server)
• noop (Boolean - Run the plan in noop. csr_attributes.yaml will still be generated, however nodes will not be migrated.)

Note: Either targets or fact_name/fact_value must be specified. Cannot specify both.

To specific a trusted fact, use fact_name = trusted.extensions.pp_role.

Limitations

Verified with the following OS\Primary combinations.

Puppet Enterprise

• 2021.7.6
• 2021.7.9
• 2023.8.0

Puppet Nodes

• Windows 2019
• Windows 2022
• RHEL 8
• RHEL 9

Expected to work for all Windows 2016 or later, Enterprise Linux, Debian, Ubuntu versions.

Expected to work with all modern Puppet Enterprise releases.

Development

If you find any issues with this module, please log them in the issues register of the GitHub project. Issues

PR glady accepted :)

Reference

Table of Contents

Tasks

• check_pe_connection: Confirms if a PE server is accessible from a node
• clear_ssl_certs: Clears SSL certs from Puppet agent; deletes cert and restart
• confirm_primary_server: Task to verify if the server its running on is in fact the Puppet Primary server
• set_csr_attributes: Merges existing trusted fact
• set_long_paths_windows: Enable long path support on Windows 2016 or later

Plans

• migrate_nodes::migrate_node: PE plan to migrate nodes to another PE server

Tasks

check_pe_connection

Confirms if a PE server is accessible from a node

Supports noop? false

Parameters

target_pe_server

Data type: String[1]

PE server to check connection to

bypass_connectivity_check

Data type: Boolean

Bypass connectivity check, still checks for PE server

clear_ssl_certs

Clears SSL certs from Puppet agent; deletes cert and restart

Supports noop? true

Parameters

noop

Data type: Boolean

noop workaround parameter

confirm_primary_server

Task to verify if the server its running on is in fact the Puppet Primary server

Supports noop? false

Parameters

pe_primary_server

Data type: String

Puppet Primary server hostname

ignore_infra_status_error

Data type: Boolean

Ignore puppet infra status stderr

set_csr_attributes

Merges existing trusted fact

Supports noop? false

Parameters

trusted_facts

Data type: Hash

Trusted facts to add

preserve_existing_facts

Data type: Boolean

Preserve existing trusted facts

set_long_paths_windows

Enable long path support on Windows 2016 or later

Supports noop? true

Plans

migrate_nodes::migrate_node

lint:ignore:140chars

Parameters

The following parameters are available in the migrate_nodes::migrate_node plan:

• origin_pe_primary_server
• target_pe_address
• targets
• fact_name
• fact_value
• noop
• bypass_connectivity_check
• ignore_infra_status_error

origin_pe_primary_server

Data type: String

Puppet Primary server the node is being migrated from. Must match Primary server FQDN(Certname). Use to purge migrated nodes.

Default value: undef

target_pe_address

Data type: Variant[String,Array]

Target Puppet server, either compiler address or FQDN of Primary server. Use array to specific multiple compilers.

targets

Data type: Optional[TargetSpec]

The targets to run on (note this must match the certnames used by Puppet / shown in PE console). NOTE: you may ONLY specify target or fact_value. Specifying both will cause the plan to fail.

Default value: undef

fact_name

Data type: Optional[String]

Fact name to match nodes by.

Default value: undef

fact_value

Data type: Optional[String]

Fact value the fact must match. NOTE: you may ONLY specify target or fact_value. Specifying both will cause the plan to fail.

Default value: undef

noop

Data type: Boolean

Run the plan in noop mode. Make no changes.

Default value: false

bypass_connectivity_check

Data type: Boolean

Do not check for connectivity to target PE server.

Default value: false

ignore_infra_status_error

Data type: Boolean

Default value: false

Changelog

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

Release 1.0.0

Features

• Added support Puppet 8.
• Migrate_node plan will now automatically locate the origin primary server.
• Added lint test to github actions.

Release 0.1.0

Features

• First release to forge.

Bugfixes

Known Issues