pod

Documentation

Overview

package pod contains the data structure for the pod and functions to get information of the pod. It is shared by other packages, including the CLI implementation, api service, and the library.

Index

• Constants
• Variables
• func ReadUUIDFromFile(path string) (string, error)
• func WalkPods(dataDir string, include IncludeMask, f func(*Pod)) error
• func WriteUUIDToFile(uuid *types.UUID, path string) error
• type ErrChildNotReady
  • func (e ErrChildNotReady) Error() string
• type IncludeMask
• type Pod
  • func NewPod(dataDir string) (*Pod, error)
  • func PodFromUUIDString(dataDir, uuid string) (*Pod, error)
  • func (p *Pod) AppExitCode(appName string) (int, error)
  • func (p *Pod) AppImageManifest(appName string) (*schema.ImageManifest, error)
  • func (p *Pod) ContainerPid1() (pid int, err error)
  • func (p *Pod) CreationTime() (time.Time, error)
  • func (p *Pod) ExclusiveLockManifest() error
  • func (p *Pod) GCMarkedTime() (time.Time, error)
  • func (p *Pod) GetAppTreeStoreID(app types.ACName) (string, error)
  • func (p *Pod) GetAppsTreeStoreIDs() ([]string, error)
  • func (p *Pod) GetStage1TreeStoreID() (string, error)
  • func (p *Pod) IsAfterRun() bool
  • func (p *Pod) IsFinished() bool
  • func (p *Pod) IsMutable() bool
  • func (p *Pod) IsSupervisorReady() bool
  • func (p *Pod) JournalLogPath() (string, error)
  • func (p *Pod) Path() string
  • func (p *Pod) Pid() (int, error)
  • func (p *Pod) PodManifest() ([]byte, *schema.PodManifest, error)
  • func (p *Pod) PodManifestAvailable() bool
  • func (p *Pod) SandboxManifest() (*schema.PodManifest, error)
  • func (p *Pod) Stage1RootfsPath() (string, error)
  • func (p *Pod) StartTime() (time.Time, error)
  • func (p *Pod) State() string
  • func (p *Pod) Sync() error
  • func (p *Pod) ToExitedGarbage() error
  • func (p *Pod) ToGarbage() error
  • func (p *Pod) ToPrepared() error
  • func (p *Pod) ToPreparing() error
  • func (p *Pod) ToRun() error
  • func (p *Pod) UnlockManifest() error
  • func (p *Pod) UpdateManifest(m *schema.PodManifest, path string) error
  • func (p *Pod) UsesOverlay() bool
  • func (p *Pod) WaitFinished(ctx context.Context) error
  • func (p *Pod) WaitReady(ctx context.Context) error

Constants

const (
	Embryo         = "embryo"
	Preparing      = "preparing"
	AbortedPrepare = "aborted prepare"
	Prepared       = "prepared"
	Running        = "running"
	Deleting       = "deleting"
	ExitedDeleting = "exited deleting"
	Exited         = "exited"
	ExitedGarbage  = "exited garbage"
	Garbage        = "garbage"
)

Exported state. See Documentation/devel/pod-lifecycle.md for some explanation

Variables

var ErrImmutable = errors.New("immutable pod")

ErrImmutable is the error that is returned by SandboxManifest if the pod is immutable, hence changes on the pod manifest are not allowed.

Functions

func ReadUUIDFromFile

func ReadUUIDFromFile(path string) (string, error)

ReadUUIDFromFile reads the uuid string from the given path.

func WalkPods

func WalkPods(dataDir string, include IncludeMask, f func(*Pod)) error

WalkPods iterates over the included directories calling function f for every pod found. The pod will be closed after the function 'f' is executed.

func WriteUUIDToFile

func WriteUUIDToFile(uuid *types.UUID, path string) error

WriteUUIDToFile writes the uuid string to the given path.

Types

type ErrChildNotReady

type ErrChildNotReady struct {
}

func (ErrChildNotReady) Error

func (e ErrChildNotReady) Error() string

type IncludeMask

type IncludeMask byte

const (
	IncludeEmbryoDir IncludeMask = 1 << iota
	IncludePrepareDir
	IncludePreparedDir
	IncludeRunDir
	IncludeExitedGarbageDir
	IncludeGarbageDir

	IncludeMostDirs IncludeMask = (IncludeRunDir | IncludeExitedGarbageDir | IncludePrepareDir | IncludePreparedDir)
	IncludeAllDirs  IncludeMask = (IncludeMostDirs | IncludeEmbryoDir | IncludeGarbageDir)
)

type Pod

type Pod struct {
	UUID       *types.UUID
	Nets       []netinfo.NetInfo // list of networks (name, IP, iface) this pod is using
	MountLabel string            // Label to use for container image

	*lock.FileLock // the lock for the whole pod
	// contains filtered or unexported fields
}

Pod is the struct that reflects a pod and its lifecycle. It provides the necessary methods for state transitions and methods for querying internal state.

Unless documented otherwise methods do not refresh the pod state as it is reflected on the file system but only the pod state at the point where this struct was created.

See Documentation/devel/pod-lifecycle.md for some explanation.

func NewPod

func NewPod(dataDir string) (*Pod, error)

NewPod creates a new pod directory in the "preparing" state, allocating a unique uuid for it in the process. The returned pod is always left in an exclusively locked state (preparing is locked in the prepared directory) The pod must be closed using pod.Close()

func PodFromUUIDString

func PodFromUUIDString(dataDir, uuid string) (*Pod, error)

PodFromUUIDString attempts to resolve the supplied UUID and return a pod. The pod must be closed using pod.Close()

func (*Pod) AppExitCode

func (p *Pod) AppExitCode(appName string) (int, error)

AppExitCode returns the app's exit code. It returns an error if the exit code file doesn't exit or the content of the file is invalid.

func (*Pod) AppImageManifest

func (p *Pod) AppImageManifest(appName string) (*schema.ImageManifest, error)

AppImageManifest returns an ImageManifest for the app.

func (*Pod) ContainerPid1

func (p *Pod) ContainerPid1() (pid int, err error)

ContainerPid1 returns the pid of the process with pid 1 in the pod. Note: This method blocks indefinitely and refreshes the pod state.

func (*Pod) CreationTime

func (p *Pod) CreationTime() (time.Time, error)

CreationTime returns the time when the pod was created. This happens at prepare time.

func (*Pod) ExclusiveLockManifest

func (p *Pod) ExclusiveLockManifest() error

ExclusiveLockManifest gets an exclusive lock on only the pod manifest in the app sandbox. Since the pod might already be running, we can't just get an exclusive lock on the pod itself.

func (*Pod) GCMarkedTime

func (p *Pod) GCMarkedTime() (time.Time, error)

GCMarkedTime returns the time when the pod is marked by gc.

func (*Pod) GetAppTreeStoreID

func (p *Pod) GetAppTreeStoreID(app types.ACName) (string, error)

GetAppTreeStoreID returns the treeStoreID of the provided app. TODO(yifan): Maybe make this unexported.

func (*Pod) GetAppsTreeStoreIDs

func (p *Pod) GetAppsTreeStoreIDs() ([]string, error)

GetAppsTreeStoreIDs returns the treeStoreIDs of the apps images used in this pod. TODO(yifan): Maybe make this unexported.

func (*Pod) GetStage1TreeStoreID

func (p *Pod) GetStage1TreeStoreID() (string, error)

GetStage1TreeStoreID returns the treeStoreID of the stage1 image used in this pod TODO(yifan): Maybe make this unexported.

func (*Pod) IsAfterRun

func (p *Pod) IsAfterRun() bool

IsAfterRun returns true if the pod is in a post-running state, otherwise it returns false.

func (*Pod) IsFinished

func (p *Pod) IsFinished() bool

IsFinished returns true if the pod is in a terminal state, else false.

func (*Pod) IsMutable

func (p *Pod) IsMutable() bool

IsMutable can be used to determine if a pod is mutable

func (*Pod) IsSupervisorReady

func (p *Pod) IsSupervisorReady() bool

IsSupervisorReady checks if the pod supervisor (typically systemd-pid1) has reached its ready state. All errors are handled as non-readiness.

func (*Pod) JournalLogPath

func (p *Pod) JournalLogPath() (string, error)

JournalLogPath returns the path to the journal log dir of the pod.

func (*Pod) Path

func (p *Pod) Path() string

Path returns the path to the pod according to the current (cached) state.

func (*Pod) Pid

func (p *Pod) Pid() (int, error)

Pid returns the pid of the stage1 process that started the pod.

func (*Pod) PodManifest

func (p *Pod) PodManifest() ([]byte, *schema.PodManifest, error)

PodManifest reads the pod manifest, returns the raw bytes and the unmarshalled object.

func (*Pod) PodManifestAvailable

func (p *Pod) PodManifestAvailable() bool

PodManifestAvailable returns whether the caller should reasonably expect PodManifest to function in the pod's current state. Namely, in Preparing, AbortedPrepare, and Deleting it's possible for the manifest to not be present

func (*Pod) SandboxManifest

func (p *Pod) SandboxManifest() (*schema.PodManifest, error)

SandboxManifest loads the underlying pod manifest and checks whether mutable operations are allowed. It returns ErrImmutable if the pod does not allow mutable operations or any other error if the operation failed. Upon success a reference to the pod manifest is returned and mutable operations are possible.

func (*Pod) Stage1RootfsPath

func (p *Pod) Stage1RootfsPath() (string, error)

Stage1RootfsPath returns the stage1 path of the pod.

func (*Pod) StartTime

func (p *Pod) StartTime() (time.Time, error)

StartTime returns the time when the pod was started.

func (*Pod) State

func (p *Pod) State() string

State returns the current state of the pod

func (*Pod) Sync

func (p *Pod) Sync() error

Sync syncs the pod data. By now it calls a syncfs on the filesystem containing the pod's directory.

func (*Pod) ToExitedGarbage

func (p *Pod) ToExitedGarbage() error

ToExitedGarbage transitions a pod from run -> exitedGarbage This method refreshes the pod state.

func (*Pod) ToGarbage

func (p *Pod) ToGarbage() error

ToGarbage transitions a pod from abortedPrepared -> garbage or prepared -> garbage This method refreshes the pod state.

func (*Pod) ToPrepared

func (p *Pod) ToPrepared() error

ToPrepared transitions a pod from preparing -> prepared, leaves the pod unlocked in the prepared directory. only the creator of the pod (via NewPod()) may do this, nobody to race with. This method refreshes the pod state.

func (*Pod) ToPreparing

func (p *Pod) ToPreparing() error

ToPrepare transitions a pod from embryo -> preparing, leaves the pod locked in the prepare directory. only the creator of the pod (via NewPod()) may do this, nobody to race with. This method refreshes the pod state.

func (*Pod) ToRun

func (p *Pod) ToRun() error

ToRun transitions a pod from prepared -> run, leaves the pod locked in the run directory. the creator of the pod (via NewPod()) may also jump directly from preparing -> run This method refreshes the pod state.

func (*Pod) UnlockManifest

func (p *Pod) UnlockManifest() error

UnlockManifest unlocks the pod manifest lock.

func (*Pod) UpdateManifest

func (p *Pod) UpdateManifest(m *schema.PodManifest, path string) error

UpdateManifest updates the given pod manifest in the given path atomically on the file system. The pod manifest has to be locked using LockManifest first to avoid races in case of concurrent writes.

func (*Pod) UsesOverlay

func (p *Pod) UsesOverlay() bool

UsesOverlay returns whether the pod Uses overlayfs. TODO(yifan): Maybe make this function unexported.

func (*Pod) WaitFinished

func (p *Pod) WaitFinished(ctx context.Context) error

WaitFinished waits for a pod to finish by polling every 100 milliseconds or until the given context is cancelled. This method refreshes the pod state. It is the caller's responsibility to determine the actual terminal state.

func (*Pod) WaitReady

func (p *Pod) WaitReady(ctx context.Context) error

WaitReady blocks until the pod is ready by polling the readiness state every 100 milliseconds or until the given context is cancelled. This method refreshes the pod state.