puppet-deploy/README.md

Puppet-deploy
=============

Ovvero della centralizzazione, automazione e documentazione delle configurazioni di un server autogestito

### Requisiti

#### Puppet
 - [Puppet](https://puppetlabs.com/)
 - [Puppet modules](https://docs.puppetlabs.com/puppet/latest/reference/modules_fundamentals.html)
 - **puppet masterless**
  - [puppet masterless server automation on a very small scale](https://www.tiredpixel.com/2014/02/23/puppet-masterless-server-automation-on-a-very-small-scale/)

#### Git
 - [Git](http://www.git-scm.com/)

#### gcrypt
 - [Github](https://github.com/joeyh/git-remote-gcrypt)
 - In Debian 7.x Wheezy si installa da backports

#### MyRepos
 - https://myrepos.branchable.com/

#### Riseup shared puppet modules
 - [Shared puppet modules](https://gitlab.com/groups/shared-puppet-modules-group)


#### Presupposti
 - Semplificare l'installazione l'installazione di un nuovo server
 - Semplificare la reinstallazione di un server esistente
 - Mantenere logica, dati e configurazioni separati
 - Avere un versioning delle confgiurazioni
 - Facilitare la collaborazione degli amministratori nel mantenimento dei server/servizi
 - Facilitare la collaborazione nello sviluppo degli strumenti
 - Collaborare con gli altri collettivi/server/reti
 - Evitare Single Point of Failure
 - Non creare tool nuovi, utilizzare l'esistente (soprattutto se conosciuto)

#### Architettura

##### MyRepos
 - Tutto parte dalla configurazione di mr, che elenca quali repository scaricare e mantenere aggiornati.
 - **/root/.mrconfig** elenca i repository ed e' parametrizzato in funzione di SITE, HOSTNAME e REPO_ROOT
<pre>
[DEFAULT]
lib = SITE="nome_site" && \
  HOSTFQDN="$(hostname --fqdn)" && HOSTNAME="$(hostname)" && \
  REPO_ROOT="git@gitlab.com:organization/"
[/etc/puppet]
checkout = git clone ${REPO_ROOT}/puppet-deploy.git puppet
order = 1
[/etc/puppet/site-conf]
checkout = git clone gcrypt::${REPO_ROOT}/siteconf-${SITE}.git site-conf
order = 2
chain = true
[/etc/puppet/site-conf/host-conf]
checkout = git clone gcrypt::${REPO_ROOT}/hostconf-${HOSTNAME}.git host-conf
order = 3
chain = true
[/etc/puppet/modules/common]
checkout = git clone ${REPO_ROOT}/module-common.git common
order = 4
[/etc/puppet/modules/stdlib]
checkout = git clone ${REPO_ROOT}/puppetlabs-stdlib.git stdlib
        cd stdlib && git checkout tags/4.5.1
order = 4
[/etc/puppet/modules/apt]
checkout = git clone ${REPO_ROOT}/module-apt.git apt
order = 4
[/etc/puppet/modules/concat]
checkout = git clone ${REPO_ROOT}/module-concat.git concat
order = 4
[/etc/puppet/modules/lsb]
checkout = git clone ${REPO_ROOT}/module-lsb.git lsb
order = 4
[/etc/puppet/modules/postfix]
checkout = git clone ${REPO_ROOT}/module-postfix.git postfix
order = 4
</pre>
 - **/root/.mrtrust** istruisce myrepos per fidarsi dei file .mrconfig inclusi nei repository di configurazione del sito e dell'host
<pre>
/etc/puppet/site-conf/.mrconfig
/etc/puppet/site-conf/host-conf/.mrconfig
</pre>

##### Repository Git
 - **[<font color="yellow">conf</font>, <font color="red">world-wide</font>, <font color="red">clear</font>]** **[puppet-deploy](http://git.lattuga.net/opuppet/puppet-deploy)**
  - E' il progetto principale in cui viene mantenuta tutta e sola la configurazione di puppet e hiera;
  - Ogni sviluppatore ha un account read-write sul repository centrale di questo progetto;
  - Una copia del repository e' distribuita su ogni server, con account read-only, nella directory `/etc/puppet` (su Debian);
  - **NON** contiene dati sensibili (chiavi e password); 
  - **NON** contiene dati o tabelle utenti; 
  - Il file `manifests/site.pp` contiene la dichiarazione di default per i nodi, che include i ruoli definiti nella configurazione [`hiera_include('host-roles')`]

 - **[<font color="cyan">logic</font>, <font color="red">world-wide</font>, <font color="red">clear</font>]** **module-$(prog-name)** 
  - Quando disponibile il clone iniziale deriva da gli [shared puppet module](https://gitlab.com/groups/shared-puppet-modules-group)
  - Sono i moduli puppet responsabili di una singola funzionalita'/programma
  - Rappresentano il principale luogo di collaborazione nella comunita'. Committare sui moduli upstream significa sviluppare la logica su cui tutti i siti si basano. 
  - Es: module-postfix, module-apt, etc. 

 - **[<font color="yellow">conf</font>, <font color="orange">site-wide</font>, <font color="green">gcrypt</font>]** **siteconf-$(site-name)** 
  - Contiene principalmente (solo?) due file:
   - site.yaml: file utilizzato da hiera per determinare le proprieta' e le configurazioni specifiche di un sito
   - .mrconfig: configurazione di myrepos per includere i moduli (repository git) specifici per un sito

 - **[<font color="cyan">logic</font>, <font color="orange">site-wide</font>, <font color="green">gcrypt</font>]** **module-$(site-name)** 
  - Modulo (o moduli) specifici del sito (es. ortiche), che contiene funzionalita' utili solo per uno specifico gruppo di server; 
  - Esistono due differenti filosofie da valurare
   - O questo modulo non dovrebbe esistere e tutte le funzionalita' utili dovrebbero essere portate upstream in un modulo condiviso oppure, se sono specifiche di un server, incluse in un modulo module-$(server-name).
   - Oppure posso utilizzarlo per distribuire le chiavi, file, configurazioni comuni ai server di uno stesso sito
  - Es: module-ortiche

 - **[<font color="yellow">conf</font>, <font color="green">host-wide</font>, <font color="green">gcrypt</font>]** **hostconf-$(server-name)**
  - Contiene principalmente (solo?) due file:
   - host.yaml: file utilizzato da hiera per determinare le proprieta' e le configurazioni specifiche del server
   - .mrconfig: configurazione di myrepos per includere i moduli (repository git) specifici per il server

 - **[<font color="cyan">logic</font>, <font color="green">host-wide</font>, <font color="green">gcrypt</font>]** **module-$(server-name)** 
  - Modulo che contiene la logica specifica per un unico server
  - Includo qui i file sensibili per un unico server?


### Installare e configurare un nuovo server

#### Software necessario
 gem install deep_merge


#### Creare un nuovo $(site-name)
##### Configurazione siteconf-$(sitename)
  1. Creare il repository git per la configurazione del site 
	`git init siteconf-$(sitename)`
  2. (Opzionale) Creare il repositori bare remoto
  3. Configurare il nuovo repository per usare un remote crittato con gcrypt: <pre>cd siteconf-$(sitename)/
git remote add $(gcrypt_remote) gcrypt::<repo_location>/siteconf-$(site-name).git
git config remote.$(gcrypt_remote).gcrypt-participants "$(sysadm1-key-fingerprint) $(sysadm2-key-fingerprint) $(server1-key-fingerprint) $(server2-key-fingerprint)"
git config remote.$(gcrypt_remote).gcrypt-publish-participants true
touch README
git add .
git commit -m "Initial gcrypt commit"
git push --set-upstream $(gcrypt_remote) master</pre>

**E' importante importare le chiavi pubbliche di TUTTI i sysadmin e TUTTI i servers elencati in `gcrypt-participants` prima di continuare oltre**


##### Configurazione module-$(sitename)
  0. Creare un file .mrconfig nel repository siteconf-$(sitename) contenente i dettagli del repository di module-$(sitename)
<pre>[DEFAULT]
lib = SITE="$(sitename)" && \
	HOSTFQDN="$(hostname --fqdn)" && HOSTNAME="$(hostname)" && \
        REPO_ROOT="git@gitlab.com:organization/"

[/etc/puppet/modules/$(modulename)]
checkout = git clone gcrypt::${REPO_ROOT}/module-${SITE}.git $(modulename)]
order=3</pre>
  2. Committare/pushare/aggiornare siteconf-$(modulename)
  1. Creare il repository git per la configurazione del site 
	`git init module-$(sitename)`
  2. (Opzionale) Creare il repositori bare remoto
  3. Configurare il nuovo repository per usare un remote crittato con gcrypt: <pre>cd module-$(sitename)/
git remote add $(gcrypt_remote) gcrypt::<repo_location>/module-$(site-name).git
git config remote.$(gcrypt_remote).gcrypt-participants "$(sysadm1-key-fingerprint) $(sysadm2-key-fingerprint) $(server1-key-fingerprint) $(server2-key-fingerprint)"
git config remote.$(gcrypt_remote).gcrypt-publish-participants true
touch README
git add .
git commit -m "Initial gcrypt commit"
git push --set-upstream $(gcrypt_remote) master</pre>

**E' importante importare le chiavi pubbliche di TUTTI i sysadmin e TUTTI i servers elencati in `gcrypt-participants` prima di continuare oltre**

#### Configurazione di un server base, senza moduli specifici per site o host
  1. Installare un nuovo server Debian Wheezy
  2. Abilitare i backports (necessari per `git-remote-gcrypt`) 
     `echo "deb http://http.debian.net/debian wheezy-backports main" >> /etc/apt/sources.list`
  3. Aggiungere i repository dei PuppetLabs (per le versioni aggiornate di puppet)
     `wget https://apt.puppetlabs.com/puppetlabs-release-wheezy.deb && dpkg -i puppetlabs-release-wheezy.deb
  4. Creare il file `/etc/apt/preferences.d/00-puppet.pref` con le seguente configurazione:
     `Package: puppet puppet-common
      Pin: version 3.7*
      Pin-Priority: 999

      Package: facter
      Pin: version 2.3*
      Pin-Priority: 999`
  5. Aggiornare la lista dei pacchetti disponibili
     `apt-get update`
  6. Da root `apt-get install puppet git git-remote-gcrypt myrepos`
  7. Eliminare i file esistenti per puppet `rm -rf /etc/puppet`
  8. Generare una nuova coppia di chiavi gpg `gpg --gen-key`
  9. Configurare sul repository git l'account e i permessi per il nuovo server. Questo passo potrebbe non essere indispensabile, dipende dal repository configurato.
  10. (Opzionale) Configurare l'agent gpg
  10. Copiare i file `.mrconfig` e `.mrtrust` forniti sopra in `/root` e configurare le variabili `SITE` e `REPO_ROOT` in `.mrconfig`.
  11. Eseguire l'update di tutti i moduli `mr -d /etc/ update`
  12. Lanciare l'esecuzione di puppet  `puppet apply -v /etc/puppet/manifests/site.pp`


#### Appunti 
 - **module naming convention**
   Dalla [documentazione di puppet](https://docs.puppetlabs.com/puppet/latest/reference/modules_fundamentals.html#manifests): *`init.pp` is special and always contains a class with the same name as the module. You may not have a class named init.*