managed-services-lib

Core library for building Codesphere managed-service provider backends. Implement one interface; the library serves it over the Codesphere REST contract.

Not a runnable service. Start from managed-services-template for a working server with an example provider, Dockerfile, and CI.

Install

go get github.com/codesphere-cloud/managed-services-lib

Go 1.26+.

Provider interface

type Provider[CreateParams any, Status any, UpdateParams any] interface {
	Create(ctx context.Context, params CreateParams) error
	List(ctx context.Context) ([]model.ServiceID, error)
	GetStatus(ctx context.Context, ids []model.ServiceID) (map[model.ServiceID]Status, error)
	Update(ctx context.Context, id model.ServiceID, args UpdateParams) error
	Delete(ctx context.Context, id model.ServiceID) error
}

Embed provider.Base for the shared dependencies (Kubernetes client, logger) and helpers.

Backups are an opt-in capability, generic over the provider's own request type:

type Backups[BackupParams any] interface {
	TakeBackup(ctx context.Context, backupID model.BackupId, params BackupParams) error
	GetBackupStatus(ctx context.Context, backupID model.BackupId, params BackupParams) (BackupStatus, error)
	DeleteBackup(ctx context.Context, backupID model.BackupId, params BackupParams) error
}

A provider that supports backups implements Backups and calls RegisterBackupRoutes.

Wiring

cfg, _ := config.Load()
k8s, _ := client.NewKubernetesClient(cfg.Kubeconfig)
logger := slog.Default()

routes := map[string]func(*gin.RouterGroup){
	"mysvc": func(g *gin.RouterGroup) {
		p := mysvc.NewProvider(k8s, logger)
		provider.RegisterRoutes(g, p)       // CRUD
		provider.RegisterBackupRoutes(g, p) // backups
	},
}

server, _ := api.NewServer(cfg, routes)
server.Run()

RegisterRoutes mounts the CRUD endpoints under /api/v1/{name}; RegisterBackupRoutes adds the /backups endpoints for providers that implement Backups.

Detached Jobs

Some operations (backups, restores, migrations) are easier to run as one-shot Kubernetes Jobs, detached from the provider pod.

• client.JobRunner (also on provider.Base as Jobs) — Run / State / Delete / Replace a one-shot Job, with an optional owned credentials Secret injected via secretKeyRef.
• provider.ServiceJob / ServiceJobSpec — build a JobSpec with a consistent name (<operation>-<key>) and identity labels; BackupStatusFromJob / OperationStatusFromJob map a Job's state to a status.

spec := provider.ServiceJobSpec(provider.ServiceJob{
	Operation: provider.JobOpBackup, MsID: id, Key: backupID,
	Image: img, Command: []string{"/backup"},
	Env: env, Secrets: secrets, // whatever your image reads
})
err := p.Jobs.Run(ctx, ns, spec)

See the package docs and provider/servicejob_usage_test.go for details.

Configuration

config.Load() reads these environment variables:

Variable	Default
PORT	8080	HTTP port
API_KEY	—	auth key (off if unset)
KUBECONFIG	—	kubeconfig path (in-cluster if unset)
ENVIRONMENT	development	development / production

This is framework config only. Provider-specific config (storage class, credentials, image versions) belongs in your provider's constructor.

Development

make test, make lint, make mocks. make all runs everything.