narc

README

                  88
              .d888888b
              d8P 88 "8b
              Y8b.88        88888b.   8888b.  888d888 .d8888b
              "Y88888b.     888 "88b     "88b 888P"  d88P"
                  88 "8b    888  888 .d888888 888    888
              Y8b 88 .8P    888  888 888  888 888    Y88b.
               "Y8888P"     888  888 "Y888888 888     "Y8888P
                  88


                       $ nearly a real console


= About

Provides interactive console access to fresh new throwaway containers. As soon
as the task is complete (whether it's an interactive bash session or a one-off
command), the container is destroyed and the task goes away.

Containers are spun up and torn down over NATS, and connected to via a
lightweight SSH server.

= Running tests

librarian-chef install
vagrant up
vagrant ssh
gvm install go1.1.2 (one-time thing)
gvm use go1.1.2
cd /workspace
export GOPATH=$PWD
cd src/github.com/cloudfoundry/narc
go test -gocheck.v

= Usage

  PUB task.start

    Provisions a task on the given narc server.

    Payload: {"task":"(task id)","secure_token":"(secure token)"}

      `task id` is a unique identifier for the session.
      `secure token` is the token to authorize access to the task.

    Optional toplevel attributes:

      {"memory_limit":(memory limit)}
      {"disk_limit":(memory limit)}

      `memory limit` is the memory limit for the container, in megabytes.
      `disk limit` is the disk quota for the container, in megabytes.

      If either are omitted, there is no limit. For example, if memory is
      limited but not disk, there will be no disk limit, and vice versa.

  --------------------------------------------------

  PUB task.stop

    Terminate a task. This destroys the container and kicking everyone off.

    Payload: {"task":"(task id)"}

      `task id` is a unique identifier for the task.

  --------------------------------------------------

  SUB task.advertise

    Sent periodically to allow other components to discover the narc server.

    Payload: {
      "id": "(agent id)",
      "available_memory": (avail. memory),
      "available_disk": (avail. disk)
    }

      `agent id` is the unique identifier for the narc server.
      `available memory` is the remaining reservable memory for the server.
      `available disk` is the remaining reservable disk space for the server.

Documentation

Index

• Variables
• type Agent
  • func NewAgent(taskBackend TaskBackend, routerClient gibson.RouterClient, port int) (*Agent, error)
  • func (agent *Agent) HandleStarts(mbus cfmessagebus.MessageBus) error
  • func (agent *Agent) HandleStops(mbus cfmessagebus.MessageBus) error
• type CapacityConfig
• type Config
  • func LoadConfig(configFilePath string) Config
• type Container
• type ContainerCreationRunner
• type ContainerCreationRunnerInJson
  • func (runner *ContainerCreationRunnerInJson) Run(request *CreateContainerMessage, response *CreateContainerResponse, ...) error
• type ContainerInfo
• type CreateContainerMessage
• type CreateContainerResponse
• type JobInfo
• type MappedPort
• type MessageBusConfig
• type ProxyServer
  • func NewProxyServer(registry *Registry) (*ProxyServer, error)
  • func (p *ProxyServer) Start(port int) error
  • func (p *ProxyServer) Stop() error
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Lookup(id string) (*Task, bool)
  • func (r *Registry) Register(id string, task *Task)
  • func (r *Registry) Unregister(id string)
• type RouterRegistrar
• type Task
  • func NewTask(container Container, secureToken string, command *exec.Cmd) (*Task, error)
  • func (t *Task) Attach(channel ssh.Channel) error
  • func (t *Task) OnComplete(callback func())
  • func (t *Task) Start() (io.Writer, io.Reader, error)
  • func (t *Task) Stop() error
• type TaskBackend
• type TaskLimits
  • func (limits *TaskLimits) IsValid() bool
• type Tasks
• type WardenContainer
  • func NewWardenContainer(wardenSocketPath string, limits TaskLimits, cmdRunner ContainerCreationRunner) (*WardenContainer, error)
  • func (c *WardenContainer) Destroy() error
  • func (c *WardenContainer) ID() string
  • func (c *WardenContainer) Run(script string) (*JobInfo, error)
• type WardenTaskBackend
  • func (p WardenTaskBackend) ProvideCommand(container Container) *exec.Cmd
  • func (p WardenTaskBackend) ProvideContainer(limits TaskLimits) (Container, error)

Variables

var DefaultConfig = Config{
	Host: "127.0.0.1",

	MessageBus: MessageBusConfig{
		Host: "127.0.0.1",
		Port: 4222,
	},

	Capacity: CapacityConfig{
		MemoryInBytes: 1 * gigabyte,
		DiskInBytes:   1 * gigabyte,
	},

	WardenSocketPath:     "/tmp/warden.sock",
	WardenContainersPath: "/opt/warden/containers",

	AdvertiseInterval: 10 * time.Second,
}

var TaskAlreadyRegistered = errors.New("task already registered")

var TaskNotRegistered = errors.New("task not registered")

Types

type Agent

type Agent struct {
	ID       *uuid.UUID
	Registry *Registry
	// contains filtered or unexported fields
}

func NewAgent

func NewAgent(taskBackend TaskBackend, routerClient gibson.RouterClient, port int) (*Agent, error)

func (*Agent) HandleStarts

func (agent *Agent) HandleStarts(mbus cfmessagebus.MessageBus) error

func (*Agent) HandleStops

func (agent *Agent) HandleStops(mbus cfmessagebus.MessageBus) error

type CapacityConfig

type CapacityConfig struct {
	MemoryInBytes uint64
	DiskInBytes   uint64
}

type Config

type Config struct {
	Host                 string
	MessageBus           MessageBusConfig
	Capacity             CapacityConfig
	AdvertiseInterval    time.Duration
	WardenSocketPath     string
	WardenContainersPath string
}

func LoadConfig

func LoadConfig(configFilePath string) Config

type Container

type Container interface {
	ID() string
	Destroy() error
	Run(command string) (*JobInfo, error)
}

type ContainerCreationRunner

type ContainerCreationRunner interface {
	Run(request *CreateContainerMessage, response *CreateContainerResponse, cmd string) error
}

type ContainerCreationRunnerInJson

type ContainerCreationRunnerInJson struct{}

func (*ContainerCreationRunnerInJson) Run

func (runner *ContainerCreationRunnerInJson) Run(request *CreateContainerMessage, response *CreateContainerResponse, executable string) error

type ContainerInfo

type ContainerInfo struct {
	MemoryLimitInBytes uint64
}

type CreateContainerMessage

type CreateContainerMessage struct {
	WardenSocketPath string `json:"warden_socket_path"`
	DiskLimit        uint64 `json:"disk_limit"`
	MemoryLimit      uint64 `json:"memory_limit"`
	Network          bool   `json:"network"`
}

type CreateContainerResponse

type CreateContainerResponse struct {
	Handle               string `json:"handle"`
	HostPort             int    `json:"host_port"`
	ContainerPort        int    `json:"container_port"`
	ConsoleHostPort      int    `json:"console_host_port"`
	ConsoleContainerPort int    `json:"console_container_port"`
}

type JobInfo

type JobInfo struct {
	ExitStatus uint32
}

type MappedPort

type MappedPort uint32

type MessageBusConfig

type MessageBusConfig struct {
	Host     string
	Port     int
	Username string
	Password string
}

type ProxyServer

type ProxyServer struct {
	// contains filtered or unexported fields
}

func NewProxyServer

func NewProxyServer(registry *Registry) (*ProxyServer, error)

func (*ProxyServer) Start

func (p *ProxyServer) Start(port int) error

func (*ProxyServer) Stop

func (p *ProxyServer) Stop() error

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

func NewRegistry

func NewRegistry() *Registry

func (*Registry) Lookup

func (r *Registry) Lookup(id string) (*Task, bool)

func (*Registry) Register

func (r *Registry) Register(id string, task *Task)

func (*Registry) Unregister

func (r *Registry) Unregister(id string)

type RouterRegistrar

type RouterRegistrar interface {
	Register(string, int)
	Unregister(string, int)
}

type Task

type Task struct {
	SecureToken  string
	ProcessState *os.ProcessState
	// contains filtered or unexported fields
}

func NewTask

func NewTask(container Container, secureToken string, command *exec.Cmd) (*Task, error)

func (*Task) Attach

func (t *Task) Attach(channel ssh.Channel) error

func (*Task) OnComplete

func (t *Task) OnComplete(callback func())

func (*Task) Start

func (t *Task) Start() (io.Writer, io.Reader, error)

func (*Task) Stop

func (t *Task) Stop() error

type TaskBackend

type TaskBackend interface {
	ProvideContainer(TaskLimits) (Container, error)
	ProvideCommand(Container) *exec.Cmd
}

type TaskLimits

type TaskLimits struct {
	MemoryLimitInBytes uint64
	DiskLimitInBytes   uint64
}

func (*TaskLimits) IsValid

func (limits *TaskLimits) IsValid() bool

type Tasks

type Tasks map[string]*Task

type WardenContainer

type WardenContainer struct {
	Handle string
	// contains filtered or unexported fields
}

func NewWardenContainer

func NewWardenContainer(wardenSocketPath string, limits TaskLimits, cmdRunner ContainerCreationRunner) (*WardenContainer, error)

func (*WardenContainer) Destroy

func (c *WardenContainer) Destroy() error

func (*WardenContainer) ID

func (c *WardenContainer) ID() string

func (*WardenContainer) Run

func (c *WardenContainer) Run(script string) (*JobInfo, error)

type WardenTaskBackend

type WardenTaskBackend struct {
	WardenContainersPath string
	WardenSocketPath     string
}

func (WardenTaskBackend) ProvideCommand

func (p WardenTaskBackend) ProvideCommand(container Container) *exec.Cmd

func (WardenTaskBackend) ProvideContainer

func (p WardenTaskBackend) ProvideContainer(limits TaskLimits) (Container, error)