Container Service for Kubernetes:Workload FAQ

How do I deploy a containerized application in an ACK cluster?

Deploying a containerized application involves four phases:

1. Write your application code in any language.

2. Build a container image using a Dockerfile — a text file that packages your code and all its dependencies into a portable delivery artifact. A container image is more complete than traditional packages like JAR, WAR, or RPM files because it bundles the application with every file the container runtime needs. Use that image to start a container, which is the running application. For step-by-step instructions, see Build, package, and run images using a Dockerfile.

3. Push the image to a registry. Container Registry (ACR) stores, manages, distributes, and serves images. ACR offers two editions: For more information, see What is Container Registry ACR.

   • Personal Edition — for individual developers

   • Enterprise Edition — for enterprise customers

4. Deploy workloads in ACK to run your containerized application. ACK manages the full lifecycle of containerized workloads — scheduling pods to specific nodes, scaling on load changes, and more. For more information, see Workloads.

Why do image pulls take too long or fail?

Check the following based on where you're pulling from:

Pulling over the public network

• Verify that your cluster has public network access. See Enable public network access for a cluster.

• Verify that your image registry also allows public access. For an ACR example, see Configure public network access control for ACR.

• Check whether public IP bandwidth is set too low.

Pulling from ACR

• Verify that the image pull secret is correct. See How do I use imagePullSecrets?.

• If using the passwordless pull component, verify that it is configured correctly. See Pull images within the same account and Pull images across accounts.

How do I troubleshoot application issues in ACK?

Application failures typically originate from pods, controllers (Deployment, StatefulSet, DaemonSet), or Services. Start by identifying which layer has the problem, then follow the steps below.

kubectl get endpoints <service_name>

How do I manually update Helm?

Helm v2's Tiller server-side component has known security vulnerabilities that allow attackers to install unauthorized applications in clusters. Upgrade to Helm v3. See Upgrading from Helm v2 to Helm v3.

How do I pull images from a Container Registry Enterprise Edition instance in the Chinese mainland to an ACK cluster outside the Chinese mainland?

Purchase the following Container Registry Enterprise Edition instances:

• Standard or Premium instance in the region inside the Chinese mainland

• Basic instance in the region outside the Chinese mainland

Then use a sync instance to replicate images from the Chinese mainland region to the region outside the Chinese mainland. See Same-account sync instance. After synchronization, retrieve the registry address from the Enterprise Edition instance in the region outside the Chinese mainland and use it when creating applications in ACK.

ACR Personal Edition has slower synchronization speeds. For self-managed repositories, you must purchase Global Acceleration (GA) to speed up image pulls, which increases cost. Container Registry Enterprise Edition is the recommended option. See Billing information.

How do I perform rolling updates without service interruptions?

When replacing pods during a rolling update, a delay of a few seconds occurs before pod changes sync to the Classic Load Balancer (CLB) instance. This can cause temporary 5XX errors. Configure graceful shutdown to achieve zero-downtime rolling updates. See How to implement zero-downtime rolling updates for Kubernetes.

How do I get a container image for a workload?

For prerequisites and guidance on pulling a container image, see Pull image.

How do I restart a container?

Kubernetes does not support restarting individual containers directly. Instead, delete the pod — the controller (Deployment, DaemonSet, etc.) automatically creates a replacement.

1. List pods to find the one to restart:

   kubectl get pods

2. Delete the pod:

   kubectl delete pod <pod-name>

3. Verify the new pod is running:

   kubectl get pods

   Confirm the pod status is Running.

In production, manage containers through higher-level objects like ReplicaSets and Deployments rather than directly manipulating pods. This preserves cluster state consistency.

How do I change the namespace of a Deployment?

Moving a Deployment to a different namespace also requires manually updating dependent resources — persistent volume claims (PVCs), ConfigMaps, and Secrets — to the new namespace.

1. Export the Deployment configuration:

   kubectl get deploy <deployment-name> -n <old-namespace> -o yaml > deployment.yaml

2. Edit deployment.yaml and replace the namespace value:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     annotations:
     generation: 1
     labels:
       app: nginx
     name: nginx-deployment
     namespace: new-namespace # Specify the new namespace.
     ... ...

3. Apply the updated configuration:

   kubectl apply -f deployment.yaml

4. Verify the Deployment is running in the new namespace:

   kubectl get deploy -n new-namespace

How do I expose pod information to running containers?

ACK follows native Kubernetes community specifications. Two methods are supported:

• Environment variables — pass pod information to a container via environment variables. See Expose pod information to containers through environment variables.

• Files — mount pod information as files inside the container using the Downward API volume. See Expose pod information to containers through files.

How to use imagePullSecrets?

ACR Personal Edition instances created on or after September 9, 2024 do not support aliyun-acr-credential-helper. Store your credentials in a Kubernetes Secret and reference it via imagePullSecrets.

Step 1: Create the Secret

kubectl create secret docker-registry image-secret \
  --docker-server=<ACR-registry> \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-email=<email@example.com>

Step 2: Reference the Secret

Choose one of the following methods:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: default
  namespace: default
imagePullSecrets:
- name: image-secret # Enter the ACR Secret

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-test
  namespace: default
  labels:
    app: nginx
spec:
  serviceAccountName: default # If using the default ServiceAccount for the namespace, you do not need to specify it.
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: <acrID>.cr.aliyuncs.com/<repo>/nginx:latest  # Replace with the ACR instance link

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  # Use the Secret created in the previous step
      containers:
      - name: nginx
        image: <acrID>.cr.aliyuncs.com/<repo>/nginx:latest  # Replace with the Registry Address of the ACR repository

Verify

After applying the configuration, confirm the pod is running:

kubectl get pods

Why do pulls still fail after configuring the passwordless component?

The passwordless pull component may be misconfigured. Check for these two common causes:

• The instance information in the component does not match the ACR instance.

• The image address used to pull does not match the domain name configured in the component.

Follow Pull images within the same account to verify the configuration.

If the pull still fails after the configuration is correct, a manually specified imagePullSecrets field in the workload YAML may be conflicting with the passwordless component. Remove the imagePullSecrets field, then delete and recreate the pod.

Why do containers fail to start on new nodes after enabling node pool image acceleration?

After enabling Container Image Acceleration for a node pool, you may see the following error:

failed to create containerd container: failed to attach and mount for snapshot 46: failed to enable target for /sys/kernel/config/target/core/user_99999/dev_46, failed:failed to open remote file as tar file xxxx

This error occurs because Container Image Acceleration requires the aliyun-acr-acceleration-suite component to be installed and pull credentials to be configured for private images. See Configure container image pull credentials.