dea

README

golang docker exec api

Project status: pre-alpha (not yet working)

$ go get github.com/rs-pro/docker-exec-api

Whait this is

This is a REST microservice to execute commands via docker and provide their output as a websocket connection.

Includes support passing SSH agent through to the container.

Not designed to execute untrusted user-provided commands.

Websocket connection is read-only and not protected by api key (but requires a client to know a random docker id) by design so it can be served directly to end user.

Developed for rtrack.ru as a part of deployment automation service.

Install

go get github.com/rs-pro/docker-exec-api

Examples:

Examples use httpie and wsd

install it:

go get github.com/alexanderGugel/wsd

Replace create-your-key with a better key for security.

# create config.yml (see example in this repo)
docker-exec-api
# from your backend
http POST http://localhost:12010/sessions X-Api-Key:create-your-key image=ruby:2.7 commands:='["git -C app pull || git clone git@rscz.ru:rocket-science/piudelcibo.git app", "cd app", "gem install bundler:1.17.2", "bundle install", "cap staging deploy"]' volumes:='[{"piudelcibo_data": "/data"]' pull_image="ruby:2.7"
# Example output:

HTTP/1.1 200 OK
Content-Length: 73
Content-Type: application/json; charset=utf-8
Date: Mon, 06 Jul 2020 20:39:31 GMT

{
    "ID": "your-long-id"
}

# from browser to show output:

wsd -url=ws://localhost:12010/sessions/your-long-id/websocket

# or
 http get http://localhost:12010/sessions/your-long-id/output
 

Production usage

Please use nginx for HTTPS connections. Config example:

License

MIT License

Documentation

Index

• func PrepareCommand(cmd string) string
• type Command
  • func (c *Command) GetOutput() string
• type Container
  • func NewContainer() *Container
  • func (c *Container) GetCommands() []*Command
  • func (c *Container) LastCommand() *Command
  • func (c *Container) StartCommand(command string)
  • func (c *Container) StdErr() io.Writer
  • func (c *Container) StdOut() io.Writer
• type ContainerPool
  • func NewPool() *ContainerPool
  • func (p *ContainerPool) Exec(params *ExecParams) (*Container, error)
  • func (p *ContainerPool) GetAllContainers() map[string]*Container
  • func (p *ContainerPool) GetContainerByToken(token string) *Container
• type ExecParams
• type LineKind
• type OutputLine
• type Writer
  • func (w Writer) Write(p []byte) (n int, err error)

Functions

func PrepareCommand

func PrepareCommand(cmd string) string

Types

type Command

type Command struct {
	Command   string        `json:"command"`
	Args      []string      `json:"args"`
	Output    []*OutputLine `json:"-"`
	StartedAt *time.Time    `json:"started_at"`
	EndedAt   *time.Time    `json:"ended_at"`
	ExitCode  *int          `json:"exit_code"`
}

func (*Command) GetOutput

func (c *Command) GetOutput() string

type Container

type Container struct {
	ID string `json:"id"`
	// Cond is a condition variable to signal new terminal output presence in commands
	Cond *sync.Cond `json:"-"`
	// StdinCond is a condition variable to signal that command is finished
	StdinCond *sync.Cond `json:"-"`
	StoppedAt *time.Time `json:"stopped_at"`
	Error     error      `json:"error"`

	Ctx context.Context `json:"-"`
	// contains filtered or unexported fields
}

func NewContainer

func NewContainer() *Container

func (*Container) GetCommands

func (c *Container) GetCommands() []*Command

func (*Container) LastCommand

func (c *Container) LastCommand() *Command

func (*Container) StartCommand

func (c *Container) StartCommand(command string)

func (*Container) StdErr

func (c *Container) StdErr() io.Writer

func (*Container) StdOut

func (c *Container) StdOut() io.Writer

type ContainerPool

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

func NewPool

func NewPool() *ContainerPool

func (*ContainerPool) Exec

func (p *ContainerPool) Exec(params *ExecParams) (*Container, error)

func (*ContainerPool) GetAllContainers

func (p *ContainerPool) GetAllContainers() map[string]*Container

func (*ContainerPool) GetContainerByToken

func (p *ContainerPool) GetContainerByToken(token string) *Container

type ExecParams

type ExecParams struct {
	PullImage *string           `json:"pull_image"`
	Image     string            `json:"image"`
	Commands  []string          `json:"commands"`
	Shell     []string          `json:"shell"`
	Volumes   map[string]string `json:"volumes"`
}

type LineKind

type LineKind int

const (
	StdIn LineKind = iota //stdin is not used
	StdOut
	StdErr
)

type OutputLine

type OutputLine struct {
	Kind    LineKind  `json:"kind"`
	Content []byte    `json:"content"`
	Time    time.Time `json:"time"`
}

type Writer

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

func (Writer) Write

func (w Writer) Write(p []byte) (n int, err error)