nacos Documentation

File: README.md Copy Chapter

Nacos: Dynamic *Na*ming and *Co*nfiguration *S*ervice

What does it do Copy Chapter

Nacos (official site: nacos.io) is an easy-to-use platform designed for dynamic service discovery and configuration and service management. It helps you to build cloud native applications and microservices platform easily.

Service is a first-class citizen in Nacos. Nacos supports almost all type of services，for example，Dubbo/gRPC service, Spring Cloud RESTFul service or Kubernetes service.

Nacos provides four major functions.

• Service Discovery and Service Health Check

  Nacos makes it simple for services to register themselves and to discover other services via a DNS or HTTP interface. Nacos also provides real-time health checks of services to prevent sending requests to unhealthy hosts or service instances.

• Dynamic Configuration Management

  Dynamic Configuration Service allows you to manage configurations of all services in a centralized and dynamic manner across all environments. Nacos eliminates the need to redeploy applications and services when configurations are updated, which makes configuration changes more efficient and agile.

• Dynamic DNS Service

  Nacos supports weighted routing, making it easier for you to implement mid-tier load balancing, flexible routing policies, flow control, and simple DNS resolution services in the production environment within your data center. It helps you to implement DNS-based service discovery easily and prevent applications from coupling to vendor-specific service discovery APIs.

• Service and MetaData Management

  Nacos provides an easy-to-use service dashboard to help you manage your services metadata, configuration, kubernetes DNS, service health and metrics statistics.

Quick Start Copy Chapter

It is super easy to get started with your first project.

Deploying Nacos on cloud Copy Section

You can deploy Nacos on cloud, which is the easiest and most convenient way to start Nacos.

Use the following Nacos deployment guide to see more information and deploy a stable and out-of-the-box Nacos server.

Start by the provided startup package Copy Section

Step 1: Download the binary package

You can download the package from the latest stable release.

Take release nacos-server-1.0.0.zip for example:

unzip nacos-server-1.0.0.zip
cd nacos/bin

Step 2: Start Server

On the Linux/Unix/Mac platform, run the following command to start server with standalone mode:

sh startup.sh -m standalone

On the Windows platform, run the following command to start server with standalone mode. Alternatively, you can also double-click the startup.cmd to run NacosServer.

startup.cmd -m standalone

For more details, see quick-start.

Quick start for other open-source projects: Copy Chapter

• Quick start with Nacos command and console

• Quick start with dubbo

• Quick start with spring cloud

• Quick start with kubernetes

Documentation Copy Chapter

You can view the full documentation from the Nacos website.

You can also read this online eBook from the NACOS ARCHITECTURE & PRINCIPLES.

All the latest and long-term notice can also be found here from GitHub notice issue.

Contributing Copy Chapter

Contributors are welcomed to join Nacos project. Please check CONTRIBUTING about how to contribute to this project.

How can I contribute? Copy Section

• Take a look at issues with tags marked good first issue or contribution welcome.
• Answer questions on issues.
• Fix bugs reported on issues, and send us a pull request.
• Review the existing pull request.
• Improve the website, typically we need
  • blog post
  • translation on documentation
  • use cases around the integration of Nacos in enterprise systems.

Other Related Project Repositories Copy Chapter

• nacos-spring-project provides the integration functionality for Spring.
• nacos-group is the repository that hosts the eco tools for Nacos, such as SDK, synchronization tool, etc.
• spring-cloud-alibaba provides the one-stop solution for application development over Alibaba middleware which includes Nacos.

Contact Copy Chapter

• Gitter: Nacos's IM tool for community messaging, collaboration and discovery.
• Twitter: Follow along for latest nacos news on Twitter.
• Weibo: Follow along for latest nacos news on Weibo (Twitter of China version).
• Nacos Segmentfault: Get latest notice and prompt help from Segmentfault.
• Email Group:
  • [email protected]: Nacos usage general discussion.
  • [email protected]: Nacos developer discussion (APIs, feature design, etc).
  • [email protected]: Commits notice, very high frequency.
• Join us from DingDing(Group 1: 21708933(full), Group 2: 30438813(full), Group 3: 31222241(full), Group 4: 12810027056).

DingDing Group QR Code Copy Section

DingDing MCP Group QR Code Copy Section

WeChat Group QR Code Copy Section

Enterprise Service Copy Chapter

If you need Nacos enterprise service support, or purchase cloud product services, you can join the discussion by scanning the following DingTalk group. It can also be directly activated and used through the microservice engine (MSE) provided by Alibaba Cloud.
https://cn.aliyun.com/product/aliware/mse?spm=nacos-website.topbar.0.0.0

Download Copy Chapter

• Nacos Official Website
• GitHub Release

Who is using Copy Chapter

These are only part of the companies using Nacos, for reference only. If you are using Nacos, please add your company here to tell us your scenario to make Nacos better.

File: console-ui/src/pages/AuthorityControl/README.md Copy Chapter

权限控制

AuthorityControl

1. UserManagement => 用户管理
2. RolesManagement => 角色管理
3. PermissionsManagement => 权限管理

File: console-ui/README.md Copy Chapter

Nacos Console UI (Legacy)

The legacy Nacos console frontend, built with React + Webpack 4.

Prerequisites Copy Chapter

• Node.js >= 14 (recommended 14.x ~ 22.x)
• npm
• Global CLI tools:

npm install cross-env webpack webpack-cli

Install Dependencies Copy Chapter

npm install

Local Development Copy Chapter

npm start

Proxy configuration is in build/webpack.dev.conf.js under the proxy property:

proxy: [{
  context: ['/'],
  changeOrigin: true,
  secure: false,
  target: 'http://ip:port',
}],

Build Copy Chapter

npm run build

Build output goes to the dist/ directory.

Note: Node.js 17+ requires the --openssl-legacy-provider flag (already configured in the package.json build script).

Deploy Copy Chapter

Copy build artifacts to the backend static resources directory:

rm -rf ../console/src/main/resources/static/legacy/*
cp -r dist/* ../console/src/main/resources/static/legacy/

Deployed directory structure:

console/src/main/resources/static/legacy/
├── index.html
├── css/
└── js/

contextPath Adaptation Copy Chapter

Build artifacts use relative paths (../), adapting to any nacos.console.contextPath configuration value. No rebuild is needed for different contextPath settings.

File: example/README.md Copy Chapter

Nacos example module

This module contains some examples for nacos.

1. Run the Nacos service in standalone mode locally. By default, it uses port 8848.
2. App.java file is a simple "Hello Nacos" program.
3. ConfigExample.java file demonstrates how to utilize the configuration center in Nacos.
4. NamingExample.java file demonstrates how to use Nacos for service register, deregister, and subscribe.

File: istio/src/main/resources/proto/mcp/Readme.md Copy Chapter

// Copyright 2018 Istio Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

Mesh Configuration Protocol (MCP)

Introduction Copy Chapter

This folder contains the proto buffers for the Mesh Configuration
Protocol (MCP). MCP is based on
XDS
and maintains conceptual alignment with it, despite the specific
service and proto definitions being different.

Overview Copy Chapter

MCP is a subscription-based configuration distribution API. The
configuration consumer (i.e. sink) requests updates for collections of
resources from a configuration producer (i.e. source). The source
pushes resource updates to the sink when resources are added, updated,
or deleted. The sink positively ACK's the resource update, if it was
accepted, and NACK's if it was rejected, e.g. because a resource was
invalid. The source may push additional update once the previous
update was ACK/NACK'd. The source should only have one outstanding
update (per-collection) in flight at a time.

MCP is a pair of bidirectional streaming gRPC API services
(ResourceSource and ResourceSink).

• The ResourceSource service is used when the resource source is the
  server and the sink is a client. By default, Galley implements the
  ResourceSource service and Pilot/Mixer connect as clients.

• The ResourceSink service is used when the resource source is a
  client and the sink is the server. Galley can be configured to
  optionally "dial-out" to a remote configuration sink, e.g. Pilot is in
  another cluster where it cannot, as a client, initiate
  connection to Galley. In this scenario, Pilot would implement the
  ResourceSink service and Galley would connect as a client.

ResourceSource and ResourceSink are semantically equivalent with
regards to the message exchange. The only meaningful difference is who
initiates the connection and opens the grpc stream.

Data model Copy Chapter

MCP is the mechanism of transport whereby Pilot and Mixer can be
configured by a manager component. MCP defines a common per-resource
metadata format and resource specific contents is defined elsewhere
(e.g. https://github.com/istio/api/tree/master/networking/v1alpha3).

Collections Copy Section

Resources of the same type are organized into named
collections. Istio API collection names are of the form
istio/<area>/<version>/<api> where <area>, <version>, and <api>
are defined by the API style guidelines. For
example, the collection name for VirtualService is
istio/networking/v1alpha3/virtualservices.

Metadata Copy Section

Connection establishment Copy Chapter

• ResourceSource service - The client is the resource sink. The
  client dials the server and establishes a new gRPC stream. The client
  sends RequestResources and receive Resources messages.

• ResourceSink service - The client is the resource source. The
  client dials the server and establishes a new gRPC stream. The server
  sends RequestResources and receive Resources messages.

Configuration updates Copy Chapter

The following overview applies to both ResourceSink and ResourceSource
services, regardless of client/server roles.

The resource update protocol is derived from Incremental xDS. The
protocol exchange is mostly the same except that resource hints have
been removed. Most of the text and diagrams below are copied from the
Incremental xDS docs and adjusted accordingly.

In MCP, resources are first organized by collection. Within each
collection, resources are uniquely identifiable by their metadata
name. Individual resources are versioned to differentiate newer
versions of the same named resource.

A RequestResource message can be sent in two situations:

• Initial message in an MCP bidirectional change stream

• As an ACK or NACK response to a previous Resources message. In
  this case the response_nonce is set to the nonce value from the
  Resources message. ACK/NACK is determined by the presence of
  error_detail in the subsequent request.

The initial RequestResources messages includes the collection
corresponding to the subscribed set of resources
(e.g. VirtualService), the node sink identifier, and nonce fields, and
initial_resource_version (more on that later). The source send a
Resources message when the requested resources are available. After
processing the Resources message , the sink sends a new
RequestResources message on the stream, specifying the last version
successfully applied and the nonce provided by the source.

The nonce field is used to pair RequestResources and Resources
messages per collection. The source should only send one outstanding
Resource message at a time (per-collection) and wait for the sink to
ACK/NACK. Upon receiving an update, the sink is expected to send an
ACK/NACK relatively quickly after decoding, validating, and persisting
the update to its internal configuration store.

The source should ignore requests with stale and unknown nonces that
do not match the nonce in the most recently sent Resource message.

Success examples Copy Section

The following example shows the sink receiving a sequence of changes
which are successfully ACK'd.

The following example shows the same desired resource delivered with
incremental updates. This example assumes incremental is supported by
the source. When source does not support incremental updates, the
pushed Resources will always have incremental set to false,
regardles of whether the sink requested an incremental update. At any
time, the source can decide to push a full-state update, ignoring the
sink's request. Both sides must negotiate (i.e. agree) to use
incremental on a per request/response basis for an update to be sent
incrementally.

Error example Copy Section

The following example shows what happens when a change cannot be applied.

The sink should only NACK in exceptional cases. For example, if a set of
resources was invalid, malformed, or could not be decoded. NACK'd updates
should raise an alarm for subsequent investigation by a human. The source
should not resend the same set of resources that were previously NACK'd.
Canary pushes to dedicated sinks may also be used to verify correctness
(non-NACK) before pushing to a larger fleet of resource sinks.

The nonce in MCP is used to match RequestResources and Resources. On
reconnect, the sinks may attempt to resume a session with the same
source by specifying the known resources version with
initial_resource_version for each collection.