5.3.3. HOWTO Set up a SIMP Environment in a Control Repository

This HOWTO describes how to create Puppet control repositories for use with a Control Repository deployment scenario.

5.3.3.1. Requirements

To use any of the procedures in this section, you must:

  1. Have access to a remotely-hosted Git repository where you will host your control repository.

  2. Have a basic understanding of:

You may find it helpful to read the section that explains how a control repository works in Puppet, Inc.’s control repository documentation .

5.3.3.2. Creating a Control Repository on a SIMP Server

This procedure creates an r10k control repository from a fresh SIMP ISO/RPM installation. It is currently limited to just the control repository—the RPM-provided Puppet module git repositories will remain on the SIMP server’s local filesystem.

Important

This procedure does NOT describe how to migrate or host SIMP Puppet modules in remote git Repositories, or how to update the Puppetfile.simp file to deploy them.

Prerequisites

  • You have installed SIMP (per the installation guide) from ISO or RPM Repository.

  • This procedure needs to be done on the SIMP server.

Procedure

  1. Create a git repository inside the production Puppet environment directory:

    cd /etc/puppetlabs/code/environments/production
    git init .
    
  2. Create a new branch for the production Puppet environment:

    git checkout -b production
    
  3. Add files to the git repository. (Do not add the modules/ directory or .resource_types/ directory):

    # Add the files
    git add Puppetfile Puppetfile.simp hiera.yaml environment.conf
    
    # Add directories
    git add manifests/ data/
    
  4. Commit the changes

    git commit -m "Initial production environment"
    
  5. Push the branch to your control repository:

    # Add a remote for your control repository
    git remote add control_repo <URL to the control repo>
    
    # Push the branch
    git push production control_repo
    

5.3.3.3. Creating a Control Repository without SIMP installed

This procedure creates a control repository with a branch for an environment named called dev1. The Puppet modules will be deployed from the SIMP project’s public git repositories over the internet.

Important

If you intend to use this environment to bootstrap a SIMP server without RPMs, it must be named production (and not dev1).

Prerequisites

You will need the SIMP Puppet environment “skeleton” directory, which can be obtained from one of the following sources:

1

If your working host doesn’t have the simp-environment-skeleton RPM and you’d like to install it, you can set up the SIMP yum repositories (see “Installing SIMP From A Repository).”

Procedure

  1. Create an empty git repository:

    mkdir $HOME/control-repo
    cd $HOME/control-repo
    git init .
    
  2. Copy the puppet environment skeleton into your git repository:

    cd $HOME/control-repo
    cp -R /usr/share/simp/environment-skeleton/puppet/* .
    
  3. Substitute your environment’s name into environment.conf:

    sed -e "s/%%SKELETON_ENVIRONMENT%%/dev1/g" ./environment.conf.TEMPLATE > ./environment.conf
    chmod 640 environment.conf
    rm environment.conf.TEMPLATE
    
  4. Download and edit the Puppetfile.simp file:

    1. Download the Puppetfile used to create a SIMP ISO for a specific release from the SIMP simp-core repository (in this example, it is 6.4.0-0):

      cd /etc/puppetlabs/code/environments/dev1
      curl -o Puppetfile.simp https://github.com/simp/simp-core/blob/6.4.0-0/Puppetfile.pinned
      
    2. Edit Puppetfile.simp to remove components that are not Puppet modules, deleting all lines up to and including moduledir 'src/puppet/modules'. You can do this from the command line by running:

      sed -i -e "0,/^moduledir 'src\/puppet\/modules'/d" Puppetfile.simp
      
    3. (Optionally,) edit Puppetfile.simp to remove any non-core SIMP modules (e.g., the ones packaged with simp-extras) that you don’t need. You can discover the list of the SIMP extra modules by examining the dependencies of the simp-extras RPM:

      yum deplist simp-extras | grep dependency:
      
  5. Create the Puppetfile:

    1. Create the file $HOME/control-repo/Puppetfile, which should include the following line:

      instance_eval(File.read(File.join(__dir__,"Puppetfile.simp")))
      
    2. (Optionally,) also add entries for any non-SIMP modules your site requires.

  6. Add/adjust any of the Hiera files in the data/ directory.

  7. Add all the files to a branch named for the environment in this repository:

    # create the branch
    git checkout -b dev1
    
    # add the directory tree
    git add --all
    
    # verify the directory tree doesn't have any temporary files you created
    git status
    
    git commit -m 'Initial dev1 environment'
    
  8. Push the branch to your control repository:

    # Add a remote for your control repository
    git remote add control_repo <URL to the control repo>
    
    # Push the branch
    git push dev1 control_repo
    

5.3.3.4. Advanced Topics

5.3.3.4.1. Bootstrapping A SIMP Server without SIMP Module RPMs

A full set of SIMP module RPMs is not required in order for the SIMP server to be initially configured. With a slight change to the procedures listed in Initial SIMP Server Configuration, a SIMP server can be bootstrapped with a production SIMP Omni-Environment skeleton, such as one created in this HOWTO.

Note

You may want to read through Initial SIMP Server Configuration before proceeding. It provides additional information that will not be repeated here.

In these procedures, we assume that you have created a production SIMP Omni-Environment skeleton that contains a Puppetfile with URLs to the core SIMP Puppet modules. For example, you followed the procedures to create a control repository for a production environment using internet module repositories.

Execute the following steps as root:

  1. Deploy the modules in the production Puppet environment using r10K or Code Manager. Be sure the deployed modules are accessible to the puppet group.

  2. Install the puppetserver package:

    yum install puppetserver
    
  3. Run simp config with an option that tells it the SIMP Omni-Environment has already been created:

    simp config --force-config
    
  4. Run simp bootstrap:

    simp bootstrap
    
  5. After simp bootstrap completes, add the following generated Hiera files in the production Puppet environment to the production branch in your control repository:

    • production/data/simp_config_settings.yaml

    • production/data/hosts/<SIMP server FQDN>.yaml

To continue configuring the system, move on Client Management section in the SIMP User Guide.