Nacos Kubernetes Quick Start

This quick start guide helps you quickly deploy and use Nacos in Kubernetes through the Nacos Docker image.

This quick start is intended to help you quickly install, deploy, and get started with Nacos. We recommend using it only for testing. For production deployment, enable authentication to avoid security risks.
This quick start is intended to help you quickly install, deploy, and get started with Nacos. To make it convenient to quickly deploy Nacos in a Kubernetes environment, this quick start uses default database configuration when connecting to the database. We recommend using it only for testing. For production deployment, be sure to modify the deployed database configuration to avoid security risks.
Nacos is positioned as an internal IDC application component, not a product for public network environments. We recommend deploying it in an isolated internal network environment and strongly discourage deployment in public network environments.

1. Prepare the Environment

To install and deploy Nacos using this quick start method, install Kubernetes.

2. Download the nacos-k8s Project

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

3. Quick Start

When using this method to start quickly, note that persistent volumes are not used, so there may be a risk of data loss.

3.1. Edit the Deployment Configuration File and Add Authentication Configuration

Find the nacos container in the nacos StatefulSet in deploy/nacos/nacos-quick-start.yaml:

Change image to an available target 3.3 image, such as nacos/nacos-server:<target-version-tag>. The repository’s default image may still use an older release.
Keep the database, NACOS_SERVERS, and other settings. Replace the authentication variables below with your own values. Edit existing entries with the same names instead of adding duplicates.

NACOS_AUTH_TOKEN is the server secret used to sign tokens. It must be valid Base64 decoding to at least 32 bytes, and is different from the login response’s accessToken. The server identity key/value must be nonempty. All replicas must use the same secret and server identity; replace the repository’s demo values.

The following is the authentication portion of the container’s env. Replace the placeholders with actual values:

env:
  - name: NACOS_AUTH_ENABLE
    value: "true"
  - name: NACOS_AUTH_TOKEN
    value: "<your-base64-token-signing-secret>"
  - name: NACOS_AUTH_IDENTITY_KEY
    value: "<your-server-identity-key>"
  - name: NACOS_AUTH_IDENTITY_VALUE
    value: "<your-server-identity-value>"

3.2. Run the Quick Start Script to Start Nacos

chmod +x quick-startup.sh
./quick-startup.sh

4. Verify Whether Nacos Started Successfully

Run kubectl logs -f $pod_name to view the Nacos startup logs. If you see the following log, the service has started successfully.

Nacos started successfully in xxxx mode. use xxxx storage

Once the Pod is ready, forward its ports in the current namespace and keep that terminal running. Run the verification commands in a second terminal. The console and API examples below use these local forwarded addresses.

kubectl port-forward pod/nacos-0 8080:8080 8848:8848

4.1. Nacos Console Page

Open any browser and enter http://127.0.0.1:8080 to access the Nacos console page.

Note: The first time you open the console, you are asked to initialize the password for the administrator user nacos.

4.1.1. Obtain An Access Token

Run the following commands in Bash (Git Bash or WSL on Windows). Replace the password with the administrator password you initialized, then copy accessToken from the login response into NACOS_ACCESS_TOKEN:

export NACOS_USERNAME='nacos'
export NACOS_PASSWORD='<your-initialized-password>'
curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/login' \
  --data-urlencode "username=${NACOS_USERNAME}" \
  --data-urlencode "password=${NACOS_PASSWORD}"

export NACOS_ACCESS_TOKEN='<accessToken-from-login-response>'

Both Client and Admin API calls below use this token. Log in again after it expires. Applications should use an account with the required resource permissions; see Access Credentials.

4.2. Service Registration

curl -X POST 'http://127.0.0.1:8848/nacos/v3/client/ns/instance?serviceName=quickstart.test.service&ip=127.0.0.1&port=8080' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}"

4.3. Service Discovery

curl -X GET 'http://127.0.0.1:8848/nacos/v3/client/ns/instance/list?serviceName=quickstart.test.service' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}"

4.4. Publish Configuration

curl -X POST 'http://127.0.0.1:8848/nacos/v3/admin/cs/config?dataId=quickstart.test.config&groupName=test&content=HelloWorld' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}"

4.5. Get Configuration

curl -X GET 'http://127.0.0.1:8848/nacos/v3/client/cs/config?dataId=quickstart.test.config&groupName=test' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}"

If authentication fails, check the username, password, token validity, and account permissions. Explicitly disabling Client authentication is a temporary migration option for existing clients without credentials; see the Upgrade Guide.