Go Config Server Client

Go library for Spring Config Server. Inspired by the Java
library Cloud Config Client.

go get github.com/Piszmog/cloudconfigclient/v2

V2 Migration

See V2 Migration for details on how to migrate from V1
to V2

Description

Spring’s Config Server provides way to externalize configurations of applications. Spring’s
Spring Cloud Config Client
can be used to load the base configurations that an application requires to properly function.

This library provides clients the ability to load Configurations and Files from the Config Server.

Compatibility

This library is compatible with versions of Spring Config Server greater than or equal to 1.4.x.RELEASE. Prior
versions of the Config Server do not provide the endpoint necessary to retrieve files for the Config Server’s default
branch.

Spring Cloud Config Server v3.x

Since Spring Cloud Services v3.0, the service name in VCAP_SERVICES has changed from p-config-server to
be p.config-server.

To help mitigate migration difficulties, cloudconfigclient.New(cloudconfigclient.DefaultCFService()) will first search
for the service p.config-server (v3.x). If the v3.x service could not be found,
p-config-server (v2.x) will be search for.

See Spring Cloud Services Differences
for more details.

Example Usage

Below is an example usage of the library to retrieve a file from the Config Server and to retrieve the application’s
configurations

• For local config client, there are two options (Option) the create a client
  1. Call LocalEnv(). Set the environment variable CONFIG_SERVER_URLS. It is a comma separated list of all the
     base URLs
  2. Call Local(baseUrls ...string). Provide the array of base URLs of Config Servers.
• If the config server is protected with basic auth, call Basic with the username and password.
• For running in Cloud Foundry, ensure a Config Server is bounded to the application. VCAP_SERVICES will be provided
  as an environment variables with the credentials to access the Config Server
• For connecting to a Config Server via OAuth2 and not deployed to Cloud Foundry, an OAuth2 Client can be created
  with OAuth2(baseURL string, clientId string, secret string, tokenURI string)

package main
import (
    "fmt"
    "github.com/Piszmog/cloudconfigclient/v2"
    "net/http"
)
type File struct {
    Example Example `json:"example"`
}
type Example struct {
    Field string `json:"field"`
}
func main() {
    // To create a Client for a locally running Spring Config Server
    configClient, err := cloudconfigclient.New(cloudconfigclient.LocalEnv(&http.Client{}))
    // Or
    configClient, err = cloudconfigclient.New(cloudconfigclient.Local(&http.Client{}, "http://localhost:8888"))
    // or to create a Client for a Spring Config Server using Basic Authentication
    configClient, err = cloudconfigclient.New(cloudconfigclient.Basic(&http.Client{}, "username", "password" "http://localhost:8888"))
    // or to create a Client for a Spring Config Server in Cloud Foundry
    configClient, err = cloudconfigclient.New(cloudconfigclient.DefaultCFService())
    // or to create a Client for a Spring Config Server with OAuth2
    configClient, err = cloudconfigclient.New(cloudconfigclient.OAuth2("config server uri", "client id", "client secret",
        "access token uri"))
    // or a combination of local, Cloud Foundry, and OAuth2
    configClient, err = cloudconfigclient.New(
        cloudconfigclient.Local(&http.Client{}, "http://localhost:8888"),
        cloudconfigclient.DefaultCFService(),
        cloudconfigclient.OAuth2("config server uri", "client id", "client secret", "access token uri"),
    )
    if err != nil {
        fmt.Println(err)
        return
    }
    var file File
    // Retrieves a 'temp1.json' from the Config Server's default branch in directory 'temp' and deserialize to File
    err = configClient.GetFile("temp", "temp1.json", &file)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Printf("%+v\n", file)
    // Retrieves a 'temp2.txt' from the Config Server's default branch in directory 'temp' as a byte slice ([]byte)
    b, err := configClient.GetFileRaw("temp", "temp2.txt")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(string(b))
    // Retrieves the configurations from the Config Server based on the application name and active profiles
    config, err := configClient.GetConfiguration("testApp", "dev")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Printf("%+v", config)
    // if we want, we can convert the config to a struct
    var configStruct Config
    err = config.Unmarshal(&configStruct)
    if err != nil {
        fmt.Println(err)
    }
}
type Config struct {
    Field1 string `json:"example"`
    Field2 int    `json:"field2"`
}

VCAP_SERVICES

When an application is deployed to Cloud Foundry, services can be bounded to the application. When a service is bounded
to an application, the application will have the necessary connection information provided in the environment
variable VCAP_SERVICES.

Structure of the VCAP_SERVICES value

{
  "<service type :: e.g. p-config-server>": [
    {
      "name": "<the service name>",
      "instance_name": "<service name>",
      "binding_name": "<bounded name of the service>",
      "credentials": {
        "uri": "<URI of the service :: used to connect to the service>",
        "client_secret": "<OAuth2 client secret>",
        "client_id": "<OAuth2 client id>",
        "access_token_uri": "<OAuth2 token URI>"
      },
      ...
    }
  ]
}

CredHub Reference

Newer versions of PCF (>=2.6) may have services that use a CredHub Reference to store credential information.

When viewing the Environment Variables of an application via the UI, the credentials may appear as the following

{
  "credentials": {
    "credhub-ref": "/c/example-service-broker/example-service/faa677f5-25cd-4f1e-8921-14a9d5ab48b8/credentials"
  }
}

When the application starts up, the credhub-ref is replaced with the actual credential values that application will
need to connect to the service.

Configurations

The Config Server allows the ability to retrieve configurations for an application. Only files that follow a strict
naming convention will be loaded,

The loaded configurations are in the following JSON format,

{
  "name": "<name of application>",
  "profiles": "<profiles passed in request>",
  "label": "<GIT branch configurations loaded from>",
  "version": "<version>",
  "state": "<state>",
  "propertySources": [
    {
      "<propertySourceName>": {
        "name": "<property source name>",
        "source": {
          "<source path in .properties format>": "<value>"
        }
      }
    }
  ]
}

To use the library to retrieve configurations, create a Client and invoke the
method GetConfiguration(applicationName string, profiles ...string). The return will be the struct representation of
the configuration JSON - client.Configuration.

Resources

Spring’s Config Server allows two ways to retrieve files from a backing repository.

• When retrieving a file from the Config Server’s default branch, the file must not exist at the root of the repository.
• If the directory is in the searchPath, it does not have to be specified (depending on SCCS version)

The functions available to retrieve resource files
are GetFile(directory string, file string, interfaceType interface{}) and
GetFileFromBranch(branch string, directory string, file string, interfaceType interface{}). To retrieve the data from
the files, the functions available are GetFileRaw(directory string, file string) and
GetFileFromBranchRaw(branch string, directory string, file string)

• The interfaceType is the object to deserialize the file to

Spring Cloud Config Server v3.x Changes

The following is only for certain versions of SCCS v3.x. If a file is not being found by the client, the following may
be true.

SCCS v3.x slightly changed how files are retrieved. If the Config Server specified a directory in the searchPaths, the
path should be excluded from the GetFile(..) invocation.

For example if common has been specified in the searchPaths and the file common/foo.txt needs to be retrieved,
then the directory to provide to GetFile(..)
should be "" (blank).

This differs with SCS v2.x where the directory in searchPaths did not impact the directory provided
to GetFile(..) (e.g. to retrieve file common/foo.txt,
directory would be "common").