implement podman update

podman update allows users to change the cgroup configuration of an existing container using the already defined resource limits flags
from podman create/run. The supported flags in crun are:

this command is also now supported in the libpod api via the /libpod/containers/<CID>/update endpoint where
the resource limits are passed inthe request body and follow the OCI resource spec format

–memory
–cpus
–cpuset-cpus
–cpuset-mems
–memory-swap
–memory-reservation
–cpu-shares
–cpu-quota
–cpu-period
–blkio-weight
–cpu-rt-period
–cpu-rt-runtime
-device-read-bps
-device-write-bps
-device-read-iops
-device-write-iops
-memory-swappiness
-blkio-weight-device

resolves #15067

Signed-off-by: Charlie Doern <cdoern@redhat.com>

17 files changed, 157 insertions, 137 deletions

diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore
index 26509612d..74e7fc075 100644
--- a/docs/source/markdown/.gitignore
+++ b/docs/source/markdown/.gitignore
@@ -27,3 +27,4 @@ podman-run.1.md
 podman-search.1.md
 podman-stop.1.md
 podman-unpause.1.md
+podman-update.1.md
diff --git a/docs/source/markdown/links/podman-container-update.1 b/docs/source/markdown/links/podman-container-update.1
new file mode 100644
index 000000000..e903b5c06
--- /dev/null
+++ b/docs/source/markdown/links/podman-container-update.1
@@ -0,0 +1 @@
+.so man1/podman-update.1
diff --git a/docs/source/markdown/options/device-read-bps.md b/docs/source/markdown/options/device-read-bps.md
new file mode 100644
index 000000000..e0c610061
--- /dev/null
+++ b/docs/source/markdown/options/device-read-bps.md
@@ -0,0 +1,5 @@
+#### **--device-read-bps**=*path:rate*
+
+Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**).
+
+This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/options/device-read-iops.md b/docs/source/markdown/options/device-read-iops.md
new file mode 100644
index 000000000..9cd0f9030
--- /dev/null
+++ b/docs/source/markdown/options/device-read-iops.md
@@ -0,0 +1,5 @@
+#### **--device-read-iops**=*path:rate*
+
+Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**).
+
+This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/options/device-write-bps.md b/docs/source/markdown/options/device-write-bps.md
new file mode 100644
index 000000000..3dacc4515
--- /dev/null
+++ b/docs/source/markdown/options/device-write-bps.md
@@ -0,0 +1,5 @@
+#### **--device-write-bps**=*path:rate*
+
+Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/dev/sda:1mb**).
+
+This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/options/device-write-iops.md b/docs/source/markdown/options/device-write-iops.md
new file mode 100644
index 000000000..cf5ce3859
--- /dev/null
+++ b/docs/source/markdown/options/device-write-iops.md
@@ -0,0 +1,5 @@
+#### **--device-write-iops**=*path:rate*
+
+Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**).
+
+This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/options/memory-reservation.md b/docs/source/markdown/options/memory-reservation.md
new file mode 100644
index 000000000..410f1dd7c
--- /dev/null
+++ b/docs/source/markdown/options/memory-reservation.md
@@ -0,0 +1,11 @@
+#### **--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 you should always set the value below **--memory**, otherwise the
+hard limit will take precedence. By default, memory reservation will be the same
+as memory limit.
+
+This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/options/memory-swap.md b/docs/source/markdown/options/memory-swap.md
new file mode 100644
index 000000000..08ee8b1a0
--- /dev/null
+++ b/docs/source/markdown/options/memory-swap.md
@@ -0,0 +1,13 @@
+#### **--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.
+The argument value should always 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.
+
+This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/options/memory.md b/docs/source/markdown/options/memory.md
new file mode 100644
index 000000000..1be9159c3
--- /dev/null
+++ b/docs/source/markdown/options/memory.md
@@ -0,0 +1,11 @@
+#### **--memory**, **-m**=*number[unit]*
+
+Memory limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes).
+
+Allows the memory available to a container to be constrained. If the host
+supports swap memory, then the **-m** memory setting can be larger than physical
+RAM. If a limit of 0 is specified (not using **-m**), 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 would be very large, that's millions of trillions).
+
+This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/podman-container-clone.1.md.in b/docs/source/markdown/podman-container-clone.1.md.in
index 26f414b62..3e31389d2 100644
--- a/docs/source/markdown/podman-container-clone.1.md.in
+++ b/docs/source/markdown/podman-container-clone.1.md.in
@@ -52,36 +52,18 @@ If none are specified, the original container's CPU memory nodes are used.
 
 @@option destroy
 
-#### **--device-read-bps**=*path*
+@@option device-read-bps
 
-Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb).
-
-This option is not supported on cgroups V1 rootless systems.
-
-#### **--device-write-bps**=*path*
-
-Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb)
-
-This option is not supported on cgroups V1 rootless systems.
+@@option device-write-bps
 
 #### **--force**, **-f**
 
 Force removal of the original container that we are cloning. Can only be used in conjunction with **--destroy**.
 
-#### **--memory**, **-m**=*limit*
-
-Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes))
-
-Allows the memory available to a container to be constrained. If the host
-supports swap memory, then the **-m** memory setting can be larger than physical
-RAM. If a limit of 0 is specified (not using **-m**), 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 would be very large, that's millions of trillions).
+@@option memory
 
 If no memory limits are specified, the original container's will be used.
 
-This option is not supported on cgroups V1 rootless systems.
-
 #### **--memory-reservation**=*limit*
 
 Memory soft limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes))
@@ -92,8 +74,6 @@ reservation. So you should always set the value below **--memory**, otherwise th
 hard limit will take precedence. By default, memory reservation will be the same
 as memory limit from the container being cloned.
 
-This option is not supported on cgroups V1 rootless systems.
-
 #### **--memory-swap**=*limit*
 
 A limit value equal to memory plus swap. Must be used with the  **-m**
diff --git a/docs/source/markdown/podman-container.1.md b/docs/source/markdown/podman-container.1.md
index a66e2789d..593cd3c42 100644
--- a/docs/source/markdown/podman-container.1.md
+++ b/docs/source/markdown/podman-container.1.md
@@ -46,6 +46,7 @@ The container command allows you to manage containers
 | top        | [podman-top(1)](podman-top.1.md)                    | Display the running processes of a container.                                |
 | unmount    | [podman-unmount(1)](podman-unmount.1.md)            | Unmount a working container's root filesystem.(Alias unmount)                |
 | unpause    | [podman-unpause(1)](podman-unpause.1.md)            | Unpause one or more containers.                                              |
+| update     | [podman-update(1)](podman-update.1.md)              | Updates the cgroup configuration of a given container.                      |
 | wait       | [podman-wait(1)](podman-wait.1.md)                  | Wait on one or more containers to stop and print their exit codes.           |
 
 ## SEE ALSO
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index 2fad2deb1..10f0f7f56 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/docs/source/markdown/podman-create.1.md.in
@@ -87,9 +87,7 @@ each of stdin, stdout, and stderr.
 
 @@option blkio-weight
 
-#### **--blkio-weight-device**=*device:weight*
-
-Block IO relative device weight.
+@@option blkio-weight-device
 
 @@option cap-add
 
@@ -148,27 +146,11 @@ device. The devices that podman will load modules when necessary are:
 
 #### **--device-read-bps**=*path*
 
-Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb)
-
-This option is not supported on cgroups V1 rootless systems.
-
-#### **--device-read-iops**=*path*
-
-Limit read rate (IO per second) from a device (e.g. --device-read-iops=/dev/sda:1000)
-
-This option is not supported on cgroups V1 rootless systems.
-
-#### **--device-write-bps**=*path*
-
-Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb)
-
-This option is not supported on cgroups V1 rootless systems.
-
-#### **--device-write-iops**=*path*
+@@option device-read-iops
 
-Limit write rate (IO per second) to a device (e.g. --device-write-iops=/dev/sda:1000)
+@@option device-write-bps
 
-This option is not supported on cgroups V1 rootless systems.
+@@option device-write-iops
 
 @@option disable-content-trust
 
@@ -307,42 +289,11 @@ This option is currently supported only by the **journald** log driver.
 
 @@option mac-address
 
-#### **--memory**, **-m**=*limit*
-
-Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes))
-
-Allows you to constrain the memory available to a container. If the host
-supports swap memory, then the **-m** memory setting can be larger than physical
-RAM. If a limit of 0 is specified (not using **-m**), 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 would be very large, that's millions of trillions).
-
-This option is not supported on cgroups V1 rootless systems.
-
-#### **--memory-reservation**=*limit*
-
-Memory soft limit (format: `<number>[<unit>]`, where unit = 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 you should always set the value below **--memory**, otherwise the
-hard limit will take precedence. By default, memory reservation will be the same
-as memory limit.
-
-This option is not supported on cgroups V1 rootless systems.
-
-#### **--memory-swap**=*limit*
-
-A limit value equal to memory plus swap. Must be used with the  **-m**
-(**--memory**) flag. The swap `LIMIT` should always be larger than **-m**
-(**--memory**) value. By default, the swap `LIMIT` will be set to double
-the value of --memory.
+@@option memory
 
-The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes),
-`k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a
-unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
+@@option memory-reservation
 
-This option is not supported on cgroups V1 rootless systems.
+@@option memory-swap
 
 @@option memory-swappiness
 
diff --git a/docs/source/markdown/podman-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in
index 999297f5e..24edc44ec 100644
--- a/docs/source/markdown/podman-pod-clone.1.md.in
+++ b/docs/source/markdown/podman-pod-clone.1.md.in
@@ -48,13 +48,9 @@ Podman may load kernel modules required for using the specified
 device. The devices that Podman will load modules for when necessary are:
 /dev/fuse.
 
-#### **--device-read-bps**=*path*
+@@option device-read-bps
 
-Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb).
-
-#### **--device-write-bps**=*path*
-
-Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb)
+@@option device-write-bps
 
 @@option gidmap.pod
 
diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in
index 2f8bcc31c..35d06fa00 100644
--- a/docs/source/markdown/podman-pod-create.1.md.in
+++ b/docs/source/markdown/podman-pod-create.1.md.in
@@ -65,13 +65,9 @@ Podman may load kernel modules required for using the specified
 device. The devices that Podman will load modules for when necessary are:
 /dev/fuse.
 
-#### **--device-read-bps**=*path*
+@@option device-read-bps
 
-Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb)
-
-#### **--device-write-bps**=*path*
-
-Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb)
+@@option device-write-bps
 
 #### **--dns**=*ipaddr*
 
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index c4df88e3b..b63c37e6f 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -180,29 +180,13 @@ device. The devices that Podman will load modules when necessary are:
 
 @@option device-cgroup-rule
 
-#### **--device-read-bps**=*path:rate*
+@@option device-read-bps
 
-Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**).
+@@option device-read-iops
 
-This option is not supported on cgroups V1 rootless systems.
+@@option device-write-bps
 
-#### **--device-read-iops**=*path:rate*
-
-Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**).
-
-This option is not supported on cgroups V1 rootless systems.
-
-#### **--device-write-bps**=*path:rate*
-
-Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/dev/sda:1mb**).
-
-This option is not supported on cgroups V1 rootless systems.
-
-#### **--device-write-iops**=*path:rate*
-
-Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**).
-
-This option is not supported on cgroups V1 rootless systems.
+@@option device-write-iops
 
 @@option disable-content-trust
 
@@ -335,33 +319,9 @@ RAM. If a limit of 0 is specified (not using **-m**), 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 would be very large, that's millions of trillions).
 
-This option is not supported on cgroups V1 rootless systems.
-
-#### **--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 you should always set the value below **--memory**, otherwise the
-hard limit will take precedence. By default, memory reservation will be the same
-as memory limit.
-
-This option is not supported on cgroups V1 rootless systems.
-
-#### **--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.
-The argument value should always 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.
+@@option memory-reservation
 
-This option is not supported on cgroups V1 rootless systems.
+@@option memory-swap
 
 @@option memory-swappiness
 
diff --git a/docs/source/markdown/podman-update.1.md.in b/docs/source/markdown/podman-update.1.md.in
new file mode 100644
index 000000000..2928379f3
--- /dev/null
+++ b/docs/source/markdown/podman-update.1.md.in
@@ -0,0 +1,78 @@
+% podman-update(1)
+
+## NAME
+podman\-update - Updates the cgroup configuration of a given container
+
+## SYNOPSIS
+**podman update** [*options*] *container*
+
+**podman container update** [*options*] *container*
+
+## DESCRIPTION
+
+Updates the cgroup configuration of an already existing container. The currently supported options are a subset of the
+podman create/run resource limits options. These new options are non-persistent and only last for the current execution of the container; the configuration will be honored on its next run.
+This means that this command can only be executed on an already running container and the changes made will be erased the next time the container is stopped and restarted, this is to ensure immutability.
+This command takes one argument, a container name or ID, alongside the resource flags to modify the cgroup.
+
+## OPTIONS
+
+@@option blkio-weight
+
+@@option blkio-weight-device
+
+@@option cpu-period
+
+@@option cpu-quota
+
+@@option cpu-rt-period
+
+@@option cpu-rt-runtime
+
+@@option cpu-shares
+
+@@option cpus.container
+
+@@option cpuset-cpus
+
+@@option cpuset-mems
+
+@@option device-read-bps
+
+@@option device-read-iops
+
+@@option device-write-bps
+
+@@option device-write-iops
+
+@@option memory
+
+@@option memory-reservation
+
+@@option memory-swap
+
+@@option memory-swappiness
+
+
+## EXAMPLEs
+
+update a container with a new cpu quota and period
+```
+podman update --cpus=5 myCtr
+```
+
+update a container with all available options for cgroups v2
+```
+podman update --cpus 5 --cpuset-cpus 0 --cpu-shares 123 --cpuset-mems 0 --memory 1G --memory-swap 2G --memory-reservation 2G --blkio-weight-device /dev/zero:123 --blkio-weight 123 --device-read-bps /dev/zero:10mb --device-write-bps /dev/zero:10mb --device-read-iops /dev/zero:1000 --device-write-iops /dev/zero:1000 ctrID
+```
+
+update a container with all available options for cgroups v1
+```
+podman update --cpus 5 --cpuset-cpus 0 --cpu-shares 123 --cpuset-mems 0 --memory 1G --memory-swap 2G --memory-reservation 2G --memory-swappiness 50 ctrID
+```
+
+## SEE ALSO
+**[podman(1)](podman.1.md)**, **[podman-create(1)](podman-create.1.md)**, **[podman-run(1)](podman-run.1.md)**
+
+## HISTORY
+August 2022, Originally written by Charlie Doern <cdoern@redhat.com>
diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md
index d1192b6d2..8c3af2561 100644
--- a/docs/source/markdown/podman.1.md
+++ b/docs/source/markdown/podman.1.md
@@ -355,6 +355,7 @@ the exit codes follow the `chroot` standard, see below:
 | [podman-unpause(1)](podman-unpause.1.md)         | Unpause one or more containers.                                             |
 | [podman-unshare(1)](podman-unshare.1.md)         | Run a command inside of a modified user namespace.                          |
 | [podman-untag(1)](podman-untag.1.md)             | Removes one or more names from a locally-stored image.                      |
+| [podman-update(1)](podman-update.1.md)           | Updates the cgroup configuration of a given container.                      |
 | [podman-version(1)](podman-version.1.md)         | Display the Podman version information.                                     |
 | [podman-volume(1)](podman-volume.1.md)           | Simple management tool for volumes.                                         |
 | [podman-wait(1)](podman-wait.1.md)               | Wait on one or more containers to stop and print their exit codes.          |