allocator

README

Allocator service

Allocator allows users to create an instance of a pre-defined service, e.g. syncbase, that they can use for testing purposes.

It leverages the functionality provided by the cluster package to run the service on Kubernetes.

The allocator server API has 3 methods:

• Create()
• Destroy()
• List()

Create()

Create is used to create a new instance of the service.

When the server receives the Create() request, it creates a new Kubernetes Deployment that is based on a pre-defined template. The template is expanded with the following data:

• Name: The name of the kubernetes Deployment and its persistent disk.
• AccessList: A JSON-encoded AccessList that contains the caller's blessing names.
• MountName: The name where the new instance should publish itself.
• CreatorInfo: A JSON-encoded string describing the caller, suitable to be used as an annotation.
• OwnerHash: A hash of the creator's email address.

Destroy()

Destroy destroys the instance whose name is passed as argument, along with its persistent disk.

List()

List shows all the instances that are owned by the calling user.

Example

Tools

Refer to the Tools and Create a cluster sections of the Vanadium Cluster documentation.

This document assumes that the Kubernetes cluster already exists and that we have a vkube.cfg file for it.

Deployment template

Allocatord doesn't know anything about the service to allocate. Instead, it takes a user-defined template as argument.

Let's use syncbase as a simplified example.

 cat - <<EOF> syncbased-deployment.json-template
{
  "apiVersion": "extensions/v1beta1",
  "kind": "Deployment",
  "metadata": {
    "name": "{{.Name}}",
    "annotations": {
      "v.io/creator-info": {{.CreatorInfo}}
    },
    "labels": {
      "ownerHash": "{{.OwnerHash}}"
    }
  },
  "spec": {
    "template": {
      "metadata": {
        "labels": {
          "application": "{{.Name}}"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "syncbased",
            "image": "b.gcr.io/vanadium-docker-images/syncbased:latest"
            "command": [
              "syncbased",
              "--name={{.MountName}}",
              "--root-dir=/data/root",
              "--v23.permissions.literal={\"Admin\":{{.AccessList}}}"
            ],
            "volumeMounts": [ { "name": "data-disk", "mountPath": "/data" } ]
          }
        ],
        "volumes": [
          { "name": "data-disk", "gcePersistentDisk": { "pdName": "{{.Name}}", "fsType": "ext4" } }
        ]
      }
    }
  }
}
EOF

Run allocatord

allocatord \
  --deployment-template=syncbased-deployment.json-template \
  --name=syncbase-allocator \
  --server-name=syncbased \
  --vkube-cfg=vkube.cfg

Creating a new service instance

allocator --allocator=syncbase-allocator create

This command returns the name of the newly created syncbase instance.

Documentation

Index

• Variables
• type AllocatorClientMethods
• type AllocatorClientStub
  • func AllocatorClient(name string) AllocatorClientStub
• type AllocatorServerMethods
• type AllocatorServerStub
  • func AllocatorServer(impl AllocatorServerMethods) AllocatorServerStub
• type AllocatorServerStubMethods
• type Instance
  • func (x Instance) VDLIsZero() bool
  • func (x *Instance) VDLRead(dec vdl.Decoder) error
  • func (Instance) VDLReflect(struct{ ... })
  • func (x Instance) VDLWrite(enc vdl.Encoder) error

Variables

var AllocatorDesc rpc.InterfaceDesc = descAllocator

AllocatorDesc describes the Allocator interface.

Types

type AllocatorClientMethods

type AllocatorClientMethods interface {
	// Create creates a new instance of the service.
	// It returns a handle for the new instance.
	Create(*context.T, ...rpc.CallOpt) (handle string, _ error)
	// Destroy destroys the instance with the given handle.
	Destroy(_ *context.T, handle string, _ ...rpc.CallOpt) error
	// List returns a list of all the instances owned by the caller.
	List(*context.T, ...rpc.CallOpt) (instances []Instance, _ error)
}

AllocatorClientMethods is the client interface containing Allocator methods.

type AllocatorClientStub

type AllocatorClientStub interface {
	AllocatorClientMethods
	rpc.UniversalServiceMethods
}

AllocatorClientStub adds universal methods to AllocatorClientMethods.

func AllocatorClient

func AllocatorClient(name string) AllocatorClientStub

AllocatorClient returns a client stub for Allocator.

type AllocatorServerMethods

type AllocatorServerMethods interface {
	// Create creates a new instance of the service.
	// It returns a handle for the new instance.
	Create(*context.T, rpc.ServerCall) (handle string, _ error)
	// Destroy destroys the instance with the given handle.
	Destroy(_ *context.T, _ rpc.ServerCall, handle string) error
	// List returns a list of all the instances owned by the caller.
	List(*context.T, rpc.ServerCall) (instances []Instance, _ error)
}

AllocatorServerMethods is the interface a server writer implements for Allocator.

type AllocatorServerStub

type AllocatorServerStub interface {
	AllocatorServerStubMethods
	// Describe the Allocator interfaces.
	Describe__() []rpc.InterfaceDesc
}

AllocatorServerStub adds universal methods to AllocatorServerStubMethods.

func AllocatorServer

func AllocatorServer(impl AllocatorServerMethods) AllocatorServerStub

AllocatorServer returns a server stub for Allocator. It converts an implementation of AllocatorServerMethods into an object that may be used by rpc.Server.

type AllocatorServerStubMethods

type AllocatorServerStubMethods AllocatorServerMethods

AllocatorServerStubMethods is the server interface containing Allocator methods, as expected by rpc.Server. There is no difference between this interface and AllocatorServerMethods since there are no streaming methods.

type Instance

type Instance struct {
	Handle        string
	MountName     string
	BlessingNames []string
	CreationTime  time.Time
	Replicas      int32
	Version       string
}

Instance describes a service instance.

func (Instance) VDLIsZero

func (x Instance) VDLIsZero() bool

func (*Instance) VDLRead

func (x *Instance) VDLRead(dec vdl.Decoder) error

func (Instance) VDLReflect

func (Instance) VDLReflect(struct {
	Name string `vdl:"v.io/x/ref/services/allocator.Instance"`
})

func (Instance) VDLWrite

func (x Instance) VDLWrite(enc vdl.Encoder) error