--- /dev/null
+# Automatisierte Provisionierung mittels Terraform
+
+**Autor:** Frank Brehm <frank.brehm@pixelpark.com>
+**Copyright:** Pixelpark GmbH, Berlin, 2019
+
+## 1. Voraussetzungen und Installation
+
+Das verwendete Python-Script verwendet **Terraform** und **Python3** für die Provisionierung.
+
+Weiterhin empfehle ich auch grundsätzlich die Verwendung von _Python virtualenv_ zur Ausführung,
+da damit relativ einfach zusätzlich weiter Python-Module installiert und isoliert von anderen
+Benutzern und Prozessen ausgeführt werden können.
+
+Die Mindest-Version von Python 3 ist **3.5**.
+
+**Hinweis:** Man sollte sich überlegen, *wo* man dieses Provisionierungs-Script laufen lassen
+möchte, da bei der Ausführung pro Projekt eine Datei mit zum Teil persölichen Secrets angelegt
+wird. Diese wird zwar nur für den aktuellen Nutzer lesbar angelegt und auch für Git maskiert,
+aber wenn andere Nutzer mit Root-Rechten auf der Kiste angemeldet sind, können sie diese trotzdem lesen.
+Das Gleiche trifft für die allgemeine Konfigurationsdatei zu, wenn man diese anlegt (siehe Punkt 1.4.).
+
+### 1.1. Betriebssystem-Pakete
+
+#### 1.1.1. Bei Debian-basierten Distributionen:
+
+also zum Beispiel _Debian_, _Ubuntu_ usw.
+
+* python3
+* python3-virtualenv
+
+#### 1.1.2. Bei RPM-basierten Distributionen:
+
+also CentOS, Fedora, RHEL, OEL, SuSE usw.
+
+* python36
+* python-virtualenv (ist zwar für Python 2.7, dient aber als Wrapper für virtualenv mit Python 3.6)
+
+### 1.2. Installation Terraform
+
+Leider gibt es keine Terraform-Pakete. Man ist daher darauf angewiesen,
+sich das Terrform-ZIP-Paket von folgender URL zu holen: https://www.terraform.io/downloads.html
+Dort das ZIP-File für Linux 64 Bit downloaden, entpacken, und die herauspurzelnde Datei
+ausführbar machen und irgendwo in den Pfad legen.
+
+### 1.3. Installion einer virtuellen Umgebung
+
+Nach dem Auschecken dieses Repos sollte eine virtuelle Umgebung für Python3 eingerichtet werden.
+
+Um die Arbeit zu vereinfachen, habe ich im Wurzelverzeichnis das Skript **update-env.sh**
+hingelegt, das alle notwendigen Schritte unternimmt, um die Arbeitsumgebung einzurichten
+bzw. zu aktualisieren. Das sind folgende Dinge:
+
+* Einrichten des Virtual Environments in `venv`, falls es noch nicht geschehen sein sollte,
+* Installieren und aktualisieren aller benötigten PIP-Module,
+* Aktualisieren des Git-Submodules unter **python_fb_tools**,
+* Kompilieren der i18n-Dateien (für die Herren, die des Englischen nicht ganz so mächtig sind).
+
+Das sieht beim ersten Mal so aus:
+```
+frank.brehm@ns1-local ~/Develop/provisioning (test) > ./update-env.sh
+Preparing virtual environment ...
+
+Found python3.6.
+
+Running virtualenv with interpreter /usr/bin/python3.6
+Using base prefix '/usr'
+New python executable in /home/frank.brehm/Develop/provisioning/venv/bin/python3.6
+Also creating executable in /home/frank.brehm/Develop/provisioning/venv/bin/python
+Installing setuptools, pip, wheel...done.
+---------------------------------------------------
+Installing and/or upgrading necessary modules ...
+
+Cache entry deserialization failed, entry ignored
+Collecting pip (from -r requirements.txt (line 1))
+ Using cached https://files.pythonhosted.org/packages/46/dc/7fd5df840efb3e56c8b4f768793a237ec4ee59891959d6a215d63f727023/pip-19.0.1-py2.py3-none-any.whl
+
+.
+.
+.
+
+Installing collected packages: pip, setuptools, pycparser, cffi, six, asn1crypto, cryptography, PyYAML, MarkupSafe, jinja2, pynacl, pyasn1, bcrypt, paramiko, ansible, pytz, babel, chardet, idna, certifi, urllib3, requests, pyvmomi, dnspython, pyflakes, pycodestyle, mccabe, entrypoints, flake8, websocket-client, docker-pycreds, docker-py, pathlib
+ Found existing installation: pip 9.0.1
+ Uninstalling pip-9.0.1:
+ Successfully uninstalled pip-9.0.1
+ Found existing installation: setuptools 28.8.0
+ Uninstalling setuptools-28.8.0:
+ Successfully uninstalled setuptools-28.8.0
+Successfully installed MarkupSafe-1.1.0 PyYAML-3.13 ansible-2.7.6 asn1crypto-0.24.0 babel-2.6.0 bcrypt-3.1.6 certifi-2018.11.29 cffi-1.11.5 chardet-3.0.4 cryptography-2.5 dnspython-1.16.0 docker-py-1.10.6 docker-pycreds-0.4.0 entrypoints-0.3 flake8-3.7.3 idna-2.8 jinja2-2.10 mccabe-0.6.1 paramiko-2.4.2 pathlib-1.0.1 pip-19.0.1 pyasn1-0.4.5 pycodestyle-2.5.0 pycparser-2.19 pyflakes-2.1.0 pynacl-1.3.0 pytz-2018.9 pyvmomi-6.7.1.2018.12 requests-2.21.0 setuptools-40.7.1 six-1.12.0 urllib3-1.24.1 websocket-client-0.54.0
+
+---------------------------------------------------
+Installed modules:
+
+Package Version
+---------------- -------------
+ansible 2.7.6
+asn1crypto 0.24.0
+Babel 2.6.0
+.
+.
+.
+wheel 0.29.0
+
+---------------------------------------------------
+Updating Git submodule python_fb_tools ...
+git init ...
+
+
+--------------
+git update ...
+
+
+--------------
+Updating i18n files in /home/frank.brehm/Develop/provisioning ...
+
+340 of 340 messages (100%) translated in locale/de_DE/LC_MESSAGES/pp_provisioning.po
+compiling catalog locale/de_DE/LC_MESSAGES/pp_provisioning.po to locale/de_DE/LC_MESSAGES/pp_provisioning.mo
+12 of 340 messages (3%) translated in locale/en_US/LC_MESSAGES/pp_provisioning.po
+compiling catalog locale/en_US/LC_MESSAGES/pp_provisioning.po to locale/en_US/LC_MESSAGES/pp_provisioning.mo
+
+--------------
+Updating i18n files in python_fb_tools ...
+
+253 of 253 messages (100%) translated in locale/de_DE/LC_MESSAGES/fb_tools.po
+compiling catalog locale/de_DE/LC_MESSAGES/fb_tools.po to locale/de_DE/LC_MESSAGES/fb_tools.mo
+4 of 253 messages (1%) translated in locale/en_US/LC_MESSAGES/fb_tools.po
+compiling catalog locale/en_US/LC_MESSAGES/fb_tools.po to locale/en_US/LC_MESSAGES/fb_tools.mo
+
+-------
+Fertig.
+
+frank.brehm@ns1-local ~/Develop/provisioning (test) >
+
+```
+
+Der nächste Schrit ist grundsätzlich vor jeder Arbeitssitzung zu machen, um die virtuelle
+Umgebung zu aktivieren:
+
+```
+frank.brehm@ns1-local ~/Develop/provisioning (test) > . venv/bin/activate
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) >
+```
+
+Mindestens einmal nach der Einrichtung der virtuellen Umgebung, aber auch später regelmäßig sollte
+danach die Umgebung mittels **update-env.sh** aktualisiert werden:
+
+```
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) > ./update-env.sh
+Preparing virtual environment ...
+
+---------------------------------------------------
+Installing and/or upgrading necessary modules ...
+
+Requirement already up-to-date: pip in ./venv/lib/python3.6/site-packages (from -r requirements.txt (line 1)) (19.0.1)
+.
+.
+.
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) >
+```
+
+### 1.4. Grundlegende Installation
+
+Nach dem Clonen befindet sich im Arbeitzsverzeichnis unter _etc_ die Datei _'create-terraform.ini.default'_, welches
+nicht die allgemeine Konfigurationsdatei ist, sondern nur ein Muster dafür. Zwar ist das Anlegen der allgemeinen
+Konfigurationsdatei _'create-terraform.ini'_ unter _etc_ nicht unbedingt erforderlich, da für fast alle Konfigurations-Parameter
+sinnvolle Vorgabewerte definiert wurden, aber es gibt exakt drei Ausnahmen dazu, nämlich:
+
+* das Passwort für den VSphere Nutzer (welcher übrigens per Default auf _'Administrator@vsphere.local'_ gesetzt ist),
+* den Key für die globale PowerDNS-API und
+* das root-Passwort für die installierten Kisten (wird derzeit nicht verwendet, ist aber für später vorgesehen).
+
+Wenn man die nachfolgend beschriebene Einrichung der _'etc/create-terraform.ini'_ nicht macht, wird man
+bei jeder Ausführung des Scripts nach dem Passwort des VSphere-Nutzers _'Administrator@vsphere.local'_
+und nach dem API-Key für PowerDNS gefragt. Da es _dringend empfohlen_ ist, sich mit einem personalisierten
+Account bei VSphere anzumelden (und die dauernden Fragen nach Passwort und Key natürlich nerven), hier
+kurz, wie man die _'etc/create-terraform.ini'_ einrichtet:
+
+```
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) > cp -vi etc/create-terraform.ini.default etc/create-terraform.ini
+„etc/create-terraform.ini.default“ -> „etc/create-terraform.ini“
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) >
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) > chmod 0600 etc/create-terraform.ini
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) >
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) > ls -lA etc/
+insgesamt 8
+-rw------- 1 frank.brehm pixel 1475 22. Jun 10:36 create-terraform.ini
+-rw-r--r-- 1 frank.brehm pixel 1354 21. Jun 17:51 create-terraform.ini.default
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) >
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) > vi etc/create-terraform.ini
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) >
+(venv) frank.brehm@ns1-local ~/Develop/provisioning (test) > cat etc/create-terraform.ini | egrep -v '^[ ]*(;|#|$)'
+[global]
+puppet_master = puppetmaster02.pixelpark.com
+[vSphere]
+user = frank.brehm
+password = <mein_oberschickes_Passwort>
+[PowerDNS]
+api_key = <API-Key>
+[Terraform]
+
+*Hinweis*: Den API-Key für die globale PowerDNS-Instanz findet man hier: https://intra.pixelpark.com/confluence/display/its/DNS+Server+-+Betriebsdokumentation+-+Maschinen+und+Software#DNSServer-Betriebsdokumentation-MaschinenundSoftware-Zugangsdaten - Service _'PowerDNS-API global'_.
+
+Die weiteren Angaben sind in der Datei _'etc/create-terraform.ini.default'_ beschrieben und brauchen nicht
+unbedingt überschrieben werden, ausser, man will zum Beispiel den Test-VSphere-Cluster nehmen.
+
+## 2. Arbeit mit Provisionierungs-Projekten
+
+Jedes Provisionierungs-Projekt wird in einer einzelnen Projekt-Datei beschrieben, welche im YAML-Format vorliegen muss
+(später vorgesehen: JSON bzw. Hjson). Bei der Ausführung der Projekt-Datei wird ein Verzeichnis unterhalb
+von _'terraform'_ neu angelegt, welches so heißt wie die Projekt-Datei ohne ihre Endung. Wenn es dieses Verzeichnis
+schon geben sollte und es ist leer, wird es natürlich verwendet. Wenn es nicht leer ist, werden normalerweise alle
+Dateien und Verzeichnisse darin mit Beginn der Ausführung gelöscht, außer es existieren darin das Verzeicnis _'.terraform'_
+und die Datei _'terraform.tfstate'_, was darauf hindeutet, dass darin schon einmal terraform erfolgreich ausgeführt wurde.
+Im letzteren Fall bricht die Ausführung mit einer Fehlermeldung ab.
+
+
+```
+
+## 3. FeatureRequests
+### 3.1 change vSphere Host per need in terraform yaml (live <--> test)
projects / pixelpark / create-terraform.git / commitdiff