Installieren Sie den STACKIT Server Agenten über die STACKIT IAAS API, die STACKIT CLI oder STACKIT Terraform

Zuletzt aktualisiert am 19. Mai 2026

Um unsere neuesten Features wie Run Command, Server Update Management Service und viele weitere zukünftige Funktionen nutzen zu können, muss der STACKIT Server Agent als Basis auf Ihrem Server installiert sein. Der STACKIT Server Agent dient als Schnittstelle zwischen unserer Infrastruktur und dem Betriebssystem. Er empfängt und verarbeitet remote gesendete Skripte und führt sie lokal auf Ihrem Server aus, sodass Sie Ihre Server-Einstellungen nach Bedarf anpassen können.

Die folgende Dokumentation beschreibt, wie Sie Ihren Server mithilfe der STACKIT IAAS API, der STACKIT CLI oder STACKIT Terraform vollständig konfiguriert mit der neuesten verfügbaren Version des STACKIT Server Agent bereitstellen können.

Wenn Sie den STACKIT Server Agent lieber über das STACKIT Portal installieren möchten, lesen Sie bitte diese Dokumentation: Installation des STACKIT Server Agents über das Portal.

Wenn Sie den STACKIT Server Agent auf einem bereits laufenden Linux- oder Windows Server installieren möchten, lesen Sie bitte diese Dokumentation: Installation des STACKIT Server Agents auf einem bestehenden Server.

Voraussetzungen

Sie haben ein Service Account erstellt.
(Siehe: Service Accounts erstellen, verwalten und löschen)
Sie haben diesem Service Account die erforderlichen Projektberechtigungen zugewiesen. (Siehe: Rollen einem Benutzer oder Service Account zuweisen)
Sie haben ein Access Token für diesen Service Account erstellt. (Siehe: Kurzlebige Access Tokens abrufen)
Grundkenntnisse in der Nutzung von APIs: VM über API erstellen
Kenntnisse im Umgang mit der STACKIT-Befehlszeilenschnittstelle (CLI) oder STACKIT Terraform.
Windows Server über APIs und CLIs erstellen: Windows Server über die STACKIT API erstellen

Installation des STACKIT Server Agents auf einem neuen Server über die STACKIT IaaS API

Der STACKIT Server Agent wird über vendordata installiert, wenn das entsprechende Flag in der API Anfrage enthalten ist. Achten Sie bei der Bereitstellung eines Servers über die STACKIT IAAS API darauf, dass dieses Flag gesetzt ist, wenn Sie möchten, dass der Agent installiert wird. Sie können dieses Flag wie unten gezeigt als agent-Eigenschaft in der API setzen (weitere Informationen finden Sie auch in der API Dokumentation).

1. Standardanfrage

Wenn Sie öffentliche STACKIT Images verwenden, fügen Sie einfach das provisioned-Flag hinzu:

JSON
{
  "agent": {
    "provisioned": true
  }
}

2. Verwendung benutzerdefinierter Images

Bei benutzerdefinierten Linux Images muss die STACKIT Infrastruktur vor der Erstellung des Servers darüber informiert werden, dass das Image mit dem Agenten kompatibel ist. Dies erfolgt in der Regel während Ihrer Image Release Pipeline.

Nach dem Hochladen Ihres Images müssen Sie eine PATCH Anfrage an den STACKIT IAAS API Image Endpunkt senden, um die Agenten Eigenschaften festzulegen:

Endpunkt: PATCH /projects/{projectId}/regions/{region}/images/{imageId}

Beispiel Payload:

JSON
{
  "name": "my-server",
  "machineType": "g2i.1",
  "imageSourceId": "<IMAGE_ID>",
  "agent": {
    "supported": true,
    "provisionByDefault": true
  }
}

supported: Muss auf “true” gesetzt sein, damit der Agent über Vendordata installiert werden kann.

provisionByDefault: Wenn auf “true” gesetzt, wird der Agent auf jedem Server installiert, der aus diesem Image erstellt wird, auch wenn das Agent-Flag in der Anfrage zur Servererstellung weggelassen wird.

Hinweis: Ohne diese Metadaten Eigenschaften wird die Vendordata Einbindung nicht ausgelöst und der Agent wird nicht automatisch installiert.

3. Fallback über Userdata

Wenn Ihr Betriebssystem Vendordata nicht unterstützt (z. B. Windows Server, Debian 11), müssen Sie das Installationsskript manuell über das Userdata-Feld einbinden.

Wichtig: Bei der Verwendung von Userdata für die Installation sollte das API Flag agent.provisioned in der Regel weggelassen oder auf false gesetzt werden, um widersprüchliche Installationsversuche zu vermeiden.

Die spezifischen Skripte, die in Userdata zu verwenden sind, finden Sie unter: Installieren des STACKIT Server Agenten auf einem bestehenden Server.

Diese Methode zur Bereitstellung des STACKIT Server Agent wird für alle aktuellen x86/amd64-Versionen der öffentlichen STACKIT Linux Images unterstützt (ARM wird in Zukunft unterstützt werden).

Installation des STACKIT Server Agenten auf einem neuen Server über die STACKIT CLI

Die STACKIT CLI ermittelt anhand einer Bereitstellungsrichtlinie, ob der Agent bei der Servererstellung installiert werden soll.

stackit server create \
  --name "my-server" \
  --machine-type "g3i.2" \
  --boot-volume-source-id <IMAGE_ID> \
  --agent-provisioning-policy "ALWAYS"

Das Flag —agent-provisioning-policy unterstützt die folgenden Werte:

Richtlinie	Beschreibung
ALWAYS	Erzwingt die Installation des Agenten, unabhängig von der Konfiguration des Server-Images.
NEVER	Den Agenten nicht installieren, unabhängig von der Image-Konfiguration.
INHERIT (Standard)	Das im ausgewählten Server-Image definierte Standardverhalten verwenden.

Weitere Informationen zur Installation und Verwendung der STACKIT-CLI finden Sie im offiziellen GitHub-Repository: stackit-CLI.

Installation des STACKIT Server Agenten auf einem neuen Server über STACKIT Terraform

Im STACKIT Terraform Provider wird die Installation des Agenten über das Argument “provisioning_policy” gesteuert.

resource "stackit_server" "example" {
  name                = "my-server"
  project_id          = "<PROJECT_ID>"
  machine_type        = "g3i.2"

  boot_volume = {
    source_id   = "<IMAGE_ID>"
    source_type = "image"
    size        = 64
  }

  # Defines the agent installation behavior
  agent = {
    provisioning_policy = "ALWAYS"
  }
}

Das Argument “provisioning_policy” unterstützt die folgenden Werte:

Richtlinie	Beschreibung
ALWAYS	Erzwingt die Installation des Agenten, unabhängig von der Konfiguration des Server-Images.
NEVER	Installiert den Agenten nicht, unabhängig von der Image-Konfiguration.
INHERIT (Standard)	Verwendet das im ausgewählten Server-Image definierte Standardverhalten.

Das Attribut agent_provisioned steht als schreibgeschütztes Feld zur Überprüfung des Status zur Verfügung, aber die provisioning_policy ist die primäre Steuerung für Ihren Infrastrukturcode. (Siehe: STACKIT Terraform Provider-Dokumentation: https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs)

Überprüfung der Installation des STACKIT Server Agent

Überprüfen Sie nach dem Start der Server Bereitstellung den Status Ihres Servers. Sobald der Server verfügbar ist und Sie sich anmelden können, überprüfen Sie, ob der STACKIT Server Agent ordnungsgemäß installiert wurde, indem Sie den Status des STACKIT Server Agent Dienstes STACKITServerAgent überprüfen. In Windows verwenden Sie den folgenden PowerShell-Befehl:

Get-Service STACKITServerAgent

Alternativ überprüfen Sie den Status im Tab Dienste des Task-Managers:

Liste der Windows-Dienste, in welcher der Dienst "STACKITServerAgent" mit dem Status "Wird ausgeführt" hervorgehoben ist.

Windows Dienste zeigt den 'STACKITServerAgent'-Service.

Verwenden Sie in Linux den folgenden Befehl:

systemctl status stackit-server-agent.service

Linux Terminalausgabe, die den Status von "stackit-server-agent.service" über systemctl als "aktiv (läuft)" anzeigt.

Der STACKIT Server Agent ist nun vollständig konfiguriert und kann zur Ausführung von Befehlen verwendet werden.

Installation des STACKIT Server Agent auf einem bestehenden Server

Wenn Sie bereits einen laufenden Linux- oder Windows-Server haben, können Sie den STACKIT Server Agent nachträglich manuell installieren, indem Sie die folgende Dokumentation verwenden: Installieren Sie den Server Agent über das Portal.