本文为您介绍Kubernetes发布常见
发布使用私有镜像
如果发布到 Kubernetes 集群的镜像是私有的，用户需要在 Kubernetes 集群中进行配置已支持集群能够拉取私有镜像，阿里云Kubernetes用户请参见如何支持私有镜像，其它用户请参考Kubernetes官方文档进行配置。
使用证书创建集群时跳过TLS校验
问题描述：使用证书创建集群时，发布任务失败提示：
error: specifying a root certificates file with the insecure flag is not allowed
解决方案：在部署配置中手动指定“跳过TLS校验”，声明insecure-skip-tls-verify，如下所示：
insecure-skip-tls-verify: true如何解决集群版本不支持extensions/v1beta1?
问题描述：Kubectl发布部署，Kubernetes 集群版本不支持extensions/v1beta1，失败提示：
"no matches for kind "Ingress" in version "extensions/v1beta1"
解决方案：公共示例代码库ingress.yaml文件中配置的Kubernetes集群版本与当前使用的集群版本不匹配，具体解决方案请参考创建并使用Nginx Ingress对外暴露服务更新Ingress.yaml参数值apiVersion: networking.k8s.io/v1。
镜像仓库拉取容器镜像失败如何处理?
问题描述：Kubectl发布，镜像仓库拉取容器镜像失败提示：
容器的事件日志，Error:ImagePullBackOff，Failed to pull image "registry.cn-hangzhou.aliyuncs.com/xxxx/xxxxxx:tag": failed to pull and unpack image "registry.cn-hangzhou.aliyuncs.comxxxx/xxxxxx:tag": failed to resolve reference "registry.cn-hangzhou.aliyuncs.com/xxxx/xxxxxx:tag": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed
解决方案：安装免密组件，创建配置项，详细请参考使用免密组件拉取容器镜像。
云效部署 Kubernetes 集群网络连通性问题
问题描述：云效流水线执行 Kubernetes 部署时，提示 i/o timeout 或 context deadline exceeded，部署任务失败。
原因：构建节点无法访问目标集群 API Server，通常由网络配置不当（未开启公网访问、EIP 未绑定、安全组/ACL 未放行）或白名单限制导致。
解决方案：根据部署架构选择对应排查路径：
公网访问（云效公共构建集群）：在 ACK 控制台开启 API Server 公网访问并绑定 EIP（建议初始带宽 5 Mbps），在服务连接配置中选择公网连接方式，并在安全组及 ACL 白名单中放行云效构建集群出口 IP。
内网访问（专有构建集群或 VPC 内网）：确保构建节点与 ACK 集群在同一 VPC，在服务连接配置中使用内网 kubeconfig 连接集群。
遇到 i/o timeout 时，依次确认：API Server 已开启公网访问、EIP 已有效绑定且带宽充足、安全组/ACL 已放行构建机 IP、构建机与集群所在地域网络连通正常。
Kubectl 版本选择与兼容性
问题描述：流水线 Kubernetes 部署时，出现 object has been modified 报错或资源更新失败；或不清楚应选择哪个 kubectl 版本。
解决方案：kubectl 客户端版本应与集群控制面版本一致或相差不超过 1 个次要版本。在 KubectlApply 部署步骤中通过Kubectl 版本下拉框选择匹配版本，当前平台支持的最高版本为 v1.27.9。若集群版本高于 v1.27.9，建议选择平台最高可用版本。若仍报 object has been modified，请移除 YAML 中的 resourceVersion、uid 等元数据字段后重试。
YAML 路径配置与变量替换问题
问题描述：Kubernetes 部署时提示"没有找到发布的资源"或"未定义变量"。
解决方案：
检查YAML 路径（
PATH_TO_YAML）是否指向代码库中实际存在的 YAML 文件或目录，路径为相对于代码检出根目录的相对路径。避免使用
${REPLICAS:1}等非标准语法，统一改为${VAR_NAME}格式。详细变量使用方式参考kubectl发布在YAML中使用变量。若日志显示模板处理后目录为空（
total 0），请检查变量是否已定义、YAML 格式是否规范。如确认无误仍为空，可勾选跳过模板校验（SKIP_UNDEFINE_VARIABLE）以忽略未替换变量的报错。若部署任务变量配置中镜像地址下拉框为空，请确认上游镜像构建任务已成功运行并生成产物，然后在部署任务中添加变量绑定关联上游输出的镜像地址。
RBAC 权限不足与部署失败排查
问题描述：kubectl 发布时报权限错误（如缺少 get、list、update 权限或提示 auth failed），或部署申请失败。
解决方案：权限不足时，联系集群管理员为执行账号在目标命名空间授予 view 或 edit 角色，并检查部署任务中的命名空间字段与实际目标 namespace 是否一致。
部署申请失败时，还需排查：Ingress 是否关联了多个 Service、Service 的 selector 与 Deployment 的 labels 是否匹配、镜像 tag 是否已更新（或将 imagePullPolicy 设为 Always）、YAML 中容器名称是否正确、namespace 资源配额是否超限。底层服务偶发超时可直接重试发布。
容器启动报错 host.docker.internal 解析失败
问题描述：Nginx 等容器启动时报错 host not found in upstream "host.docker.internal"，容器无法正常启动。
原因：host.docker.internal 是 Docker Desktop（Mac/Windows）特有的宿主机域名，Linux 原生 Docker 环境中不会自动解析。云效构建集群运行于 Linux 环境。
解决方案：若不需要该域名，将 Nginx 配置中的 host.docker.internal 替换为实际服务地址。若必须使用，可在 Docker 启动参数中添加 --add-host host.docker.internal:host-gateway，或在 Docker Compose 中通过 extra_hosts 声明解析地址。