**Copyright:** Pixelpark GmbH, Berlin, 2021
-## 1. Voraussetzungen und Installation
+## Voraussetzungen und Installation
Das verwendete Python-Script verwendet **Terraform** und **Python3** für die Provisionierung.
`terraform` selbst wird dann nach den zwei oder drei Angaben, nämlich dem PowerDNS-API-Key,
dem VSphere-Nutzernamen und dessen Passwort gefragt.
-### 1.1. Auschecken des Repositories
+### Auschecken des Repositories
Es werden drei Git-Repositories aus dem Pixelpark-Gitlab verwendet. Für die Anwender dieses
Provisionierungstools ist erst einmal nur das Arbeits-Repository wichtig, welches man sich
* `host.pixelpark.com`
* `terraform.pixelpark.com`
-### 1.2. Betriebssystem-Pakete
+### Betriebssystem-Pakete
-#### 1.2.1. Bei Debian-basierten Distributionen:
+#### Bei Debian-basierten Distributionen:
also zum Beispiel _Debian_, _Ubuntu_ usw.
* python3
* python3-virtualenv
-#### 1.2.2. Bei RPM-basierten Distributionen:
+#### Bei RPM-basierten Distributionen:
also CentOS, Fedora, RHEL, OEL, SuSE usw.
* python36 bzw. python38
* python-virtualenv (ist zwar für Python 2.7, dient aber als Wrapper für virtualenv mit Python 3.6)
-### 1.3. Installation Terraform
+### Installation Terraform
Mittlerweile gibt es rpms für Terraform.
Infos sind hier zu finden: https://www.terraform.io/docs/cli/install/yum.html
Auf den Hosts `host.pixelpark.com` und `terraform.pixelpark.com` ist terraform mit der
Version *1.0.6* installiert.
-### 1.4. Installion einer virtuellen Umgebung
+### Installion einer virtuellen Umgebung
-#### 1.4.1. Initiale Installation der virtuellen Umgebung
+#### Initiale Installation der virtuellen Umgebung
Nach dem Auschecken dieses Repos muss eine virtuelle Umgebung für Python3 eingerichtet werden.
```
-#### 1.4.2. Update der virtuellen Umgebung
+#### Update der virtuellen Umgebung
Der nächste Schritt ist grundsätzlich vor jeder Arbeitssitzung zu machen, um die virtuelle
Umgebung zu aktivieren:
Wenn es Probleme beim Update gibt, die aus einem zu alten Virtual Environment stammen,
einfach das Verzeichnis `venv` komplett löschen und das Update-Script neu ausführen.
-#### 1.4.3. Aktivieren virtuellen Umgebung
+#### Aktivieren virtuellen Umgebung
Vor jeder Arbeit ist die virtualle Umgebung zu aktivieren:
Wie oben ersichtlich, befindet sich der Befehl **create-terraform** nach der Aktivierung im
Pfad für ausführbare Dateien.
-### 1.5. Grundlegende Konfiguration
+### Grundlegende Konfiguration
Nach dem Clonen und dem Update der Virtuellen Umgebung befindet sich im Arbeitsverzeichnis unter _venv/etc_
die Datei _'create-terraform.ini.default'_, welches nicht die allgemeine Konfigurationsdatei ist,
* Den API-Key für die globale PowerDNS-Instanz findet man hier: https://intra.powerofone.de/confluence/x/gIjrAQ
im Abschnitt '5. Zugangsdaten' bzw. im Team Password Manager unter https://passwords.powerofone.de/index.php/pwd/view/81.
-## 2. Arbeit mit Provisionierungs-Projekten
+## Arbeit mit Provisionierungs-Projekten
Jedes Provisionierungs-Projekt wird in einer einzelnen Projekt-Datei beschrieben, welche im YAML-Format vorliegen muss.
Diese YAML-Dateien können hierarchisch in verschachtelten Unterverzeichnissen organisiert werden. Bei der Ausführung der
Im letzteren Fall bricht die Ausführung mit einer Fehlermeldung ab.
-### 2.1. Aufbau einer Provisionierungs-Projekt-Datei
+## Aufbau einer Provisionierungs-Projekt-Datei
Grundsätzlich ist die Projekt-Datei so angelegt, dass sich Konfigurations-Angaben möglichst nicht wiederholen.
Direkt im obersten Verzeichnis befindet sich die Datei **`example-dont-use.yaml`**, in der exemplarisch alle Möglichkeiten der Konfioguration dargestellt werden.
-#### 2.1.1. Schlüssel auf oberster Ebene
+### Schlüssel auf oberster Ebene
-##### simulate
+#### simulate
Boolscher Wert. Wenn wahr, ist das identisch damit, als ob *'create-terraform'* immer mit dem
Schalter *'--simulate'* aufgerufen wird. Es wird also nur so getan, als ob, und die Terraform-Projekt-Verzeichnisse
und -Dateien werden nicht angelegt.
-##### defaults
+#### defaults
Wie bereits erwähnt, werden hier die globalen Vorgabewerte für alle VMs definiert.
-##### vms
+#### vms
Liste der nicht gruppierten VMs. Das heißt, sie beziehen ihre Vorgaben ausschließlich aus den
Vorgabewerten der obersten Ebene.
In dieser Liste werden alle VMs, die provisioniert werden sollen, als Hashes aufgelistet, wobei minimal
der Name und eine IPv4-Adresse pro VM definiert werden müssen.
-##### groups
+#### groups
Liste von Gruppen von VMs, die wiederum gemeinsame, von den globalen abweichende Vorgabewerte
haben. Jede Gruppe ist ein Hash mit drei notwendigen Schlüsseln: `name`, `defaults` und `vms`, sowie
Die Schlüssel **defaults**, **vms** und **groups** haben exakt die selbe Bedeutung wie auf der obersten
Ebene. In den **defaults** in einer Gruppe können Vorgabewerte der nächsthöheren Ebene überschrieben werde.
-#### 2.1.2. Konfigurations-Parameter für eine VM
+### Konfigurations-Parameter für eine VM
Die nachfolgenden Parameter können pro defaults-Abschnitt und pro VM vergeben werden.
-##### vsphere
+#### vsphere
Name der der VSPhere-Umgebung aus der Konfiguration dieser Anwendung, also im Falle von Pixelpark
entweder `test` oder `live`.
**Achtung**: Durch die Limitierung von Terraform darf es in einem Terraform-Projekt nur ein VSphere geben,
damit macht es Sinn, diesen Parameter nur ein einziges Mal anzugeben, nämlich im obersten Template.
-##### cluster
+#### cluster
Hier wird das VSphere-Rechencluster festgelegt. Welches Cluster man festlegt, hängt davon ab,
in Welchem **vsphere** die VMs provisioniert werden sollen.
Im **live** VSPhere stehen folgende Cluster zur Verfügung:
* vmcc-l015-01 (Alle ESX-Hosts mit Intel-CPU)
-* vmcc-l015-02 (Alle ESX-Hosts mit amd-cpu)
+* vmcc-l015-02 (Alle ESX-Hosts mit AMD-CPU)
Im **test** VSPhere stehen folgende Cluster zur Verfügung:
* test-vmcc-l105-01
* vmcc-l65-01
-##### vm\_folder
+#### vm\_folder
Der Name des Ordners innerhalb des Baums der 'VMs und Vorlagen'-Ansicht in VSPhere. Dabei achtet
VSPhere auf Groß- und Kleinschreibung, also sind `Pixelpark` und `pixelpark` zwei unterschiedliche Ordner.
Ordner leer ist, wird er von Terraform nicht weggeräumt.
Das obliegt dann dem Admin, der die VMs weggeräumt hat, manuell.
-##### num\_cpus
+#### num\_cpus
Die Anzahl der CPUs der VM als Integer-Zahl. Der Einfachheit halber ist damit grundsätzlich die
Anzahl der CPUs mit jeweils einem Core gemeint.
Bislang hat sich mir derlei Notwendigkeit aber noch nicht dargestellt.
-##### memory
+#### memory
Die Größe des Haupspeichers der VM. Wenn keine Einheit angegeben wurde, werden MiByte (also 2^20 Bytes)
angenommen. Man kann aber auch eine Float- oder Integerzahl zusammen mit einer Maßeinheit wie GiB oder TiB
1 GB identisch mit 1 GiB ist, also 2^30 Bytes, und nicht 10^9 entspricht. Im Normalfall verwendet man aber
ein Vielfaches von 1 GiB als Hauptspeicher.
-##### boot\_delay
+#### boot\_delay
Die Verweildauer im POST nach dem Einschalten als Float-Zahl in Sekunden. In diesem Zeitraum kann
in der VM-Konsole in VSPhere zum Beispiel das Boot-Menü aufgerufen werden, um die VM beispiesweise vom Netz oder
Der Standardwert, wenn er nicht gesetzt wird, beträgt 5 Sekunden.
-##### datastore\_cluster
+#### datastore\_cluster
Welcher Datenstore-Cluster soll für alle Disks der VM verwendet werden? Ene Angabe an dieser
Stelle hat Vorrang vor *datastore_type*.
Der Standard-Wert für diesen Eintrag ist **'~'** - also nicht angegeben.
-##### datastore\_type
+#### datastore\_type
Auf welchem Typ Storage sollen die Disks der VM angelegt werden, wenn kein Datenstore-Cluster
angegeben wurde. Mögliche Angaben sind **ssd**, **sas** und **sata**, wobei letzteres die Vorgabe ist, wenn hier
wurde, und erst danach, wenn kein entsprechender Datenstore-Cluster gefunden wurde, die Suche auf
Datastores auszudehnen.
-##### root\_disk
+#### root\_disk
In der aktuellen Version des Tools ist der Wert ein Hash mit nur einem Schlüssel, nämlich **size**.
eine weitere Partition anlegen, die man zum Beispiel zum Vergrößern von Volume-Gruppen
nutzen könnte.
-##### dada\_disk
+#### data\_disk
In der aktuellen Version des Tools ist der Wert ein Hash mit nur einem Schlüssel, nämlich **size**,
oder '**~**' - was bedeutet, dass keine Daten-Disk angelegt werden soll.
existiert und in Verwendung ist. Da kommnt man dann meistens nicht darum herum, die Daten-Disk
als LVM PV zu deklarieren und damit die root-VolumeGroup zu vergrößern.
-##### data\_disks
+#### data\_disks
Wie der Name schon vermuten läßt, kann man hier mehrere Daten-Disks mit einem Mal bereits bei der
Provisionierung an die VM anhängen.
Die Bemerkungen zur Größe, zum SCSI-Controller und zur Einbindung, die ich bereits bei _data_disk_
gemacht habe, treffen natürlich auch hier zu.
-##### customer
+#### customer
Das ist ein einfacher Free-Form-String (Mindestlänge 1 Zeichen), der lediglich für die
Generierung der `/etc/motd` zum Anzeigen des Kunden beim Login auf dem Host verwendet wird.
Vorgabewert: _Pixelpark_
-##### purpose
+#### purpose
Genau wie _customer_ ein einfacher Free-Form-String (Mindestlänge 1 Zeichen), der ebenfalls
für die Generierung der `/etc/motd` zum Anzeigen des Zwecks des Hosts beim Login
Vorgabewert: _Customer project_
-##### template
+#### template
Das ist eine **obligatorische Angabe**, die besagt, welche Vorlage von VSPhere geklont werden
soll, um die VM zu provisionieren.
verwendungsfähig ist, kann man sich auch in VSPhere unter _'VMs und Vorlagen'_ im Ordner
**templates** eine der rotierten Vorlagen aussuchen.
-##### puppet
+#### puppet
Das ist ein Hash, dessen Key-Value-Paare zur Einrichtung des Puppet-Agents dienen.
role: dpx-postgresql::cluster_node
tier: development
-###### puppet/contact
+##### puppet/contact
Das ist von den Angaben die unwichtigste. Es ist ein einfacher Free-Form-String
(Mindestlänge 1 Zeichen), der lediglich für die Generierung der `/etc/motd` zum Anzeigen
Vorgabewert: _8x5@pixelpark.com_
-###### puppet/customer
+##### puppet/customer
Das zeigt den Kundennamen in Puppet-Hiera an, also den Verzeichnisnamen in Hiera unterhalb
von `customers`, unterhalb dessen die zuständigen YAML-Dateien für den Host
Dieses ist eine **obligatorische** Angabe.
-###### puppet/environment
+##### puppet/environment
Das beschreibt das **r10k Environment**, das für diese VM zuständig sein soll.
Damit werden also alle Puppet-Module und deren Versionen benannt, die für die Konfiguration
Vorgabewert: _development_
-###### puppet/project
+##### puppet/project
Dieser **optionale** Wert beschreibt das Kundenprojekt in Hiera, also ein Unterverzeichnis
in Hiera unterhalb des Kundenverzeinisses, unterhalb dessen die zuständigen YAML-Dateien
Für das obige Beispiel wäre das also in Hiera das Verzeichnis `customer/pixelpark/postgresql-dev`.
-Wenn wes weggelassen (die Vorgabe) oder ausdrücklich auf '**~**' gesetzt wird, dann kann nur
-diremt im Kundenverzeichnis im Hiera nach den zuständigen YAML-Dateien gesucht werden.
+Wenn es weggelassen (die Vorgabe) oder ausdrücklich auf '**~**' gesetzt wird, dann kann nur
+direkt im Kundenverzeichnis im Hiera nach den zuständigen YAML-Dateien gesucht werden.
-###### puppet/role
+##### puppet/role
Das beschreibt die eindeutige Rolle aus dem Puppet-Modul **pixelpark-infra**, die dem Host
zugewiesen wird.
Vorgabewert: _default_
-###### puppet/tier
+##### puppet/tier
-Die logische Einordung der VM in den Entwicklungs-Stand des Kunden. Das stimmt nicht
+Die logische Einordung der VM in den Entwicklungsstand des Kunden. Das stimmt **nicht**
zwangsweise mit dem Puppet-Environment überein.
Mögliche Werte:
YAML-Dateien unterhalb des Kunden-Projekt-Ordners und des Kunden-Ordners mit
herangezogen werden.
-## 3. FeatureRequests
+Vorgabewert: _development_
+
+#### nameservers
+
+Das ist eine Liste der Nameserver die in die `/etc/resolv.conf` eingetragen werden sollen.
+
+Diese Werte werden nicht nur bei der Provisionierung in die `/etc/resolv.conf` eingetragen,
+sondern auch mit den Networkmanager persistiert.
+
+Natürlich wird mit dem ersten Puppet-Lauf die `/etc/resolv.conf` angepasst, aber unmittelbar nach
+einem Reboot schreibt der Networkmanager die Datei neu, und wenn man Pech hat, sind dabei falsche
+Nameserver eingetragen, so dass der Host bis zum ersten Puppet-Lauf Schwierigkeiten mit der
+DNS-Auflösung hat - mit allen schädlichen Folgen.
+
+Also sollte man hier schon die Nameserver eintragen, die dann auch später durch Puppet
+eingetragen werden. Und diese wiederum hängen vom Netzwerksegment ab, in das die VM hineinkommen
+soll.
+
+Man kann sich dabei an anderen Hosts orientieren, die sich schon in diesem Netzwerksegment
+befinden, und im Zweifel das Netzwerk-Team fragen. Und wenn die nicht mehr weiter wissen,
+dann halt mich, was solls.
+
+Vorgabewerte:
+* _93.188.109.13_
+* _217.66.52.10_
+* _212.91.225.75_
+
+#### searchdomains
+
+Hier wird eine Liste mit DNS-Suchdomänen eingetragen, die bei der Provisionierung in die
+`/etc/resolv.conf` eingetragen werden und beim Networkmanager persisiert werden.
+
+Auch hier sollten die Angaben mit denen in Puppet übereinstimmen.
+
+Vorgabewerte:
+* _pixelpark.net_
+* _pixelpark.com_
+
+#### dns\_options
+
+Hier wird ein String mit den DNS-Optionen eingetragen, die bei der Provisionierung in die
+`/etc/resolv.conf` eingetragen werden und beim Networkmanager persisiert werden.
+
+Auch hier sollten die Angaben mit denen in Puppet übereinstimmen.
+
+Vorgabewert: _timeout:1 attempts:2_
+
+### Konfigurations-Parameter einer VM, die nicht in einer Vorlage definiert werden können
+
+Die nachfolgenden Parameter uausschließlich pro VM vergeben werden.
+
+## FeatureRequests
-### 3.1 change vSphere Host per need in terraform yaml (live <--> test)
+### change vSphere Host per need in terraform yaml (live <--> test)
-### 3.2 support terrform 0.13
projects / pixelpark / create-terraform.git / commitdiff