118 lines
4.7 KiB
Go
118 lines
4.7 KiB
Go
/*
|
|
Package pkger implements a means to create and consume reusable
|
|
templates for what will eventually come to support all influxdb
|
|
resources.
|
|
|
|
The parser supports JSON, Jsonnet, and YAML encodings as well as a number
|
|
of different ways to read the file/reader/string as it may. While the parser
|
|
supports Jsonnet, due to issues in the go-jsonnet implementation, only trusted
|
|
input should be given to the parser and therefore the EnableJsonnet() option
|
|
must be used with Parse() to enable Jsonnet support.
|
|
|
|
As an example, you can use the following to parse and validate a YAML
|
|
file and see a summary of its contents:
|
|
|
|
newTemplate, err := Parse(EncodingYAML, FromFile(PATH_TO_FILE))
|
|
if err != nil {
|
|
panic(err) // handle error as you see fit
|
|
}
|
|
sum := newTemplate.Summary()
|
|
fmt.Println(sum) // do something with the summary
|
|
|
|
The parser will validate all contents of the template and provide any
|
|
and all fields/entries that failed validation.
|
|
|
|
If you wish to use the Template type in your transport layer and let the
|
|
transport layer manage the decoding, then you can run the following
|
|
to validate the template after the raw decoding is done:
|
|
|
|
if err := template.Validate(); err != nil {
|
|
panic(err) // handle error as you see fit
|
|
}
|
|
|
|
If a validation error is encountered during the validation or parsing then
|
|
the error returned will be of type *parseErr. The parseErr provides a rich
|
|
set of validations failures. There can be numerous failures in a template
|
|
and we did our best to inform the caller about them all in a single run.
|
|
|
|
If you want to see the effects of a template before applying it to the
|
|
organization's influxdb platform, you have the flexibility to dry run the
|
|
template and see the outcome of what would happen after it were to be applied.
|
|
You may use the following to dry run a template within your organization:
|
|
|
|
svc := NewService(serviceOpts...)
|
|
summary, diff, err := svc.DryRun(ctx, orgID, userID, ApplyWithTemplate(template))
|
|
if err != nil {
|
|
panic(err) // handle error as you see fit
|
|
}
|
|
// explore the summary and diff
|
|
|
|
The diff provided here is a diff of the existing state of the platform for
|
|
your organization and the concluding the state after the application of a
|
|
template. All buckets, labels, and variables, when given a name that already
|
|
exists, will not create a new resource, but rather, will edit the existing
|
|
resource. If this is not a desired result, then rename your bucket to something
|
|
else to avoid the imposed changes applying this template would incur. The summary
|
|
provided is a summary of the template itself. If a resource exists all IDs will
|
|
be populated for them, if they do not, then they will be zero values. Any zero
|
|
value ID is safe to assume is not populated. All influxdb.ID's must be non zero
|
|
to be in existence.
|
|
|
|
If you would like to apply a template you may use the service to do so. The
|
|
following will apply the template in full to the provided organization.
|
|
|
|
svc := NewService(serviceOpts...)
|
|
summary, err := svc.Apply(ctx, orgID, userID, ApplyWithTemplate(template))
|
|
if err != nil {
|
|
panic(err) // handle error as you see fit
|
|
}
|
|
// explore the summary
|
|
|
|
The summary will be populated with valid IDs that were created during the
|
|
application of the template. If an error is encountered during the application
|
|
of a template, then all changes that had occurred will be rolled back. However, as
|
|
a warning for buckets, changes may have incurred destructive changes. The changes
|
|
are not applied inside a large transaction, for numerous reasons, but it is
|
|
something to be considered. If you have dry run the template before it is to be
|
|
applied, then the changes should have been made known to you. If not, then there is
|
|
potential loss of data if the changes to a bucket resulted in the retention period
|
|
being shortened in the template.
|
|
|
|
If you would like to export existing resources into the form of a template, then you
|
|
have the ability to do so using the following:
|
|
|
|
resourcesToClone := []ResourceToClone{
|
|
{
|
|
Kind: KindBucket,
|
|
ID: Existing_BUCKET_ID,
|
|
Name: "new bucket name"
|
|
},
|
|
{
|
|
Kind: KindDashboard,
|
|
ID: Existing_Dashboard_ID,
|
|
},
|
|
{
|
|
Kind: KindLabel,
|
|
ID: Existing_Label_ID,
|
|
},
|
|
{
|
|
Kind: KindVarible,
|
|
ID: Existing_Var_ID,
|
|
},
|
|
}
|
|
|
|
svc := NewService(serviceOpts...)
|
|
newTemplate, err := svc.Export(ctx, ExportWithExistingResources(resourcesToClone...))
|
|
if err != nil {
|
|
panic(err) // handle error as you see fit
|
|
}
|
|
// explore newly created and validated template
|
|
|
|
Things to note about the behavior of exporting existing resources. All label
|
|
associations with existing resources will be included in the new template.
|
|
However, the variables that are used within a dashboard query will not be added
|
|
automatically to the template. Variables will need to be passed in alongside
|
|
the dashboard to be added to the template.
|
|
*/
|
|
package pkger
|