在Azure Kubernetes 服务 (AKS)（预览版）中创建和管理准备的图像规范（PIS）

预备映像规范（PIS）让您能够定义预先配置的节点映像，其中包含您所需的容器映像和自定义配置。 AKS 生成一次准备好的映像，并在节点预配期间重复使用它，从而减少后续缩放操作的启动时间。有关准备图像规范的工作原理以及何时使用它的详细信息，请参阅 AKS 中的准备图像规范（预览版）。

本文介绍如何在 AKS 中创建和管理 PIS。

Important

AKS 预览功能可在自助服务和自愿选择的基础上启用。预览版按“现状”和“视供应情况”提供，它们不包括在服务级别协议和有限保证范围内。 AKS 预览功能是由客户支持尽最大努力部分覆盖。因此，这些功能并不适合用于生产。有关详细信息，请参阅以下支持文章：

先决条件

运行受支持的 Kubernetes 版本的现有 AKS 群集。如果还没有群集，请参阅创建 AKS 群集。
Azure CLI 2.85.0 或更高版本。运行 az --version 即可查找版本。如果需要进行安装或升级，请参阅安装 Azure CLI。
需要适当的Azure RBAC 权限才能在资源组中创建和管理 AKS 资源。
容器映像必须可从 AKS 群集访问。如果使用 Azure 容器注册表（ACR），请确保它与 AKS 群集集成。
aks-preview CLI 扩展版本 21.0.0b5 或更高版本。如果没有它，请参阅安装 aks-preview CLI 扩展。
在您的订阅中注册的 AKSPreparedImageSpecificationPreview 功能标志。如果尚未注册该功能，请参阅 “注册 AKSPreparedImageSpecificationPreview 功能标志”。

局限性

预览期间存在以下限制：

可在 Azure 公共区域中使用，但不包括主权云和物理隔离环境。
支持的操作系统包括 Ubuntu、Azure Linux 和 Windows。
自定义脚本可能会导致映像生成或纵向扩展失败。
修改现有规范时，可能需要重新创建这些规范。

安装 `aks-preview` CLI 扩展

如果尚未安装 aks-preview CLI 扩展，请使用 az extension add 命令进行安装。

az extension add --name aks-preview

如果已安装扩展，请使用命令将其更新到最新版本 az extension update 。

az extension update --name aks-preview

注册 `AKSPreparedImageSpecificationPreview` 功能标志

使用 AKSPreparedImageSpecificationPreview 命令在订阅中注册 az feature register 功能标志。

az feature register \
  --namespace Microsoft.ContainerService \
  --name AKSPreparedImageSpecificationPreview

使用 az feature show 命令验证注册状态。

az feature show \
  --namespace Microsoft.ContainerService \
  --name AKSPreparedImageSpecificationPreview

注册功能标志后，使用 az provider register 命令刷新 Microsoft.ContainerService 资源提供程序的注册。
```
az provider register --namespace Microsoft.ContainerService
```

创建预备映像规范（PIS）

创建基本预配映像规范

使用 az aks prepared-image-specification create 命令创建 PIS。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
PIS_NAME=<your-pis-name>
LOCATION=<location>
PIS_VERSION=v1

# Create a basic Prepared Image Specification
az aks prepared-image-specification create \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME \
    --version $PIS_VERSION \
    --location $LOCATION

使用缓存映像创建已准备映像规范

使用 az aks prepared-image-specification create 命令创建一个预缓存容器映像的 PIS。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
PIS_NAME=<your-pis-name>
LOCATION=<location>
PIS_VERSION=v1

# Create a Prepared Image Specification with cached images
az aks prepared-image-specification create \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME \
    --version $PIS_VERSION \
    --container-images \
        myacr.azurecr.cn/model-server:v1 \
        myacr.azurecr.cn/inference:v1

使用自定义脚本创建准备的图像规范

使用 az aks prepared-image-specification create 命令创建一个在映像构建期间运行自定义脚本的 PIS。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
PIS_NAME=<your-pis-name>
LOCATION=<location>
PIS_VERSION=v1

# Create a Prepared Image Specification using custom scripts
az aks prepared-image-specification create \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME \
    --version $PIS_VERSION \
    --customization-scripts @scripts.json

使用已准备映像规范创建群集或节点池

创建 PIS 后，可以在创建或更新群集或节点池时引用它。您需要已准备好的映像版本的资源 ID。

使用 PIS 创建群集

使用 az aks prepared-image-specification version show 命令获取 PIS 版本资源 ID。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>
PIS_VERSION=v1

# Get the PIS version resource ID
PIS_VERSION_ID=$(az aks prepared-image-specification version show \
    --resource-group $RESOURCE_GROUP \
    --pis-name $PIS_NAME \
    --name $PIS_VERSION \
    --query id -o tsv)

使用 az aks create 命令并带上 --prepared-image-specification-id 参数，创建一个引用准备好的映像的新 AKS 群集。

# Set environment variables
CLUSTER_NAME=<your-aks-cluster-name>

# Create a new AKS cluster using the prepared image
az aks create \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --prepared-image-specification-id $PIS_VERSION_ID \
    --generate-ssh-keys

使用 PIS 创建节点池

使用 az aks prepared-image-specification version show 命令获取 PIS 版本资源 ID。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>
PIS_VERSION=v1

# Get the PIS version resource ID
PIS_VERSION_ID=$(az aks prepared-image-specification version show \
    --resource-group $RESOURCE_GROUP \
    --pis-name $PIS_NAME \
    --name $PIS_VERSION \
    --query id -o tsv)

使用带有 az aks nodepool add 参数的 --prepared-image-specification-id 命令，创建一个引用已准备好的映像的新节点池。

# Set environment variables
CLUSTER_NAME=<your-aks-cluster-name>

# Create a new node pool using the prepared image
az aks nodepool add \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --name userpool \
    --prepared-image-specification-id $PIS_VERSION_ID

使用 az aks nodepool show 命令验证节点池是否正在使用 PIS。

az aks nodepool show \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --name userpool \
    --query "{state:provisioningState, pisId:preparedImageSpecificationId}"

管理预备映像规范

已准备好的图像规格列表

使用 az aks prepared-image-specification list 命令列出资源组中的所有已准备图像规范。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>

# List all Prepared Image Specifications in the resource group
az aks prepared-image-specification list --resource-group $RESOURCE_GROUP

显示特定的预备镜像规范

使用 az aks prepared-image-specification show 命令获取特定准备图像规范的详细信息。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>

# Show the details of the Prepared Image Specification
az aks prepared-image-specification show \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME

更新准备的图像规范元数据

有两个资源概念： PIS 资源和PIS 版本。更新 PIS 元数据（如标记）会更新 PIS 资源，并且不会更改引用版本的映像/脚本。若要更改容器映像或脚本，应创建新的 PIS 版本，并更新节点池以引用该 PIS 版本 ID。

可以使用 az aks prepared-image-specification update 命令更新现有的 Prepared Image Specification 的元数据，例如标签。若要更改容器映像或脚本，请改为创建新的版本。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>

# Update the Prepared Image Specification metadata
az aks prepared-image-specification update \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME \
    --tags environment=prod

列出已准备映像规范的所有版本

使用 az aks prepared-image-specification version list 命令列出已准备映像规范的所有版本。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>

# List all versions of the Prepared Image Specification
az aks prepared-image-specification version list \
    --resource-group $RESOURCE_GROUP \
    --pis-name $PIS_NAME

显示预备映像规范的特定版本

使用 az aks prepared-image-specification version show 命令并将 --name 参数设置为 PIS 版本，以获取特定版本的详细信息。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>
PIS_VERSION=v1

# Show the details of the specific version of the Prepared Image Specification
az aks prepared-image-specification version show \
    --resource-group $RESOURCE_GROUP \
    --pis-name $PIS_NAME \
    --name $PIS_VERSION

列出使用特定预配置映像规范的节点池

若要查找引用已准备映像规范的群集中的所有节点池，请使用 az aks nodepool list 带有 JMESPath 筛选器的命令。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>

# List all node pools in the cluster that reference a Prepared Image Specification
az aks nodepool list \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --query "[?preparedImageSpecificationId != null]"

升级预备映像规范版本

当基础映像、依赖项或自定义项发生更改时，请创建新的版本并更新节点池以引用它。建议的工作流为：

使用更新的容器映像或脚本创建新版本。
在非生产节点池中验证新版本。

更新生产节点池以引用新版本。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
NEW_PIS_VERSION_ID=<new-pis-version-resource-id>

# Update a node pool to reference a new PIS version using the `az aks nodepool update` command
az aks nodepool update \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --name userpool \
    --prepared-image-specification-id $NEW_PIS_VERSION_ID

清理未使用的映像以优化成本。

AKS 版本升级

升级 Kubernetes 版本时，AKS 会自动为引用的 PIS 版本重新生成准备好的 VHD。无需为 Kubernetes 版本升级创建新的 PIS 版本。当 PIS 内容（如容器映像或脚本）发生更改时，应创建新的 PIS 版本。

使用 az aks get-upgrades 命令检查是否有可用的升级。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
    
# Check for available upgrades
az aks get-upgrades \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME

使用 az aks upgrade 命令升级群集。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
KUBERNETES_VERSION=<new-kubernetes-version>
    
# Upgrade the cluster to the new Kubernetes version
az aks upgrade \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --kubernetes-version $KUBERNETES_VERSION

Important

在升级生产节点池之前，创建并验证面向新的 Kubernetes 和节点映像版本的新的准备映像规范版本。

使用 az aks nodepool upgrade 命令升级特定节点池。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
NODE_POOL_NAME=<your-node-pool-name>

# Upgrade the node pool to the new Kubernetes version
az aks nodepool upgrade \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --name $NODE_POOL_NAME

从节点池中删除预构建映像规范

若要停止对节点池使用“已准备映像规范”，请使用 az aks nodepool update 命令更新节点池，并将 --prepared-image-specification-id 参数设为空字符串。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>

# Remove the Prepared Image Specification from the node pool
az aks nodepool update \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME \
  --name userpool \
  --prepared-image-specification-id ""

删除预准备映像规范版本

使用 az aks prepared-image-specification version delete 命令删除特定版本。

Important

请勿删除节点池引用的 PIS 版本。相反，应更新节点池以删除 PIS 或引用另一个 PIS 版本。删除引用的版本可能会阻止 AKS 成功重新生成或滚动准备好的映像。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>
PIS_VERSION=<your-pis-version>

# Delete the specific version of the Prepared Image Specification
az aks prepared-image-specification version delete \
    --resource-group $RESOURCE_GROUP \
    --pis-name $PIS_NAME \
    --name $PIS_VERSION

删除已准备的图像规范

使用 az aks prepared-image-specification delete 命令删除整个预备映像规范资源。

Important

在删除 PIS 资源之前，请确保没有任何节点池引用其任何版本。如果找到任何引用，请在删除 PIS 资源之前删除或更新它们。删除被引用的 PIS 可能导致 AKS 无法成功重新构建或滚动更新已准备好的映像。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>

# Delete the Prepared Image Specification
az aks prepared-image-specification delete \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME

监控 Prepared Image Specification 的性能

若要评估 PIS 是否正在减少环境中的预配延迟，请监视以下指标：

节点预配持续时间和就绪时间：与不使用已准备映像的节点进行比较。
横向扩展完成时间：从自动缩放程序触发器到处于就绪状态的节点的时间。
映像生成持续时间和生成成功率：跟踪映像准备管道的运行状况。
Pod 启动时间和容器映像拉取持续时间：验证映像预缓存是否有效使用。

预配映像规范故障排除

与 PIS 相关的错误应包括失败原因，许多失败可能来自自定义脚本。如果在添加 PIS 后节点池创建或纵向扩展失败，则应检查映像生成/自定义脚本日志，并在创建新版本或更新节点池引用之前验证脚本。

映像创建失败

注释

当自定义脚本在映像生成期间失败时，AKS 会解除分配生成 VM，而不是将其删除，以便客户可以启动和调试。在后续的 PIS 重新构建过程中，AKS 会删除并重新创建虚拟机规模集和构建资源。

如果 PIS 无法构建已准备好的映像，请检查以下内容：

无效或格式不正确的自定义脚本。
容器注册表身份验证失败 - 验证 AKS 群集是否具有对指定注册表的拉取访问权限。
缺少对资源组或注册表的 Azure RBAC 权限。
目标操作系统不支持的自定义类型。

节点池创建失败

如果引用 PIS 的节点池无法创建，请验证：

PIS 版本 ID 有效，版本存在于同一区域中。
您的订阅有足够的配额来满足所请求的 VM SKU。
所请求的 VM SKU 受已准备的映像支持。
该区域在预览期间支持 PIS 功能。

缩放操作并不会更快

如果未看到预配时间减少，请验证：

您要加速的容器映像已包含在 PIS 版本中。
节点池引用正确的版本。
新节点正从预先准备好的映像启动，而不是从基础 AKS 节点映像启动。
瓶颈是容器映像拉取时间，而不是工作负荷启动或其他初始化。

清理资源

如果出于测试目的在本文中创建资源，请在完成后将其删除，以避免持续产生费用。这包括 PIS 版本、PIS 资源、测试节点池和测试 AKS 群集。

若要删除资源组及其中的所有资源，请使用 az group delete 命令。

# Set environment variables
RESOURCE_GROUP=<your-resource-group>

# Delete the resource group and all resources in it
az group delete \
    --name $RESOURCE_GROUP \
    --yes \
    --no-wait

若要了解有关准备图像规范的详细信息，请参阅 AKS 中的准备图像规范（预览版）。

Last updated on 2026-08-14

在Azure Kubernetes 服务 (AKS)（预览版）中创建和管理准备的图像规范（PIS）

先决条件

局限性

安装 aks-preview CLI 扩展

注册 AKSPreparedImageSpecificationPreview 功能标志

创建预备映像规范（PIS）

创建基本预配映像规范

使用缓存映像创建已准备映像规范

使用自定义脚本创建准备的图像规范

使用已准备映像规范创建群集或节点池

使用 PIS 创建群集

使用 PIS 创建节点池

管理预备映像规范

已准备好的图像规格列表

显示特定的预备镜像规范

更新准备的图像规范元数据

列出已准备映像规范的所有版本

显示预备映像规范的特定版本

列出使用特定预配置映像规范的节点池

升级预备映像规范版本

AKS 版本升级

从节点池中删除预构建映像规范

删除预准备映像规范版本

删除已准备的图像规范

监控 Prepared Image Specification 的性能

预配映像规范故障排除

映像创建失败

节点池创建失败

缩放操作并不会更快

清理资源

相关内容

其他资源

安装 `aks-preview` CLI 扩展

注册 `AKSPreparedImageSpecificationPreview` 功能标志