client

README

Community Go Client for STACKIT

The client is community-supported and not an official STACKIT release, it is maintained by internal Schwarz IT teams integrating with STACKIT

Install

To install the latest stable release, run:

go get github.com/SchwarzIT/community-stackit-go-client@latest

Usage example

To get started, a Service Account[^1] and a Customer Account[^2] must be in place

If you're not sure how to get this information, please contact STACKIT support

package main

import (
	"context"
	"fmt"
	"os"

	client "github.com/SchwarzIT/community-stackit-go-client"
)

func main() {
	c, err := client.New(context.Background(), &client.Config{
		ServiceAccountID: os.Getenv("STACKIT_SERVICE_ACCOUNT_ID"),
		Token:            os.Getenv("STACKIT_SERVICE_ACCOUNT_TOKEN"),
		OrganizationID:   os.Getenv("STACKIT_ORGANIZATION_ID"),
	})
	if err != nil {
		panic(err)
	}

	projectID := "1234-56789-101112"
	bucketName := "example"

	process, err := c.ObjectStorage.Buckets.Create(context.TODO(), projectID, bucketName)
	if err != nil {
		panic(err)
	}

	// wait for bucket to be created
	if _, err := process.Wait(); err != nil {
		panic(err)
	}

	fmt.Printf("bucket '%s' created successfully", bucketName)
}

Further usage examples can be found in terraform-provider-stackit

Auto retry

The client can automatically retry failed calls using pkg/retry

To enable retry in the client, use SetRetry in the following way:

package main

import (
	"context"
	"os"

	client "github.com/SchwarzIT/community-stackit-go-client"
	"github.com/SchwarzIT/community-stackit-go-client/pkg/retry"
)

func main() {
	c, err := client.New(context.Background(), &client.Config{
		ServiceAccountID: os.Getenv("STACKIT_SERVICE_ACCOUNT_ID"),
		Token:            os.Getenv("STACKIT_SERVICE_ACCOUNT_TOKEN"),
		OrganizationID:   os.Getenv("STACKIT_ORGANIZATION_ID"),
	})
	if err != nil {
		panic(err)
	}

	c.SetRetry(retry.New())
}

[^1]: In order to use the client, a Service Account and Token must be created using Service Account API
After creation, assign roles to the Service Account using Membership API
If your Service Account needs to operate outside the scope of your project, you may need to contact STACKIT to assign further permissions

[^2]: The Customer Account ID is also referred to as Organization ID

Documentation

Index

• type AuthAPIClientCredentialFlowRes
• type AuthClient
  • func MockAuthServer() (c *AuthClient, mux *http.ServeMux, teardown func(), err error)
  • func NewAuth(ctx context.Context, cfg *AuthConfig) (*AuthClient, error)
  • func (c *AuthClient) Do(req *http.Request, v interface{}, errorHandlers ...func(*http.Response) error) (*http.Response, error)
  • func (c *AuthClient) GetToken(ctx context.Context) (res AuthAPIClientCredentialFlowRes, err error)
  • func (c *AuthClient) Request(ctx context.Context, method, path string, body string) (*http.Request, error)
• type AuthConfig
  • func (c *AuthConfig) SetURL(value string) error
  • func (c *AuthConfig) Validate() error
• type Client
  • func MockServer() (c *Client, mux *http.ServeMux, teardown func(), err error)
  • func New(ctx context.Context, cfg *Config) (*Client, error)
  • func (c *Client) Do(req *http.Request, v interface{}, errorHandlers ...func(*http.Response) error) (*http.Response, error)
  • func (c *Client) GetConfig() *Config
  • func (c *Client) GetHTTPClient() *http.Client
  • func (c *Client) OrganizationID() string
  • func (c *Client) Request(ctx context.Context, method, path string, body []byte) (*http.Request, error)
  • func (c *Client) Retry() *retry.Retry
  • func (c *Client) SetRetry(r *retry.Retry)
  • func (c *Client) SetToken(token string)
• type Config
  • func (c *Config) SetURL(value string) error
  • func (c *Config) Validate() error
• type IncubatorServices
• type ProductiveServices

Types

type AuthAPIClientCredentialFlowRes

type AuthAPIClientCredentialFlowRes struct {
	AccessToken string `json:"access_token"`
	TokenType   string `json:"token_type"`
	ExpiresIn   int    `json:"expires_in"`
	Scope       string `json:"scope"`
	JTI         string `json:"jti"`
}

AuthAPIClientCredentialFlowRes response structure for client credentials flow

type AuthClient

type AuthClient struct {
	Client *http.Client
	Config *AuthConfig
}

AuthClient manages communication with Auth API

func MockAuthServer

func MockAuthServer() (c *AuthClient, mux *http.ServeMux, teardown func(), err error)

MockAuthServer mocks an authentication server and returns an auth client pointing to it, mux, teardown function and an error indicator

func NewAuth

func NewAuth(ctx context.Context, cfg *AuthConfig) (*AuthClient, error)

NewAuth returns a new Auth API client

func (*AuthClient) Do

func (c *AuthClient) Do(req *http.Request, v interface{}, errorHandlers ...func(*http.Response) error) (*http.Response, error)

Do performs the request and decodes the response if given interface != nil

func (*AuthClient) GetToken

func (c *AuthClient) GetToken(ctx context.Context) (res AuthAPIClientCredentialFlowRes, err error)

GetToken returns a token from Auth API

func (*AuthClient) Request

func (c *AuthClient) Request(ctx context.Context, method, path string, body string) (*http.Request, error)

Request creates an API request

type AuthConfig

type AuthConfig struct {
	BaseUrl      *url.URL
	ClientID     string
	ClientSecret string
}

AuthConfig holds information for using auth API

func (*AuthConfig) SetURL

func (c *AuthConfig) SetURL(value string) error

SetURL sets a given url string as the base url in the config if the given value is empty, the default auth base URL will be used

func (*AuthConfig) Validate

func (c *AuthConfig) Validate() error

Validate verifies that the given config is valid

type Client

type Client struct {

	// Productive services - services that are ready to be used in production
	ProductiveServices

	// Incubator - services under development or currently being tested
	// not ready for production usage
	Incubator IncubatorServices
	// contains filtered or unexported fields
}

Client service for managing interactions with STACKIT API

func MockServer

func MockServer() (c *Client, mux *http.ServeMux, teardown func(), err error)

MockServer mocks STACKIT api server and returns a client pointing to it, mux, teardown function and an error indicator

func New

func New(ctx context.Context, cfg *Config) (*Client, error)

New returns a new client

func (*Client) Do

func (c *Client) Do(req *http.Request, v interface{}, errorHandlers ...func(*http.Response) error) (*http.Response, error)

Do performs the request, including retry if set To set retry, use WithRetry() which returns a shalow copy of the client

func (*Client) GetConfig

func (c *Client) GetConfig() *Config

func (*Client) GetHTTPClient

func (c *Client) GetHTTPClient() *http.Client

func (*Client) OrganizationID

func (c *Client) OrganizationID() string

OrganizationID returns the organization ID defined in the configuration

func (*Client) Request

func (c *Client) Request(ctx context.Context, method, path string, body []byte) (*http.Request, error)

Request creates a new API request

func (*Client) Retry

func (c *Client) Retry() *retry.Retry

Retry returns the defined retry

func (*Client) SetRetry

func (c *Client) SetRetry(r *retry.Retry)

SetRetry overrides default retry setting

func (*Client) SetToken

func (c *Client) SetToken(token string)

type Config

type Config struct {
	BaseUrl          *url.URL
	Token            string
	ServiceAccountID string
	OrganizationID   string
}

Config is the STACKIT client configuration

func (*Config) SetURL

func (c *Config) SetURL(value string) error

SetURL sets a given url string as the base url in the config if the given value is empty, the default base URL will be used

func (*Config) Validate

func (c *Config) Validate() error

Validate verifies that the given config is valid

type IncubatorServices

type IncubatorServices struct {
	Membership      *membership.MembershipService
	ResourceManager *resourceManager.ResourceManagerService
}

IncubatorServices is the struct representing all services that are under development

type ProductiveServices

type ProductiveServices struct {
	Argus         *argus.ArgusService
	Costs         *costs.CostsService
	Kubernetes    *kubernetes.KubernetesService
	ObjectStorage *objectstorage.ObjectStorageService
	Projects      *projects.ProjectService
	Roles         *roles.RolesService
	Users         *users.UsersService
}

ProductiveServices is the struct representing all productive services