octo-tools-Konfiguration

Die OctoMesh-Developer-PowerShell verwendet eine Konfigurationsdatei pro Entwickler für alles, was von Ihrer Umgebung abhängt — die OctoMesh-Installationen, mit denen Sie sprechen, Ihre Container-Registry, Ihre Rancher- / Vault- / Semaphore- / AI-Bastion-Endpunkte, die Telerik-Kendo-UI-Lizenz. Diese Werte werden nicht im octo-tools-Repo ausgeliefert; sie liegen in ~/.config/octo-tools/installations.json außerhalb von git.

Das PowerShell-Profil lädt die Datei beim Start. Cmdlets, die einen Wert benötigen, werfen einen klaren, umsetzbaren Fehler, wenn die Datei fehlt oder der angeforderte Eintrag nicht definiert ist.

1. Die Konfiguration erstellen

Kopieren Sie die Beispieldatei aus dem Repo:

mkdir -p ~/.config/octo-tools
cp <your octo-tools checkout>/installations.example.json ~/.config/octo-tools/installations.json

Oder überschreiben Sie den Speicherort mit $env:OCTO_TOOLS_CONFIG, wenn Sie die Datei anderswo aufbewahren möchten (CI / geteiltes Dotfiles-Repo / etc.).

2. Den installations[]-Block bearbeiten

Register-OctoCliContext -Installation <name> schlägt die Installation anhand ihres name in dieser Liste nach. Jeder Eintrag hat eine services-Map mit URL-Vorlagen. Der Platzhalter {0} wird durch -$UriSuffix ersetzt, wenn Sie -UriSuffix übergeben, andernfalls durch die leere Zeichenkette — so deckt eine einzige Vorlage Preview-Subumgebungen ab.

Minimal sinnvoller Inhalt für einen lokalen Host-Prozess-Dev-Loop:

{
  "installations": [
    {
      "name": "local",
      "services": {
        "assets":        "https://localhost:5001/",
        "identity":      "https://localhost:5003/",
        "bots":          "https://localhost:5009/",
        "communication": "https://localhost:5015/",
        "reporting":     "https://localhost:5007/",
        "ai":            "https://localhost:5019/"
      }
    }
  ]
}

Fügen Sie ein Remote-Cluster auf dieselbe Weise hinzu:

{
  "name": "example-test",
  "services": {
    "assets":        "https://assets{0}.test.example.com/",
    "identity":      "https://connect{0}.test.example.com/",
    "bots":          "https://bots{0}.test.example.com/",
    "communication": "https://communication{0}.test.example.com/",
    "reporting":     "https://reporting{0}.test.example.com/",
    "ai":            "https://ai{0}.test.example.com/"
  }
}

Nun löst Register-OctoCliContext -Installation example-test -TenantId mytenant -UriSuffix pr123 zu https://assets-pr123.test.example.com/ usw. auf.

3. (Optional) Weitere Endpunkte hinzufügen

Dieselbe Datei sammelt jeden umgebungsspezifischen Endpunkt, den das Tooling benötigt:

{
  "registry":  { "url": "your-dev-registry.example.com" },
  "rancher":   { "url": "https://rancher.example.com" },
  "vault":     { "addr": "https://vault.example.com" },
  "semaphore": {
    "url": "https://semaphore.example.com",
    "breakGlassProjectId":  1,
    "breakGlassTemplateId": 1
  },
  "aiBastion": { "url": "https://ai.example.com" }
}

Jeder Top-Level-Block ist optional. Cmdlets scheitern nur, wenn der spezifische Block fehlt, den sie benötigen. profile.ps1 exportiert RANCHER_URL, VAULT_ADDR, SEMAPHORE_URL, SEMAPHORE_BREAKGLASS_PROJECT_ID und SEMAPHORE_BREAKGLASS_TEMPLATE_ID beim Start aus diesen Blöcken; Cmdlets, die diese Umgebungsvariablen lesen, funktionieren unverändert.

Vollständige Schema-Referenz: docs/installations-config.md im octo-tools-Repo.

4. Privates Profil für persönliche Zugangsdaten

Alles, was persönlich für Sie ist (Ihre Telerik-Kendo-UI-Lizenz, Ihr Rancher-API-Token, Ihr octo-cli-Token für die AI-Bastion), gehört in ein privates PowerShell-Profil, das das octo-tools-Profil am Ende seines Bootstraps lädt.

OS	Pfad
macOS / Linux	~/.config/powershell/Microsoft.PowerShell_profile_private.ps1
Windows	~/.pwsh/profile.ps1

Typischer Inhalt:

# Telerik Kendo UI license JWT. Get it from
# https://www.telerik.com/account/your-licenses
$env:TELERIK_LICENSE   = "<your Kendo UI license JWT>"

# Rancher API token. Create at:
# <your Rancher URL>/dashboard/account/index → "Account & API Keys" → "Create API Key"
# Format: token-xxxxx:secret. Choose "No Scope" and an explicit expiry.
$env:RANCHER_API_TOKEN = "token-xxxxx:secret"

Hier gesetzte Werte überschreiben, was die geteilte Konfigurationsdatei gesetzt hat — nützlich, wenn Sie die Konfiguration in einem Dotfiles-Repo halten, aber dennoch eine der Umgebungsvariablen pro Rechner variieren möchten.

5. Überprüfen

Öffnen Sie eine frische pwsh (damit profile.ps1 läuft), dann:

Get-OctoToolsConfig | Format-List
Get-OctoInstallation -Name local
$env:RANCHER_URL
$env:VAULT_ADDR

Wenn Sie die JSON-Datei bearbeiten, während die Shell bereits läuft, übernehmen Sie die Änderung ohne Neustart mit:

Get-OctoToolsConfig -Force

6. Fehlerbehebung

• octo-tools config not found at ... — ~/.config/octo-tools/installations.json existiert nicht. Erstellen Sie sie aus der Beispieldatei (Schritt 1).
• Installation '<name>' is not defined in your octo-tools config — fügen Sie einen Eintrag für diesen Namen unter installations[] hinzu. Die Fehlermeldung listet auch die Namen auf, die Sie bereits konfiguriert haben.
• Installation '<name>' does not define a '<service>' service URL — fügen Sie den fehlenden Schlüssel unter services hinzu. Erforderliche Schlüssel sind assets, identity, bots, communication. reporting und ai sind nur erforderlich, wenn Sie Register-OctoCliContext -IncludeReporting oder -IncludeAi aufrufen.