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="ortiche" && \
  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?


#### Workflow
 - Aggiungere uno sviluppatore a opuppet su Gogs
  1. Creare l'utente <developer> dalla pagina di [registrazione](http://git.lattuga.net/user/sign_up). L'indirizzo email deve essere valido per procedere all'attivazione dell'utente;
  2. Aggiungere l'utente <developer> al team "Developer" dell'organizzazione opuppet. 

 - Aggiungere un server a opuppet su Gogs
  1. Creare un indirizzo email da associare all'utente. Per esempio, su indivia, `php vmail.php -na <hostname>@ortiche.net gestione@posta.indivia.net` ;
  2. Se non esiste gia', generare sul server <hostname> una nuova coppia di chiavi ssh per l'utente root (`ssh-keygen -b 4096 -t rsa`). Se i filename delle chiavi non vengono modificati allora e' sufficiente questo passo, altrimenti sara' necessario aggiungere le entry corrispondenti in `/root/.ssh/config` ;
  3. Creare l'utente <hostname> dalla pagina di [registrazione](http://git.lattuga.net/user/sign_up). L'indirizzo email deve essere valido per procedere all'attivazione dell'utente;
  4. Associare la chiave ssh generata, all'utente <hostname> su gogs;
  5. Aggiungere l'utente <hostname> al team "Deploy" dell'organizzazione opuppet. 
  6. Testare eseguendo `git clone --recursive gogs@lattuga.net:opuppet/puppet-deploy.git` sul server <hostname>

 - Installare un nuovo server Debian wheezy e configurare Git/puppet 
  1. `wget https://apt.puppetlabs.com/puppetlabs-release-wheezy.deb && dpkg -i puppetlabs-release-wheezy.deb && apt-get update`
  2. 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`
  3. Aggiungere la linea `echo "deb http://http.debian.net/debian wheezy-backports main" >> /etc/apt/sources.list && apt-get update`
  1. Da root `apt-get install puppet git`
  2. Eliminare i file esistenti per puppet: `rm -rf /etc/puppet`
  3. Aggiungere l'utente specifico del server sulla piattaforma Gogs (vedi piu' in alto) 
  4. Clonare il repository puppet-deploy al punto della configurazione di puppet: `cd /etc && git clone --recursive gogs@lattuga.net:opuppet/puppet-deploy.git`

 - Aggiungere la configurazione di un nuovo server in puppet-deploy
 - Aggiungere un submodule a puppet-deploy


#### 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.*