nacos-k8s: running Nacos on Kubernetes with StatefulSets

A Nacos Docker image wrapped in StatefulSet manifests

nacos-k8s is a packaging layer rather than a service registry of its own. It holds a Nacos Docker image and the Kubernetes YAML needed to run Nacos as a StatefulSet, so every instance receives an ordinal hostname, a stable network identity and its own storage claim. The audience is an operator who already maintains a Kubernetes cluster and needs Nacos, the naming and configuration service used by Spring Cloud style microservices, running on it.

The project description states the aim directly: the repository contains a Nacos Docker image meant to facilitate deployment of Nacos on Kubernetes via StatefulSets. The layout matches that scope. Top level entries include deploy/ with the manifests, helm/ with a Helm chart, operator/ with a Nacos Operator guide, plugin/ which the directory table describes as helping a Nacos cluster achieve automatic scaling in Kubernetes, plus a quick-startup.sh at the root.

One useful detail sits in the tips rather than the intro. Nacos version 1.1.4 or lower should be taken from the v1.1.4 tag instead of the default branch, so the branch content assumes a newer server than that.

The quick start script skips NFS, and the docs warn that data can be lost

The fastest route clones the repository and runs one script. The clone step is the standard git command:

git clone https://github.com/nacos-group/nacos-k8s.git

Inside the checkout, the script is made executable and started:

cd nacos-k8s
chmod +x quick-startup.sh
./quick-startup.sh

The behaviour of this path is worth stating plainly, because the documentation flags it twice. The quick start runs without NFS, and the note attached to it says that emptyDirs will possibly result in a loss of data. The limitations section repeats the same constraint: persistent volumes must be used. Anyone evaluating the project with a throwaway cluster is fine with this. Anyone who points this at anything they care about is not, because Nacos configuration and registry records live in those volumes.

There is also a data directory subtlety in the Nacos manifests, described below, that makes the simple path even less suitable as a starting point for real work.

MySQL credentials are typed by hand into the Nacos manifest

Running Nacos against an external database requires editing the manifest before applying it. The file to change is deploy/nacos/nacos-pvc-nfs.yaml, and the block to change is a data section holding five keys:

data:
  mysql.host: "db host"
  mysql.db.name: "db name"
  mysql.port: " db port"
  mysql.user: " db username"
  mysql.password: " db password"

The password travels as plaintext in a YAML file that is then applied with kubectl create. There is no secret reference in the example, so anyone running this path has to decide on their own how to handle that.

The configuration property table adds two more keys that matter. NACOS_DATASOURCE_PLATFORM is required and accepts only mysql or embedded, and the older SPRING_DATASOURCE_PLATFORM name is marked deprecated. NACOS_REPLICAS is also required, and its value must match the replicas attribute of the StatefulSet, which is an easy mismatch when both are edited separately.

A database server alone is not enough. The deployment notes say that if you use a custom database you must initialize the database script yourself first, pointing at the upstream nacos-datasource-plugin-mysql schema file. A fresh MySQL with no schema will leave Nacos unable to serve config or naming data.

The Helm chart is the maintained path, the NFS flow is marked deprecated

The deployment guide carries an explicit deprecation notice. The NFS, Ceph and OpenShift deployment methods below are deprecated and no longer actively maintained, because they rely on archived upstream projects such as kubernetes-incubator/external-storage and outdated APIs. The notice directs readers to the Helm chart instead, which supports persistent storage via any StorageClass, including NFS CSI and Rook-Ceph, with persistence.enabled=true.

That is a meaningful change in direction, and it changes the shape of the project. The older flow asked you to build a storage substrate yourself: create an RBAC Role and ServiceAccount, deploy an NFS client provisioner, define a StorageClass, confirm the provisioner pod is running, then deploy MySQL against it. The chart path removes that bootstrap entirely, since the cluster already has a StorageClass you can name. What remains in the repo is the history of the earlier approach rather than a recommended procedure.

The deprecation notice also tells you what not to copy from older guides. Tutorials that walk through the provisioner steps describe a path the project no longer supports, so a deployment following them inherits archived dependencies.

Ordinal hostnames are what hold the cluster membership together

The mechanism that makes a Nacos cluster work here is the StatefulSet hostname convention. Each Pod gets a unique hostname of the form <statefulset name>-<ordinal index>, and the Nacos cluster configuration file inside the container lists the members by address. You can read that file straight out of a running Pod:

for i in 0 1; do echo nacos-$i; kubectl exec nacos-$i -- cat conf/cluster.conf; done

Because the replicas field of the nacos StatefulSet is set to 2 at that point, the cluster file contains only two Nacos addresses. Scaling the StatefulSet is a normal kubectl operation:

kubectl scale sts nacos --replicas=3

Afterwards the same inspection covers three members:

for i in 0 1 2; do echo nacos-$i; kubectl exec nacos-$i -- cat conf/cluster.conf; done

This is where the plugin directory earns its place in the layout table. The plugin is there to help a Nacos cluster achieve automatic scaling in Kubernetes, which is exactly the step that a hand edited cluster.conf file cannot do on its own. If you scale beyond the two members in the manifest, check whether that plugin has rewritten the membership list before you assume the new member joined.

Registration, discovery and config calls target the v2 API paths

The quick start documentation includes four curl calls for checking that the deployment works, and they use the v2 endpoints of the Nacos open API. Registering an instance is a POST to the naming service:

  curl -X POST 'http://cluster-ip:8848/nacos/v2/ns/instance?serviceName=nacos.naming.serviceName&ip=20.18.7.10&port=8080'

Listing the instances of that service is the matching GET:

  curl -X GET 'http://cluster-ip:8848/nacos/v2/ns/instance/list?serviceName=nacos.naming.serviceName'

Configuration is published and read through the config service, using a dataId and a group:

  curl -X POST "http://cluster-ip:8848/nacos/v2/cs/config?dataId=nacos.cfg.dataId&group=test&content=helloWorld"

  curl -X GET "http://cluster-ip:8848/nacos/v2/cs/config?dataId=nacos.cfg.dataId&group=test"

Two things are fixed in these examples and are worth noting before you adapt them. The port is 8848, and the address is a cluster IP rather than a Pod IP or a NodePort, so you need a Service in front of the StatefulSet. The example also uses Nacos 1.x style endpoints under the /nacos/v2 prefix, so a client built against a different Nacos API version may need a different path.

Three tags and a push on 2026-10-16 describe the release history

The repository is not archived, and the last push was on 2026-10-16. The release list is short. v1.0.0 was published on 2022-11-08, v1.0.1 on 2024-08-02, and v1.0.2 on 2026-04-02. Two years separate the first two tags and roughly twenty months separate the second from the third, so the version numbers track infrastructure and packaging changes rather than the Nacos server release cadence. Nothing in the documentation ties a tag to a specific Nacos server version, and that mapping is worth confirming against the image build files before you pin a tag in a cluster.

Licensing is Apache-2.0, which permits internal modification and redistribution with the usual notice and licence file obligations. The README also links a Chinese translation at README-CN.md, and there are separate guides for Ceph and for OpenShift, the latter now covered by the deprecation notice.

Prerequisites are stated plainly: Kubernetes 1.19 or later, and NFS 4.1 or later where NFS is used. The reference node configuration is a three node cluster of CentOS Linux release 7.4.1708 machines with single core processors, 4G of memory and a 40G cloud disk, which is a low bar by modern standards and no guide to real capacity.

Editorial conclusion

Choose nacos-k8s when you already run Kubernetes and want Nacos deployed as a StatefulSet with per instance identities, and treat the Helm chart with persistence.enabled=true as the path to use. Skip the NFS, Ceph and OpenShift manifests, which the project itself marks deprecated and reliant on archived upstream projects. If you need an embedded database, multi cluster management or automatic configuration reconciliation, the Helm chart and the Nacos Operator are closer to what you need. Before deploying, verify that your cluster runs Kubernetes 1.19 or later, that a StorageClass can be bound for each StatefulSet member, and that your MySQL schema has been initialized from the upstream nacos-datasource-plugin-mysql schema script.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. nacos-group/nacos-k8s on GitHub
4. README
5. Releases