Menggunakan kumpulan sesi di Azure Container Apps

Kumpulan sesi menyediakan waktu alokasi sesi sub-detik dan mengelola siklus hidup setiap sesi.

Konsep umum untuk kedua kumpulan

Proses untuk membuat kumpulan sedikit berbeda tergantung pada apakah Anda membuat kumpulan sesi penerjemah kode atau kumpulan kontainer kustom. Konsep berikut berlaku untuk keduanya.

Untuk membuat kumpulan sesi menggunakan Azure CLI, pastikan Anda memiliki versi terbaru Azure CLI dan ekstensi Azure Container Apps:

# Upgrade the Azure CLI
az upgrade

# Install or upgrade the Azure Container Apps extension
az extension add --name containerapp --upgrade --allow-preview true -y

Perintah kumpulan sesi umum meliputi:

  • az containerapp sessionpool create
  • az containerapp sessionpool show
  • az containerapp sessionpool list
  • az containerapp sessionpool update
  • az containerapp sessionpool delete

Gunakan --help dengan perintah apa pun untuk melihat argumen yang tersedia dan nilai yang didukung.

Untuk memeriksa status kumpulan sesi, gunakan az containerapp sessionpool show perintah :

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

Saat membuat atau memperbarui kumpulan, Anda dapat mengatur jumlah maksimum sesi bersamaan, periode pendinginan saat tidak aktif, dan menentukan apakah lalu lintas jaringan keluar diizinkan untuk sesi.

Penting

Jika Anda mengaktifkan egress, kode yang berjalan dalam sesi dapat mengakses internet. Berhati-hatilah saat kode tidak tepercaya karena dapat digunakan untuk melakukan aktivitas berbahaya seperti serangan penolakan layanan.

Penting

Jika sesi digunakan untuk menjalankan kode yang tidak tepercaya, jangan sertakan informasi atau data yang tidak Anda inginkan untuk diakses oleh kode yang tidak tepercaya. Asumsikan kode berbahaya dan memiliki akses penuh ke kontainer, termasuk variabel lingkungan, rahasia, dan filenya.

Mengonfigurasi kumpulan

Gunakan az containerapp sessionpool create --help untuk melihat argumen CLI terbaru untuk konfigurasi kumpulan sesi. Bagian ini berfokus pada opsi konfigurasi tingkat lanjut yang berlaku di seluruh versi API.

Konfigurasi siklus hidup sesi

Saat membuat atau memperbarui kumpulan sesi, Anda dapat mengonfigurasi bagaimana sesi dihentikan dengan mengatur properties.dynamicPoolConfiguration.lifecycleConfiguration. Dimulai dengan versi 2025-01-01API , pilih salah satu dari dua jenis siklus hidup.

Untuk spesifikasi API lengkap, lihat spesifikasi SESSIONPools API.

Terjadwal (default)

Timed Dengan siklus hidup, sesi dihapus setelah periode tidak aktif. Setiap permintaan yang dikirim ke sesi mengatur ulang penghitung waktu jeda, memperpanjang masa aktif sesi dengan cooldownPeriodInSeconds.

Nota

Timed didukung untuk semua jenis kumpulan sesi dan berfungsi sama seperti executionType: Timed di versi API sebelumnya.

{
  "dynamicPoolConfiguration": {
    "lifecycleConfiguration": {
      "cooldownPeriodInSeconds": 600,
      "lifecycleType": "Timed"
    }
  }
}
Harta benda Description
cooldownPeriodInSeconds Sesi dihapus ketika tidak ada permintaan untuk durasi ini.
maxAlivePeriodInSeconds Tidak didukung untuk Timed siklus hidup.

Titik akhir manajemen

Penting

Pengidentifikasi sesi adalah informasi sensitif yang memerlukan proses aman saat Anda membuat dan mengelola nilainya. Untuk melindungi nilai ini, aplikasi Anda harus memastikan setiap pengguna atau penyewa hanya memiliki akses ke sesi mereka sendiri.

Kegagalan untuk mengamankan akses ke sesi dapat mengakibatkan penyalahgunaan atau akses tidak sah ke data yang disimpan dalam sesi pengguna Anda. Untuk informasi selengkapnya, lihat Pengidentifikasi sesi

Semua permintaan ke titik akhir manajemen kumpulan harus menyertakan header Authorization dengan token pembawa. Untuk mempelajari cara mengautentikasi dengan API manajemen kumpulan, lihat Autentikasi.

Sebagian besar permintaan API juga memerlukan parameter identifier string kueri dengan ID sesi. ID sesi unik ini memungkinkan aplikasi Anda berinteraksi dengan sesi tertentu. Operasi di seluruh kumpulan seperti sesi daftar tidak memerlukan pengidentifikasi. Untuk mempelajari selengkapnya tentang pengidentifikasi sesi, lihat Pengidentifikasi sesi.

Penembolokan gambar

Saat kumpulan sesi dibuat atau diperbarui, Azure Container Apps menyimpan gambar kontainer di kumpulan. Pengaturan cache ini membantu mempercepat proses pembuatan sesi baru.

Setiap perubahan pada gambar tidak secara otomatis tercermin dalam sesi. Untuk memperbarui gambar, perbarui kumpulan sesi dengan tag gambar baru. Gunakan tag unik untuk setiap pembaruan gambar untuk memastikan bahwa gambar baru ditarik.

Kumpulan sesi penerjemah kode

Gunakan perintah az containerapps sessionpool create untuk membuat kumpulan. Contoh berikut membuat kumpulan sesi penerjemah kode Python bernama my-session-pool. Pastikan untuk mengganti <RESOURCE_GROUP> dengan nama grup sumber daya anda sebelum menjalankan perintah.

az containerapp sessionpool create \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --location westus2 \
    --container-type PythonLTS \
    --max-sessions 100 \
    --cooldown-period 300 \
    --network-status EgressDisabled

Anda dapat menentukan pengaturan berikut saat membuat kumpulan sesi:

Setting Description
--container-type Jenis penerjemah kode yang akan digunakan. Nilai yang didukung mencakup PythonLTS, NodeLTS, Shell, dan CustomContainer.
--max-sessions Jumlah sesi maksimum yang dapat dialokasikan pada saat bersamaan. Nilai maksimumnya adalah 600.
--cooldown-period Jumlah detik diam yang diizinkan sebelum penghentian. Periode diam diatur ulang setiap kali API sesi dipanggil. Rentang yang diizinkan adalah antara 300 dan 3600.
--network-status Menentukan apakah lalu lintas jaringan keluar diizinkan dari sesi. Nilai yang valid adalah EgressDisabled (default) dan EgressEnabled.

Titik akhir manajemen penerjemah kode

Untuk menggunakan sesi penerjemah kode dengan integrasi kerangka kerja LLM atau dengan memanggil titik akhir API manajemen secara langsung, Anda memerlukan titik akhir API manajemen kumpulan.

Titik akhir dalam format https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>.

Untuk mengambil titik akhir API manajemen untuk kumpulan sesi, lihat bagian umum di atas untuk contoh perintah.

Titik akhir berikut tersedia untuk mengelola sesi dalam kumpulan:

Jalur titik akhir Metode Description
code/execute POST Jalankan kode dalam sesi.
files/upload POST Unggah file ke sesi.
files/content/{filename} GET Mengunduh sebuah file dari sesi.
files GET Daftar file dalam sesi.
session GET Dapatkan detail tentang sesi tertentu.
listSessions GET Cantumkan semua sesi di kumpulan dengan penomoran halaman.
session DELETE Menghentikan dan menghapus sesi.

Anda membangun URL lengkap untuk setiap titik akhir dengan menggabungkan titik akhir API manajemen kumpulan dengan jalur titik akhir. String kueri harus menyertakan parameter yang identifier berisi pengidentifikasi sesi, dan api-version parameter dengan nilai 2024-02-02-preview. Versi API dapat berubah, jadi selalu konfirmasikan versi terbaru di dokumen REST API sebelum menggunakannya dalam produksi.

Misalnya: {sessionManagementEndpoint}/code/execute?api-version=2024-02-02-preview&identifier=<IDENTIFIER>

get sessionUntuk API , delete session dan list sessions , lihat Mengambil informasi sesi untuk detail permintaan dan respons.

Untuk referensi REST API, referensikan API Komponen Data dari Container Apps dan ringkasan operasi Komponen Data dari Container Apps.

Kumpulan sesi kontainer kustom

Untuk membuat kumpulan sesi kontainer kustom, Anda perlu menyediakan gambar kontainer dan pengaturan konfigurasi kumpulan.

Anda memanggil atau berkomunikasi dengan setiap sesi menggunakan permintaan HTTP. Kontainer kustom harus mengekspos server HTTP pada port yang Anda tentukan untuk merespons permintaan ini.

Kemampuan berikut hanya berlaku untuk kumpulan sesi kontainer kustom.

Titik akhir manajemen kontainer kustom

Untuk kumpulan sesi kontainer kustom, dapatkan titik akhir manajemen dari portal Azure atau output Azure CLI. Titik akhir dikembalikan sebagai poolManagementEndpoint.

Titik akhir dalam format https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io.

Kumpulan kontainer kustom mendukung titik akhir manajemen yang sama dengan kumpulan penerjemah kode, ditambah titik akhir aplikasi kustom yang Anda tentukan:

Jalur titik akhir Metode Description
* (jalur kustom) POST, GET Titik akhir kustom yang ditentukan oleh aplikasi kontainer Anda.
.management/getSession POST Dapatkan detail tentang sesi tertentu.
.management/listSessions POST Cantumkan semua sesi di kumpulan dengan penomoran halaman.
.management/stopSession POST Hentikan sesi.

Untuk getSession, stopSession dan listSessions titik akhir, lihat Ambil informasi sesi untuk detail permintaan dan respons.

OnContainerExit

OnContainerExit Dalam siklus hidup, sesi tetap aktif sampai kontainer keluar sendiri atau periode aktif maksimum tercapai.

{
  "dynamicPoolConfiguration": {
    "lifecycleConfiguration": {
      "maxAlivePeriodInSeconds": 6000,
      "lifecycleType": "OnContainerExit"
    }
  }
}
Harta benda Description
maxAlivePeriodInSeconds Waktu maksimum sesi dapat tetap aktif sebelum dihapus.
cooldownPeriodInSeconds Tidak didukung untuk OnContainerExit siklus hidup.

Pemeriksaan kontainer

Pemantauan kontainer memungkinkan Anda untuk memeriksa kesehatan kontainer sesi agar pool dapat mendeteksi sesi yang tidak sehat dan menggantinya demi menjaga target tetap readySessionInstances sehat.

Kumpulan sesi mendukung pemeriksaan Liveness dan Startup . Untuk informasi selengkapnya tentang perilaku probe, lihat Health probes di Azure Container Apps.

Saat membuat atau memperbarui kumpulan sesi, tentukan pengujian di properties.customContainerTemplate.containers. Untuk skema isi permintaan lengkap, lihat referensi API SessionPools Create atau Update. Contoh berikut menunjukkan konfigurasi parsial dengan definisi probe:

{
  "properties": {
    "customContainerTemplate": {
      "containers": [
        {
          "name": "my-session-container",
          "image": "myregistry.azurecr.io/my-session-image:latest",
          "probes": [
            {
              "type": "Liveness",
              "httpGet": {
                "path": "/health",
                "port": 8080
              },
              "periodSeconds": 10,
              "failureThreshold": 3
            },
            {
              "type": "Startup",
              "httpGet": {
                "path": "/ready",
                "port": 8080
              },
              "periodSeconds": 5,
              "failureThreshold": 30
            }
          ]
        }
      ]
    },
    "dynamicPoolConfiguration": {
      "readySessionInstances": 5
    }
  }
}

Kumpulan sesi kontainer kustom memerlukan lingkungan Azure Container Apps yang diaktifkan profil beban kerja. Jika Anda tidak memiliki lingkungan, gunakan az containerapp env create -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP> --location <LOCATION> perintah untuk membuatnya.

az containerapp sessionpool create Gunakan perintah untuk membuat kumpulan sesi kontainer kustom.

Contoh berikut membuat kumpulan sesi bernama my-session-pool dengan gambar kontainer kustom myregistry.azurecr.io/my-container-image:1.0.

Sebelum Anda mengirim permintaan, ganti placeholder di antara tanda <> dengan nilai yang sesuai untuk kumpulan sesi dan pengidentifikasi sesi Anda.

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>

Perintah ini membuat kumpulan sesi dengan pengaturan berikut:

Pengaturan Nilai Description
--name my-session-pool Nama kumpulan sesi.
--resource-group my-resource-group Grup sumber daya yang berisi kumpulan sesi.
--environment my-environment Nama atau ID sumber daya lingkungan aplikasi kontainer.
--container-type CustomContainer Jenis kontainer kumpulan sesi. Harus CustomContainer untuk sesi kontainer kustom.
--image myregistry.azurecr.io/my-container-image:1.0 Gambar kontainer yang digunakan untuk kumpulan sesi.
--registry-server myregistry.azurecr.io Nama host server registri kontainer.
--registry-username my-username Nama pengguna untuk masuk ke registri kontainer.
--registry-password my-password Kata sandi untuk masuk ke registri kontainer.
--cpu 0.25 CPU yang diperlukan dalam bentuk inti.
--memory 0.5Gi Memori yang diperlukan.
--target-port 80 Port sesi yang digunakan untuk lalu lintas masuk.
--cooldown-period 300 Jumlah detik yang dapat diam sesi sebelum sesi dihentikan. Periode diam diatur ulang setiap kali API sesi dipanggil. Nilai harus antara 300 dan 3600.
--network-status EgressDisabled Menentukan apakah lalu lintas jaringan keluar diizinkan dari sesi. Nilai yang valid adalah EgressDisabled (default) dan EgressEnabled.
--max-sessions 10 Jumlah maksimum sesi yang dapat dialokasikan secara bersamaan.
--ready-sessions 5 Jumlah target sesi yang tersedia dalam pool sesi setiap saat. Tingkatkan jumlah ini jika sesi dialokasikan lebih cepat daripada kumpulan yang sedang diisi ulang.
--env-vars "key1=value1" "key2=value2" Variabel lingkungan yang akan diatur dalam kontainer.
--location "Supported Location" Lokasi kumpulan sesi.

Untuk memperbarui kumpulan sesi, gunakan az containerapp sessionpool update perintah .

  • Terakhir diperbarui pada