provisioner

README

provisioner/

This directory contains provisioners capapble of spinning up resources of a particular type. It has a generic design that supports multiple provisioner implementations and multiple resource types.

There is currently one supported resource type:

• runtime: an instance on a Rill runtime (see runtime/ at the root of our monorepo)

There are currently two supported provisioner implementations:

• static: creates runtime instances using a pool of statically configured runtimes
• kubernetes: creates runtime instances by dynamically provisioning a dedicated runtime in Kubernetes

Configuration

The provisioners are configured using the environment variable RILL_ADMIN_PROVISIONER_SET_JSON with a named set of provisioners using a format like the following example. More provisioners of the same type can be configured, this is a useful for example to support deployments to different Kubernetes clusters. Furthermore the name of the default provisioner needs to be specified with RILL_ADMIN_DEFAULT_PROVISIONER, this provisioner will be used for all deployed projects where a provisioner is not explicitly chosen.

{
  "static-example":
    {
      "type": "static",
      "spec":
        {
          "runtimes":
            [
              {
                "host": "http://localhost:9091",          // Runtime host
                "slots": 50,                              // Amount of slots in the pre-provisioned runtime
                "data_dir": "/mnt/data",                  // Directory to use for data storage like DB files etc.
                "audience_url": "http://localhost:8081"   // Audience URL (JWT)
              }
            ]
        }
    },

  "kubernetes-example":
    {
      "type": "kubernetes",
      "spec":
        {
          "timeout_seconds": 30,                              // Maximum time to wait for the runtime to become ready
          "data_dir": "/mnt/data",                            // Directory to use for data storage like DB files etc.
          "host": "http://node-*.localhost",                  // The wildcard '*' will be replaced with the deployment's 'provision_id'
          "namespace": "cloud-runtime",                       // Namespace to use in the K8s cluster
          "image": "rilldata/rill",                           // Rill Docker image
          "kubeconfig_path": "kubeconfig.yaml",               // K8s config file to authenticate against the cluster
          "template_paths":
            {
              "http_ingress": "templates/http_ingress.yaml",  // Ingress resource template for HTTP
              "grpc_ingress": "templates/grpc_ingress.yaml",  // Ingress resource template for GRCP
              "service": "templates/service.yaml",            // Service resource template
              "deployment": "templates/deployment.yaml",      // Deployment resource template
              "pvc": "templates/pvc.yaml"                     // PVC resource template
            }
        }
    }
}

Documentation

Index

• Variables
• func NewSet(setSpecJSON string, db database.DB, logger *zap.Logger) (map[string]Provisioner, error)
• func Register(typ string, fn ProvisionerInitializer)
• type ClickhouseConfig
  • func NewClickhouseConfig(cfg map[string]any) (*ClickhouseConfig, error)
  • func (r *ClickhouseConfig) AsMap() map[string]any
• type Provisioner
• type ProvisionerInitializer
• type ProvisionerSpec
• type Resource
• type ResourceOptions
• type ResourceType
  • func (r ResourceType) Valid() bool
• type RuntimeArgs
  • func NewRuntimeArgs(args map[string]any) (*RuntimeArgs, error)
  • func (r *RuntimeArgs) AsMap() map[string]any
• type RuntimeConfig
  • func NewRuntimeConfig(cfg map[string]any) (*RuntimeConfig, error)
  • func (r *RuntimeConfig) AsMap() map[string]any

Variables

var Initializers = make(map[string]ProvisionerInitializer)

Initializers is a registry of provisioner initializers by type.

Functions

func NewSet

func NewSet(setSpecJSON string, db database.DB, logger *zap.Logger) (map[string]Provisioner, error)

NewSet initializes a set of provisioners from a JSON specification. The JSON specification should be a map of names to ProvisionerSpecs.

func Register

func Register(typ string, fn ProvisionerInitializer)

Register registers a new provisioner initializer.

Types

type ClickhouseConfig

type ClickhouseConfig struct {
	DSN string `mapstructure:"dsn"`
}

ClickhouseConfig describes the expected config for a provisioned Clickhouse resource.

func NewClickhouseConfig

func NewClickhouseConfig(cfg map[string]any) (*ClickhouseConfig, error)

func (*ClickhouseConfig) AsMap

func (r *ClickhouseConfig) AsMap() map[string]any

type Provisioner

type Provisioner interface {
	// Type returns the type of the provisioner.
	Type() string
	// Close is called when the provisioner is no longer needed.
	Close() error
	// Supports indicates if it can provision the resource type.
	Supports(rt ResourceType) bool
	// Provision provisions a new resource.
	// It may be called multiple times for the same ID if:
	//  - the initial provision is interrupted, or
	//  - the resource args are updated
	//
	// This means Provision should be idempotent for the resource's ID (or otherwise do appropriate garbage collection in calls to Check).
	Provision(ctx context.Context, r *Resource, opts *ResourceOptions) (*Resource, error)
	// Deprovision deprovisions a resource.
	Deprovision(ctx context.Context, r *Resource) error
	// AwaitReady waits for a resource to be ready.
	AwaitReady(ctx context.Context, r *Resource) error
	// Check is called periodically to health check the provisioner.
	// The provided context should have a generous timeout to allow the provisioner to perform maintenance tasks.
	Check(ctx context.Context) error
	// CheckResource is called periodically to health check a specific resource.
	// The provided context should have a generous timeout to allow the provisioner to perform maintenance tasks for the resource.
	// The resource's state map will be updated to match that of the returned value.
	CheckResource(ctx context.Context, r *Resource, opts *ResourceOptions) (*Resource, error)
}

Provisioner is able to provision resources for one or more resource types.

type ProvisionerInitializer

type ProvisionerInitializer func(specJSON []byte, db database.DB, logger *zap.Logger) (Provisioner, error)

ProvisionerInitializer creates a new provisioner.

type ProvisionerSpec

type ProvisionerSpec struct {
	Type string          `json:"type"`
	Spec json.RawMessage `json:"spec"`
}

ProvisionerSpec is a JSON-serializable specification for a provisioner.

type Resource

type Resource struct {
	// ID uniquely identifies the provisioned resource.
	ID string
	// Type describes what type of service the resource is.
	Type ResourceType
	// State contains state about the provisioned resource for use by the provisioner.
	// It should not be accessed outside of the provisioner.
	State map[string]any
	// Config contains access details for clients that use the resource.
	Config map[string]any
}

Resource represents a provisioned resource.

type ResourceOptions

type ResourceOptions struct {
	// Service-specific arguments for the provisioner. See resources.go for supported arguments.
	Args map[string]any
	// Annotations for the project the resource belongs to.
	Annotations map[string]string
	// RillVersion is the current version of Rill.
	RillVersion string
}

ResourceOptions contains metadata about a resource.

type ResourceType

type ResourceType string

ResourceType enumerates the provisionable resource types.

const (
	ResourceTypeRuntime    ResourceType = "runtime"
	ResourceTypeClickHouse ResourceType = "clickhouse"
)

func (ResourceType) Valid

func (r ResourceType) Valid() bool

type RuntimeArgs

type RuntimeArgs struct {
	Slots   int    `mapstructure:"slots"`
	Version string `mapstructure:"version"`
}

RuntimeArgs describe the expected arguments for provisioning a runtime resource.

func NewRuntimeArgs

func NewRuntimeArgs(args map[string]any) (*RuntimeArgs, error)

func (*RuntimeArgs) AsMap

func (r *RuntimeArgs) AsMap() map[string]any

type RuntimeConfig

type RuntimeConfig struct {
	Host         string `mapstructure:"host"`
	Audience     string `mapstructure:"audience"`
	CPU          int    `mapstructure:"cpu"`
	MemoryGB     int    `mapstructure:"memory_gb"`
	StorageBytes int64  `mapstructure:"storage_bytes"`
}

RuntimeConfig describes the expected config for a provisioned runtime resource.

func NewRuntimeConfig

func NewRuntimeConfig(cfg map[string]any) (*RuntimeConfig, error)

func (*RuntimeConfig) AsMap

func (r *RuntimeConfig) AsMap() map[string]any