概述

本文档提供了在 Kubernetes 集群中部署阿里云容器镜像服务(ACR)凭证助手组件的详细步骤。该组件用于自动管理ACR私有镜像仓库的访问凭证。

前提条件

1. 已安装并配置好 Kubernetes 集群 (v1.16+)
2. 已安装 kubectl 命令行工具
3. 集群有足够的权限创建 ClusterRole 和 ClusterRoleBinding
4. 已准备好阿里云ACR实例的访问凭证

部署步骤

1. 获取部署脚本

将脚本保存为 deploy-acr-helper.sh 文件，并赋予脚本执行权限：

# 脚本源码详见附录
chmod +x deploy-acr-helper.sh

2. 执行部署

使用默认配置部署

./deploy-acr-helper.sh

使用自定义配置部署

export INSTANCE_ID="your-instance-id"
export REGION_ID="your-region-id"
export ACCESS_KEY="your-access-key"
export ACCESS_SECRET="your-access-secret"
export IMAGE="your-custom-image"
./deploy-acr-helper.sh

验证部署

检查所有组件是否正常运行：

# 检查 ConfigMap
kubectl -n kube-system get cm acr-configuration

# 检查 ServiceAccount
kubectl -n kube-system get sa aliyun-acr-credential-helper

# 检查 ClusterRole
kubectl get clusterrole aliyun-acr-credential-helper

# 检查 Deployment
kubectl -n kube-system get deployment aliyun-acr-credential-helper

# 检查 Pod 状态
kubectl -n kube-system get pods -l app=aliyun-acr-credential-helper

# 检查 Service
kubectl -n kube-system get svc aliyun-acr-credential-helper

# 检查 Webhook 配置
kubectl get mutatingwebhookconfiguration acr-credential-webhook

自定义配置

敏感信息配置

建议通过环境变量传入敏感信息，而不是直接修改脚本：

export INSTANCE_ID="your-new-instance-id"
export REGION_ID="your-new-region"
export ACCESS_KEY="your-new-access-key"
export ACCESS_SECRET="your-new-secret"
./deploy-acr-helper.sh

镜像版本配置

要使用不同版本的镜像：

export IMAGE="registry.cn-hangzhou.aliyuncs.com/acs/aliyun-acr-credential-helper:new-version"
./deploy-acr-helper.sh

故障排查

常见问题

1. 凭证无效

• • 检查 ACCESS_KEY 和 ACCESS_SECRET 是否正确
  • 验证凭证是否有访问ACR的权限

1. Webhook 无法访问

• • 检查 Service 是否正常运行
  • 验证网络策略是否允许流量
  • 检查证书配置是否正确

1. Pod 无法启动

• • 检查镜像拉取权限
  • 验证节点是否有足够资源

查看日志

# 查看 Pod 日志
kubectl -n kube-system logs -l app=aliyun-acr-credential-helper

卸载步骤

如需卸载组件：

# 删除 Webhook 配置
kubectl delete mutatingwebhookconfiguration acr-credential-webhook

# 删除 Service
kubectl -n kube-system delete svc aliyun-acr-credential-helper

# 删除 Deployment
kubectl -n kube-system delete deployment aliyun-acr-credential-helper

# 删除权限配置
kubectl delete clusterrolebinding aliyun-acr-credential-helper
kubectl delete clusterrole aliyun-acr-credential-helper

# 删除 ServiceAccount
kubectl -n kube-system delete sa aliyun-acr-credential-helper

# 删除 ConfigMap
kubectl -n kube-system delete cm acr-configuration

附录：脚本源码

#!/bin/bash

# 设置敏感信息变量（建议通过环境变量或密钥管理工具传入）
INSTANCE_ID=${INSTANCE_ID:-"cri-xxxx"}
REGION_ID=${REGION_ID:-"ap-southeast-1"}
ACCESS_KEY=${ACCESS_KEY:-"xxxxx"}
ACCESS_SECRET=${ACCESS_SECRET:-"xxxx"}
IMAGE=${IMAGE:-"registry.cn-hangzhou.aliyuncs.com/acs/aliyun-acr-credential-helper:v23.02.06.2-74e2172-aliyun"}

echo "Deploying Aliyun ACR Credential Helper with following configuration:"
echo "Instance ID: $INSTANCE_ID"
echo "Region ID: $REGION_ID"
echo "Image: $IMAGE"

# 1. 创建 ConfigMap
echo "Creating ConfigMap..."
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: acr-configuration
  namespace: kube-system
data:
    acr-api-version: "2018-12-01"
    acr-registry-info: |
      - instanceId: "$INSTANCE_ID"
        regionId: "$REGION_ID"
        customAccessKey: "$ACCESS_KEY"
        customAccessKeySecret: "$ACCESS_SECRET"
    watch-namespace: "all"
    service-account: "*"
    expiring-threshold: "15m"
EOF

# 2. 创建 ServiceAccount
echo "Creating ServiceAccount..."
kubectl apply -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: aliyun-acr-credential-helper
  namespace: kube-system
EOF

# 3. 创建 ClusterRole
echo "Creating ClusterRole..."
kubectl apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: aliyun-acr-credential-helper
rules:
  - apiGroups:
      - ""
    resources:
      - namespaces
      - configmaps
      - pods
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - ""
    resources:
      - serviceaccounts
      - secrets
      - events
    verbs:
      - create
      - update
      - patch
      - get
      - list
      - watch
  - apiGroups:
      - admissionregistration.k8s.io
    resources:
      - validatingwebhookconfigurations
      - mutatingwebhookconfigurations
    verbs:
      - get
      - list
      - update
      - create
      - delete
EOF

# 4. 创建 ClusterRoleBinding
echo "Creating ClusterRoleBinding..."
kubectl apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: aliyun-acr-credential-helper
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: aliyun-acr-credential-helper
subjects:
  - kind: ServiceAccount
    name: aliyun-acr-credential-helper
    namespace: kube-system
EOF

# 5. 创建 Deployment
echo "Creating Deployment..."
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: aliyun-acr-credential-helper
  name: aliyun-acr-credential-helper
  namespace: kube-system
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: aliyun-acr-credential-helper
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: aliyun-acr-credential-helper
    spec:
      affinity:
        nodeAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - preference:
              matchExpressions:
              - key: k8s.aliyun.com
                operator: NotIn
                values:
                - "true"
            weight: 1
      containers:
      - env:
        - name: POD_NAME
          valueFrom:
            fieldRef:
              apiVersion: v1
              fieldPath: metadata.name
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              apiVersion: v1
              fieldPath: metadata.namespace
        - name: REGION_ID
          value: $REGION_ID
        image: $IMAGE
        imagePullPolicy: Always
        livenessProbe:
          exec:
            command:
            - sh
            - -c
            - ps -ef | grep aliyun-acr-credential-helper | grep -v grep
          failureThreshold: 3
          initialDelaySeconds: 10
          periodSeconds: 30
          successThreshold: 1
          timeoutSeconds: 1
        name: aliyun-acr-credential-helper
        ports:
        - containerPort: 8900
          protocol: TCP
        - containerPort: 7443
          protocol: TCP
        readinessProbe:
          exec:
            command:
            - sh
            - -c
            - ps -ef | grep aliyun-acr-credential-helper | grep -v grep
          failureThreshold: 3
          initialDelaySeconds: 5
          periodSeconds: 10
          successThreshold: 1
          timeoutSeconds: 1
        resources:
          limits:
            cpu: 500m
            memory: 500Mi
          requests:
            cpu: 50m
            memory: 50Mi
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          runAsUser: 1000
          seccompProfile:
            type: RuntimeDefault
        terminationMessagePath: /dev/termination-log
        terminationMessagePolicy: File
        volumeMounts:
        - mountPath: /var/addon
          name: addon-token
          readOnly: true
        - mountPath: /var/run/secrets/tokens
          name: oidc-token
      dnsPolicy: ClusterFirst
      nodeSelector:
        beta.kubernetes.io/os: linux
      priorityClassName: system-cluster-critical
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      serviceAccount: aliyun-acr-credential-helper
      serviceAccountName: aliyun-acr-credential-helper
      terminationGracePeriodSeconds: 30
      volumes:
      - name: addon-token
        secret:
          defaultMode: 420
          items:
          - key: addon.token.config
            path: token-config
          optional: true
          secretName: addon.aliyuncsmanagedacrrole.token
      - name: oidc-token
        projected:
          defaultMode: 420
          sources:
          - serviceAccountToken:
              audience: sts.aliyuncs.com
              expirationSeconds: 7200
              path: oidc-token
EOF

# 6. 创建 Service
echo "Creating Service..."
kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  name: aliyun-acr-credential-helper
  labels:
    app: aliyun-acr-credential-helper
  namespace: kube-system
spec:
  ports:
    - port: 7443
      targetPort: 7443
  selector:
    app: aliyun-acr-credential-helper
EOF

# 7. 创建 MutatingWebhookConfiguration
echo "Creating MutatingWebhookConfiguration..."
kubectl apply -f - <<EOF
apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
  name: acr-credential-webhook
  namespace: kube-system
webhooks:
- name: acr.credential.mutate
  rules:
  - apiGroups: ["apps", ""]
    apiVersions: ["v1"]
    operations: ["CREATE"]
    resources: ["serviceaccounts"]
  clientConfig:
    service:
      namespace: kube-system
      name: aliyun-acr-credential-helper
      path: "/patch"
      port: 7433
    caBundle: LQo=
  admissionReviewVersions: ["v1"]
  sideEffects: None
  failurePolicy: Ignore
  timeoutSeconds: 10
EOF

echo "Aliyun ACR Credential Helper deployment completed!"