stackit

README

Community Go Client for STACKIT

This is a Go client designed to help developers interact with STACKIT APIs. It is maintained by the STACKIT community within Schwarz IT.

 

Installation

To install the community-stackit-go-client package, run the following command:

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

 

Usage

package main

import (
    "context"
    "fmt"

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

func main() {
    ctx := context.Background()
    c := stackit.MustNewClientWithKeyAuth(ctx)

    res, err := c.Kubernetes.ProviderOptions.List(ctx)
    if err = validate.Response(res, err, "JSON200.AvailabilityZones"); err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println("STACKIT Kubernetes Engine (SKE) availability zones:")
    for _, zone := range *res.JSON200.AvailabilityZones {
        if zone.Name == nil {
            continue
        }
        fmt.Printf("- %s\n", *zone.Name)
    }
}

1. Copy the code above to a file called example.go

2. Make sure environment variables for key flow are in place (read more in the Authentication section below)

3. Now you can run the example with the following command:

   go run example.go
   

   output should look similar to:

   STACKIT Kubernetes Engine (SKE) availability zones:
   - eu01-m
   - eu01-1
   - eu01-2
   - eu01-3
   

Further Examples

1. Under /examples directory
2. In our terraform-provider-stackit

 

Authentication

Before you can start using the client, you will need to create a STACKIT Service Account in your project and assign it the appropriate permissions (i.e. project.owner).

After the service account has been created, you can authenticate to the client using the Key authentication flow (recommended) or with the static Token flow (less secure as the token is long-lived).

Key flow

⚠️ Currently, setting up Key flow requires a slightly more technical approach as it is not yet available in the portal UI.

1. Create an RSA key pair:

   openssl req -x509 -nodes -newkey rsa:2048 -days 365 \
      -keyout private_key.pem -out public_key.pem -subj "/CN=unused"
   

2. Create a serivce account in one of your STACKIT projects & make sure to assign permissions to it

3. Get your access token from the portal (from the developer tools, network tab)

4. Create a service account key:

   • Create a file called create_sa_key.go and put it in the same directory as the RSA key pair

   • Copy the contents of examples/service-accounts/create_sa_key.go to create_sa_key.go and fill out the constants

   • Run with:

     go run create_sa_key.go
     

   • a file called sa_key.json will be created

5. Set environment variables:

   export STACKIT_SERVICE_ACCOUNT_KEY_PATH="sa_key.json"
   export STACKIT_PRIVATE_KEY_PATH="private_key.pem"
   

6. Configure the client

   package main
   
   import (
       "context"
       stackit "github.com/SchwarzIT/community-stackit-go-client"
   )
   
   func main() {
       ctx := context.Background()
       c := stackit.MustNewClientWithKeyAuth(ctx)
       // ...
   }
   

Token flow

1. Create a serivce account in one of your STACKIT projects & make sure to assign permissions to it

2. Set the following environment variables:

   export STACKIT_SERVICE_ACCOUNT_EMAIL=email
   export STACKIT_SERVICE_ACCOUNT_TOKEN=token
   

3. Configure the client

   package main
   
   import (
       "context"
       stackit "github.com/SchwarzIT/community-stackit-go-client"
   )
   
   func main() {
       ctx := context.Background()
       c := stackit.MustNewClientWithTokenAuth(ctx)
       // ...
   }
   

 

Working with non-prod environments

For each service package there's an overriding environment variable for the base URL

they are defined for every service in service.go according to the specified package name

the pattern is STACKIT_${package}_BASEURL

example: STACKIT_KUBERNETES_BASEURL or STACKIT_LOGME_BASEURL

Key authentication for non-prod

for token API set STACKIT_TOKEN_BASEURL

and for jwks.json url set STACKIT_JWKS_BASEURL

 

Contributing

If you find a bug or have an idea for a new feature, feel free to submit an issue or pull request!

Please make sure to include tests for any new functionality you add, and to run the existing tests before submitting your changes.

 

License

This project is licensed under the Apache-2.0 license - see the LICENSE file for details.

Documentation

Index

• func MustNewClientWithKeyAuth(ctx context.Context, cfg ...clients.KeyFlowConfig) *services.Services
• func MustNewClientWithTokenAuth(ctx context.Context, cfg ...clients.TokenFlowConfig) *services.Services
• func NewClientWithKeyAuth(ctx context.Context, cfg ...clients.KeyFlowConfig) (*services.Services, error)
• func NewClientWithTokenAuth(ctx context.Context, cfg ...clients.TokenFlowConfig) (*services.Services, error)

Functions

func MustNewClientWithKeyAuth

func MustNewClientWithKeyAuth(ctx context.Context, cfg ...clients.KeyFlowConfig) *services.Services

MustNewClientWithKeyAuth panics if client initialization failed

func MustNewClientWithTokenAuth

func MustNewClientWithTokenAuth(ctx context.Context, cfg ...clients.TokenFlowConfig) *services.Services

MustNewClientWithTokenAuth panics if client initialization failed

func NewClientWithKeyAuth

func NewClientWithKeyAuth(ctx context.Context, cfg ...clients.KeyFlowConfig) (*services.Services, error)

NewClientWithKeyAuth creates a new client that authenticates itself with STACKIT APIs using a service account key and a private RSA key this is the recommended way of authenticating to STACKIT API

func NewClientWithTokenAuth

func NewClientWithTokenAuth(ctx context.Context, cfg ...clients.TokenFlowConfig) (*services.Services, error)

NewClientWithTokenAuth creates a new client that authenticates itself with STACKIT APIs using a service account token important: this approach is less secure, as the token has a long lifespan