Menyiapkan host dan identitas node fleksibel (pratinjau)

Important

Fitur pratinjau AKS tersedia atas dasar layanan mandiri dan pendaftaran sukarela. Pratinjau disediakan "apa adanya" dan "sebagaimana tersedia," dan pratinjau tersebut dikecualikan dari perjanjian tingkat layanan (SLA) serta garansi terbatas. Fitur pratinjau AKS sebagian didukung oleh dukungan pelanggan sebatas upaya terbaik. Dengan demikian, fitur-fitur ini tidak dimaksudkan untuk penggunaan produksi. Untuk informasi lebih lanjut, lihat artikel dukungan berikut ini:

• Kebijakan dukungan AKS
• Tanya Jawab Umum dukungan Azure

Sebelum Anda melampirkan host Linux sebagai simpul fleksibel, siapkan host, konfigurasikan identitas yang Anda pilih selama perencanaan, dan berikan akses identitas tersebut ke kluster Azure Kubernetes Service (AKS).

Dalam artikel ini, Anda:

• Tinjau persyaratan host, lalu provisikan atau pilih host Linux dan identitas Azure.
• Siapkan dan periksa host, lalu catat nilai yang digunakan oleh alur kerja lampiran.
• Tetapkan akses identitas di cakupan kluster AKS, dan verifikasi identitas tersebut.

Jalankan perintah manajemen dalam artikel ini di lingkungan Bash yang kompatibel dengan Linux yang memiliki alat dan akses jaringan yang diperlukan. Artikel ini menyebut lingkungan Bash Anda. Mesin terpisah yang bergabung dengan kluster adalah host node flex; jalankan perintah di sana hanya jika suatu langkah secara eksplisit mengarahkan Anda untuk melakukannya.

Sebelum Anda mulai

• Selesaikan Konfigurasi jaringan dan buat kumpulan simpul fleksibel di AKS.
• Tinjau Konsep identitas dan akses untuk simpul fleksibel dan pilih satu opsi identitas.
• Gunakan akun Azure yang dapat memeriksa sumber daya host dan membuat penetapan peran di cakupan kluster AKS. Role Based Access Control Administrator dan User Access Administrator adalah contoh peran yang dapat membuat penugasan.
• Instal Azure CLI dan klien OpenSSH di lingkungan Bash Anda.
• Siapkan pasangan kunci SSH yang diterima oleh host.

Memuat lingkungan penyebaran

Mulai sesi Bash baru, identifikasi file lingkungan dari artikel perencanaan, dan muat. Ganti <deployment-name> dengan label deployment Anda.

export FLEXNODE_DEPLOYMENT="<deployment-name>"
export FLEXNODE_ENV_FILE="${HOME}/.config/aks-flexnode/${FLEXNODE_DEPLOYMENT}.env"
test -s "${FLEXNODE_ENV_FILE}"
source "${FLEXNODE_ENV_FILE}"

File lingkungan menyediakan nilai penyebaran bersama yang dibaca artikel ini, termasuk WORK_DIR, direktori di lingkungan Bash Anda tempat artikel ini menyimpan unduhan dan file yang dihasilkan. Secara default, WORK_DIR adalah ~/.local/share/aksflexnode/<deployment-name>. Artikel ini memperoleh variabel lain yang dibutuhkannya. Jika Anda belum membuat file lingkungan, selesaikan Rencanakan penyebaran simpul fleksibel Anda terlebih dahulu.

Jika file tidak ditemukan atau tidak dapat dimuat, hentikan dan kembali ke artikel perencanaan sebelum Anda melanjutkan.

Atur langganan aktif dan konfirmasikan kluster yang dipilih:

az account set --subscription "${SUBSCRIPTION_ID}"

az aks show \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --query "{Name:name,ResourceId:id,ProvisioningState:provisioningState}" \
    --output table

Lanjutkan ketika ID sumber daya cocok AKS_RESOURCE_ID dan status provisi adalah Succeeded.

1. Tinjau persyaratan host

Gunakan host khusus yang memenuhi persyaratan berikut:

• Host AMD64 atau ARM64 yang menjalankan Ubuntu 24.04 LTS, Azure Linux 3.x, atau Red Hat Enterprise Linux (RHEL) 9 atau 10.
• Nama host unik yang merupakan nama subdomain DNS yang valid. Agen mengonversinya menjadi huruf kecil ketika mendaftarkan simpul.
• Setidaknya empat vCPU dan setidaknya 8 GiB gratis di bawah /var/lib.
• Akun SSH dengan akses root atau tanpa sudo kata sandi pada host.
• Akses jaringan ke server API AKS, Azure Resource Manager, Microsoft Entra ID, rilis node fleksibel dan mirror artefak yang dipilih, serta registri kontainer yang diperlukan.
• Koneksi Lapisan 3 yang sudah ada antara host jaringan flex node dan jaringan node yang dikelola AKS. Host dan kluster AKS tidak harus berada di wilayah Azure yang sama.

Lingkungan Bash Anda juga harus dapat terhubung ke host simpul flex melalui SSH. Alamat IP publik tidak diperlukan saat Anda memiliki jalur manajemen lain yang disetujui.

2. Memprovisikan atau memilih host dan identitas

Lengkapi hanya bagian untuk opsi identitas yang dipilih di Konsep identitas dan akses untuk node flex. Jangan mengonfigurasi lebih dari satu mode identitas Azure tahan lama untuk host yang sama.

Tip

Menyambungkan mesin di luar Azure? Gunakan identitas terkelola Azure Arc jika mesin sudah mengaktifkan Arc, atau gunakan service principal. Gunakan identitas terkelola VM Azure hanya ketika host simpul flex adalah VM Azure.

Atur jalur kunci SSH yang digunakan oleh setiap opsi identitas:

export SSH_PRIVATE_KEY_PATH="<path-to-private-key>"
export SSH_PUBLIC_KEY_PATH="<path-to-public-key>"

Setiap opsi identitas juga menetapkan dua alamat host. FLEX_HOST_SSH_TARGET adalah alamat yang digunakan oleh lingkungan Bash Anda. FLEX_HOST_PRIVATE_IP adalah alamat host yang dapat dijangkau dari jaringan simpul yang dikelola AKS. Pastikan dengan administrator jaringan Anda bahwa FLEX_HOST_PRIVATE_IP termasuk dalam FLEX_HOST_SUBNET_CIDR dan merupakan alamat yang dapat dijangkau dari jaringan node yang dikelola AKS. Jangan gunakan alamat publik terpisah atau alamat khusus manajemen sebagai alamat node flex.

Menggunakan identitas terkelola Azure Arc

Gunakan opsi ini untuk host yang sudah tersambung ke Azure Arc. Jika perlu, ikuti Sambungkan komputer hibrid dengan server yang diaktifkan Azure Arc.

Atur nilai sumber daya Arc dan alamat host:

export ARC_RESOURCE_GROUP="<arc-machine-resource-group>"
export ARC_MACHINE_NAME="<arc-machine-name>"
export FLEX_HOST_SSH_TARGET="<admin-user>@<reachable-host-address>"
export FLEX_HOST_PRIVATE_IP="<private-ip-reachable-from-aks>"

Ambil ID sumber daya, status koneksi, dan ID objek utama:

ARC_RESOURCE_ID="/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${ARC_RESOURCE_GROUP}/providers/Microsoft.HybridCompute/machines/${ARC_MACHINE_NAME}"
export ARC_RESOURCE_ID

HOST_PRINCIPAL_OBJECT_ID="$(az resource show \
    --ids "${ARC_RESOURCE_ID}" \
    --query identity.principalId \
    --output tsv)"
export HOST_PRINCIPAL_OBJECT_ID

az resource show \
    --ids "${ARC_RESOURCE_ID}" \
    --query "{Name:name,Status:properties.status,IdentityType:identity.type,PrincipalId:identity.principalId}" \
    --output yaml

Lanjutkan saat Status adalah Connected dan PrincipalId diisi.

Verifikasi agen Connected Machine dan Hybrid Instance Metadata Service di host:

ssh -i "${SSH_PRIVATE_KEY_PATH}" "${FLEX_HOST_SSH_TARGET}" \
    'sudo azcmagent show && systemctl is-active himdsd'

Konfirmasikan bahwa azcmagent show melaporkan ID langganan, grup sumber daya, dan nama komputer yang sama dengan ARC_RESOURCE_ID, ARC_RESOURCE_GROUP, dan ARC_MACHINE_NAME. Konfirmasikan juga bahwa himdsd aktif. Jika sumber daya tidak cocok, hentikan dan koreksi nilai sumber daya Arc sebelum menetapkan akses.

Catat nilai Arc dan identitas:

set_flexnode_env ARC_RESOURCE_GROUP "${ARC_RESOURCE_GROUP}"
set_flexnode_env ARC_MACHINE_NAME "${ARC_MACHINE_NAME}"
set_flexnode_env ARC_RESOURCE_ID "${ARC_RESOURCE_ID}"
set_flexnode_env FLEX_HOST_SSH_TARGET "${FLEX_HOST_SSH_TARGET}"
set_flexnode_env FLEX_HOST_PRIVATE_IP "${FLEX_HOST_PRIVATE_IP}"
set_flexnode_env HOST_PRINCIPAL_OBJECT_ID "${HOST_PRINCIPAL_OBJECT_ID}"
set_flexnode_env HOST_IDENTITY_CLIENT_ID ""

Gunakan prinsipal layanan

Gunakan opsi ini untuk komputer virtual lain yang didukung atau host bare-metal. Sebaiknya gunakan kredensial sertifikat daripada rahasia klien jangka panjang. Langkah-langkah berikut membuat aplikasi khusus dan perwakilan layanan dengan sertifikat yang ditandatangani sendiri untuk evaluasi. Mereka tidak membuat rahasia klien atau menetapkan peran Azure. Anda memberikan akses ke kluster AKS target di langkah 4.

Sebelum melanjutkan:

• Instal OpenSSL di lingkungan Bash Anda, dan gunakan Azure CLI versi terbaru yang mendukung az login --certificate.
• Masuklah dengan akun yang dapat mendaftarkan aplikasi dan membuat prinsipal layanan di tenant Microsoft Entra yang terkait dengan langganan target. Kepemilikan langganan Azure saja tidak memberikan izin direktori ini. Jika penyewa Anda membatasi pendaftaran aplikasi, mintalah bantuan administrator penyewa Anda. Lihat Membuat perwakilan layanan Azure dengan Azure CLI.
• Konfirmasikan bahwa organisasi Anda mengizinkan sertifikat yang ditandatangani sendiri untuk evaluasi. Untuk identitas yang sudah disetujui, gunakan ID tenant, ID klien aplikasi, ID objek service principal, dan file PEM yang dilindungi, lalu lanjutkan ke Catat service principal dan nilai host.

Jangan simpan kredensial, kunci privat, atau jalur kredensial dalam file lingkungan bersama. Jangan mencetak file PEM atau menyertakannya dalam kontrol sumber. File PEM berisi kunci privat yang tidak terenkripsi sehingga agen dapat mengautentikasi tanpa permintaan kata sandi interaktif. Lindungi dengan izin file dan kontrol akses host yang disetujui.

Buat prinsipal layanan berbasis sertifikat

Jalankan perintah ini di lingkungan Bash Anda saat masuk dengan akun operator Anda.

1. Konfirmasi langganan, penyewa, dan akun masuk.

   az account set --subscription "${SUBSCRIPTION_ID}"
   az account show \
       --query "{SubscriptionId:id,TenantId:tenantId,Account:user.name}" \
       --output table
   
   SP_TENANT_ID="$(az account show --query tenantId --output tsv)"
   export SP_TENANT_ID
   

   Lanjutkan hanya jika langganan dan tenant merupakan target yang dimaksud.

2. Pilih nama tampilan aplikasi yang unik dan buat direktori kredensial yang dilindungi.

   export SP_DISPLAY_NAME="aks-flexnode-${FLEXNODE_DEPLOYMENT}-$(date -u +%Y%m%dT%H%M%SZ)"
   install -d -m 0700 "${WORK_DIR:?Load the deployment environment first.}"
   SP_CREDENTIAL_DIR="$(mktemp -d "${WORK_DIR}/sp-credential.XXXXXXXX")"
   export SP_CREDENTIAL_DIR
   export SP_CLIENT_CERTIFICATE_FILE="${SP_CREDENTIAL_DIR:?Credential directory wasn't created.}/sp-client.pem"
   

3. Buat sertifikat 30 hari dan file PEM gabungan yang berisi sertifikat dan kunci privat.

   (
       set -e
       umask 077
   
       openssl req -x509 -newkey rsa:2048 -sha256 -days 30 -nodes \
           -keyout "${SP_CREDENTIAL_DIR}/sp-client.key" \
           -out "${SP_CREDENTIAL_DIR}/sp-client.crt" \
           -subj "/CN=${SP_DISPLAY_NAME}"
   
       cat "${SP_CREDENTIAL_DIR}/sp-client.crt" \
           "${SP_CREDENTIAL_DIR}/sp-client.key" \
           > "${SP_CLIENT_CERTIFICATE_FILE}"
       chmod 0600 "${SP_CLIENT_CERTIFICATE_FILE}"
       rm -f "${SP_CREDENTIAL_DIR}/sp-client.key"
   )
   
   openssl x509 \
       -in "${SP_CREDENTIAL_DIR}/sp-client.crt" \
       -noout -subject -dates
   stat -c '%a %n' "${SP_CLIENT_CERTIFICATE_FILE}"
   

   Hentikan jika pembuatan sertifikat gagal. Konfirmasikan bahwa izin PEM adalah 600. Validitas 30 hari adalah untuk evaluasi, bukan kebijakan rotasi. Ganti kredensial sesuai prosedur yang telah disetujui sebelum masa berlakunya berakhir jika host masih terpasang.

4. Buat aplikasi dan prinsipal layanan dengan hanya mengunggah sertifikat publik.

   SP_CLIENT_ID="$(az ad sp create-for-rbac \
       --name "${SP_DISPLAY_NAME}" \
       --cert "@${SP_CREDENTIAL_DIR}/sp-client.crt" \
       --query appId \
       --output tsv)"
   export SP_CLIENT_ID
   

   Lanjutkan hanya ketika perintah berhasil dan mengembalikan ID klien aplikasi. Perintah dapat melaporkan bahwa tanggal akhir kredensial telah disesuaikan agar sesuai dengan tanggal kedaluwarsa sertifikat. Jangan tambahkan --role atau --scopes; penetapan peran yang terakhir hanya berlaku untuk kluster AKS. Jangan menjalankan ulang proses pembuatan pada aplikasi yang sudah ada untuk memperbarui kredensialnya.

5. Ambil ID objek prinsipal layanan dan periksa kredensial yang terdaftar.

   SP_OBJECT_ID="$(az ad sp show \
       --id "${SP_CLIENT_ID}" \
       --query id \
       --output tsv)"
   export SP_OBJECT_ID
   
   az ad sp show \
       --id "${SP_CLIENT_ID}" \
       --query "{ClientId:appId,ServicePrincipalObjectId:id}" \
       --output table
   
   az ad app show \
       --id "${SP_CLIENT_ID}" \
       --query "{ClientId:appId,PasswordCredentials:length(passwordCredentials),Certificates:keyCredentials[].{KeyId:keyId,Expires:endDateTime}}" \
       --output json
   

   Pastikan bahwa ID objek service principal terisi, kedua ID klien sama dengan SP_CLIENT_ID, PasswordCredentials adalah 0, dan tepat satu sertifikat terdaftar dengan tanggal kedaluwarsa yang diharapkan. Jika replikasi direktori menunda pencarian, tunggu sebentar dan coba lagi pencarian daripada membuat aplikasi lain.

Untuk pengujian khusus kredensial, jalankan hanya pemeriksaan autentikasi sertifikat di Memverifikasi perwakilan layanan. Anda tidak perlu menetapkan peran Azure atau menyiapkan host untuk pemeriksaan tersebut. Setelah pengujian selesai, hapus aplikasi pengujian khusus dan kredensial lokal.

Catat nilai service principal dan host

Atur alamat host. Jika Anda memilih identitas yang sudah ada, terlebih dahulu atur SP_TENANT_ID, SP_CLIENT_ID, dan SP_OBJECT_ID agar sesuai dengan pengidentifikasinya.

export FLEX_HOST_SSH_TARGET="<admin-user>@<reachable-host-address>"
export FLEX_HOST_PRIVATE_IP="<private-ip-reachable-from-aks>"

: "${SP_TENANT_ID:?Set the Microsoft Entra tenant ID.}"
: "${SP_CLIENT_ID:?Set the application client ID.}"
: "${SP_OBJECT_ID:?Set the service principal object ID.}"
export HOST_IDENTITY_CLIENT_ID=""
export HOST_PRINCIPAL_OBJECT_ID="${SP_OBJECT_ID}"

set_flexnode_env FLEX_HOST_SSH_TARGET "${FLEX_HOST_SSH_TARGET}"
set_flexnode_env FLEX_HOST_PRIVATE_IP "${FLEX_HOST_PRIVATE_IP}"
set_flexnode_env SP_TENANT_ID "${SP_TENANT_ID}"
set_flexnode_env SP_CLIENT_ID "${SP_CLIENT_ID}"
set_flexnode_env SP_OBJECT_ID "${SP_OBJECT_ID}"
set_flexnode_env HOST_IDENTITY_CLIENT_ID "${HOST_IDENTITY_CLIENT_ID}"
set_flexnode_env HOST_PRINCIPAL_OBJECT_ID "${HOST_PRINCIPAL_OBJECT_ID}"

SP_OBJECT_ID adalah ID objek aplikasi Enterprise, juga disebut ID objek perwakilan layanan. Ini bukan ID objek pendaftaran Aplikasi. Konfirmasikan bahwa SP_CLIENT_ID, SP_OBJECT_ID, dan sertifikat milik perwakilan layanan yang sama.

Bootstrap memetakan SP_TENANT_ID dan SP_CLIENT_ID ke azure.servicePrincipal.tenantId dan azure.servicePrincipal.clientId dalam konfigurasi agen yang dihasilkan. SP_OBJECT_IDdigunakan untuk penetapan peran Azure, bukan sebagai ID klien agen. Untuk kolom file sertifikat, struktur konfigurasi lengkap yang telah disunting, dan perintah verifikasi yang aman, lihat Periksa konfigurasi service principal yang dihasilkan.

Simpan file PEM yang dilindungi untuk verifikasi identitas dan bootstrap host. Pastikan tersedia pada host sesuai proses pengelolaan kredensial yang telah disetujui sebelum dilampirkan. Rekam lokasinya melalui proses manajemen kredensial yang disetujui, bukan dalam file lingkungan bersama. Lanjutkan dengan Siapkan dan periksa host, lalu tetapkan peran AKS.

Gunakan identitas terkelola pada mesin virtual Azure

Gunakan opsi ini untuk VM Azure. Buat VM dengan mengikuti Mulai Cepat: Buat komputer virtual Linux dengan Azure CLI, atau pilih VM yang sudah ada. Tempatkan VM di jaringan host simpul fleksibel yang direncanakan untuk penyebaran ini. Anda tidak memerlukan alamat IP publik saat lingkungan Bash Anda memiliki jalur SSH lain yang disetujui.

Atur nilai VM:

export VM_RESOURCE_GROUP="<vm-resource-group>"
export VM_NAME="<vm-name>"
export VM_ADMIN_USER="<vm-admin-user>"

Ambil ID sumber daya VM dan alamat host. Target SSH menggunakan alamat IP publik ketika VM memilikinya, dan alamat privat sebaliknya:

VM_RESOURCE_ID="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query id \
    --output tsv)"
export VM_RESOURCE_ID

FLEX_HOST_PRIVATE_IP="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --show-details \
    --query privateIps \
    --output tsv)"
export FLEX_HOST_PRIVATE_IP

VM_PUBLIC_IP="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --show-details \
    --query publicIps \
    --output tsv)"
export VM_PUBLIC_IP

export FLEX_HOST_SSH_TARGET="${VM_ADMIN_USER}@${VM_PUBLIC_IP:-${FLEX_HOST_PRIVATE_IP}}"

Konfirmasikan alamat privat yang dikembalikan untuk VM:

az vm list-ip-addresses \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query "[0].virtualMachine.{Name:name,PrivateAddresses:network.privateIpAddresses}" \
    --output table

Lanjutkan hanya ketika FLEX_HOST_PRIVATE_IP berisi satu alamat privat milik FLEX_HOST_SUBNET_CIDR dan dapat dijangkau dari jaringan simpul yang dikelola AKS. Jika Azure mengembalikan lebih dari satu alamat, atur FLEX_HOST_PRIVATE_IP ke alamat simpul fleksibel yang direncanakan sebelum Anda melanjutkan.

Jika VM tidak memiliki alamat IP publik, atau lingkungan Bash Anda mencapai host melalui jalur manajemen lain yang disetujui, atur FLEX_HOST_SSH_TARGET ke alamat atau nama host yang dapat dijangkau lingkungan Bash Anda.

Selesaikan salah satu opsi identitas terkelola berikut ini.

Identitas terkelola yang diberikan oleh sistem

Aktifkan identitas terkelola yang ditetapkan sistem:

az vm identity assign \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --output none

Ambil ID objek utamanya:

HOST_PRINCIPAL_OBJECT_ID="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query identity.principalId \
    --output tsv)"
export HOST_PRINCIPAL_OBJECT_ID

export HOST_IDENTITY_CLIENT_ID=""

Identitas terkelola yang ditetapkan pengguna

Buat atau pilih identitas dengan mengikuti Kelola identitas terkelola yang ditetapkan pengguna dengan menggunakan Azure CLI.

Atur nilai identitas:

export USER_ASSIGNED_IDENTITY_RESOURCE_GROUP="<identity-resource-group>"
export USER_ASSIGNED_IDENTITY_NAME="<identity-name>"

Ambil pengenal identitas:

USER_ASSIGNED_IDENTITY_RESOURCE_ID="$(az identity show \
    --resource-group "${USER_ASSIGNED_IDENTITY_RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query id \
    --output tsv)"
export USER_ASSIGNED_IDENTITY_RESOURCE_ID

HOST_PRINCIPAL_OBJECT_ID="$(az identity show \
    --resource-group "${USER_ASSIGNED_IDENTITY_RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query principalId \
    --output tsv)"
export HOST_PRINCIPAL_OBJECT_ID

HOST_IDENTITY_CLIENT_ID="$(az identity show \
    --resource-group "${USER_ASSIGNED_IDENTITY_RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query clientId \
    --output tsv)"
export HOST_IDENTITY_CLIENT_ID

Tetapkan identitas ke VM:

az vm identity assign \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --identities "${USER_ASSIGNED_IDENTITY_RESOURCE_ID}" \
    --output none

Verifikasi bahwa VM mencantumkan identitas yang dipilih:

az vm identity show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query "{Type:type,UserAssignedIdentities:userAssignedIdentities}" \
    --output yaml

Lanjutkan saat output menyertakan USER_ASSIGNED_IDENTITY_RESOURCE_ID.

Merekam identitas VM

Catat nilai VM dan identitas:

set_flexnode_env VM_RESOURCE_GROUP "${VM_RESOURCE_GROUP}"
set_flexnode_env VM_NAME "${VM_NAME}"
set_flexnode_env VM_ADMIN_USER "${VM_ADMIN_USER}"
set_flexnode_env VM_RESOURCE_ID "${VM_RESOURCE_ID}"
set_flexnode_env VM_PUBLIC_IP "${VM_PUBLIC_IP}"
set_flexnode_env FLEX_HOST_SSH_TARGET "${FLEX_HOST_SSH_TARGET}"
set_flexnode_env FLEX_HOST_PRIVATE_IP "${FLEX_HOST_PRIVATE_IP}"
set_flexnode_env HOST_PRINCIPAL_OBJECT_ID "${HOST_PRINCIPAL_OBJECT_ID}"
set_flexnode_env HOST_IDENTITY_CLIENT_ID "${HOST_IDENTITY_CLIENT_ID}"

3. Siapkan dan periksa host

Sambungkan ke host:

ssh -i "${SSH_PRIVATE_KEY_PATH}" "${FLEX_HOST_SSH_TARGET}"

Pada host, periksa sistem operasi, arsitektur, nama host, CPU, dan penyimpanan yang tersedia:

source /etc/os-release
printf 'Operating system: %s %s\n' "${NAME}" "${VERSION_ID}"
printf 'Architecture: %s\n' "$(uname -m)"
printf 'Host name: %s\n' "$(hostname)"
printf 'vCPUs: %s\n' "$(nproc)"
free -h
df -h /var/lib

Bandingkan hasilnya dengan persyaratan host di langkah 1. Atasi perbedaan apa pun sebelum Melanjutkan.

Skrip bootstrap memerlukan curl, , jqdan tar pada host dan berhenti jika salah satu dari mereka hilang. Agen node flex menginstal paket runtime yang tersisa saat bootstrap.

Pasang mana saja dari ketiganya yang belum disertakan dalam image Anda:

# Ubuntu
sudo apt-get update && sudo apt-get install -y curl jq tar

# Azure Linux 3
sudo tdnf install -y curl jq tar

Keluar dari sesi host:

exit

Baca nama host Linux aktual dari lingkungan Bash Anda:

FLEX_HOST_NAME="$(ssh \
    -i "${SSH_PRIVATE_KEY_PATH}" \
    "${FLEX_HOST_SSH_TARGET}" \
    hostname)"
export FLEX_HOST_NAME

printf 'Flex host name: %s\n' "${FLEX_HOST_NAME}"

Lanjutkan ketika perintah mengembalikan nama host yang diharapkan.

Ambil FQDN server API AKS dan verifikasi resolusi nama dan konektivitas HTTPS dari host:

AKS_API_FQDN="$(az aks show \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --query '(privateFqdn || fqdn)' \
    --output tsv)"
export AKS_API_FQDN

ssh -i "${SSH_PRIVATE_KEY_PATH}" "${FLEX_HOST_SSH_TARGET}" \
    "getent hosts '${AKS_API_FQDN}' && \
    timeout 5 bash -c '</dev/tcp/${AKS_API_FQDN}/443'"

Jika resolusi nama atau koneksi TCP gagal, perbaiki DNS, perutean, atau kontrol jaringan sebelum Anda melanjutkan. Kluster AKS publik menggunakan API FQDN publiknya. Untuk kluster AKS privat, lingkungan Bash dan jaringan host simpul fleksibel Anda harus dapat mengurai dan merutekan ke FQDN API privat.

Catat nilai host. Berkas lingkungan bersama menyimpan jalur dan pengidentifikasi yang tidak bersifat rahasia, bukan isi kunci atau kredensial.

set_flexnode_env SSH_PRIVATE_KEY_PATH "${SSH_PRIVATE_KEY_PATH}"
set_flexnode_env SSH_PUBLIC_KEY_PATH "${SSH_PUBLIC_KEY_PATH}"
set_flexnode_env FLEX_HOST_NAME "${FLEX_HOST_NAME}"

4. Tetapkan peran AKS

Alur kerja pratinjau saat ini menggunakan Peran Kontributor Azure Kubernetes Service pada cakupan kluster AKS yang tepat. Ketiga opsi identitas menggunakan ID objek perwakilan layanan untuk kontrol akses berbasis peran Azure. Gunakan identitas host khusus, dan hapus tugas ini saat Anda menghapus host seperti yang dijelaskan dalam Mengelola dan menghapus simpul fleksibel di AKS.

Tampilkan ID objek utama terpilih:

printf 'Principal object ID: %s\n' "${HOST_PRINCIPAL_OBJECT_ID}"

Lanjutkan hanya jika nilainya telah diisi dan sesuai dengan identitas VM, mesin Arc, atau prinsipal layanan yang dipilih.

Periksa apakah tugas sudah ada:

az role assignment list \
    --assignee-object-id "${HOST_PRINCIPAL_OBJECT_ID}" \
    --scope "${AKS_RESOURCE_ID}" \
    --fill-principal-name false \
    --query "[?roleDefinitionName=='Azure Kubernetes Service Contributor Role'].{PrincipalId:principalId,Role:roleDefinitionName,Scope:scope}" \
    --output table

Jika perintah tidak mengembalikan baris, buat penugasan:

az role assignment create \
    --assignee-object-id "${HOST_PRINCIPAL_OBJECT_ID}" \
    --assignee-principal-type ServicePrincipal \
    --role "Azure Kubernetes Service Contributor Role" \
    --scope "${AKS_RESOURCE_ID}" \
    --output none

Jalankan perintah daftar lagi. Lanjutkan ketika ID utama dan cakupan cocok dengan identitas yang dipilih dan AKS_RESOURCE_ID. Penyebaran penetapan peran dapat memakan waktu beberapa menit.

5. Verifikasi identitas yang dipilih

Sebelum melakukan bootstrap pada host, pastikan bahwa identitas yang dipilih dapat melakukan autentikasi dan membaca kluster AKS target yang dimaksud. Selesaikan hanya bagian untuk opsi identitas Anda.

Memverifikasi identitas terkelola Azure Arc

Di lingkungan Bash Anda, teruskan ID sumber daya AKS nonrahasia ke server berkemampuan Azure Arc:

[[ "${AKS_RESOURCE_ID}" == /subscriptions/*/providers/Microsoft.ContainerService/managedClusters/* ]]
printf -v AKS_RESOURCE_ID_QUOTED '%q' "${AKS_RESOURCE_ID}"

ssh -t \
    -i "${SSH_PRIVATE_KEY_PATH}" \
    "${FLEX_HOST_SSH_TARGET}" \
    "export AKS_RESOURCE_ID=${AKS_RESOURCE_ID_QUOTED}; \
    exec bash -l"

Di server yang mendukung Azure Arc, minta token Azure Resource Manager dari Hybrid Instance Metadata Service (HIMDS) dan gunakan untuk membaca sumber daya AKS. Membaca token tantangan memerlukan akses root atau keanggotaan dalam grup himds:

TOKEN_URL="${IDENTITY_ENDPOINT:-http://127.0.0.1:40342/metadata/identity/oauth2/token}?api-version=2019-11-01&resource=https%3A%2F%2Fmanagement.azure.com"

CHALLENGE_TOKEN_PATH="$(curl --silent --show-error \
    --dump-header - \
    --output /dev/null \
    --header Metadata:true \
    "${TOKEN_URL}" |
    sed -n 's/^[Ww][Ww][Ww]-[Aa]uthenticate: Basic realm=//p' |
    tr -d '\r')"

test -n "${CHALLENGE_TOKEN_PATH}"
CHALLENGE_TOKEN="$(sudo cat "${CHALLENGE_TOKEN_PATH}")"

TOKEN="$(curl --fail --silent --show-error \
    --header Metadata:true \
    --header "Authorization: Basic ${CHALLENGE_TOKEN}" \
    "${TOKEN_URL}" |
    jq -r '.access_token // empty')"

test -n "${TOKEN}"

AKS_ARM_HTTP="$(curl --silent --show-error \
    --output /dev/null \
    --write-out '%{http_code}' \
    --header "Authorization: Bearer ${TOKEN}" \
    "https://management.azure.com${AKS_RESOURCE_ID}?api-version=2025-07-01")"

unset CHALLENGE_TOKEN TOKEN
printf 'AKS_ARM_HTTP=%s\n' "${AKS_ARM_HTTP}"

Output yang diharapkan: AKS_ARM_HTTP=200. Jalankan exit untuk meninggalkan sesi server dengan dukungan Azure Arc.

Memverifikasi perwakilan layanan

Di lingkungan Bash Anda, gunakan file PEM gabungan dari langkah persiapan prinsipal layanan. Jika Anda memulai sesi baru atau memilih identitas yang sudah ada, atur jalur terproteksinya lagi:

export SP_CLIENT_CERTIFICATE_FILE="<protected-path-to-sp-client.pem>"
test -s "${SP_CLIENT_CERTIFICATE_FILE}"

Hentikan jika file tidak ada atau kosong. Jangan tambahkan jalur ini ke file lingkungan bersama.

Pertama verifikasi autentikasi sertifikat dengan profil Azure CLI terisolasi. Subshell menghapus cache token sementaranya bahkan ketika perintah gagal dan tidak mengubah proses masuk Azure CLI normal Anda.

(
    set -e
    SP_AZURE_CONFIG_DIR="$(mktemp -d)"
    chmod 0700 "${SP_AZURE_CONFIG_DIR}"
    trap 'rm -rf -- "${SP_AZURE_CONFIG_DIR}"' EXIT
    export AZURE_CONFIG_DIR="${SP_AZURE_CONFIG_DIR}"

    az login \
        --service-principal \
        --username "${SP_CLIENT_ID}" \
        --certificate "${SP_CLIENT_CERTIFICATE_FILE}" \
        --tenant "${SP_TENANT_ID}" \
        --allow-no-subscriptions \
        --output none

    az account get-access-token \
        --resource https://management.azure.com/ \
        --query "{Tenant:tenant,ExpiresOn:expiresOn}" \
        --output table
)

Konfirmasikan bahwa Penyewa cocok SP_TENANT_ID dan token belum kedaluwarsa. Perintah ini hanya mencetak tenant dan waktu kedaluwarsa, bukan token akses. --allow-no-subscriptionsmemungkinkan Anda menguji autentikasi sebelum memberikan akses Azure. Autentikasi yang berhasil tidak membuktikan izin untuk membaca atau mendaftar dengan kluster AKS.

Setelah penetapan peran AKS di langkah 4 diterapkan, verifikasi bahwa Anda memiliki akses ke kluster target yang dimaksud:

(
    set -e
    SP_AZURE_CONFIG_DIR="$(mktemp -d)"
    chmod 0700 "${SP_AZURE_CONFIG_DIR}"
    trap 'rm -rf -- "${SP_AZURE_CONFIG_DIR}"' EXIT
    export AZURE_CONFIG_DIR="${SP_AZURE_CONFIG_DIR}"

    az login \
        --service-principal \
        --username "${SP_CLIENT_ID}" \
        --certificate "${SP_CLIENT_CERTIFICATE_FILE}" \
        --tenant "${SP_TENANT_ID}" \
        --output none

    az account set --subscription "${SUBSCRIPTION_ID}"

    az aks show \
        --resource-group "${RESOURCE_GROUP}" \
        --name "${CLUSTER_NAME}" \
        --query "{Name:name,ResourceId:id,ProvisioningState:provisioningState}" \
        --output table
)

Lanjutkan hanya ketika ID sumber daya yang dikembalikan cocok AKS_RESOURCE_ID dan status provisi adalah Succeeded. Jika autentikasi berhasil tetapi permintaan kluster ditolak, verifikasi ID objek perwakilan layanan, cakupan penetapan peran yang tepat, dan penyebaran sebelum mencoba kembali. Pemeriksaan ini membuktikan bahwa perwakilan layanan dan sertifikatnya dapat membaca kluster target. Host menggunakan kredensial yang disiapkan di Melampirkan node flex ke kluster AKS.

Memverifikasi identitas terkelola VM Azure

Di lingkungan Bash Anda, teruskan ID sumber daya AKS nonsecret dan ID klien identitas ke VM Azure:

[[ "${AKS_RESOURCE_ID}" == /subscriptions/*/providers/Microsoft.ContainerService/managedClusters/* ]]
printf -v AKS_RESOURCE_ID_QUOTED '%q' "${AKS_RESOURCE_ID}"
printf -v HOST_IDENTITY_CLIENT_ID_QUOTED '%q' "${HOST_IDENTITY_CLIENT_ID}"

ssh -t \
    -i "${SSH_PRIVATE_KEY_PATH}" \
    "${FLEX_HOST_SSH_TARGET}" \
    "export AKS_RESOURCE_ID=${AKS_RESOURCE_ID_QUOTED}; \
    export HOST_IDENTITY_CLIENT_ID=${HOST_IDENTITY_CLIENT_ID_QUOTED}; \
    exec bash -l"

Pada VM Azure, minta token Azure Resource Manager dari identitas terkelola yang dipilih dan gunakan untuk membaca sumber daya AKS:

TOKEN_URL="http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fmanagement.azure.com%2F"

if [ -n "${HOST_IDENTITY_CLIENT_ID}" ]; then
    ENCODED_CLIENT_ID="$(jq -rn \
        --arg value "${HOST_IDENTITY_CLIENT_ID}" \
        '$value|@uri')"
    TOKEN_URL="${TOKEN_URL}&client_id=${ENCODED_CLIENT_ID}"
fi

TOKEN="$(curl --fail --silent --show-error \
    --header Metadata:true \
    "${TOKEN_URL}" |
    jq -r '.access_token // empty')"

test -n "${TOKEN}"

AKS_ARM_HTTP="$(curl --silent --show-error \
    --output /dev/null \
    --write-out '%{http_code}' \
    --header "Authorization: Bearer ${TOKEN}" \
    "https://management.azure.com${AKS_RESOURCE_ID}?api-version=2025-07-01")"

unset TOKEN
printf 'AKS_ARM_HTTP=%s\n' "${AKS_ARM_HTTP}"

Output yang diharapkan: AKS_ARM_HTTP=200. Untuk identitas yang ditetapkan pengguna, permintaan menggunakan HOST_IDENTITY_CLIENT_ID yang sama yang diteruskan oleh alur kerja lampiran ke --msi-client-id. Jalankan exit untuk meninggalkan sesi VM Azure.

Alur kerja lampiran melakukan pemeriksaan end-to-end akhir saat host menggunakan identitas yang dipilih untuk mendaftarkan sumber daya Azure Machine-nya.

Langkah selanjutnya

Selanjutnya, lampirkan dan verifikasi host yang disiapkan sebagai node flex.