# agollo: a Go client for the Apollo configuration centre

> agollo is the Go client for the Apollo configuration centre, a module at version 5 with a major path change, real time configuration synchronisation, gray release support, lazy loading of namespaces, and a fallback to local configuration files. The quick start is a go get, a config struct, and one call to start the client and read a value.

**apolloconfig/agollo** — 🚀Go client for ctrip/apollo (https://github.com/apolloconfig/apollo)

- Repository: https://github.com/apolloconfig/agollo
- Website: https://www.apolloconfig.com
- Stars: 773 · Forks: 197
- Language: Go
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/apolloconfig-agollo

## A client for a configuration centre, and what that means

agollo is a Golang client for the configuration centre framework Apollo, and the project site is apolloconfig.com. The module is Apache 2.0 licensed, and the repository is not archived, with the last push on 2026-09-21.

The release history shows the shape of the project. v5.0.0 was published in March 2026, v4.4.0 in May 2024, and v4.3.1 in July 2023, so the client is versioned independently of the Apollo server and is not on a monthly cadence.

What a configuration centre client actually has to do is the interesting part. The feature list is short and each entry is a real requirement.

Support for multiple IPs, AppIDs, and namespaces means the client can talk to a cluster of configuration servers, to more than one application, and to more than one namespace, which is the difference between a client and a hardcoded config fetch. Real-time configuration synchronization is the core promise of a configuration centre, so a value changed in the console reaches the running process without a restart. Gray release configuration means a subset of instances can be given a different value, which is how a staged rollout of a configuration change is done. Lazy loading, with runtime namespaces, means a namespace is not fetched until something asks for it, so a service that only needs two namespaces does not pay for the other forty.

Client-side and configuration file fallback is the resilience story. The client can be configured with a local file that holds the last known good values, and the service keeps starting when Apollo is down. Customizable logger and cache components matter for the same reason: the logger has to be the one your application already uses, and the cache has to be the one you can reason about, because the cache is where a stale value would otherwise hide.

Support for configuration access keys is the last item, and it is the one that connects to the Secret field in the configuration struct.

## The quick start is a config struct and two calls

The usage section is the shortest of any client in this space, and that is a good sign.

The install is a single go get, and note the version suffix on the module path.

```bash
go get -u github.com/apolloconfig/agollo/v5@latest
```

Then you build a config struct and hand it to the client.

```go
package main

import (
	"fmt"

	"github.com/apolloconfig/agollo/v5"
	"github.com/apolloconfig/agollo/v5/env/config"
)

func main() {
	c := &config.AppConfig{
		AppID:          "testApplication_yang",
		Cluster:        "dev",
		IP:             "http://localhost:8080",
		NamespaceName:  "dubbo",
		IsBackupConfig: true,
		Secret:         "6ce3ff7e96a24335a9634fe9abca6d51",
	}

	client, _ := agollo.StartWithConfig(func() (*config.AppConfig, error) {
		return c, nil
	})
	fmt.Println("Apollo configuration initialized successfully")

	//Use your apollo key to test
	cache := client.GetConfigCache(c.NamespaceName)
	value, _ := cache.Get("key")
	fmt.Println(value)
}
```

There are four things to read out of that. The configuration is a struct with the obvious fields, AppID, Cluster, IP, NamespaceName, IsBackupConfig, and Secret, and it lives in the env/config subpackage rather than in the root, which is what lets the same struct be loaded from an environment variable, a file, or a literal.

StartWithConfig takes a function that returns the config and an error, rather than a config value. That signature is there for the file and environment loading paths, where the configuration may not be available at the moment you build the struct, and it means the error is not swallowed by a constructor that has nowhere to return it.

GetConfigCache takes a namespace name and returns a cache, and the cache is what you read values from with Get. The namespace in the example is the one from the config struct, so a client that is configured for one namespace still asks for the cache by name, which is what allows several namespaces to be used from one client.

The Secret field is the access key, and the comment in the example says to use your Apollo key to test.

## The fallback path, and viper behind it

The IsBackupConfig flag in the example is the local fallback, and the dependency list explains how it works.

The go.mod for version 5 declares the module as github.com/apolloconfig/agollo/v5, with a go directive of 1.20. The direct requirements are small: viper at 1.8.1 for configuration file handling, gomonkey v2 for the tests, and gohamcrest for matching. The indirect list is viper's own dependency tree, and it is a revealing one: fsnotify for watching files, hcl, the magiconair properties library, pelletier go-toml, afero, cast, jwalterweatherman, pflag, gotenv, the ini and yaml parsers, and golang.org/x/text.

That is the standard set of viper dependencies, and it tells you the shape of the local configuration support. Viper reads ini, yaml, toml, and properties files, it can read environment variables through gotenv and pflag, and it watches files with fsnotify so a change on disk is noticed. The app.properties file at the root of the repository is consistent with that, since properties is one of the formats viper handles.

So the fallback path is: the client reads a local file with the same keys it would have read from Apollo, and when the configuration service is unreachable the local values are used. The IsBackupConfig flag is what turns that on.

The afero dependency is worth a second look because it is not a viper default in most configurations. Afero is a filesystem abstraction, and it is what lets the tests swap in their own filesystem and assert on the reload behaviour without depending on the real disk. Combined with the mock_server_test.go file at the root, which is a fake Apollo server for the client tests, the test setup is reasonably thorough for a configuration client.

The customizable logger and cache features are the other two extension points, and the directory layout reflects them, with component directories for the pluggable parts, cluster for the multi server handling, protocol for the API layer, storage for the local persistence, agcache for the cache, and env for the environment based configuration.

## The module path change, and how the package is laid out

Two practical details are easy to trip over and both are stated in the README.

The first is the module path. The module is versioned as /v5, and the import statements have to match, which is the Go convention for a module whose major version is above one. An existing project moving from version 4 has to change every import path, and the install command carries the same suffix with the @latest tag. The repository also keeps a README_CN.md, so the documentation exists in Chinese and English, which is consistent with the project being maintained by a Chinese team for a configuration centre originally built at Ctrip.

The second is the other languages problem. The README points out that for languages such as PHP you should use agollo-agent as a local agent, so a non-Go application reads its configuration from the same Apollo server through a local process rather than through a native client. There is a separate demo project, agollo_demo, for the Go usage.

## Other languages, the reference server, and where to ask for help

The Apollo server itself is a separate project, and the README links it as the reference, with the configuration centre repository at the apolloconfig organisation.

On the practical side, the project keeps a CHANGELOG.md and a CONTRIBUTING.md, and a .mergify.yml file, which is the configuration for a bot that automates merge and label handling on pull requests. The issue tracker on GitHub is the support channel, and the README asks you to use it for both problems and feature requests, with an email address as an alternative.

One last thing about the version 5 release, since it is the most recent and the one you will meet first. It landed in March 2026 after a gap of nearly two years from v4.4.0, and the change in the major number means the maintainers considered it a breaking release, which in this client means the module path change rather than a change in the feature set.

## Conclusion

agollo fits a Go service that already uses Apollo as its configuration centre, or a team moving to it, and that wants the client to keep working when the configuration service is unreachable, since the fallback to local configuration files is built in. It does not fit a service that does not run Apollo, and it does not fit a team that cannot change the module path in their import statements. Verify first that your Apollo version and your Apollo release are compatible with client version 5, since the module path carries the major version, that the namespace names you request exist and that you have decided whether to load them lazily or at startup, and that the Secret in the configuration is the access key your Apollo deployment expects.

## FAQ

### How do I install the agollo Go client?

With go get -u github.com/apolloconfig/agollo/v5@latest. The version suffix is part of the module path, so the import statements in your code have to use the /v5 path as well.

### How do I start the agollo client and read a configuration value?

Build a config.AppConfig with the AppID, Cluster, IP, NamespaceName, IsBackupConfig, and Secret fields, pass a function returning it to agollo.StartWithConfig, then call client.GetConfigCache with the namespace name and read the value with the Get method on the returned cache.

### What happens in agollo when the Apollo server is unreachable?

The client-side and configuration file fallback feature applies. With IsBackupConfig enabled, the client keeps the last known values from a local file, and the repository uses viper with fsnotify and afero for that local configuration handling, which is why the local file format is the same as the configuration service's key and value model.

### Does agollo support gray releases and lazy namespace loading?

Yes. The feature list includes gray release configuration, so a subset of instances can be given a different value, and lazy loading of namespaces at runtime, so a namespace is not fetched until it is asked for.

### Can I use Apollo from a language other than Go?

The README points you to agollo-agent, a local agent that gives languages such as PHP access to the same Apollo configuration, so the non-Go application reads its configuration through a local process rather than a native client.

## Sources

- [apolloconfig/agollo on GitHub](https://github.com/apolloconfig/agollo)
- [License: Apache-2.0](https://github.com/apolloconfig/agollo/blob/master/LICENSE)
- [Project website](https://www.apolloconfig.com)
- [README](https://github.com/apolloconfig/agollo/blob/master/README.md)
- [Releases](https://github.com/apolloconfig/agollo/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/apolloconfig-agollo