specgen

package
v4.7.0-rc1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 15, 2023 License: Apache-2.0 Imports: 26 Imported by: 21

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidSpecConfig describes an error that the given SpecGenerator is invalid
	ErrInvalidSpecConfig = errors.New("invalid configuration")
	// SystemDValues describes the only values that SystemD can be
	SystemDValues = []string{"true", "false", "always"}
	// ImageVolumeModeValues describes the only values that ImageVolumeMode can be
	ImageVolumeModeValues = []string{"ignore", define.TypeTmpfs, "anonymous"}
)
View Source 
var (
	// ErrNoStaticIPRootless is used when a rootless user requests to assign a static IP address
	// to a pod or container
	ErrNoStaticIPRootless = errors.New("rootless containers and pods cannot be assigned static IP addresses")
	// ErrNoStaticMACRootless is used when a rootless user requests to assign a static MAC address
	// to a pod or container
	ErrNoStaticMACRootless = errors.New("rootless containers and pods cannot be assigned static MAC addresses")
	// Multiple volume mounts to the same destination is not allowed
	ErrDuplicateDest = errors.New("duplicate mount destination")
)
View Source 
var (
	// ErrInvalidPodSpecConfig describes an error given when the podspecgenerator is invalid
	ErrInvalidPodSpecConfig = errors.New("invalid pod spec")
)

Functions

func ConvertWinMountPath added in v4.1.0 

func ConvertWinMountPath(path string) (string, error)

Converts a Windows path to a WSL guest path if local env is a WSL linux guest or this is a Windows client.

func FinishThrottleDevices added in v4.3.0 

func FinishThrottleDevices(s *SpecGenerator) error

FinishThrottleDevices takes the temporary representation of the throttle devices in the specgen and looks up the major and major minors. it then sets the throttle devices proper in the specgen

func GenVolumeMounts 

func GenVolumeMounts(volumeFlag []string) (map[string]spec.Mount, map[string]*NamedVolume, map[string]*OverlayVolume, error)

GenVolumeMounts parses user input into mounts, volumes and overlay volumes

func SetupUserNS 

func SetupUserNS(idmappings *storage.IDMappingOptions, userns Namespace, g *generate.Generator) (string, error)

func SplitVolumeString added in v4.1.0 

func SplitVolumeString(vol string) []string

Splits a volume string, accounting for Win drive paths when running as a WSL linux guest or Windows client

func StringSlicesEqual added in v4.3.0 

func StringSlicesEqual(a, b []string) bool

func WeightDevices added in v4.3.0 

func WeightDevices(specgen *SpecGenerator) error

Types

type ContainerBasicConfig 

type ContainerBasicConfig struct {
	// Name is the name the container will be given.
	// If no name is provided, one will be randomly generated.
	// Optional.
	Name string `json:"name,omitempty"`
	// Pod is the ID of the pod the container will join.
	// Optional.
	Pod string `json:"pod,omitempty"`
	// Entrypoint is the container's entrypoint.
	// If not given and Image is specified, this will be populated by the
	// image's configuration.
	// Optional.
	Entrypoint []string `json:"entrypoint,omitempty"`
	// Command is the container's command.
	// If not given and Image is specified, this will be populated by the
	// image's configuration.
	// Optional.
	Command []string `json:"command,omitempty"`
	// EnvHost indicates that the host environment should be added to container
	// Optional.
	EnvHost bool `json:"env_host,omitempty"`
	// EnvHTTPProxy indicates that the http host proxy environment variables
	// should be added to container
	// Optional.
	HTTPProxy bool `json:"httpproxy,omitempty"`
	// Env is a set of environment variables that will be set in the
	// container.
	// Optional.
	Env map[string]string `json:"env,omitempty"`
	// Terminal is whether the container will create a PTY.
	// Optional.
	Terminal bool `json:"terminal,omitempty"`
	// Stdin is whether the container will keep its STDIN open.
	Stdin bool `json:"stdin,omitempty"`
	// Labels are key-value pairs that are used to add metadata to
	// containers.
	// Optional.
	Labels map[string]string `json:"labels,omitempty"`
	// Annotations are key-value options passed into the container runtime
	// that can be used to trigger special behavior.
	// Optional.
	Annotations map[string]string `json:"annotations,omitempty"`
	// StopSignal is the signal that will be used to stop the container.
	// Must be a non-zero integer below SIGRTMAX.
	// If not provided, the default, SIGTERM, will be used.
	// Will conflict with Systemd if Systemd is set to "true" or "always".
	// Optional.
	StopSignal *syscall.Signal `json:"stop_signal,omitempty"`
	// StopTimeout is a timeout between the container's stop signal being
	// sent and SIGKILL being sent.
	// If not provided, the default will be used.
	// If 0 is used, stop signal will not be sent, and SIGKILL will be sent
	// instead.
	// Optional.
	StopTimeout *uint `json:"stop_timeout,omitempty"`
	// Timeout is a maximum time in seconds the container will run before
	// main process is sent SIGKILL.
	// If 0 is used, signal will not be sent. Container can run indefinitely
	// Optional.
	Timeout uint `json:"timeout,omitempty"`
	// LogConfiguration describes the logging for a container including
	// driver, path, and options.
	// Optional
	LogConfiguration *LogConfig `json:"log_configuration,omitempty"`
	// ConmonPidFile is a path at which a PID file for Conmon will be
	// placed.
	// If not given, a default location will be used.
	// Optional.
	ConmonPidFile string `json:"conmon_pid_file,omitempty"`
	// RawImageName is the user-specified and unprocessed input referring
	// to a local or a remote image.
	RawImageName string `json:"raw_image_name,omitempty"`
	// ImageOS is the user-specified image OS
	ImageOS string `json:"image_os,omitempty"`
	// ImageArch is the user-specified image architecture
	ImageArch string `json:"image_arch,omitempty"`
	// ImageVariant is the user-specified image variant
	ImageVariant string `json:"image_variant,omitempty"`
	// RestartPolicy is the container's restart policy - an action which
	// will be taken when the container exits.
	// If not given, the default policy, which does nothing, will be used.
	// Optional.
	RestartPolicy string `json:"restart_policy,omitempty"`
	// RestartRetries is the number of attempts that will be made to restart
	// the container.
	// Only available when RestartPolicy is set to "on-failure".
	// Optional.
	RestartRetries *uint `json:"restart_tries,omitempty"`
	// OCIRuntime is the name of the OCI runtime that will be used to create
	// the container.
	// If not specified, the default will be used.
	// Optional.
	OCIRuntime string `json:"oci_runtime,omitempty"`
	// Systemd is whether the container will be started in systemd mode.
	// Valid options are "true", "false", and "always".
	// "true" enables this mode only if the binary run in the container is
	// /sbin/init or systemd. "always" unconditionally enables systemd mode.
	// "false" unconditionally disables systemd mode.
	// If enabled, mounts and stop signal will be modified.
	// If set to "always" or set to "true" and conditionally triggered,
	// conflicts with StopSignal.
	// If not specified, "false" will be assumed.
	// Optional.
	Systemd string `json:"systemd,omitempty"`
	// Determine how to handle the NOTIFY_SOCKET - do we participate or pass it through
	// "container" - let the OCI runtime deal with it, advertise conmon's MAINPID
	// "conmon-only" - advertise conmon's MAINPID, send READY when started, don't pass to OCI
	// "ignore" - unset NOTIFY_SOCKET
	SdNotifyMode string `json:"sdnotifyMode,omitempty"`
	// Namespace is the libpod namespace the container will be placed in.
	// Optional.
	Namespace string `json:"namespace,omitempty"`
	// PidNS is the container's PID namespace.
	// It defaults to private.
	// Mandatory.
	PidNS Namespace `json:"pidns,omitempty"`
	// UtsNS is the container's UTS namespace.
	// It defaults to private.
	// Must be set to Private to set Hostname.
	// Mandatory.
	UtsNS Namespace `json:"utsns,omitempty"`
	// Hostname is the container's hostname. If not set, the hostname will
	// not be modified (if UtsNS is not private) or will be set to the
	// container ID (if UtsNS is private).
	// Conflicts with UtsNS if UtsNS is not set to private.
	// Optional.
	Hostname string `json:"hostname,omitempty"`
	// HostUsers is a list of host usernames or UIDs to add to the container
	// /etc/passwd file
	HostUsers []string `json:"hostusers,omitempty"`
	// Sysctl sets kernel parameters for the container
	Sysctl map[string]string `json:"sysctl,omitempty"`
	// Remove indicates if the container should be removed once it has been started
	// and exits
	Remove bool `json:"remove,omitempty"`
	// ContainerCreateCommand is the command that was used to create this
	// container.
	// This will be shown in the output of Inspect() on the container, and
	// may also be used by some tools that wish to recreate the container
	// (e.g. `podman generate systemd --new`).
	// Optional.
	ContainerCreateCommand []string `json:"containerCreateCommand,omitempty"`
	// PreserveFDs is a number of additional file descriptors (in addition
	// to 0, 1, 2) that will be passed to the executed process. The total FDs
	// passed will be 3 + PreserveFDs.
	// set tags as `json:"-"` for not supported remote
	// Optional.
	PreserveFDs uint `json:"-"`
	// Timezone is the timezone inside the container.
	// Local means it has the same timezone as the host machine
	// Optional.
	Timezone string `json:"timezone,omitempty"`
	// DependencyContainers is an array of containers this container
	// depends on. Dependency containers must be started before this
	// container. Dependencies can be specified by name or full/partial ID.
	// Optional.
	DependencyContainers []string `json:"dependencyContainers,omitempty"`
	// PidFile is the file that saves container process id.
	// set tags as `json:"-"` for not supported remote
	// Optional.
	PidFile string `json:"-"`
	// EnvSecrets are secrets that will be set as environment variables
	// Optional.
	EnvSecrets map[string]string `json:"secret_env,omitempty"`
	// InitContainerType describes if this container is an init container
	// and if so, what type: always or once
	InitContainerType string `json:"init_container_type"`
	// Personality allows users to configure different execution domains.
	// Execution domains tell Linux how to map signal numbers into signal actions.
	// The execution domain system allows Linux to provide limited support
	// for binaries compiled under other UNIX-like operating systems.
	Personality *spec.LinuxPersonality `json:"personality,omitempty"`
	// EnvMerge takes the specified environment variables from image and preprocess them before injecting them into the
	// container.
	EnvMerge []string `json:"envmerge,omitempty"`
	// UnsetEnv unsets the specified default environment variables from the image or from buildin or containers.conf
	// Optional.
	UnsetEnv []string `json:"unsetenv,omitempty"`
	// UnsetEnvAll unsetall default environment variables from the image or from buildin or containers.conf
	// UnsetEnvAll unsets all default environment variables from the image or from buildin
	// Optional.
	UnsetEnvAll bool `json:"unsetenvall,omitempty"`
	// Passwd is a container run option that determines if we are validating users/groups before running the container
	Passwd *bool `json:"manage_password,omitempty"`
	// PasswdEntry specifies arbitrary data to append to a file.
	PasswdEntry string `json:"passwd_entry,omitempty"`
	// GroupEntry specifies arbitrary data to append to a file.
	GroupEntry string `json:"group_entry,omitempty"`
}

ContainerBasicConfig contains the basic parts of a container.

type ContainerCgroupConfig 

type ContainerCgroupConfig struct {
	// CgroupNS is the container's cgroup namespace.
	// It defaults to private.
	// Mandatory.
	CgroupNS Namespace `json:"cgroupns,omitempty"`
	// CgroupsMode sets a policy for how cgroups will be created in the
	// container, including the ability to disable creation entirely.
	CgroupsMode string `json:"cgroups_mode,omitempty"`
	// CgroupParent is the container's Cgroup parent.
	// If not set, the default for the current cgroup driver will be used.
	// Optional.
	CgroupParent string `json:"cgroup_parent,omitempty"`
}

ContainerCgroupConfig contains configuration information about a container's cgroups.

type ContainerHealthCheckConfig 

type ContainerHealthCheckConfig struct {
	HealthConfig               *manifest.Schema2HealthConfig     `json:"healthconfig,omitempty"`
	HealthCheckOnFailureAction define.HealthCheckOnFailureAction `json:"health_check_on_failure_action,omitempty"`
	// Startup healthcheck for a container.
	// Requires that HealthConfig be set.
	// Optional.
	StartupHealthConfig *define.StartupHealthCheck `json:"startupHealthConfig,omitempty"`
}

ContainerHealthCheckConfig describes a container healthcheck with attributes like command, retries, interval, start period, and timeout.

type ContainerNetworkConfig 

type ContainerNetworkConfig struct {
	// NetNS is the configuration to use for the container's network
	// namespace.
	// Mandatory.
	NetNS Namespace `json:"netns,omitempty"`
	// PortBindings is a set of ports to map into the container.
	// Only available if NetNS is set to bridge, slirp, or pasta.
	// Optional.
	PortMappings []nettypes.PortMapping `json:"portmappings,omitempty"`
	// PublishExposedPorts will publish ports specified in the image to
	// random unused ports (guaranteed to be above 1024) on the host.
	// This is based on ports set in Expose below, and any ports specified
	// by the Image (if one is given).
	// Only available if NetNS is set to Bridge or Slirp.
	PublishExposedPorts bool `json:"publish_image_ports,omitempty"`
	// Expose is a number of ports that will be forwarded to the container
	// if PublishExposedPorts is set.
	// Expose is a map of uint16 (port number) to a string representing
	// protocol i.e map[uint16]string. Allowed protocols are "tcp", "udp", and "sctp", or some
	// combination of the three separated by commas.
	// If protocol is set to "" we will assume TCP.
	// Only available if NetNS is set to Bridge or Slirp, and
	// PublishExposedPorts is set.
	// Optional.
	Expose map[uint16]string `json:"expose,omitempty"`
	// Map of networks names or ids that the container should join.
	// You can request additional settings for each network, you can
	// set network aliases, static ips, static mac address  and the
	// network interface name for this container on the specific network.
	// If the map is empty and the bridge network mode is set the container
	// will be joined to the default network.
	Networks map[string]nettypes.PerNetworkOptions
	// CNINetworks is a list of CNI networks to join the container to.
	// If this list is empty, the default CNI network will be joined
	// instead. If at least one entry is present, we will not join the
	// default network (unless it is part of this list).
	// Only available if NetNS is set to bridge.
	// Optional.
	// Deprecated: as of podman 4.0 use "Networks" instead.
	CNINetworks []string `json:"cni_networks,omitempty"`
	// UseImageResolvConf indicates that resolv.conf should not be managed
	// by Podman, but instead sourced from the image.
	// Conflicts with DNSServer, DNSSearch, DNSOption.
	UseImageResolvConf bool `json:"use_image_resolve_conf,omitempty"`
	// DNSServers is a set of DNS servers that will be used in the
	// container's resolv.conf, replacing the host's DNS Servers which are
	// used by default.
	// Conflicts with UseImageResolvConf.
	// Optional.
	DNSServers []net.IP `json:"dns_server,omitempty"`
	// DNSSearch is a set of DNS search domains that will be used in the
	// container's resolv.conf, replacing the host's DNS search domains
	// which are used by default.
	// Conflicts with UseImageResolvConf.
	// Optional.
	DNSSearch []string `json:"dns_search,omitempty"`
	// DNSOptions is a set of DNS options that will be used in the
	// container's resolv.conf, replacing the host's DNS options which are
	// used by default.
	// Conflicts with UseImageResolvConf.
	// Optional.
	DNSOptions []string `json:"dns_option,omitempty"`
	// UseImageHosts indicates that /etc/hosts should not be managed by
	// Podman, and instead sourced from the image.
	// Conflicts with HostAdd.
	// Do not set omitempty here, if this is false it should be set to not get
	// the server default.
	// Ideally this would be a pointer so we could differentiate between an
	// explicitly false/true and unset (containers.conf default). However
	// specgen is stable so we can not change this right now.
	// TODO (5.0): change to pointer
	UseImageHosts bool `json:"use_image_hosts"`
	// HostAdd is a set of hosts which will be added to the container's
	// /etc/hosts file.
	// Conflicts with UseImageHosts.
	// Optional.
	HostAdd []string `json:"hostadd,omitempty"`
	// NetworkOptions are additional options for each network
	// Optional.
	NetworkOptions map[string][]string `json:"network_options,omitempty"`
}

ContainerNetworkConfig contains information on a container's network configuration.

type ContainerResourceConfig 

type ContainerResourceConfig struct {
	// ResourceLimits are resource limits to apply to the container.,
	// Can only be set as root on cgroups v1 systems, but can be set as
	// rootless as well for cgroups v2.
	// Optional.
	ResourceLimits *spec.LinuxResources `json:"resource_limits,omitempty"`
	// Rlimits are POSIX rlimits to apply to the container.
	// Optional.
	Rlimits []spec.POSIXRlimit `json:"r_limits,omitempty"`
	// OOMScoreAdj adjusts the score used by the OOM killer to determine
	// processes to kill for the container's process.
	// Optional.
	OOMScoreAdj *int `json:"oom_score_adj,omitempty"`
	// Weight per cgroup per device, can override BlkioWeight
	WeightDevice map[string]spec.LinuxWeightDevice `json:"weightDevice,omitempty"`
	// IO read rate limit per cgroup per device, bytes per second
	ThrottleReadBpsDevice map[string]spec.LinuxThrottleDevice `json:"throttleReadBpsDevice,omitempty"`
	// IO write rate limit per cgroup per device, bytes per second
	ThrottleWriteBpsDevice map[string]spec.LinuxThrottleDevice `json:"throttleWriteBpsDevice,omitempty"`
	// IO read rate limit per cgroup per device, IO per second
	ThrottleReadIOPSDevice map[string]spec.LinuxThrottleDevice `json:"throttleReadIOPSDevice,omitempty"`
	// IO write rate limit per cgroup per device, IO per second
	ThrottleWriteIOPSDevice map[string]spec.LinuxThrottleDevice `json:"throttleWriteIOPSDevice,omitempty"`
	// CgroupConf are key-value options passed into the container runtime
	// that are used to configure cgroup v2.
	// Optional.
	CgroupConf map[string]string `json:"unified,omitempty"`
	// CPU period of the cpuset, determined by --cpus
	CPUPeriod uint64 `json:"cpu_period,omitempty"`
	// CPU quota of the cpuset, determined by --cpus
	CPUQuota int64 `json:"cpu_quota,omitempty"`
}

ContainerResourceConfig contains information on container resource limits.

type ContainerSecurityConfig 

type ContainerSecurityConfig struct {
	// Privileged is whether the container is privileged.
	// Privileged does the following:
	// - Adds all devices on the system to the container.
	// - Adds all capabilities to the container.
	// - Disables Seccomp, SELinux, and Apparmor confinement.
	//   (Though SELinux can be manually re-enabled).
	// TODO: this conflicts with things.
	// TODO: this does more.
	Privileged bool `json:"privileged,omitempty"`
	// User is the user the container will be run as.
	// Can be given as a UID or a username; if a username, it will be
	// resolved within the container, using the container's /etc/passwd.
	// If unset, the container will be run as root.
	// Optional.
	User string `json:"user,omitempty"`
	// Groups are a list of supplemental groups the container's user will
	// be granted access to.
	// Optional.
	Groups []string `json:"groups,omitempty"`
	// CapAdd are capabilities which will be added to the container.
	// Conflicts with Privileged.
	// Optional.
	CapAdd []string `json:"cap_add,omitempty"`
	// CapDrop are capabilities which will be removed from the container.
	// Conflicts with Privileged.
	// Optional.
	CapDrop []string `json:"cap_drop,omitempty"`
	// SelinuxProcessLabel is the process label the container will use.
	// If SELinux is enabled and this is not specified, a label will be
	// automatically generated if not specified.
	// Optional.
	SelinuxOpts []string `json:"selinux_opts,omitempty"`
	// ApparmorProfile is the name of the Apparmor profile the container
	// will use.
	// Optional.
	ApparmorProfile string `json:"apparmor_profile,omitempty"`
	// SeccompPolicy determines which seccomp profile gets applied
	// the container. valid values: empty,default,image
	SeccompPolicy string `json:"seccomp_policy,omitempty"`
	// SeccompProfilePath is the path to a JSON file containing the
	// container's Seccomp profile.
	// If not specified, no Seccomp profile will be used.
	// Optional.
	SeccompProfilePath string `json:"seccomp_profile_path,omitempty"`
	// NoNewPrivileges is whether the container will set the no new
	// privileges flag on create, which disables gaining additional
	// privileges (e.g. via setuid) in the container.
	NoNewPrivileges bool `json:"no_new_privileges,omitempty"`
	// UserNS is the container's user namespace.
	// It defaults to host, indicating that no user namespace will be
	// created.
	// If set to private, IDMappings must be set.
	// Mandatory.
	UserNS Namespace `json:"userns,omitempty"`
	// IDMappings are UID and GID mappings that will be used by user
	// namespaces.
	// Required if UserNS is private.
	IDMappings *types.IDMappingOptions `json:"idmappings,omitempty"`
	// ReadOnlyFilesystem indicates that everything will be mounted
	// as read-only
	ReadOnlyFilesystem bool `json:"read_only_filesystem,omitempty"`
	// ReadWriteTmpfs indicates that when running with a ReadOnlyFilesystem
	// mount temporary file systems
	ReadWriteTmpfs bool `json:"read_write_tmpfs,omitempty"`

	// LabelNested indicates whether or not the container is allowed to
	// run fully nested containers including labelling
	LabelNested bool `json:"label_nested,omitempty"`

	// Umask is the umask the init process of the container will be run with.
	Umask string `json:"umask,omitempty"`
	// ProcOpts are the options used for the proc mount.
	ProcOpts []string `json:"procfs_opts,omitempty"`
	// Mask is the path we want to mask in the container. This masks the paths
	// given in addition to the default list.
	// Optional
	Mask []string `json:"mask,omitempty"`
	// Unmask is the path we want to unmask in the container. To override
	// all the default paths that are masked, set unmask=ALL.
	Unmask []string `json:"unmask,omitempty"`
}

ContainerSecurityConfig is a container's security features, including SELinux, Apparmor, and Seccomp.

type ContainerStorageConfig 

type ContainerStorageConfig struct {
	// Image is the image the container will be based on. The image will be
	// used as the container's root filesystem, and its environment vars,
	// volumes, and other configuration will be applied to the container.
	// Conflicts with Rootfs.
	// At least one of Image or Rootfs must be specified.
	Image string `json:"image"`
	// Rootfs is the path to a directory that will be used as the
	// container's root filesystem. No modification will be made to the
	// directory, it will be directly mounted into the container as root.
	// Conflicts with Image.
	// At least one of Image or Rootfs must be specified.
	Rootfs string `json:"rootfs,omitempty"`
	// RootfsOverlay tells if rootfs is actually an overlay on top of base path
	RootfsOverlay bool `json:"rootfs_overlay,omitempty"`
	// RootfsMapping specifies if there are mappings to apply to the rootfs.
	RootfsMapping *string `json:"rootfs_mapping,omitempty"`
	// ImageVolumeMode indicates how image volumes will be created.
	// Supported modes are "ignore" (do not create), "tmpfs" (create as
	// tmpfs), and "anonymous" (create as anonymous volumes).
	// The default if unset is anonymous.
	// Optional.
	ImageVolumeMode string `json:"image_volume_mode,omitempty"`
	// VolumesFrom is a set of containers whose volumes will be added to
	// this container. The name or ID of the container must be provided, and
	// may optionally be followed by a : and then one or more
	// comma-separated options. Valid options are 'ro', 'rw', and 'z'.
	// Options will be used for all volumes sourced from the container.
	VolumesFrom []string `json:"volumes_from,omitempty"`
	// Init specifies that an init binary will be mounted into the
	// container, and will be used as PID1.
	Init bool `json:"init,omitempty"`
	// InitPath specifies the path to the init binary that will be added if
	// Init is specified above. If not specified, the default set in the
	// Libpod config will be used. Ignored if Init above is not set.
	// Optional.
	InitPath string `json:"init_path,omitempty"`
	// Mounts are mounts that will be added to the container.
	// These will supersede Image Volumes and VolumesFrom volumes where
	// there are conflicts.
	// Optional.
	Mounts []spec.Mount `json:"mounts,omitempty"`
	// Volumes are named volumes that will be added to the container.
	// These will supersede Image Volumes and VolumesFrom volumes where
	// there are conflicts.
	// Optional.
	Volumes []*NamedVolume `json:"volumes,omitempty"`
	// Overlay volumes are named volumes that will be added to the container.
	// Optional.
	OverlayVolumes []*OverlayVolume `json:"overlay_volumes,omitempty"`
	// Image volumes bind-mount a container-image mount into the container.
	// Optional.
	ImageVolumes []*ImageVolume `json:"image_volumes,omitempty"`
	// Devices are devices that will be added to the container.
	// Optional.
	Devices []spec.LinuxDevice `json:"devices,omitempty"`
	// DeviceCgroupRule are device cgroup rules that allow containers
	// to use additional types of devices.
	DeviceCgroupRule []spec.LinuxDeviceCgroup `json:"device_cgroup_rule,omitempty"`
	// DevicesFrom is a way to ensure your container inherits device specific information from another container
	DevicesFrom []string `json:"devices_from,omitempty"`
	// HostDeviceList is used to recreate the mounted device on inherited containers
	HostDeviceList []spec.LinuxDevice `json:"host_device_list,omitempty"`
	// IpcNS is the container's IPC namespace.
	// Default is private.
	// Conflicts with ShmSize if not set to private.
	// Mandatory.
	IpcNS Namespace `json:"ipcns,omitempty"`
	// ShmSize is the size of the tmpfs to mount in at /dev/shm, in bytes.
	// Conflicts with ShmSize if IpcNS is not private.
	// Optional.
	ShmSize *int64 `json:"shm_size,omitempty"`
	// ShmSizeSystemd is the size of systemd-specific tmpfs mounts
	// specifically /run, /run/lock, /var/log/journal and /tmp.
	// Optional
	ShmSizeSystemd *int64 `json:"shm_size_systemd,omitempty"`
	// WorkDir is the container's working directory.
	// If unset, the default, /, will be used.
	// Optional.
	WorkDir string `json:"work_dir,omitempty"`
	// Create the working directory if it doesn't exist.
	// If unset, it doesn't create it.
	// Optional.
	CreateWorkingDir bool `json:"create_working_dir,omitempty"`
	// StorageOpts is the container's storage options
	// Optional.
	StorageOpts map[string]string `json:"storage_opts,omitempty"`
	// RootfsPropagation is the rootfs propagation mode for the container.
	// If not set, the default of rslave will be used.
	// Optional.
	RootfsPropagation string `json:"rootfs_propagation,omitempty"`
	// Secrets are the secrets that will be added to the container
	// Optional.
	Secrets []Secret `json:"secrets,omitempty"`
	// Volatile specifies whether the container storage can be optimized
	// at the cost of not syncing all the dirty files in memory.
	Volatile bool `json:"volatile,omitempty"`
	// ChrootDirs is an additional set of directories that need to be
	// treated as root directories. Standard bind mounts will be mounted
	// into paths relative to these directories.
	ChrootDirs []string `json:"chroot_directories,omitempty"`
}

ContainerStorageConfig contains information on the storage configuration of a container.

type ImageVolume 

type ImageVolume struct {
	// Source is the source of the image volume.  The image can be referred
	// to by name and by ID.
	Source string
	// Destination is the absolute path of the mount in the container.
	Destination string
	// ReadWrite sets the volume writable.
	ReadWrite bool
}

ImageVolume is a volume based on a container image. The container image is first mounted on the host and is then bind-mounted into the container. An ImageVolume is always mounted read-only.

type LogConfig 

type LogConfig struct {
	// LogDriver is the container's log driver.
	// Optional.
	Driver string `json:"driver,omitempty"`
	// LogPath is the path the container's logs will be stored at.
	// Only available if LogDriver is set to "json-file" or "k8s-file".
	// Optional.
	Path string `json:"path,omitempty"`
	// Size is the maximum size of the log file
	// Optional.
	Size int64 `json:"size,omitempty"`
	// A set of options to accompany the log driver.
	// Optional.
	Options map[string]string `json:"options,omitempty"`
}

LogConfig describes the logging characteristics for a container swagger:model LogConfigLibpod

type NamedVolume 

type NamedVolume struct {
	// Name is the name of the named volume to be mounted. May be empty.
	// If empty, a new named volume with a pseudorandomly generated name
	// will be mounted at the given destination.
	Name string
	// Destination to mount the named volume within the container. Must be
	// an absolute path. Path will be created if it does not exist.
	Dest string
	// Options are options that the named volume will be mounted with.
	Options []string
	// IsAnonymous sets the named volume as anonymous even if it has a name
	// This is used for emptyDir volumes from a kube yaml
	IsAnonymous bool
	// SubPath stores the sub directory of the named volume to be mounted in the container
	SubPath string
}

NamedVolume holds information about a named volume that will be mounted into the container.

type Namespace 

type Namespace struct {
	NSMode NamespaceMode `json:"nsmode,omitempty"`
	Value  string        `json:"value,omitempty"`
}

Namespace describes the namespace

func ParseCgroupNamespace 

func ParseCgroupNamespace(ns string) (Namespace, error)

ParseCgroupNamespace parses a cgroup namespace specification in string form.

func ParseIPCNamespace added in v4.1.0 

func ParseIPCNamespace(ns string) (Namespace, error)

ParseIPCNamespace parses an ipc namespace specification in string form.

func ParseNamespace 

func ParseNamespace(ns string) (Namespace, error)

ParseNamespace parses a namespace in string form. This is not intended for the network namespace, which has a separate function.

func ParseNetworkFlag 

func ParseNetworkFlag(networks []string, pastaNetworkNameExists bool) (Namespace, map[string]types.PerNetworkOptions, map[string][]string, error)

ParseNetworkFlag parses a network string slice into the network options If the input is nil or empty it will use the default setting from containers.conf TODO (5.0): Drop pastaNetworkNameExists

func ParseUserNamespace 

func ParseUserNamespace(ns string) (Namespace, error)

ParseUserNamespace parses a user namespace specification in string form.

func (*Namespace) IsAuto 

func (n *Namespace) IsAuto() bool

IsAuto indicates the namespace is auto

func (*Namespace) IsBridge 

func (n *Namespace) IsBridge() bool

IsBridge returns a bool if the namespace is a Bridge

func (*Namespace) IsContainer 

func (n *Namespace) IsContainer() bool

IsContainer indicates via bool if the namespace is based on a container

func (*Namespace) IsDefault 

func (n *Namespace) IsDefault() bool

IsDefault returns whether the namespace is set to the default setting (which also includes the empty string).

func (*Namespace) IsHost 

func (n *Namespace) IsHost() bool

IsHost returns a bool if the namespace is host based

func (*Namespace) IsKeepID 

func (n *Namespace) IsKeepID() bool

IsKeepID indicates the namespace is KeepID

func (*Namespace) IsNoMap added in v4.1.0 

func (n *Namespace) IsNoMap() bool

IsNoMap indicates the namespace is NoMap

func (*Namespace) IsNone added in v4.1.0 

func (n *Namespace) IsNone() bool

IsNone returns a bool if the namespace is set to none

func (*Namespace) IsPath 

func (n *Namespace) IsPath() bool

IsPath indicates via bool if the namespace is based on a path

func (*Namespace) IsPod 

func (n *Namespace) IsPod() bool

IsPod indicates via bool if the namespace is based on a pod

func (*Namespace) IsPrivate 

func (n *Namespace) IsPrivate() bool

IsPrivate indicates the namespace is private

func (*Namespace) String 

func (n *Namespace) String() string

type NamespaceMode 

type NamespaceMode string
const (
	// Default indicates the spec generator should determine
	// a sane default
	Default NamespaceMode = "default"
	// Host means the namespace is derived from the host
	Host NamespaceMode = "host"
	// Path is the path to a namespace
	Path NamespaceMode = "path"
	// FromContainer means namespace is derived from a
	// different container
	FromContainer NamespaceMode = "container"
	// FromPod indicates the namespace is derived from a pod
	FromPod NamespaceMode = "pod"
	// Private indicates the namespace is private
	Private NamespaceMode = "private"
	// Shareable indicates the namespace is shareable
	Shareable NamespaceMode = "shareable"
	// None indicates the IPC namespace is created without mounting /dev/shm
	None NamespaceMode = "none"
	// NoNetwork indicates no network namespace should
	// be joined.  loopback should still exist.
	// Only used with the network namespace, invalid otherwise.
	NoNetwork NamespaceMode = "none"
	// Bridge indicates that the network backend (CNI/netavark)
	// should be used.
	// Only used with the network namespace, invalid otherwise.
	Bridge NamespaceMode = "bridge"
	// Slirp indicates that a slirp4netns network stack should
	// be used.
	// Only used with the network namespace, invalid otherwise.
	Slirp NamespaceMode = "slirp4netns"
	// Pasta indicates that a pasta network stack should be used.
	// Only used with the network namespace, invalid otherwise.
	Pasta NamespaceMode = "pasta"
	// KeepId indicates a user namespace to keep the owner uid inside
	// of the namespace itself.
	// Only used with the user namespace, invalid otherwise.
	KeepID NamespaceMode = "keep-id"
	// NoMap indicates a user namespace to keep the owner uid out
	// of the namespace itself.
	// Only used with the user namespace, invalid otherwise.
	NoMap NamespaceMode = "no-map"
	// Auto indicates to automatically create a user namespace.
	// Only used with the user namespace, invalid otherwise.
	Auto NamespaceMode = "auto"

	// DefaultKernelNamespaces is a comma-separated list of default kernel
	// namespaces.
	DefaultKernelNamespaces = "ipc,net,uts"
)

type OverlayVolume 

type OverlayVolume struct {
	// Destination is the absolute path where the mount will be placed in the container.
	Destination string `json:"destination"`
	// Source specifies the source path of the mount.
	Source string `json:"source,omitempty"`
	// Options holds overlay volume options.
	Options []string `json:"options,omitempty"`
}

OverlayVolume holds information about an overlay volume that will be mounted into the container.

type PodBasicConfig 

type PodBasicConfig struct {
	// Name is the name of the pod.
	// If not provided, a name will be generated when the pod is created.
	// Optional.
	Name string `json:"name,omitempty"`
	// Hostname is the pod's hostname. If not set, the name of the pod will
	// be used (if a name was not provided here, the name auto-generated for
	// the pod will be used). This will be used by the infra container and
	// all containers in the pod as long as the UTS namespace is shared.
	// Optional.
	Hostname string `json:"hostname,omitempty"`
	// ExitPolicy determines the pod's exit and stop behaviour.
	ExitPolicy string `json:"exit_policy,omitempty"`
	// Labels are key-value pairs that are used to add metadata to pods.
	// Optional.
	Labels map[string]string `json:"labels,omitempty"`
	// NoInfra tells the pod not to create an infra container. If this is
	// done, many networking-related options will become unavailable.
	// Conflicts with setting any options in PodNetworkConfig, and the
	// InfraCommand and InfraImages in this struct.
	// Optional.
	NoInfra bool `json:"no_infra,omitempty"`
	// InfraConmonPidFile is a custom path to store the infra container's
	// conmon PID.
	InfraConmonPidFile string `json:"infra_conmon_pid_file,omitempty"`
	// InfraCommand sets the command that will be used to start the infra
	// container.
	// If not set, the default set in the Libpod configuration file will be
	// used.
	// Conflicts with NoInfra=true.
	// Optional.
	InfraCommand []string `json:"infra_command,omitempty"`
	// InfraImage is the image that will be used for the infra container.
	// If not set, the default set in the Libpod configuration file will be
	// used.
	// Conflicts with NoInfra=true.
	// Optional.
	InfraImage string `json:"infra_image,omitempty"`
	// InfraName is the name that will be used for the infra container.
	// If not set, the default set in the Libpod configuration file will be
	// used.
	// Conflicts with NoInfra=true.
	// Optional.
	InfraName string `json:"infra_name,omitempty"`
	// Ipc sets the IPC namespace of the pod, set to private by default.
	// This configuration will then be shared with the entire pod if PID namespace sharing is enabled via --share
	Ipc Namespace `json:"ipcns,omitempty"`
	// SharedNamespaces instructs the pod to share a set of namespaces.
	// Shared namespaces will be joined (by default) by every container
	// which joins the pod.
	// If not set and NoInfra is false, the pod will set a default set of
	// namespaces to share.
	// Conflicts with NoInfra=true.
	// Optional.
	SharedNamespaces []string `json:"shared_namespaces,omitempty"`
	// RestartPolicy is the pod's restart policy - an action which
	// will be taken when one or all the containers in the pod exits.
	// If not given, the default policy will be set to Always, which
	// restarts the containers in the pod when they exit indefinitely.
	// Optional.
	RestartPolicy string `json:"restart_policy,omitempty"`
	// RestartRetries is the number of attempts that will be made to restart
	// the container.
	// Only available when RestartPolicy is set to "on-failure".
	// Optional.
	RestartRetries *uint `json:"restart_tries,omitempty"`
	// PodCreateCommand is the command used to create this pod.
	// This will be shown in the output of Inspect() on the pod, and may
	// also be used by some tools that wish to recreate the pod
	// (e.g. `podman generate systemd --new`).
	// Optional.
	// ShareParent determines if all containers in the pod will share the pod's cgroup as the cgroup parent
	ShareParent      *bool    `json:"share_parent,omitempty"`
	PodCreateCommand []string `json:"pod_create_command,omitempty"`
	// Pid sets the process id namespace of the pod
	// Optional (defaults to private if unset). This sets the PID namespace of the infra container
	// This configuration will then be shared with the entire pod if PID namespace sharing is enabled via --share
	Pid Namespace `json:"pidns,omitempty"`
	// Userns is used to indicate which kind of Usernamespace to enter.
	// Any containers created within the pod will inherit the pod's userns settings.
	// Optional
	Userns Namespace `json:"userns,omitempty"`
	// UtsNs is used to indicate the UTS mode the pod is in
	UtsNs Namespace `json:"utsns,omitempty"`
	// Devices contains user specified Devices to be added to the Pod
	Devices []string `json:"pod_devices,omitempty"`
	// Sysctl sets kernel parameters for the pod
	Sysctl map[string]string `json:"sysctl,omitempty"`
}

PodBasicConfig contains basic configuration options for pods.

type PodCgroupConfig 

type PodCgroupConfig struct {
	// CgroupParent is the parent for the Cgroup that the pod will create.
	// This pod cgroup will, in turn, be the default cgroup parent for all
	// containers in the pod.
	// Optional.
	CgroupParent string `json:"cgroup_parent,omitempty"`
}

PodCgroupConfig contains configuration options about a pod's cgroups. This will be expanded in future updates to pods.

type PodNetworkConfig 

type PodNetworkConfig struct {
	// NetNS is the configuration to use for the infra container's network
	// namespace. This network will, by default, be shared with all
	// containers in the pod.
	// Cannot be set to FromContainer and FromPod.
	// Setting this to anything except default conflicts with NoInfra=true.
	// Defaults to Bridge as root and Slirp as rootless.
	// Mandatory.
	NetNS Namespace `json:"netns,omitempty"`
	// PortMappings is a set of ports to map into the infra container.
	// As, by default, containers share their network with the infra
	// container, this will forward the ports to the entire pod.
	// Only available if NetNS is set to Bridge, Slirp, or Pasta.
	// Optional.
	PortMappings []types.PortMapping `json:"portmappings,omitempty"`
	// Map of networks names to ids the container should join to.
	// You can request additional settings for each network, you can
	// set network aliases, static ips, static mac address  and the
	// network interface name for this container on the specific network.
	// If the map is empty and the bridge network mode is set the container
	// will be joined to the default network.
	Networks map[string]types.PerNetworkOptions
	// CNINetworks is a list of CNI networks to join the container to.
	// If this list is empty, the default CNI network will be joined
	// instead. If at least one entry is present, we will not join the
	// default network (unless it is part of this list).
	// Only available if NetNS is set to bridge.
	// Optional.
	// Deprecated: as of podman 4.0 use "Networks" instead.
	CNINetworks []string `json:"cni_networks,omitempty"`
	// NoManageResolvConf indicates that /etc/resolv.conf should not be
	// managed by the pod. Instead, each container will create and manage a
	// separate resolv.conf as if they had not joined a pod.
	// Conflicts with NoInfra=true and DNSServer, DNSSearch, DNSOption.
	// Optional.
	NoManageResolvConf bool `json:"no_manage_resolv_conf,omitempty"`
	// DNSServer is a set of DNS servers that will be used in the infra
	// container's resolv.conf, which will, by default, be shared with all
	// containers in the pod.
	// If not provided, the host's DNS servers will be used, unless the only
	// server set is a localhost address. As the container cannot connect to
	// the host's localhost, a default server will instead be set.
	// Conflicts with NoInfra=true.
	// Optional.
	DNSServer []net.IP `json:"dns_server,omitempty"`
	// DNSSearch is a set of DNS search domains that will be used in the
	// infra container's resolv.conf, which will, by default, be shared with
	// all containers in the pod.
	// If not provided, DNS search domains from the host's resolv.conf will
	// be used.
	// Conflicts with NoInfra=true.
	// Optional.
	DNSSearch []string `json:"dns_search,omitempty"`
	// DNSOption is a set of DNS options that will be used in the infra
	// container's resolv.conf, which will, by default, be shared with all
	// containers in the pod.
	// Conflicts with NoInfra=true.
	// Optional.
	DNSOption []string `json:"dns_option,omitempty"`
	// NoManageHosts indicates that /etc/hosts should not be managed by the
	// pod. Instead, each container will create a separate /etc/hosts as
	// they would if not in a pod.
	// Conflicts with HostAdd.
	NoManageHosts bool `json:"no_manage_hosts,omitempty"`
	// HostAdd is a set of hosts that will be added to the infra container's
	// /etc/hosts that will, by default, be shared with all containers in
	// the pod.
	// Conflicts with NoInfra=true and NoManageHosts.
	// Optional.
	HostAdd []string `json:"hostadd,omitempty"`
	// NetworkOptions are additional options for each network
	// Optional.
	NetworkOptions map[string][]string `json:"network_options,omitempty"`
}

PodNetworkConfig contains networking configuration for a pod.

type PodResourceConfig 

type PodResourceConfig struct {
	// ResourceLimits contains linux specific CPU data for the pod
	ResourceLimits *spec.LinuxResources `json:"resource_limits,omitempty"`
	// CPU period of the cpuset, determined by --cpus
	CPUPeriod uint64 `json:"cpu_period,omitempty"`
	// CPU quota of the cpuset, determined by --cpus
	CPUQuota int64 `json:"cpu_quota,omitempty"`
	// ThrottleReadBpsDevice contains the rate at which the devices in the pod can be read from/accessed
	ThrottleReadBpsDevice map[string]spec.LinuxThrottleDevice `json:"throttleReadBpsDevice,omitempty"`
}

type PodSecurityConfig 

type PodSecurityConfig struct {
	SecurityOpt []string `json:"security_opt,omitempty"`
	// IDMappings are UID and GID mappings that will be used by user
	// namespaces.
	// Required if UserNS is private.
	IDMappings *storageTypes.IDMappingOptions `json:"idmappings,omitempty"`
}

type PodSpecGenerator 

type PodSpecGenerator struct {
	PodBasicConfig
	PodNetworkConfig
	PodCgroupConfig
	PodResourceConfig
	PodStorageConfig
	PodSecurityConfig
	InfraContainerSpec *SpecGenerator `json:"-"`

	// The ID of the pod's service container.
	ServiceContainerID string `json:"serviceContainerID,omitempty"`
}

PodSpecGenerator describes options to create a pod swagger:model PodSpecGenerator

func NewPodSpecGenerator 

func NewPodSpecGenerator() *PodSpecGenerator

NewPodSpecGenerator creates a new pod spec

func (*PodSpecGenerator) Validate 

func (p *PodSpecGenerator) Validate() error

Validate verifies the input is valid

type PodStorageConfig 

type PodStorageConfig struct {
	// Mounts are mounts that will be added to the pod.
	// These will supersede Image Volumes and VolumesFrom volumes where
	// there are conflicts.
	// Optional.
	Mounts []spec.Mount `json:"mounts,omitempty"`
	// Volumes are named volumes that will be added to the pod.
	// These will supersede Image Volumes and VolumesFrom  volumes where
	// there are conflicts.
	// Optional.
	Volumes []*NamedVolume `json:"volumes,omitempty"`
	// Overlay volumes are named volumes that will be added to the pod.
	// Optional.
	OverlayVolumes []*OverlayVolume `json:"overlay_volumes,omitempty"`
	// Image volumes bind-mount a container-image mount into the pod's infra container.
	// Optional.
	ImageVolumes []*ImageVolume `json:"image_volumes,omitempty"`
	// VolumesFrom is a set of containers whose volumes will be added to
	// this pod. The name or ID of the container must be provided, and
	// may optionally be followed by a : and then one or more
	// comma-separated options. Valid options are 'ro', 'rw', and 'z'.
	// Options will be used for all volumes sourced from the container.
	VolumesFrom []string `json:"volumes_from,omitempty"`
	// ShmSize is the size of the tmpfs to mount in at /dev/shm, in bytes.
	// Conflicts with ShmSize if IpcNS is not private.
	// Optional.
	ShmSize *int64 `json:"shm_size,omitempty"`
	// ShmSizeSystemd is the size of systemd-specific tmpfs mounts
	// specifically /run, /run/lock, /var/log/journal and /tmp.
	// Optional
	ShmSizeSystemd *int64 `json:"shm_size_systemd,omitempty"`
}

PodStorageConfig contains all of the storage related options for the pod and its infra container.

type Secret 

type Secret struct {
	Source string
	Target string
	UID    uint32
	GID    uint32
	Mode   uint32
}

type SpecGenerator 

type SpecGenerator struct {
	ContainerBasicConfig
	ContainerStorageConfig
	ContainerSecurityConfig
	ContainerCgroupConfig
	ContainerNetworkConfig
	ContainerResourceConfig
	ContainerHealthCheckConfig
	// contains filtered or unexported fields
}

SpecGenerator creates an OCI spec and Libpod configuration options to create a container based on the given configuration. swagger:model SpecGenerator

func NewSpecGenerator 

func NewSpecGenerator(arg string, rootfs bool) *SpecGenerator

NewSpecGenerator returns a SpecGenerator struct given one of two mandatory inputs

func NewSpecGeneratorWithRootfs 

func NewSpecGeneratorWithRootfs(rootfs string) *SpecGenerator

NewSpecGenerator returns a SpecGenerator struct given one of two mandatory inputs

func (*SpecGenerator) GetImage 

func (s *SpecGenerator) GetImage() (*libimage.Image, string)

Image returns the associated image for the generator. May be nil if no image has been set yet.

func (*SpecGenerator) InitResourceLimits added in v4.3.0 

func (s *SpecGenerator) InitResourceLimits(rtc *config.Config)

func (*SpecGenerator) IsInitContainer added in v4.6.0 

func (s *SpecGenerator) IsInitContainer() bool

func (*SpecGenerator) SetImage 

func (s *SpecGenerator) SetImage(image *libimage.Image, resolvedImageName string)

SetImage sets the associated for the generator.

func (*SpecGenerator) Validate 

func (s *SpecGenerator) Validate() error

Validate verifies that the given SpecGenerator is valid and satisfies required input for creating a container.

Source Files

View all Source files

Directories

Path Synopsis
kube

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.