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 }