README ¶
Nobl9 SDK for the Go programming language.
Checkout release notes for details on the latest bug fixes, updates, and features.
⚠️ Until v1.0.0 is released, we expect some minor breaking API changes to be introduced.
Legend:
Installation
To add the latest version to your Go module run:
go get github.com/nobl9/nobl9-go
Examples
Basic usage
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"github.com/nobl9/nobl9-go/manifest"
"github.com/nobl9/nobl9-go/manifest/v1alpha"
"github.com/nobl9/nobl9-go/manifest/v1alpha/project"
"github.com/nobl9/nobl9-go/manifest/v1alpha/service"
"github.com/nobl9/nobl9-go/sdk"
objectsV1 "github.com/nobl9/nobl9-go/sdk/endpoints/objects/v1"
)
func main() {
ctx := context.Background()
// Create client.
client, err := sdk.DefaultClient()
if err != nil {
log.Fatalf("failed to create sdk client, err: %v", err)
}
// Read from file, url or glob pattern.
objects, err := sdk.ReadObjects(ctx, "./project.yaml")
if err != nil {
log.Fatalf("failed to read project.yaml file, err: %v", err)
}
// Use manifest.FilterByKind to extract specific objects from the manifest.Object slice.
myProject := manifest.FilterByKind[project.Project](objects)[0]
// Define objects in code.
myService := service.New(
service.Metadata{
Name: "my-service",
DisplayName: "My Service",
Project: myProject.GetName(),
Labels: v1alpha.Labels{
"team": []string{"green", "orange"},
"region": []string{"eu-central-1"},
},
},
service.Spec{
Description: "Example service",
},
)
objects = append(objects, myService)
// Verify the objects.
if errs := manifest.Validate(objects); len(errs) > 0 {
log.Fatalf("service validation failed, errors: %v", errs)
}
// Apply the objects.
if err = client.Objects().V1().Apply(ctx, objects); err != nil {
log.Fatalf("failed to apply objects, err: %v", err)
}
// Get the applied resources.
services, err := client.Objects().V1().GetV1alphaServices(ctx, objectsV1.GetServicesRequest{
Project: myProject.GetName(),
Names: []string{myService.GetName()},
})
if err != nil {
log.Fatalf("failed to get services, err: %v", err)
}
projects, err := client.Objects().V1().GetV1alphaProjects(ctx, objectsV1.GetProjectsRequest{
Names: []string{myProject.GetName()},
})
if err != nil {
log.Fatalf("failed to get projects, err: %v", err)
}
// Aggregate objects back into manifest.Objects slice.
appliedObjects := make([]manifest.Object, 0, len(services)+len(projects))
for _, service := range services {
appliedObjects = append(appliedObjects, service)
}
for _, project := range projects {
appliedObjects = append(appliedObjects, project)
}
// Print JSON representation of these objects.
data, err := json.MarshalIndent(appliedObjects, "", " ")
if err != nil {
log.Fatalf("failed to marshal objects, err: %v", err)
}
fmt.Println(string(data))
// Delete resources.
if err = client.Objects().V1().Delete(ctx, objects); err != nil {
log.Fatalf("failed to delete objects, err: %v", err)
}
}
Usage
Reading configuration
In order for sdk.Client
to work, it needs to be configured.
The configuration can be read from a file, environment variables,
code options or a combination of these.
The precedence of the configuration sources is as follows (starting from the highest):
- Code options
- Environment variables
- Configuration file
- Default values
The following flowchart illustrates the process of reading the configuration:
flowchart TD
subgraph s1[Read config file]
direction LR
As1{{Config file exists}} -- true --> Bs1(Read config file)
As1 -- false --> Cs1(Create default config file)
Cs1 --> Bs1
end
subgraph s2[Build config struct]
direction LR
As2{{Has ConfigOption}} -- not set --> Bs2{{Has env variable}}
As2 -- set --> Fs2(Use value)
Bs2 -- not set --> Cs2{{Has config file option}}
Bs2 -- set --> Fs2
Cs2 -- not set --> Ds2{{Has default value}}
Cs2 -- set --> Fs2
Ds2 -- not set --> Es2(No value)
Ds2 -- set --> Fs2
end
A(Read config) --> B(Read config options defined in code)
B --> C(Read env variables)
C --> s1
s1 --> s2 --> I(Return Config)
Testing code relying on nobl9-go
Checkout these instructions
along with a working example for recommendations on mocking sdk.Client
.
Repository structure
Public packages
-
sdk defines:
Client
which exposes methods for interacting with different Nobl9 web APIs.- Methods for reading and managing Nobl9
configuration (including the
config.toml
file) used by tools such assloctl
or the SDK itself. - Methods for fetching and parsing Nobl9 configuration objects.
-
manifest holds definitions of all Nobl9 configuration objects, such as SLO or Project. It is divided into three package levels:
└── manifest └── version (e.g. v1alpha) └── object (e.g. slo)
Internal packages
- tests contains the end-to-end tests code. These tests are run directly against a Nobl9 platform.
- internal holds internal packages that are not meant to be exposed as part of the library's API.
Contributing
Checkout both contributing guidelines and development instructions.
Directories ¶
Path | Synopsis |
---|---|
internal
|
|
Package manifest defines the basic primitives for Nobl9 objects schema.
|
Package manifest defines the basic primitives for Nobl9 objects schema. |
v1alpha
Package v1alpha represents objects available in API n9/v1alpha
|
Package v1alpha represents objects available in API n9/v1alpha |
v1alpha/agent
Package agent defines Agent object definitions.
|
Package agent defines Agent object definitions. |
v1alpha/alert
Package alert defines Alert object definitions.
|
Package alert defines Alert object definitions. |
v1alpha/alertmethod
Package alertmethod defines AlertMethod object definitions.
|
Package alertmethod defines AlertMethod object definitions. |
v1alpha/alertpolicy
Package alertpolicy defines AlertPolicy object definitions and validation.
|
Package alertpolicy defines AlertPolicy object definitions and validation. |
v1alpha/alertsilence
Package alertsilence defines AlertSilence object definitions.
|
Package alertsilence defines AlertSilence object definitions. |
v1alpha/annotation
Package annotation defines Annotation object definitions.
|
Package annotation defines Annotation object definitions. |
v1alpha/budgetadjustment
Package budgetadjustment defines BudgetAdjustment object definitions.
|
Package budgetadjustment defines BudgetAdjustment object definitions. |
v1alpha/dataexport
Package dataexport defines DataExport object definitions.
|
Package dataexport defines DataExport object definitions. |
v1alpha/direct
Package direct defines Direct object definitions.
|
Package direct defines Direct object definitions. |
v1alpha/parser
Package parser provides parsing methods for v1alpha objects.
|
Package parser provides parsing methods for v1alpha objects. |
v1alpha/project
Package project defines Project object definitions.
|
Package project defines Project object definitions. |
v1alpha/report
Package report defines Report object definitions.
|
Package report defines Report object definitions. |
v1alpha/rolebinding
Package rolebinding defines RoleBinding object definitions.
|
Package rolebinding defines RoleBinding object definitions. |
v1alpha/service
Package service defines Service object definitions.
|
Package service defines Service object definitions. |
v1alpha/slo
Package slo defines SLO object definitions.
|
Package slo defines SLO object definitions. |
v1alpha/twindow
Package twindow provides enums and functions to operate with resources related to Time Windows
|
Package twindow provides enums and functions to operate with resources related to Time Windows |
v1alpha/usergroup
Package usergroup defines UserGroup object definitions.
|
Package usergroup defines UserGroup object definitions. |
Package sdk provide an abstraction for communication with API.
|
Package sdk provide an abstraction for communication with API. |
endpoints/authdata
Package authdata aggregates API endpoints' versions which are related to authentication data such as fetching agent credentials.
|
Package authdata aggregates API endpoints' versions which are related to authentication data such as fetching agent credentials. |
endpoints/authdata/v1
Package v1 defines methods for managing various authentication data.
|
Package v1 defines methods for managing various authentication data. |
endpoints/objects
Package objects aggregates manifest.Object API endpoints' versions.
|
Package objects aggregates manifest.Object API endpoints' versions. |
endpoints/objects/v1
Package v1 defines methods for managing manifest.Object.
|
Package v1 defines methods for managing manifest.Object. |
endpoints/slostatusapi
Package slostatusapi provides the API for managing SLO status API requests in the SDK.
|
Package slostatusapi provides the API for managing SLO status API requests in the SDK. |
endpoints/slostatusapi/v1
Package v1 provides the API for managing SLO status API V1 requests in the SDK.
|
Package v1 provides the API for managing SLO status API V1 requests in the SDK. |
endpoints/slostatusapi/v2
Package v2 provides the API for managing SLO status API V2 requests in the SDK.
|
Package v2 provides the API for managing SLO status API V2 requests in the SDK. |
models
Package models defines sdk.Client API request and response models.
|
Package models defines sdk.Client API request and response models. |