README.md in onceover-3.22.0 vs README.md in onceover-4.0.0
- old
+ new
@@ -1,17 +1,20 @@
# Onceover
+[](https://github.com/voxpupuli/onceover/blob/master/LICENSE)
+[](#transfer-notice)
+[](https://rubygems.org/gems/onceover)
+[](https://rubygems.org/gems/onceover)
+
*The gateway drug to automated infrastructure testing with Puppet*
Onceover is a tool to automatically run basic tests on an entire Puppet control repository.
It includes automatic parsing of the `Puppetfile`, `environment.conf` and others in order to stop silly mistakes ever reaching your Puppet Master!
**New in v3.19.1: I've reversed the decision to have onceover use `site.pp` in the same way Puppet does. From now on your `manifest` setting in `environment.conf` will be ignored and your `site.pp` will only be used if you explicitly set the `manifest` option in the CLI or config file.**
-[](https://travis-ci.com/dylanratcliffe/onceover) [](https://ci.appveyor.com/project/dylanratcliffe/onceover/branch/master)
-
## Table of Contents
- [Overview](#overview)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
@@ -19,10 +22,11 @@
- [Factsets](#factsets)
- [Hiera](#hiera)
- [Puppetfile](#puppetfile)
- [Spec testing](#spec-testing)
- [Adding your own spec tests](#adding-your-own-spec-tests)
+ - [Vendored Modules](#vendored-modules)
- [Using Workarounds](#using-workarounds)
- [Extra tooling](#extra-tooling)
- [Plugins](#plugins)
- [Overriding Onceover's Templates](#overriding-onceovers-templates)
- [Accessing Onceover in a traditional RSpec test](#accessing-onceover-in-a-traditional-rspec-test)
@@ -31,10 +35,11 @@
- [Filtering](#filtering)
- [Extra Configuration](#extra-configuration)
- [Ruby Warnings](#ruby-warnings)
- [Rake tasks](#rake-tasks)
- [generate_fixtures](#generate_fixtures)
+ - [generate_vendor_cache](#generate_vendor_cache)
## Overview
This gem provides a toolset for testing _Puppet control repository_ (ie. Repos used with r10k).
@@ -63,10 +68,11 @@
1. Set up your configuration
```shell
bundle exec onceover init
```
+
1. Run your spec tests!
```shell
bundle exec onceover run spec
```
@@ -177,10 +183,11 @@
A block to run **after** each spec test.
**Note**: The facts are available through the `node_facts` hash and the trusted facts as `trusted_facts`.
Exmaple:
+
```yaml
after:
- "puts 'Test finished running'"
```
@@ -198,10 +205,11 @@
Default: `{}`
This setting overrides defaults for the `Onceover::Controlrepo` class' `opts` hash.
Example:
+
```yaml
opts:
:facts_dirs: # Remember: `opts` keys are symbols!
- 'spec/factsets' # Limit factsets to files in this repository
:debug: true # Set the `logger.level` to debug
@@ -383,14 +391,15 @@
In this case, you're all set and onceover will auto-magically pick those up for you.
**Note**: The top level `trusted` hash takes precidence over the `trusted[extensions]` hash nested under `values`. Meaning that if you have any specified at the top level, any nested ones will not be considered. So pick **ONE** method and stick with that.
#### Trusted Certname
-**Note:** When testing with Puppet >= 4.3 the trusted facts hash will have the standard trusted fact keys (certname, domain, and hostname) populated based on the node name (as set with :node).
-To support the resolution of the trusted fact `certname` in auto-generated spec tests, onceover will set `:node` to the value of `trusted[certname]` where present in the source factset.
+**Note:** When testing with Puppet >= 4.3 the trusted facts hash will have the standard trusted fact keys (certname, domain, and hostname) populated based on the node name (as set with :node).
+To support the resolution of the trusted fact `certname` in auto-generated spec tests, onceover will set `:node` to the value of `trusted[certname]` where present in the source factset.
+
For example: A spec test generated by the factset below would result in `:node` == `node.puppetlabs.net`.
```json
{
"name": "node.puppetlabs.net",
@@ -423,13 +432,14 @@
}
}
```
See the following rspec-puppet links for more information:
- - [Specifying the FQDN of the test node](https://github.com/puppetlabs/rspec-puppet#specifying-the-fqdn-of-the-test-node)
- - [Specifying trusted facts](https://github.com/puppetlabs/rspec-puppet#specifying-trusted-facts)
+- [Specifying the FQDN of the test node](https://github.com/puppetlabs/rspec-puppet#specifying-the-fqdn-of-the-test-node)
+- [Specifying trusted facts](https://github.com/puppetlabs/rspec-puppet#specifying-trusted-facts)
+
#### Trusted External Data
**Note:** This feature requires `rspec-puppet` >= 2.8.0.
You can add trusted external data to the factsets by creating a new section called trusted_external:
@@ -486,21 +496,21 @@
### Puppetfile
Organisations often reference modules from their own git servers in the `Puppetfile`, like this:
-```
+```ruby
mod "puppetlabs-apache",
:git => "https://git.megacorp.com/pup/puppetlabs-apache.git",
:tag => "v5.4.0"
```
Under the hood, `onceover` uses `r10k` to download the modules in your `Puppetfile`.
If you get errors downloading modules from `git`, its because `r10k`'s call to your underlying `git` command has failed.
`onceover` tells you the command that `r10k` tried to run, so if you get an error like this:
-```
+```text
INFO -> Updating module /Users/dylan/control-repo/.onceover/etc/puppetlabs/code/environments
/production/modules/apache
ERROR -> Command exited with non-zero exit code:
Command: git --git-dir /Users/dylan/.r10k/git/ssh---git.megacorp.com-pup-puppetlabs_apache.git fetch origin --prune
Stderr:
@@ -514,18 +524,21 @@
Exit code: 128
```
Then the approach to debug it would be to run the command that Onceover suggested:
-```
+```shell
git --git-dir /Users/dylan/.r10k/git/ssh---git.megacorp.com-pup-puppetlabs_apache.git fetch origin --prune
```
In this case, running the command interactively gives us a prompt to add the server to our `~/.ssh/known_hosts` file, which fixes the problem permanently:
-```
+```shell
$ git --git-dir /Users/dylan/.r10k/git/ssh---git.megacorp.com-pup-puppetlabs_apache.git fetch origin --prune
+```
+
+```text
The authenticity of host 'git.megacorp.com (123.456.789.101)' can't be established.
...
Warning: Permanently added 'git.megacorp.com,123.456.789.101' (RSA) to the list of known hosts.
```
@@ -603,17 +616,41 @@
If you want to see Puppet's output, you can set the `SHOW_PUPPET_OUTPUT` environment variable to `true`, eg:
`SHOW_PUPPET_OUTPUT=true onceover run spec`
+### Vendored Modules
+
+As of Puppet 6.0 some resource types were removed from Puppet and repackaged as individual modules. These supported type modules are still included in the `puppet-agent` package, so you don't have to download them from the Forge. However, this does not apply to the `puppet` gem used when spec testing. This frequently results in users wondering why their Puppet manifests apply just fine on a node, but their tests fail with messages like `Unknown resource type: cron_core` for example. A common workaround for this problem was to add said modules into your Puppetfile, thus requiring manual management.
+
+Onceover now has the ability to remove that manual process for you by querying Github's API to determine which versions are in use by the version of the [puppet-agent package](https://github.com/puppetlabs/puppet-agent/tree/main/configs/components) you are testing against.
+
+This functionality is opt in, so to use it configure the following:
+
+```yaml
+# onceover.yaml
+opts:
+ auto_vendored: true
+```
+
+or on the cli:
+
+```shell
+bundle exec onceover run spec --auto_vendored=true
+```
+
+Essentially what this is doing is resolving any of these [supported type modules](https://www.puppet.com/docs/puppet/8/type#supported-type-modules-in-puppet-agent) that are not already specified in your Puppetfile, and adding them to the copy Onceover uses to deploy into its working directory structure.
+
+CI/CD pipeline users are encouraged to provide Onceover with a cache of the module versions to test against in order to avoid hitting Githubs API ratelimit. To do so, the [generate_vendor_cache](#generate_vendor_cache) rake task can be used to populate the cache into your `spec/vendored_modules` directory.
+
## Using workarounds
There may be situations where you cannot test everything that is in your puppet code, some common reasons for this include:
- - Code is destined for a Puppet Master but the VM image is not a Puppet Master which means we can't restart certain services etc.
- - A file is being pulled from somewhere that is only accessible in production
- - Something is trying to connect to something else that does not exist
+- Code is destined for a Puppet Master but the VM image is not a Puppet Master which means we can't restart certain services etc.
+- A file is being pulled from somewhere that is only accessible in production
+- Something is trying to connect to something else that does not exist
Fear not! There is a solution for this, it's also a good way to practice writing *nasty* puppet code. For this exact purpose I have added the ability for onceover to include extra bits of code in the tests to fix things like this. All you need to do is put a file/s containing puppet code here:
`spec/pre_conditions/*.pp`
@@ -671,12 +708,12 @@
Onceover now allows for plugins. To use a plugin simply install a gem with a name that starts with `onceover-` and onceover will activate it.
Useful plugins:
- - [onceover-codequality](https://github.com/declarativesystems/onceover-codequality) _Check lint and syntax_
- - [onceover-octocatalog-diff](https://github.com/dylanratcliffe/onceover-octocatalog-diff) _See the differences between two versions of a catalog_
+- [onceover-codequality](https://github.com/declarativesystems/onceover-codequality) _Check lint and syntax_
+- [onceover-octocatalog-diff](https://github.com/voxpupuli/onceover-octocatalog-diff) _See the differences between two versions of a catalog_
If you want to write your own plugin, take a look at [onceover-helloworld](https://github.com/declarativesystems/onceover-helloworld) to help you get started.
### Inspecting and updating the Puppetfile
@@ -877,10 +914,16 @@
ref: 1.5.0
```
Notice that the symlinks are not the ones that we provided in `environment.conf`? This is because the rake task will go into each of directories, find the modules and create a symlink for each of them (This is what rspec expects).
+#### generate_vendor_cache
+
+`bundle exec rake generate_vendor_cache`
+
+This task will query Github's API to determine the versions of the vendored modules in use by the version of the puppet agent you are testing against, and cache that information in `control-repo/spec/vendored_modules`. This way your pipelines won't need to reach out for this information each time Onceover is ran with `auto_vendored` enabled.
+
## Developing Onceover
Install gem dependencies:
`bundle install`
@@ -895,25 +938,28 @@
## Contributors
Cheers to all of those who helped out:
- - @jessereynolds
- - @op-ct
- - @GeoffWilliams
- - @beergeek
- - @jairojunior
- - @natemccurdy
- - @aardvark
- - @Mandos
- - @Nekototori
- - @LMacchi
- - @tabakhase
- - @binford2k
- - @raphink
- - @tequeter
- - @alexjfisher
- - @smortex
- - @16c7x
- - @neomilium
- - @chlawren
+- @jessereynolds
+- @op-ct
+- @GeoffWilliams
+- @beergeek
+- @jairojunior
+- @natemccurdy
+- @aardvark
+- @Mandos
+- @Nekototori
+- @LMacchi
+- @tabakhase
+- @binford2k
+- @raphink
+- @tequeter
+- @alexjfisher
+- @smortex
+- @16c7x
+- @neomilium
+- @chlawren
+## Transfer Notice
+
+This project was originally authored by dylanratcliffe. The maintainer preferred that Vox Pupuli take ownership of the project for future improvement and maintenance. Existing pull requests and issues were transferred over, please fork and continue to contribute here instead of voxpupuli-onceover.