diff --git a/.github/workflows/test-upgrade-legacy.yaml b/.github/workflows/test-upgrade-legacy.yaml new file mode 100644 index 00000000..a8fb954a --- /dev/null +++ b/.github/workflows/test-upgrade-legacy.yaml @@ -0,0 +1,163 @@ +--- +name: "Upgrade PE with one legacy compiler" + +on: + pull_request: + paths: + - ".github/workflows/**/*" + - "spec/**/*" + - "lib/**/*" + - "tasks/**/*" + - "functions/**/*" + - "types/**/*" + - "plans/**/*" + - "hiera/**/*" + - "manifests/**/*" + - "templates/**/*" + - "files/**/*" + - "metadata.json" + - "Rakefile" + - "Gemfile" + - "provision.yaml" + - ".rspec" + - ".rubocop.yml" + - ".puppet-lint.rc" + - ".fixtures.yml" + branches: [main] + workflow_dispatch: + ssh-debugging: + description: "Boolean; whether or not to pause for ssh debugging" + required: true + default: "false" + +jobs: + test-install: + name: "PE ${{ matrix.version }} ${{ matrix.architecture }} on ${{ matrix.image }}" + runs-on: ubuntu-20.04 + env: + BOLT_GEM: true + BOLT_DISABLE_ANALYTICS: true + LANG: "en_US.UTF-8" + strategy: + fail-fast: false + matrix: + architecture: + - "large-with-two-compilers" + image: + - "almalinux-cloud/almalinux-8" + version: + - "2023.6.0" + to_version: + - "2023.7.0" + + steps: + - name: "Start SSH session" + if: ${{ github.event.inputs.ssh-debugging == 'true' }} + uses: luchihoratiu/debug-via-ssh@main + with: + NGROK_AUTH_TOKEN: ${{ secrets.NGROK_AUTH_TOKEN }} + SSH_PASS: ${{ secrets.SSH_PASS }} + + - name: "Checkout Source" + uses: actions/checkout@v2 + + - name: "Activate Ruby 2.7" + uses: ruby/setup-ruby@v1 + with: + ruby-version: "2.7" + bundler-cache: true + + - name: "Print bundle environment" + if: ${{ github.repository_owner == 'puppetlabs' }} + run: | + echo ::group::info:bundler + bundle env + echo ::endgroup:: + + - name: "Provision test cluster" + timeout-minutes: 15 + run: | + echo ::group::prepare + mkdir -p $HOME/.ssh + echo 'Host *' > $HOME/.ssh/config + echo ' ServerAliveInterval 150' >> $HOME/.ssh/config + echo ' ServerAliveCountMax 2' >> $HOME/.ssh/config + bundle exec rake spec_prep + echo ::endgroup:: + + echo ::group::provision + bundle exec bolt plan run peadm_spec::provision_test_cluster \ + --modulepath spec/fixtures/modules \ + provider=provision_service \ + image=${{ matrix.image }} \ + architecture=${{ matrix.architecture }} + echo ::endgroup:: + + echo ::group::info:request + cat request.json || true; echo + echo ::endgroup:: + + echo ::group::info:inventory + sed -e 's/password: .*/password: "[redacted]"/' < spec/fixtures/litmus_inventory.yaml || true + echo ::endgroup:: + + - name: Set up yq + uses: frenck/action-setup-yq@v1 + with: + version: v4.30.5 + + - name: 'Install PE on test cluster' + timeout-minutes: 120 + run: | + bundle exec bolt plan run peadm_spec::install_test_cluster \ + --inventoryfile spec/fixtures/litmus_inventory.yaml \ + --modulepath spec/fixtures/modules \ + architecture="large" \ + version=${{ matrix.version }} + + - name: 'Wait as long as the file ${HOME}/pause file is present' + if: ${{ always() && github.event.inputs.ssh-debugging == 'true' }} + run: | + while [ -f "${HOME}/pause" ] ; do + echo "${HOME}/pause present, sleeping for 60 seconds..." + sleep 60 + done + echo "${HOME}/pause absent, continuing workflow." + + - name: 'Convert one compiler to legacy' + timeout-minutes: 120 + run: | + primary=$(yq '.groups[].targets[] | select(.vars.role == "primary") | .uri' spec/fixtures/litmus_inventory.yaml) + compiler=$(yq '.groups[].targets[] | select(.vars.role == "compiler") | .uri' spec/fixtures/litmus_inventory.yaml | head -n 1) + + bundle exec bolt plan run peadm::convert_compiler_to_legacy \ + --inventoryfile spec/fixtures/litmus_inventory.yaml \ + --modulepath spec/fixtures/modules \ + --no-host-key-check \ + primary_host=$primary \ + legacy_hosts=$compiler + + + - name: 'Upgrade PE on test cluster' + timeout-minutes: 120 + run: | + bundle exec bolt plan run peadm_spec::upgrade_test_cluster \ + --inventoryfile spec/fixtures/litmus_inventory.yaml \ + --modulepath spec/fixtures/modules \ + --no-host-key-check \ + architecture="large" \ + version=${{ matrix.to_version }} + + - name: "Tear down test cluster" + if: ${{ always() }} + continue-on-error: true + run: | + if [ -f spec/fixtures/litmus_inventory.yaml ]; then + echo ::group::tear_down + bundle exec rake 'litmus:tear_down' + echo ::endgroup:: + + echo ::group::info:request + cat request.json || true; echo + echo ::endgroup:: + fi diff --git a/REFERENCE.md b/REFERENCE.md index 065b6d75..8d7c910e 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -8,123 +8,130 @@ #### Private Classes -* `peadm::setup::convert_node_manager`: Used during the peadm::convert plan -* `peadm::setup::convert_pre20197`: Defines configuration needed for converting PE 2018 -* `peadm::setup::node_manager`: Configures PEAdm's required node groups -* `peadm::setup::node_manager_yaml`: Set up the node_manager.yaml file in the temporary Bolt confdir +- `peadm::setup::convert_node_manager`: Used during the peadm::convert plan +- `peadm::setup::convert_pre20197`: Defines configuration needed for converting PE 2018 +- `peadm::setup::legacy_compiler_group` +- `peadm::setup::node_manager`: Configures PEAdm's required node groups +- `peadm::setup::node_manager_yaml`: Set up the node_manager.yaml file in the temporary Bolt confdir ### Functions -* [`peadm::assert_supported_architecture`](#peadm--assert_supported_architecture): Assert that the architecture given is a supported one -* [`peadm::assert_supported_bolt_version`](#peadm--assert_supported_bolt_version): Assert that the Bolt executable running PEAdm is a supported version -* [`peadm::assert_supported_pe_version`](#peadm--assert_supported_pe_version): Assert that the PE version given is supported by PEAdm -* [`peadm::bolt_version`](#peadm--bolt_version) -* [`peadm::certname`](#peadm--certname): Return the certname of the given target-like input -* [`peadm::check_version_and_known_hosts`](#peadm--check_version_and_known_hosts): Checks PE verison and warns about setting r10k_known_hosts -* [`peadm::convert_hash`](#peadm--convert_hash): converts two arrays into hash -* [`peadm::convert_status`](#peadm--convert_status): Transforms a value in a human readable status with or without colors -* [`peadm::determine_status`](#peadm--determine_status): Produces a summarized hash of the given status data -* [`peadm::fail_on_transport`](#peadm--fail_on_transport): Fails if any nodes have the chosen transport. Useful for excluding PCP when it's not appopriate -* [`peadm::file_content_upload`](#peadm--file_content_upload) -* [`peadm::file_or_content`](#peadm--file_or_content) -* [`peadm::flatten_compact`](#peadm--flatten_compact) -* [`peadm::generate_pe_conf`](#peadm--generate_pe_conf): Generate a pe.conf file in JSON format -* [`peadm::get_pe_conf`](#peadm--get_pe_conf) -* [`peadm::get_targets`](#peadm--get_targets): Accept undef or a SingleTargetSpec, and return an Array[Target, 1, 0]. This differs from get_target() in that: - It returns an Array[Target -* [`peadm::migration_opts_default`](#peadm--migration_opts_default) -* [`peadm::node_manager_yaml_location`](#peadm--node_manager_yaml_location) -* [`peadm::oid`](#peadm--oid) -* [`peadm::plan_step`](#peadm--plan_step) -* [`peadm::recovery_opts_all`](#peadm--recovery_opts_all) -* [`peadm::recovery_opts_default`](#peadm--recovery_opts_default) -* [`peadm::update_pe_conf`](#peadm--update_pe_conf): Update the pe.conf file on a target with the provided hash -* [`peadm::wait_until_service_ready`](#peadm--wait_until_service_ready): A convenience function to help remember port numbers for services and handle running the wait_until_service_ready task +- [`peadm::assert_supported_architecture`](#peadm--assert_supported_architecture): Assert that the architecture given is a supported one +- [`peadm::assert_supported_bolt_version`](#peadm--assert_supported_bolt_version): Assert that the Bolt executable running PEAdm is a supported version +- [`peadm::assert_supported_pe_version`](#peadm--assert_supported_pe_version): Assert that the PE version given is supported by PEAdm +- [`peadm::bolt_version`](#peadm--bolt_version) +- [`peadm::certname`](#peadm--certname): Return the certname of the given target-like input +- [`peadm::check_version_and_known_hosts`](#peadm--check_version_and_known_hosts): Checks PE verison and warns about setting r10k_known_hosts +- [`peadm::convert_hash`](#peadm--convert_hash): converts two arrays into hash +- [`peadm::convert_status`](#peadm--convert_status): Transforms a value in a human readable status with or without colors +- [`peadm::determine_status`](#peadm--determine_status): Produces a summarized hash of the given status data +- [`peadm::fail_on_transport`](#peadm--fail_on_transport): Fails if any nodes have the chosen transport. Useful for excluding PCP when it's not appopriate +- [`peadm::file_content_upload`](#peadm--file_content_upload) +- [`peadm::file_or_content`](#peadm--file_or_content) +- [`peadm::flatten_compact`](#peadm--flatten_compact) +- [`peadm::generate_pe_conf`](#peadm--generate_pe_conf): Generate a pe.conf file in JSON format +- [`peadm::get_pe_conf`](#peadm--get_pe_conf) +- [`peadm::get_targets`](#peadm--get_targets): Accept undef or a SingleTargetSpec, and return an Array[Target, 1, 0]. This differs from get_target() in that: - It returns an Array[Target +- [`peadm::migration_opts_default`](#peadm--migration_opts_default) +- [`peadm::node_manager_yaml_location`](#peadm--node_manager_yaml_location) +- [`peadm::oid`](#peadm--oid) +- [`peadm::plan_step`](#peadm--plan_step) +- [`peadm::recovery_opts_all`](#peadm--recovery_opts_all) +- [`peadm::recovery_opts_default`](#peadm--recovery_opts_default) +- [`peadm::update_pe_conf`](#peadm--update_pe_conf): Update the pe.conf file on a target with the provided hash +- [`peadm::wait_until_service_ready`](#peadm--wait_until_service_ready): A convenience function to help remember port numbers for services and handle running the wait_until_service_ready task ### Data types -* [`Peadm::Known_hosts`](#Peadm--Known_hosts) -* [`Peadm::Ldap_config`](#Peadm--Ldap_config) -* [`Peadm::Pe_version`](#Peadm--Pe_version) -* [`Peadm::Pem`](#Peadm--Pem) -* [`Peadm::Recovery_opts`](#Peadm--Recovery_opts) -* [`Peadm::SingleTargetSpec`](#Peadm--SingleTargetSpec): A SingleTargetSpec represents any String, Target or single-element array of one or the other that can be passed to get_targets() to return an +- [`Peadm::Known_hosts`](#Peadm--Known_hosts) +- [`Peadm::Ldap_config`](#Peadm--Ldap_config) +- [`Peadm::Pe_version`](#Peadm--Pe_version) +- [`Peadm::Pem`](#Peadm--Pem) +- [`Peadm::Recovery_opts`](#Peadm--Recovery_opts) +- [`Peadm::SingleTargetSpec`](#Peadm--SingleTargetSpec): A SingleTargetSpec represents any String, Target or single-element array of one or the other that can be passed to get_targets() to return an ### Tasks -* [`agent_install`](#agent_install): Install the Puppet agent from a master -* [`backup_classification`](#backup_classification): A task to call the classification api and write to file -* [`cert_data`](#cert_data): Return certificate data related to the Puppet agent -* [`cert_valid_status`](#cert_valid_status): Check primary for valid state of a certificate -* [`code_manager`](#code_manager): Perform various code manager actions -* [`code_sync_status`](#code_sync_status): A task to confirm code is in sync accross the cluster for clusters with code manager configured -* [`divert_code_manager`](#divert_code_manager): Divert the code manager live-dir setting -* [`download`](#download): Download a file using curl -* [`enable_replica`](#enable_replica): Execute the enable replica puppet command -* [`filesize`](#filesize): Return the size of a file in bytes -* [`get_peadm_config`](#get_peadm_config): Run on a PE primary node to return the currently configured PEAdm parameters -* [`get_psql_version`](#get_psql_version): Run on a PE PSQL node to return the major version of the PSQL server currently installed -* [`infrastatus`](#infrastatus): Runs puppet infra status and returns the output -* [`mkdir_p_file`](#mkdir_p_file): Create a file with the specified content at the specified location -* [`mv`](#mv): Wrapper task for mv command -* [`os_identification`](#os_identification): Return the operating system runnin gon the target as a string -* [`pe_install`](#pe_install): Install Puppet Enterprise from a tarball -* [`pe_ldap_config`](#pe_ldap_config): Set the ldap config in the PE console -* [`pe_uninstall`](#pe_uninstall): Uninstall Puppet Enterprise -* [`precheck`](#precheck): Return pre-check information about a system -* [`provision_replica`](#provision_replica): Execute the replica provision puppet command -* [`puppet_infra_upgrade`](#puppet_infra_upgrade): Execute the puppet infra upgrade command -* [`puppet_runonce`](#puppet_runonce): Run the Puppet agent one time -* [`rbac_token`](#rbac_token): Get and save an rbac token for the root user, admin rbac user -* [`read_file`](#read_file): Read the contents of a file -* [`reinstall_pe`](#reinstall_pe): Reinstall PE, only to be used to restore PE -* [`restore_classification`](#restore_classification): A short description of this task -* [`sign_csr`](#sign_csr): Submit a certificate signing request -* [`ssl_clean`](#ssl_clean): Clean an agent's certificate -* [`submit_csr`](#submit_csr): Submit a certificate signing request -* [`transform_classification_groups`](#transform_classification_groups): Transform the user groups from a source backup to a list of groups on the target server -* [`wait_until_service_ready`](#wait_until_service_ready): Return when the orchestrator service is healthy, or timeout after 15 seconds +- [`agent_install`](#agent_install): Install the Puppet agent from a master +- [`backup_classification`](#backup_classification): A task to call the classification api and write to file +- [`cert_data`](#cert_data): Return certificate data related to the Puppet agent +- [`cert_valid_status`](#cert_valid_status): Check primary for valid state of a certificate +- [`code_manager`](#code_manager): Perform various code manager actions +- [`code_sync_status`](#code_sync_status): A task to confirm code is in sync accross the cluster for clusters with code manager configured +- [`divert_code_manager`](#divert_code_manager): Divert the code manager live-dir setting +- [`download`](#download): Download a file using curl +- [`enable_replica`](#enable_replica): Execute the enable replica puppet command +- [`filesize`](#filesize): Return the size of a file in bytes +- [`get_peadm_config`](#get_peadm_config): Run on a PE primary node to return the currently configured PEAdm parameters +- [`get_psql_version`](#get_psql_version): Run on a PE PSQL node to return the major version of the PSQL server currently installed +- [`infrastatus`](#infrastatus): Runs puppet infra status and returns the output +- [`mkdir_p_file`](#mkdir_p_file): Create a file with the specified content at the specified location +- [`mv`](#mv): Wrapper task for mv command +- [`os_identification`](#os_identification): Return the operating system runnin gon the target as a string +- [`pe_install`](#pe_install): Install Puppet Enterprise from a tarball +- [`pe_ldap_config`](#pe_ldap_config): Set the ldap config in the PE console +- [`pe_uninstall`](#pe_uninstall): Uninstall Puppet Enterprise +- [`precheck`](#precheck): Return pre-check information about a system +- [`provision_replica`](#provision_replica): Execute the replica provision puppet command +- [`puppet_infra_upgrade`](#puppet_infra_upgrade): Execute the puppet infra upgrade command +- [`puppet_runonce`](#puppet_runonce): Run the Puppet agent one time +- [`rbac_token`](#rbac_token): Get and save an rbac token for the root user, admin rbac user +- [`read_file`](#read_file): Read the contents of a file +- [`reinstall_pe`](#reinstall_pe): Reinstall PE, only to be used to restore PE +- [`restore_classification`](#restore_classification): A short description of this task +- [`sign_csr`](#sign_csr): Submit a certificate signing request +- [`ssl_clean`](#ssl_clean): Clean an agent's certificate +- [`submit_csr`](#submit_csr): Submit a certificate signing request +- [`transform_classification_groups`](#transform_classification_groups): Transform the user groups from a source backup to a list of groups on the target server +- [`wait_until_service_ready`](#wait_until_service_ready): Return when the orchestrator service is healthy, or timeout after 15 seconds ### Plans #### Public Plans -* [`peadm::add_compiler`](#peadm--add_compiler): Add a new compiler to a PE architecture or replace an existing one with new configuration. -* [`peadm::add_database`](#peadm--add_database) -* [`peadm::add_replica`](#peadm--add_replica): Add or replace a replica host. -Supported use cases: -1: Adding a replica to an existing primary. -2: The existing replica is broken, we have a fresh new VM we want to provision the replica to. -* [`peadm::backup`](#peadm--backup): Backup puppet primary configuration -* [`peadm::backup_ca`](#peadm--backup_ca) -* [`peadm::convert`](#peadm--convert): Convert an existing PE cluster to a PEAdm-managed cluster -* [`peadm::install`](#peadm--install): Install a new PE cluster -* [`peadm::modify_certificate`](#peadm--modify_certificate): Modify the certificate of one or more targets -* [`peadm::restore`](#peadm--restore): Restore puppet primary configuration -* [`peadm::restore_ca`](#peadm--restore_ca) -* [`peadm::status`](#peadm--status): Return status information from one or more PE clusters in a table format -* [`peadm::upgrade`](#peadm--upgrade): Upgrade a PEAdm-managed cluster -* [`peadm::util::init_db_server`](#peadm--util--init_db_server) +- [`peadm::add_compiler`](#peadm--add_compiler): Add a new compiler to a PE architecture or replace an existing one with new configuration. +- [`peadm::add_database`](#peadm--add_database) +- [`peadm::add_replica`](#peadm--add_replica): Add or replace a replica host. + Supported use cases: + 1: Adding a replica to an existing primary. + 2: The existing replica is broken, we have a fresh new VM we want to provision the replica to. +- [`peadm::backup`](#peadm--backup): Backup puppet primary configuration +- [`peadm::backup_ca`](#peadm--backup_ca) +- [`peadm::convert`](#peadm--convert): Convert an existing PE cluster to a PEAdm-managed cluster +- [`peadm::install`](#peadm--install): Install a new PE cluster +- [`peadm::modify_certificate`](#peadm--modify_certificate): Modify the certificate of one or more targets +- [`peadm::restore`](#peadm--restore): Restore puppet primary configuration +- [`peadm::restore_ca`](#peadm--restore_ca) +- [`peadm::status`](#peadm--status): Return status information from one or more PE clusters in a table format +- [`peadm::upgrade`](#peadm--upgrade): Upgrade a PEAdm-managed cluster +- [`peadm::util::init_db_server`](#peadm--util--init_db_server) #### Private Plans -* `peadm::misc::divert_code_manager`: This plan exists to account for a scenario where a PE XL -* `peadm::modify_cert_extensions` -* `peadm::subplans::component_install`: Install a new PEADM component -* `peadm::subplans::configure`: Configure first-time classification and DR setup -* `peadm::subplans::db_populate`: Destructively (re)populates a new or existing database with the contents or a known good source -* `peadm::subplans::install`: Perform initial installation of Puppet Enterprise Extra Large -* `peadm::subplans::modify_certificate` -* `peadm::subplans::prepare_agent` -* `peadm::uninstall`: Single-entry-point plan for uninstalling Puppet Enterprise -* `peadm::util::code_sync_status` -* `peadm::util::copy_file` -* `peadm::util::db_disable_pglogical` -* `peadm::util::db_purge` -* `peadm::util::insert_csr_extension_requests` -* `peadm::util::retrieve_and_upload` -* `peadm::util::sanitize_pg_pe_conf` -* `peadm::util::update_classification`: Configure classification -* `peadm::util::update_db_setting`: Make updates to PuppetDB database settings +- `peadm::add_compiler`: Add a new compiler to a PE architecture or replace an existing one with new configuration. +- `peadm::add_replica`: Replace a replica host for a Standard or Large architecture. + Supported use cases: + 1: The existing replica is broken, we have a fresh new VM we want to provision the replica to. +- `peadm::convert_compiler_to_legacy` +- `peadm::misc::divert_code_manager`: This plan exists to account for a scenario where a PE XL +- `peadm::modify_cert_extensions` +- `peadm::subplans::component_install`: Install a new PEADM component +- `peadm::subplans::configure`: Configure first-time classification and DR setup +- `peadm::subplans::db_populate`: Destructively (re)populates a new or existing database with the contents or a known good source +- `peadm::subplans::install`: Perform initial installation of Puppet Enterprise Extra Large +- `peadm::subplans::modify_certificate` +- `peadm::subplans::prepare_agent` +- `peadm::uninstall`: Single-entry-point plan for uninstalling Puppet Enterprise +- `peadm::update_compiler_extensions` +- `peadm::util::code_sync_status` +- `peadm::util::copy_file` +- `peadm::util::db_disable_pglogical` +- `peadm::util::db_purge` +- `peadm::util::insert_csr_extension_requests` +- `peadm::util::retrieve_and_upload` +- `peadm::util::sanitize_pg_pe_conf` +- `peadm::util::update_classification`: Configure classification +- `peadm::util::update_db_setting`: Make updates to PuppetDB database settings ## Functions @@ -144,32 +151,22 @@ Returns: `Hash` Data type: `TargetSpec` - - ##### `replica_host` Data type: `Variant[TargetSpec, Undef]` - - ##### `primary_postgresql_host` Data type: `Variant[TargetSpec, Undef]` - - ##### `replica_postgresql_host` Data type: `Variant[TargetSpec, Undef]` - - ##### `compiler_hosts` Data type: `Variant[TargetSpec, Undef]` - - ### `peadm::assert_supported_bolt_version` Type: Puppet Language @@ -208,14 +205,10 @@ version number to check Data type: `String` - - ##### `permit_unsafe_versions` Data type: `Boolean` - - ### `peadm::bolt_version` Type: Ruby 4.x API @@ -241,12 +234,14 @@ is its certname. For strings, the certname is equal to the string. Undef input returns undef. #### `peadm::certname(Variant[Target, + String, Undef, Array[Target,1,1], Array[String,1,1], Array[Undef,1,1], - Array[Any,0,0]] $target)` + +Array[Any,0,0]] $target)` This function accepts a variety of data types which could represent single targets, and returns the certname corresponding to the input. @@ -272,8 +267,6 @@ Variant[Target, Array[Any,0,0]] ``` - - ### `peadm::check_version_and_known_hosts` Type: Puppet Language @@ -310,20 +303,14 @@ The r10k_known_hosts parameter Data type: `String` - - ##### `target_version` Data type: `String` - - ##### `r10k_known_hosts` Data type: `Optional[Peadm::Known_hosts]` - - ### `peadm::convert_hash` Type: Puppet Language @@ -605,20 +592,14 @@ Returns: `Any` Data type: `TargetSpec` - - ##### `transport` Data type: `String` - - ##### `message` Data type: `String` - - ### `peadm::file_content_upload` Type: Ruby 4.x API @@ -635,20 +616,14 @@ Returns: `Any` Data type: `String[1]` - - ##### `destination` Data type: `String[1]` - - ##### `*targets` Data type: `TargetOrTargets` - - ### `peadm::file_or_content` Type: Puppet Language @@ -665,20 +640,14 @@ Returns: `Any` Data type: `String` - - ##### `file` Data type: `Variant[String, Undef]` - - ##### `content` Data type: `Variant[String, Undef]` - - ### `peadm::flatten_compact` Type: Puppet Language @@ -695,8 +664,6 @@ Returns: `Any` Data type: `Array` - - ### `peadm::generate_pe_conf` Type: Puppet Language @@ -732,23 +699,23 @@ Returns: `Any` Data type: `Target` - - ### `peadm::get_targets` Type: Puppet Language Accept undef or a SingleTargetSpec, and return an Array[Target, 1, 0]. This differs from get_target() in that: - - It returns an Array[Target, 1, 0], rather than a Target - - It will accept undef and return [ ]. + +- It returns an Array[Target, 1, 0], rather than a Target +- It will accept undef and return [ ]. #### `peadm::get_targets(Variant[TargetSpec, Undef] $spec, Optional[Integer[1,1]] $count = undef)` Accept undef or a SingleTargetSpec, and return an Array[Target, 1, 0]. This differs from get_target() in that: - - It returns an Array[Target, 1, 0], rather than a Target - - It will accept undef and return [ ]. + +- It returns an Array[Target, 1, 0], rather than a Target +- It will accept undef and return [ ]. Returns: `Any` @@ -756,14 +723,10 @@ Returns: `Any` Data type: `Variant[TargetSpec, Undef]` - - ##### `count` Data type: `Optional[Integer[1,1]]` - - ### `peadm::migration_opts_default` Type: Puppet Language @@ -804,8 +767,6 @@ Returns: `Any` Data type: `String` - - ### `peadm::plan_step` Type: Ruby 4.x API @@ -822,14 +783,10 @@ Returns: `Any` Data type: `String` - - ##### `&block` Data type: `Callable` - - ### `peadm::recovery_opts_all` Type: Puppet Language @@ -896,14 +853,10 @@ Returns: `Any` Data type: `String` - - ##### `target` Data type: `TargetSpec` - - ## Data types ### `Peadm::Known_hosts` @@ -991,9 +944,9 @@ Struct[{ ### `Peadm::SingleTargetSpec` A SingleTargetSpec represents any String, Target or single-element array of -one or the other that can be passed to get_targets() to return an +one or the other that can be passed to get*targets() to return an Array[Target, 1, 1]. This is a constrained type variant of -Boltlib::TargetSpec for use when a _single_ target is valid, but multiple +Boltlib::TargetSpec for use when a \_single* target is valid, but multiple targets are not. Alias of `Variant[Pattern[/\A[^[:space:],]+\z/], Target, Array[Peadm::SingleTargetSpec, 1, 1]]` @@ -1564,17 +1517,17 @@ Add a new compiler to a PE architecture or replace an existing one with new conf The following parameters are available in the `peadm::add_compiler` plan: -* [`avail_group_letter`](#-peadm--add_compiler--avail_group_letter) -* [`compiler_host`](#-peadm--add_compiler--compiler_host) -* [`dns_alt_names`](#-peadm--add_compiler--dns_alt_names) -* [`primary_host`](#-peadm--add_compiler--primary_host) -* [`primary_postgresql_host`](#-peadm--add_compiler--primary_postgresql_host) +- [`avail_group_letter`](#-peadm--add_compiler--avail_group_letter) +- [`compiler_host`](#-peadm--add_compiler--compiler_host) +- [`dns_alt_names`](#-peadm--add_compiler--dns_alt_names) +- [`primary_host`](#-peadm--add_compiler--primary_host) +- [`primary_postgresql_host`](#-peadm--add_compiler--primary_postgresql_host) ##### `avail_group_letter` Data type: `Enum['A', 'B']` -_ Either A or B; whichever of the two letter designations the compiler is being assigned to +\_ Either A or B; whichever of the two letter designations the compiler is being assigned to Default value: `'A'` @@ -1582,13 +1535,13 @@ Default value: `'A'` Data type: `Peadm::SingleTargetSpec` -_ The hostname and certname of the new compiler +\_ The hostname and certname of the new compiler ##### `dns_alt_names` Data type: `Optional[String[1]]` -_ A comma_separated list of DNS alt names for the compiler +\_ A comma_separated list of DNS alt names for the compiler Default value: `undef` @@ -1596,13 +1549,13 @@ Default value: `undef` Data type: `Peadm::SingleTargetSpec` -_ The hostname and certname of the primary Puppet server +\_ The hostname and certname of the primary Puppet server ##### `primary_postgresql_host` Data type: `Optional[Peadm::SingleTargetSpec]` -_ The hostname and certname of the PE-PostgreSQL server with availability group $avail_group_letter +\_ The hostname and certname of the PE-PostgreSQL server with availability group $avail_group_letter Default value: `undef` @@ -1614,29 +1567,23 @@ The peadm::add_database class. The following parameters are available in the `peadm::add_database` plan: -* [`targets`](#-peadm--add_database--targets) -* [`primary_host`](#-peadm--add_database--primary_host) -* [`mode`](#-peadm--add_database--mode) -* [`begin_at_step`](#-peadm--add_database--begin_at_step) +- [`targets`](#-peadm--add_database--targets) +- [`primary_host`](#-peadm--add_database--primary_host) +- [`mode`](#-peadm--add_database--mode) +- [`begin_at_step`](#-peadm--add_database--begin_at_step) ##### `targets` Data type: `Peadm::SingleTargetSpec` - - ##### `primary_host` Data type: `Peadm::SingleTargetSpec` - - ##### `mode` Data type: `Optional[Enum['init', 'pair']]` - - Default value: `undef` ##### `begin_at_step` @@ -1653,8 +1600,6 @@ Optional[Enum[ 'finalize']] ``` - - Default value: `undef` ### `peadm::add_replica` @@ -1668,10 +1613,10 @@ Supported use cases: The following parameters are available in the `peadm::add_replica` plan: -* [`primary_host`](#-peadm--add_replica--primary_host) -* [`replica_host`](#-peadm--add_replica--replica_host) -* [`replica_postgresql_host`](#-peadm--add_replica--replica_postgresql_host) -* [`token_file`](#-peadm--add_replica--token_file) +- [`primary_host`](#-peadm--add_replica--primary_host) +- [`replica_host`](#-peadm--add_replica--replica_host) +- [`replica_postgresql_host`](#-peadm--add_replica--replica_postgresql_host) +- [`token_file`](#-peadm--add_replica--token_file) ##### `primary_host` @@ -1690,7 +1635,7 @@ Data type: `Peadm::SingleTargetSpec` Data type: `Optional[Peadm::SingleTargetSpec]` - The hostname and certname of the host with the replica PE-PosgreSQL database. -Can be a separate host in an XL architecture, or undef in Standard or Large. + Can be a separate host in an XL architecture, or undef in Standard or Large. Default value: `undef` @@ -1708,7 +1653,7 @@ Backup puppet primary configuration #### Examples -##### +##### ```puppet bolt plan run peadm::backup -t primary1.example.com @@ -1718,10 +1663,10 @@ bolt plan run peadm::backup -t primary1.example.com The following parameters are available in the `peadm::backup` plan: -* [`targets`](#-peadm--backup--targets) -* [`backup_type`](#-peadm--backup--backup_type) -* [`backup`](#-peadm--backup--backup) -* [`output_directory`](#-peadm--backup--output_directory) +- [`targets`](#-peadm--backup--targets) +- [`backup_type`](#-peadm--backup--backup_type) +- [`backup`](#-peadm--backup--backup) +- [`output_directory`](#-peadm--backup--output_directory) ##### `targets` @@ -1761,21 +1706,17 @@ The peadm::backup_ca class. The following parameters are available in the `peadm::backup_ca` plan: -* [`target`](#-peadm--backup_ca--target) -* [`output_directory`](#-peadm--backup_ca--output_directory) +- [`target`](#-peadm--backup_ca--target) +- [`output_directory`](#-peadm--backup_ca--output_directory) ##### `target` Data type: `Peadm::SingleTargetSpec` - - ##### `output_directory` Data type: `Optional[String]` - - Default value: `'/tmp'` ### `peadm::convert` @@ -1788,85 +1729,67 @@ management using PEAdm. The following parameters are available in the `peadm::convert` plan: -* [`primary_host`](#-peadm--convert--primary_host) -* [`replica_host`](#-peadm--convert--replica_host) -* [`compiler_hosts`](#-peadm--convert--compiler_hosts) -* [`primary_postgresql_host`](#-peadm--convert--primary_postgresql_host) -* [`replica_postgresql_host`](#-peadm--convert--replica_postgresql_host) -* [`compiler_pool_address`](#-peadm--convert--compiler_pool_address) -* [`internal_compiler_a_pool_address`](#-peadm--convert--internal_compiler_a_pool_address) -* [`internal_compiler_b_pool_address`](#-peadm--convert--internal_compiler_b_pool_address) -* [`dns_alt_names`](#-peadm--convert--dns_alt_names) -* [`begin_at_step`](#-peadm--convert--begin_at_step) +- [`primary_host`](#-peadm--convert--primary_host) +- [`replica_host`](#-peadm--convert--replica_host) +- [`compiler_hosts`](#-peadm--convert--compiler_hosts) +- [`primary_postgresql_host`](#-peadm--convert--primary_postgresql_host) +- [`replica_postgresql_host`](#-peadm--convert--replica_postgresql_host) +- [`compiler_pool_address`](#-peadm--convert--compiler_pool_address) +- [`internal_compiler_a_pool_address`](#-peadm--convert--internal_compiler_a_pool_address) +- [`internal_compiler_b_pool_address`](#-peadm--convert--internal_compiler_b_pool_address) +- [`dns_alt_names`](#-peadm--convert--dns_alt_names) +- [`begin_at_step`](#-peadm--convert--begin_at_step) ##### `primary_host` Data type: `Peadm::SingleTargetSpec` - - ##### `replica_host` Data type: `Optional[Peadm::SingleTargetSpec]` - - Default value: `undef` ##### `compiler_hosts` Data type: `Optional[TargetSpec]` - - Default value: `undef` ##### `primary_postgresql_host` Data type: `Optional[Peadm::SingleTargetSpec]` - - Default value: `undef` ##### `replica_postgresql_host` Data type: `Optional[Peadm::SingleTargetSpec]` - - Default value: `undef` ##### `compiler_pool_address` Data type: `String` - - Default value: `$primary_host` ##### `internal_compiler_a_pool_address` Data type: `Optional[String]` - - Default value: `undef` ##### `internal_compiler_b_pool_address` Data type: `Optional[String]` - - Default value: `undef` ##### `dns_alt_names` Data type: `Array[String]` - - Default value: `[]` ##### `begin_at_step` @@ -1881,8 +1804,6 @@ Optional[Enum[ 'finalize']] ``` - - Default value: `undef` ### `peadm::install` @@ -1893,34 +1814,34 @@ Install a new PE cluster The following parameters are available in the `peadm::install` plan: -* [`compiler_pool_address`](#-peadm--install--compiler_pool_address) -* [`internal_compiler_a_pool_address`](#-peadm--install--internal_compiler_a_pool_address) -* [`internal_compiler_b_pool_address`](#-peadm--install--internal_compiler_b_pool_address) -* [`pe_installer_source`](#-peadm--install--pe_installer_source) -* [`ldap_config`](#-peadm--install--ldap_config) -* [`final_agent_state`](#-peadm--install--final_agent_state) -* [`stagingdir`](#-peadm--install--stagingdir) -* [`uploaddir`](#-peadm--install--uploaddir) -* [`primary_host`](#-peadm--install--primary_host) -* [`replica_host`](#-peadm--install--replica_host) -* [`compiler_hosts`](#-peadm--install--compiler_hosts) -* [`primary_postgresql_host`](#-peadm--install--primary_postgresql_host) -* [`replica_postgresql_host`](#-peadm--install--replica_postgresql_host) -* [`console_password`](#-peadm--install--console_password) -* [`version`](#-peadm--install--version) -* [`dns_alt_names`](#-peadm--install--dns_alt_names) -* [`pe_conf_data`](#-peadm--install--pe_conf_data) -* [`code_manager_auto_configure`](#-peadm--install--code_manager_auto_configure) -* [`r10k_remote`](#-peadm--install--r10k_remote) -* [`r10k_private_key_file`](#-peadm--install--r10k_private_key_file) -* [`r10k_private_key_content`](#-peadm--install--r10k_private_key_content) -* [`r10k_known_hosts`](#-peadm--install--r10k_known_hosts) -* [`deploy_environment`](#-peadm--install--deploy_environment) -* [`license_key_file`](#-peadm--install--license_key_file) -* [`license_key_content`](#-peadm--install--license_key_content) -* [`download_mode`](#-peadm--install--download_mode) -* [`permit_unsafe_versions`](#-peadm--install--permit_unsafe_versions) -* [`token_lifetime`](#-peadm--install--token_lifetime) +- [`compiler_pool_address`](#-peadm--install--compiler_pool_address) +- [`internal_compiler_a_pool_address`](#-peadm--install--internal_compiler_a_pool_address) +- [`internal_compiler_b_pool_address`](#-peadm--install--internal_compiler_b_pool_address) +- [`pe_installer_source`](#-peadm--install--pe_installer_source) +- [`ldap_config`](#-peadm--install--ldap_config) +- [`final_agent_state`](#-peadm--install--final_agent_state) +- [`stagingdir`](#-peadm--install--stagingdir) +- [`uploaddir`](#-peadm--install--uploaddir) +- [`primary_host`](#-peadm--install--primary_host) +- [`replica_host`](#-peadm--install--replica_host) +- [`compiler_hosts`](#-peadm--install--compiler_hosts) +- [`primary_postgresql_host`](#-peadm--install--primary_postgresql_host) +- [`replica_postgresql_host`](#-peadm--install--replica_postgresql_host) +- [`console_password`](#-peadm--install--console_password) +- [`version`](#-peadm--install--version) +- [`dns_alt_names`](#-peadm--install--dns_alt_names) +- [`pe_conf_data`](#-peadm--install--pe_conf_data) +- [`code_manager_auto_configure`](#-peadm--install--code_manager_auto_configure) +- [`r10k_remote`](#-peadm--install--r10k_remote) +- [`r10k_private_key_file`](#-peadm--install--r10k_private_key_file) +- [`r10k_private_key_content`](#-peadm--install--r10k_private_key_content) +- [`r10k_known_hosts`](#-peadm--install--r10k_known_hosts) +- [`deploy_environment`](#-peadm--install--deploy_environment) +- [`license_key_file`](#-peadm--install--license_key_file) +- [`license_key_content`](#-peadm--install--license_key_content) +- [`download_mode`](#-peadm--install--download_mode) +- [`permit_unsafe_versions`](#-peadm--install--permit_unsafe_versions) +- [`token_lifetime`](#-peadm--install--token_lifetime) ##### `compiler_pool_address` @@ -2004,156 +1925,116 @@ Default value: `undef` Data type: `Peadm::SingleTargetSpec` - - ##### `replica_host` Data type: `Optional[Peadm::SingleTargetSpec]` - - Default value: `undef` ##### `compiler_hosts` Data type: `Optional[TargetSpec]` - - Default value: `undef` ##### `primary_postgresql_host` Data type: `Optional[Peadm::SingleTargetSpec]` - - Default value: `undef` ##### `replica_postgresql_host` Data type: `Optional[Peadm::SingleTargetSpec]` - - Default value: `undef` ##### `console_password` Data type: `String` - - ##### `version` Data type: `Peadm::Pe_version` - - Default value: `'2021.7.9'` ##### `dns_alt_names` Data type: `Optional[Array[String]]` - - Default value: `undef` ##### `pe_conf_data` Data type: `Optional[Hash]` - - Default value: `{}` ##### `code_manager_auto_configure` Data type: `Optional[Boolean]` - - Default value: `undef` ##### `r10k_remote` Data type: `Optional[String]` - - Default value: `undef` ##### `r10k_private_key_file` Data type: `Optional[String]` - - Default value: `undef` ##### `r10k_private_key_content` Data type: `Optional[Peadm::Pem]` - - Default value: `undef` ##### `r10k_known_hosts` Data type: `Optional[Peadm::Known_hosts]` - - Default value: `undef` ##### `deploy_environment` Data type: `Optional[String]` - - Default value: `undef` ##### `license_key_file` Data type: `Optional[String]` - - Default value: `undef` ##### `license_key_content` Data type: `Optional[String]` - - Default value: `undef` ##### `download_mode` Data type: `Enum['direct', 'bolthost']` - - Default value: `'bolthost'` ##### `permit_unsafe_versions` Data type: `Boolean` - - Default value: `false` ##### `token_lifetime` Data type: `String` - - Default value: `'1y'` ### `peadm::modify_certificate` @@ -2165,55 +2046,43 @@ setting DNS alternative names. The following parameters are available in the `peadm::modify_certificate` plan: -* [`targets`](#-peadm--modify_certificate--targets) -* [`primary_host`](#-peadm--modify_certificate--primary_host) -* [`add_extensions`](#-peadm--modify_certificate--add_extensions) -* [`remove_extensions`](#-peadm--modify_certificate--remove_extensions) -* [`dns_alt_names`](#-peadm--modify_certificate--dns_alt_names) -* [`force_regenerate`](#-peadm--modify_certificate--force_regenerate) +- [`targets`](#-peadm--modify_certificate--targets) +- [`primary_host`](#-peadm--modify_certificate--primary_host) +- [`add_extensions`](#-peadm--modify_certificate--add_extensions) +- [`remove_extensions`](#-peadm--modify_certificate--remove_extensions) +- [`dns_alt_names`](#-peadm--modify_certificate--dns_alt_names) +- [`force_regenerate`](#-peadm--modify_certificate--force_regenerate) ##### `targets` Data type: `TargetSpec` - - ##### `primary_host` Data type: `Peadm::SingleTargetSpec` - - ##### `add_extensions` Data type: `Hash` - - Default value: `{}` ##### `remove_extensions` Data type: `Array` - - Default value: `[]` ##### `dns_alt_names` Data type: `Optional[Array]` - - Default value: `undef` ##### `force_regenerate` Data type: `Boolean` - - Default value: `false` ### `peadm::restore` @@ -2222,7 +2091,7 @@ Restore puppet primary configuration #### Examples -##### +##### ```puppet bolt plan run peadm::restore -t primary1.example.com input_file=/tmp/peadm-backup.tar.gz @@ -2232,10 +2101,10 @@ bolt plan run peadm::restore -t primary1.example.com input_file=/tmp/peadm-backu The following parameters are available in the `peadm::restore` plan: -* [`targets`](#-peadm--restore--targets) -* [`restore_type`](#-peadm--restore--restore_type) -* [`restore`](#-peadm--restore--restore) -* [`input_file`](#-peadm--restore--input_file) +- [`targets`](#-peadm--restore--targets) +- [`restore_type`](#-peadm--restore--restore_type) +- [`restore`](#-peadm--restore--restore) +- [`input_file`](#-peadm--restore--input_file) ##### `targets` @@ -2273,28 +2142,22 @@ The peadm::restore_ca class. The following parameters are available in the `peadm::restore_ca` plan: -* [`target`](#-peadm--restore_ca--target) -* [`file_path`](#-peadm--restore_ca--file_path) -* [`recovery_directory`](#-peadm--restore_ca--recovery_directory) +- [`target`](#-peadm--restore_ca--target) +- [`file_path`](#-peadm--restore_ca--file_path) +- [`recovery_directory`](#-peadm--restore_ca--recovery_directory) ##### `target` Data type: `Peadm::SingleTargetSpec` - - ##### `file_path` Data type: `String` - - ##### `recovery_directory` Data type: `Optional[String]` - - Default value: `'/tmp/peadm_recovery'` ### `peadm::status` @@ -2313,11 +2176,11 @@ peadm::status($targets, 'table', true, true) The following parameters are available in the `peadm::status` plan: -* [`targets`](#-peadm--status--targets) -* [`format`](#-peadm--status--format) -* [`summarize`](#-peadm--status--summarize) -* [`verbose`](#-peadm--status--verbose) -* [`colors`](#-peadm--status--colors) +- [`targets`](#-peadm--status--targets) +- [`format`](#-peadm--status--format) +- [`summarize`](#-peadm--status--summarize) +- [`verbose`](#-peadm--status--verbose) +- [`colors`](#-peadm--status--colors) ##### `targets` @@ -2365,24 +2228,24 @@ Upgrade a PEAdm-managed cluster The following parameters are available in the `peadm::upgrade` plan: -* [`compiler_pool_address`](#-peadm--upgrade--compiler_pool_address) -* [`internal_compiler_a_pool_address`](#-peadm--upgrade--internal_compiler_a_pool_address) -* [`internal_compiler_b_pool_address`](#-peadm--upgrade--internal_compiler_b_pool_address) -* [`pe_installer_source`](#-peadm--upgrade--pe_installer_source) -* [`final_agent_state`](#-peadm--upgrade--final_agent_state) -* [`r10k_known_hosts`](#-peadm--upgrade--r10k_known_hosts) -* [`stagingdir`](#-peadm--upgrade--stagingdir) -* [`uploaddir`](#-peadm--upgrade--uploaddir) -* [`primary_host`](#-peadm--upgrade--primary_host) -* [`replica_host`](#-peadm--upgrade--replica_host) -* [`compiler_hosts`](#-peadm--upgrade--compiler_hosts) -* [`primary_postgresql_host`](#-peadm--upgrade--primary_postgresql_host) -* [`replica_postgresql_host`](#-peadm--upgrade--replica_postgresql_host) -* [`version`](#-peadm--upgrade--version) -* [`token_file`](#-peadm--upgrade--token_file) -* [`download_mode`](#-peadm--upgrade--download_mode) -* [`permit_unsafe_versions`](#-peadm--upgrade--permit_unsafe_versions) -* [`begin_at_step`](#-peadm--upgrade--begin_at_step) +- [`compiler_pool_address`](#-peadm--upgrade--compiler_pool_address) +- [`internal_compiler_a_pool_address`](#-peadm--upgrade--internal_compiler_a_pool_address) +- [`internal_compiler_b_pool_address`](#-peadm--upgrade--internal_compiler_b_pool_address) +- [`pe_installer_source`](#-peadm--upgrade--pe_installer_source) +- [`final_agent_state`](#-peadm--upgrade--final_agent_state) +- [`r10k_known_hosts`](#-peadm--upgrade--r10k_known_hosts) +- [`stagingdir`](#-peadm--upgrade--stagingdir) +- [`uploaddir`](#-peadm--upgrade--uploaddir) +- [`primary_host`](#-peadm--upgrade--primary_host) +- [`replica_host`](#-peadm--upgrade--replica_host) +- [`compiler_hosts`](#-peadm--upgrade--compiler_hosts) +- [`primary_postgresql_host`](#-peadm--upgrade--primary_postgresql_host) +- [`replica_postgresql_host`](#-peadm--upgrade--replica_postgresql_host) +- [`version`](#-peadm--upgrade--version) +- [`token_file`](#-peadm--upgrade--token_file) +- [`download_mode`](#-peadm--upgrade--download_mode) +- [`permit_unsafe_versions`](#-peadm--upgrade--permit_unsafe_versions) +- [`begin_at_step`](#-peadm--upgrade--begin_at_step) ##### `compiler_pool_address` @@ -2466,70 +2329,52 @@ Default value: `'/tmp'` Data type: `Peadm::SingleTargetSpec` - - ##### `replica_host` Data type: `Optional[Peadm::SingleTargetSpec]` - - Default value: `undef` ##### `compiler_hosts` Data type: `Optional[TargetSpec]` - - Default value: `undef` ##### `primary_postgresql_host` Data type: `Optional[Peadm::SingleTargetSpec]` - - Default value: `undef` ##### `replica_postgresql_host` Data type: `Optional[Peadm::SingleTargetSpec]` - - Default value: `undef` ##### `version` Data type: `Optional[Peadm::Pe_version]` - - Default value: `undef` ##### `token_file` Data type: `Optional[String]` - - Default value: `undef` ##### `download_mode` Data type: `Enum[direct,bolthost]` - - Default value: `'bolthost'` ##### `permit_unsafe_versions` Data type: `Boolean` - - Default value: `false` ##### `begin_at_step` @@ -2546,8 +2391,6 @@ Optional[Enum[ 'finalize']] ``` - - Default value: `undef` ### `peadm::util::init_db_server` @@ -2558,38 +2401,29 @@ The peadm::util::init_db_server class. The following parameters are available in the `peadm::util::init_db_server` plan: -* [`db_host`](#-peadm--util--init_db_server--db_host) -* [`install_pe`](#-peadm--util--init_db_server--install_pe) -* [`pe_version`](#-peadm--util--init_db_server--pe_version) -* [`pe_platform`](#-peadm--util--init_db_server--pe_platform) +- [`db_host`](#-peadm--util--init_db_server--db_host) +- [`install_pe`](#-peadm--util--init_db_server--install_pe) +- [`pe_version`](#-peadm--util--init_db_server--pe_version) +- [`pe_platform`](#-peadm--util--init_db_server--pe_platform) ##### `db_host` Data type: `String[1]` - - ##### `install_pe` Data type: `Boolean` - - Default value: `false` ##### `pe_version` Data type: `String[1]` - - Default value: `'2023.5.0'` ##### `pe_platform` Data type: `String[1]` - - Default value: `'el-8-x86_64'` - diff --git a/documentation/convert.md b/documentation/convert.md index 6d2c8095..30242ef0 100644 --- a/documentation/convert.md +++ b/documentation/convert.md @@ -15,14 +15,14 @@ Prepare to run the plan against all servers in the PE infrastructure, using a pa "pe-xl-compiler-1.lab1.puppet.vm" ], - "compiler_pool_address": "puppet.lab1.puppet.vm", + "compiler_pool_address": "puppet.lab1.puppet.vm" } ``` -See the [install](install.md#reference-architectures) documentation for a list of supported architectures. Note that for convert, *all infrastructure being converted must already be functional*; you cannot use convert to add new systems to the infrastructure, nor can you use it to change your architecture. +See the [install](install.md#reference-architectures) documentation for a list of supported architectures. Note that for convert, _all infrastructure being converted must already be functional_; you cannot use convert to add new systems to the infrastructure, nor can you use it to change your architecture. ``` -bolt plan run peadm::convert --params @params.json +bolt plan run peadm::convert --params @params.json ``` ## Retry or resume plan @@ -30,3 +30,17 @@ bolt plan run peadm::convert --params @params.json This plan is broken down into steps. Normally, the plan runs through all the steps from start to finish. The name of each step is displayed during the plan run, as the step begins. The `begin_at_step` parameter can be used to facilitate re-running this plan after a failed attempt, skipping past any steps that already completed successfully on the first try and picking up again at the step specified. The step name to resume at can be read from the previous run logs. A full list of available values for this parameter can be viewed by running `bolt plan show peadm::convert`. + +## Convert compilers to legacy + +### Puppet Enterprise installed with puppetlabs-peadm version 3.21 or later + +To convert compilers to legacy compilers use the `peadm::convert_compiler_to_legacy` plan. This plan will create the needed Node group and Classifier rules to make the compilers legacy. Also will add certificate extensions to those nodes. + +```shell +bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com +``` + +### Puppet Enterprise installed with puppetlabs-peadm version prior to 3.21 + +Follow Steps 1 to 3 in the [Upgrade Puppet Enterprise with legacy compilers](upgrade_with_legacy_compilers.md) documentation. diff --git a/documentation/upgrade_with_legacy_compilers.md b/documentation/upgrade_with_legacy_compilers.md new file mode 100644 index 00000000..b33f4bf5 --- /dev/null +++ b/documentation/upgrade_with_legacy_compilers.md @@ -0,0 +1,45 @@ +# Upgrade Puppet Enterprise with legacy compilers + +## What is a legacy compiler and a current compiler + +As a legacy compiler we refer to a compiler that doesn't have PuppetDB. And a current Compiler is a compiler that has PuppetDB. By default, latest versions of Puppet enterprise comes with compilers that have PuppetDB.If your primary server and compilers are connected with high-latency links or congested network segments, you might experience better PuppetDB performance with legacy compilers. + +## Who is this documentation for + +For those users that have installed Puppet Enterprise with puppetlabs-peadm prior version 3.21 and manually converted their existing complilers (all of the or at least 1) to legacy compilers. + +## Who is this documentation not for + +For those users that have installed Puppet Enterprise with PEADM with 3.21 version or later, there is no need to follow this documentation. The install process will automatically have created the necessary configurations for you and you can use the `peadm::convert_compiler_to_legacy` plan if you need a legacy compiler. example: + +```shell +bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com +``` + +## How to upgrade Puppet Enterprise with legacy compilers + +### 1. Revert changes to the legacy compilers nodes + +Usually users pin the nodes in the Pe Master Node Group and then manually removing PuppetDB from compilers nodes. To revert this changes go to your Puppet Enterprise console and unpin the compilers nodes from the Group. + +### 2. Update certificate extensions for NON legacy compilers + +If you have NON legacy compilers in your infrastructure, you have to add a certificate extension to them that recognizes them as NON legacy compilers. To do this, execute the following plan: + +```shell +bolt plan run peadm::update_compiler_extensions primary_host=primary.example.com compiler_hosts=compiler1.example.com,compiler2.example.com +``` + +### 3. Use the convert legacy compiler plan + +Now that we have unpinned the compilers nodes from the PE Master node group, execute the following plan to convert your needed compilers to legacy compilers: + +```shell +bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com +``` + +The above will create the needed Node group and Classifier rules to make the compilers legacy. Also will add certificate extensions to those nodes. + +### 4. Upgrade Puppet Enterprise + +After you have completed the above steps, you can proceed with the upgrade of Puppet Enterprise as usual using the puppetlabs-peadm module. There is no need to do the above ever again. diff --git a/functions/oid.pp b/functions/oid.pp index 2fc735d0..0f03a43c 100644 --- a/functions/oid.pp +++ b/functions/oid.pp @@ -4,6 +4,7 @@ function peadm::oid ( case $short_name { 'peadm_role': { '1.3.6.1.4.1.34380.1.1.9812' } 'peadm_availability_group': { '1.3.6.1.4.1.34380.1.1.9813' } + 'peadm_legacy_compiler': { '1.3.6.1.4.1.34380.1.1.9814' } 'pp_application': { '1.3.6.1.4.1.34380.1.1.8' } 'pp_cluster': { '1.3.6.1.4.1.34380.1.1.16' } 'pp_role': { '1.3.6.1.4.1.34380.1.1.13' } diff --git a/manifests/setup/legacy_compiler_group.pp b/manifests/setup/legacy_compiler_group.pp new file mode 100644 index 00000000..1311f2f2 --- /dev/null +++ b/manifests/setup/legacy_compiler_group.pp @@ -0,0 +1,50 @@ +# @api private +class peadm::setup::legacy_compiler_group ( + String[1] $primary_host +) { + Node_group { + purge_behavior => none, + } + + node_group { 'PE Legacy Compiler': + parent => 'PE Master', + rule => ['and', + ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'], + ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'], + ], + classes => { + 'pe_repo' => {}, + 'puppet_enterprise::profile::master' => { 'code_manager_auto_configure' => true, 'replication_mode' => 'none' }, + }, + data => { + 'pe_repo' => { 'compile_master_pool_address' => $primary_host }, + }, + variables => { + 'pe_master' => true, + }, + } + + node_group { 'PE Legacy Compiler Group A': + ensure => 'present', + parent => 'PE Legacy Compiler', + rule => ['and', + ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'], + ['=', ['trusted', 'extensions', peadm::oid('peadm_availability_group')], 'A'], + ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'], + ], + } + + node_group { 'PE Legacy Compiler Group B': + ensure => 'present', + parent => 'PE Legacy Compiler', + rule => ['and', + ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'], + ['=', ['trusted', 'extensions', peadm::oid('peadm_availability_group')], 'B'], + ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'], + ], + } + + node_group { 'PE Compiler': + rule => ['and', ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'false']], + } +} diff --git a/manifests/setup/node_manager.pp b/manifests/setup/node_manager.pp index 65c69044..f14d08bb 100644 --- a/manifests/setup/node_manager.pp +++ b/manifests/setup/node_manager.pp @@ -79,6 +79,12 @@ variables => { 'pe_master' => true }, } + # PE Compiler group comes from default PE and already has the pe compiler role + node_group { 'PE Compiler': + parent => 'PE Master', + rule => ['and', ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'false']], + } + # This group should pin the primary, and also map to any pe-postgresql nodes # which are part of the architecture. node_group { 'PE Database': @@ -115,6 +121,7 @@ rule => ['and', ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'], ['=', ['trusted', 'extensions', peadm::oid('peadm_availability_group')], 'A'], + ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'false'], ], classes => { 'puppet_enterprise::profile::puppetdb' => { @@ -173,6 +180,7 @@ rule => ['and', ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'], ['=', ['trusted', 'extensions', peadm::oid('peadm_availability_group')], 'B'], + ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'false'], ], classes => { 'puppet_enterprise::profile::puppetdb' => { @@ -192,4 +200,46 @@ }, }, } + + node_group { 'PE Legacy Compiler': + parent => 'PE Master', + rule => ['and', + ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'], + ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'], + ], + classes => { + 'pe_repo' => {}, + 'puppet_enterprise::profile::master' => { 'code_manager_auto_configure' => true, 'replication_mode' => 'none' }, + }, + data => { + 'pe_repo' => { 'compile_master_pool_address' => $primary_host }, + }, + variables => { + 'pe_master' => true, + }, + } + + # Configure the A pool for legacy compilers. There are up to two pools for DR, each + # having an affinity for one "availability zone" or the other. + node_group { 'PE Legacy Compiler Group A': + ensure => 'present', + parent => 'PE Legacy Compiler', + rule => ['and', + ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'], + ['=', ['trusted', 'extensions', peadm::oid('peadm_availability_group')], 'A'], + ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'], + ], + } + + # Configure the B pool for legacy compilers. There are up to two pools for DR, each + # having an affinity for one "availability zone" or the other. + node_group { 'PE Legacy Compiler Group B': + ensure => 'present', + parent => 'PE Legacy Compiler', + rule => ['and', + ['=', ['trusted', 'extensions', 'pp_auth_role'], 'pe_compiler'], + ['=', ['trusted', 'extensions', peadm::oid('peadm_availability_group')], 'B'], + ['=', ['trusted', 'extensions', peadm::oid('peadm_legacy_compiler')], 'true'], + ], + } } diff --git a/plans/convert_compiler_to_legacy.pp b/plans/convert_compiler_to_legacy.pp new file mode 100644 index 00000000..69be62b3 --- /dev/null +++ b/plans/convert_compiler_to_legacy.pp @@ -0,0 +1,58 @@ +# @api private +plan peadm::convert_compiler_to_legacy ( + Peadm::SingleTargetSpec $primary_host, + TargetSpec $legacy_hosts, + Boolean $remove_pdb = false, +) { + $primary_target = peadm::get_targets($primary_host, 1) + $legacy_targets = peadm::get_targets($legacy_hosts) + + $cluster = run_task('peadm::get_peadm_config', $primary_host).first.value + $error = getvar('cluster.error') + if $error { + fail_plan($error) + } + + $all_targets = peadm::flatten_compact([ + getvar('cluster.params.primary_host'), + getvar('cluster.params.replica_host'), + getvar('cluster.params.primary_postgresql_host'), + getvar('cluster.params.replica_postgresql_host'), + getvar('cluster.params.compiler_hosts'), + ]) + + if $remove_pdb { + run_command('puppet resource service puppet ensure=stopped', $legacy_targets) + run_command('puppet resource service pe-puppetdb ensure=stopped enable=false', $legacy_targets) + } + + apply($primary_target) { + class { 'peadm::setup::node_manager_yaml': + primary_host => $primary_target.peadm::certname(), + } + + class { 'peadm::setup::legacy_compiler_group': + primary_host => $primary_target.peadm::certname(), + } + } + + run_plan('peadm::update_compiler_extensions', compiler_hosts => $legacy_targets, primary_host => $primary_target, legacy => true) + + run_task('peadm::puppet_runonce', $legacy_targets) + run_task('peadm::puppet_runonce', $primary_target) + run_task('peadm::puppet_runonce', $all_targets) + + if $remove_pdb { + run_command('puppet resource package pe-puppetdb ensure=purged', $legacy_targets) + run_command('puppet resource user pe-puppetdb ensure=absent', $legacy_targets) + + run_command('rm -rf /etc/puppetlabs/puppetdb', $legacy_targets) + run_command('rm -rf /var/log/puppetlabs/puppetdb', $legacy_targets) + run_command('rm -rf /opt/puppetlabs/server/data/puppetdb', $legacy_targets) + } + + run_command('systemctl start pe-puppetserver.service', $legacy_targets) + run_command('puppet resource service puppet ensure=running', $legacy_targets) + + return("Converted host ${legacy_targets} to legacy compiler.") +} diff --git a/plans/subplans/component_install.pp b/plans/subplans/component_install.pp index df74079e..daf11688 100644 --- a/plans/subplans/component_install.pp +++ b/plans/subplans/component_install.pp @@ -22,6 +22,10 @@ peadm::oid('pp_auth_role') => 'pe_compiler', peadm::oid('peadm_availability_group') => $avail_group_letter, } + } elsif $role == 'pe_compiler_legacy' { + $certificate_extensions = { + peadm::oid('peadm_role') => $role, + } } else { $certificate_extensions = { peadm::oid('peadm_role') => $role, diff --git a/plans/subplans/install.pp b/plans/subplans/install.pp index 7d48cb8a..88930218 100644 --- a/plans/subplans/install.pp +++ b/plans/subplans/install.pp @@ -278,6 +278,7 @@ extension_requests => { peadm::oid('pp_auth_role') => 'pe_compiler', peadm::oid('peadm_availability_group') => 'A', + peadm::oid('peadm_legacy_compiler') => 'false', } ) }, @@ -286,6 +287,7 @@ extension_requests => { peadm::oid('pp_auth_role') => 'pe_compiler', peadm::oid('peadm_availability_group') => 'B', + peadm::oid('peadm_legacy_compiler') => 'false', } ) }, diff --git a/plans/update_compiler_extensions.pp b/plans/update_compiler_extensions.pp new file mode 100644 index 00000000..784f919e --- /dev/null +++ b/plans/update_compiler_extensions.pp @@ -0,0 +1,25 @@ +# @api private +plan peadm::update_compiler_extensions ( + TargetSpec $compiler_hosts, + Peadm::SingleTargetSpec $primary_host, + Boolean $legacy = false, +) { + $primary_target = peadm::get_targets($primary_host, 1) + $host_targets = peadm::get_targets($compiler_hosts) + + run_plan('peadm::modify_certificate', $host_targets, + primary_host => $primary_target, + add_extensions => { peadm::oid('peadm_legacy_compiler') => String($legacy) }, + ) + + run_task('peadm::puppet_runonce', $primary_target) + run_task('peadm::puppet_runonce', $host_targets) + + if $legacy { + run_command('systemctl restart pe-puppetserver.service', $host_targets) + } else { + run_command('systemctl restart pe-puppetserver.service pe-puppetdb.service', $host_targets) + } + + return("Added legacy cert with value ${legacy} to compiler hosts ${compiler_hosts}") +} diff --git a/plans/upgrade.pp b/plans/upgrade.pp index b9adcd38..63375829 100644 --- a/plans/upgrade.pp +++ b/plans/upgrade.pp @@ -167,11 +167,25 @@ == $cert_extensions.dig($primary_target[0].peadm::certname, peadm::oid('peadm_availability_group'))) } + $compiler_m1_nonlegacy_targets = $compiler_targets.filter |$target| { + ($cert_extensions.dig($target.peadm::certname, peadm::oid('peadm_availability_group')) + == $cert_extensions.dig($primary_target[0].peadm::certname, peadm::oid('peadm_availability_group'))) and + ($cert_extensions.dig($target.peadm::certname, peadm::oid('peadm_legacy_compiler')) + == 'false') + } + $compiler_m2_targets = $compiler_targets.filter |$target| { ($cert_extensions.dig($target.peadm::certname, peadm::oid('peadm_availability_group')) == $cert_extensions.dig($replica_target[0].peadm::certname, peadm::oid('peadm_availability_group'))) } + $compiler_m2_nonlegacy_targets = $compiler_targets.filter |$target| { + ($cert_extensions.dig($target.peadm::certname, peadm::oid('peadm_availability_group')) + == $cert_extensions.dig($replica_target[0].peadm::certname, peadm::oid('peadm_availability_group'))) and + ($cert_extensions.dig($target.peadm::certname, peadm::oid('peadm_legacy_compiler')) + == 'false') + } + peadm::plan_step('preparation') || { if $download_mode == 'bolthost' { # Download the PE tarball on the nodes that need it @@ -239,7 +253,7 @@ peadm::plan_step('upgrade-primary') || { # Shut down PuppetDB on CMs that use the PM's PDB PG. Use run_command instead # of run_task(service, ...) so that upgrading from 2018.1 works over PCP. - run_command('systemctl stop pe-puppetdb', $compiler_m1_targets) + run_command('systemctl stop pe-puppetdb', $compiler_m1_nonlegacy_targets) run_task('peadm::pe_install', $primary_postgresql_target, tarball => $upload_tarball_path, @@ -344,7 +358,7 @@ # Shut down PuppetDB on CMs that use the replica's PDB PG. Use run_command # instead of run_task(service, ...) so that upgrading from 2018.1 works # over PCP. - run_command('systemctl stop pe-puppetdb', $compiler_m2_targets) + run_command('systemctl stop pe-puppetdb', $compiler_m2_nonlegacy_targets) run_task('peadm::pe_install', $replica_postgresql_target, tarball => $upload_tarball_path, diff --git a/spec/acceptance/peadm_spec/plans/provision_test_cluster.pp b/spec/acceptance/peadm_spec/plans/provision_test_cluster.pp index aecd8197..4529dc9b 100644 --- a/spec/acceptance/peadm_spec/plans/provision_test_cluster.pp +++ b/spec/acceptance/peadm_spec/plans/provision_test_cluster.pp @@ -20,6 +20,9 @@ 'large': { ['primary', 'compiler'] } + 'large-with-two-compilers': { + ['primary', 'compiler', 'compiler'] + } 'large-with-dr': { ['primary', 'compiler', 'replica', 'compiler'] }