Datum Go SDK Generator

This repository generates Go client SDKs for Datum Cloud APIs using Kubernetes client-gen.

Overview

The SDK generator creates typed Kubernetes-style clients (clientsets, informers, listers) for Datum Cloud API resources. Each project gets its own directory with generated clients that can be imported independently.

Available SDKs

Project	Import Path	Upstream Module	API Groups
Activity	github.com/datum-cloud/go-sdk-generator/activity/client/clientset/versioned	go.miloapis.com/activity	activity
Milo	github.com/datum-cloud/go-sdk-generator/milo/client/clientset/versioned	go.miloapis.com/milo	iam, identity, infrastructure, notes, notification, quota, resourcemanager

Installation

# Activity SDK
go get github.com/datum-cloud/go-sdk-generator/activity/client/clientset/versioned

# Milo SDK
go get github.com/datum-cloud/go-sdk-generator/milo/client/clientset/versioned

Usage

Activity Client

package main

import (
    "context"
    "fmt"

    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/rest"
    "k8s.io/client-go/tools/clientcmd"

    activityclient "github.com/datum-cloud/go-sdk-generator/activity/client/clientset/versioned"
)

func main() {
    config, _ := clientcmd.BuildConfigFromFlags("", clientcmd.RecommendedHomeFile)
    client, _ := activityclient.NewForConfig(config)

    ctx := context.Background()
    activities, _ := client.ActivityV1alpha1().Activities("default").List(ctx, metav1.ListOptions{})

    for _, activity := range activities.Items {
        fmt.Printf("Activity: %s\n", activity.Name)
    }
}

Milo Client

package main

import (
    "context"
    "fmt"

    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/rest"
    "k8s.io/client-go/tools/clientcmd"

    miloclient "github.com/datum-cloud/go-sdk-generator/milo/client/clientset/versioned"
)

func main() {
    config, _ := clientcmd.BuildConfigFromFlags("", clientcmd.RecommendedHomeFile)
    client, _ := miloclient.NewForConfig(config)

    ctx := context.Background()

    // List organizations (cluster-scoped)
    orgs, _ := client.ResourcemanagerV1alpha1().Organizations().List(ctx, metav1.ListOptions{})
    for _, org := range orgs.Items {
        fmt.Printf("Organization: %s\n", org.Name)
    }

    // List users (cluster-scoped)
    users, _ := client.IamV1alpha1().Users().List(ctx, metav1.ListOptions{})
    for _, user := range users.Items {
        fmt.Printf("User: %s\n", user.Name)
    }

    // List projects (cluster-scoped)
    projects, _ := client.ResourcemanagerV1alpha1().Projects().List(ctx, metav1.ListOptions{})
    for _, project := range projects.Items {
        fmt.Printf("Project: %s\n", project.Name)
    }
}

Development

Prerequisites

• Go 1.21+
• Task (optional, for running tasks)

Setup

Enter the development shell (if using Nix):

nix develop

Or install dependencies manually:

go mod download

Available Tasks

# Show all available tasks
task

# Sync API types from upstream modules
task sync-apis

# Generate all client code
task generate

# Generate only activity client
task generate:activity

# Generate only milo client
task generate:milo

# Clean generated files
task clean

# Run go mod tidy
task tidy

# Install code-generator tools
task install-tools

Adding a New Project

1. Add the upstream module to go.mod:

   go get example.com/new-project@v1.0.0

2. Add a sync function in hack/sync-apis.sh:

   sync_newproject() {
       local version
       version=$(go list -m -f '{{.Version}}' example.com/new-project)
       local src="${GOMODCACHE}/example.com/new-project@${version}/pkg/apis/newproject"
       local dst="${SCRIPT_ROOT}/newproject/apis/newproject"
   
       echo "Syncing newproject APIs from ${src}..."
       rm -rf "${dst}"
       mkdir -p "${dst}"
       cp -r "${src}"/* "${dst}/"
       chmod -R u+w "${dst}"
       echo "Newproject APIs synced successfully"
   }
   
   sync_newproject

3. Add generation in hack/update-codegen.sh:

   echo "Generating client for newproject..."
   kube::codegen::gen_client \
       --output-dir "${SCRIPT_ROOT}/newproject/client" \
       --output-pkg "${THIS_PKG}/newproject/client" \
       --boilerplate "${SCRIPT_ROOT}/hack/boilerplate.go.txt" \
       --with-watch \
       "${SCRIPT_ROOT}/newproject/apis"

4. Run generation:

   task generate

Project Structure

go-sdk-generator/
├── activity/
│   ├── apis/                    # Synced API types
│   │   └── activity/
│   │       └── v1alpha1/
│   └── client/                  # Generated clients
│       ├── clientset/versioned/ # Typed clientset
│       ├── informers/           # Shared informers
│       └── listers/             # Listers for caching
├── milo/
│   ├── apis/                    # Synced API types
│   │   ├── iam/v1alpha1/
│   │   ├── identity/v1alpha1/
│   │   ├── infrastructure/v1alpha1/
│   │   ├── notes/v1alpha1/
│   │   ├── notification/v1alpha1/
│   │   ├── quota/v1alpha1/
│   │   └── resourcemanager/v1alpha1/
│   └── client/                  # Generated clients
│       ├── clientset/versioned/
│       ├── informers/
│       └── listers/
├── hack/
│   ├── boilerplate.go.txt       # License header
│   ├── sync-apis.sh             # API sync script
│   └── update-codegen.sh        # Code generation script
├── Taskfile.yaml
├── flake.nix
├── go.mod
└── go.sum

Milo API Groups

The Milo SDK provides clients for the following API groups:

Group	Description	Example Resources
iam.miloapis.com	Identity and Access Management	User, Group, Role, PolicyBinding, MachineAccount
identity.miloapis.com	Identity providers	UserIdentity, Session
infrastructure.miloapis.com	Infrastructure management	ProjectControlPlane
notes.miloapis.com	Notes and annotations	Note, ClusterNote
notification.miloapis.com	Notification system	Contact, ContactGroup, Email, EmailTemplate
quota.miloapis.com	Resource quota management	ResourceGrant, ResourceClaim, AllowanceBucket
resourcemanager.miloapis.com	Resource hierarchy	Organization, Project, OrganizationMembership

Notes on Kubebuilder Projects

Some upstream projects like milo are built with kubebuilder and use controller-runtime clients instead of client-gen. These projects require additional processing during sync:

1. Missing +genclient markers - Kubebuilder doesn't add these by default. The sync script automatically injects +genclient (and +genclient:nonNamespaced for cluster-scoped resources) before type definitions.

2. GroupVersion vs SchemeGroupVersion - Some kubebuilder projects use GroupVersion as the variable name, but client-gen expects SchemeGroupVersion. The sync script renames these.

3. Missing Resource() function - Client-gen generated listers require a Resource() function in register.go. The sync script adds this if missing.

Projects like activity that are already designed for client-gen don't need these fixes - they just copy and generate.

License

Apache License 2.0