From 1a9824df2fea14fb4961e34fe15cf01013d88764 Mon Sep 17 00:00:00 2001 From: Frank Brehm Date: Thu, 16 Sep 2021 18:44:35 +0200 Subject: [PATCH] Update README.md --- README.md | 144 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 97 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 87eaae0..30d85c9 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ **Copyright:** Pixelpark GmbH, Berlin, 2021 -## 1. Voraussetzungen und Installation +## Voraussetzungen und Installation Das verwendete Python-Script verwendet **Terraform** und **Python3** für die Provisionierung. @@ -25,7 +25,7 @@ private Terraformdatei nicht angelegt, _aber_ bei jedem Aufruf von `create-terra `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 @@ -46,23 +46,23 @@ Dafür bieten sich insbesondere folgende zwei Hosts an: * `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 @@ -74,9 +74,9 @@ abwärtskompatibel sind, sollte Terraform immer auf dem aktuellen Stand gehalten 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. @@ -191,7 +191,7 @@ frank.brehm@ns1-local ~/Work/terraform (test) > ``` -#### 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: @@ -221,7 +221,7 @@ frank.brehm@ns1-local ~/Work/terraform (test) > 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: @@ -236,7 +236,7 @@ frank@bruni ~/Develop/PP/terraform (master) > . venv/bin/activate 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, @@ -310,7 +310,7 @@ auskommentierten Einträge in der _create-terraform.ini.default_ sind). Aber es * 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 @@ -324,7 +324,7 @@ schon einmal terraform erfolgreich ausgeführt wurde. 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. @@ -398,19 +398,19 @@ für Text-Dateien eingehalten wird, das heißt, die letzte Zeile der Datei schli 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. @@ -418,7 +418,7 @@ 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 @@ -430,11 +430,11 @@ nicht verwendet, aber dient zum einfacheren Auffinden von Fehlern in der Konfigu 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`. @@ -442,7 +442,7 @@ 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. @@ -450,7 +450,7 @@ 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: @@ -458,7 +458,7 @@ 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. @@ -473,7 +473,7 @@ nicht als Terraform-Resourcen behandelt, das heißt, wenn nach dem Wegwerfen von 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. @@ -483,7 +483,7 @@ obigem Schema ein und konfiguriert diese anschließend manuell in VSPhere. 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 @@ -494,7 +494,7 @@ von 256 MiB sein muss. SI-konforme Einheiten werden hier nicht beachtet, das hei 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 @@ -505,7 +505,7 @@ Wert auf '**0**'. In diesem Fall kann man aber auch keine Tasten für BIOS usw. 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*. @@ -516,7 +516,7 @@ wenn man SSD-Storage benötigt. 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 @@ -537,7 +537,7 @@ Vorgesehen ist, vorher eine ähnliche Suche über alle Datenstore-Cluster zu mac 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**. @@ -555,7 +555,7 @@ Partitionen haben, kann man anschließend nach der Provisionierung in dem ungenu 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. @@ -584,7 +584,7 @@ Problem, wenn die Daten-Disk für ein Dateisystem vorgesehen ist, das bereits in 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. @@ -601,14 +601,14 @@ Das sieht dann ungefähr so aus: 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 @@ -616,7 +616,7 @@ auf dem Host verwendet wird. Vorgabewert: _Customer project_ -##### template +#### template Das ist eine **obligatorische Angabe**, die besagt, welche Vorlage von VSPhere geklont werden soll, um die VM zu provisionieren. @@ -635,7 +635,7 @@ Falls diese Vorlage (unwahrscheinlicherweise, aber man weiß ja nie) kaputt und 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. @@ -649,7 +649,7 @@ Mit allen Angabes sieht das ungefähr so aus: 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 @@ -657,7 +657,7 @@ der Mailadresse des zuständigen Kontaktes beim Login auf dem Host verwendet wir 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 @@ -665,7 +665,7 @@ gefunden werden. 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 @@ -675,7 +675,7 @@ Dieses ist eine **obligatorische** Angabe. 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 @@ -683,10 +683,10 @@ für den Host gefunden werden. 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. @@ -699,9 +699,9 @@ im Hiera _vor_ der Provisionierung anzulegen. 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: @@ -714,8 +714,58 @@ Praktisch verbirgt sich dahinter, dass beim Durchsuchen des Hiera auch gleichnam 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 -- 2.39.5