podman-container-clone(1)

📦
version 6.1.4 · 5 versions
, in arch rolling, centos-stream 10, nixpkgs unstable

💖 podman-container-clone(1) 💖

okay so you're in the General Commands Manual section and the vibe is immaculate — welcome to podman-container-clone, bestie 🫶

✨ NAME ✨

podman-container-clone — make a copy of a container that already exists. literally a clone moment 👯‍♀️💅

🌸 SYNOPSIS 🌸

podman container clone [options] container name image

🦋 DESCRIPTION 🦋

so podman container clone creates a copy of a container — it recreates the original with an identical configuration. like, the whole fit is the same, no cap 🔥

this command takes three arguments, and yes you need all of them, bestie:

  1. the first one is the container ID or name you wanna clone — the main character in question 👑
  2. the second argument can change the name of the clone from its default of $ORIGINAL_NAME-clone — so if you don't say anything, it just gets -clone slapped on the end, iconic behavior honestly 🎀
  3. the third is a new image to use in the cloned container — new image, same energy ✨
🧚 no seriously, three args. don't come crying to me when you forget the image. iykyk 😭

✨ OPTIONS ✨

Ok bestie, this is the big one — every flag you can throw at podman container clone, and what it actually does. Buckle up 🎀

  • --blkio-weight=_weight_ — block IO relative weight, and the weight has to be a value between 10 and 1000.
Heads up: this one is not supported on cgroups V1 rootless systems. 💀
  • --blkio-weight-device=_device:weight_ — same energy, but the block IO relative weight for one specific device.
  • --cpu-period=_limit_ — sets the CPU period for the Completely Fair Scheduler (CFS), which is a duration in microseconds. Once the container's CPU quota is all used up, it will not be scheduled to run again until the current period ends. Defaults to 100000 microseconds.

On some systems, changing the resource limits may not be allowed for non-root users. For more details, peep https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

Not supported on cgroups V1 rootless systems. 🫠

If none is specified, the original container's cpu period is used.

  • --cpu-quota=_limit_ — caps the CPU Completely Fair Scheduler (CFS) quota.

Limits the container's CPU usage. By default, containers run with the full CPU resource. The limit is a number in microseconds. If a number is provided, the container is allowed to use that much CPU time until the CPU period ends (controllable via --cpu-period).

On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

Not supported on cgroups V1 rootless systems.

If none is specified, the original container's CPU quota are used.

  • --cpu-rt-period=_microseconds_ — limits the CPU real-time period in microseconds.

This limits the container's Real Time CPU usage — it tells the kernel to restrict the container's Real Time CPU usage to the period specified. ✨

This option is only supported on cgroups V1 rootful systems.

If none is specified, the original container's CPU runtime period is used.

  • --cpu-rt-runtime=_microseconds_ — limits the CPU real-time runtime in microseconds.

Limits the container's Real Time CPU usage. This option tells the kernel to limit the amount of time in a given CPU period that Real Time tasks may consume. Ex: Period of 1,000,000us and Runtime of 950,000us means that this container can consume 95% of available CPU and leave the remaining 5% to normal priority tasks. 🧮

The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. No cap, that's just the rules.

This option is only supported on cgroups V1 rootful systems.

  • --cpu-shares, -c=_shares_ — CPU shares (relative weight).

By default, all containers get the same proportion of CPU cycles. This proportion can be modified by changing the container's CPU share weighting relative to the combined weight of all the running containers. Default weight is 1024.

The proportion only applies when CPU-intensive processes are running. When tasks in one container are idle, other containers can use the leftover CPU time. The actual amount of CPU time varies depending on the number of containers running on the system.

For example, consider three containers, one has a cpu-share of 1024 and two others have a cpu-share setting of 512. When processes in all three containers attempt to use 100% of CPU, the first container receives 50% of the total CPU time. If a fourth container is added with a cpu-share of 1024, the first container only gets 33% of the CPU. The remaining containers receive 16.5%, 16.5% and 33% of the CPU.

On a multi-core system, the shares of CPU time are distributed over all CPU cores. Even if a container is limited to less than 100% of CPU time, it can use 100% of each individual CPU core.

For example, consider a system with more than three cores. If the container C0 is started with --cpu-shares=512 running one process, and another container C1 with --cpu-shares=1024 running two processes, this can result in the following division of CPU shares:

┌─────┬───────────┬─────┬──────────────┐
│ PID │ container │ CPU │ CPU share    │
├─────┼───────────┼─────┼──────────────┤
│ 100 │ C0        │ 0   │ 100% of CPU0 │
├─────┼───────────┼─────┼──────────────┤
│ 101 │ C1        │ 1   │ 100% of CPU1 │
├─────┼───────────┼─────┼──────────────┤
│ 102 │ C1        │ 2   │ 100% of CPU2 │
└─────┴───────────┴─────┴──────────────┘

On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

Not supported on cgroups V1 rootless systems. 😭

If none are specified, the original container's CPU shares are used.

  • --cpus — sets a number of CPUs for the container that overrides the original container's CPU limits. If none are specified, the original container's Nano CPUs are used.

This is shorthand for --cpu-period and --cpu-quota, so only --cpus or both the --cpu-period and --cpu-quota options can be set — pick a lane, bestie. 🚦

Not supported on cgroups V1 rootless systems.

  • --cpuset-cpus=_number_ — the CPUs in which to allow execution. Can be specified as a comma-separated list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof (e.g. 0-3,7,11-15). Iconic and flexible. 💅

On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

Not supported on cgroups V1 rootless systems.

If none are specified, the original container's CPUset is used.

  • --cpuset-mems=_nodes_ — the memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems, iykyk.

If there are four memory nodes on the system (0-3), use --cpuset-mems=0,1 then processes in the container only use memory from the first two memory nodes. 🧠

On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

Not supported on cgroups V1 rootless systems.

If none are specified, the original container's CPU memory nodes are used.

  • --destroy — removes the original container that we are cloning, once it's been used to mimic the configuration. Like, it served its purpose, bye 👋
  • --device-read-bps=_path:rate_ — limits the read rate (in bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb).

On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

Not supported on cgroups V1 rootless systems.

  • --device-write-bps=_path:rate_ — limits the write rate (in bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb).

On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

Not supported on cgroups V1 rootless systems.

  • --force, -f — forces removal of the original container that we're cloning. Can only be used in conjunction with --destroy. No solo runs, bestie. 🔥
  • --memory, -m=_number[unit]_ — memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).

Lets the memory available to a container be constrained. If the host supports swap memory, then the --memory setting can be larger than physical RAM. If a limit of 0 is specified (not using --memory), the container's memory is not limited. The actual limit may be rounded up to a multiple of the operating system's page size (the value is very large, that's millions of trillions 👀).

Not supported on cgroups V1 rootless systems.

If no memory limits are specified, the original container's memory limits are used.

  • --memory-reservation=_number[unit]_ — memory soft limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).

After setting memory reservation, when the system detects memory contention or low memory, containers are forced to restrict their consumption to their reservation. So always set the value below --memory, otherwise the hard limit takes precedence. By default, memory reservation is the same as memory limit.

Not supported on cgroups V1 rootless systems.

If unspecified, memory reservation is the same as memory limit from the container being cloned.

  • --memory-swap=_number[unit]_ — a limit value equal to memory plus swap. A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).

Must be used with the -m (--memory) flag — they're a package deal 🫶 The argument value must be larger than that of -m (--memory). By default, it is set to double the value of --memory.

Set number to -1 to enable unlimited swap.

Not supported on cgroups V1 rootless systems.

If unspecified, the container being cloned is used to derive the swap value.

  • --memory-swappiness=_number_ — tunes a container's memory swappiness behavior. Accepts an integer between 0 and 100.

This flag is only supported on cgroups V1 rootful systems.

  • --name — sets a custom name for the cloned container. The default if not specified is of the syntax: <ORIGINAL_NAME>-clone ✨ (yes, the angle brackets are part of the syntax, she's fancy like that)
  • --pod=_name_ — clone the container in an existing pod. It's helpful to move a container to an existing pod. The container joins the pod shared namespaces, losing its configuration that conflicts with the shared namespaces. ⚠️ Like, it will drop what doesn't fit, so know that going in.
  • --run — when set to true, this flag runs the newly created container after the clone process has completed. This specifies a detached running mode. 🏃‍♀️💨

💖 EXAMPLES 💖

okay bestie, this is the part where it gets real — here come the actual glow-up demos ✨

  • Clone a specified container into a new container — just point it at the container ID and let it do its thing:
# podman container clone d0cf1f782e2ed67e8c0050ff92df865a039186237a4df24d7acba5b1fa8cc6e7
6b2c73ff8a1982828c9ae2092954bcd59836a131960f7e05221af9df5939c584
  • Clone a specified container into a newly named container — same energy, but you're picking the name yourself with --name=clone:
# podman container clone --name=clone d0cf1f782e2ed67e8c0050ff92df865a039186237a4df24d7acba5b1fa8cc6e7
6b2c73ff8a1982828c9ae2092954bcd59836a131960f7e05221af9df5939c584
  • Replace a specified container with selected resource constraints into a new container, removing the original container — yes, --destroy is doing the dramatic exit, and --cpus=5 is setting the resource vibe:
# podman container clone --destroy --cpus=5 d0cf1f782e2ed67e8c0050ff92df865a039186237a4df24d7acba5b1fa8cc6e7
6b2c73ff8a1982828c9ae2092954bcd59836a131960f7e05221af9df5939c584
  • Clone a specified container, give it a new name, and then replace the image of the original container with the specified image name — this one's giving full main-character makeover, and the output is literally all right here:
# podman container clone 2d4d4fca7219b4437e0d74fcdc272c4f031426a6eacd207372691207079551de new_name fedora
Resolved "fedora" as an alias (/etc/containers/registries.conf.d/shortnames.conf)
Trying to pull registry.fedoraproject.org/fedora:latest...
Getting image source signatures
Copying blob c6183d119aa8 done
Copying config e417cd49a8 done
Writing manifest to image destination
Storing signatures
5a9b7851013d326aa4ac4565726765901b3ecc01fcbc0f237bc7fd95588a24f9

👀 SEE ALSO 👀

bestie, go peek at these too, they're part of the lore 🫶

🧚 HISTORY 🧚

  • January 2022 — Originally written by Charlie Doern cdoern@redhat.com ⟨mailto:cdoern@redhat.com⟩ 💌

and that's the whole page, no cap 💅 signed, sealed, delivered: podman-container-clone(1), January 2022 edition — mwah 🎀✨

📦 where this page comes from