api

Documentation

Overview

Package api defines the API outline for working with different container runtimes.

The user should first establish some kind of connection as client with their desired container runtime. The client configuraton could be either by specifying it manually, or by recognizing them on the host first.

After establishing a client connection with container runtime, the user could invoke the client API to enumerate containers and images by their IDs, and open one of these entities furtherly.

Index

• type Cluster
• type ClusterResource
• type Container
• type File
• type FileSystem
• type Image
• type Layer
• type Process
• type Psutil
• type Runtime

Types

type Cluster

type Cluster interface {
	Close() error

	// Version return version of cluster
	Version() string

	// ConfigPath return config path of cluster
	ConfigPath() string

	// ConfigBytes return config path of cluster
	ConfigBytes() []byte

	// ListNamespaces attempt to list all namespaces in cluster
	ListNamespaces() ([]string, error)

	// InCluster return kubernetes client whether in cluster
	InCluster() bool

	// Resource attempt to open ClusterResource
	// accord schema.GroupVersionResource
	Resource(namespace string, kind string) (ClusterResource, error)
}

Cluster is the connection established with a specific specs cluster

type ClusterResource

type ClusterResource interface {
	Close() error

	// Kind return resource kind
	Kind() string

	// Get attempt to get resource raw bytes from cluster
	Get(ctx context.Context, name string) ([]byte, error)

	// List attempts to list resources from cluster
	// return resource name for Get method
	List(ctx context.Context) ([]string, error)

	// Create attempts to create resource in cluster
	Create(ctx context.Context, resource []byte) error

	// Update attempts to update resource in cluster
	Update(ctx context.Context, resource []byte) error
}

type Container

type Container interface {
	FileSystem
	Psutil

	Close() error
	ID() string
	Name() string
	ImageID() string

	OCISpec() (*specs.Spec, error)
	OCIState() (*specs.State, error)
}

type File

type File interface {
	io.ReadWriteCloser
	io.ReaderAt
	io.WriterAt
	io.Seeker

	Stat() (os.FileInfo, error)
}

File abstracts an open file from container. Some behaviours might be masked due to potential incompatibility.

type FileSystem

type FileSystem interface {
	Open(path string) (File, error)
	Stat(path string) (os.FileInfo, error)
	Lstat(path string) (os.FileInfo, error)
	Readlink(path string) (string, error)
	EvalSymlink(path string) (string, error)
	Readdir(path string) ([]os.FileInfo, error)
	Walk(root string, walkFn filepath.WalkFunc) error
}

FileSystem abstracts the property of an object to visit its internal file system structure, which is usually prepared by the container runtime.

type Image

type Image interface {
	FileSystem

	Close() error
	ID() string

	Repos() ([]string, error)
	RepoRefs() ([]string, error)

	OCISpecV1() (*imageV1.Image, error)
}

Image is the open image object from a runtime.

type Layer

type Layer interface {
	FileSystem

	Close() error
	ID() string
	Opaques() ([]string, error)
	Whiteouts() ([]string, error)
}

Layer is the open layer object from a image.

type Process

type Process interface {
	Close()
	Children() ([]Process, error)
	Cmdline() (string, error)
	Cwd() (string, error)
	Environ() ([]string, error)
	Exe() (string, error)
	Gids() ([]int32, error)
	Parent() (Process, error)
	Ppid() (int32, error)
	Pid() (int32, error)
	HostPid() (int32, error)
	Uids() ([]int32, error)
	Name() (string, error)
	Status() (string, error)
	CreateTime() (time.Time, error)
}

type Psutil

type Psutil interface {
	Pids() ([]int32, error)
	PidExists(pid int32) (bool, error)
	NewProcess(pid int32) (Process, error)
}

type Runtime

type Runtime interface {
	Close() error

	// ListImageIDs attempt to enumerate the images by their
	// IDs managed by the container runtime, which could be
	// used to open the image.
	ListImageIDs() ([]string, error)

	// FindImageIDs attempt to match image ID by specifying
	// their human readable identifiers. It must follow the
	// following rules.
	//
	// 1. When pattern is image ID recognizable by this
	//    container runtime, it will be searched first.
	// 2. When pattern is pure hexadecimal, the digest value
	//    portion will be matched.
	// 3. When pattern is a single identifier, all images
	//    with the specified identifier will be matched.
	// 4. When pattern is a repository path, all images with
	//    the specified repository but different versions
	//    will be matched.
	// 5. When pattern is a named tagged or canonical
	//    reference, the whole portion will be matched.
	FindImageIDs(pattern string) ([]string, error)

	// OpenImageByID attempt to open a image by its ID.
	OpenImageByID(id string) (Image, error)

	// ListContainerIDs attempt to open a container by its ID.
	ListContainerIDs() ([]string, error)

	// FindContainerIDs attempt to match container ID by specifying
	// their human readable identifiers. It must follow the
	// following rules.
	FindContainerIDs(pattern string) ([]string, error)

	// OpenContainerByID attempt to open a container by its ID.
	OpenContainerByID(id string) (Container, error)
}

Runtime is the connection established with a specific container runtime, depending on the implementation and container runtime internal nature.