Kubernetes deployment issues

Public access configuration

When using the public build cluster, the Kubernetes API Server must have public access enabled.

For Container Service for Kubernetes (ACK) clusters:

1. Enable public access for the ACK API Server and bind an elastic IP address (EIP). The recommended initial EIP bandwidth is 5 Mbit/s or higher.

2. When creating a Service Connection in Flow, select the public network access method.

3. In the ACK security group or ACL settings, add the egress IP addresses of the public build cluster to the allowlist.

Private access configuration

When using a private build cluster or communicating over a VPC internal network:

1. Ensure that the build nodes and the Kubernetes cluster are in the same VPC.

2. Use the private network kubeconfig when configuring the Service Connection in Flow.

General i/o timeout troubleshooting

If the deployment fails with i/o timeout or auth failed, verify the following:

1. The Kubernetes API Server has public access enabled.

2. The EIP bound to the API Server is valid and has sufficient bandwidth.

3. The security group or ACL rules allow inbound traffic from the build cluster egress IP addresses.

4. The network connectivity between the build region and the target cluster region is working correctly.

Version matching rule

The kubectl client version should match the Kubernetes cluster control plane version, or differ by no more than one minor version. For example, if your cluster is running v1.34, you can use kubectl v1.33 or v1.34.

Handling version mismatches

The current maximum kubectl version available in Flow is v1.27.9. If your cluster version is higher than the available kubectl versions, select the highest available version (v1.27.9). In most cases, this is sufficient for compatibility.

If the deployment fails with errors such as object has been modified or resource updates fail after selecting the highest available version:

1. Select v1.27.9 (the highest available version) in the KubectlApply step configuration.

2. Remove the resourceVersion and uid fields from the metadata section of your YAML files, as these fields can cause conflicts when re-applying existing resources.

Manually specifying the kubectl version

In the KubectlApply step configuration, you can manually specify the kubectl version to match your cluster version. The following kubectl versions are currently supported:

v1.27.9 (default), v1.26.12, v1.25.16, v1.24.17, v1.23.6, v1.22.9, v1.21.12, v1.20.1, v1.19.1, v1.18.4, v1.17.4, v1.16.4, v1.15.5, v1.14.0, v1.13.0, v1.12.0, v1.11.0

No release resource found

Problem: The deployment fails with an error indicating that no release resource was found.

Solution: Check the PATH_TO_YAML parameter in the KubectlApply step. This parameter specifies the path to the Kubernetes manifest file or directory, relative to the code checkout root directory. For example, if your manifest is located at manifests/gateway.yaml in the repository root, set PATH_TO_YAML to manifests/gateway.yaml. Verify that the file exists on the specified branch.

Variable syntax errors

Problem: The deployment fails because variables in the YAML file are undefined or use an unsupported syntax.

Solution: Ensure that variables in your YAML files use the standard ${VAR_NAME} format. Non-standard syntax such as ${REPLICAS:1} causes parsing failures. Define all required variables in the pipeline variable settings before running the deployment.

If you want the deployment to proceed even when the YAML contains undefined variables, enable the Skip template validation option in the KubectlApply step configuration.

Empty content after template processing

Problem: The deployment log shows that the directory is empty after template processing (for example, total 0).

Solution: Check whether variable substitution is causing YAML content to become empty, or whether YAML formatting errors are preventing the file from being parsed correctly. Review the pipeline variable values and ensure the YAML syntax is valid.

IMAGE_URL variable binding

Problem: The IMAGE_URL dropdown is empty when configuring the deployment task.

Solution: Verify that the upstream image build task has completed successfully and generated build artifacts. In the deployment task configuration, add a variable binding to map the image address output from the upstream build task to the IMAGE_URL field. For more information about using variables in YAML files, see The variables that kubectl uses in YAML..

RBAC insufficient permissions

Problem: The deployment fails with an error indicating that the account lacks the required permissions, such as get, list, or update on resources in the target namespace.

Solution:

1. Contact your cluster administrator to grant the service account used in the pipeline at least the view or edit cluster role in the target namespace.

2. Verify that the Namespace field in the KubectlApply step configuration is set correctly. The namespace must exist in the Kubernetes cluster and must match the namespace where the resources are deployed.

Common deployment request failures

If the deployment request fails without an explicit permission error, check the following common causes:

• Ingress associated with multiple Services: An Ingress resource is configured to route to multiple Services, which may cause conflicts. Review the Ingress routing rules.

• LabelSelector mismatch: The selector in the Service does not match the labels defined in the Deployment. Ensure that the labels are consistent between the Service and the Deployment spec.

• Image not updated: The container image tag has not changed since the last deployment. Kubernetes may not restart the pods if the image tag is the same. Use a unique image tag (such as a build number or commit hash) for each release.

• Incorrect container name: The container name in the YAML does not match the expected name. Verify the name field under containers in the Deployment spec.

• Resource quota exceeded: The deployment request exceeds the resource quota (CPU, memory, or pod count) configured for the namespace. Contact your cluster administrator to review and adjust the resource quota.

• Transient service timeout: Occasional timeouts in the underlying infrastructure. Retry the deployment. If the issue persists, contact Apsara DevOps technical support.