In short:

1. cfpuppetserver - Puppet Server + PuppetDB + PostgreSQL + r10k + librarian-puppet automatic configuration module
2. Brief Introduction to Puppet
3. Describes initial deployment from scratch

Thematic cycle:

• Part I: network and network filter (cfnetwork + cffirehol)
• Part II: Access and Standard Environment (cfauth + cfsystem)
• Part III: Install Puppet Server (cfpuppetserver)
• Part IV: Centralized Management (cftotalcontrol)
• Part V: Databases (cfdb)
• Part VI: Topical Blacklists and Secure Knock

Some lyrics. It would seem that the whole cycle should be started with this article, but the target audience is more experienced users of the Open Source products of Puppet Labs, who are not satisfied with the separate little-integrated modules with Puppet Forge. As with any case of the “library vs. framework”, the cost is to follow the author’s worldview of the integrated solution.

A little bit about how Puppet works

Puppet is first and foremost a specific language for the declarative specification of the final state of the system. For comparison, the GNU Makefile is extremely suitable, where, in addition to directly describing dependencies, there is the possibility of starting to the fullest.

Abstraction Puppet is about the following ( disrupting templates - forget everything you knew about the terms in programming! ).

• A node is a collection of configurations for a specific target system. In fact, this is a special case of the class.
• A class is a set of declarative logic that is included in the node configuration or other classes. The class has neither instances nor methods, but there are parameters and variables defined inside logic. In fact, this is more a procedure that can inherit another procedure by a banal code extension and not quite a banal scope of variables.
• Type (type) - but it already looks more like a classic class - it assumes instances with a name and definitely specified parameters, but nothing more. A concrete type implementation can be written in the form of a Puppet script via define , which creates instances of other types or as an extension to Ruby with a flight of fancy.
• A resource is actually the named instances of the Types. The name of each resource is unique within a specific type within a node (directory) configuration.
• Variables - well, in short, these are constants ... Up to the version of Puppet 4, with their scope, it was still worse. Now it is adequate: for use from outside the place of definition, a fully qualified identifier is required, except for the case of class inheritance.

Puppet can be used for local deployment without a network and related infrastructure. This can be used to create container images. There is even a whole line of campaigners for abandoning the centralized server.

In the ideologically correct key, the Puppet infrastructure consists of an agent — a privileged service on the target system and a server that distributes valuable instructions in the form of declarative resource directories upon request from agents. Security is implemented at the level of a private public key infrastructure ( X.509 ). Simply put, the same mechanisms as in HTTPS, but with its own CA and mandatory verification of the client certificate.

In a simplified form, the deployment procedure looks like this:

1. Processing using TLS and X.509 (establishing a connection, updating the CRL, checking certificate limits, etc.)
2. The agent receives fact generators from the server with caching and all the tasks (more precisely, everything from the lib / folders in modules is pulled). It’s easy to add your Ruby script to collect information of interest.
3. The agent collects facts about the target system and sends to the server. All facts can be easily viewed manually through puppet facts . These facts are available as global variables.
4. The server makes a directory of resources and sends it to the agent. Under this lies a whole layer of different concepts.
5. The agent pulls everything you need from the server and brings the system to the specified form. The agent himself does not know how to deal with resources, he relies on the implementation of providers (the semantic translation will be the "embodiment", and not the supplier) of specific types of resources. Some providers are standard and come in Puppet packages, while the rest are pulled out of the modules.

For tasting all the charms, there are additional buns in the form:

• A module is a collection of declarative Puppet scripts, Ruby extensions for Puppet, files, file templates, Hiera data, and more. A more correct term would be "package."
• Environment (Environment) - a set of scripts, modules and Hiera data. With the complexity of the infrastructure, it was inevitably necessary to separate the configuration beyond the standard division by nodes. Basically, this is required for pilot innovations and banal access control (when not all admins have access to all IT infrastructure nodes).
• Hiera is a hierarchical database. Such a formulation can be very daunting. This is probably why it was changed in the documentation of later versions. In fact, it is an extremely simple and convenient mechanism for pulling a configuration out of YAML or JSON files. The hierarchy consists in the ability to specify the order of reading a set of configuration files - i.e. hierarchy / priority of these files.
  
  • In addition to pulling data on a function call, Puppet pulls out the class parameters by default, which is the main highlight.
  • Of course, Hiera supports the interpolation of facts and even the calling of special functions.
  • Puppet 4.3 implemented the same functionality again to support not only the global database, but also the local one for the Environment and the Module, although the author has already found several problems in their implementation ( PUP-5983 , PUP-5952 and PUP-5899 ), which were Puppet Labs is instantly fixed.
  • Several strategies for extracting values ​​from all files across the hierarchy are supported:
    
    • first - the first priority value is given
    • unique - collects all values ​​into a one-dimensional array and removes duplicates
    • hash - unites all found YAML Hash. Duplicate keys are selected by priority.
    • deep - essentially a recursive version of hash
  • The beauty is that the sampling strategy can be set as when calling the lookup() function, since and in any hierarchy file using the special key lookup_options , which is actively used in the cfnetwork module.
• PuppetDB is essentially a business logic layer around a relational database (PostgreSQL) that allows you to save reports of facts and deployments and export resources for later import into directories on other nodes or select through special functions. There is also a web muzzle in the form of Puppet Dashboard.
• X.509 PKI is the already mentioned certificate infrastructure, which is extremely convenient to use for other services without the need to manage a separate infrastructure.
• MCollective seems to be a useful thing for the event launch of tasks on a server farm, but the author has a certain lack of confidence in the security of a particular solution.
• Puppet Forge is an open platform for publishing and downloading Modules.
• some other features in the form of controlling external devices such as Cisco equipment and deployment on bare hardware, but this is another story

Security and Availability Notes

It is required to understand that Puppet Server becomes a vulnerability of the entire IT infrastructure, since determines the final configuration of all systems. In special cases, it makes sense to do the separation - a separate server for critical infrastructure elements with extremely limited access and manual updating, and the second for everything else.

Availability Puppet Server determines the ability to manage the entire infrastructure. It makes sense to place Puppet Server on a virtual machine in a more reliable and quickly recoverable third-party cloud than its own capabilities. Or, you should install multiple servers.

In any case, do not install other services on the system where Puppet Server with gadgets will be deployed. Virtualization and containerization to help you.

Multi-master (several separate Puppet Server)

• In this case, only one server acts as a CA (Certificate Authority) - its inaccessibility means the impossibility to add new nodes.
  
  • Puppet allows the use of third-party X.509 infrastructure, if the built-in does not suit.
• All configuration (Environment) should be stored in the version control system and deployed on each server simultaneously.
• The only thing in common is the PostgreSQL database, the organization of which high availability is beyond the scope of this article.
• The cfpuppetserver module supports installations as a primary (with CA) and as a secondary server.

What significant has changed from older versions

The manufacturer has a full description.

• All services moved to JVM, JRuby and Jetty. Beyond the obvious advantages of integration, there are downsides to memory consumption.
• Added lambda functions for processing collections - now there is no need to cut crutches on Ruby or pervert through create_resources ()
• The EPP template processing tool has appeared - essentially the same ERB , but with Puppet DSL instead of Ruby,
• The default configuration file directory structure has changed greatly.
• Data Providers support has appeared for Environments and Modules (hacks are no longer required).
• Diminishing the role of the global Hiera. A new associated command is the puppet lookup .

Installation

This process is quite primitive, but requires adherence to a certain sequence of steps. Since doing it manually is a thankless task, the author will teach the bad, namely, download incomprehensible scripts from the Internet and run as root on his system.

The three main components of the server are Puppet Server, PuppetDB and PostgreSQL itself. They can all be pushed into one node or split into two or three systems. Puppet Server and Puppet DB can be run multiple times, but PostgeSQL is a single point of failure. There are various approaches to replication and clustering of PostgeSQL. A convenient approach in the case of primary and secondary servers will be Master + Read-Only Slave, which is supported in PuppetDB itself as the main and read-only database node, but automating this configuration takes time and therefore has not yet Included in the cfpuppetserver module.

Directly, the configuration can be simply stored at least on the file system along with Puppet Server, but this is how to write scripts on the combat web server. The best solution is the git repository. The r10k utility can pull out all the branches of the repository and deploy them to the Puppet Server as separate Environments. r10k is bad enough with dependency pulling, so librarian-puppet is used on top. It is worth noting immediately that the main canonical environment of Puppet is "production". Therefore, in the configuration repository, you should use a branch called "production" and not "master".

System requirements

For iron described by the manufacturer . The cfpuppetserver module cfpuppetserver only supports Debian Jessie + and Ubuntu Trusty +.

Configuration in git

For the r10k itself, the placement of the repository does not really matter - the main thing is its availability. For example, for testing purposes, the repository can be placed on the same system with access via file:// . A good start would be an example of the codingfuture / puppet-exampleenv configuration .

1. git clone https://github.com/codingfuture/puppet-exampleenv my-puppet-conf && cd my-puppet-conf repository: git clone https://github.com/codingfuture/puppet-exampleenv my-puppet-conf && cd my-puppet-conf
2. Set the general admin access settings, using the hints in the comments:
   
   • $EDITOR data/common.yaml
3. Create a node configuration:
   
   • $MY_DOMAIN - root domain name (for example, example.org)
   • $HOST_NAME - the name of the client node without a domain
   • mkdir data/$MY_DOMAIN
   • cp data/example.com/puppet.yaml data/${MY_DOMAIN}/puppet.yaml
   • $EDITOR nano -w data/${MY_DOMAIN}/puppet.yaml - setting up a node with Puppet Server according to the prompts in the comments
   • cp data/example.com/host.yaml data/${MY_DOMAIN}/${HOST_NAME}.yaml
   • $EDITOR nano -w data/${MY_DOMAIN}/${HOST_NAME}.yaml - setting up an arbitrary node using the prompts in the comments
4. We push on own Git the server or we make available locally on a node with Puppet Server through rsync or scp. The local repository is convenient as an intermediate step until the Git server is deployed from the Puppet itself. In a sense, it resembles a compiler build in several steps.

We put from scratch on a clean system

The cfpuppetserver module allows cfpuppetserver to install everything using the Puppet tool itself, but for the initial installation, the basic operations are duplicated by the Bash script.

On the target system:

1. Download the installation script: wget https://raw.githubusercontent.com/codingfuture/puppet-cfpuppetserver/master/setup_puppetserver.sh
2. Check the script and frown: less setup_puppetserver.sh
3. Run: bash setup_puppetserver.sh <repo_uri> puppet.${MY_DOMAIN} .
   
   • Example with remote repository: bash setup_puppetserver.sh ssh://git@git.example.com/puppet-conf
   • Example with local: bash setup_puppetserver.sh file:///root/puppetconf/
4. We look how the system puffs up and does not install everything very quickly.
5. If remote repository:
   
   • Create a ssh key at root: ssh-keygen -t rsa -b 2048
   • We register the public key /root/.ssh/id_rsa.pub on a remote Git server ...
   • ... and in the same place we configure Git hook with a call of the following command: /usr/bin/ssh -T deploypuppet@puppet.${MY_DOMAIN} ./puppetdeploy.sh
6. Run the manual configuration deployment: /etc/puppetlabs/deploy.sh
7. Trying how it works on the server itself: /opt/puppetlabs/bin/puppet agent --test
8. Check network settings, network filter and SSH access

Add managed nodes

1. The full name of the Puppet Server should be accessible via DNS on the managed host or should be “sewn up” in / etc / hosts.
   
   • Example: echo "128.1.1.1 puppet.example.com" >> /etc/hosts
2. On the node with Puppet Server, run the following script /opt/codingfuture/bin/cf_gen_puppet_client_init ${HOST_NAME}.${MY_DOMAIN} .
3. The result is copied entirely and pasted into the command line on the target system.
4. We are waiting for the execution to finish and run /opt/puppetlabs/bin/puppet agent --test . When you first start, a certificate signing request will be generated.
5. Go to the Puppet Server node to sign the certificate.
   
   • puppet cert list - we verify the signature of the certificate for greater paranoia.
   • puppet cert sign ${HOST_NAME}.${MY_DOMAIN} - in fact, we sign the certificate.
6. Go back to the managed node and run: / opt / puppetlabs / bin / puppet agent - test` again. This will force the deployment procedure.
7. We are waiting until the end of the deployment via Puppet Agent.
8. Everything, you have a minimal Puppet infrastructure ready!

 bash <<EOT #!/bin/bash http_proxy= if test "\$(id -un)" != 'root'; then echo 'This script must run as root' exit 1 fi if test ! -z ""; then echo -n >/etc/cflocation fi if test ! -z ""; then echo -n >/etc/cflocationpool fi if test ! -z "\$http_proxy"; then export http_proxy export https_proxy="\$http_proxy" export HTTP_PROXY="\$http_proxy" export HTTPS_PROXY="\$http_proxy" fi echo host.example.com > /etc/hostname hostname host.example.com if ! which lsb-release | read; then apt-get install lsb-release fi codename=\$(lsb_release -cs) if test -z "\$codename"; then echo "Failed to detect correct codename" exit 1 fi wget https://apt.puppetlabs.com/puppetlabs-release-pc1-\${codename}.deb dpkg -i puppetlabs-release-pc1-\${codename}.deb mkdir -p /etc/puppetlabs/puppet cat > /etc/puppetlabs/puppet/puppet.conf <<EOF [main] certname = host.example.com server = puppet.example.com ca_server = puppet.example.com environment = production EOF apt-get update && apt-get install puppet-agent while ! /opt/puppetlabs/bin/puppet agent --test --wairforcert 120; do echo "Please go to puppetserver and exec the following command when we wait for key" echo "> puppet cert sign host.example.com" echo "Use CTRL+C to stop cycle, if fails due to different reasons" sleep 5 done EOT 

Module Description

Full list of Bash parameters of the initial installation script

 ~# ./setup_puppetserver.sh Usage: ./setup_puppetserver.sh <r10k_repo_url> [<certname=hostname> [<cflocation> [<cflocationpool> [<http_proxy>] ] ] ] 

• r10k_repo_url - Git URI repository
• certname - FQDN of the node
• cflocation - initialization of the fact cf_location
• cflocationpool - initialize the cf_location_pool fact
• http_proxy - proxy server for HTTP and HTTPS requests

Full list of Bash parameters for the Puppet Client Initialization Script

 ~# /opt/codingfuture/bin/cf_gen_puppet_client_init Usage: cf_gen_puppet_client_init <certname> [<cflocation> [<cflocationpool> [<http_proxy>]]] 

The value of the parameters is the same as in the previous script.

cfpuppetserver class

• deployuser = 'deploypuppet' - username for automatic deployment of configuration updates
• deployuser_auth_keys = undef - list of keys for $ deployuser
• repo_url = undef - repository URI (example: ssh: // user @ host / repo or file: /// some / path)
• puppetserver = true - whether to install the Puppet Server component on this node
• puppetdb = true - whether to install the PuppetDB component on this node
• puppetdb_port = 8081 - port for PuppetDB
• setup_postgresql = true - whether to install the PostgreSQL component on this node (only if the PuppetDB installation is enabled)
• service_face = 'any' - the name of the cfnetwork::iface for accepting incoming connections
• puppetserver_mem = auto - RAM under Puppet Server in megabytes (minimum 192MB)
• puppetdb_mem = auto - RAM under PuppetDB in megabytes (minimum 192MB)
• postgresql_mem = auto - RAM under PostgreSQL in megabytes (at least 128MB)

class cfpuppetserver::puppetdb

• postgresql_host = 'localhost' - database address
• postgresql_listen = $postgresql_host - the value goes directly to PostgreSQL listen_addresses
• postgresql_port = 5432 - database port
• postgresql_user = 'puppetdb' - PuppetDB user in database
• postgresql_pass = 'puppetdb' is the password of the PuppetDB user in the database
• postgresql_ssl = false - enable connection encryption based on Puppet PKI certificates

class cfpuppetserver::puppetserver

• autosign = false - DO NOT use in a combat environment, except in the DMZ. There is only to automate testing.
• global_hiera_config = 'cfpuppetserver/hiera.yaml' - the path to the default Hiera configuration file according to the canons of Puppet (the first component is the module name, the rest is the path under the files/ folder in the module)

UPD 2016-03-12
Updated the name of the client initialization generation script (cf_gen_puppet_client_init).