README
¶
xconnect - declaring microservices connectivity
Xconnect is a structure in YAML that describes how a service can accept connections and what connections a service needs to operate. With this information, a static overview of the landscape of intercconnected services can be constructed.
how does it work
Every application/service uses some kind of configuration to specifiy what other services is connects to. This can be a database, another service, a filesystem etc. By standardising a part of that configuration, a tool can extract connectivity information from that configuration. This is called the xconnect section.
xonnect section
The xconnect section of a configuration (now YAML only), consists of 3 parts:
- description of what a service can provide by connecting to it, the listen part.
- description of what a service needs to consume or produce to using a connection, the connect part
- metadata about the service such as version, ownership and custom labels.
Not all application configuration is related to connectivity ; the section for connectivity can be part of it. So instead of keeping connection related information separate from the rest of the configuration, with the inevitable effect of becoming out of date, the xconnect section should be integrated in the complete configuration. The actual format of the xconnect data is free-form YAML, meaning that users are free to add their own service metadata if desired.
Use as Go package
This example uses *gopkg.in/yaml.v2* for parsing the configuration.
content, err := ioutil.ReadFile("xconnect.yaml")
var cfg xonnect.Config // use xconnect.Document if your YAML has the top level element called xconnect
err := yaml.Unmarshal(content, &cfg)
Sprint Boot application configration
xconnect:
meta:
listen:
connect:
some-db:
url: jdbc:postgresql://localhost:5432/postgres?reWriteBatchedInserts=true
spring:
datasource:
# use a reference to the actual value, within this document
url: ${xconnect.connect.some-db.url}
To extract the xconnect section using the command line tool:
xconnect -input application.yml -target file://xconnect-from-application.yml
or POST the extracted information to an HTTP endpoint
xconnect -input application.yml -target http://some-service/v1/xconnect
Kubernetes configration (ConfigMap)
apiVersion: v1
data:
xconnect:
meta:
...
listen:
...
connect:
...
kind: ConfigMap
metadata:
creationTimestamp: null
name: some
namespace: somewhere
To extract the xconnect section using the command line tool:
xconnect -input configmap.yml -k8s -target file://xconnect-from-configmap.yml
or using the Go package:
var k8s xconnect.K8SConfiguration
if err = yaml.Unmarshal(yamlContentBytes, &k8s); err != nil {
return
}
cfg, err := k8s.ExtractConfig()
...
Getting the extra fields
See xconnect_test.go
Inspiration
© 2019, ernestmicklei.com. MIT License. Contributions welcome.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Meta MetaConfig `yaml:"meta" json:"meta"`
Listen map[string]ListenEntry `yaml:"listen" json:"listen"`
Connect map[string]ConnectEntry `yaml:"connect" json:"connect"`
}
Config represents the xconnect data section of a YAML document. See spec-xconnect.yaml.
func (Config) DataStore ¶
func (c Config) DataStore(id string) GCPDataStoreEntry
DataStore finds the connect entry in the configuration. Panic with log if it does not.
func (Config) MemoryStore ¶
func (c Config) MemoryStore(id string) GCPMemoryStoreEntry
MemoryStore finds the connect entry in the configuration. Panic with log if it does not.
func (Config) PubSub ¶
func (c Config) PubSub(id string) GCPPubSubEntry
PubSub finds the connect entry in the configuration. Panic with log if it does not.
type ConnectEntry ¶
type ConnectEntry struct {
Scheme string `yaml:"scheme,omitempty" json:"scheme,omitempty"`
TLS *bool `yaml:"tls,omitempty" json:"tls,omitempty"`
Host string `yaml:"host,omitempty" json:"host,omitempty"`
Port *int `yaml:"port,omitempty" json:"port,omitempty"`
URL string `yaml:"url,omitempty" json:"url,omitempty"`
Disabled bool `yaml:"disabled,omitempty" json:"disabled,omitempty"`
ExtraFields map[string]interface{} `yaml:"-,inline"`
// GoogleServices
GCP *GCPEntry `yaml:"gcp,omitempty" json:"gcp,omitempty"`
}
ConnectEntry is a list element in the xconnect.connect config.
func (ConnectEntry) ExtraString ¶
func (e ConnectEntry) ExtraString(path string) string
ExtraString return a string for a give dotted path.
type Document ¶
type Document struct {
Configuration Config `yaml:"xconnect"`
}
Document is the root YAML element
type GCPDataStoreEntry ¶
type GCPDataStoreEntry struct {
Namespace string `yaml:"namespace" json:"namespace"`
}
GCPDataStoreEntry is a Google Cloud Platform Datastore entry in gcp.
type GCPEntry ¶
type GCPEntry struct {
Pubsub *GCPPubSubEntry `yaml:"pubsub,omitempty" json:"pubsub,omitempty"`
MemoryStore *GCPMemoryStoreEntry `yaml:"memorystore,omitempty" json:"memorystore,omitempty"`
DataStore *GCPDataStoreEntry `yaml:"datastore,omitempty" json:"datastore,omitempty"`
}
GCPEntry is a Google Cloud Platform Service entry in connect.
type GCPMemoryStoreEntry ¶
type GCPMemoryStoreEntry struct {
InstanceID string `yaml:"instance-id" json:"instance-id"`
}
GCPMemoryStoreEntry is a Google Cloud Platform MemoryStore entry in gcp.
type GCPPubSubEntry ¶
type GCPPubSubEntry struct {
Subscription string `yaml:"subscription,omitempty" json:"subscription,omitempty"`
Topic string `yaml:"topic,omitempty" json:"topic,omitempty"`
}
GCPPubSubEntry is a Google Cloud Platform PubSub entry in gcp.
type K8SConfiguration ¶
type K8SConfiguration struct {
APIVersion string `yaml:"apiVersion"`
Data map[string]interface{} `yaml:"data"`
Kind string `yaml:"kind" `
Metadata struct {
Name string `yaml:"name" `
Namespace string `yaml:"namespace"`
CreationTimestamp time.Time `yaml:"creationTimestamp"`
} `yaml:"metadata"`
}
K8SConfiguration represents a Kubernetes configuration.
func (K8SConfiguration) ExtractConfig ¶
func (k K8SConfiguration) ExtractConfig() (x Config, err error)
ExtractConfig expects a "xconnect" key in the data map and parses that part into a xconnect.Config.
type ListenEntry ¶
type ListenEntry struct {
Scheme string `yaml:"scheme,omitempty" json:"scheme,omitempty"`
TLS *bool `yaml:"tls,omitempty" json:"tls,omitempty"`
Port *int `yaml:"port,omitempty" json:"port,omitempty"`
Disabled bool `yaml:"disabled,omitempty" json:"disabled,omitempty"`
ExtraFields map[string]interface{} `yaml:"-,inline"`
}
ListenEntry is a list element in the xconnect.accept config.
func (ListenEntry) ExtraString ¶
func (e ListenEntry) ExtraString(path string) string
ExtraString return a string for a give dotted path.
type MetaConfig ¶
type MetaConfig struct {
Name string `yaml:"name,omitempty" json:"name,omitempty"`
Version string `yaml:"version,omitempty" json:"version,omitempty"`
Owner string `yaml:"owner,omitempty" json:"owner,omitempty"`
Labels []string `yaml:"labels,omitempty" json:"labels,omitempty"`
ExtraFields map[string]interface{} `yaml:"-,inline"`
}
MetaConfig represents the meta element in the xconnect data section.
func (MetaConfig) ExtraString ¶
func (m MetaConfig) ExtraString(path string) string
ExtraString return a string for a give dotted path.
Source Files
Directories