* Jumpstart programme is not live
We should remove the mention of the jumpstart programme which appears orphaned and unmaintained
* Update README.md
Co-authored-by: Reid Vandewiele <reid@puppet.com>
All links to Puppet's Code Manager were broken. The Puppet 5 links are
updated to version 7. The Gitlab links redirect somewhere else. The
direct link saves users a redirect.
This branch is intended as a portability fix. Some functionailty had
been inadvertently removed as unused, but testing revealed that it had a
purpose. Because the purpose was unclear, this commit restores the
functionality AND clarifies it in the script names and comments in
config_version.sh.
This commit updates the Puppetfile example module versions to list the
latest releases for the example modules as of 2019-07-10, and also
updates several files for style.
Standardizing on double-quotes in YAML due to:
1. Functional irrelevance between single vs. double quotes in our YAML
2. Prevalent use of double-quotes in Puppet documentation
3. Similar look-and-feel to other data serialization formats like JSON
This commit attempts to cleanup and modernize the comments in site.pp a
bit.
For one thing, I've updated the docs links to point to working URL's.
For another, I tried to reorganize, clarify, and deduplicate the comments.
The symlink served for a good discussion point around change impact, but
in the end having it makes for a more confusing experience overall both
to new users cloning the control-repo to get started and also to anyone
accustomed to "site". A new user won't miss "site". A symlink will muddy
the waters over the change for long-time users. Better for clarity to be
all-in and not include a symlink.
Prior to this commit, we placed modules local to a users installation
in the `site` directory. This was just a convention and the name
`site` doesn't clearly convey what it is for.
After this commit, we place modules local to a users installation in
the `site-modules` directory. This makes it more clear to users
that this is a directory that modules go i. When users start
with bolt they won't even know what a control-repo is and
renaming site to site-modules gives them a better idea of why
they should put their modules with tasks in them. Also see:
https://tickets.puppetlabs.com/browse/BOLT-1108
r10k generates a .r10k-deploy.json file since version 2.1.0 which was
released on October 28, 2015. New users of the control-repo are not
likely to have a so old version of r10k, so remove this dead code.
The appropriate ruby interpreter is determined by the config_version.sh
shell script which explicitely use it to start these ruby scripts.
Removing the execute bit ensure users will not run these script with the
wrong Ruby version.
- Fix shebang: `bash` is not always in `/bin/`, and since the script
does not have bashism, rely on `sh` which is always in `/bin/`;
- Use `/opt/puppetlabs/puppet/bin/ruby` if this file exist and is
executable, otherwise use `ruby` from $PATH;
- Use `code_manager_config_version.rb` if `.r10k-deploy.json` is found,
and `config_version.rb` in all other cases.
This commit moves the "where did all the previous code go" section to
the bottom as it's been a while since that change was made. Nowadays,
people new to Control Repositories will find this and won't understand
the reference as they never knew about previous versions.
Now the README starts right away with information on what this project
is and how to use it.
Also cleaned up some of the Markdown syntax to make it easier to read.
This is mainly a style and readability change.
Prior to this, on masters whose hostname is actually their FQDN, the
config_version script would show the entire FQDN. On nodes with really
longs FQDN's, it was not very nice to look at.
This takes the hostname of the master, splits it on dots (.) and takes
the first segment.
Now this: compile-master-02.int.lab.dmz.company-name.net-production-48fd18ab
Is this: compile-master-02-production-48fd18ab
Prior to this, the config_version.rb script (used for r10k) attempted to
use the system ruby to parse the script. This caused problems on Puppet
masters that don't have `ruby` in PATH.
This fixes that by hardcoding the puppet-agent's ruby in the shebang.
Prior to this, modules that were deployed with r10k into the ./modules
directory weren't being ignored by git.
When doing local development or testing, it's nice to be able to run
'r10k puppetfile install' to pull down modules from the Puppetfile.
After this commit, those modules won't be tracked by git.
This commit enables the control repo to use Hiera 5 environment-level
hiera hierarchy. This means adding a hiera.yaml to the repo, and moving
hieradata/ => data/.
We should do this to the control-repo template new customers base off of
because in a Hiera 5 world, the global hiera.yaml should be very minimal
(possibly even ONLY having the console level), and everything else
(nodes, common) belongs in the environment hiera.yaml.
This control-repo template is how people start using Puppet. It should
reflect using our most modern technologies.
Prior to this, the config_version script just showed the commit ID of
the version of code being compiled. This commit includes the compiling
Puppet master's hostname and environment name in the config_version.
This is very useful for debugging when a Puppet master is failing and
you have multiple masters behind a load balancer.
The output of config_version now looks like this:
pupmaster01-production-ac9785273a10
Prior to this commit, if you used windows bash git when you clone
down the repo these files would get incorrect permissions which
make them unexecutable.
After this commit, due to some windows bash git magic I don't
understand it appears that adding the shebang to the beginning of
the file causes windows bash git to change the permissions to
so the file is executable.
This resolves https://github.com/puppetlabs/control-repo/issues/40
Prior to this commit, we mitigated issues with hiera-eyaml causing
a memory leak by setting max_requets_per_instance to 0
After this commit, we go back to the default for
max_requests_per_instance because the hiera-eyaml memory leak
has been resolved for months if you use the newest version
* [Where Did All The Previous Code Go?](#where-did-all-the-previous-code-go)
* [What You Get From This control\-repo](#what-you-get-from-this-control-repo)
* [Copy This Repo Into Your Own Git Server](#copy-this-repo-into-your-own-git-server)
* [Gitlab](#gitlab)
* [Stash](#stash)
* [Github](#github)
* [What You Get From This control\-repo](#what-you-get-from-this-control-repo)
* [Copy This Repo Into Your Own Git Server](#copy-this-repo-into-your-own-git-server)
* [GitLab](#gitlab)
* [Bitbucket/Stash](#bitbucketstash)
* [Github](#github)
* [Code Manager Setup](#code-manager-setup)
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
# Where Did All The Previous Code Go?
## What You Get From This control-repo
Initially, the control-repo project began as a 'starter' template for anyone
who wanted to get started with R10k. As time passed (and Code Manager was
integrated into Puppet Enterprise), the scope of this project grew to include
opinionated Puppet profiles to setup many Puppet Enterprise components. As the
code increased, so did the complexity of the control-repo project. To reduce
that complexity, as well as continue to meet the needs of individuals who would
like a more minimal template, this repository was stripped of anything other
than the bare minimum files necessary to get started with a functioning
control-repo. All of the code that was previously in this repository still
exists in separate repositories under the [Puppet Labs RampUp Program namespace within Github](https://github.com/PuppetLabs-RampUpProgram)
and can easily be re-connected to an existing control-repo if that is required
(simply add the modules to the Puppetfile). Alternatively, if that
previously-opinoinated control-repo is desired, [it still exists on Github under the Puppet Labs RampUp Program namespace.](https://github.com/PuppetLabs-RampUpProgram/control-repo)
This control-repo project will remain a template for anyone who would like a minimal
'starter' template.
This is a template [control repository](https://puppet.com/docs/pe/latest/control_repo.html) that has the minimum amount of scaffolding to make it easy to get started with [r10k](https://puppet.com/docs/pe/latest/r10k.html) or Puppet Enterprise's [Code Manager](https://puppet.com/docs/pe/latest/code_mgr.html).
# What You Get From This control-repo
The important files and items in this template are as follows:
This repository exists as a template control-repo that can be used with R10k or Puppet Enterprise Code Manager.
* Basic example of roles and profiles.
* An example Puppetfile with various module references.
* An example Hiera configuration file and data directory with pre-created common.yaml and nodes directory.
* These match the default hierarchy that ships with PE.
* An [environment.conf](https://puppet.com/docs/puppet/7/config_file_environment.html) that correctly implements:
* A site-modules directory for roles, profiles, and any custom modules for your organization.
* A config\_version script.
* An example [config\_version](https://puppet.com/docs/puppet/7/config_file_environment.html#environment-conf-allowed-settings) script that outputs the git commit ID of the code that was used during a Puppet run.
The major points are:
- An environment.conf that correctly implements:
- A site directory for roles, profiles, and any custom modules for your organization
- A config_version script
- Provided config_version scripts to output the commit of code that your agent just applied
- Basic example of roles/profiles code
- Example hieradata directory with pre-created common.yaml and nodes directory
- These match the default hierarchy that ships with PE
Here's a visual representation of the structure of this repository:
##Copy This Repo Into Your Own Git Server
```
control-repo/
├── data/ # Hiera data directory.
│ ├── nodes/ # Node-specific data goes here.
│ └── common.yaml # Common data goes here.
├── manifests/
│ └── site.pp # The "main" manifest that contains a default node definition.
├── scripts/
│ ├── code_manager_config_version.rb # A config_version script for Code Manager.
│ ├── config_version.rb # A config_version script for r10k.
│ └── config_version.sh # A wrapper that chooses the appropriate config_version script.
├── site-modules/ # This directory contains site-specific modules and is added to $modulepath.
│ ├── profile/ # The profile module.
│ └── role/ # The role module.
├── LICENSE
├── Puppetfile # A list of external Puppet modules to deploy with an environment.
├── README.md
├── environment.conf # Environment-specific settings. Configures the modulepath and config_version.
└── hiera.yaml # Hiera's configuration file. The Hiera hierarchy is defined here.
```
###Gitlab
## Copy This Repo Into Your Own Git Server
1. Install Gitlab
- https://about.gitlab.com/downloads/
To get started with using the control-repo template in your own environment and git server, we've provided steps for the three most common servers we see: [GitLab](#gitlab), [BitBucket](#bitbucketstash), and [GitHub](#github).
2. After Gitlab is installed you may sign if with the `root` user and password `5iveL!fe`
### GitLab
3. Make a user for yourself
1. Install GitLab.
* <https://about.gitlab.com/downloads/>
1. After GitLab is installed you may sign in with the `root` user. If you didn't specify a custom password during installation, a temporary password is located in `/etc/gitlab/initial_root_password`.
1. Make a user for yourself.
1. Make an SSH key to link with your user. You’ll want to do this on the machine you intend to edit code from (most likely not your Puppet master, but your local workstation or laptop).
1. Create a project called `control-repo`, and set the Namespace to be the `puppet` group.
1. Clone this control repository to your laptop/workstation:
* `git clone <repository url>`
* `cd control-repo`
1. Remove this repository as the origin remote:
* `git remote remove origin`
1. Add your internal repository as the origin remote:
* `git remote add origin <url of your gitlab repository>`
1. Push the production branch of the repository from your machine up to your git server
* `git push origin production`
4. Make an ssh key to link with your user. You’ll want to do this on the machine you intend to edit code from ( most likely not your puppet master but your local workstation / laptop )
1. Make a `Project` called `puppet` (with a short name of `PUP`)
1. Create a repository called `control-repo`
1. Create a user called `r10k` with a password of `puppet`.
* Make the r10k user an admin of the `PUP` project.
1. Either use the admin user to test pushing code, or create a user for yourself and add your SSH key to that user.
* If making a user for yourself, give your user account read/write or admin privilege to the `PUP` project.
1. Clone this control repository to your laptop/workstation
* `git clone <repository url>`
* `cd control-repo`
1. Remove this repository as the origin remote
* `git remote remove origin`
1. Add your internal repository as the origin remote
* `git remote add origin <url of your bitbucket repository>`
1. Push the production branch of the repository from your machine up to your git server
* `git push origin production`
6. Add your user to the `puppet` group as well
### GitHub
7. Create a project called `control-repo` and set the Namespace to be the `puppet` group
Follow [GitHub's documentation](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template) to create your control repository starting from this template.
8. Clone this control repository to your laptop/workstation
1. Create a repository called `control-repo` in your user account or organization. Ensure that "Initialize this repository with a README" is not selected.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
