Resolving kube-apiserver Startup Failure Due to --etcd-servers Configuration Error

When kube-apiserver fails to start, check the service status:

systemctl status kube-apiserver

Examine system logs for detailed error messages:

cat /var/log/messages | grep kube-apiserver | grep -i error

If the log shows Error: --etcd-servers must be specified, verify the configuration file /usr/local/kubernetes/cfg/kube-apiserver.conf. Even if --etcd-servers is present, trailing spaces on any line can cause parsing failures.

Example problematic configuration:

KUBE_APISERVER_OPTS="--logtostderr=false \ 
--v=2 \ 
--log-dir=/usr/local/kubernetes/logs \ 
--etcd-servers=https://192.168.153.22:2379,https://192.168.153.20:2379,https://192.168.153.21:2379 \  
--bind-address=192.168.153.22 \ 
--secure-port=6443 \ 
--advertise-address=192.168.153.22 \ 
--allow-privileged=true \ 
--service-cluster-ip-range=10.0.0.0/24 \ 
--enable-admission-plugins=NamespaceLifecycle,LimitRanger,ServiceAccount,ResourceQuota,NodeRestriction \ 
--authorization-mode=RBAC,Node \ 
--enable-bootstrap-token-auth=true \ 
--token-auth-file=/usr/local/kubernetes/cfg/token.csv \ 
--service-node-port-range=30000-32767 \ 
--kubelet-client-certificate=/usr/local/kubernetes/ssl/server.pem \ 
--kubelet-client-key=/usr/local/kubernetes/ssl/server-key.pem \ 
--tls-cert-file=/usr/local/kubernetes/ssl/server.pem \ 
--tls-private-key-file=/usr/local/kubernetes/ssl/server-key.pem \ 
--client-ca-file=/usr/local/kubernetes/ssl/ca.pem \ 
--service-account-key-file=/usr/local/kubernetes/ssl/ca-key.pem \ 
--etcd-cafile=/usr/local/etcd/ssl/ca.pem \ 
--etcd-certfile=/usr/local/etcd/ssl/server.pem \ 
--etcd-keyfile=/usr/local/etcd/ssl/server-key.pem \ 
--audit-log-maxage=30 \ 
--audit-log-maxbackup=3 \ 
--audit-log-maxsize=100 \ 
--audit-log-path=/usr/local/kubernetes/logs/k8s-audit.log"

In this example, an extra space after the etcd-servers line causes the entire configuration to be misinterpreted. Removing all trailing whitespace from every line resolves the issue.

Tags: kubernetes kube-apiserver etcd configuration troubleshooting

Posted on Thu, 14 May 2026 02:17:25 +0000 by treeleaf20