github.com/containers/podman/v4@v4.9.4/pkg/specgen/podspecgen.go (about) 1 package specgen 2 3 import ( 4 "net" 5 6 "github.com/containers/common/libnetwork/types" 7 storageTypes "github.com/containers/storage/types" 8 spec "github.com/opencontainers/runtime-spec/specs-go" 9 ) 10 11 // PodBasicConfig contains basic configuration options for pods. 12 type PodBasicConfig struct { 13 // Name is the name of the pod. 14 // If not provided, a name will be generated when the pod is created. 15 // Optional. 16 Name string `json:"name,omitempty"` 17 // Hostname is the pod's hostname. If not set, the name of the pod will 18 // be used (if a name was not provided here, the name auto-generated for 19 // the pod will be used). This will be used by the infra container and 20 // all containers in the pod as long as the UTS namespace is shared. 21 // Optional. 22 Hostname string `json:"hostname,omitempty"` 23 // ExitPolicy determines the pod's exit and stop behaviour. 24 ExitPolicy string `json:"exit_policy,omitempty"` 25 // Labels are key-value pairs that are used to add metadata to pods. 26 // Optional. 27 Labels map[string]string `json:"labels,omitempty"` 28 // NoInfra tells the pod not to create an infra container. If this is 29 // done, many networking-related options will become unavailable. 30 // Conflicts with setting any options in PodNetworkConfig, and the 31 // InfraCommand and InfraImages in this struct. 32 // Optional. 33 NoInfra bool `json:"no_infra,omitempty"` 34 // InfraConmonPidFile is a custom path to store the infra container's 35 // conmon PID. 36 InfraConmonPidFile string `json:"infra_conmon_pid_file,omitempty"` 37 // InfraCommand sets the command that will be used to start the infra 38 // container. 39 // If not set, the default set in the Libpod configuration file will be 40 // used. 41 // Conflicts with NoInfra=true. 42 // Optional. 43 InfraCommand []string `json:"infra_command,omitempty"` 44 // InfraImage is the image that will be used for the infra container. 45 // If not set, the default set in the Libpod configuration file will be 46 // used. 47 // Conflicts with NoInfra=true. 48 // Optional. 49 InfraImage string `json:"infra_image,omitempty"` 50 // InfraName is the name that will be used for the infra container. 51 // If not set, the default set in the Libpod configuration file will be 52 // used. 53 // Conflicts with NoInfra=true. 54 // Optional. 55 InfraName string `json:"infra_name,omitempty"` 56 // Ipc sets the IPC namespace of the pod, set to private by default. 57 // This configuration will then be shared with the entire pod if PID namespace sharing is enabled via --share 58 Ipc Namespace `json:"ipcns,omitempty"` 59 // SharedNamespaces instructs the pod to share a set of namespaces. 60 // Shared namespaces will be joined (by default) by every container 61 // which joins the pod. 62 // If not set and NoInfra is false, the pod will set a default set of 63 // namespaces to share. 64 // Conflicts with NoInfra=true. 65 // Optional. 66 SharedNamespaces []string `json:"shared_namespaces,omitempty"` 67 // RestartPolicy is the pod's restart policy - an action which 68 // will be taken when one or all the containers in the pod exits. 69 // If not given, the default policy will be set to Always, which 70 // restarts the containers in the pod when they exit indefinitely. 71 // Optional. 72 RestartPolicy string `json:"restart_policy,omitempty"` 73 // RestartRetries is the number of attempts that will be made to restart 74 // the container. 75 // Only available when RestartPolicy is set to "on-failure". 76 // Optional. 77 RestartRetries *uint `json:"restart_tries,omitempty"` 78 // PodCreateCommand is the command used to create this pod. 79 // This will be shown in the output of Inspect() on the pod, and may 80 // also be used by some tools that wish to recreate the pod 81 // (e.g. `podman generate systemd --new`). 82 // Optional. 83 // ShareParent determines if all containers in the pod will share the pod's cgroup as the cgroup parent 84 ShareParent *bool `json:"share_parent,omitempty"` 85 PodCreateCommand []string `json:"pod_create_command,omitempty"` 86 // Pid sets the process id namespace of the pod 87 // Optional (defaults to private if unset). This sets the PID namespace of the infra container 88 // This configuration will then be shared with the entire pod if PID namespace sharing is enabled via --share 89 Pid Namespace `json:"pidns,omitempty"` 90 // Userns is used to indicate which kind of Usernamespace to enter. 91 // Any containers created within the pod will inherit the pod's userns settings. 92 // Optional 93 Userns Namespace `json:"userns,omitempty"` 94 // UtsNs is used to indicate the UTS mode the pod is in 95 UtsNs Namespace `json:"utsns,omitempty"` 96 // Devices contains user specified Devices to be added to the Pod 97 Devices []string `json:"pod_devices,omitempty"` 98 // Sysctl sets kernel parameters for the pod 99 Sysctl map[string]string `json:"sysctl,omitempty"` 100 } 101 102 // PodNetworkConfig contains networking configuration for a pod. 103 type PodNetworkConfig struct { 104 // NetNS is the configuration to use for the infra container's network 105 // namespace. This network will, by default, be shared with all 106 // containers in the pod. 107 // Cannot be set to FromContainer and FromPod. 108 // Setting this to anything except default conflicts with NoInfra=true. 109 // Defaults to Bridge as root and Slirp as rootless. 110 // Mandatory. 111 NetNS Namespace `json:"netns,omitempty"` 112 // PortMappings is a set of ports to map into the infra container. 113 // As, by default, containers share their network with the infra 114 // container, this will forward the ports to the entire pod. 115 // Only available if NetNS is set to Bridge, Slirp, or Pasta. 116 // Optional. 117 PortMappings []types.PortMapping `json:"portmappings,omitempty"` 118 // Map of networks names to ids the container should join to. 119 // You can request additional settings for each network, you can 120 // set network aliases, static ips, static mac address and the 121 // network interface name for this container on the specific network. 122 // If the map is empty and the bridge network mode is set the container 123 // will be joined to the default network. 124 Networks map[string]types.PerNetworkOptions 125 // CNINetworks is a list of CNI networks to join the container to. 126 // If this list is empty, the default CNI network will be joined 127 // instead. If at least one entry is present, we will not join the 128 // default network (unless it is part of this list). 129 // Only available if NetNS is set to bridge. 130 // Optional. 131 // Deprecated: as of podman 4.0 use "Networks" instead. 132 CNINetworks []string `json:"cni_networks,omitempty"` 133 // NoManageResolvConf indicates that /etc/resolv.conf should not be 134 // managed by the pod. Instead, each container will create and manage a 135 // separate resolv.conf as if they had not joined a pod. 136 // Conflicts with NoInfra=true and DNSServer, DNSSearch, DNSOption. 137 // Optional. 138 NoManageResolvConf bool `json:"no_manage_resolv_conf,omitempty"` 139 // DNSServer is a set of DNS servers that will be used in the infra 140 // container's resolv.conf, which will, by default, be shared with all 141 // containers in the pod. 142 // If not provided, the host's DNS servers will be used, unless the only 143 // server set is a localhost address. As the container cannot connect to 144 // the host's localhost, a default server will instead be set. 145 // Conflicts with NoInfra=true. 146 // Optional. 147 DNSServer []net.IP `json:"dns_server,omitempty"` 148 // DNSSearch is a set of DNS search domains that will be used in the 149 // infra container's resolv.conf, which will, by default, be shared with 150 // all containers in the pod. 151 // If not provided, DNS search domains from the host's resolv.conf will 152 // be used. 153 // Conflicts with NoInfra=true. 154 // Optional. 155 DNSSearch []string `json:"dns_search,omitempty"` 156 // DNSOption is a set of DNS options that will be used in the infra 157 // container's resolv.conf, which will, by default, be shared with all 158 // containers in the pod. 159 // Conflicts with NoInfra=true. 160 // Optional. 161 DNSOption []string `json:"dns_option,omitempty"` 162 // NoManageHosts indicates that /etc/hosts should not be managed by the 163 // pod. Instead, each container will create a separate /etc/hosts as 164 // they would if not in a pod. 165 // Conflicts with HostAdd. 166 NoManageHosts bool `json:"no_manage_hosts,omitempty"` 167 // HostAdd is a set of hosts that will be added to the infra container's 168 // /etc/hosts that will, by default, be shared with all containers in 169 // the pod. 170 // Conflicts with NoInfra=true and NoManageHosts. 171 // Optional. 172 HostAdd []string `json:"hostadd,omitempty"` 173 // NetworkOptions are additional options for each network 174 // Optional. 175 NetworkOptions map[string][]string `json:"network_options,omitempty"` 176 } 177 178 // PodStorageConfig contains all of the storage related options for the pod and its infra container. 179 type PodStorageConfig struct { 180 // Mounts are mounts that will be added to the pod. 181 // These will supersede Image Volumes and VolumesFrom volumes where 182 // there are conflicts. 183 // Optional. 184 Mounts []spec.Mount `json:"mounts,omitempty"` 185 // Volumes are named volumes that will be added to the pod. 186 // These will supersede Image Volumes and VolumesFrom volumes where 187 // there are conflicts. 188 // Optional. 189 Volumes []*NamedVolume `json:"volumes,omitempty"` 190 // Overlay volumes are named volumes that will be added to the pod. 191 // Optional. 192 OverlayVolumes []*OverlayVolume `json:"overlay_volumes,omitempty"` 193 // Image volumes bind-mount a container-image mount into the pod's infra container. 194 // Optional. 195 ImageVolumes []*ImageVolume `json:"image_volumes,omitempty"` 196 // VolumesFrom is a set of containers whose volumes will be added to 197 // this pod. The name or ID of the container must be provided, and 198 // may optionally be followed by a : and then one or more 199 // comma-separated options. Valid options are 'ro', 'rw', and 'z'. 200 // Options will be used for all volumes sourced from the container. 201 VolumesFrom []string `json:"volumes_from,omitempty"` 202 // ShmSize is the size of the tmpfs to mount in at /dev/shm, in bytes. 203 // Conflicts with ShmSize if IpcNS is not private. 204 // Optional. 205 ShmSize *int64 `json:"shm_size,omitempty"` 206 // ShmSizeSystemd is the size of systemd-specific tmpfs mounts 207 // specifically /run, /run/lock, /var/log/journal and /tmp. 208 // Optional 209 ShmSizeSystemd *int64 `json:"shm_size_systemd,omitempty"` 210 } 211 212 // PodCgroupConfig contains configuration options about a pod's cgroups. 213 // This will be expanded in future updates to pods. 214 type PodCgroupConfig struct { 215 // CgroupParent is the parent for the Cgroup that the pod will create. 216 // This pod cgroup will, in turn, be the default cgroup parent for all 217 // containers in the pod. 218 // Optional. 219 CgroupParent string `json:"cgroup_parent,omitempty"` 220 } 221 222 // PodSpecGenerator describes options to create a pod 223 // swagger:model PodSpecGenerator 224 type PodSpecGenerator struct { 225 PodBasicConfig 226 PodNetworkConfig 227 PodCgroupConfig 228 PodResourceConfig 229 PodStorageConfig 230 PodSecurityConfig 231 InfraContainerSpec *SpecGenerator `json:"-"` 232 233 // The ID of the pod's service container. 234 ServiceContainerID string `json:"serviceContainerID,omitempty"` 235 } 236 237 type PodResourceConfig struct { 238 // ResourceLimits contains linux specific CPU data for the pod 239 ResourceLimits *spec.LinuxResources `json:"resource_limits,omitempty"` 240 // CPU period of the cpuset, determined by --cpus 241 CPUPeriod uint64 `json:"cpu_period,omitempty"` 242 // CPU quota of the cpuset, determined by --cpus 243 CPUQuota int64 `json:"cpu_quota,omitempty"` 244 // ThrottleReadBpsDevice contains the rate at which the devices in the pod can be read from/accessed 245 ThrottleReadBpsDevice map[string]spec.LinuxThrottleDevice `json:"throttleReadBpsDevice,omitempty"` 246 } 247 248 type PodSecurityConfig struct { 249 SecurityOpt []string `json:"security_opt,omitempty"` 250 // IDMappings are UID and GID mappings that will be used by user 251 // namespaces. 252 // Required if UserNS is private. 253 IDMappings *storageTypes.IDMappingOptions `json:"idmappings,omitempty"` 254 } 255 256 // NewPodSpecGenerator creates a new pod spec 257 func NewPodSpecGenerator() *PodSpecGenerator { 258 return &PodSpecGenerator{} 259 }