IBMCloudEnv

README

IBM Cloud Environment

The ibm-cloud-env-golang package allows for the abstraction of environment variables from various Cloud compute providers, such as, but not limited to, CloudFoundry and Kubernetes, so the application can be environment-agnostic.

The package allows for an array of search patterns that will be executed one by one until required value is found.

Installation

go get github.com/ibm-developer/ibm-cloud-env-golang

Usage

Create a JSON file containing your mappings and initialize the package

import "github.com/ibm-developer/ibm-cloud-env-golang"

//in main function 
IBMCloudEnv.Initialize("/path/to/the/mappings/file/relative/to/prject/root")

Supported search patterns types

ibm-cloud-config supports searching for values using four search pattern types - user-provided, cloudfoundry, env, file.

• Using user-provided allows to search for values in VCAP_SERVICES for service credentials
• Using cloudfoundry allows to search for values in VCAP_SERVICES and VCAP_APPLICATIONS environment variables
• Using env allows to search for values in environment variables
• Using file allows to search for values in text/json files

Example search patterns

• user-provided:service-instance-name:credential-key - searches through parsed VCAP_SERVICES environment variable and returns the value of the requested service name and credential
• cloudfoundry:service-instance-name - searches through parsed VCAP_SERVICES environment variable and returns the credentials object of the matching service instance name
• cloudfoundry:$.JSONPath - searches through parsed VCAP_SERVICES and VCAP_APPLICATION environment variables and returns the value that corresponds to JSONPath
• env:env-var-name - returns environment variable named "env-var-name"
• env:env-var-name:$.JSONPath - attempts to parse the environment variable "env-var-name" and return a value that corresponds to JSONPath
• file:/server/config.text - returns content of /server/config.text file
• file:/server/config.json:$.JSONPath - reads the content of /server/config.json file, tries to parse it, returns the value that corresponds to JSONPath

mappings.json file example

{
    "service1-credentials": {
        "searchPatterns": [
            "user-provided:my-service1-instance-name:service1-credentials",
            "cloudfoundry:my-service1-instance-name", 
            "env:my-service1-credentials", 
            "file:/localdev/my-service1-credentials.json" 
        ]
    },
    "service2-username": {
        "searchPatterns":[
            "user-provided:my-service2-instance-name:username",
            "cloudfoundry:$.service2[@.name=='my-service2-instance-name'].credentials.username",
            "env:my-service2-credentials:$.username",
            "file:/localdev/my-service1-credentials.json:$.username"
        ]
    }
}

Using the values in application

In your application retrieve the values using below commands

service1credentials := IBMCloudEnv.GetDictionary("service1-credentials") // this will be a dictionary
service2username := IBMCloudEnv.GetString("service2-username") // this will be a string

Following the above approach your application can be implemented in an runtime-environment agnostic way, abstracting differences in environment variable management introduced by different cloud compute providers.

Filter the values for tags and labels

In your application, you can filter credentials generated by the package based on service tags and service labels.

filtered_credentials := IBMCloudEnv.GetCredentialsForService(tag, label, credentials) // returns a map of string to strings with credentials for specified service tag and label

Publishing Changes

In order to publish changes, you will need to fork the repository or ask to join the ibm-developer org and branch off the master branch.

Make sure to follow the conventional commit specification before contributing. To help you with commit a commit template is provide. Run config.sh to initialize the commit template to your .git/config

Once you are finished with your changes, run go test to make sure all tests pass.

Do a pull request against master, make sure the build passes. A team member will review and merge your pull request.

Documentation

Index

• Constants
• func GetCredentialsForService(serviceTag, serviceLabel, credentials string) map[string]string
• func GetDictionary(name string) gjson.Result
• func GetString(name string) (string, bool)
• func Initialize(mappingsFilePath string) string

Constants

const PREFIX_PATTERN_CF = "cloudfoundry"

const PREFIX_PATTERN_ENV = "env"

const PREFIX_PATTERN_FILE = "file"

const PREFIX_PATTERN_USER = "user-provided"

Functions

func GetCredentialsForService

func GetCredentialsForService(serviceTag, serviceLabel, credentials string) map[string]string

func GetDictionary

func GetDictionary(name string) gjson.Result

func GetString

func GetString(name string) (string, bool)

func Initialize

func Initialize(mappingsFilePath string) string