//Cloudogu EcoSystem Docs

Projekte beim CES-Setup importieren

In diesem Artikel wird beschrieben wie beim CES-Setup Terraform-Projekte importiert werden können.

Voraussetzungen

Folgende Voraussetzungen müssen für einen erfolgreichen Projekt-Import erfüllt sein.

  • Die Dogus, die in den zu importierenden Projekten angegeben sind, müssen installiert werden.
  • Alle Dogus, die installiert werden, müssen nach der Installation im Status healthy sein.
  • Die Terraform-Provider, die in dem zu importierenden Projekten verwendet werden, müssen entweder

    • in der Terraform-Registry vorhanden sein (damit diese von dort aus heruntergeladen werden können)
    • oder manuell installiert werden (Details s.u.)
  • ces-commons muss in einer Version >= 0.5.0 vorliegen

Konfiguration in der setup.json

Für den Import von Projekten muss ein projects-Block in der setup.json auf folgende Art und Weise konfiguriert werden.

"projects":{
  "external_admin_username": "<Benutzername>",
  "external_admin_password": "<Passwort>",
  "import":[
    {
      "username":"<Benutzername>",
      "password":"<Passwort>",
      "type":"Git",
      "location":"https://github.com/cloudogu/demo-content-petclinic",
      "reference":{
        "name":"0.0.1",
        "type":"Tag"
      }
    }
  ],
  "completed":true
},

Eigenschaften

externaladminusername
  • Datentyp: String
  • Optional: Wird bei der Verwendung eines externen LDAP benötigt.
  • Inhalt: Der Benutzername des CES-Admin-Users.
externaladminpassword
  • Datentyp: String
  • Optional: Wird bei der Verwendung eines externen LDAP benötigt.
  • Inhalt: Das Passwort des CES-Admin-Users.
import
  • Datentyp: Project Array
  • Inhalt: Liste aller Projekte, die importiert werden sollen.
Datentyp Project
username
  • Datentyp: string
  • Inhalt: Der Nutzername für die Authentifizierung bei dem Dienst (z. B. GitHub), von dem das zu importierende Projekt abgerufen wird.
  • Wenn der type Archive ist und das Archiv ohne Authentifizierung heruntergeladen werden kann, braucht kein Benutzername angegeben werden.
password
  • Datentyp: string
  • Inhalt: Das Passwort für die Authentifizierung bei dem Dienst (z. B. GitHub), von dem das zu importierende Projekt abgerufen wird.
  • Hinweis: Falls das Projekt aus einem GitHub-Repository ausgecheckt werden soll und in GitHub eine 2-Faktor-Authentifizierung aktiviert ist, funktioniert hier das normale Passwort nicht. In GitHub muss hierzu ein Konsolen-Key generiert und hier anstelle des Passworts verwendet werden. Für Details siehe: https://docs.github.com/en/github/authenticating-to-github/accessing-github-using-two-factor-authentication
  • Wenn der type Archive ist und das Archiv ohne Authentifizierung heruntergeladen werden kann, braucht kein Passwort angegeben werden.
type
  • Datentyp: string
  • Inhalt: Der Typ des Projektes
  • Mögliche Werte:

    • Archive
    • für ein ZIP-Archiv
    • das in location angegebene ZIP-Archiv wird heruntergeladen und entpackt
    • Git
    • für ein Git-Repository
    • das in location angegebene Git-Repository wird geklont
location
  • Datentyp: string
  • Inhalt: Der Ort, an dem das Projekt gespeichert ist, z. B. eine URL zu einem Git-Repository
  • Abhängig vom type des Projektes.

    • Git:
    • Angabe eines Git-Repositories
    • Beispiel: https://github.com/cloudogu/demo-content-petclinic
    • Archive:
    • Angabe eines ZIP-Archivs von einem beliebigen Web-Server
    • Beispiel: https://stagex.cloudogu.com/nexus/repository/Cloudogu-Docs/terraform-projects/demo-content-petclinic.zip
reference
  • Datentyp: Reference
  • Inhalt: Eine Referenz auf einen bestimmten Branch oder einen bestimmten Tag
  • Wird nur ausgewertet, wenn der type des Projekts Git ist
  • Optional
  • Wenn keine Referenz spezifiziert ist, wird der Default-Branch des Repositorys verwendet.
Datentyp Reference
name
  • Datentyp: string
  • Inhalt: Eine Referenz auf einen Branch oder Tag
  • Beispiel: feature/123_myBranch
type
  • Datentyp: string
  • Inhalt: Der Typ der Referenz
  • Mögliche Werte: Tag, Branch

Import über die Benutzeroberfläche

Der Projekte-Import über die Benutzeroberfläche ist aktuell noch nicht implementiert und kann ausschließlich über die setup.json erfolgen.

Ablauf des Projekt-Imports

  • Der Import von Projekten ist der letzte Schritt des Setups und erfolgt nach der Installation und dem Start der Dogus.
  • Damit Projekte erfolgreich importiert werden können, wird bei jedem installierten Dogu gewartet, bis das Dogu den Health-Status erreicht hat. Der Timeout für das Warten beträgt pro Dogu 20 Minuten.
  • Die Projekte werden nacheinander importiert.
  • Im ersten Schritt wird ein Projekt ausgecheckt.

    • Bei Git Projekten erfolgt dies über git clone
    • Bei ZIP-Archiven wird das ZIP-Archiv heruntergeladen und entpackt.
  • Das ausgecheckte Projekt wird mit terraform init und terraform apply importiert.
  • Wenn ein Fehler auftritt, wird das Setup an der Stelle, an der der Fehler aufgetreten ist, abgebrochen.
  • In welche Dogus etwas importiert werden soll und welche Terraform-Provider verwendet werden sollen, wird in dem Terraform-Projekt definiert. Vom CES-Setup erfolgt keine Überprüfung, ob die Dogus und die Terraform-Provider vorhanden sind.

Manuelle Installation eine Terraform-Providers

  • Zur manuellen Installation eines lokalen Terraform-Providers muss dieser im Home-Verzeichnis des Nutzers unter .terraform.d/plugins abgelegt werden.
  • Der Terraform-Provider muss nach folgender Unterstruktur abgelegt werden: <namespace>/tf/<name>/<version>/<distribution>
  • Beispiel: Der terraform-provider-scm muss im lokalen CES in folgendes Verzeichnis kopiert werden: /root/.terraform.d/plugins/cloudogu.com/tf/scm/1.0/linux_amd64
  • Beim lokalen Bauen eines Terraform-Providers wird die passende Unterstruktur bereits erstellt.
  • Für eine detaillierte Anleitung siehe hier.