From 2c5e1f3bbf59df0ecb84b6835b26fa343c9f6b4c Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Mon, 10 Apr 2023 10:57:52 -0400 Subject: [PATCH] local build --- Containerfile.5.md | 41 +++++++++++++++ containers-auth.json.5.md | 4 +- containers-policy.json.5.md | 2 +- containers-signature.5.md | 4 +- containers-storage.conf.5.md | 6 +++ containers.conf | 31 ++++++++++-- containers.conf.5.md | 97 ++++++++++++++++++++++++++---------- shortnames.conf | 2 + storage.conf | 2 + 9 files changed, 155 insertions(+), 34 deletions(-) diff --git a/Containerfile.5.md b/Containerfile.5.md index 90226bc..12245e5 100644 --- a/Containerfile.5.md +++ b/Containerfile.5.md @@ -154,6 +154,47 @@ Current supported mount TYPES are bind, cache, secret and tmpfs. · rw, read-write: allows writes on the mount. +**RUN --network** + +`RUN --network` allows control over which networking environment the command +is run in. + +Syntax: `--network=` + +**Network types** + +| Type | Description | +|----------------------------------------------|----------------------------------------| +| [`default`](#run---networkdefault) (default) | Run in the default network. | +| [`none`](#run---networknone) | Run with no network access. | +| [`host`](#run---networkhost) | Run in the host's network environment. | + +##### RUN --network=default + +Equivalent to not supplying a flag at all, the command is run in the default +network for the build. + +##### RUN --network=none + +The command is run with no network access (`lo` is still available, but is +isolated to this process). + +##### Example: isolating external effects + +```dockerfile +FROM python:3.6 +ADD mypackage.tgz wheels/ +RUN --network=none pip install --find-links wheels mypackage +``` + +`pip` will only be able to install the packages provided in the tarfile, which +can be controlled by an earlier build stage. + +##### RUN --network=host + +The command is run in the host's network environment (similar to +`buildah build --network=host`, but on a per-instruction basis) + **RUN Secrets** diff --git a/containers-auth.json.5.md b/containers-auth.json.5.md index 4030a06..8f83a6c 100644 --- a/containers-auth.json.5.md +++ b/containers-auth.json.5.md @@ -18,8 +18,8 @@ Except the primary (read/write) file, other files are read-only, unless the user ## FORMAT -The auth.json file stores encrypted authentication information for the -user to container image registries. The file can have zero to many entries and +The auth.json file stores, or references, credentials that allow the user to authenticate +to container image registries. The file can have zero to many entries and is created by a `login` command from a container tool such as `podman login`, `buildah login` or `skopeo login`. Each entry either contains a single hostname (e.g. `docker.io`) or a namespace (e.g. `quay.io/user/image`) as a key diff --git a/containers-policy.json.5.md b/containers-policy.json.5.md index db40eb9..6aa5f80 100644 --- a/containers-policy.json.5.md +++ b/containers-policy.json.5.md @@ -282,7 +282,7 @@ signed by the provided public key. The `signedIdentity` field has the same semantics as in the `signedBy` requirement described above. Note that `cosign`-created signatures only contain a repository, so only `matchRepository` and `exactRepository` can be used to accept them (and that does not protect against substitution of a signed image with an unexpected tag). -To use this with images hosted on image registries, the relevant registry or repository must have the `use-sigstore-attachments` option enabled in containers-registries.d(5). +To use this with images hosted on image registries, the `use-sigstore-attachments` option needs to be enabled for the relevant registry or repository in the client's containers-registries.d(5). ## Examples diff --git a/containers-signature.5.md b/containers-signature.5.md index c0a9a92..cc6f9c3 100644 --- a/containers-signature.5.md +++ b/containers-signature.5.md @@ -68,7 +68,9 @@ the consumer MUST verify at least the following aspects of the signature (like the `github.com/containers/image/signature` package does): - The blob MUST be a “Signed Message” as defined RFC 4880 section 11.3. - (e.g. it MUST NOT be an unsigned “Literal Message”, or any other non-signature format). + (e.g. it MUST NOT be an unsigned “Literal Message”, + a “Cleartext Signature” as defined in RFC 4880 section 7, + or any other non-signature format). - The signature MUST have been made by an expected key trusted for the purpose (and the specific container image). - The signature MUST be correctly formed and pass the cryptographic validation. - The signature MUST correctly authenticate the included JSON payload diff --git a/containers-storage.conf.5.md b/containers-storage.conf.5.md index 2064648..672e6b9 100644 --- a/containers-storage.conf.5.md +++ b/containers-storage.conf.5.md @@ -64,6 +64,12 @@ Default directory to store all temporary writable content created by container s By default, the storage driver is set via the `driver` option. If it is not defined, then the best driver will be picked according to the current platform. This option allows you to override this internal priority list with a custom one to prefer certain drivers. Setting this option only has an effect if the local storage has not been initialized yet and the driver name is not set. +**transient_store** = "false" | "true" + +Transient store mode makes all container metadata be saved in temporary storage +(i.e. runroot above). This is faster, but doesn't persist across reboots. +Additional garbage collection must also be performed at boot-time, so this option should remain disabled in most configurations. (default: false) + ### STORAGE OPTIONS TABLE The `storage.options` table supports the following options: diff --git a/containers.conf b/containers.conf index 37d131b..b506955 100644 --- a/containers.conf +++ b/containers.conf @@ -33,6 +33,11 @@ # #base_hosts_file = "" +# List of cgroup_conf entries specifying a list of cgroup files to write to and +# their values. For example `memory.high=1073741824` sets the +# memory.high limit to 1GB. +# cgroup_conf = [] + # Default way to to create a cgroup namespace for the container # Options are: # `private` Create private Cgroup Namespace for the container. @@ -63,6 +68,7 @@ # "SETGID", # "SETPCAP", # "SETUID", +# "SYS_CHROOT", #] # A list of sysctls to be set in containers by default, @@ -197,6 +203,10 @@ log_driver = "journald" # #no_hosts = false +# Tune the host's OOM preferences for containers +# (accepts values from -1000 to 1000). +#oom_score_adj = 0 + # Default way to to create a PID namespace for the container # Options are: # `private` Create private PID Namespace for the container. @@ -294,6 +304,15 @@ log_driver = "journald" # "/opt/cni/bin", #] +# List of directories that will be searched for netavark plugins. +# +#netavark_plugin_dirs = [ +# "/usr/local/libexec/netavark", +# "/usr/libexec/netavark", +# "/usr/local/lib/netavark", +# "/usr/lib/netavark", +#] + # The network name of the default network to attach pods to. # #default_network = "podman" @@ -447,7 +466,7 @@ log_driver = "journald" # #image_parallel_copies = 0 -# Tells container engines how to handle the builtin image volumes. +# Tells container engines how to handle the built-in image volumes. # * bind: An anonymous named volume will be created and mounted # into the container. # * tmpfs: The volume is mounted onto the container as a tmpfs, @@ -463,13 +482,17 @@ log_driver = "journald" # Infra (pause) container image name for pod infra containers. When running a # pod, we start a `pause` process in a container to hold open the namespaces -# associated with the pod. This container does nothing other then sleep, -# reserving the pods resources for the lifetime of the pod. By default container -# engines run a builtin container using the pause executable. If you want override +# associated with the pod. This container does nothing other than sleep, +# reserving the pod's resources for the lifetime of the pod. By default container +# engines run a built-in container using the pause executable. If you want override # specify an image to pull. # #infra_image = "" +# Default Kubernetes kind/specification of the kubernetes yaml generated with the `podman kube generate` command. +# The possible options are `pod` and `deployment`. +#kube_generate_type = "pod" + # Specify the locking mechanism to use; valid values are "shm" and "file". # Change the default only if you are sure of what you are doing, in general # "file" is useful only on platforms where cgo is not available for using the diff --git a/containers.conf.5.md b/containers.conf.5.md index cac551c..2b546fe 100644 --- a/containers.conf.5.md +++ b/containers.conf.5.md @@ -9,11 +9,12 @@ Container engines like Podman & Buildah read containers.conf file, if it exists and modify the defaults for running containers on the host. containers.conf uses a TOML format that can be easily modified and versioned. -Container engines read the /usr/share/containers/containers.conf and -/etc/containers/containers.conf, and /etc/containers/containers.conf.d/*.conf files -if they exist. When running in rootless mode, they also read -$HOME/.config/containers/containers.conf and -$HOME/.config/containers/containers.conf.d/*.conf files. +Container engines read the __/usr/share/containers/containers.conf__, +__/etc/containers/containers.conf__, and __/etc/containers/containers.conf.d/\*.conf__ +files if they exist. +When running in rootless mode, they also read +__$HOME/.config/containers/containers.conf__ and +__$HOME/.config/containers/containers.conf.d/\*.conf__ files. Fields specified in containers conf override the default options, as well as options in previously read containers.conf files. @@ -22,10 +23,10 @@ Config files in the `.d` directories, are added in alpha numeric sorted order an Not all options are supported in all container engines. -Note container engines also use other configuration files for configuring the environment. +Note, container engines also use other configuration files for configuring the environment. * `storage.conf` for configuration of container and images storage. -* `registries.conf` for definition of container registires to search while pulling. +* `registries.conf` for definition of container registries to search while pulling. container images. * `policy.conf` for controlling which images can be pulled to the system. @@ -50,6 +51,7 @@ TOML can be simplified to: The containers table contains settings to configure and manage the OCI runtime. **annotations** = [] + List of annotations. Specified as "key=value" pairs to be added to all containers. Example: "run.oci.keep_original_groups=1" @@ -66,6 +68,12 @@ file. This must be either an absolute path or as special values "image" which uses the hosts file from the container image or "none" which means no base hosts file is used. The default is "" which will use /etc/hosts. +**cgroup_conf**=[] + +List of cgroup_conf entries specifying a list of cgroup files to write to and +their values. For example `memory.high=1073741824` sets the +memory.high limit to 1GB. + **cgroups**="enabled" Determines whether the container will create CGroups. @@ -98,6 +106,7 @@ default_capabilities = [ "SETGID", "SETPCAP", "SETUID", + "SYS_CHROOT", ] ``` @@ -227,6 +236,10 @@ Options are: Create /etc/hosts for the container. By default, container engines manage /etc/hosts, automatically adding the container's own IP address. +**oom_score_adj**=0 + +Tune the host's OOM preferences for containers (accepts values from -1000 to 1000). + **pidns**="private" Default way to to create a PID namespace for the container. @@ -324,6 +337,20 @@ cni_plugin_dirs = [ ] ``` +**netavark_plugin_dirs**=[] + +List of directories that will be searched for netavark plugins. + +The default list is: +``` +netavark_plugin_dirs = [ + "/usr/local/libexec/netavark", + "/usr/libexec/netavark", + "/usr/local/lib/netavark", + "/usr/lib/netavark", +] +``` + **default_network**="podman" The network name of the default network to attach pods to. @@ -355,8 +382,8 @@ default_subnet_pools = [ **network_config_dir**="/etc/cni/net.d/" Path to the directory where network configuration files are located. -For the CNI backend the default is "/etc/cni/net.d" as root -and "$HOME/.config/cni/net.d" as rootless. +For the CNI backend the default is __/etc/cni/net.d__ as root +and __$HOME/.config/cni/net.d__ as rootless. For the netavark backend "/etc/containers/networks" is used as root and "$graphroot/networks" as rootless. @@ -462,12 +489,14 @@ with detailed information about the container. Set to false by default. A is a list of directories which are used to search for helper binaries. The default paths on Linux are: + - `/usr/local/libexec/podman` - `/usr/local/lib/podman` - `/usr/libexec/podman` - `/usr/lib/podman` The default paths on macOS are: + - `/usr/local/opt/podman/libexec` - `/opt/homebrew/bin` - `/opt/homebrew/opt/podman/libexec` @@ -478,6 +507,7 @@ The default paths on macOS are: - `/usr/lib/podman` The default path on Windows is: + - `C:\Program Files\RedHat\Podman` **hooks_dir**=["/etc/containers/oci/hooks.d", ...] @@ -502,7 +532,7 @@ Not setting this field will fall back to containers/image defaults. (6) **image_volume_mode**="bind" -Tells container engines how to handle the builtin image volumes. +Tells container engines how to handle the built-in image volumes. * bind: An anonymous named volume will be created and mounted into the container. * tmpfs: The volume is mounted onto the container as a tmpfs, which allows the users to create content that disappears when the container is stopped. @@ -512,18 +542,22 @@ Tells container engines how to handle the builtin image volumes. Infra (pause) container image command for pod infra containers. When running a pod, we start a `/pause` process in a container to hold open the namespaces -associated with the pod. This container does nothing other then sleep, -reserving the pods resources for the lifetime of the pod. +associated with the pod. This container does nothing other than sleep, +reserving the pod's resources for the lifetime of the pod. **infra_image**="" Infra (pause) container image for pod infra containers. When running a pod, we start a `pause` process in a container to hold open the namespaces -associated with the pod. This container does nothing other then sleep, -reserving the pods resources for the lifetime of the pod. By default container -engines run a builtin container using the pause executable. If you want override +associated with the pod. This container does nothing other than sleep, +reserving the pod's resources for the lifetime of the pod. By default container +engines run a built-in container using the pause executable. If you want override specify an image to pull. +**kube_generate_type**="pod" + +Default Kubernetes kind/specification of the kubernetes yaml generated with the `podman kube generate` command. The possible options are `pod` and `deployment`. + **lock_type**="shm" Specify the locking mechanism to use; valid values are "shm" and "file". @@ -595,6 +629,7 @@ Pull image before running or creating a container. The default is **missing**. - **never**: do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally. **remote** = false + Indicates whether the application should be running in remote mode. This flag modifies the --remote option on container engines. Setting the flag to true will default `podman --remote=true` for access to the remote Podman service. @@ -745,7 +780,9 @@ Environment variables like $HOME as well as complete paths are supported for the source and destination. An optional third field `:ro` can be used to tell the container engines to mount the volume readonly. -On Mac, the default volumes are: `"/Users:/Users", "/private:/private", "/var/folders:/var/folders"` +On Mac, the default volumes are: + + [ "/Users:/Users", "/private:/private", "/var/folders:/var/folders" ] **provider**="" @@ -757,23 +794,31 @@ default is `QEMU` and on Windows it is `WSL`. **containers.conf** -Distributions often provide a `/usr/share/containers/containers.conf` file to -define default container configuration. Administrators can override fields in -this file by creating `/etc/containers/containers.conf` to specify their own -configuration. Rootless users can further override fields in the config by -creating a config file stored in the `$HOME/.config/containers/containers.conf` file. +Distributions often provide a __/usr/share/containers/containers.conf__ file to +provide a default configuration. Administrators can override fields in this +file by creating __/etc/containers/containers.conf__ to specify their own +configuration. They may also drop `.conf` files in +__/etc/containers/containers.conf.d__ which will be loaded in alphanumeric order. +Rootless users can further override fields in the config by creating a config +file stored in the __$HOME/.config/containers/containers.conf__ file or __.conf__ files in __$HOME/.config/containers/containers.conf.d__. -If the `CONTAINERS_CONF` path environment variable is set, just -this path will be used. This is primarily used for testing. +If the `CONTAINERS_CONF` environment variable is set, all system and user +config files are ignored and only the specified config file will be loaded. -Fields specified in the containers.conf file override the default options, as -well as options in previously read containers.conf files. +If the `CONTAINERS_CONF_OVERRIDE` path environment variable is set, the config +file will be loaded last even when `CONTAINERS_CONF` is set. + +The values of both environment variables may be absolute or relative paths, for +instance, `CONTAINERS_CONF=/tmp/my_containers.conf`. + +Fields specified in a containers.conf file override the default options, as +well as options in previously loaded containers.conf files. **storage.conf** The `/etc/containers/storage.conf` file is the default storage configuration file. Rootless users can override fields in the storage config by creating -`$HOME/.config/containers/storage.conf`. +__$HOME/.config/containers/storage.conf__. If the `CONTAINERS_STORAGE_CONF` path environment variable is set, this path is used for the storage.conf file rather than the default. diff --git a/shortnames.conf b/shortnames.conf index 2009c4c..3500b2d 100644 --- a/shortnames.conf +++ b/shortnames.conf @@ -2,6 +2,8 @@ # almalinux "almalinux" = "docker.io/library/almalinux" "almalinux-minimal" = "docker.io/library/almalinux-minimal" + # Amazon Linux + "amazonlinux" = "public.ecr.aws/amazonlinux/amazonlinux" # Arch Linux "archlinux" = "docker.io/library/archlinux" # centos diff --git a/storage.conf b/storage.conf index cc1e1db..b914c3f 100644 --- a/storage.conf +++ b/storage.conf @@ -34,6 +34,8 @@ graphroot = "/var/lib/containers/storage" # Transient store mode makes all container metadata be saved in temporary storage # (i.e. runroot above). This is faster, but doesn't persist across reboots. +# Additional garbage collection must also be performed at boot-time, so this +# option should remain disabled in most configurations. # transient_store = true [storage.options]