STACKIT SDK for Go

Das STACKIT SDK for Go bietet ein sicheres, strukturiertes und modulares Toolkit für die Interaktion mit den APIs des STACKIT-Cloud-Ökosystems. Das STACKIT SDK for Go ist in ein unabhängiges Core-Utility-Modul und dedizierte Service-Submodule aufgeteilt, um den Deployment-Footprint minimal zu halten.

Prerequisites

Das STACKIT SDK for Go benötigt Go-Version 1.25 oder höher. Hole vor dem Ausführen von API-Operationen eine gültige STACKIT-Projekt-ID aus dem STACKIT Portal.

Erste Schritte

Folge diesen Schritten, um die Module des STACKIT SDK for Go in deinen Entwicklungs-Workspace zu integrieren.

1. Core-Modul herunterladen: Führe den Befehl zur Abhängigkeitsauflösung des Paketmanagers aus, um geteilte Funktionalität, Authentifizierungssysteme und die grundlegenden Client-Konfigurationsstrukturen zu installieren.

   go get github.com/stackitcloud/stackit-sdk-go/core

2. Benötigte Services herunterladen: Installiere einzelne Service-Ressourcen-Clients unabhängig, um eine saubere Dependency-Kopplung zu erzwingen. Lade beispielsweise den DNS-Management-Client herunter.

   go get github.com/stackitcloud/stackit-sdk-go/services/dns

3. Engine-Code initialisieren: Importiere die heruntergeladenen Client-Strukturen in deine Anwendungslogik, um die Orchestrierung zu starten.

---

Code-Blueprint: DNS-Zonen-Management

Das folgende produktionsreife Beispiel zeigt, wie ein API-Client initialisiert wird, um Zonen-Ressourcendefinitionen im STACKIT-DNS-Dienst zu lesen und zu erstellen.

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/stackitcloud/stackit-sdk-go/services/dns"
)

func main() {
  // Specify the target project context
  projectId := "YOUR_STACKIT_PROJECT_ID_UUID"

  // Instantiate a service client using the default configuration
  dnsClient, err := dns.NewAPIClient()
  if err != nil {
    fmt.Fprintf(os.Stderr, "[STACKIT Go SDK] Failed to initialize client session: %v\n", err)
    os.Exit(1)
  }

  // Retrieve the DNS zones associated with the project scope
  ctx := context.Background()
  getZoneResp, err := dnsClient.GetZones(ctx, projectId).Execute()
  if err != nil {
    fmt.Fprintf(os.Stderr, "[STACKIT Go SDK] Error calling GetZones: %v\n", err)
  } else {
    fmt.Printf("[STACKIT Go SDK] Discovered active zone count: %v\n", len(getZoneResp.Zones))
  }

  // Declare the payload for the target zone state
  createZonePayload := dns.CreateZonePayload{
    Name:    "production-zone-alpha",
    DnsName: "infra.alpha-sovereign.com",
  }

  // Execute the request to allocate the DNS zone
  createZoneResp, err := dnsClient.CreateZone(ctx, projectId).CreateZonePayload(createZonePayload).Execute()
  if err != nil {
    fmt.Fprintf(os.Stderr, "[STACKIT Go SDK] Zone allocation failed: %v\n", err)
  } else {
    createdZone := createZoneResp.Zone
    fmt.Printf("[STACKIT Go SDK] Provisioned zone \"%s\" mapping to ID: %s\n", createdZone.Name, createdZone.Id)
  }
}

---

Authentifizierungsschemata

Das STACKIT SDK for Go benötigt einen instanziierten Service-Account mit präzisen Berechtigungs-Mappings (etwa project.owner), um automatisierte Änderungen durchzuführen.

Unterstützte Authentifizierungsmethoden

• Workload Identity Federation: Workload Identity Federation nutzt kurzlebige OIDC-Tokens, um Identitäten ohne persistente Secret-Speicherung zu verifizieren.
• Key-Pair-Flow: Der Key-Pair-Flow nutzt kryptografische RSA-Private/Public-Key-Bindungen, um zeitlich begrenzte Tokens auszustellen.
• Token-Flow: Der Token-Flow autorisiert über langlebige technische Tokens und ist für Produktionsumgebungen deprecated.

Auswertung und Prioritätsmechanik

Der Konfigurationsmanager des STACKIT SDK for Go parst die Umgebung in einer definierten Reihenfolge, um passende Anmeldedaten zu finden.

1. Explizite In-Code-Deklarationen: In-Code-Deklarationen überschreiben Fallback-Muster über programmatische Parameter, die direkt in der Anwendungsinitialisierung angegeben werden.

2. System-Umgebungsvariablen: Das SDK prüft Umgebungsvariablen im laufenden Shell-Kontext.

3. Lokale Datei-Konfiguration: Das SDK wertet die standardisierte Credentials-Datei unter $HOME/.stackit/credentials.json aus.

Die vollständige Schema-Dokumentation für alle unterstützten Ressourcen und Data Sources wird im offiziellen Repository des STACKIT SDK for Go und in der STACKIT-API-Referenz gepflegt.