Nacos on AWS User Guide

Overview

This image runs Nacos, an easy to use open source platform for dynamic service discovery, configuration management and service management, designed for building cloud native applications and microservice architectures. Services register themselves with Nacos and discover one another by name, and configuration is stored centrally and pushed to listening clients in near real time, so settings can change without redeploying or restarting the applications that consume them.

Nacos runs here in standalone mode with its built in embedded datastore, so there is no external database to provision before the platform is usable. The server is installed under /opt/nacos and runs as the unprivileged nacos system account. It exposes its OpenAPI and gRPC base on port 8848 and its gRPC client port on 9848, and serves the web console on port 8080 on the loopback interface. nginx terminates TLS on port 443 and reverse proxies the console, so the interface you browse to is encrypted; port 80 answers a /healthz probe and otherwise redirects to HTTPS.

The embedded datastore and the naming and configuration runtime state live at /opt/nacos/data, which is a dedicated, independently resizable EBS data volume rather than part of the operating system disk.

Stock Nacos deployments are frequently found exposed on the internet because they were left on a well known default console login. This image ships with no administrator account and no signing keys at all. On the first boot of every deployed instance a one shot service generates a fresh JSON Web Token signing key, a fresh server identity pair and a strong random administrator password, all unique to that instance, and writes the login to /root/nacos-credentials.txt with mode 0600 so that only the root user can read it. Two instances launched from the same Amazon Machine Image therefore never share a password. Server API and gRPC authentication is enabled, so unauthenticated calls to the naming and configuration interfaces are rejected rather than merely hidden behind the console.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network, port 443 for the web console, and ports 8848 and 9848 from the networks where your client applications run
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Nacos. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network, port 443 for the console, and ports 8848 and 9848 from your application networks. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a short time after the instance state becomes Running and the status checks pass, while the image generates the per instance secrets, initialises the administrator account and issues the instance's TLS certificate.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Nacos Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 443, 8848 and 9848 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=nacos}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Confirm the Services Are Running

Two systemd units make up the running product: nacos.service is the platform itself, and nginx.service terminates TLS and publishes the console.

systemctl is-active nacos.service nginx.service

Both units report active:

active
active

The platform binds its OpenAPI and gRPC base port, its gRPC client port and the console port, and nginx binds ports 80 and 443.

ss -tln | grep -E ':(80|443|8848|9848|8080) '

Port 8848 carries the naming and configuration OpenAPI, port 9848 is the gRPC client port used by the software development kits, port 8080 is the console bound for the reverse proxy, and ports 80 and 443 are nginx.

The platform runs on a Java 17 runtime:

java -version

Step 5: Retrieve the Administrator Password

The administrator password is generated on the first boot of your instance and written to a root only file. Read it with sudo:

sudo cat /root/nacos-credentials.txt

The file records the username, the generated password, the console URL and the server address your applications should use:

NACOS_ADMIN_USERNAME=nacos
NACOS_ADMIN_PASSWORD=<NACOS_ADMIN_PASSWORD>
NACOS_CONSOLE_URL=https://<instance-public-ip>/
NACOS_SERVER_ADDR=<instance-public-ip>:8848

Treat this file as a secret. It is mode 0600 and owned by root, so only the root user can read it.

Step 6: Sign In to the Web Console

Browse to https://<instance-public-ip>/ and sign in as nacos with the password from the previous step. The console is published over HTTPS using a self signed certificate generated for your instance on first boot, so your browser shows a certificate warning the first time you visit; Step 10 explains how to replace it with a certificate from a certificate authority.

The stock nacos / nacos login that ships with unconfigured Nacos deployments is not present on this image; only the generated per instance password works.

Step 7: Review the Service List

Choose Services and then Service List in the left hand navigation. This page lists every service that has registered with the platform, with its instance count and how many of those instances are currently healthy.

Selecting Detail on a service shows its individual instances, each with its IP address, port, weight and health state, along with the service's protection threshold and cluster configuration.

Note that the Nacos 3.2 console renders a red "Threshold Triggered" tag against every row of the service list regardless of the real protection state. The authoritative values are the Healthy Instances count on this list and the per instance Healthy badge on the detail page shown above.

Step 8: Review and Publish Configuration

Choose Configuration and then Configurations. This page lists every configuration the platform is storing, identified by its data ID and group, with the format of each entry.

Selecting Detail on an entry shows its full content, its checksum and when it was last modified, and gives you access to the edit and history views so you can roll back to an earlier revision.

Choose New Config to publish a configuration. Give it a data ID that your application will ask for, leave the group as DEFAULT_GROUP unless you are separating environments by group, pick the format, enter the content and choose Publish. Clients that are listening for that data ID receive the change without a restart.

Step 9: Verify the Platform End to End

The image ships a self test that proves the full security posture and the naming round trip in one command. It confirms that an unauthenticated registration attempt is rejected, that the stock nacos / nacos credential is refused, and that a login with your generated administrator password returns an access token that can register a service instance and read it back.

sudo /opt/nacos/nacos-selftest.sh

A healthy instance reports that the round trip succeeded, naming the address it registered and read back.

The load balancer health probe on port 80 is open and unauthenticated, which is what you point an AWS target group at:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/healthz

It answers 200. Any other path on port 80 redirects to HTTPS:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/

This answers 301.

Step 10: Connect Your Applications

Your applications talk to the platform at the server address recorded in the credentials file, which is the instance address with port 8848. Because server API authentication is enabled on this image, a client must present an access token; obtain one by posting your administrator username and password to the login endpoint, then pass the returned accessToken on subsequent calls.

For a Spring Cloud Alibaba application, the server address, username and password go into your application configuration so the starter obtains and refreshes the token for you. For direct API use, request a token and then call the naming or configuration API with it. Create a dedicated user in the console under the platform's authentication settings rather than distributing the administrator password to every application.

The gRPC client port 9848 must also be reachable from your application networks; the 2.x and 3.x software development kits use it for service discovery and configuration listening, and discovery silently degrades if only 8848 is open.

Step 11: Replace the Self Signed Certificate

The console is served over HTTPS with a self signed certificate generated for your instance on first boot, which is why browsers show a warning. To present a certificate from a certificate authority, point a DNS name at your instance, obtain a certificate for that name, and replace the certificate and key that nginx reads:

• Certificate: /etc/nginx/tls/nacos.crt
• Private key: /etc/nginx/tls/nacos.key

Keep the same paths and file permissions, then reload nginx. The private key must remain mode 0600 and owned by root.

The Data Volume

The embedded datastore and the naming and configuration runtime state live on a dedicated EBS volume mounted at /opt/nacos/data, separate from the operating system disk so it can be resized, snapshotted and monitored independently.

df -h /opt/nacos/data

The volume is referenced in /etc/fstab by filesystem UUID rather than by device name, so it remounts correctly across reboots and instance type changes:

findmnt -no SOURCE,TARGET,FSTYPE /opt/nacos/data

To grow the volume, expand it in the EC2 console or with the AWS CLI, then grow the filesystem on the instance with resize2fs against the device shown above.

Backup and Maintenance

Take EBS snapshots of the data volume on a schedule that matches your recovery point objective; that volume holds the registered services, the stored configurations and their history. A snapshot taken while the platform is running is crash consistent, which the embedded datastore recovers from cleanly on restart, but for a fully quiesced copy stop nacos.service first, take the snapshot, and start it again.

Apply operating system updates with apt-get update and apt-get upgrade on your own maintenance schedule, and restart nacos.service after any update that replaces the Java runtime.

Service logs are available through the journal:

journalctl -u nacos.service --no-pager -n 20

The platform also writes its own logs under /opt/nacos/logs.

Support

This image is published by cloudimg with 24/7 technical support by email and chat, covering deployment, console access, client wiring, namespace design, TLS termination and upgrades.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.