nobl9-go

module
v0.89.0-rc9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2024 License: MPL-2.0

README

N9

checks tests vulnerabilities

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:

  1. Installation
  2. Examples
  3. Usage
  4. Repository structure
  5. Contributing

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

  1. 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 as sloctl or the SDK itself.
    • Methods for fetching and parsing Nobl9 configuration objects.
  2. 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)
    
    • manifest defines general contracts and generic methods for all objects.
    • Version-specific packages, such as v1alpha, define version-specific APIs, functions and structures shared by multiple objects.
    • Object-specific packages, like slo, provide object definition for specific object versions.

Internal packages

  1. tests contains the end-to-end tests code. These tests are run directly against a Nobl9 platform.
  2. 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.
sdk
Package sdk provide an abstraction for communication with API.
Package sdk provide an abstraction for communication with API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL