Commit 94b10f220b0ad57bd7782903ceebb16a9590d85e
1 parent
d4af4bf811
first spike at docs on puppet modules
Showing 1 changed file with 111 additions and 0 deletions Side-by-side Diff
docs/modules.md
| 1 | +# Writing Puppet modules for Boxen | |
| 2 | + | |
| 3 | +Writing Puppet modules for Boxen is easy. | |
| 4 | + | |
| 5 | +## Tooling | |
| 6 | + | |
| 7 | +* Always use Bundler | |
| 8 | +* Always use librarian-puppet | |
| 9 | +* Always use puppet-lint | |
| 10 | +* Always use rspec-puppet | |
| 11 | + | |
| 12 | +## Directory structure | |
| 13 | + | |
| 14 | +We follow Puppet's recommended structure very closely. | |
| 15 | +Here's the directory structure from the boxen Puppet module: | |
| 16 | + | |
| 17 | +``` | |
| 18 | +├── Gemfile | |
| 19 | +├── Gemfile.lock | |
| 20 | +├── README.md | |
| 21 | +├── files | |
| 22 | +│ ├── README.md | |
| 23 | +│ └── gemrc | |
| 24 | +├── lib | |
| 25 | +│ ├── facter | |
| 26 | +│ │ ├── boxen.rb | |
| 27 | +│ │ └── root_encrypted.rb | |
| 28 | +│ └── puppet | |
| 29 | +│ ├── parser | |
| 30 | +│ │ └── functions | |
| 31 | +│ │ ├── file_exists.rb | |
| 32 | +│ │ ├── include_all_projects.rb | |
| 33 | +│ │ └── include_projects_from_boxen_cli.rb | |
| 34 | +│ ├── provider | |
| 35 | +│ │ ├── package | |
| 36 | +│ │ │ ├── compressed_app.rb | |
| 37 | +│ │ │ ├── hax.rb | |
| 38 | +│ │ │ └── homebrew.rb | |
| 39 | +│ │ ├── repository | |
| 40 | +│ │ │ └── git.rb | |
| 41 | +│ │ └── service | |
| 42 | +│ │ └── ghlaunchd.rb | |
| 43 | +│ └── type | |
| 44 | +│ └── repository.rb | |
| 45 | +├── manifests | |
| 46 | +│ ├── bin.pp | |
| 47 | +│ ├── config.pp | |
| 48 | +│ ├── development | |
| 49 | +│ │ └── project.pp | |
| 50 | +│ ├── development.pp | |
| 51 | +│ ├── environment.pp | |
| 52 | +│ ├── gemrc.pp | |
| 53 | +│ ├── janitor.pp | |
| 54 | +│ ├── osx_defaults.pp | |
| 55 | +│ ├── personal.pp | |
| 56 | +│ ├── profile.pp | |
| 57 | +│ ├── project.pp | |
| 58 | +│ ├── repo.pp | |
| 59 | +│ ├── security.pp | |
| 60 | +│ ├── sudoers.pp | |
| 61 | +│ └── zipped_widget.pp | |
| 62 | +├── script | |
| 63 | +│ ├── bootstrap | |
| 64 | +│ ├── cibuild | |
| 65 | +│ ├── lint | |
| 66 | +│ ├── specs | |
| 67 | +│ └── syntax | |
| 68 | +├── spec | |
| 69 | +│ ├── classes | |
| 70 | +│ │ ├── bin_spec.rb | |
| 71 | +│ │ └── environment_spec.rb | |
| 72 | +│ ├── fixtures | |
| 73 | +│ │ ├── Puppetfile | |
| 74 | +│ │ ├── Puppetfile.lock | |
| 75 | +│ │ ├── manifests | |
| 76 | +│ │ │ └── site.pp | |
| 77 | +│ │ └── modules | |
| 78 | +│ │ ├── boxen | |
| 79 | +│ │ │ ├── files -> ../../../../files | |
| 80 | +│ │ │ ├── lib -> ../../../../lib | |
| 81 | +│ │ │ ├── manifests -> ../../../../manifests | |
| 82 | +│ │ │ └── templates -> ../../../../templates | |
| 83 | +│ │ └── projects | |
| 84 | +│ │ └── manifests | |
| 85 | +│ │ └── test.pp | |
| 86 | +│ ├── spec_helper.rb | |
| 87 | +│ └── unit | |
| 88 | +│ └── puppet | |
| 89 | +│ └── type | |
| 90 | +│ └── repository_spec.rb | |
| 91 | +└── templates | |
| 92 | + ├── config.sh.erb | |
| 93 | + ├── env.sh.erb | |
| 94 | + └── gh_creds.sh.erb | |
| 95 | +``` | |
| 96 | + | |
| 97 | +Of note, we do not use things like `rake` to drive specs. | |
| 98 | +Instead, we bias towards simple, portable shell scripts that can be consumed | |
| 99 | +by other shell scripts. | |
| 100 | + | |
| 101 | +## Facts and variables | |
| 102 | + | |
| 103 | +The core boxen module provides [a number of variables to use](https://github.com/boxen/puppet-boxen/blob/master/manifests/config.pp#L2-L14). | |
| 104 | + | |
| 105 | +In addition to these, you may always assume the presence of a `boxen_user` fact, | |
| 106 | +which is the local user running Boxen. | |
| 107 | + | |
| 108 | +Other modules may provider their own globally available variables. | |
| 109 | +The recommendation is to put any variables that might be consumed by | |
| 110 | +multiple classes/manifests should be in a scoped config class | |
| 111 | +(e.g. `modules/boxen/manifests/config.pp`). |