diff --git a/manifests/init.pp b/manifests/init.pp
index a73a2740..5c622ec8 100644
--- a/manifests/init.pp
+++ b/manifests/init.pp
@@ -103,6 +103,12 @@
 # @param skip_if_unavailable
 #    For yum-based repositories, set the skip_if_unavailable option of the `yumrepo` type.
 # @param disable_proxy
+# @param alternate_pe_version
+#   When using a PE-based package source (e.g. "alternate_pe_source", "aix_source")
+#   this setting allows you to override the PE version number used when constructing the
+#   package source URL. Normally, this will be the running version of PE but this setting
+#   can be used to "hold back" the agents during an upgrade of PE if there is a need
+#   to upgrade the platform and agents on separate schedules.
 class puppet_agent (
   String                         $arch                    = $facts['os']['architecture'],
   String                         $collection              = $puppet_agent::params::collection,
@@ -131,7 +137,8 @@
   Optional                       $wait_for_pxp_agent_exit = undef,
   Optional                       $wait_for_puppet_run     = undef,
   Array[Puppet_agent::Config]    $config                  = [],
-  String                         $version_file_path       = $facts['os']['family'] ? { 'windows' => "${facts['env_windows_installdir']}\\VERSION", default => '/opt/puppetlabs/puppet/VERSION' }
+  String                         $version_file_path       = $facts['os']['family'] ? { 'windows' => "${facts['env_windows_installdir']}\\VERSION", default => '/opt/puppetlabs/puppet/VERSION' },
+  Optional[String[1]]            $alternate_pe_version    = undef,
 ) inherits puppet_agent::params {
   # The configure class uses $puppet_agent::config to manage settings in
   # puppet.conf, and will always be present. It does not require management of
diff --git a/manifests/osfamily/aix.pp b/manifests/osfamily/aix.pp
index b885c1c4..d6063963 100644
--- a/manifests/osfamily/aix.pp
+++ b/manifests/osfamily/aix.pp
@@ -10,7 +10,7 @@
     fail('AIX upgrades are only supported on Puppet Enterprise')
   }
 
-  $pe_server_version = pe_build_version()
+  $pe_server_version = $puppet_agent::alternate_pe_version.lest || { pe_build_version() }
 
   # in puppet versions later than 4 we began using single agent packages for
   # multiple version of AIX. The support sequence is as follows:
diff --git a/manifests/osfamily/darwin.pp b/manifests/osfamily/darwin.pp
index ab3dfd15..8da706b7 100644
--- a/manifests/osfamily/darwin.pp
+++ b/manifests/osfamily/darwin.pp
@@ -12,7 +12,7 @@
   if $puppet_agent::absolute_source {
     $source = $puppet_agent::absolute_source
   } elsif ($puppet_agent::is_pe and (!$puppet_agent::use_alternate_sources)) {
-    $pe_server_version = pe_build_version()
+    $pe_server_version = $puppet_agent::alternate_pe_version.lest || { pe_build_version() }
     if $puppet_agent::alternate_pe_source {
       $source = "${puppet_agent::alternate_pe_source}/packages/${pe_server_version}/${facts['platform_tag']}/${puppet_agent::package_name}-${puppet_agent::prepare::package_version}-1.osx${$productversion_major}.dmg"
     } elsif $puppet_agent::source {
diff --git a/manifests/osfamily/debian.pp b/manifests/osfamily/debian.pp
index 7cbd9d3e..0fb6de49 100644
--- a/manifests/osfamily/debian.pp
+++ b/manifests/osfamily/debian.pp
@@ -15,7 +15,7 @@
     if getvar('::puppet_agent::manage_repo') == true {
       include apt
       if ($puppet_agent::is_pe and (!$puppet_agent::use_alternate_sources)) {
-        $pe_server_version = pe_build_version()
+        $pe_server_version = $puppet_agent::alternate_pe_version.lest || { pe_build_version() }
         if $puppet_agent::source {
           $source = "${puppet_agent::source}/packages/${pe_server_version}/${facts['platform_tag']}"
         } elsif $puppet_agent::alternate_pe_source {
diff --git a/manifests/osfamily/redhat.pp b/manifests/osfamily/redhat.pp
index 36e6693d..9a1ed608 100644
--- a/manifests/osfamily/redhat.pp
+++ b/manifests/osfamily/redhat.pp
@@ -31,7 +31,7 @@
     }
     # lint:endignore
     if ($puppet_agent::is_pe and (!$puppet_agent::use_alternate_sources)) {
-      $pe_server_version = pe_build_version()
+      $pe_server_version = $puppet_agent::alternate_pe_version.lest || { pe_build_version() }
       # Treat Amazon Linux just like Enterprise Linux
       $pe_repo_dir = ($facts['os']['name'] == 'Amazon') ? {
         true    => "el-${amz_el_version}-${facts['os']['architecture']}",
diff --git a/manifests/osfamily/solaris.pp b/manifests/osfamily/solaris.pp
index 13721560..7193f5dc 100644
--- a/manifests/osfamily/solaris.pp
+++ b/manifests/osfamily/solaris.pp
@@ -10,7 +10,7 @@
     fail('Solaris upgrades are only supported on Puppet Enterprise')
   }
 
-  $pe_server_version = pe_build_version()
+  $pe_server_version = $puppet_agent::alternate_pe_version.lest || { pe_build_version() }
   if $puppet_agent::absolute_source {
     $source_dir = $puppet_agent::absolute_source
   } elsif $puppet_agent::alternate_pe_source {
diff --git a/manifests/osfamily/suse.pp b/manifests/osfamily/suse.pp
index ad199af1..80a76e7d 100644
--- a/manifests/osfamily/suse.pp
+++ b/manifests/osfamily/suse.pp
@@ -17,7 +17,7 @@
     contain puppet_agent::prepare::package
   } else {
     if ($puppet_agent::is_pe and (!$puppet_agent::use_alternate_sources)) {
-      $pe_server_version = pe_build_version()
+      $pe_server_version = $puppet_agent::alternate_pe_version.lest || { pe_build_version() }
 
       # SLES 11 in PE can no longer install agents from pe_repo
       if $facts['os']['release']['major'] == '11' {
diff --git a/manifests/osfamily/windows.pp b/manifests/osfamily/windows.pp
index 8114ddeb..2253c127 100644
--- a/manifests/osfamily/windows.pp
+++ b/manifests/osfamily/windows.pp
@@ -7,7 +7,7 @@
   } elsif $puppet_agent::source {
     $source = $puppet_agent::source
   } elsif  ($puppet_agent::is_pe and (!$puppet_agent::use_alternate_sources)) {
-    $pe_server_version = pe_build_version()
+    $pe_server_version = $puppet_agent::alternate_pe_version.lest || { pe_build_version() }
     $tag = $puppet_agent::arch ? {
       'x64' => $facts['fips_enabled'] ? {
         true => 'windowsfips-x86_64',
diff --git a/spec/classes/puppet_agent_osfamily_aix_spec.rb b/spec/classes/puppet_agent_osfamily_aix_spec.rb
index 14814377..61dc3be7 100644
--- a/spec/classes/puppet_agent_osfamily_aix_spec.rb
+++ b/spec/classes/puppet_agent_osfamily_aix_spec.rb
@@ -80,6 +80,32 @@
     }
   end
 
+  context 'with a user defined PE version' do
+    let(:facts) do
+      common_facts.merge(
+        {
+          architecture: 'PowerPC_POWER8',
+          platform_tag: 'aix-7.1-power',
+        }
+      )
+    end
+    let(:params) do
+      {
+        package_version: '7.10.100.1',
+        collection: 'puppet7',
+        alternate_pe_version: '2222.2.2',
+      }
+    end
+
+    before(:each) do
+      Puppet::Parser::Functions.newfunction(:pe_build_version, type: :rvalue) { |_args| '2000.0.0' }
+    end
+
+    it {
+      is_expected.to contain_file('/opt/puppetlabs/packages/puppet-agent-7.10.100.1-1.aix7.1.ppc.rpm').with_source('puppet:///pe_packages/2222.2.2/aix-7.1-power/puppet-agent-7.10.100.1-1.aix7.1.ppc.rpm')
+    }
+  end
+
   context 'with a puppet6 collection' do
     context 'with versions up to 6.19.1' do
       let(:params) do
diff --git a/spec/classes/puppet_agent_osfamily_darwin_spec.rb b/spec/classes/puppet_agent_osfamily_darwin_spec.rb
index cc9c5f7f..88959f5b 100644
--- a/spec/classes/puppet_agent_osfamily_darwin_spec.rb
+++ b/spec/classes/puppet_agent_osfamily_darwin_spec.rb
@@ -84,6 +84,26 @@
     it { is_expected.to contain_file('/opt/puppetlabs/packages/puppet-agent-5.10.100.1-1.osx10.13.dmg').with_source('https://fake-pe-master.com/packages/2000.0.0/osx-10.13-x86_64/puppet-agent-5.10.100.1-1.osx10.13.dmg') }
   end
 
+  describe 'when using a user defined PE version' do
+    let(:params) do
+      {
+        package_version: '5.10.100.1',
+        collection: 'puppet5',
+        alternate_pe_version: '2222.2.2',
+      }
+    end
+    let(:facts) do
+      facts.merge({
+                    is_pe: true,
+                    aio_agent_version: '1.10.99',
+                    platform_tag: 'osx-10.13-x86_64',
+                    macosx_productversion_major: '10.13'
+                  })
+    end
+
+    it { is_expected.to contain_file('/opt/puppetlabs/packages/puppet-agent-5.10.100.1-1.osx10.13.dmg').with_source('puppet:///pe_packages/2222.2.2/osx-10.13-x86_64/puppet-agent-5.10.100.1-1.osx10.13.dmg') }
+  end
+
   describe 'when using package_version auto' do
     let(:params) do
       {
diff --git a/spec/classes/puppet_agent_osfamily_debian_spec.rb b/spec/classes/puppet_agent_osfamily_debian_spec.rb
index e6040363..457f840c 100644
--- a/spec/classes/puppet_agent_osfamily_debian_spec.rb
+++ b/spec/classes/puppet_agent_osfamily_debian_spec.rb
@@ -216,6 +216,28 @@
       }
     end
 
+    context 'when managing PE apt repo settings and using a user defined PE version' do
+      let(:params) do
+        {
+          manage_repo: true,
+          package_version: package_version,
+          alternate_pe_version: '2222.2.2'
+        }
+      end
+
+      it {
+        is_expected.to contain_apt__source('pc_repo')
+          .with({
+                  'location' => 'https://master.example.vm:8140/packages/2222.2.2/debian-7-x86_64',
+                  'repos'    => 'PC1',
+                  'key'      => {
+                    'id'     => 'D6811ED3ADEEB8441AF5AA8F4528B6CD9E61EF26',
+                    'source' => '/etc/pki/deb-gpg/GPG-KEY-puppet-20250406',
+                  },
+                })
+      }
+    end
+
     context 'when not managing PE apt repo settings' do
       let(:params) do
         {
diff --git a/spec/classes/puppet_agent_osfamily_redhat_spec.rb b/spec/classes/puppet_agent_osfamily_redhat_spec.rb
index b92104bc..67079ca6 100644
--- a/spec/classes/puppet_agent_osfamily_redhat_spec.rb
+++ b/spec/classes/puppet_agent_osfamily_redhat_spec.rb
@@ -186,6 +186,18 @@
         it { is_expected.to contain_yumrepo('pc_repo').with_baseurl("http://fake-pe-master.com/packages/2000.0.0/#{repodir}") }
       end
 
+      context 'when using a user defined PE version' do
+        let(:params) do
+          {
+            package_version: '5.2.0',
+            manage_repo: true,
+            alternate_pe_version: '2222.2.2'
+          }
+        end
+
+        it { is_expected.to contain_yumrepo('pc_repo').with_baseurl("https://master.example.vm:8140/packages/2222.2.2/#{repodir}") }
+      end
+
       context 'with manage_repo enabled' do
         let(:params) do
           {
diff --git a/spec/classes/puppet_agent_osfamily_solaris_spec.rb b/spec/classes/puppet_agent_osfamily_solaris_spec.rb
index bddf35e1..d6aee188 100644
--- a/spec/classes/puppet_agent_osfamily_solaris_spec.rb
+++ b/spec/classes/puppet_agent_osfamily_solaris_spec.rb
@@ -125,6 +125,26 @@ def install_script(ver, arch)
       end
     end
 
+    context 'when Solaris 11 i386 and a user defined PE version' do
+      let(:facts) do
+        override_facts(facts, is_pe: true, os: { release: { major: '11', }, }, platform_tag: 'solaris-11-i386')
+      end
+      let(:params) do
+        {
+          package_version: package_version,
+          alternate_pe_version: '2222.2.2'
+        }
+      end
+
+      it do
+        is_expected.to contain_file("/opt/puppetlabs/packages/puppet-agent@#{sol11_package_version},5.11-1.i386.p5p")
+          .with({
+                  'ensure' => 'file',
+                  'source' => "puppet:///pe_packages/2222.2.2/solaris-11-i386/puppet-agent@#{sol11_package_version},5.11-1.i386.p5p",
+                })
+      end
+    end
+
     context 'when Solaris 11 i386' do
       let(:facts) do
         override_facts(facts, is_pe: true, os: { release: { major: '11', }, }, platform_tag: 'solaris-11-i386')
@@ -258,6 +278,26 @@ def install_script(ver, arch)
       end
     end
 
+    context 'when Solaris 10 i386 and a user defined PE version' do
+      let(:facts) do
+        override_facts(facts, is_pe: true, os: { release: { major: '10', }, }, platform_tag: 'solaris-10-i386')
+      end
+      let(:params) do
+        {
+          package_version: package_version,
+          alternate_pe_version: '2222.2.2'
+        }
+      end
+
+      it do
+        is_expected.to contain_file("/opt/puppetlabs/packages/puppet-agent-#{package_version}-1.i386.pkg.gz")
+          .with({
+                  'ensure' => 'file',
+                  'source' => "puppet:///pe_packages/2222.2.2/solaris-10-i386/puppet-agent-#{package_version}-1.i386.pkg.gz",
+                })
+      end
+    end
+
     context 'when Solaris 10 i386' do
       let(:facts) do
         override_facts(facts, is_pe: true, os: { release: { major: '10', }, }, platform_tag: 'solaris-10-i386')
diff --git a/spec/classes/puppet_agent_osfamily_suse_spec.rb b/spec/classes/puppet_agent_osfamily_suse_spec.rb
index 851363df..c567bd48 100644
--- a/spec/classes/puppet_agent_osfamily_suse_spec.rb
+++ b/spec/classes/puppet_agent_osfamily_suse_spec.rb
@@ -342,6 +342,26 @@
                 }
               end
 
+              context 'with manage_repo enabled and a user defined PE version' do
+                let(:params) do
+                  {
+                    manage_repo: true,
+                    package_version: package_version,
+                    alternate_pe_version: '2222.2.2',
+                  }
+                end
+
+                it {
+                  is_expected.to contain_ini_setting('zypper pc_repo baseurl')
+                    .with({
+                            'path'    => '/etc/zypp/repos.d/pc_repo.repo',
+                            'section' => 'pc_repo',
+                            'setting' => 'baseurl',
+                            'value'   => "https://master.example.vm:8140/packages/2222.2.2/sles-#{os_version}-x86_64?ssl_verify=no",
+                          })
+                }
+              end
+
               it do
                 is_expected.to contain_package('puppet-agent')
               end
@@ -369,23 +389,36 @@
             end
 
             describe 'package source', if: os_version == '11' do
-              it { is_expected.to contain_file('/etc/zypp/repos.d/pc_repo.repo').with({ 'ensure' => 'absent' }) }
-              it {
-                is_expected.to contain_file('/opt/puppetlabs/packages/puppet-agent-1.10.100-1.sles11.x86_64.rpm')
-                  .with(
-                  source: 'puppet:///pe_packages/2000.0.0/sles-11-x86_64/puppet-agent-1.10.100-1.sles11.x86_64.rpm',
-                )
-              }
-              it {
-                is_expected.to contain_exec('GPG check the RPM file')
-                  .with(
-                  command: 'rpm -K /opt/puppetlabs/packages/puppet-agent-1.10.100-1.sles11.x86_64.rpm',
-                  path: '/bin:/usr/bin:/sbin:/usr/sbin',
-                  require: 'File[/opt/puppetlabs/packages/puppet-agent-1.10.100-1.sles11.x86_64.rpm]',
-                  logoutput: 'on_failure',
-                  notify: 'Package[puppet-agent]',
-                )
-              }
+              context 'with no source overrides' do
+                it { is_expected.to contain_file('/etc/zypp/repos.d/pc_repo.repo').with({ 'ensure' => 'absent' }) }
+                it {
+                  is_expected.to contain_file('/opt/puppetlabs/packages/puppet-agent-1.10.100-1.sles11.x86_64.rpm')
+                    .with(
+                    source: 'puppet:///pe_packages/2000.0.0/sles-11-x86_64/puppet-agent-1.10.100-1.sles11.x86_64.rpm',
+                  )
+                }
+                it {
+                  is_expected.to contain_exec('GPG check the RPM file')
+                    .with(
+                    command: 'rpm -K /opt/puppetlabs/packages/puppet-agent-1.10.100-1.sles11.x86_64.rpm',
+                    path: '/bin:/usr/bin:/sbin:/usr/sbin',
+                    require: 'File[/opt/puppetlabs/packages/puppet-agent-1.10.100-1.sles11.x86_64.rpm]',
+                    logoutput: 'on_failure',
+                    notify: 'Package[puppet-agent]',
+                  )
+                }
+              end
+
+              context 'with a user defined PE version' do
+                let(:params) { super().merge(alternate_pe_version: '2222.2.2') }
+
+                it {
+                  is_expected.to contain_file('/opt/puppetlabs/packages/puppet-agent-1.10.100-1.sles11.x86_64.rpm')
+                    .with(
+                    source: 'puppet:///pe_packages/2222.2.2/sles-11-x86_64/puppet-agent-1.10.100-1.sles11.x86_64.rpm',
+                  )
+                }
+              end
             end
           end
         end
diff --git a/spec/classes/puppet_agent_osfamily_windows_spec.rb b/spec/classes/puppet_agent_osfamily_windows_spec.rb
index a0f7a5a8..97dff465 100644
--- a/spec/classes/puppet_agent_osfamily_windows_spec.rb
+++ b/spec/classes/puppet_agent_osfamily_windows_spec.rb
@@ -56,6 +56,26 @@
           'source' => "puppet:///pe_packages/#{pe_version}/windows-#{tag}/puppet-agent-#{arch}.msi",
         )
       }
+
+      context 'when alternate_pe_source is supplied' do
+        let(:params) { super().merge(alternate_pe_source: 'https://fake-package-source.com') }
+
+        it {
+          is_expected.to contain_file("#{appdata}\\Puppetlabs\\packages\\puppet-agent-#{arch}.msi").with(
+            'source' => "https://fake-package-source.com/packages/#{pe_version}/windows-#{tag}/puppet-agent-#{arch}.msi",
+          )
+        }
+      end
+
+      context 'when alternate_pe_version is supplied' do
+        let(:params) { super().merge(alternate_pe_version: '2222.2.2') }
+
+        it {
+          is_expected.to contain_file("#{appdata}\\Puppetlabs\\packages\\puppet-agent-#{arch}.msi").with(
+            'source' => "puppet:///pe_packages/2222.2.2/windows-#{tag}/puppet-agent-#{arch}.msi",
+          )
+        }
+      end
     end
   end