Benutzerdefinierte Azure Container Apps-Containersitzungen

Zusätzlich zum integrierten Codeinterpreter, den dynamische Azure Container Apps-Sitzungen bereitstellen, können Sie auch benutzerdefinierte Container verwenden, um Ihre eigenen Sitzungssandboxes zu definieren.

Verwendungsmöglichkeiten für benutzerdefinierte Containersitzungen

Mit benutzerdefinierten Containern können Sie Lösungen erstellen, die speziell auf Ihre Anforderungen zugeschnitten sind. Sie ermöglichen es Ihnen, Code oder Anwendungen in Umgebungen auszuführen, die schnell und kurzlebig sind und sichere Sandkastenbereiche mit Hyper-V bieten. Darüber hinaus können sie mit optionaler Netzwerkisolation konfiguriert werden. Beispiele hierfür sind:

• Codeinterpreter: Wenn Sie nicht vertrauenswürdigen Code in sicheren Sandboxes mit einer Sprache ausführen müssen, die im integrierten Interpreter nicht unterstützt wird, oder Sie die vollständige Kontrolle über die Codeinterpreterumgebung benötigen.

• Isolierte Ausführung: Wenn Sie Anwendungen in feindlichen Szenarien mit mehreren Mandanten ausführen müssen, in denen jeder Mandant oder Benutzer über eine eigene Sandkastenumgebung verfügt. Diese Umgebungen sind voneinander und von der Hostanwendung isoliert. Beispiele sind u. a. Anwendungen, die vom Benutzer bereitgestellten Code ausführen, Code, der Endbenutzerzugriff auf eine cloudbasierte Shell gewährt, KI-Agents und Entwicklungsumgebungen.

Verwenden benutzerdefinierter Containersitzungen

Um benutzerdefinierte Containersitzungen zu verwenden, erstellen Sie zunächst einen Sitzungspool mit einem benutzerdefinierten Containerimage. Azure Container Apps startet Container automatisch mit den bereitgestellten Images in ihren eigenen Hyper-V-Sandboxes. Sobald der Container gestartet wurde, ist er für den Sitzungspool verfügbar.

Wenn Ihre Anwendung eine Sitzung anfordert, wird sofort eine Instanz aus dem Pool zugeordnet. Die Sitzung bleibt aktiv, bis sie in einen Leerlaufzustand wechselt, wird dann automatisch beendet und zerstört.

Erstellen eines benutzerdefinierten Containersitzungspools

Um einen benutzerdefinierten Containersitzungspool zu erstellen, müssen Sie ein Containerimage und Konfigurationseinstellungen für den Pool bereitstellen.

Sie rufen mithilfe von HTTP-Anforderungen einzelne Sitzungen auf oder kommunizieren mit diesen. Der benutzerdefinierte Container muss einen HTTP-Server auf einem von Ihnen angegebenen Port verfügbar machen, um auf diese Anforderungen zu reagieren.

Azure-Befehlszeilenschnittstelle

Wenn Sie einen benutzerdefinierten Containersitzungspool mit der Azure-Befehlszeilenschnittstelle (Command Line Interface, CLI) erstellen möchten, stellen Sie mithilfe der folgenden Befehle sicher, dass Sie über die aktuellen Versionen der Azure CLI und der Azure Container Apps-Erweiterung verfügen:

az upgrade
az extension add --name containerapp --upgrade --allow-preview true -y

Benutzerdefinierte Containersitzungspools erfordern eine Azure Container Apps-Umgebung mit Unterstützung für Workloadprofile. Falls Sie nicht über eine Umgebung verfügen, verwenden Sie den Befehl az containerapp env create -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP> --location <LOCATION> --enable-workload-profiles, um eine zu erstellen.

Verwenden Sie den Befehl az containerapp sessionpool create, um einen benutzerdefinierten Containersitzungspool zu erstellen.

Im folgenden Beispiel wird ein Sitzungspool namens my-session-pool mit dem benutzerdefinierten Containerimage myregistry.azurecr.io/my-container-image:1.0 erstellt.

Ersetzen Sie vor dem Senden der Anforderung die Platzhalter zwischen den Klammern (<>) durch die entsprechenden Werte für Ihren Sitzungspool und die Sitzungs-ID.

az containerapp sessionpool create \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --environment <ENVIRONMENT> \
    --registry-server myregistry.azurecr.io \
    --registry-username <USER_NAME> \
    --registry-password <PASSWORD> \
    --container-type CustomContainer \
    --image myregistry.azurecr.io/my-container-image:1.0 \
    --cpu 0.25 --memory 0.5Gi \
    --target-port 80 \
    --cooldown-period 300 \
    --network-status EgressDisabled \
    --max-sessions 10 \
    --ready-sessions 5 \
    --env-vars "key1=value1" "key2=value2" \
    --location <LOCATION>

Dieser Befehl erstellt einen Sitzungspool mit den folgenden Einstellungen:

Parameter	Wert	Beschreibung
--name	my-session-pool	Der Name des Sitzungspools.
--resource-group	my-resource-group	Die Ressourcengruppe, die den Sitzungspool enthält.
--environment	my-environment	Der Name der Ressourcen-ID der Umgebung der Container-App.
--container-type	CustomContainer	Der Containertyp des Sitzungspools. Für benutzerdefinierte Containersitzungen muss der Typ CustomContainer sein.
--image	myregistry.azurecr.io/my-container-image:1.0	Das Containerimage, das für den Sitzungspool verwendet werden soll.
--registry-server	myregistry.azurecr.io	Der Hostname des Containerregistrierungsservers.
--registry-username	my-username	Der Benutzername für die Anmeldung bei der Containerregistrierung.
--registry-password	my-password	Das Kennwort für die Anmeldung bei der Containerregistrierung.
--cpu	0.25	Die erforderliche CPU in Kernen.
--memory	0.5Gi	Der erforderliche Arbeitsspeicher.
--target-port	80	Der Sitzungsport, der für eingehenden Datenverkehr verwendet wird.
--cooldown-period	300	Die Anzahl von Sekunden, nach der eine Sitzung im Leerlauf beendet wird. Der Leerlaufzeitraum wird jedes Mal zurückgesetzt, wenn die API der Sitzung aufgerufen wird. Der Wert muss zwischen 300 und 3600 liegen.
--network-status	Legt fest, ob ausgehender Netzwerkdatenverkehr aus der Sitzung zulässig ist. Gültige Werte sind EgressDisabled (Standard) und EgressEnabled.
--max-sessions	10	Die maximale Anzahl von Sitzungen, die gleichzeitig zugeordnet werden können.
--ready-sessions	5	Die Zielanzahl von Sitzungen, die immer im Sitzungspool bereit sind. Erhöhen Sie diese Anzahl, wenn Sitzungen schneller zugeordnet werden, als der Pool aufgefüllt wird.
--env-vars	"key1=value1" "key2=value2"	Die Umgebungsvariablen, die im Container festgelegt werden sollen.
--location	"Supported Location"	Der Speicherort des Sitzungspools.

Verwenden Sie den az containerapp sessionpool show Befehl, um den Status des Sitzungspools zu überprüfen:

az containerapp sessionpool show \
    --name <SESSION_POOL_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --query "properties.poolManagementEndpoint" \
    --output tsv

Verwenden Sie den Befehl az containerapp sessionpool update, um den Sitzungspool zu aktualisieren.

Azure Resource Manager

Um einen benutzerdefinierten Containersitzungspool mit Azure Resource Manager zu erstellen, erstellen Sie eine Sitzungspoolressource mit dem Ressourcentyp Microsoft.ContainerApps/sessionPools. Das folgende Beispiel zeigt einen ARM-Vorlagenausschnitt, der einen benutzerdefinierten Containersitzungspool erstellt.

Ersetzen Sie vor dem Senden der Anforderung die Platzhalter zwischen den Klammern (<>) durch die entsprechenden Werte für Ihren Sitzungspool und die Sitzungs-ID.

{
  "type": "Microsoft.App/sessionPools",
  "apiVersion": "2024-08-02-preview",
  "name": "my-session-pool",
  "location": "westus2",
  "properties": {
    "environmentId": "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>",
    "poolManagementType": "Dynamic",
    "containerType": "CustomContainer",
    "scaleConfiguration": {
      "maxConcurrentSessions": 10,
      "readySessionInstances": 5
    },
    "dynamicPoolConfiguration": {
      "executionType": "Timed",
      "cooldownPeriodInSeconds": 600
    },
    "secrets": [
      {
        "name": "registrypassword",
        "value": "<REGISTRY_PASSWORD>"
      }
    ],
    "customContainerTemplate": {
      "registryCredentials": {
          "server": "myregistry.azurecr.io",
          "username": "myregistry",
          "passwordSecretRef": "registrypassword"
      },
      "containers": [
        {
          "image": "myregistry.azurecr.io/my-container-image:1.0",
          "name": "mycontainer",
          "resources": {
            "cpu": 0.25,
            "memory": "0.5Gi"
          },
          "command": [
            "/bin/sh"
          ],
          "args": [
            "-c",
            "while true; do echo hello; sleep 10;done"
          ],
          "env": [
            {
              "name": "key1",
              "value": "value1"
            },
            {
              "name": "key2",
              "value": "value2"
            }
          ]
        }
      ],
      "ingress": {
        "targetPort": 80
      }
    },
    "sessionNetworkConfiguration": {
      "status": "EgressEnabled"
    }
  }
}

Diese Vorlage erstellt einen Sitzungspool mit den folgenden Einstellungen:

Parameter	Wert	Beschreibung
name	my-session-pool	Der Name des Sitzungspools.
location	westus2	Der Speicherort des Sitzungspools.
environmentId	/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>	Die Ressourcen-ID der Umgebung der Container-App.
poolManagementType	Dynamic	Für benutzerdefinierte Containersitzungen muss der Typ Dynamic sein.
containerType	CustomContainer	Der Containertyp des Sitzungspools. Für benutzerdefinierte Containersitzungen muss der Typ CustomContainer sein.
scaleConfiguration.maxConcurrentSessions	10	Die maximale Anzahl von Sitzungen, die gleichzeitig zugeordnet werden können.
scaleConfiguration.readySessionInstances	5	Die Zielanzahl von Sitzungen, die immer im Sitzungspool bereit sind. Erhöhen Sie diese Anzahl, wenn Sitzungen schneller zugeordnet werden, als der Pool aufgefüllt wird.
dynamicPoolConfiguration.executionType	Timed	Der Ausführungstyp für den Sitzungspool. Für benutzerdefinierte Containersitzungen muss der Typ Timed sein.
dynamicPoolConfiguration.cooldownPeriodInSeconds	600	Die Anzahl von Sekunden, nach der eine Sitzung im Leerlauf beendet wird. Der Leerlaufzeitraum wird jedes Mal zurückgesetzt, wenn die API der Sitzung aufgerufen wird. Der Wert muss zwischen 300 und 3600 liegen.
secrets	[{ "name": "registrypassword", "value": "<REGISTRY_PASSWORD>" }]	Eine Liste der geheimen Schlüssel.
customContainerTemplate.registryCredentials.server	myregistry.azurecr.io	Der Hostname des Containerregistrierungsservers.
customContainerTemplate.registryCredentials.username	myregistry	Der Benutzername für die Anmeldung bei der Containerregistrierung.
customContainerTemplate.registryCredentials.passwordSecretRef	registrypassword	Der Name des geheimen Schlüssels, der das Kennwort zum Anmelden bei der Containerregistrierung enthält.
customContainerTemplate.containers[0].image	myregistry.azurecr.io/my-container-image:1.0	Das Containerimage, das für den Sitzungspool verwendet werden soll.
customContainerTemplate.containers[0].name	mycontainer	Der Name des Containers,
customContainerTemplate.containers[0].resources.cpu	0.25	Die erforderliche CPU in Kernen.
customContainerTemplate.containers[0].resources.memory	0.5Gi	Der erforderliche Arbeitsspeicher.
customContainerTemplate.containers[0].env	Array von Name-Wert-Paaren	Die Umgebungsvariablen, die im Container festgelegt werden sollen.
customContainerTemplate.containers[0].command	["/bin/sh"]	Der Befehl, der im Container ausgeführt werden soll.
customContainerTemplate.containers[0].args	["-c", "while true; do echo hello; sleep 10;done"]	Die Argumente, die an den Befehl übergeben werden sollen.
customContainerTemplate.containers[0].ingress.targetPort	80	Der Sitzungsport, der für eingehenden Datenverkehr verwendet wird.
sessionNetworkConfiguration.status	EgressDisabled	Legt fest, ob ausgehender Netzwerkdatenverkehr aus der Sitzung zulässig ist. Gültige Werte sind EgressDisabled (Standard) und EgressEnabled.

Wichtig

Wenn die Sitzung zum Ausführen von nicht vertrauenswürdigem Code verwendet wird, schließen Sie keine Informationen oder Daten ein, auf die der nicht vertrauenswürdige Code nicht zugreifen soll. Gehen Sie davon aus, dass der Code schädlich ist und Vollzugriff auf den Container hat, einschließlich der Umgebungsvariablen, Geheimnisse und Dateien.

Zwischenspeichern von Bildern

Wenn ein Sitzungspool erstellt oder aktualisiert wird, speichert Azure-Container-Apps das Containerimage im Pool zwischen. Mit dieser Zwischenspeicherung können Sie den Prozess des Erstellens neuer Sitzungen beschleunigen.

Alle Änderungen am Bild werden in den Sitzungen nicht automatisch wiedergegeben. Um das Image zu aktualisieren, aktualisieren Sie den Sitzungspool mit einem neuen Imagetag. Verwenden Sie für jede Bildaktualisierung ein eindeutiges Tag, um sicherzustellen, dass das neue Bild abgerufen wird.

Mit Sitzungen arbeiten

Ihre Anwendung interagiert mithilfe der Verwaltungs-API des Sitzungspools mit einer Sitzung.

Der Verwaltungsendpunkt eines Pools für benutzerdefinierte Containersitzungen weist folgendes Format auf: https://<SESSION_POOL>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io.

Verwenden Sie den Befehl az containerapp sessionpool show, um den Verwaltungsendpunkt des Sitzungspools abzurufen:

az containerapp sessionpool show \
    --name <SESSION_POOL_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --query "properties.poolManagementEndpoint" \
    --output tsv

Alle Anforderungen an den Verwaltungsendpunkt des Pools müssen einen Authorization-Header mit einem Bearertoken enthalten. Informationen zum Authentifizieren mit der Poolverwaltungs-API finden Sie unter Authentifizierung.

Jede API-Anforderung muss auch den Abfragezeichenfolgenparameter identifier mit der Sitzungs-ID enthalten. Mit dieser eindeutigen Sitzungs-ID kann Ihre Anwendung mit bestimmten Sitzungen interagieren. Weitere Informationen zu Sitzungs-IDs finden Sie unter Sitzungs-IDs.

Wichtig

Der Sitzungsbezeichner ist vertrauliche Information, was einen sicheren Prozess erfordert, während Sie seinen Wert erstellen und verwalten. Um diesen Wert zu schützen, muss Ihre Anwendung sicherstellen, dass jeder Benutzer oder Mandant nur Zugriff auf seine eigenen Sitzungen hat. Wenn Sie den Zugriff auf Sitzungen nicht sichern, kann dies zu Missbrauch oder unbefugtem Zugriff auf Daten führen, die in den Sitzungen Ihrer Benutzer gespeichert sind. Weitere Informationen finden Sie unter Sitzungs-IDs.

Weiterleiten von Anforderungen an den Container der Sitzung:

Alle Elemente im Pfad, die dem Verwaltungsendpunkt für den Basispool folgen, werden an den Container der Sitzung weitergeleitet.

Wenn Sie z. B. <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile aufrufen, wird die Anforderung an den Container der Sitzung an 0.0.0.0:<TARGET_PORT>/api/uploadfile weitergeleitet.

Kontinuierliche Sitzungsinteraktion:

Sie können weiterhin Anforderungen an dieselbe Sitzung senden. Wenn länger als die Abkühldauer keine Anforderungen an die Sitzung gesendet werden, wird die Sitzung automatisch gelöscht.

Beispielanforderung

Das folgende Beispiel zeigt eine Anforderung an eine benutzerdefinierte Containersitzung anhand einer Benutzer-ID.

Ersetzen Sie vor dem Senden der Anforderung die Platzhalter zwischen den Klammern (<>) durch Werte, die für Ihre Anforderung spezifisch sind.

POST https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io/<API_PATH_EXPOSED_BY_CONTAINER>?identifier=<USER_ID>
Authorization: Bearer <TOKEN>
{
  "command": "echo 'Hello, world!'"
}

Diese Anforderung wird an die benutzerdefinierte Containersitzung mit dem Bezeichner für die Benutzer-ID weitergeleitet. Wenn die Sitzung noch nicht ausgeführt wird, ordnet Azure Container Apps eine Sitzung aus dem Pool zu, bevor die Anforderung weitergeleitet wird.

Im Beispiel empfängt der Container der Sitzung die Anforderung unter http://0.0.0.0:<INGRESS_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>.

Verwenden einer verwalteten Identität

Eine verwaltete Identität von Microsoft Entra ID ermöglicht es Ihren benutzerdefinierten Containersitzungspools und deren Sitzungen, auf andere von Microsoft Entra geschützte Ressourcen zuzugreifen. Weitere Informationen zu verwalteten Identitäten in Microsoft Entra ID finden Sie unter Verwaltete Identitäten für Azure-Ressourcen.

Sie können verwaltete Identitäten für Ihre benutzerdefinierten Containersitzungspools aktivieren. Es werden sowohl systemseitig als auch benutzerseitig zugewiesene verwaltete Identitäten unterstützt.

Es gibt zwei Möglichkeiten, verwaltete Identitäten mit benutzerdefinierten Containersitzungspools zu verwenden:

• Authentifizierung beim Abrufen des Image (image pull):: Verwenden Sie die verwaltete Identität zur Authentifizierung bei der Containerregistrierung, um das Containerimage abzurufen.

• Ressourcenzugriff: Verwenden Sie die verwaltete Identität des Sitzungspools in einer Sitzung, um auf andere von Microsoft Entra geschützte Ressourcen zuzugreifen. Aufgrund ihrer Sicherheitsauswirkungen ist diese Funktion standardmäßig deaktiviert.

  Wichtig

  Wenn Sie den Zugriff auf verwaltete Identität in einer Sitzung aktivieren, können Code oder Programme, die in der Sitzung ausgeführt werden, Entra-Token für die verwaltete Identität des Pools erstellen. Da Sitzungen in der Regel nicht vertrauenswürdigen Code ausführen, verwenden Sie dieses Feature mit Vorsicht.

Azure-Befehlszeilenschnittstelle

Verwenden Sie Azure Resource Manager, um verwaltete Identität für einen benutzerdefinierten Containersitzungspool zu aktivieren.

Azure Resource Manager

Um verwaltete Identität für einen benutzerdefinierten Containersitzungspool zu aktivieren, fügen Sie der Sitzungspoolressource eine identity Eigenschaft hinzu. Die identity Eigenschaft muss eine type Eigenschaft mit dem Wert SystemAssigned oder UserAssigned haben. Ausführliche Informationen zum Konfigurieren dieser Eigenschaft finden Sie unter Konfigurieren verwalteter Identitäten.

Das folgende Beispiel zeigt einen ARM-Vorlagenausschnitt, der eine vom Benutzer zugewiesene Identität für einen benutzerdefinierten Containersitzungspool ermöglicht und für die Image-Pull-Authentifizierung verwendet. Ersetzen Sie vor dem Senden der Anforderung die Platzhalter zwischen den Klammern (<>) durch die entsprechenden Werte für Ihren Sitzungspool und die Sitzungs-ID.

{
  "type": "Microsoft.App/sessionPools",
  "apiVersion": "2024-08-02-preview",
  "name": "my-session-pool",
  "location": "westus2",
  "properties": {
    "environmentId": "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>",
    "poolManagementType": "Dynamic",
    "containerType": "CustomContainer",
    "scaleConfiguration": {
      "maxConcurrentSessions": 10,
      "readySessionInstances": 5
    },
    "dynamicPoolConfiguration": {
      "executionType": "Timed",
      "cooldownPeriodInSeconds": 600
    },
    "customContainerTemplate": {
      "registryCredentials": {
          "server": "myregistry.azurecr.io",
          "identity": "<IDENTITY_RESOURCE_ID>"
      },
      "containers": [
        {
          "image": "myregistry.azurecr.io/my-container-image:1.0",
          "name": "mycontainer",
          "resources": {
            "cpu": 0.25,
            "memory": "0.5Gi"
          },
          "command": [
            "/bin/sh"
          ],
          "args": [
            "-c",
            "while true; do echo hello; sleep 10;done"
          ],
          "env": [
            {
              "name": "key1",
              "value": "value1"
            },
            {
              "name": "key2",
              "value": "value2"
            }
          ]
        }
      ],
      "ingress": {
        "targetPort": 80
      }
    },
    "sessionNetworkConfiguration": {
      "status": "EgressEnabled"
    },
    "managedIdentitySettings": [
      {
        "identity": "<IDENTITY_RESOURCE_ID>",
        "lifecycle": "None"
      }
    ]
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "<IDENTITY_RESOURCE_ID>": {}
    }
  }
}

Diese Vorlage enthält die folgenden zusätzlichen Einstellungen für verwaltete Identität:

Parameter	Wert	Beschreibung
customContainerTemplate.registryCredentials.identity	<IDENTITY_RESOURCE_ID>	Die Ressourcen-ID der verwalteten Identität, die für die Image-Pull-Authentifizierung verwendet werden soll.
managedIdentitySettings.identity	<IDENTITY_RESOURCE_ID>	Die Ressourcen-ID der verwalteten Identität, die in der Sitzung verwendet werden soll.
managedIdentitySettings.lifecycle	None	Der Sitzungslebenszyklus, in dem die verwaltete Identität verfügbar ist. - None (Standard): Die Sitzung kann nicht auf die Identität zugreifen. Es wird nur für Image-Pull verwendet. - Main: Zusätzlich zum Image-Pull kann die Hauptsitzung auch auf die Identität zugreifen. Mit Vorsicht verwenden.

Logging

Konsolenprotokolle aus benutzerdefinierten Containersitzungen sind im Azure Log Analytics-Arbeitsbereich verfügbar, der der Azure-Container-Apps-Umgebung in einer Tabelle mit dem Namen AppEnvSessionConsoleLogs_CLzugeordnet ist.

Abrechnung

Benutzerdefinierte Containersitzungen werden basierend auf den vom Sitzungspool verbrauchten Ressourcen abgerechnet. Weitere Informationen finden Sie unter Abrechnung von Azure Container Apps.

Nächste Schritte

Übersicht: Dynamische Azure Container Apps-Sitzungen