OtterScale API

Shared type definitions — CRDs (Kubebuilder) + ConnectRPC services (Protobuf) — for the OtterScale multi-cluster Kubernetes platform.

Quick Start

# Go
go get github.com/otterscale/api@latest

# TypeScript
npm install @otterscale/api

# Generate all (proto, CRDs, deepcopy, lint)
make all

# Individual targets
make proto       # buf generate (Go + TypeScript + OpenAPI)
make manifests   # controller-gen CRDs
make generate    # controller-gen deepcopy
make lint        # golangci-lint

API Groups

CRDs (Kubebuilder)

Group	Kind	Scope	Purpose
tenant.otterscale.io/v1alpha1	Workspace	Cluster	Namespace isolation with RBAC, quotas, network policies

Install CRDs

kubectl apply --server-side -f https://github.com/otterscale/api/releases/download/<version>/crds.yaml

Note: CRDs that embed Kubernetes core types (e.g. DeploymentSpec) produce large schemas that exceed the kubectl.kubernetes.io/last-applied-configuration annotation limit. Use --server-side to avoid this.

ConnectRPC Services (Protobuf)

Package	Service	Key RPCs
otterscale.link.v1	LinkService	Register, ListLinks, GetAgentManifest
otterscale.resource.v1	ResourceService	Discovery, Schema, List, Get, Create, Apply, Delete, Watch
otterscale.runtime.v1	RuntimeService	PodLog, ExecuteTTY, PortForward, Scale, Restart

Generated Outputs (make proto)

Plugin	Output	Description
protocolbuffers/go	*.pb.go	Go protobuf types (opaque API)
connectrpc/go	*.connect.go	Go ConnectRPC clients/handlers
bufbuild/es	ts/src/	TypeScript protobuf types (@otterscale/api)
connect-openapi	openapi/openapi.yaml	OpenAPI spec

Toolchain

Tool	Version	Installed via
buf	v1.69.0	make proto (auto-downloads)
controller-gen	v0.20.1	make manifests / make generate (auto-downloads)
golangci-lint	v2.11.4	make lint (auto-downloads)

Feature Gating

RPCs are annotated with otterscale.api.feature method options for runtime feature gating:

rpc Register(RegisterRequest) returns (RegisterResponse) {
  option (otterscale.api.feature) = {name: "link-enabled"};
}