From 9b2a0d902983477168f2f2eb655d5f3214cfe00f Mon Sep 17 00:00:00 2001 From: Nate McCurdy Date: Tue, 6 Feb 2018 15:59:51 -0800 Subject: [PATCH 1/4] Fix markdown list syntax --- README.md | 125 ++++++++++++++++++++++-------------------------------- 1 file changed, 50 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 6624a9f..4f9b9ae 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,9 @@ Table of Contents * [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](#Bitbucket/Stash) + * [Bitbucket/Stash](#bitbucketstash) * [Github](#github) -Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go) - # Where Did All The Previous Code Go? 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 set up many Puppet Enterprise components. As the code increased, so did the complexity of the control-repo project. To reduce that complexity, as well as continuing 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 @@ -22,97 +20,74 @@ All of the code that was previously in this repository still exists in separate This repository is a template control-repo that can be used with r10k or Puppet Enterprise Code Manager. 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. + * 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. ## Copy This Repo Into Your Own Git Server ### GitLab 1. Install GitLab. - - https://about.gitlab.com/downloads/ - -2. After GitLab is installed you may sign in with the `root` user and password `5iveL!fe`. - -3. Make a user for yourself. - -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 or laptop). - - http://doc.gitlab.com/ce/ssh/README.html - - https://help.github.com/articles/generating-ssh-keys/ - -5. Create a group called `puppet` (this is case sensitive). - - http://doc.gitlab.com/ce/workflow/groups.html - -6. Add your user to the `puppet` group as well. - -7. Create a project called `control-repo`, and set the Namespace to be the `puppet` group. - -8. Clone this control repository to your laptop/workstation: - - `git clone ` - - `cd control-repo` - -9. Remove this repository as the origin remote: - - `git remote remove origin` - -10. Add your internal repository as the origin remote: - - `git remote add origin ` - -11. Push the production branch of the repository from your machine up to your git server - - `git push origin production` + * +1. After GitLab is installed you may sign in with the `root` user and password `5iveL!fe`. +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 group called `puppet` (this is case sensitive). + * +1. Add your user to the `puppet` group as well. +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 ` + * `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 ` +1. Push the production branch of the repository from your machine up to your git server + * `git push origin production` ### Bitbucket/Stash 1. Install Bitbucket - - https://www.atlassian.com/software/bitbucket/download - + * 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. 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. - + * 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 ` - - `cd control-repo` - + * `git clone ` + * `cd control-repo` 1. Remove this repository as the origin remote - - `git remote remove origin` - + * `git remote remove origin` 1. Add your internal repository as the origin remote - - `git remote add origin ` - + * `git remote add origin ` 1. Push the production branch of the repository from your machine up to your git server - - `git push origin production` + * `git push origin production` ### GitHub 1. Prepare your local git client to authenticate with GitHub.com or a local GitHub Enterprise instance. - - https://help.github.com/articles/generating-ssh-keys/ - - https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/ + * + * +1. Create a repository called `control-repo` in your user account or organization. Ensure that "Initialize this repository with a README" is not selected. + * +1. Make a note of your repository URL (HTTPS or SSH, depending on your security configuration). +1. Clone this control repository to your laptop/workstation: + * `git clone ` + * `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 ` +1. Push the production branch of the repository from your machine up to your git server + * `git push origin production` -2. Create a repository called `control-repo` in your user account or organization. Ensure that "Initialize this repository with a README" is not selected. - - https://help.github.com/articles/creating-a-new-repository/ - -3. Make a note of your repository URL (HTTPS or SSH, depending on your security configuration). - -4. Clone this control repository to your laptop/workstation: - - `git clone ` - - `cd control-repo` - -5. Remove this repository as the origin remote: - - `git remote remove origin` - -6. Add your internal repository as the origin remote: - - `git remote add origin ` - -7. Push the production branch of the repository from your machine up to your git server - - `git push origin production` From c69edadddac3d939fc7ff8918dd643337369b316 Mon Sep 17 00:00:00 2001 From: Nate McCurdy Date: Tue, 6 Feb 2018 16:12:30 -0800 Subject: [PATCH 2/4] Reorganize the README and improve the documentation 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. --- README.md | 50 +++++++++++++++++++++++++++----------------------- 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 4f9b9ae..042287f 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,32 @@ -Table of Contents -================= +# A Puppet Control Repository - * [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) - * [Bitbucket/Stash](#bitbucketstash) - * [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) +* [Where Did All The Previous Code Go?](#where-did-all-the-previous-code-go) -# Where Did All The Previous Code Go? -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 set up many Puppet Enterprise components. As the code increased, so did the complexity of the control-repo project. To reduce that complexity, as well as continuing 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. +## What You Get From This control-repo -All of the code that was previously in this repository still exists in separate repositories under the [Puppet Ramp Up Program namespace within Github](https://github.com/Puppet-RampUpProgram) and can be re-connected to an existing control-repo if that is required by adding the modules to the Puppetfile. Alternatively, if that previously opinionated control-repo is desired, [it still exists on Github under the Puppet Ramp Up Program namespace.](https://github.com/Puppet-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/code_management/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/code_management/r10k.html) or Puppet Enterprise's [Code Manager](https://puppet.com/docs/pe/latest/code_management/code_mgr.html). -# What You Get From This control-repo +The important files and items in this template are as follows: -This repository is a template control-repo that can be used with r10k or Puppet Enterprise Code Manager. - -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. +* 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/5.3/config_file_environment.html) that correctly implements: + * A site directory for roles, profiles, and any custom modules for your organization. + * A config_version script. +* An example [config_version](https://puppet.com/docs/puppet/5.3/config_file_environment.html#configversion) script that outputs the git commit ID of the code that was used during a Puppet run. ## Copy This Repo Into Your Own Git Server +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). + ### GitLab 1. Install GitLab. @@ -91,3 +88,10 @@ The major points are: 1. Push the production branch of the repository from your machine up to your git server * `git push origin production` +## Where Did All The Previous Code Go? + +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 set up many Puppet Enterprise components. As the code increased, so did the complexity of the control-repo project. To reduce that complexity, as well as continuing 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 Ramp Up Program namespace within Github](https://github.com/Puppet-RampUpProgram) and can be re-connected to an existing control-repo if that is required by adding the modules to the Puppetfile. Alternatively, if that previously opinionated control-repo is desired, [it still exists on Github under the Puppet Ramp Up Program namespace.](https://github.com/Puppet-RampUpProgram/control-repo) This control-repo project will remain a template for anyone who would like a minimal 'starter' template. + From fda0396e06ad23a12abc9b3b83737926a8066ceb Mon Sep 17 00:00:00 2001 From: Nate McCurdy Date: Tue, 6 Feb 2018 16:26:51 -0800 Subject: [PATCH 3/4] Add a tree view with descriptions of important files --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.md b/README.md index 042287f..ee9bc19 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,29 @@ The important files and items in this template are as follows: * A config_version script. * An example [config_version](https://puppet.com/docs/puppet/5.3/config_file_environment.html#configversion) script that outputs the git commit ID of the code that was used during a Puppet run. +Here's a visual representation of the structure of this repository: + +``` +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/ # 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 moduelpath and config_version. +└── hiera.yaml # Hiera's configuration file. The Hiera hierarchy is defined here. +``` + ## Copy This Repo Into Your Own Git Server 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). From bab3453bb5dd094a41896a3643e80e086cc8762c Mon Sep 17 00:00:00 2001 From: Nate McCurdy Date: Tue, 6 Feb 2018 17:34:32 -0800 Subject: [PATCH 4/4] Simplify the info about the RampUp Program --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ee9bc19..aaed15c 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ * [GitLab](#gitlab) * [Bitbucket/Stash](#bitbucketstash) * [Github](#github) -* [Where Did All The Previous Code Go?](#where-did-all-the-previous-code-go) +* [Code Manager Setup](#code-manager-setup) ## What You Get From This control-repo @@ -111,10 +111,9 @@ To get started with using the control-repo template in your own environment and 1. Push the production branch of the repository from your machine up to your git server * `git push origin production` -## Where Did All The Previous Code Go? +## Code Manager Setup -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 set up many Puppet Enterprise components. As the code increased, so did the complexity of the control-repo project. To reduce that complexity, as well as continuing 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. +If you use Puppet Enterprise and have not yet enabled and configured Code Manager, in addition to reading the official [documentation](https://puppet.com/docs/pe/latest/code_management/code_mgr.html) for enabling it, you may want to look at the Ramp-Up Program's control repository instead of this one. It's similar to this repo except that it has batteries includes, so to speak. There are pre-built profiles for configuring Code Manager, generating SSH keys, and setting up your Git server to work with Code Manager. -All of the code that was previously in this repository still exists in separate repositories under the [Puppet Ramp Up Program namespace within Github](https://github.com/Puppet-RampUpProgram) and can be re-connected to an existing control-repo if that is required by adding the modules to the Puppetfile. Alternatively, if that previously opinionated control-repo is desired, [it still exists on Github under the Puppet Ramp Up Program namespace.](https://github.com/Puppet-RampUpProgram/control-repo) This control-repo project will remain a template for anyone who would like a minimal 'starter' template. +*