ServiceComb Kie: a label-addressed configuration server for distributed systems

Key plus labels is the whole addressing model

Apache ServiceComb Kie is a service for configuration management in distributed system, and its design turns on one idea: a configuration item is addressed by a key and a set of labels.

The Conceptions section spells it out. A key could indicate a configuration like timeout, then the value could be 3s, or it could indicate a file name app.properties, then the value could be the content of app.properties. So the value is not restricted to a scalar, it can be a whole file's content.

The labels are what make it more than a key value store. Each key could have labels, and labels indicate a unique key. A key log_level with labels env=production may save the value INFO for all application log level in production environment. A key log_level with labels env=production, component=payment may save the value DEBUG for the payment service in production environment.

The README then draws the consequence. It means all payment service print debug log, but for other service print info log. So you can control your application runtime behaviors by setting different labels to a key.

That is the difference from an ordinary configuration server. In a key value store, the key is the identity and there is exactly one value per key. Here, the key names a setting and the labels narrow down which deployment you are asking about, so the same key resolves differently depending on who is asking.

The primary language is Go, the licence is Apache-2.0 with a LICENSE file and a NOTICE file at the root, the homepage is servicecomb.apache.org, and the last push was on 2026-05-15. The release history is short: v0.2.0 from 2021-02-18 and v0.1.0 from 2019-10-21, so the tags are well behind the code.

One component, four features, and MongoDB underneath

The Components section is short and says it includes 1 components, which is server, a rest api service to manage kv. So this is a single service, not a tiered system, and that is a meaningful constraint rather than a simplification.

The features list has four items. You can manage config items by key and label. You can manage all the kv change history, which is the revision management. You can watch for kv changes using long polling, which the README says highly decreased network cost. And if any client polls config from the server, the detail will be tracked, which is the polling detail track.

The long polling choice is the interesting one. A configuration server that has to tell thousands of instances that a value changed has three options: a websocket, a message queue, or polling. Long polling sits in between and it means the client holds a request open until something happens, which is cheap for a server that would otherwise be hammered by thousands of clients each asking every second. It also means no persistent connection infrastructure and no broker in the deployment.

The polling detail tracking is the feature with the most operational value. If an instance asks for a particular key with particular labels, the server records that. That gives you the map of which applications and machines are actually reading which configuration, which is what you need when you want to change a value and know who will be affected.

The Go module file shows the storage and the surrounding stack. The MongoDB driver at 1.5.1 is there for the key value data and its history. The etcd API at 3.5.4 is there, along with a hashicorp/serf dependency and an etcdadpt package, which points to etcd being used for service discovery or coordination alongside MongoDB rather than MongoDB doing everything. The rest of the direct dependencies are the go-chassis family: cari, foundation for utilities, go-archaius for the configuration library, go-chassis itself for the microservice framework, and openlog and seclog for logging. There is also emicklei/go-restful for the REST layer, urfave/cli for the command line, gofrs/uuid, little-cui/etcdadpt, patrickmn/go-cache for caching, and yaml.v2 and testify.

Running it locally is a compose file and three endpoints

The Quick Start is the shortest section of the README and covers the whole local setup.

git clone [email protected]:apache/servicecomb-kie.git
cd servicecomb-kie/deployments/docker
sudo docker-compose up

That launches three components, and the README lists them with their addresses: mongodb at 127.0.0.1:27017, the mongodb UI at http://127.0.0.1:8081, and the servicecomb-kie service at http://127.0.0.1:30110.

So the local stack is a MongoDB with a browser interface for it, and the config server itself. Two ports to remember: 8081 for looking at the raw data and 30110 for the API.

The API documentation is served by the running service, and the README tells you to browse it at http://127.0.0.1:30110/apidocs.json and copy that document to http://editor.swagger.io/. So the API is described in the OpenAPI JSON format that Swagger Editor consumes, and you can paste it straight in to try the endpoints by hand.

Building your own image and binary is a separate script, and it takes a version.

cd build
export VERSION=0.0.1 #optional, it is latest by default
./build_docker.sh

The output is a servicecomb-kie-0.0.1-linux-amd64.tar in the release folder and a docker image servicecomb/kie:0.0.1. The VERSION variable being optional and defaulting to latest is a small convenience that tells you the build script can pick up the current source version on its own.

The repository layout supports all of this. There is a build/ directory with the build scripts, a deployments/ directory with the compose setup, cmd/ and pkg/ for the Go entry points and packages, a server/ directory, an examples/dev/ directory that the README points to for setting up a local development environment, docs/ for the documentation, scripts/, and proxy.sh at the root.

The documentation itself lives at kie.readthedocs.io, and there is also a docs/README.md describing how to generate it locally.

The label scheme is a design decision you have to make carefully

The Why use kie section is where the project argues its case, and it makes an argument that is really about labels.

kie is described as a highly flexible config server, and the situation it addresses is an operation team facing different x-centralized systems. The example given is a classic application-centralized system, where an operator wants to change config based on application name and version, so the label would be app,version for locating an app's configurations.

The other example is a team managing applications in a data center, where each application instance is deployed in a VM machine, and the label would be farm,role,server,component to locate an app's configurations.

So kie fits different scenarios for configuration management which benefit from label design.

The design implication is significant. The set of labels is part of your configuration schema, and it is decided once and then lives in every client. A team that labels by app and version and a team that labels by farm, role, server and component are making different commitments about what varies in their estate, and migrating between them means changing every client's label set.

That also means the label scheme scales with the number of dimensions you need to distinguish. Two labels give you a matrix of two axes. Four labels give you a matrix of four, and the resolution of the query becomes a matching problem: find the entry whose labels are the most specific match for what the client asked about. The README describes the semantics in terms of specificity, with env=production alone matching everything in production and env=production, component=payment matching only the payment service, but the exact resolution rules when several entries could match are the sort of detail that belongs in the API documentation rather than the README.

One thing the README does not discuss, and that a team should think about before committing, is what happens when two entries have labels that overlap partially. The README does not document a conflict resolution rule, so that is a question for the API doc at the apidocs.json endpoint or for the project itself.

Where ServiceComb Kie is the wrong tool

The first wrong-tool case is a single service with one environment. If you have one application in one environment, the labels buy you nothing and the infrastructure costs you a MongoDB and a service to keep running. A configuration file in the repository, with the deployment pipeline substituting values, is the smaller and more auditable answer.

The second case is a team that needs a secrets store rather than a configuration store. Kie stores values in MongoDB and serves them over an HTTP REST API with no mention of encryption at rest, no mention of access control per label set and no mention of secret rotation. The README describes value management, revision history, change events and polling tracking, and nothing about authorisation. If you are putting credentials in it, you are writing your own access control, and the read access is a single REST endpoint.

The third case is a team that already runs an ecosystem around etcd, Consul or ZooKeeper and wants configuration to live in the same system with the same operational tooling. Kie does use etcd in its dependency set, but the README does not describe it as an etcd-backed store, and the storage story presented to the user is MongoDB with a UI.

The fourth case is a team that needs push rather than pull. Long polling is a reasonable design for a config server and it keeps the deployment simple, but a client that has been offline for an hour reconnects and has to catch up rather than being handed the current value, and any behaviour that depends on immediate propagation to many instances at once is a different mechanism.

On maintenance, the release gap is the thing to weigh. The newest tag is v0.2.0 from February 2021 and the previous one v0.1.0 from October 2019, while the last push was on 2026-05-15. So the repository has five years of work that has not produced a tagged release, and if you install from source or from a container image you are running something quite different from the last published artefact.

The dependency versions tell a similar story. The go-chassis dependency is pinned to a pseudo-version dated December 2025 rather than a release tag, and several others are pinned to specific commits, which is normal for a project tracking a fast-moving sibling library but does mean your build is tied to those commits.

The client is a separate repository, go-chassis/kie-client, and that separation is worth noting: the Go client is versioned independently of the server, so the two can drift.

On licence, Apache-2.0 with a licenses/ directory at the root alongside the LICENSE and NOTICE files, which is the standard Apache project arrangement for third party attributions. Note that Apache-2.0 still carries obligations, such as keeping the licence and notice text when you redistribute.

Editorial conclusion

ServiceComb Kie suits a team whose deployments vary along several axes at once, such as environment, application, version and machine role, because the key plus labels addressing model is exactly what lets one configuration item resolve to different values per deployment target. It does not suit a single-team service with one environment, where a config file in the repository is enough, and it does not suit a team that needs fine-grained authorisation or a secrets store. Before adopting, check the release history first: the newest tag is v0.2.0 from February 2021 while the last push was on 2026-05-15, so the current state of the code is well past the last published release.

Frequently asked questions

Official sources

1. apache/servicecomb-kie on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases