SIMP 6.4+: Design `simp environment` command

This article began as an artifact of  SIMP-6380 - Getting issue details... STATUS .

It describes the simp environment new command (and others), proposed in the decision log SIMP 6.4+: The ISO installation/Puppetfile workflow.

Design lineage

This design has been informed by the mapping work in SIMP 6.4: Map old/new files and capabilities.

Terminology

This page uses terminology defined in the SIMP Environments article.


(Mockup:) simp environment COMMAND [OPTIONS]

Manage and coordinate SIMP omni-environments

Usage:

    simp environment COMMAND [OPTIONS]

Alias:

    simp env

A complete SIMP environment (often referred to as the SIMP "omni-environment")
has three distinct sources:

  * Puppet: Puppet code and data under $environmentpath/$environment/
  * Secondary: Environment-specific SIMP data (e.g, site_files/)
  * Writable: Env-specific SIMP data created during compile (e.g., passgen)

The Secondary and Writable environment are collectively referred to as the
SIMP "Extra" environment.

In order to compile the Puppet catalog, the Puppet server MUST be able to read
from all three environments, and it MUST be able to write to the Writable
environment. The Puppet and Secondary environment's assets MUST be available
_before_ compiling the catalog.

Files:

  /etc/simp/simp_cli.yaml

       Contains configurations for the simp cli command

simp environment new ENVIRONMENT [OPTIONS]

Create a new SIMP "Extra" (default) or "omni" environment

Usage:

    simp environment new ENVIRONMENT [OPTIONS]


By default, this command will:

  * create a new environment (–-skeleton)
  * raise an error if an environment directory already exists

It can create a complete SIMP omni-environment with --puppet-env


Examples:

     # Create a new development "extra" environment
     simp env new development

     # Link staging's Secondary and Writable env dirs to production
     simp env new staging --link production

     # Create a separate copy of production (will diverge over time)
     simp env new newprod --copy production

     # Create new omni environment, 
     simp env new local_prod --puppetfile


Options:

option
   purpose
--skeleton
(default) Generate environments from skeleton templates.
Implies --puppetfile
--copy ENVIRONMENT
Copy assets from ENVIRONMENT
--link ENVIRONMENT
Symlink Secondary and Writeable environment directories
to ENVIRONMENT. If `--puppet-env` is set, the Puppet
environment will `--copy`.


Puppetfile options 

option
  purpose
--[no]-puppetfile
Generate Puppetfiles in Puppet env directory
* `Puppetfile` will only be created if missing
* `Puppetfile.simp` will be generated from RPM/
* implies `--puppet-env`
--[no]-puppetfile-install
Automatically deploys Puppetfile in Puppet env 
directory after creating it
* implies `--puppet-env`
* does NOT imply `--puppetfile`



Extra options 

option
  purpose
--puppet-env-dir PATH
Parent directory for new Puppet environment dir 
(default: .)
--secondary-env-dir PATH

Parent directory for new Secondary environment dir

(default: /var/simp/environments)

--writable-env-dir PATH

Parent directory for new Writable environment dir

(default: ${(Puppet server's) vardir}/simp/)

--[no-]puppet-env
Includes Puppet environment when `--puppet-env`
(default: --no-puppet-env)
--[no-]secondary-env
Skips the Secondary environment when `--no-`
(default: --secondary-env)
--[no-]writable-env
Skips the Writable environment when `--no-`
(default: --writable-env)


Future options:

option
  purpose
--simp-mod-data-provider SRC

Provider of simp module data (default: `local_repos`)
Used to generate `Puppetfile.simp`
In the future, SRC may include alternatives, like
`url=PUPPETFILE_URL` or `libkv`

--secondary-env-provider SRC

Provider of secondary env data (default: `directory`)
In the future, SRC may include alternatives,
like `libkv`

--writable-env-provider SRC

Provider of writable env data (default: `directory`)
In the future, SRC  may include alternatives,
like `libkv`



simp environment update ENVIRONMENT [OPTIONS]

Update data in a SIMP "Extra" (default) or "omni" environment

Usage:

    simp environment update ENVIRONMENT [OPTIONS]

Alias:

    simp env up ENVIRONMENT [OPTIONS]


The only update the content of Puppetfile.simp.


Copy options:


option
   purpose
--copy ENVIRONMENT
copy assets from ENVIRONMENT


Puppetfile options: 

   (same as simp environment new)


Extra options: 

   (same as simp environment new)


simp environment remove

Remove an entire SIMP extra-environment

Usage:

simp environment remove ENVIRONMENT [OPTIONS]

Alias:

    simp env rm ENVIRONMENT [OPTIONS])


Remove an environment's assets/code/data from ENVIRONMENT'S directories.


Options:

Extra options: 

   (same as simp environment new)


simp environment mirror [ENVIRONMENT] [OPTIONS]

Alternate names considered: postrundeployensure

Ensure that a SIMP extra environment exists for each Puppet environment (under
$environmentpath/), creating or removing secondary and writable environments
until there is a 1:1 mapping.

When ENVIRONMENT is given, only that environment will be affected.

This command is useful to run after Code Manager/`r10k deploy environment` or a Code
Manager run.

Usage:

    # Ensure that a SIMP extra environment exists for each Puppet environment
    # (and remove any extraneous SIMP extra environments)
    simp environment mirror [OPTIONS]

    # * If a Puppet environment exists at $environmentpath/development,  ensure
    #   that a corresponding SIMP extra environment exists, too.
    # * If not, ensure that there is no SIMP extra environment for `development`
    simp environment mirror development [OPTIONS]

Examples:

     # Create a new development "extra" environment
     simp env new development


     # Link staging's Secondary and Writable env dirs to production
     simp env new staging --link production


     # Create a separate copy of production (will diverge over time)
     simp env new newprod --copy production


Extra options: 

   (same as simp environment new)


simp environment list

List SIMP omni environments

Usage:

simp environment list [PATTERN] [OPTIONS]

Alias:

    simp env ls ENVIRONMENT [OPTIONS]

option
   purpose
--details
Show table of component environments and status

Examples:

     # short list of environments
     $ simp env list

     production
     development
     staging 


     # component environment details
     $ simp env list --details

     | Env dirs:   | Puppet | Secondary | Writable |
     | ----------- | ------ | --------- | -------- |
     | production  | Yes    | Yes       | Yes      |
     | development | Yes    | Yes       | :x:      |
     | production  | Yes    | Yes       | Yes      |


simp environment fix ENVIRONMENT

Re-apply FACLs, SELinux contexts, and permissions to all omni-environment files

Usage:

    simp environment fix ENVIRONMENT [OPTIONS]

Actions:

* Ensure SELinux contexts under all environment directories (`fixfiles restore`)
* Restore FACLs under ${SECONDARY_ENVDIR} ${PUPPET_ENVDIR} ${WRITABLE_ENVDIR}`
* If ${SECONDARY_ENVDIR}/FakeCA/cacertkey doesn't exist, fill it will random gibberish


Extra options: 

   (same as simp environment new)

simp environment validate [ENVIRONMENT] [OPTIONS]

Validates various things about an environment

Usage:

    simp environment validate [ENVIRONMENT] [OPTIONS]

Checks include:

* FACLs, SELinux contexts, and permissions to all omni-environment files
* (Basically, everything that `simp env fix` would fix)

Extra options: 

   (same as simp environment new)

simp environment export ENVIRONMENT FILE [OPTIONS]

Creates an encrypted tarball of ENVIRONMENT'S omni-environment

Usage:

    simp environment export ENVIRONMENT FILE [OPTIONS]


(This might only be relevant to environments provided by directories)


simp environment import ENVIRONMENT FILE [OPTIONS]

Import an exported omni-environment back into ENVIRONMENT

Usage:

    simp environment import ENVIRONMENT FILE [OPTIONS]


(This might only be relevant to environments provided by directories)

Implementation

Simp::Cli::Environment::


Simp::Cli::Commands::

The simp environment COMMAND is composed of sub-commands, like simp puppetfile COMMAND

Below are the relationships to compose simp puppetfile new: