RefArchSetup is a Ruby gem designed to help install the various Puppet Reference Architectures. It currently supports the Standard Reference Architecture.

RefArchSetup uses Puppet Bolt to automate the PE installation steps.

RefArchSetup executes Bolt commands as the root user using the --run-as root option to ensure a successful PE installation. See the Bolt Options section for more information.

RefArchSetup supports the following platforms:

RefArchSetup supports PE versions greater than 2018.1.0.

RefArchSetup currently supports the Standard Architecture.

Install Bolt using the instructions for your platform.

RefArchSetup should be installed using the version of Ruby provided by Bolt. This eliminates the need to install Ruby separately but does require specifying the Bolt path when installing RefArchSetup.

RefArchSetup can be installed via RubyGems or by building the gem locally.

The easiest way to install RefArchSetup is via RubyGems:

    $ /opt/puppetlabs/bolt/bin/gem install ref_arch_setup

To build the gem locally:

• Clone the RefArchSetup repository and install the dependencies by following the steps in the Getting Started section in CONTRIBUTING.md.
• From your local copy of the repository, build the gem using the provided rake task:

    $ ~/ref_arch_setup> bundle exec rake gem:build

• The gem will be built to the pkg directory; install the gem by either specifying the path to the RAS gem provided in the output from the previous step:

    $ ~/ref_arch_setup> /opt/puppetlabs/bolt/bin/gem install pkg/ref_arch_setup-0.0.x

or navigate to the pkg directory first, in which case specifying the version is not required:

    $ ~/ref_arch_setup> cd pkg && /opt/puppetlabs/bolt/bin/gem install ref_arch_setup && cd ..

The Bolt path must be specified when running RefArchSetup. This can be avoided by running the following command:

    $ ln -s /opt/puppetlabs/bolt/bin/ref_arch_setup /usr/local/bin/ref_arch_setup

RefArchSetup provides help on the command line. Run the ref_arch_setup command with the -h option to display the available commands and options:

    $ ref_arch_setup -h
    Usage: ref_arch_setup <command> [subcommand] [options]
  
    Available Commands:
  
      install                         - Install a bootstrapped PE on target host
      install generate-pe-conf        - Generates a pe.conf for the install
      install bootstrap               - Installs a bare PE on the target host
      install pe-infra-agent-install  - Installs agents on all PE
                                        infrastructure nodes
      install configure               - Configures PE infrastructure nodes to
                                        reference architecture settings
  
    Available Options:
  
      -h, --help                       Prints this help
      -v, --version                    Show current version of ref_arch_setup
      

Run the ref_arch_setup install sub-command with the -h option to display the available sub-commands and options:

    $ ref_arch_setup install -h
    Usage: ref_arch_setup install [options]

    Runs the install subcommands in the following order:
      generate-pe-conf (unless --pe-conf is provided)
      bootstrap
      pe-infra-agent-install (noop for "Standard" ref arch)
      configure

    Available Options:
      Either --console-password or --pe-conf required
        --user <username>               SSH username for bolt ssh to target host
        --password <password>           SSH password for bolt ssh to target host
        --private-key <path>            Path to SSH private key file for bolt
                                        ssh to target host
        --sudo-password <password>      Root user password for privilege escalation
        --console-password <password>   Password for the PE console
        --primary-master <hostname>     Hostname of primary master
        --pe-tarball <path|URL>         Path or URL to PE tarball
        --pe-version <version>          PE version to get tarball for
        --pe-conf <path>                Path to pe.conf file

Install PE on the desired primary master using the install command. For example:

    $ ref_arch_setup install --primary-master=localhost --pe-version=latest --pe-conf=/path/to/pe.conf

RefArchSetup is currently in development and as such not all subcommands are currently available. Currently only the bootstrap subcommand is implemented; other subcommands run in a noop mode.

This subcommand has not been implemented.

This subcommand runs the bootstrap portion of the install which includes the following steps:

• Download the PE tarball or verify a local tarball if specified
• Extract the tarball
• Run the PE installer
• Run the Puppet agent until no changes are reported

This subcommand has not been implemented.

This subcommand has not been implemented.

RefArchSetup can perform the PE installation with a local or remote primary master.

To perform the PE installation on the same host where RefArchSetup is run, specify --primary-master=localhost.

To perform the PE installation on a remote host, specify --primary-master=my.remote.master. If a remote host is specified it must be accessible to Bolt; see the Bolt Options section for more information.

Specifying a PE tarball is optional, but if the option is specified it will override the --pe-version option.

To install PE using a tarball URL, specify --pe-tarball=https://my.host.tarball.tar.gz.

To install PE using a tarball on a local or remote filesystem, specify --pe-tarball=/path/to/tarball.tar.gz.

RefArchSetup can install a specific version of PE or the latest version. See the Puppet Enterprise Version History for a comprehensive list of PE versions.

To install a specific version of PE, specify the version number: --pe-version=2018.1.4.

To install the latest version, specify --pe-version=latest.

PE installation requires a valid pe.conf file. At a minimum the "console_admin_password" option must be specified. RefArchSetup provides a default pe.conf file. Specify the path to the pe.conf file: --pe-conf=/path/to/pe.conf

RefArchSetup executes Bolt commands as the root user using the --run-as option. If RefArchSetup is run as a user other than root the sudo password must be specified: --sudo-password=mysudopassword

To execute Bolt commands via ssh with a user other than the user running RefArchSetup, specify --user=my.ssh.user. Bolt can authenticate using a password or a private key file.

To authenticate using a password, specify --password=mypassword.

To authenticate using a private key, specify --private-key=/path/to/my_key.rsa.

See LICENSE file.

Please log tickets and issues in the SLV project.

For additional information on filing tickets, please check out our CONTRIBUTOR doc.

For information on project maintainers, please check out our MAINTAINERS doc.