github.com/Prakhar-Agarwal-byte/moby@v0.0.0-20231027092010-a14e3e8ab87e/api/types/container/hostconfig.go (about)

     1  package container // import "github.com/Prakhar-Agarwal-byte/moby/api/types/container"
     2  
     3  import (
     4  	"fmt"
     5  	"strings"
     6  
     7  	"github.com/Prakhar-Agarwal-byte/moby/api/types/blkiodev"
     8  	"github.com/Prakhar-Agarwal-byte/moby/api/types/mount"
     9  	"github.com/Prakhar-Agarwal-byte/moby/api/types/strslice"
    10  	"github.com/docker/go-connections/nat"
    11  	units "github.com/docker/go-units"
    12  )
    13  
    14  // CgroupnsMode represents the cgroup namespace mode of the container
    15  type CgroupnsMode string
    16  
    17  // cgroup namespace modes for containers
    18  const (
    19  	CgroupnsModeEmpty   CgroupnsMode = ""
    20  	CgroupnsModePrivate CgroupnsMode = "private"
    21  	CgroupnsModeHost    CgroupnsMode = "host"
    22  )
    23  
    24  // IsPrivate indicates whether the container uses its own private cgroup namespace
    25  func (c CgroupnsMode) IsPrivate() bool {
    26  	return c == CgroupnsModePrivate
    27  }
    28  
    29  // IsHost indicates whether the container shares the host's cgroup namespace
    30  func (c CgroupnsMode) IsHost() bool {
    31  	return c == CgroupnsModeHost
    32  }
    33  
    34  // IsEmpty indicates whether the container cgroup namespace mode is unset
    35  func (c CgroupnsMode) IsEmpty() bool {
    36  	return c == CgroupnsModeEmpty
    37  }
    38  
    39  // Valid indicates whether the cgroup namespace mode is valid
    40  func (c CgroupnsMode) Valid() bool {
    41  	return c.IsEmpty() || c.IsPrivate() || c.IsHost()
    42  }
    43  
    44  // Isolation represents the isolation technology of a container. The supported
    45  // values are platform specific
    46  type Isolation string
    47  
    48  // Isolation modes for containers
    49  const (
    50  	IsolationEmpty   Isolation = ""        // IsolationEmpty is unspecified (same behavior as default)
    51  	IsolationDefault Isolation = "default" // IsolationDefault is the default isolation mode on current daemon
    52  	IsolationProcess Isolation = "process" // IsolationProcess is process isolation mode
    53  	IsolationHyperV  Isolation = "hyperv"  // IsolationHyperV is HyperV isolation mode
    54  )
    55  
    56  // IsDefault indicates the default isolation technology of a container. On Linux this
    57  // is the native driver. On Windows, this is a Windows Server Container.
    58  func (i Isolation) IsDefault() bool {
    59  	// TODO consider making isolation-mode strict (case-sensitive)
    60  	v := Isolation(strings.ToLower(string(i)))
    61  	return v == IsolationDefault || v == IsolationEmpty
    62  }
    63  
    64  // IsHyperV indicates the use of a Hyper-V partition for isolation
    65  func (i Isolation) IsHyperV() bool {
    66  	// TODO consider making isolation-mode strict (case-sensitive)
    67  	return Isolation(strings.ToLower(string(i))) == IsolationHyperV
    68  }
    69  
    70  // IsProcess indicates the use of process isolation
    71  func (i Isolation) IsProcess() bool {
    72  	// TODO consider making isolation-mode strict (case-sensitive)
    73  	return Isolation(strings.ToLower(string(i))) == IsolationProcess
    74  }
    75  
    76  // IpcMode represents the container ipc stack.
    77  type IpcMode string
    78  
    79  // IpcMode constants
    80  const (
    81  	IPCModeNone      IpcMode = "none"
    82  	IPCModeHost      IpcMode = "host"
    83  	IPCModeContainer IpcMode = "container"
    84  	IPCModePrivate   IpcMode = "private"
    85  	IPCModeShareable IpcMode = "shareable"
    86  )
    87  
    88  // IsPrivate indicates whether the container uses its own private ipc namespace which can not be shared.
    89  func (n IpcMode) IsPrivate() bool {
    90  	return n == IPCModePrivate
    91  }
    92  
    93  // IsHost indicates whether the container shares the host's ipc namespace.
    94  func (n IpcMode) IsHost() bool {
    95  	return n == IPCModeHost
    96  }
    97  
    98  // IsShareable indicates whether the container's ipc namespace can be shared with another container.
    99  func (n IpcMode) IsShareable() bool {
   100  	return n == IPCModeShareable
   101  }
   102  
   103  // IsContainer indicates whether the container uses another container's ipc namespace.
   104  func (n IpcMode) IsContainer() bool {
   105  	_, ok := containerID(string(n))
   106  	return ok
   107  }
   108  
   109  // IsNone indicates whether container IpcMode is set to "none".
   110  func (n IpcMode) IsNone() bool {
   111  	return n == IPCModeNone
   112  }
   113  
   114  // IsEmpty indicates whether container IpcMode is empty
   115  func (n IpcMode) IsEmpty() bool {
   116  	return n == ""
   117  }
   118  
   119  // Valid indicates whether the ipc mode is valid.
   120  func (n IpcMode) Valid() bool {
   121  	// TODO(thaJeztah): align with PidMode, and consider container-mode without a container name/ID to be invalid.
   122  	return n.IsEmpty() || n.IsNone() || n.IsPrivate() || n.IsHost() || n.IsShareable() || n.IsContainer()
   123  }
   124  
   125  // Container returns the name of the container ipc stack is going to be used.
   126  func (n IpcMode) Container() (idOrName string) {
   127  	idOrName, _ = containerID(string(n))
   128  	return idOrName
   129  }
   130  
   131  // NetworkMode represents the container network stack.
   132  type NetworkMode string
   133  
   134  // IsNone indicates whether container isn't using a network stack.
   135  func (n NetworkMode) IsNone() bool {
   136  	return n == "none"
   137  }
   138  
   139  // IsDefault indicates whether container uses the default network stack.
   140  func (n NetworkMode) IsDefault() bool {
   141  	return n == "default"
   142  }
   143  
   144  // IsPrivate indicates whether container uses its private network stack.
   145  func (n NetworkMode) IsPrivate() bool {
   146  	return !(n.IsHost() || n.IsContainer())
   147  }
   148  
   149  // IsContainer indicates whether container uses a container network stack.
   150  func (n NetworkMode) IsContainer() bool {
   151  	_, ok := containerID(string(n))
   152  	return ok
   153  }
   154  
   155  // ConnectedContainer is the id of the container which network this container is connected to.
   156  func (n NetworkMode) ConnectedContainer() (idOrName string) {
   157  	idOrName, _ = containerID(string(n))
   158  	return idOrName
   159  }
   160  
   161  // UserDefined indicates user-created network
   162  func (n NetworkMode) UserDefined() string {
   163  	if n.IsUserDefined() {
   164  		return string(n)
   165  	}
   166  	return ""
   167  }
   168  
   169  // UsernsMode represents userns mode in the container.
   170  type UsernsMode string
   171  
   172  // IsHost indicates whether the container uses the host's userns.
   173  func (n UsernsMode) IsHost() bool {
   174  	return n == "host"
   175  }
   176  
   177  // IsPrivate indicates whether the container uses the a private userns.
   178  func (n UsernsMode) IsPrivate() bool {
   179  	return !n.IsHost()
   180  }
   181  
   182  // Valid indicates whether the userns is valid.
   183  func (n UsernsMode) Valid() bool {
   184  	return n == "" || n.IsHost()
   185  }
   186  
   187  // CgroupSpec represents the cgroup to use for the container.
   188  type CgroupSpec string
   189  
   190  // IsContainer indicates whether the container is using another container cgroup
   191  func (c CgroupSpec) IsContainer() bool {
   192  	_, ok := containerID(string(c))
   193  	return ok
   194  }
   195  
   196  // Valid indicates whether the cgroup spec is valid.
   197  func (c CgroupSpec) Valid() bool {
   198  	// TODO(thaJeztah): align with PidMode, and consider container-mode without a container name/ID to be invalid.
   199  	return c == "" || c.IsContainer()
   200  }
   201  
   202  // Container returns the ID or name of the container whose cgroup will be used.
   203  func (c CgroupSpec) Container() (idOrName string) {
   204  	idOrName, _ = containerID(string(c))
   205  	return idOrName
   206  }
   207  
   208  // UTSMode represents the UTS namespace of the container.
   209  type UTSMode string
   210  
   211  // IsPrivate indicates whether the container uses its private UTS namespace.
   212  func (n UTSMode) IsPrivate() bool {
   213  	return !n.IsHost()
   214  }
   215  
   216  // IsHost indicates whether the container uses the host's UTS namespace.
   217  func (n UTSMode) IsHost() bool {
   218  	return n == "host"
   219  }
   220  
   221  // Valid indicates whether the UTS namespace is valid.
   222  func (n UTSMode) Valid() bool {
   223  	return n == "" || n.IsHost()
   224  }
   225  
   226  // PidMode represents the pid namespace of the container.
   227  type PidMode string
   228  
   229  // IsPrivate indicates whether the container uses its own new pid namespace.
   230  func (n PidMode) IsPrivate() bool {
   231  	return !(n.IsHost() || n.IsContainer())
   232  }
   233  
   234  // IsHost indicates whether the container uses the host's pid namespace.
   235  func (n PidMode) IsHost() bool {
   236  	return n == "host"
   237  }
   238  
   239  // IsContainer indicates whether the container uses a container's pid namespace.
   240  func (n PidMode) IsContainer() bool {
   241  	_, ok := containerID(string(n))
   242  	return ok
   243  }
   244  
   245  // Valid indicates whether the pid namespace is valid.
   246  func (n PidMode) Valid() bool {
   247  	return n == "" || n.IsHost() || validContainer(string(n))
   248  }
   249  
   250  // Container returns the name of the container whose pid namespace is going to be used.
   251  func (n PidMode) Container() (idOrName string) {
   252  	idOrName, _ = containerID(string(n))
   253  	return idOrName
   254  }
   255  
   256  // DeviceRequest represents a request for devices from a device driver.
   257  // Used by GPU device drivers.
   258  type DeviceRequest struct {
   259  	Driver       string            // Name of device driver
   260  	Count        int               // Number of devices to request (-1 = All)
   261  	DeviceIDs    []string          // List of device IDs as recognizable by the device driver
   262  	Capabilities [][]string        // An OR list of AND lists of device capabilities (e.g. "gpu")
   263  	Options      map[string]string // Options to pass onto the device driver
   264  }
   265  
   266  // DeviceMapping represents the device mapping between the host and the container.
   267  type DeviceMapping struct {
   268  	PathOnHost        string
   269  	PathInContainer   string
   270  	CgroupPermissions string
   271  }
   272  
   273  // RestartPolicy represents the restart policies of the container.
   274  type RestartPolicy struct {
   275  	Name              RestartPolicyMode
   276  	MaximumRetryCount int
   277  }
   278  
   279  type RestartPolicyMode string
   280  
   281  const (
   282  	RestartPolicyDisabled      RestartPolicyMode = "no"
   283  	RestartPolicyAlways        RestartPolicyMode = "always"
   284  	RestartPolicyOnFailure     RestartPolicyMode = "on-failure"
   285  	RestartPolicyUnlessStopped RestartPolicyMode = "unless-stopped"
   286  )
   287  
   288  // IsNone indicates whether the container has the "no" restart policy.
   289  // This means the container will not automatically restart when exiting.
   290  func (rp *RestartPolicy) IsNone() bool {
   291  	return rp.Name == RestartPolicyDisabled || rp.Name == ""
   292  }
   293  
   294  // IsAlways indicates whether the container has the "always" restart policy.
   295  // This means the container will automatically restart regardless of the exit status.
   296  func (rp *RestartPolicy) IsAlways() bool {
   297  	return rp.Name == RestartPolicyAlways
   298  }
   299  
   300  // IsOnFailure indicates whether the container has the "on-failure" restart policy.
   301  // This means the container will automatically restart of exiting with a non-zero exit status.
   302  func (rp *RestartPolicy) IsOnFailure() bool {
   303  	return rp.Name == RestartPolicyOnFailure
   304  }
   305  
   306  // IsUnlessStopped indicates whether the container has the
   307  // "unless-stopped" restart policy. This means the container will
   308  // automatically restart unless user has put it to stopped state.
   309  func (rp *RestartPolicy) IsUnlessStopped() bool {
   310  	return rp.Name == RestartPolicyUnlessStopped
   311  }
   312  
   313  // IsSame compares two RestartPolicy to see if they are the same
   314  func (rp *RestartPolicy) IsSame(tp *RestartPolicy) bool {
   315  	return rp.Name == tp.Name && rp.MaximumRetryCount == tp.MaximumRetryCount
   316  }
   317  
   318  // ValidateRestartPolicy validates the given RestartPolicy.
   319  func ValidateRestartPolicy(policy RestartPolicy) error {
   320  	switch policy.Name {
   321  	case RestartPolicyAlways, RestartPolicyUnlessStopped, RestartPolicyDisabled:
   322  		if policy.MaximumRetryCount != 0 {
   323  			msg := "invalid restart policy: maximum retry count can only be used with 'on-failure'"
   324  			if policy.MaximumRetryCount < 0 {
   325  				msg += " and cannot be negative"
   326  			}
   327  			return &errInvalidParameter{fmt.Errorf(msg)}
   328  		}
   329  		return nil
   330  	case RestartPolicyOnFailure:
   331  		if policy.MaximumRetryCount < 0 {
   332  			return &errInvalidParameter{fmt.Errorf("invalid restart policy: maximum retry count cannot be negative")}
   333  		}
   334  		return nil
   335  	case "":
   336  		// Versions before v25.0.0 created an empty restart-policy "name" as
   337  		// default. Allow an empty name with "any" MaximumRetryCount for
   338  		// backward-compatibility.
   339  		return nil
   340  	default:
   341  		return &errInvalidParameter{fmt.Errorf("invalid restart policy: unknown policy '%s'; use one of '%s', '%s', '%s', or '%s'", policy.Name, RestartPolicyDisabled, RestartPolicyAlways, RestartPolicyOnFailure, RestartPolicyUnlessStopped)}
   342  	}
   343  }
   344  
   345  // LogMode is a type to define the available modes for logging
   346  // These modes affect how logs are handled when log messages start piling up.
   347  type LogMode string
   348  
   349  // Available logging modes
   350  const (
   351  	LogModeUnset    LogMode = ""
   352  	LogModeBlocking LogMode = "blocking"
   353  	LogModeNonBlock LogMode = "non-blocking"
   354  )
   355  
   356  // LogConfig represents the logging configuration of the container.
   357  type LogConfig struct {
   358  	Type   string
   359  	Config map[string]string
   360  }
   361  
   362  // Resources contains container's resources (cgroups config, ulimits...)
   363  type Resources struct {
   364  	// Applicable to all platforms
   365  	CPUShares int64 `json:"CpuShares"` // CPU shares (relative weight vs. other containers)
   366  	Memory    int64 // Memory limit (in bytes)
   367  	NanoCPUs  int64 `json:"NanoCpus"` // CPU quota in units of 10<sup>-9</sup> CPUs.
   368  
   369  	// Applicable to UNIX platforms
   370  	CgroupParent         string // Parent cgroup.
   371  	BlkioWeight          uint16 // Block IO weight (relative weight vs. other containers)
   372  	BlkioWeightDevice    []*blkiodev.WeightDevice
   373  	BlkioDeviceReadBps   []*blkiodev.ThrottleDevice
   374  	BlkioDeviceWriteBps  []*blkiodev.ThrottleDevice
   375  	BlkioDeviceReadIOps  []*blkiodev.ThrottleDevice
   376  	BlkioDeviceWriteIOps []*blkiodev.ThrottleDevice
   377  	CPUPeriod            int64           `json:"CpuPeriod"`          // CPU CFS (Completely Fair Scheduler) period
   378  	CPUQuota             int64           `json:"CpuQuota"`           // CPU CFS (Completely Fair Scheduler) quota
   379  	CPURealtimePeriod    int64           `json:"CpuRealtimePeriod"`  // CPU real-time period
   380  	CPURealtimeRuntime   int64           `json:"CpuRealtimeRuntime"` // CPU real-time runtime
   381  	CpusetCpus           string          // CpusetCpus 0-2, 0,1
   382  	CpusetMems           string          // CpusetMems 0-2, 0,1
   383  	Devices              []DeviceMapping // List of devices to map inside the container
   384  	DeviceCgroupRules    []string        // List of rule to be added to the device cgroup
   385  	DeviceRequests       []DeviceRequest // List of device requests for device drivers
   386  
   387  	// KernelMemory specifies the kernel memory limit (in bytes) for the container.
   388  	// Deprecated: kernel 5.4 deprecated kmem.limit_in_bytes.
   389  	KernelMemory      int64           `json:",omitempty"`
   390  	KernelMemoryTCP   int64           `json:",omitempty"` // Hard limit for kernel TCP buffer memory (in bytes)
   391  	MemoryReservation int64           // Memory soft limit (in bytes)
   392  	MemorySwap        int64           // Total memory usage (memory + swap); set `-1` to enable unlimited swap
   393  	MemorySwappiness  *int64          // Tuning container memory swappiness behaviour
   394  	OomKillDisable    *bool           // Whether to disable OOM Killer or not
   395  	PidsLimit         *int64          // Setting PIDs limit for a container; Set `0` or `-1` for unlimited, or `null` to not change.
   396  	Ulimits           []*units.Ulimit // List of ulimits to be set in the container
   397  
   398  	// Applicable to Windows
   399  	CPUCount           int64  `json:"CpuCount"`   // CPU count
   400  	CPUPercent         int64  `json:"CpuPercent"` // CPU percent
   401  	IOMaximumIOps      uint64 // Maximum IOps for the container system drive
   402  	IOMaximumBandwidth uint64 // Maximum IO in bytes per second for the container system drive
   403  }
   404  
   405  // UpdateConfig holds the mutable attributes of a Container.
   406  // Those attributes can be updated at runtime.
   407  type UpdateConfig struct {
   408  	// Contains container's resources (cgroups, ulimits)
   409  	Resources
   410  	RestartPolicy RestartPolicy
   411  }
   412  
   413  // HostConfig the non-portable Config structure of a container.
   414  // Here, "non-portable" means "dependent of the host we are running on".
   415  // Portable information *should* appear in Config.
   416  type HostConfig struct {
   417  	// Applicable to all platforms
   418  	Binds           []string          // List of volume bindings for this container
   419  	ContainerIDFile string            // File (path) where the containerId is written
   420  	LogConfig       LogConfig         // Configuration of the logs for this container
   421  	NetworkMode     NetworkMode       // Network mode to use for the container
   422  	PortBindings    nat.PortMap       // Port mapping between the exposed port (container) and the host
   423  	RestartPolicy   RestartPolicy     // Restart policy to be used for the container
   424  	AutoRemove      bool              // Automatically remove container when it exits
   425  	VolumeDriver    string            // Name of the volume driver used to mount volumes
   426  	VolumesFrom     []string          // List of volumes to take from other container
   427  	ConsoleSize     [2]uint           // Initial console size (height,width)
   428  	Annotations     map[string]string `json:",omitempty"` // Arbitrary non-identifying metadata attached to container and provided to the runtime
   429  
   430  	// Applicable to UNIX platforms
   431  	CapAdd          strslice.StrSlice // List of kernel capabilities to add to the container
   432  	CapDrop         strslice.StrSlice // List of kernel capabilities to remove from the container
   433  	CgroupnsMode    CgroupnsMode      // Cgroup namespace mode to use for the container
   434  	DNS             []string          `json:"Dns"`        // List of DNS server to lookup
   435  	DNSOptions      []string          `json:"DnsOptions"` // List of DNSOption to look for
   436  	DNSSearch       []string          `json:"DnsSearch"`  // List of DNSSearch to look for
   437  	ExtraHosts      []string          // List of extra hosts
   438  	GroupAdd        []string          // List of additional groups that the container process will run as
   439  	IpcMode         IpcMode           // IPC namespace to use for the container
   440  	Cgroup          CgroupSpec        // Cgroup to use for the container
   441  	Links           []string          // List of links (in the name:alias form)
   442  	OomScoreAdj     int               // Container preference for OOM-killing
   443  	PidMode         PidMode           // PID namespace to use for the container
   444  	Privileged      bool              // Is the container in privileged mode
   445  	PublishAllPorts bool              // Should docker publish all exposed port for the container
   446  	ReadonlyRootfs  bool              // Is the container root filesystem in read-only
   447  	SecurityOpt     []string          // List of string values to customize labels for MLS systems, such as SELinux.
   448  	StorageOpt      map[string]string `json:",omitempty"` // Storage driver options per container.
   449  	Tmpfs           map[string]string `json:",omitempty"` // List of tmpfs (mounts) used for the container
   450  	UTSMode         UTSMode           // UTS namespace to use for the container
   451  	UsernsMode      UsernsMode        // The user namespace to use for the container
   452  	ShmSize         int64             // Total shm memory usage
   453  	Sysctls         map[string]string `json:",omitempty"` // List of Namespaced sysctls used for the container
   454  	Runtime         string            `json:",omitempty"` // Runtime to use with this container
   455  
   456  	// Applicable to Windows
   457  	Isolation Isolation // Isolation technology of the container (e.g. default, hyperv)
   458  
   459  	// Contains container's resources (cgroups, ulimits)
   460  	Resources
   461  
   462  	// Mounts specs used by the container
   463  	Mounts []mount.Mount `json:",omitempty"`
   464  
   465  	// MaskedPaths is the list of paths to be masked inside the container (this overrides the default set of paths)
   466  	MaskedPaths []string
   467  
   468  	// ReadonlyPaths is the list of paths to be set as read-only inside the container (this overrides the default set of paths)
   469  	ReadonlyPaths []string
   470  
   471  	// Run a custom init inside the container, if null, use the daemon's configured settings
   472  	Init *bool `json:",omitempty"`
   473  }
   474  
   475  // containerID splits "container:<ID|name>" values. It returns the container
   476  // ID or name, and whether an ID/name was found. It returns an empty string and
   477  // a "false" if the value does not have a "container:" prefix. Further validation
   478  // of the returned, including checking if the value is empty, should be handled
   479  // by the caller.
   480  func containerID(val string) (idOrName string, ok bool) {
   481  	k, v, hasSep := strings.Cut(val, ":")
   482  	if !hasSep || k != "container" {
   483  		return "", false
   484  	}
   485  	return v, true
   486  }
   487  
   488  // validContainer checks if the given value is a "container:" mode with
   489  // a non-empty name/ID.
   490  func validContainer(val string) bool {
   491  	id, ok := containerID(val)
   492  	return ok && id != ""
   493  }