将映像从 Azure 容器注册表拉取到 Kubernetes 群集Pull images from an Azure container registry to a Kubernetes cluster

你可以将 Azure 容器注册表用作容器映像的来源,并将其用于任何 Kubernetes 群集,包括“本地”Kubernetes 群集,例如 minikubekindYou can use an Azure container registry as a source of container images with any Kubernetes cluster, including "local" Kubernetes clusters such as minikube and kind. 本文展示了如何基于 Azure Active Directory 服务主体创建 Kubernetes 拉取机密。This article shows how to create a Kubernetes pull secret based on an Azure Active Directory service principal. 然后,在 Kubernetes 部署中使用该机密从 Azure 容器注册表中拉取映像。Then, use the secret to pull images from an Azure container registry in a Kubernetes deployment.

提示

如果你使用托管 Azure Kubernetes 服务,则还可以将群集与目标 Azure 容器注册表集成以用于映像拉取。If you're using the managed Azure Kubernetes Service, you can also integrate your cluster with a target Azure container registry for image pulls.

本文假设你已创建了一个专用 Azure 容器注册表。This article assumes you already created a private Azure container registry. 你还需要确保 Kubernetes 群集正在运行并可通过 kubectl 命令行工具访问。You also need to have a Kubernetes cluster running and accessible via the kubectl command-line tool.

创建服务主体Create a service principal

若要创建可以访问容器注册表的服务主体,请在本地安装的 Azure CLI 中运行以下脚本。To create a service principal with access to your container registry, run the following script in a local installation of the Azure CLI. 此脚本已针对 Bash Shell 格式化。The script is formatted for the Bash shell.

运行脚本之前,请将 ACR_NAME 变量更新为容器注册表的名称。Before running the script, update the ACR_NAME variable with the name of your container registry. SERVICE_PRINCIPAL_NAME 值必须在 Azure Active Directory 租户中唯一。The SERVICE_PRINCIPAL_NAME value must be unique within your Azure Active Directory tenant. 如果收到“'http://acr-service-principal' already exists.”错误,请为服务主体指定另一名称。If you receive an "'http://acr-service-principal' already exists." error, specify a different name for the service principal.

如果需要授予其他权限,可以选择修改 az ad sp create-for-rbac 命令中的 --role 值。You can optionally modify the --role value in the az ad sp create-for-rbac command if you want to grant different permissions.

运行脚本后,请记下服务主体的 ID密码After you run the script, take note of the service principal's ID and password. 获得其凭据后,可以配置应用程序和服务使其作为服务主体对容器注册表进行身份验证。Once you have its credentials, you can configure your applications and services to authenticate to your container registry as the service principal.

#!/bin/bash

# Modify for your environment.
# ACR_NAME: The name of your Azure Container Registry
# SERVICE_PRINCIPAL_NAME: Must be unique within your AD tenant
ACR_NAME=<container-registry-name>
SERVICE_PRINCIPAL_NAME=acr-service-principal

# Obtain the full registry ID for subsequent command args
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)

# Create the service principal with rights scoped to the registry.
# Default permissions are for docker pull access. Modify the '--role'
# argument value as desired:
# reader:      pull only
# contributor: push and pull
# owner:       push, pull, and assign roles
SP_PASSWD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role reader --query password --output tsv)
SP_APP_ID=$(az ad sp show --id http://$SERVICE_PRINCIPAL_NAME --query appId --output tsv)

# Output the service principal's credentials; use these in your services and
# applications to authenticate to the container registry.
echo "Service principal ID: $SP_APP_ID"
echo "Service principal password: $SP_PASSWD"

使用现有的服务主体Use an existing service principal

若要向现有服务主体授予注册表访问权限,必须为服务主体分配新角色。To grant registry access to an existing service principal, you must assign a new role to the service principal. 与创建新的服务主体一样,可以授予“拉取”、“推送和拉取”以及“所有者”访问权限。As with creating a new service principal, you can grant pull, push and pull, and owner access.

以下脚本使用 az role assignment create 命令向 SERVICE_PRINCIPAL_ID 变量中指定的服务主体授予“拉取”权限。The following script uses the az role assignment create command to grant pull permissions to a service principal you specify in the SERVICE_PRINCIPAL_ID variable. 如果要授予不同的访问级别,请调整 --role 值。Adjust the --role value if you'd like to grant a different level of access.

#!/bin/bash

# Modify for your environment. The ACR_NAME is the name of your Azure Container
# Registry, and the SERVICE_PRINCIPAL_ID is the service principal's 'appId' or
# one of its 'servicePrincipalNames' values.
ACR_NAME=mycontainerregistry
SERVICE_PRINCIPAL_ID=<service-principal-ID>

# Populate value required for subsequent command args
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)

# Assign the desired role to the service principal. Modify the '--role' argument
# value as desired:
# reader:      pull only
# contributor: push and pull
# owner:       push, pull, and assign roles
az role assignment create --assignee $SERVICE_PRINCIPAL_ID --scope $ACR_REGISTRY_ID --role reader

如果你未保存或记住服务主体密码,则可以使用 az ad sp credential reset 命令重置密码:If you don't save or remember the service principal password, you can reset it with the az ad sp credential reset command:

az ad sp credential reset  --name http://<service-principal-name> --query password --output tsv

此命令为你的服务主体返回一个新的有效密码。This command returns a new, valid password for your service principal.

创建映像拉取机密Create an image pull secret

Kubernetes 使用“映像拉取机密” 来存储向注册表证明身份所需的信息。Kubernetes uses an image pull secret to store information needed to authenticate to your registry. 若要为 Azure 容器注册表创建拉取机密,请提供服务主体 ID、密码和注册表 URL。To create the pull secret for an Azure container registry, you provide the service principal ID, password, and the registry URL.

使用以下 kubectl 命令创建映像拉取机密:Create an image pull secret with the following kubectl command:

kubectl create secret docker-registry <secret-name> \
    --namespace <namespace> \
    --docker-server=<container-registry-name>.azurecr.cn \
    --docker-username=<service-principal-ID> \
    --docker-password=<service-principal-password>

其中:where:

Value 说明Description
secret-name 映像拉取机密的名称,例如 acr-secretName of the image pull secret, for example, acr-secret
namespace 用来放置机密的 Kubernetes 命名空间Kubernetes namespace to put the secret into
仅当要将机密置于默认命名空间之外的命名空间中时才需要此项Only needed if you want to place the secret in a namespace other than the default namespace
container-registry-name Azure 容器注册表的名称,例如 myregistryName of your Azure container registry, for example, myregistry

--docker-server 是注册表登录服务器的完全限定名称The --docker-server is the fully qualified name of the registry login server
service-principal-ID Kubernetes 用来访问注册表的服务主体的 IDID of the service principal that will be used by Kubernetes to access your registry
service-principal-password 服务主体密码Service principal password

使用映像拉取机密Use the image pull secret

创建映像拉取机密后,可以使用它来创建 Kubernetes Pod 和部署。Once you've created the image pull secret, you can use it to create Kubernetes pods and deployments. 在部署文件中,在 imagePullSecrets 下提供机密名称。Provide the name of the secret under imagePullSecrets in the deployment file. 例如:For example:

apiVersion: v1
kind: Pod
metadata:
  name: my-awesome-app-pod
  namespace: awesomeapps
spec:
  containers:
    - name: main-app-container
      image: myregistry.azurecr.cn/my-awesome-app:v1
      imagePullPolicy: IfNotPresent
  imagePullSecrets:
    - name: acr-secret

在前面的示例中,my-awesome-app:v1 是要从 Azure 容器注册表中拉取的映像的名称,acr-secret 是你创建的用于访问注册表的拉取密钥的名称。In the preceding example, my-awesome-app:v1 is the name of the image to pull from the Azure container registry, and acr-secret is the name of the pull secret you created to access the registry. 部署 Pod 时,如果群集上尚无映像,则 Kubernetes 会自动从注册表中拉取映像。When you deploy the pod, Kubernetes automatically pulls the image from your registry, if it is not already present on the cluster.

后续步骤Next steps