Puppet is an open source configuration management tool, that can help you to manage lots of servers without writing customized scripts for setup and maintenance for each one or each group of them.
It’s very powerful and comes with lots of modules already, for nearly every task you face.<\/p>\n\n\n\n
In this post I’ll cover how to set up a” puppet master” (control server), managing different environments on it (for teams and\/or test\/production) with r10k, writing a simple module, connecting a host to the master and configure it automatically.
The master will be puppet5, so we can fully utilize the power of hiera, which allows us to separate data (configs) from code (modules).<\/p>\n\n\n\n
echo \"deb http:\/\/apt.puppetlabs.com stretch puppet\" >> \/etc\/apt\/sources.list.d\/puppet.list\nwget apt.puppetlabs.com\/pubkey.gpg\napt-key add pubkey.gpg\napt-get update\napt-get install puppet-master-passenger<\/code><\/pre>\n\n\n\nWe’ll use puppetmaster with apache passenger here, this is more than sufficient for even big environments.
puppetserver is the future though, as it is more scalable in very large environments.<\/p>\n\n\n\n
Setup<\/h4>\n\n\n\nroot@puppetmastertest:~# ls \/etc\/puppet\/\nauth.conf code hiera.yaml puppet.conf<\/code><\/pre>\n\n\n\nYou’ll find the above structure in \/etc\/puppet.
hiera.yaml<\/strong> basically describes the hierarchy puppet should search to lookup host(grou) infromation, Delete it for now, we’ll use it in our environments later.
auth.conf<\/strong> is used to control catalog and ssl information your hosts are allowed to access (leave it, it should be sufficient for now<\/strong>).
puppet.conf<\/strong> contains your log- and ssl paths, as well as a facter path and more (can be extended, see: https:\/\/puppet.com\/docs\/puppet\/5.3\/config_file_main.html) important for now are the log and ssl locations and also the path for facter.
(Enter the example from the next box into your puppet.conf)
The directory code<\/strong> contains modules and hieradata, normally everything is stored just there, but well use several environments, so we’ll first have to create the right structure.<\/p>\n\n\n\n[main]\nlogdir=\/var\/log\/puppet\nvardir=\/var\/lib\/puppet\nssldir=\/var\/lib\/puppet\/ssl\nrundir=\/var\/run\/puppet\nfactpath=$vardir\/lib\/facter\n\n[master]\nvardir = \/var\/lib\/puppet\ncadir = \/var\/lib\/puppet\/ssl\/ca\nssl_client_header = SSL_CLIENT_S_DN\nssl_client_verify_header = SSL_CLIENT_VERIFY\ncertname = puppetmaster\ndns_alt_names = puppetmaster, puppetserver.your.domain<\/code><\/pre>\n\n\n\nThe [main] Section is pretty self explanatory, logs are stored in logdir<\/strong> and most other “stuff” related to the function of puppet is stored in $vardir<\/strong> or related directories.
SSL-Certificates (as well as requests) from the clients are stored in $ssldir<\/strong> (We’ll come to that later), the reports for the puppetruns are stored under $vardir\/state and so on. $factpath<\/strong> is where puppet will look for custom facts.
The main section can be the same for master and clients<\/strong> but must not be.
The [master] section is specifically for the master itself.
Important here are dns_alt_names<\/strong> and certname<\/strong>, because puppetmaster brings it’s own CA (you can also use your own, but we won’t cover that here), so set especially dns_alt_names to whatever you think is useful when calling the master from the clients. <\/p>\n\n\n\nconnecting a client<\/h4>\n\n\n\necho \"deb http:\/\/apt.puppetlabs.com stretch puppet\" >> \/etc\/apt\/sources.list.d\/puppet.list\nwget apt.puppetlabs.com\/pubkey.gpg\napt-key add pubkey.gpg\napt-get update\napt-get install puppet<\/code><\/pre>\n\n\n\nLet’s connect our first client and leave the directories for now. We’ll cover them once this works.<\/p>\n\n\n\n
[main]\nserver = puppetmaster.your.domain\ncertname = puppettest1.your.domain\nenv = prod<\/code><\/pre>\n\n\n\nDelete the master section.
server<\/strong> is the fqdn of our puppetmaster
certname<\/strong> is the name we want for our ssl servercertificate. This is a fact and will be important when working with facts later (e.g. in hiera.yaml)
env<\/strong> is prod for now, because as long as we haven’t configured the master otherwise this is the only environment available. We’ll configure at least two later though, a testing and a productive environment.<\/p>\n\n\n\nroot@puppettest1:~# puppet agent -vot\nInfo: Caching certificate for ca\nInfo: csr_attributes file loading from \/etc\/puppet\/csr_attributes.yaml\nInfo: Creating a new SSL certificate request for puppettest1.your.domain\nInfo: Certificate Request fingerprint (SHA256): E5:71:47:CE:94:9B:A9:DC:DC:37:B7:92:89:BA:DD:78:75:D5:CC:72:06:A5:32:AF:83:8D:B0:5A:E9:81:3F:88\nInfo: Caching certificate for ca\nExiting; no certificate found and waitforcert is disabled<\/code><\/pre>\n\n\n\nUse the above command to connect the client to the puppetmaster. puppet automatically creates a csr.
You can view and sign it on the master like this:<\/p>\n\n\n\n
puppet cert list\n \"puppettest1.your.domain\" (SHA256) E5:71:47:CE:94:9B:A9:DC:DC:37:B7:92:89:BA:DD:78:75:D5:CC:72:06:A5:32:AF:83:8D:B0:5A:E9:81:3F:88\n\nroot@puppetmaster:~# puppet cert sign puppettest1.your.domain\nSigning Certificate Request for:\n \"puppettest1.your.domain\" (SHA256) E5:71:47:CE:94:9B:A9:DC:DC:37:B7:92:89:BA:DD:78:75:D5:CC:72:06:A5:32:AF:83:8D:B0:5A:E9:81:3F:88\nNotice: Signed certificate request for puppettest1.your.domain\nNotice: Removing file Puppet::SSL::CertificateRequest puppettest1.your.domain at '\/var\/lib\/puppet\/ssl\/ca\/requests\/puppettest1.your.domain.pem'<\/code><\/pre>\n\n\n\nIf something goes wrong with signing (or you need to migrate a node), you may issue “puppet cert clean $certname” and delete the certificate files in $ssldir on the client. Then repeat the above.
Tip:<\/strong> In large environments you will want to autosign certificates (policybased or just everything is up to you), read here on how to do this: https:\/\/puppet.com\/docs\/puppet\/5.3\/ssl_autosign.html
However, you should have a connected node by now. Let’s move on, filling it with stuff.<\/p>\n\n\n\nconfiguring the master<\/h4>\n\n\n\n
I’d recommend to do all configuration of the environments in a git repository (check out how to do this: here<\/a>), leaving the management up to r10k.
However, you can just take the examples and put it into the respective directories:<\/p>\n\n\n\n- \/etc\/puppet\/code\/environments\/test<\/li>
- \/etc\/puppet\/code\/environments\/production<\/li><\/ul>\n\n\n\n
Whatever you do, you should have at least two environments. One for testing and one for production.<\/p>\n\n\n\n
In your repository (or in prod\/test) create the following:<\/p>\n\n\n\n
vi environment.conf\nmodulepath = site-modules:modules:$basemodulepath\nconfig_version = 'scripts\/config_version.sh $environmentpath $environment'<\/code><\/pre>\n\n\n\nThis contains the path where puppet should look for modules and the path for config_version.sh (needed to manage the environments with r10k).
You may look these up with:<\/p>\n\n\n\n
puppet config print basemodulepath\n\/etc\/puppet\/code\/modules:\/usr\/share\/puppet\/modules\n\npuppet config print environment\nproduction\n\npuppet config print environmentpath\n\/etc\/puppet\/code\/environments<\/code><\/pre>\n\n\n\nCreate a Puppetfile in your repository and either use prod and test branch, or just create (for now) identical files in prod\/test folders:<\/p>\n\n\n\n
forge \"http:\/\/forge.puppetlabs.com\"\nmoduledir = 'modules'\n\n# Get a specific release from GitHub\n#mod 'puppet-gitlab',\n# :git => 'https:\/\/github.com\/voxpupuli\/puppet-gitlab' ,\n# :ref => '3.0.2'\n\n#mod 'helloworld', :local => true\n#mod 'base', :local => true\n#mod 'docker', :local => true\n#mod 'kubernetes', :local => true\n#mod \"puppetlabs\/inifile\"\n#mod \"puppetlabs\/stdlib\"\n#mod \"puppetlabs\/apt\"<\/code><\/pre>\n\n\n\nThe above is just an example, but a good one to walk you through it.<\/p>\n\n\n\n
- forge<\/strong> is the location of an external url to get (forge based) modules from, I use the official puppelabs forge.<\/li>
- moduledir<\/strong> tells puppet where to install these modules (relative to path)<\/li>
- mod<\/strong> contains all attributes of the respective module.
Let’s take the first block, the name of the module is ‘puppet-gitlab’ but I use another git source than the standard one (:git<\/strong> => ‘http:\/\/$modulegit’), also I want a specific version (:ref <\/strong>=> ‘3.0.2’).
In everyday work you’ll most probably want to use specific version in production environment, after you’ve tested them and “latest” (this is fetched as a default if you don’t provide a version) in test environments.
Try it out, with hiera properly configured (later), you’ll get a fully configured and operational gitlab server in no time.
However, when working with r10k, it will wipe everything that is not referenced (so don’t forget to commit your changes and push them before running it). So there is one more important parameter:<\/li>- :local => true<\/strong>
This is to indicate that r10k should not try to download this module from somewhere but also should not wipe it, because (most likely) it’s one of your self written modules (I’ll cover helloworld, base and docker later, so that you get the idea on how to write basic modules and how to combine them to sets).
Best create a git repo for those modules and later clone\/pull them separately if needed. <\/li>- I commented nearly everything for now but you may already uncomment the last two modules:
“puppetlabs\/stdlib” and “puppetlabs\/apt” as they are pretty useful and I use them in every setup.
check it out: https:\/\/forge.puppet.com\/puppetlabs\/stdlib. inifile is useful when using the gitlab module.<\/li><\/ul>\n\n\n\nCreate the hiera.yaml in your repo:<\/p>\n\n\n\n
vi hiera.yaml\n\n---\nversion: 5\ndefaults:\n data_hash: yaml_data\n datadir: hieradata\nhierarchy:\n - name: nodes\n path: nodes\/%{trusted.certname}.yaml\n - name: Common\n path: common.yaml<\/code><\/pre>\n\n\n\nThis tells hiera that it should use yaml (data_hash), could be json as well but I haven’t tried that at all.
Also it references the directory where hiera should look for configuration data (this is where our cluster\/note$resourceconfiguration goes).
Important is the hierarchy, because it tells hiera how<\/strong> and where to look for data.
It’s best to let hiera look from the most<\/strong> to the least<\/strong> specific definition.
In this example we create a simple hierarchy (under hieradata, which is a folder in our repo):<\/p>\n\n\n\nmkdir hieradata\nmkdir nodes\ntouch nodes\/yourserver.your.domain.yaml<\/code><\/pre>\n\n\n\nThis way, if the agent connects the master the master looks under nodes (as configured) and finds a trusted.certname<\/strong>.yaml because it’s the certname of the client. Hiera stops here at the most specific match and starts applying whatever config we put into nodes\/yourserver.your.domain.yaml.
Next, create a file named common.yaml under hieradata.<\/p>\n\n\n\ntouch hieradata\/common.yaml<\/code><\/pre>\n\n\n\n
This file will contain the configuration everything that has no specific match.
As you can see, you may extend and improve this structure according to your needs, maybe naming your servers\/clusters FunctionDepartmentLocationVlan.your.domain or whatever and have different paths for different combinations of what may be implied by this structure at your company.
You may also specify different merge strategies<\/strong> for hiera like stop at first match or merge most and least specific, etc.
You get the idea. Let’s stick with our example for now, but if you are interested, read here: https:\/\/puppet.com\/docs\/puppet\/4.10\/hiera_merging.html
<\/p>\n\n\n\nvi r10k.yaml\n\ncachedir: '\/var\/cache\/r10k'\nsources:\n yourdepartment:\n basedir: '\/etc\/puppet\/code\/environments'\n remote: 'https:\/\/gitlab.your.domain\/youruser\/puppetcontrolrepo.git'\n prefix: true<\/code><\/pre>\n\n\n\nCreate the above file in your git repo (if you’ve decided not to use git, which is not recommended, skip this).
This tells r10k where to fetch the environments (I named it yourdepartment, you may configure as much as you like, to allow different teams to build their own puppet environment for example or just to separate things from each other).
prefix<\/strong> is the important option here, because it tells r10k to prefix the environments with the respective branch names.
So if you have a production and a test branch for “yourdepartment” in your gitlab repo, they will be checked out separateley.
This allows you to set the environment of some nodes (either in \/etc\/..\/puppet.conf or on the commandline with env=yourenvironment_master or –environment=yourenvironment_test) so that you can use them for testing or production, just as you need.
I recommend you keep this in your git repo under version control.<\/strong> But you need copy it to \/etc\/r10k.yaml<\/strong> on your master (if you like, create another repo for that).<\/p>\n\n\n\nmkdir modules\nmkdir manifests<\/code><\/pre>\n\n\n\nOur initial structure is complete. commit and push your code into git (no git? ignore) and do a “checkout -b test” to create a test branch while you’re at it.
Then install r10k on your master.<\/p>\n\n\n\n
gem install r10k<\/code><\/pre>\n\n\n\nNow clone your repo initially (so that r10k.yaml exists, you may also just copy it there)<\/p>\n\n\n\n
git clone https:\/\/gitlab.your.domain\/youruser\/puppetcontrolrepo \/etc\/puppet\/code\/environments\/yourdepartment_master<\/code><\/pre>\n\n\n\nYour master branch is checked out. From now on r10k will take care about updating the environment, installing modules and so on (after you’ve pushed to git of course and ran te appropriate commands).
I would advise to either run r10k regularly via cron or on demand using git as a trigger or some ssh command when running the master for several teams.
However, let’s check out the important commands, like checking the syntax of your puppetfile.<\/p>\n\n\n\n
\/etc\/puppet\/code\/environments\/yourdepartment_master# r10k puppetfile check\nSyntax OK<\/code><\/pre>\n\n\n\nThen let’s see what r10k would do (dry-run):<\/p>\n\n\n\n
\/etc\/puppet\/code\/environments\/yourdepartment_master# r10k deploy display -v\n---\n:sources:\n- :name: :yourdepartment\n :basedir: \"\/etc\/puppet\/code\/environments\"\n :prefix: true\n :remote: https:\/\/gitlab.your.domain\/youruser\/puppetcontrolrepo.git\n :environments: []<\/code><\/pre>\n\n\n\nIf everything seems right, let’s deploy our environment:<\/p>\n\n\n\n
r10k deploy environment -v -p\n\nroot@puppetmastertest:\/etc\/puppet\/code\/environments# r10k deploy environment -v -p\nWARN -> The r10k configuration file at \/etc\/r10k.yaml is deprecated.\nWARN -> Please move your r10k configuration to \/etc\/puppetlabs\/r10k\/r10k.yaml.\nINFO -> Using Puppetfile '\/etc\/puppet\/code\/environments\/test_master\/Puppetfile'\nINFO -> Using Puppetfile '\/etc\/puppet\/code\/environments\/test_test\/Puppetfile'\nINFO -> Deploying environment \/etc\/puppet\/code\/environments\/test_master\nINFO -> Environment test_master is now at 7d56685293dae8a68673b7ba1009e8ceea51571a\nINFO -> Deploying Puppetfile content \/etc\/puppet\/code\/environments\/test_master\/modules\/helloworld\n[...]<\/code><\/pre>\n\n\n\nIgnore the warnings, they tell you that we’re not using the “official” puppet package from puppetlabs but the one from the debian repository (one uses \/etc\/puppet and the other \/etc\/puppetlabs\/).<\/p>\n\n\n\n
You now have r10k management for your puppetmaster! Let’s go on and write some basic modules.<\/p>\n\n\n\n
writing basic modules<\/h4>\n\n\n\n
Either develop your modules in the modules folder<\/strong> you created in your git puppet repository or use a different one (or several), that depends on your setup and company structure.
Create a site.pp<\/strong> file in your manifests folder.
In the days of old these contained node configurations but here we tell hiera how to lookup and merge all the classes it finds and put them in the catalog (this is the merge strategy<\/strong>, mentioned further above).
More on the topic: https:\/\/puppet.com\/docs\/puppet\/5.3\/hiera_automatic.html<\/p>\n\n\n\nnotify { \"Using $environment\" :\n message => \"Processing catalog from the $environment environment.\" ,\n}\n\nlookup ('classes', Array[String], 'unique').include<\/code><\/pre>\n\n\n\nThe interesting part is the lookup statement.
The notify statement is just for debug purposes. It always shows the environment used on the client.
Let’s create a base module which we can use on all of our hosts:<\/p>\n\n\n\n
mkdir -p modules\/base\/manifests\nmkdir -p modules\/base\/files\nmkdir -p modules\/base\/manifests\/openssh<\/code><\/pre>\n\n\n\nOur base module will contain an openssh module and a bashrc module (you can download much better modules from puppetlabs, this is just to get the idea)<\/p>\n\n\n\n
vi modules\/base\/manifests\/openssh.pp\n\nclass base::openssh {\n class { base::openssh::install: }\n}\n\nvi modules\/base\/manifests\/openssh\/install.pp\n\nclass base::openssh::install {\n package { \"openssh-client\":\n ensure => present,\n }\n package { \"openssh-server\":\n ensure => present,\n }\n}<\/code><\/pre>\n\n\n\nIn our base module we create an openssh.pp file which contains a reference openssh::install class. We could have defined it in the file itself, but later, if you add to this rather rudimentary openssh module or create your own,you’ll want to design them as modular as possible. SO you could add e.g a configure.pp and so on. However, this will make sure, that always the latest version of ssh client and server will be installed on our node (in prod you may want to work with a specific version).<\/p>\n\n\n\n
root@puppettest1:~# puppet resource package openssh-client\npackage { 'openssh-client':\n ensure => '1:6.7p1-5+deb8u8',\n}<\/code><\/pre>\n\n\n\nOn a host where you have some package installed you can let puppet tell you about it’s attributes and then write your code accordingly.<\/p>\n\n\n\n
root@puppettest1:~# puppet resource user root\nuser { 'root':\n ensure => 'present',\n comment => 'root',\n gid => '0',\n home => '\/root',\n password => '$........onbZvbm0',\n password_max_age => '99999',\n password_min_age => '0',\n shell => '\/bin\/bash',\n uid => '0',\n}<\/code><\/pre>\n\n\n\n