Add profiles::puppet::migrate to repoint VM agents onto puppet-on-k8s

Migrate VM puppet agents off the legacy VM puppetmasters and onto the new
puppet-on-kubernetes servers, per-wave via hiera and reversible without
re-enrolment. Changing server/ca_server alone is insufficient: the agent's
ssldir holds a cert signed by the OLD CA that the new CA neither trusts nor
recognises. This switches migrated nodes to a FRESH ssldir so the agent
generates a new CSR (autosigned on the k8s CA) while the old creds stay on
disk for rollback.

- Add profiles::puppet::migrate: opt-in (hiera_include) toggle that owns the
  fresh ssldir directory and documents per-node/per-role/common wiring plus
  rollback in its class header.
- Extend profiles::puppet::client with optional $ssldir and $report_server
  params (default undef); the ERB template omits both lines when unset, so
  unmigrated nodes render a byte-identical puppet.conf.
- puppet.conf stays owned solely by client.pp's template; migrate.pp adds no
  competing File resource.

site/profiles/manifests/puppet/client.pp

@@ -4,17 +4,19 @@
 #
 # site/profile/manifests/puppet/client.pp
 class profiles::puppet::client (
-  Array  $dns_alt_names       = [$trusted['certname']],
-  String $server              = 'puppetmaster',
-  String $ca_server           = 'puppetca',
-  String $environment         = 'develop',
-  Integer $runinterval        = 1800,
-  Integer $runtimeout         = 3600,
-  Boolean $show_diff          = true,
-  Boolean $usecacheonfailure  = false,
-  Integer $facts_soft_limit   = 4096,
-  Boolean $splay              = true,
-  Integer $splaylimit         = 600,
+  Array  $dns_alt_names                  = [$trusted['certname']],
+  String $server                         = 'puppetmaster',
+  String $ca_server                      = 'puppetca',
+  Optional[String] $report_server        = undef,
+  String $environment                    = 'develop',
+  Integer $runinterval                   = 1800,
+  Integer $runtimeout                    = 3600,
+  Boolean $show_diff                     = true,
+  Boolean $usecacheonfailure             = false,
+  Integer $facts_soft_limit              = 4096,
+  Boolean $splay                         = true,
+  Integer $splaylimit                    = 600,
+  Optional[Stdlib::Absolutepath] $ssldir = undef,
 ) {
 
   # dont manage puppet.conf if this is a puppetmaster

site/profiles/manifests/puppet/migrate.pp

@@ -0,0 +1,90 @@
+# Class: profiles::puppet::migrate
+#
+# Repoints a VM puppet agent from the legacy VM puppetmasters onto the new
+# puppet-on-kubernetes servers.
+#
+# The agent's existing ssldir holds a client certificate signed by the OLD CA;
+# the new k8s CA will neither trust that cert nor recognise the agent. Rather
+# than revoke/clean the old creds (which would burn the rollback path), this
+# class switches the agent to a FRESH ssldir. On the next run the agent finds
+# an empty ssldir, generates a new key + CSR, submits it to the new CA
+# (autosign = true on the k8s side signs it immediately), and then pulls its
+# catalog from the new compilers. The OLD ssldir is left untouched on disk, so
+# reverting the hiera below restores the node to the legacy masters with no
+# re-enrolment.
+#
+# The catalog that performs the switch is compiled by the OLD server (the node
+# still points at it when it applies this change). profiles::puppet::client
+# rewrites puppet.conf with the new server / ca_server / report_server / ssldir
+# and notifies Service['puppet'], so the very next agent run lands on k8s.
+#
+# NOTE: this is deliberately hiera-driven per node/role so waves can be rolled
+# out and rolled back one target at a time. The class only manages the fresh
+# ssldir; the actual puppet.conf changes ride on profiles::puppet::client's
+# existing template via its $server / $ca_server / $report_server / $ssldir
+# params (see the hiera block below). Do NOT add a second File resource for
+# puppet.conf here -- client.pp already owns it.
+#
+# == Wiring (hiera_include convention)
+#
+# This class is opt-in via hiera_include; it is not pulled in by
+# profiles::base. To migrate a target add the class to hiera_include AND flip
+# the client params so puppet.conf carries the new endpoints + fresh ssldir.
+#
+# --- Canary: one node -> hieradata/nodes/<certname>.yaml -------------------
+#   hiera_include:
+#     - profiles::puppet::migrate
+#
+#   profiles::puppet::migrate::enabled: true
+#
+#   # repoint the agent (client.pp owns puppet.conf; migrate.pp owns ssldir)
+#   profiles::puppet::client::server: 'puppet.k8s.syd1.au.unkin.net'
+#   profiles::puppet::client::ca_server: 'puppetca.k8s.syd1.au.unkin.net'
+#   profiles::puppet::client::report_server: 'puppet.k8s.syd1.au.unkin.net'
+#   profiles::puppet::client::ssldir: '/etc/puppetlabs/puppet/ssl-k8s'
+# ---------------------------------------------------------------------------
+#
+# --- Wave: a whole role -> hieradata/roles/<t1>/<t2>[/<t3>].yaml -----------
+#   (same keys as the canary block above)
+# ---------------------------------------------------------------------------
+#
+# --- Final flip: hieradata/common.yaml (retires the legacy masters) --------
+#   profiles::puppet::client::server: 'puppet.k8s.syd1.au.unkin.net'
+#   profiles::puppet::client::ca_server: 'puppetca.k8s.syd1.au.unkin.net'
+#   profiles::puppet::client::report_server: 'puppet.k8s.syd1.au.unkin.net'
+#   profiles::puppet::client::ssldir: '/etc/puppetlabs/puppet/ssl-k8s'
+#   # profiles::puppet::migrate no longer needs to be in hiera_include once the
+#   # fleet default points at k8s and the fresh ssldir exists everywhere.
+# ---------------------------------------------------------------------------
+#
+# == Rollback (per target)
+#
+# Delete the migration block from the node/role hiera (or set the client keys
+# back to the legacy values and drop the ssldir override). The next run
+# rewrites puppet.conf back to the legacy ssldir, which still contains the
+# original CA-signed cert, and the node is back on the VM masters.
+#
+# site/profiles/manifests/puppet/migrate.pp
+class profiles::puppet::migrate (
+  Boolean $enabled                          = false,
+  String $new_server                        = 'puppet.k8s.syd1.au.unkin.net',
+  String $new_ca_server                     = 'puppetca.k8s.syd1.au.unkin.net',
+  Stdlib::Absolutepath $new_ssldir          = '/etc/puppetlabs/puppet/ssl-k8s',
+) {
+
+  # never touch the puppet masters themselves (same guard as client.pp)
+  if $enabled and $facts['enc_role'] != 'roles::infra::puppet::master' {
+
+    # Ensure the fresh ssldir exists with agent-correct ownership/perms. The
+    # puppet agent will create it on demand, but pre-creating it keeps the very
+    # first post-switch run from racing directory creation and makes the
+    # migration state auditable. Contents (keys, certs, crl) are populated by
+    # the agent against the new CA -- we only own the directory itself.
+    file { $new_ssldir:
+      ensure => 'directory',
+      owner  => 'root',
+      group  => 'root',
+      mode   => '0771',
+    }
+  }
+}