STACKIT SDK for Go
Getting started
RequiresGo 1.25 or higher.
To download the core module:
``
go get github.com/stackitcloud/stackit-sdk-go/core
`
To download the services/dns module:
`
go get 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 described below in section Authentication in more detail.
`go
package main
import (
"context"
"fmt"
"os"
dns "github.com/stackitcloud/stackit-sdk-go/services/dns/v1api"
)
func main() {
projectId := "PROJECT_ID" // the uuid of your STACKIT project
// 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.ListZonesResponse
getZoneResp, err = dnsClient.DefaultAPI.ListZones(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.DefaultAPI.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 = 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.DefaultAPI.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 with the SDK, you need a service account with appropriate permissions (e.g., project.owner, see here). You can create a service account through the STACKIT Portal.
Authentication Methods
The SDK supports three authentication methods:
- Workload Identity Federation Flow
- Uses OIDC trusted tokens
- Provides best security through short-lived tokens without secrets
- Key Flow
- Uses RSA key-pair based authentication
- Provides better security through short-lived tokens
- Supports both STACKIT-generated and custom key pairs
- Token Flow (Deprecated)
- Uses long-lived service account tokens
- Simpler but less secure
Configuration Priority
The SDK searches for credentials in the following order:
- Explicit configuration in code
- Environment variables
- Credentials file (
$HOME/.stackit/credentials.json)
For each authentication method, the try order is:
- Workload Identity Federation Flow
- Key Flow
- Token Flow
Using the Workload Identity Fedearion Flow
- Create a service account trusted relation in the STACKIT Portal:
- Navigate to Service Accounts → Select account → Federated Identity Providers
- Configure a Federated Identity Provider and the required assertions to trust in.
- Configure authentication using any of these methods:
A. Code Configuration
`go
// Using wokload identity federation flow
config.WithWorkloadIdentityFederationAuth()
// With the custom path for the external OIDC token
config.WithWorkloadIdentityFederationPath("/path/to/your/federated/token")
// For the service account
config.WithServiceAccountEmail("[email protected]")
`
B. Environment Variables
`bash
With the custom path for the external OIDC token
STACKIT_FEDERATED_TOKEN_FILE=/path/to/your/federated/token
For the service account
[email protected]
`
Using the Key Flow
- Create a service account key in the STACKIT Portal:
- Navigate to Service Accounts → Select account → Service Account Keys → Create key
- You can either let STACKIT generate the key pair or provide your own RSA key pair (see Creating an RSA key-pair for more details)
- Note: it's also possible to create the service account key in other ways (see Tutorials for Service Accounts for more details)
- Save the service account key JSON:
`json
{
"id": "uuid",
"publicKey": "public key",
"credentials": {
"kid": "string",
"iss": "[email protected]",
"sub": "uuid",
"aud": "string",
"privateKey": "private key (if STACKIT-generated)"
}
// ... other fields ...
}
`
- Configure authentication using any of these methods:
A. Code Configuration
`go
// Using service account key file
config.WithServiceAccountKeyPath("path/to/sa_key.json")
// Or using key content directly
config.WithServiceAccountKey(keyJSON)
// Optional: For custom key pairs
config.WithPrivateKeyPath("path/to/private.pem")
// Or using private key content directly
config.WithPrivateKey(privateKeyJSON)
`
B. Environment Variables
`bash
# Using service account key
STACKIT_SERVICE_ACCOUNT_KEY_PATH=/path/to/sa_key.json
# or
STACKIT_SERVICE_ACCOUNT_KEY=
# Optional: For custom key pairs
STACKIT_PRIVATE_KEY_PATH=/path/to/private.pem
# or
STACKIT_PRIVATE_KEY=
`
C. Credentials File ($HOME/.stackit/credentials.json)
`json
{
"STACKIT_SERVICE_ACCOUNT_KEY_PATH": "/path/to/sa_key.json",
"STACKIT_PRIVATE_KEY_PATH": "/path/to/private.pem"
}
`
Using the Token Flow
- Create an access token in the STACKIT Portal:
- Navigate to Service Accounts → Select account → Access Tokens → Create token
- Note: it's also possible to create the service account access tokens in other ways (see Tutorials for Service Accounts for more details)
- Configure authentication using any of these methods:
A. Code Configuration
`go
config.WithToken("your-token")
`
B. Environment Variables
`bash
STACKIT_SERVICE_ACCOUNT_TOKEN=your-token
`
C. Credentials File ($HOME/.stackit/credentials.json)
`json
{
"STACKIT_SERVICE_ACCOUNT_TOKEN": "your-token"
}
``
For detailed implementation examples, see the authentication example.