Container Service for Kubernetes:Pull images from an ACR Enterprise Edition instance in the same account using the credential-free add-on

Etapa 1: Instalar o add-on

1. Faça login no console ACK. No painel de navegação à esquerda, clique em Clusters.

2. Na página Clusters, clique no nome do seu cluster. No painel de navegação à esquerda, clique em Add-ons .

3. Na página Add-ons, clique na aba Security, localize o cartão aliyun-acr-credential-helper (managed) e clique em Install.

4. Na página Install add-on aliyun-acr-credential-helper, visualize as configurações de AcrInstanceInfo e outras opções. O campo AcrInstanceInfo contém as definições de cada instância do ACR associada ao add-on. As demais opções referem-se às configurações gerais do componente. Caso não precise alterar os namespaces ou ServiceAccounts monitorados, mantenha as configurações padrão.

   Após a instalação, altere as configurações clicando em Configurations no cartão aliyun-acr-credential-helper (managed) dentro da página Add-ons .

   Configurações de associação de instância ACR:

   AcrInstanceInfo		Descrição
   InstanceId		ID da instância do ACR. Obtenha esse ID no console do Container Registry. Importante Deixe este campo em branco para instâncias do ACR Personal Edition. Este campo é obrigatório para instâncias do ACR Enterprise Edition.
   regionId		ID da região onde a instância do ACR está implantada. Obtenha esse ID no console do Container Registry. Importante Este parâmetro é obrigatório para pulls de imagens entre regiões.
   domains		Nomes de domínio usados pelo add-on sem credenciais para acessar a instância do ACR. Por padrão, inclui todos os domínios (internet e VPC) da instância especificada. Para definir múltiplos domínios, separe-os por vírgulas (,).
   Configurações para pull de imagens entre contas Estas configurações aplicam-se a pulls de imagens entre contas. Se não precisar desse recurso, deixe os campos em branco.	assumeRoleARN	Nenhuma configuração é necessária para pulls na mesma conta. Para pulls entre contas, consulte Pull images across accounts.
   	expireDuration
   	rrsaRoleARN
   	rrsaOIDCProviderRoleARN

   Configurações do add-on

   Parâmetro	Descrição
   Enable RRSA	Marque esta caixa para ativar o RRSA. Nenhuma configuração é necessária para pulls na mesma conta. Para pulls entre contas, consulte Pull images across accounts.
   watchNamespace	Namespaces onde deseja habilitar o pull de imagens sem credenciais. O valor padrão édefault. Defina como all para ativar esse recurso em todos os namespaces. Para especificar vários namespaces, separe-os por vírgulas (,). Recomendamos especificar apenas seus namespaces de negócios e evitar o uso de all ou namespaces de componentes do sistema para evitar interrupções nos pulls de imagens do sistema.
   serviceAccount	Define o ServiceAccount ao qual o add-on sem credenciais gerenciado se aplica. O valor padrão é Default. O valor Default aplica o add-on ao ServiceAccount padrão nos namespaces especificados. Se definido como *, o add-on se aplica a todos os ServiceAccounts nos namespaces indicados. Para especificar vários ServiceAccounts, separe-os por vírgula (,).
   expiringThreshold	Limiar de expiração das credenciais no add-on. O valor padrão é15m.
   notifyEmail	Nenhuma configuração necessária.

Etapa 2: Puxar uma imagem

Após instalar e configurar o add-on sem credenciais, especifique um ServiceAccount associado ao add-on ao criar um workload. Isso habilita o pull de imagens sem credenciais.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      serviceAccountName: my-service-account # Specify a ServiceAccount that is associated with the credential-free add-on.
      containers:
      - name: nginx
        image: "******.cn-hangzhou.cr.aliyuncs.com/nginx/nginx:latest" # Specify the ACR image address.
        ports:
        - containerPort: 80

Etapa 1: Instalar o add-on

1. Faça login no console ACK. No painel de navegação à esquerda, clique em Clusters.

2. Na página Clusters, clique no nome do seu cluster. No painel de navegação à esquerda, clique em Add-ons .

3. Na página Add-ons, clique na aba Security, localize o cartão aliyun-acr-credential-helper e clique em Install.

4. Na página Parameters, selecione um modo de permissão na lista suspensa tokenMode e clique em OK. Após a instalação, configure o add-on antes de puxar imagens. Para mais informações, consulte Step 2: Update the add-on configuration (add an ACR instance).

   tokenMode	Descrição
   auto	(Recomendado) O add-on detecta a data de criação do cluster e escolhe automaticamente o modo de permissão. Clusters criados antes de 3 de abril de 2023 usam o modo workerRole. Clusters criados em ou após 3 de abril de 2023 usam o modo managedRole. Importante Versões do aliyun-acr-credential-helper lançadas em ou após 3 de abril de 2023 fornecem um parâmetro que permite personalizar a função RAM da qual o add-on depende. Para mais informações, consulte [Product Change] Announcement on changing the permissions required by the aliyun-acr-credential-helper add-on.
   managedRole	O add-on usa a função AliyunCSManagedAcrRole autorizada em Prerequisites para obter permissões.
   workerRole	O add-on utiliza a função RAM de worker do cluster para obter permissões. Conceda permissões específicas à função RAM de worker. Selecionar workerRole como modo do add-on Se selecionar workerRole como modo de permissão, a função RAM de worker do cluster deve ter as seguintes permissões. Para saber como conceder permissões, consulte Manage RAM role permissions. { "Version": "1", "Statement": [ { "Action": [ "cr:GetAuthorizationToken", "cr:ListInstanceEndpoint", "cr:PullRepository" ], "Resource": "*", "Effect": "Allow" } ] } Importante Selecione este modo se precisar puxar imagens entre contas assumindo uma função.

Etapa 2: Atualizar a configuração do add-on

Depois de instalar o add-on sem credenciais, configure o ConfigMap acr-configuration para adicionar uma instância do ACR antes de puxar imagens. Realize essa tarefa via console ou kubectl.

Etapa 3: Puxar uma imagem

Após instalar e configurar o add-on sem credenciais, especifique um ServiceAccount associado ao add-on ao criar um workload. Isso habilita o pull de imagens sem credenciais.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      serviceAccountName: my-service-account # Specify a ServiceAccount that is associated with the credential-free add-on.
      containers:
      - name: nginx
        image: "******.cn-hangzhou.cr.aliyuncs.com/nginx/nginx:latest" # Specify the ACR image address.
        ports:
        - containerPort: 80

Habilitar uso imediato de ServiceAccounts

Quando ativado, o add-on sem credenciais usa um Webhook para monitorar alterações nos ServiceAccounts do cluster. Ao criar um novo ServiceAccount, o add-on injeta imediatamente o Secret sem credenciais. Isso é útil em cenários onde um ServiceAccount é utilizado logo após sua criação, como quando um Helm Chart cria simultaneamente um ServiceAccount e um Deployment. Esse recurso pode afetar o desempenho do add-on e não é recomendado para uso geral.

data:
  webhook-configuration: |
    enable: true
    failure-policy: Ignore
    timeout-seconds: 10

Solucionar falhas no pull de imagens

Uma causa possível é a configuração incorreta do add-on sem credenciais, por exemplo:

• As informações da instância configuradas no add-on não correspondem à instância do ACR.

• O endereço da imagem usado para o pull não corresponde ao nome de domínio especificado nas informações da instância do add-on.

Siga as etapas deste tópico para solucionar o problema.

Se o add-on estiver configurado corretamente, mas o pull da imagem ainda falhar, pode haver um conflito entre um campo imagePullSecrets especificado manualmente no YAML do workload e o add-on sem credenciais. Para resolver, remova manualmente o campo imagePullSecrets e recrie o Pod.

Como usar imagePullSecrets?

Instâncias do ACR Personal Edition criadas em ou após 9 de setembro de 2024 não suportam o add-on sem credenciais. Para essas instâncias, recomendamos armazenar o nome de usuário e a senha em um Secret e referenciá-lo no campo imagePullSecrets.

kubectl create secret docker-registry image-secret-1 \
  --docker-server=<registry-server> \
  --docker-username=<name> \
  --docker-password=<password> \
  --docker-email=<email>

apiVersion: apps/v1
kind: Deployment 
metadata:
  name: nginx-test
  namespace: default 
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx 
    spec:
      imagePullSecrets:
      - name: image-secret-1  # Use the Secret created in the previous step.
      containers:
      - name: nginx 
        image: <acrID>.cr.aliyuncs.com/<repo>/nginx:latest  # Replace with the ACR image address.