Merge pull request #102 from ekohl/update-links

Update links in README

.gitignore

@@ -1 +1 @@
-hieradata/nodes/example-puppet-master.yaml
+modules/

CODEOWNERS

@@ -0,0 +1 @@
+* @puppetlabs/cs-arch

Puppetfile

@@ -1,17 +1,17 @@
-forge "http://forge.puppetlabs.com"
+forge 'https://forge.puppet.com'
 
 # Modules from the Puppet Forge
 # Versions should be updated to be the latest at the time you start
-#mod "puppetlabs/inifile",     '1.5.0'
-#mod "puppetlabs/stdlib",      '4.11.0'
-#mod "puppetlabs/concat",      '2.1.0'
+#mod 'puppetlabs/inifile', '5.0.1'
+#mod 'puppetlabs/stdlib',  '7.0.1'
+#mod 'puppetlabs/concat',  '7.0.1'
 
 # Modules from Git
 # Examples: https://github.com/puppetlabs/r10k/blob/master/doc/puppetfile.mkd#examples
 #mod 'apache',
-#  :git    => 'https://github.com/puppetlabs/puppetlabs-apache',
-#  :commit => '83401079053dca11d61945bd9beef9ecf7576cbf'
+#  git:    'https://github.com/puppetlabs/puppetlabs-apache',
+#  commit: '1b6f89afdde0df7f9433a163d5c4b5328eac5779'
 
 #mod 'apache',
-#  :git    => 'https://github.com/puppetlabs/puppetlabs-apache',
-#  :branch => 'docs_experiment'
+#  git:    'https://github.com/puppetlabs/puppetlabs-apache',
+#  branch: 'docs_experiment'

README.md

@@ -1,85 +1,123 @@
-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)
-      * [Stash](#stash)
+  * [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:
+
+```
+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.
+```
 
 ## Copy This Repo Into Your Own Git Server
 
-###Gitlab
+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).
 
-1. Install Gitlab
- - https://about.gitlab.com/downloads/
+### GitLab
 
-2. After Gitlab is installed you may sign if with the `root` user and password `5iveL!fe`
+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).
+    * <https://docs.gitlab.com/ee/ssh/index.html>
+    * <https://help.github.com/articles/generating-ssh-keys/>
+1. Create a group called `puppet` (this is case sensitive).
+    * <https://docs.gitlab.com/ee/user/group/index.html>
+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 <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`
 
-3. Make a user for yourself
+### Bitbucket/Stash
 
-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 )
- - http://doc.gitlab.com/ce/ssh/README.html
- - https://help.github.com/articles/generating-ssh-keys/
+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. 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`
 
-5. Create a group called `puppet` ( this is case sensitive )
- - http://doc.gitlab.com/ce/workflow/groups.html
+### GitHub
 
-6. Add your user to the `puppet` group as well
+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.
 
-7. Create a project called `control-repo` and set the Namespace to be the `puppet` group
+<img width="429" alt="template button" src="https://user-images.githubusercontent.com/1392917/117215366-f4eeb280-adb2-11eb-9108-1bd45c4d98f3.png">
 
-8. Clone this control repository to your laptop/workstation
- - `git clone <repository url>`
- - `cd control-repo`
 
-9. Remove this repository as the origin remote
- - `git remote remove origin`
+### GitHub Enterprise
 
-10. Add your internal repository as the origin remote
- - `git remote add origin <url of your gitlab repository>`
+1. Prepare your local git client to authenticate with 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.
+    * <https://help.github.com/articles/creating-a-new-repository/>
+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 <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 github repository>`
+1. Push the production branch of the repository from your machine up to your git server
+    * `git push origin production`
 
-11. Push the production branch of the repository from your machine up to your git server
- - `git push origin production`
+## Code Manager Setup
 
-###Stash
-
-Coming soon!
-
-###Github
-
-Coming soon!
+If you use Puppet Enterprise see the official [documentation](https://puppet.com/docs/pe/latest/code_mgr.html) for enabling Code Manager.

data/common.yaml

@@ -0,0 +1,2 @@
+---
+message: "This node is using common data"

environment.conf

@@ -1,2 +1,2 @@
-modulepath          = modules:site:$basemodulepath
+modulepath     = site-modules:modules:$basemodulepath
 config_version = 'scripts/config_version.sh $environmentpath $environment'

hiera.yaml

@@ -0,0 +1,12 @@
+---
+version: 5
+
+defaults:
+  datadir: "data"
+
+hierarchy:
+  - name: "Yaml backend"
+    data_hash: yaml_data
+    paths:
+      - "nodes/%{trusted.certname}.yaml"
+      - "common.yaml"

hieradata/common.yaml

@@ -1,5 +0,0 @@
----
-message: "This node is using common data"
-
-#Puppet Server Tuning
-puppet_enterprise::master::puppetserver::jruby_max_requests_per_instance: 0

manifests/site.pp

@@ -1,30 +1,29 @@
 ## site.pp ##
 
-# This file (/etc/puppetlabs/puppet/manifests/site.pp) is the main entry point
+# This file (./manifests/site.pp) is the main entry point
 # used when an agent connects to a master and asks for an updated configuration.
+# https://puppet.com/docs/puppet/latest/dirs_manifest.html
 #
 # Global objects like filebuckets and resource defaults should go in this file,
-# as should the default node definition. (The default node can be omitted
-# if you use the console and don't define any other nodes in site.pp. See
-# http://docs.puppetlabs.com/guides/language_guide.html#nodes for more on
-# node definitions.)
+# as should the default node definition if you want to use it.
 
 ## Active Configurations ##
 
 # Disable filebucket by default for all File resources:
-#http://docs.puppetlabs.com/pe/latest/release_notes.html#filebucket-resource-no-longer-created-by-default
+# https://github.com/puppetlabs/docs-archive/blob/master/pe/2015.3/release_notes.markdown#filebucket-resource-no-longer-created-by-default
 File { backup => false }
 
-# DEFAULT NODE
-# Node definitions in this file are merged with node data from the console. See
-# http://docs.puppetlabs.com/guides/language_guide.html#nodes for more on
-# node definitions.
+## Node Definitions ##
 
 # The default node definition matches any node lacking a more specific node
-# definition. If there are no other nodes in this file, classes declared here
-# will be included in every node's catalog, *in addition* to any classes
-# specified in the console for that node.
-
+# definition. If there are no other node definitions in this file, classes
+# and resources declared in the default node definition will be included in
+# every node's catalog.
+#
+# Note that node definitions in this file are merged with node data from the
+# Puppet Enterprise console and External Node Classifiers (ENC's).
+#
+# For more on node definitions, see: https://puppet.com/docs/puppet/latest/lang_node_definitions.html
 node default {
   # This is where you can declare classes for all nodes.
   # Example:

scripts/code_manager_config_version.rb

@@ -1,9 +0,0 @@
-require 'json'
-
-environmentpath = ARGV[0]
-environment     = ARGV[1]
-
-r10k_deploy_file_path = File.join(environmentpath, environment, '.r10k-deploy.json')
-
-#output the sha1 from the control-repo
-puts JSON.parse(File.read(r10k_deploy_file_path))['signature']

scripts/config_version-r10k.rb

@@ -0,0 +1,19 @@
+#!/opt/puppetlabs/puppet/bin/ruby
+require 'json'
+require 'socket'
+
+environmentpath = ARGV[0]
+environment     = ARGV[1]
+
+# Get the hostname of the Puppet master compiling the catalog.
+# Sometimes the hostname is the fqdn, so we'll take the first segment.
+compiling_master = Socket.gethostname.split('.').first
+
+# Get the path to the Code Manager deployment info file.
+r10k_deploy_file_path = File.join(environmentpath, environment, '.r10k-deploy.json')
+
+# Get the first 12 characters of the commit ID out of the deployment file.
+commit_id = JSON.parse(File.read(r10k_deploy_file_path))['signature'][0...11]
+
+# Show the compiling master, environment name, and commit ID.
+puts "#{compiling_master}-#{environment}-#{commit_id}"

scripts/config_version-rugged.rb

@@ -0,0 +1,25 @@
+#!/opt/puppetlabs/puppet/bin/ruby
+begin
+  require 'rugged'
+  require 'socket'
+rescue LoadError
+  t = Time.new
+  puts t.to_i
+else
+  environmentpath = ARGV[0]
+  environment     = ARGV[1]
+
+  # Get the hostname of the Puppet master compiling the catalog.
+  # Sometimes the hostname is the fqdn, so we'll take the first segment.
+  compiling_master = Socket.gethostname.split('.').first
+
+  # Get the path to the environment being compiled.
+  repo = Rugged::Repository.discover(File.join(environmentpath, environment))
+  head = repo.head
+
+  # First 12 characters of the sha1 hash of the newest commit.
+  commit_id = head.target_id[0...11]
+
+  # Show the compiling master, environment name, and commit ID.
+  puts "#{compiling_master}-#{environment}-#{commit_id}"
+end

scripts/config_version.rb

@@ -1,23 +0,0 @@
-begin
-  require 'rugged'
-rescue LoadError => e
-  t = Time.new
-  puts t.to_i
-else
-
-  environmentpath = ARGV[0]
-  environment     = ARGV[1]
-
-  repo = Rugged::Repository.discover(File.join(environmentpath, environment))
-  head  = repo.head
-
-  #sha1 hash of the newest commit
-  head_sha = head.target_id
-
-  #the commit message associated the newest commit
-  commit = repo.lookup(head_sha)
-
-  #add something to find the remote url
-
-  puts head_sha 
-end

scripts/config_version.sh

@@ -1,12 +1,35 @@
-#!/bin/bash
-if [ -e $1/$2/.r10k-deploy.json ]
-then
-  /opt/puppetlabs/puppet/bin/ruby $1/$2/scripts/code_manager_config_version.rb $1 $2
-elif [ -e /opt/puppetlabs/server/pe_version ]
-then 
-  /opt/puppetlabs/puppet/bin/ruby $1/$2/scripts/config_version.rb $1 $2  
-else
-  /usr/bin/git --version > /dev/null 2>&1 &&
-  /usr/bin/git --git-dir $1/$2/.git rev-parse HEAD ||
-  date +%s
+#!/bin/sh
+
+# Usage
+if [ $# -ne 2 -o ! -d "$1" -o ! -d "$1/$2" ]; then
+  echo "usage: $0 <environmentpath> <environment>" >&2
+  exit 1
+fi
+
+# For portability, identify a preferred ruby executable to use
+ruby() {
+  [ -x /opt/puppetlabs/puppet/bin/ruby ] \
+    && /opt/puppetlabs/puppet/bin/ruby "$@" \
+    || /usr/bin/env ruby "$@"
+}
+
+# Determine how best to calculate a config_version
+if [ -e $1/$2/.r10k-deploy.json ]; then
+  # The environment was deployed using r10k. We will calculate the config
+  # version using the r10k data.
+  ruby $1/$2/scripts/config_version-r10k.rb $1 $2
+
+elif [ -e /opt/puppetlabs/server/pe_version ]; then
+  # This is a Puppet Enterprise system and we can rely on the rugged ruby gem
+  # being available.
+  ruby $1/$2/scripts/config_version-rugged.rb $1 $2
+
+elif type git >/dev/null; then
+  # The git command is available.
+  git --git-dir $1/$2/.git rev-parse HEAD
+
+else
+  # Nothing else available; just use the date.
+  date +%s
+
 fi

site-modules/adhoc/plans/myplan.pp

@@ -0,0 +1,9 @@
+# This is a description for my plan
+plan adhoc::myplan(
+  # input parameters go here
+  TargetSpec $targets,
+) {
+
+  # plan steps go here
+
+}

site-modules/adhoc/tasks/nix_example.json

@@ -0,0 +1,4 @@
+{
+    "description": "This is the description for the nix_example task",
+    "input_method": "environment"
+}

site-modules/adhoc/tasks/nix_example.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+# task content goes here

site-modules/adhoc/tasks/win_example.json

@@ -0,0 +1,4 @@
+{
+    "description": "This is the description for the win_example task",
+    "input_method": "powershell"
+}

site-modules/adhoc/tasks/win_example.ps1

@@ -0,0 +1 @@
+# task content goes here

site/role/manifests/all_in_one_pe.pp

@@ -1,5 +0,0 @@
-class role::all_in_one_pe {
-
-  include pe_code_manager_webhook
-
-}