Generation Engine

The nevisAdmin 4 Generation Engine(GE)is a command line tool to generate and deploy projects. It is a tool for advanced users.

Integration with build automation or orchestration tools such as Jenkins, GoCD or Ansible is possible.

The generation engine has the following limitations:

• Secrets are not supported.
• Kubernetes is not supported.
• There are some restrictions if both the GUI and the generation engine are used. See Combined use of the Generation Engine and the GUI.

Example Usage

The GE requires the paths to the project, the inventory and the plugin libraries. Here is a simple example:

nevisadmin4 generate --project . --inventory prod.yml --orchestration direct --bundles ./plugins --binary-cache ./cache

The orchestration type direct will generate and deploy the project. There are other modes to choose from, see Command Line Help.Setting the binary cache is not needed as of version 4.8, since no patterns utilize it yet.

Command Line Help

Run nevisadmin4 generate to display the help of the generation engine.

The output will look similar to the text in the following code block:

Usage description of 'nevisadmin4 generate', version 4.8.0

Usage arguments:
 --help | -h Show this help
 --project | -p <proj-path> Path to nevisAdmin 4 GE project directory. Defaults to '.'
 --project-key | -pk <project-key> Key of the project.
 --inventory | -i <inventory-path> Path to inventory of format matching the orchestration mode
 --inventory-key | -ik <inventory-key> Key of the inventory
 --mode | -m <mode> nevisAdmin 4 GE orchestration mode to use. Supported modes:
  direct, direct-force, direct-validate,
  direct-plan, direct-plan-force (default: direct)
 --host-filter | -hf <host-filter> name of the host, name of the host group, or '*' for hosts.
  Defaults to '*'
 --instance-pattern-filter | `-ipf <pattern>` name of the pattern to deploy, or id of the pattern in 'pattern://id' format
 --bundles | -b <bundles-path> Path to bundles (plugins) directory. If not set ./plugins will be
  used if this directory exists
 --ca <ca-path> Path to CA directory. Expected directory contents:
  - ca_key.pem: CA private key
  - ca_cert.pem: CA certificate
  - ca_pass: CA private key passphrase
  If not set ./ca will be used by default
 --trace | -t <trace-level> Trace level to emit to stdout. Defaults to 'WARN'
 --binary-cache | -bc <cache-path> Path to the binary-cache storing generated files between deployments.
  If not set, there will be no binary-cache
Supported orchestration modes:
 direct-validate: Using a provided YAML inventory, only validate that the project
  can generate.
 direct-plan: Using a provided YAML inventory, generate artifacts for the pro-
  ject and calculate a plan for deploying to the hosts defined in
  the inventory. This mode establishes connections to remote hosts
  and scan them to calculate modifications. It does not modify the
  remote hosts.
 direct-plan-force: Same as 'direct-plan' but instead of calculating a deployment plan
  with minimal changes to the remote host this mode constructs a
  deployment plan that re-applies all generated files and runs all
  commands irrespective of the state of the remote host. This mode
  does not connect to remote hosts.
 direct: Using a provided YAML inventory, generate files, scan remote hosts
  for differences to calculate a minimal deployment plan and then
  execute that plan. THIS MODE MODIFIES THE REMOTE HOSTS!
 direct-force: Same as 'direct' but instead of calculating a minimal deployment
  plan this mode simply applies all generated files and executes all
  commands. THIS MODE MODIFIES THE REMOTE HOSTS!

Sample arguments: <command> --project . --inventory test-inventory.yml --orchestration direct --bundles ./plugins --ca-key-pass password

Setup Generation Engine

For deployment, the GE has to be able to connect to target hosts using SSH. See chapter Deployment via SSH for details.

The generation engine works on the file system, instead of with a database. This means that you need to create a base directory to store your project(s). How this directory looks like depends on your requirements. For example:

• The directory may contain multiple nevisAdmin 4 projects (using sub-directories).
• You may store the plug-in bundles either in the same directory or in a central location.

Here is an example structure that you can use when there is only one project:

• patterns/*.yml - Stores the nevisAdmin 4 pattern instances as YAML files.
• bundles.yml - Defines the plug-in bundles used by this project.
• variables.yml - Contains the project-level variables.
• plug-ins - Contains the plug-in bundles.
• <stage>.yml - The inventory file for each stage.
• nevisadmin4.yml or conf/nevisadmin4.yml - The nevisAdmin 4 configuration file.
• cache - Path to the binary-cache storing generated files between deployments.

Additional Settings

To specify additional settings for the generation engine, such as the key material to use for SSH connections, you can set properties:

• Properties in nevisadmin4.yml or conf/nevisadmin4.yml. The property names are the same as those recognized by the GUI, but some may be ignored because they are irrelevant for GE operation.

• Environment variables. The GE picks up environment variables that contain full property names. Here's an example related to Deployment via SSH:

  export NEVISADMIN_DEPLOYMENT_SSH_PRIVATEKEY_FILE=/path/to/id_rsa
  export NEVISADMIN_DEPLOYMENT_SSH_PRIVATEKEY_PASSPHRASE=the_password
  
  nevisadmin4 generate ...

  To translate a property known from the nevisadmin4.yml file to an environment variable name:

  • Use upper case.
  • Combine the whole key hierarchy into one string, separated by _ .
  • Replace . and - by _.

Combined Use of the Generation Engine and the GUI

The generation engine operates on the file system while the nevisAdmin 4 web application (the GUI) uses a database. If you want to use both for the same project you have to ensure that the data is in sync. You can use Git to exchange the data:

• A publish to Git in the nevisAdmin 4 application exports the project or inventory. The GE can then use the project to generate and deploy.
• If you make changes in the nevisAdmin 4 application, publish these changes to Git. Then perform a git clone and git pull, to clone and pull the changes on the server where the generation engine is running.
  • It is possible to run the generation engine and the GUI application on the same server. Also in this case data synchronization takes place via Git.
• When changing files in your local checkout, perform a git commit and git push. Use the Update function to import the changes in the nevisAdmin 4 application.

Restrictions

Observe the following restriction:

When using automatic key management: the web application creates and stores the nevisAdmin 4 CA in the database, while the generation engine creates and stores the CA in the file system.

• Deploy such configurations either from the GUI or with the generation engine, but do not mix deployments to the same inventory: They would fail.
• If mixed deployment is a requirement, use a different key management approach (see Configuring Key Material and Certificates).
• nevisAdmin 4.1.0 does not contain a REST API to extract or exchange the nevisAdmin 4 certificate authority.