Enables users of IONOS Cloud sdks to use one repo for all the GO SDKs released.

⚠️ Note: sdk-go-bundle is currently in the Early Access (EA) phase. For production or critical applications, we recommend using the older separate repo SDKs in the table below.

IONOS Enterprise-grade Infrastructure as a Service (IaaS) solutions can be managed through the Cloud API, in addition or as an alternative to the "Data Center Designer" (DCD) browser-based tool.

Both methods employ consistent concepts and features, deliver similar power and flexibility, and can be used to perform a multitude of management tasks, including adding servers, volumes, configuring networks, and so on.

The IONOS Cloud SDK for GO bundle provides you with access to the IONOS Cloud API. The client library supports both simple and complex requests. It is designed for developers who are building applications in GO . The SDK for GO wraps the IONOS Cloud API. All API operations are performed over SSL and authenticated using your IONOS Cloud portal credentials. The API can be accessed within an instance running in IONOS Cloud or directly over the Internet from any application that can send an HTTPS request and receive an HTTPS response.

⚠️ Note: To overwrite the api endpoint - api.ionos.com, the environment variable $IONOS_API_URL can be set, and used with NewConfigurationFromEnv() function.

To start working with the SDK, set up your project for Go modules, and retrieve the SDK dependencies with go get. This example shows how to use the SDK to make an API request to IONOS Cloud.

$ mkdir ~/firstbundleproj
$ cd ~/firstbundleproj
$ go mod init firstbundleproj

$ go get github.com/ionos-cloud/sdk-go-bundle/shared
$ go get github.com/ionos-cloud/sdk-go-bundle/products/compute

package main

import (
   "context"
   "fmt"
   "github.com/ionos-cloud/sdk-go-bundle/shared"
   "github.com/ionos-cloud/sdk-go-bundle/products/compute"
   "log"
)

func main() {
   // NewConfigurationFromEnv looks for the following variables in the environment: IONOS_USERNAME, IONOS_PASSWORD, IONOS_TOKEN, IONOS_API_URL
   // You can either export IONOS_USERNAME and IONOS_PASSWORD, or IONOS_TOKEN
   // IONOS_API_URL - should be set only if you with to overwrite the default ionoscloud.DefaultIonosServerUrl
   cfg := shared.NewConfigurationFromEnv()

   computeClient := compute.NewAPIClient(cfg)
   //setting Depth to 1 here makes sure we get the properties of the object(eg name)
   locations, apiResponse, err := computeClient.LocationsApi.LocationsGet(context.Background()).Depth(1).Execute()
   if err != nil {
      log.Fatalf("failed to list locations: %v", err)
   }
   apiResponse.LogInfo()
   if !locations.HasItems() || len(*locations.Items) == 0 {
      log.Fatalf("no locations found")
   }
   for _, location := range *locations.Items {
      if location.HasProperties() {
         fmt.Printf("location id is %s and location name %s\n", *location.Id, *location.Properties.Name)
      }
   }
}

go run .
[DEBUG] Request time : 601.664832ms for operation : LocationsGet
[DEBUG] response status code : 200
location id is de/fra and location name frankfurt
location id is us/las and location name lasvegas
location id is us/ewr and location name newark
location id is de/txl and location name berlin
location id is gb/lhr and location name london
location id is es/vit and location name logrono
location id is fr/par and location name paris

Using your IDE of choice, add the following code:

There are 2 ways to generate your token:

package main

import (
   "context"
   "github.com/ionos-cloud/sdk-go-bundle/shared"
   "github.com/ionos-cloud/sdk-go-bundle/products/auth"
   "github.com/ionos-cloud/sdk-go-bundle/products/compute"
   "log"
)

func main() {
   //note: to use NewConfigurationFromEnv(), you need to previously set IONOS_USERNAME and IONOS_PASSWORD as env variables
   authClient := auth.NewAPIClient(shared.NewConfigurationFromEnv())
   jwt, _, err := authClient.TokensApi.TokensGenerate(context.Background()).Execute()
   if err != nil {
      log.Fatalf("error occurred while generating token (%v)", err)
   }
   if !jwt.HasToken() {
      log.Fatalf("could not generate token")
   }
   cfg := shared.NewConfiguration("", "", *jwt.GetToken(), "")
   apiClient := compute.NewAPIClient(cfg)
   datacenters, apiResponse, err := apiClient.DataCentersApi.DatacentersGet(context.Background()).Depth(1).Execute()
   if err != nil {
      log.Fatalf("error retrieving datacenters (%v)", err)
   }
   apiResponse.LogInfo()
   if !datacenters.HasItems() || len(*datacenters.Items) == 0 {
      log.Fatalf("no datacenters found, please create one first using SDK or DCD")
   }
   for _, datacenter := range *datacenters.Items {
      if datacenter.HasProperties() {
         log.Printf("datacenter name %s in location %s \n", *datacenter.Properties.Name, *datacenter.Properties.Location)
      }
   }
}

Install ionosctl as explained here Run commands to log in and generate your token.

ionosctl login
ionosctl token generate
export IONOS_TOKEN="insert_here_token_saved_from_generate_command"

Save the generated token and use it to authenticate:

    import (
        "context"
        "fmt"
        "log"
		
        "github.com/ionos-cloud/sdk-go-bundle/shared"
        "github.com/ionos-cloud/sdk-go-bundle/products/compute"
    )

    func TokenAuthExample() error {
        //note: to use NewConfigurationFromEnv(), you need to previously set IONOS_TOKEN as env variables
        authClient := shared.NewAPIClient(authApi.NewConfigurationFromEnv())
        apiClient := compute.NewAPIClient(cfg)
        datacenters, _, err := apiClient.DataCentersApi.DatacentersGet(context.Background()).Depth(1).Execute()
        if err != nil {
            return fmt.Errorf("error retrieving datacenters (%w)", err)
        }
        return nil
    }

You can enable certificate pinning if you want to bypass the normal certificate checking procedure, by doing the following:

Set env variable IONOS_PINNED_CERT=<insert_sha256_public_fingerprint_here>

You can get the sha256 fingerprint most easily from the browser by inspecting the certificate.

You can inject any logger that implements Printf instead of using the default sdk logger. There are log levels that you can set: Off, Debug and Trace.

⚠️ Note: We recommend you only set this TRACE for debugging purposes. Disable it in your production environments because it can log sensitive data.
It logs the full request and response without encryption, even for an HTTPS call.
Verbose request and response logging can also significantly impact your application's performance.

package main

import (
   "github.com/ionos-cloud/sdk-go-bundle/shared"
   "github.com/sirupsen/logrus"
)

func main() {
   // create your configuration. replace username, password, token and url with correct values, or use NewConfigurationFromEnv()
   // if you have set your env variables as explained above
   cfg := shared.NewConfiguration("username", "password", "token", "hostUrl")
   // enable request and response logging. this is the most verbose loglevel
   shared.SdkLogLevel = shared.Trace
   // inject your own logger that implements Printf
   shared.SdkLogger = logrus.New()
}

All SDKs are found in the folder https://github.com/ionos-cloud/sdk-go-bundle/tree/master/products.

• Structs moved to shared package: GenericOpenAPIError, Configuration, APIResponse, utility functions, logging interface, environment variables.
• Import github.com/ionos-cloud/sdk-go-bundle/shared and replace the structs as required.
• IONOS_DEBUG removed, debugging now set with IONOS_LOG_LEVEL, as described here
• Replaced PtrBool, PtrInt, PtrInt32, PtrInt64, PtrFloat, PtrFloat32, PtrFloat64, PtrString, PtrTime with ToPtr generic functions
• For CloudAPI, computeconfig.SetDepth(int32(1)) is removed, you should instead use sharedconfig.AddDefaultQueryParam("depth", "1")

Example migration for compute github.com/ionos-cloud/sdk-go/v6 to github.com/ionos-cloud/sdk-go-bundle/products/compute

1. Replace the import ionoscloud github.com/ionos-cloud/sdk-go/v6 with github.com/ionos-cloud/sdk-go-bundle/products/compute You will get errors, as some structs have been moved the shared package
2. Import github.com/ionos-cloud/sdk-go-bundle/shared and replace the structs as required. Examples:
   • var apiResponse *ionoscloud.APIResponse with var apiResponse *shared.APIResponse
   • ionoscloud.NewConfiguration(username, password, token, url) with shared.NewConfiguration(username, password, token, url)
   • Logger no longer a part of the Configuration object, it is a global instance called SdkLogger, that can be set using shared.Logger = logger of your choice
   • LogLevel no longer a part of the Configuration object, it is a global instance called SdkLogLevel, that can be set using shared.SdkLogLevel

All replacements work as-is, no other changes are required.