Kubernetes StatefulSet报错：serviceName环境变量不存在求助

问题现象 #

部署关联Headless Service的StatefulSet后，仅生成一个处于Error状态的Pod，执行kubectl logs时出现报错：

serviceName environment variable doesn't exist! Fix your specification.

提供的配置如下：

Headless Service配置 #

apiVersion: v1
kind: Service
metadata:
  name: svc-hl-xyz
spec:
  clusterIP: None
  selector:
    app: svc-hl-xyz

StatefulSet配置 #

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: sts-xyz
spec:
  replicas: 3
  serviceName: "svc-hl-xyz"
  selector:
    matchLabels:
      app: svc-hl-xyz
  template:
    metadata:
      labels:
        app: svc-hl-xyz
    spec:
      containers:
        - name: ctr-sts-xyz
          image: XXX/XXX/XXX
          command: ["XXX", "XXX","XXX"]

排查与解决步骤 #

• 报错根源：容器内的启动命令或应用程序依赖serviceName环境变量，但Kubernetes不会自动为StatefulSet Pod注入该变量，当前配置也未手动添加。

• 手动注入环境变量：
  在StatefulSet的容器定义中添加serviceName环境变量，值设置为你的Headless Service名称svc-hl-xyz，修改后的容器配置如下：

  containers:
    - name: ctr-sts-xyz
      image: XXX/XXX/XXX
      command: ["XXX", "XXX","XXX"]
      env:
        - name: serviceName
          value: "svc-hl-xyz"
  

  更新配置后重新部署StatefulSet，观察Pod状态是否恢复。

• 验证镜像与启动命令：
  如果添加环境变量后仍报错，先排除镜像或启动命令的问题：

  1. 替换容器镜像为测试镜像（如nginx:alpine），去掉自定义启动命令，重新部署：

     containers:
       - name: ctr-sts-xyz
         image: nginx:alpine
     

  2. 若测试镜像能正常启动Pod，说明原镜像或启动命令存在问题，需要排查镜像内应用的逻辑，确认它对serviceName变量的具体要求，或启动命令是否存在参数错误。

• 确认Headless Service状态：
  执行kubectl get service svc-hl-xyz检查Service是否正常创建，确认其selector与StatefulSet Pod的labels完全匹配（当前配置中app: svc-hl-xyz是匹配的，若有改动需同步调整）。

内容的提问来源于stack exchange，提问作者Veljko Joksimovic