Overview

This repository contains the published SDKs and SDK releases. The modules are structured into a core module with service clients, authentication and shared functionality as well as the different STACKIT services. The usage of the SDK is shown in some examples.

Getting started

Requires Go 1.18 or higher.

To download the core module:

go mod download github.com/stackitcloud/stackit-sdk-go/core

To download the services/dns module:

go mod download github.com/stackitcloud/stackit-sdk-go/services/dns

Examples

This is an example on how to do create a client and interact with the STACKIT DNS service for reading and creating DNS zones. As prerequisite, you need a STACKIT project with its project ID. The setup of the authentication is describe below in section Authentication in more detail.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/stackitcloud/stackit-sdk-go/services/dns"
)

func main() {
	// Specify the project ID
	projectId := "PROJECT_ID"

	// Create a new API client, that uses default authentication and configuration
	dnsClient, err := dns.NewAPIClient()
	if err != nil {
		fmt.Fprintf(os.Stderr, "[DNS API] Creating API client: %v\n", err)
		os.Exit(1)
	}

	// Get the DNS Zones for your project
	var getZoneResp *dns.ZonesResponse
	getZoneResp, err = dnsClient.GetZones(context.Background(), projectId).Execute()

	// Get only active DNS Zones for your project by adding the filter "ActiveEq(true)" to the call. More filters are available and can be chained.
	// dnsRespGetZones, err := dnsClient.ZoneApi.GetZones(context.Background(), projectId).ActiveEq(true).Execute()

	if err != nil {
		fmt.Fprintf(os.Stderr, "[DNS API] Error when calling `ZoneApi.GetZones`: %v\n", err)
	} else {
		fmt.Printf("[DNS API] Number of zones: %v\n", len(getZoneResp.Zones))
	}

	// Create a DNS Zone
	createZonePayload := dns.CreateZonePayload{
		Name:    "myZone",
		DnsName: "testZone.com",
	}
	var createZoneResp *dns.ZoneResponse
	createZoneResp, err = dnsClient.CreateZone(context.Background(), projectId).CreateZonePayload(createZonePayload).Execute()
	if err != nil {
		fmt.Fprintf(os.Stderr, "[DNS API] Error when calling `ZoneApi.CreateZone`: %v\n", err)
	} else {
		var createdZone dns.Zone = createZoneResp.Zone
		fmt.Printf("[DNS API] Created zone \"%s\" with DNS name \"%s\" and zone id \"%s\".\n", createdZone.Name, createdZone.DnsName, createdZone.Id)
	}

	// Get a record set of a DNS zone.
	var recordSetResp *dns.RecordSetResponse
	recordSetResp, err = dnsClient.GetRecordSet(context.Background(), projectId, "zoneId", "recordSetId").Execute()
	if err != nil {
		fmt.Fprintf(os.Stderr, "[DNS API] Error when calling `GetRecordSet`: %v\n", err)
	} else {
		fmt.Printf("[DNS API] Got record set with name \"%s\".\n", recordSetResp.Rrset.Name)
	}
}

More examples on other services, configuration and authentication possibilities can be found in the examples folder.

Authentication

To authenticate to the SDK, you will need a service account. Create it in the STACKIT Portal an assign it the necessary permissions, e.g. project.owner. There are multiple ways to authenticate:

Key flow (recommended)
Token flow

When setting up authentication, the SDK will always try to use the key flow first and search for credentials in several locations, following a specific order:

Explicit configuration, e.g. by using the option config.WithServiceAccountKeyPath("path/to/sa_key.json")
Environment variable, e.g. by setting STACKIT_SERVICE_ACCOUNT_KEY_PATH
Credentials file

The SDK will check the credentials file located in the path defined by the STACKIT_CREDENTIALS_PATH env var, if specified, or in $HOME/.stackit/credentials.json as a fallback. The credentials file should be a json and each credential should be set using the name of the respective environment variable, as stated below in each flow. Example:
```
{
  "STACKIT_SERVICE_ACCOUNT_TOKEN": "foo_token",
  "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json"
}
```

Check the authentication example for more details.

Key flow

The following instructions assume that you have created a service account and assigned it the necessary permissions, e.g. `project.owner`.

To use the key flow, you need to have a service account key, which must have an RSA key-pair attached to it.

When creating the service account key, a new pair can be created automatically, which will be included in the service account key. This will make it much easier to configure the key flow authentication in the CLI, by just providing the service account key.

Optionally, you can provide your own private key when creating the service account key, which will then require you to also provide it explicitly to the CLI, additionaly to the service account key. Check the STACKIT Knowledge Base for an example of how to create your own key-pair.

To configure the key flow, follow this steps:

Create a service account key:

Use the STACKIT Portal: go to the Service Accounts tab, choose a Service Account and go to Service Account Keys to create a key. For more details, see Create a service account key

Save the content of the service account key by copying it and saving it in a JSON file.

The expected format of the service account key is a json with the following structure:

{
  "id": "uuid",
  "publicKey": "public key",
  "createdAt": "2023-08-24T14:15:22Z",
  "validUntil": "2023-08-24T14:15:22Z",
  "keyType": "USER_MANAGED",
  "keyOrigin": "USER_PROVIDED",
  "keyAlgorithm": "RSA_2048",
  "active": true,
  "credentials": {
    "kid": "string",
    "iss": "my-sa@sa.stackit.cloud",
    "sub": "uuid",
    "aud": "string",
    (optional) "privateKey": "private key when generated by the SA service"
  }
}

Configure the service account key for authentication in the SDK by following one of the alternatives below:
- using the configuration options: config.WithServiceAccountKey or config.WithServiceAccountKeyPath, config.WithPrivateKey or config.WithPrivateKeyPath
- setting the environment variable: STACKIT_SERVICE_ACCOUNT_KEY_PATH
- setting STACKIT_SERVICE_ACCOUNT_KEY_PATH in the credentials file (see above)

Optionally, only if you have provided your own RSA key-pair when creating the service account key, you also need to configure your private key (takes precedence over the one included in the service account key, if present). The private key must be PEM encoded and can be provided using one of the options below:

using the configuration options: config.WithPrivateKey or config.WithPrivateKeyPath

setting the environment variable: STACKIT_PRIVATE_KEY_PATH

setting STACKIT_PRIVATE_KEY_PATH in the credentials file (see above)

The SDK will search for the keys and, if valid, will use them to get access and refresh tokens which will be used to authenticate all the requests.

Token flow

Using this flow is less secure since the token is long-lived. You can provide the token in several ways:

Using the configuration option config.WithToken
Setting the environment variable STACKIT_SERVICE_ACCOUNT_TOKEN
Setting it in the credentials file (see above)

Reporting issues

If you encounter any issues or have suggestions for improvements, please open an issue in the repository or create a ticket in the STACKIT Help Center.

Contribute

Your contribution is welcome! For more details on how to contribute, refer to our Contribution Guide.

License

Apache 2.0

gogolok / stackit-sdk-go