control_repo

What does this do in summary?

Table of Contents

1. Description
2. Setup - The basics of getting started with control_repo
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Design Decisions
6. Development - Guide for contributing to the module
7. Testing
8. License
9. Code of Conduct

Description

• Why would I want to use this?
• What kind of problems can it solve for users?

Setup

What control_repo affects OPTIONAL

• What will this module alter, impact, or execute?
• Anything else you need to mention or warn about?

Setup Requirements OPTIONAL

• What does this module depend on?
• Do you need to install anything before this will work?
• Does the most recent release break any compatibility or require any particular steps for upgrading?

Beginning with control_repo

• What's an example of the most basic use?

Usage

• What are some other common use cases and examples?
• How is this module used to solve common problems?

Limitations

• Does this module have any incompatibilities, known issues, or other warnings?

Design Decisions

This section is inspired by Michael Nygard's article on DOCUMENTING ARCHITECTURE DECISIONS. The best time to write these decision summaries is right in the middle of the choice when the reasoning is most clear. Significant design choices should follow the format:

• Title What noun phrase briefly and most accurately summarises the decision? For example, "Deployment on Ruby on Rails 3.0.10" or "LDAP for Multitenant Integration"
• Context: What forces are at play, including technological, political, social, and project local? For example, "It's nice to have usage documentation in the script files themselves, in comments. When reading the code, that's the first place to look for information about how to run a script." or "Currently help text is generated by extracting specially formatted comments...But, it means that help text cannot include calculated values, such as the location of files."
• Decision What is our response to these forces? For example, "The adr-tools project will not contain any packaging or distribution scripts and config. Packaging and distribution will be managed by other projects in separate version control repositories." or "Running adr without any arguments lists the available subcommands."
• Status: In what status is this decision ("proposed", "accepted", "deprecated" or "superseded")?
• Consequences: What's the resulting context after applying this decision? In particular, how do these consequences affect the team and project in the future? Can you list all consequences positive and negative? For example "The git repo of this project will be simpler. Eventually, users will not have to use Git to get the software."

Install modules beneath .modules and not the default modules

The reason for doing this is to make easier alignment with Bolt. What does alignment with Bolt mean? Why is this important? What problem does this alignment solve?

One challenge with any module or control-repository is how to keep the Puppetfile up to date. As module versions increase and their sub-dependencies change, so must the Puppetfile. One way to do this is to change each and every module fixing dependency errors at each change. This is a very manual and labour intensive way to update the Puppetfile dependencies. A far better way is to use bolt and automatically update the Puppetfile and dependencies. To automatically update the Puppetfile with bolt, simply (1) add all dependencies to the bolt-project.yaml and then (2) run bolt module install --force.

By default, however, bolt and code manager install modules to different directories: bolt to .modules and code manager to modules. Although bolt's configuration does not currently provide a way to use modules instead of .modules, code manager does. Every environment used by code manager contains an environment.conf that specifies the modulepath for each environment. Adding .modules to the modulepath in environment.conf means that when code manager uses the bolt-generated Puppetfile, which includes the .modules directive, then all the dependent modules beneath .modules can be seen by the system and environment. Now, for example, puppet module list confirms that control-repo modules are seen beneath the expected .modules directory, e.g.,

# 
root@pe-server-37658f-0 control-repo (development)$ puppet module list --environment development
/etc/puppetlabs/code/environments/development/site-modules
└── role (???)
/etc/puppetlabs/code/environments/development/.modules
├── gavindidrichsen-bigbird (v0.1.0)
├── herculesteam-augeasproviders_core (v3.1.0)
...
/opt/puppetlabs/puppet/modules
├── puppetlabs-bash_task_helper (v2.0.0)
...
...
root@pe-server-37658f-0 control-repo (development)$ 

Separate 'global' hiera out of the control-repo into a 'hieradata' module

• Context: Some customers need to separate their hiera data out of the control-repo because they need to be able to separate change requests for 'code' and 'data'. Using a separate hieradata module can allow for this kind of separation. In particular, one customer was having trouble with their hieradata module: cd4pe impact analysis was not working for the hieradata module. Therefore,
• Decision: Add a hieradata module with 'global' settings that override any in the control-repo or below in modules.
• Status: accepted
• Consequences: Having a hieradata module allows me to easily test customer queries where a hieradata module is included.

Development

• What are the ground rules for contributing to this project
• How should work be submitted?

Testing

License

This module is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the control_repo project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Release Notes/Contributors/Etc. Optional