From c22738e739daae77422827b34966d953c566d027 Mon Sep 17 00:00:00 2001 From: Nathan Slaughter <28688390+nslaughter@users.noreply.github.com> Date: Fri, 16 Jun 2023 14:03:55 -0500 Subject: [PATCH 1/3] draft Spec --- tools/internal/spec/spec.go | 77 +++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 tools/internal/spec/spec.go diff --git a/tools/internal/spec/spec.go b/tools/internal/spec/spec.go new file mode 100644 index 0000000..233096e --- /dev/null +++ b/tools/internal/spec/spec.go @@ -0,0 +1,77 @@ +package spec + +type Spec struct { + Version string `json:"version,omitempty"` // spec version - we can use this to determine how to parse the spec + ID string `json:"id"` // unique id for the service + Name string `json:"name"` // name of the service - e.g. Cassandra, MongoDB + Author Author `json:"author,omitempty"` + Tags []string `json:"tags,omitempty"` // like categories + Status string `json:"status,omitempty"` // e.g. stable, beta, deprecated + + // Testing/Certification: [app versions] x collector version x [auxiliary app versions] + + Signals []SignalData `json:"signals,omitempty"` + Images []ImageData `json:"images,omitempty"` + Changelog Changelog `json:"changelog,omitempty"` + + Components []Component `json:"components,omitempty"` +} + +type SignalData struct { + Name string `json:"name,omitempty"` + Type string `json:"type,omitempty"` + Path string `json:"path,omitempty"` +} + +type ImageData struct { + Name string `json:"name,omitempty"` + Description string `json:"description,omitempty"` + Path string `json:"path,omitempty"` +} + +type Change struct { + Description string `json:"description,omitempty"` + Date string `json:"date,omitempty"` +} + +type Changelog struct { + Path string `json:"path,omitempty"` + Changes []Change `json:"changes,omitempty"` +} + +type Example struct { + Name string `json:"name,omitempty"` + Platform string `json:"platform,omitempty"` + Files []File `json:"files,omitempty"` +} + +type File struct { + Name string `json:"name,omitempty"` + Description string `json:"description,omitempty"` + Path string `json:"path,omitempty"` + content []byte `json:"content,omitempty"` +} + +type FileSet map[string]File `json:"file_set,omitempty"` + +func (f *FileSet) Add(file File) { + (*f)[file.Path + file.Name] = file +} + +func (f *FileSet) Render() error { + // TODO: implement this to write generate and store each file + return nil +} + +func GenerateRepoReadme() ([]byte, error) { + // 1. get the template? + // 2. execute the template + // 3. data is what's in repo + return nil, nil +} + +type Component interface { + // paths within each component are relative to the integration package root + // so this argument can set the path to the component root + Render() error +} From c8d3b1f1c72cf65ef680c0b34d31b9b894f909a2 Mon Sep 17 00:00:00 2001 From: Nathan Slaughter <28688390+nslaughter@users.noreply.github.com> Date: Fri, 21 Jul 2023 10:14:54 -0500 Subject: [PATCH 2/3] update spec --- tools/internal/spec/spec.go | 123 +++++++++++++++++++----------------- 1 file changed, 65 insertions(+), 58 deletions(-) diff --git a/tools/internal/spec/spec.go b/tools/internal/spec/spec.go index 233096e..45bf5ef 100644 --- a/tools/internal/spec/spec.go +++ b/tools/internal/spec/spec.go @@ -1,32 +1,76 @@ package spec -type Spec struct { - Version string `json:"version,omitempty"` // spec version - we can use this to determine how to parse the spec - ID string `json:"id"` // unique id for the service - Name string `json:"name"` // name of the service - e.g. Cassandra, MongoDB - Author Author `json:"author,omitempty"` - Tags []string `json:"tags,omitempty"` // like categories - Status string `json:"status,omitempty"` // e.g. stable, beta, deprecated +/* +With the intended behavior of Template you can scaffold an integration package with +just a few entries. Here's a speculative example of YAML you'll find to build something +like we created for couchdb in the examples repo... - // Testing/Certification: [app versions] x collector version x [auxiliary app versions] +```yaml +version: 0.0.1 +name: CouchDB +id: couchdb +author: Nathan Slaughter +status: development +vars: - Signals []SignalData `json:"signals,omitempty"` - Images []ImageData `json:"images,omitempty"` - Changelog Changelog `json:"changelog,omitempty"` + receiver: + endpoint: http://couchdb:5984 + username: otelu + password: otelp + collection_interval: 10s + environment: + COUCHDB_USER: otelu + COUCHDB_PASSWORD: otelp + ports: + metrics: 5984 + app: 5986 - Components []Component `json:"components,omitempty"` -} +templates: + - names: ["compose/appreceiver/solo"] + location: examples/compose/docker-compose.yml + - names: ["compose/appreceiver/cluster"] + vars: + nodes: 3 + environment: + NODENAME: + location: examples/compose/docker-compose.cluster.yml + - names: ["compose/", ""] + +``` -type SignalData struct { - Name string `json:"name,omitempty"` - Type string `json:"type,omitempty"` - Path string `json:"path,omitempty"` +This would seem valuable as it's 27 lines replacing 164 lines. But what's just as important is that every aspect of +our integration packages that we can manage through templates can now be changed in mass. This gives us flexibility +to apply the data for multiple purposes. Using concise data for each integration that captures only what's different in each case will provide us considerably + +The primary use cases that I'm contemplating are for testing. But this +becomes a valuable +gathering data +*/ +type Template struct { + Name string // used to lookup the template in project + Location string // relative path where template is rendered + Vars map[string]string } -type ImageData struct { - Name string `json:"name,omitempty"` - Description string `json:"description,omitempty"` - Path string `json:"path,omitempty"` +type Spec struct { + Version string `json:"version,omitempty"` // spec version - we can use this to determine how to parse the spec + ID string `json:"id"` // unique id for the service + Name string `json:"name"` // name of the service - e.g. Cassandra, MongoDB + Author Author `json:"author,omitempty"` + Categories []string `categories:"tags,omitempty"` // provides context on particular things relevant to the integration + Status string `json:"status,omitempty"` // e.g. (development|experimental|supported) + /* TODO: + Make an IntegrationStatus type with statuses like + - deprecated - we will fix bugs, but the legacy package may remain temporarily as a resource while customers migrate + - development - this integration doesn't yet include a dashboard + - experimental - uses an unsupported approach though it is what we would recommend to a customer + - supported - we intend to maintain + */ + Matrix Matrix `json:"matrix,omitempty"` + Vars map[string]string + Templates []Template `json:"templates,omitempty"` + Assets []Asset `json:"assets,omitempty"` + Changelog Changelog `json:"changelog,omitempty"` } type Change struct { @@ -38,40 +82,3 @@ type Changelog struct { Path string `json:"path,omitempty"` Changes []Change `json:"changes,omitempty"` } - -type Example struct { - Name string `json:"name,omitempty"` - Platform string `json:"platform,omitempty"` - Files []File `json:"files,omitempty"` -} - -type File struct { - Name string `json:"name,omitempty"` - Description string `json:"description,omitempty"` - Path string `json:"path,omitempty"` - content []byte `json:"content,omitempty"` -} - -type FileSet map[string]File `json:"file_set,omitempty"` - -func (f *FileSet) Add(file File) { - (*f)[file.Path + file.Name] = file -} - -func (f *FileSet) Render() error { - // TODO: implement this to write generate and store each file - return nil -} - -func GenerateRepoReadme() ([]byte, error) { - // 1. get the template? - // 2. execute the template - // 3. data is what's in repo - return nil, nil -} - -type Component interface { - // paths within each component are relative to the integration package root - // so this argument can set the path to the component root - Render() error -} From 9176de973faebc9c2511cf5fee5b8965f606dfa2 Mon Sep 17 00:00:00 2001 From: Nathan Slaughter <28688390+nslaughter@users.noreply.github.com> Date: Tue, 25 Jul 2023 16:56:17 -0500 Subject: [PATCH 3/3] update spec --- tools/internal/spec/spec.go | 43 +++++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 6 deletions(-) diff --git a/tools/internal/spec/spec.go b/tools/internal/spec/spec.go index 45bf5ef..bef099a 100644 --- a/tools/internal/spec/spec.go +++ b/tools/internal/spec/spec.go @@ -12,12 +12,12 @@ id: couchdb author: Nathan Slaughter status: development vars: - receiver: endpoint: http://couchdb:5984 username: otelu password: otelp collection_interval: 10s + image: couchdb environment: COUCHDB_USER: otelu COUCHDB_PASSWORD: otelp @@ -25,19 +25,50 @@ vars: metrics: 5984 app: 5986 +# remove plural of name + +---------- +templates: + - dynamically rendered with vars +assets: + - any file that is static +---------- + +examples: + vars: + + # is it static - this example .. or template + + - templates: + - name: + location: + +dashboards: + - +alerts: + - +images: + - +---------- + templates: - names: ["compose/appreceiver/solo"] location: examples/compose/docker-compose.yml - names: ["compose/appreceiver/cluster"] vars: - nodes: 3 - environment: - NODENAME: + nodes: 3 + environment: + NODENAME: `` location: examples/compose/docker-compose.cluster.yml - - names: ["compose/", ""] - +assets: + - ``` +Top-level values can be used throughout all of the templates. + +- How to configure for compose +- How to configure template for app config file + This would seem valuable as it's 27 lines replacing 164 lines. But what's just as important is that every aspect of our integration packages that we can manage through templates can now be changed in mass. This gives us flexibility to apply the data for multiple purposes. Using concise data for each integration that captures only what's different in each case will provide us considerably