1podman-auto-update(1)() podman-auto-update(1)()
2
6 podman-auto-update - Auto update containers according to their auto-up‐
7 date policy
8
11 podman auto-update [options]
12
15 podman auto-update looks up containers with a specified io.contain‐
16 ers.autoupdate label (i.e., the auto-update policy).
17 If the label is present and set to registry, Podman reaches out to the
20 corresponding registry to check if the image has been updated. The la‐
21 bel image is an alternative to registry maintained for backwards com‐
22 patibility. An image is considered updated if the digest in the local
23 storage is different than the one of the remote image. If an image
24 must be updated, Podman pulls it down and restarts the systemd unit ex‐
25 ecuting the container.
26 The registry policy requires a fully-qualified image reference (e.g.,
29 quay.io/podman/stable:latest) to be used to create the container. This
30 enforcement is necessary to know which image to actually check and
31 pull. If an image ID was used, Podman would not know which image to
32 check/pull anymore.
33 Alternatively, if the autoupdate label is set to local, Podman will
36 compare the image a container is using to the image with its raw name
37 in local storage. If an image is updated locally, Podman simply
38 restarts the systemd unit executing the container.
39 If io.containers.autoupdate.authfile label is present, Podman reaches
42 out to the corresponding authfile when pulling images.
43 At container-creation time, Podman looks up the PODMAN_SYSTEMD_UNIT en‐
46 vironment variable and stores it verbatim in the container's label.
47 This variable is now set by all systemd units generated by podman-gen‐
48 erate-systemd and is set to %n (i.e., the name of systemd unit starting
49 the container). This data is then being used in the auto-update se‐
50 quence to instruct systemd (via DBUS) to restart the unit and hence to
51 restart the container.
52 Note that podman auto-update relies on systemd. The systemd units are
55 expected to be generated with podman-generate-systemd --new, or similar
56 units that create new containers in order to run the updated images.
57 Systemd units that start and stop a container cannot run a new image.
58 Systemd Unit and Timer
61 Podman ships with a podman-auto-update.service systemd unit. This unit
62 is triggered daily at midnight by the podman-auto-update.timer systemd
63 timer. The timer can be altered for custom time-based updates if de‐
64 sired. The unit can further be invoked by other systemd units (e.g.,
65 via the dependency tree) or manually via systemctl start podman-auto-
66 update.service.
67
70 --authfile=path
71 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
72 ers/auth.json, which is set using podman login. If the authorization
73 state is not found there, $HOME/.docker/config.json is checked, which
74 is set using docker login.
75 Note: There is also the option to override the default path of the au‐
78 thentication file by setting the REGISTRY_AUTH_FILE environment vari‐
79 able. This can be done with export REGISTRY_AUTH_FILE=path.
80 --dry-run
83 Check for the availability of new images but do not perform any pull
84 operation or restart any service or container. The UPDATED field indi‐
85 cates the availability of a new image with "pending".
86 --format=format
89 Change the default output format. This can be of a supported type like
90 'json' or a Go template. Valid placeholders for the Go template are
91 listed below:
92 ┌───────────────┬──────────────────────────────┐
95 │Placeholder │ Description │
96 ├───────────────┼──────────────────────────────┤
97 │.Unit │ Name of the systemd unit │
98 ├───────────────┼──────────────────────────────┤
99 │.ContainerName │ Name of the container │
100 ├───────────────┼──────────────────────────────┤
101 │.ContainerID │ ID of the container │
102 ├───────────────┼──────────────────────────────┤
103 │.Container │ ID and name of the container │
104 ├───────────────┼──────────────────────────────┤
105 │.Image │ Name of the image │
106 ├───────────────┼──────────────────────────────┤
107 │.Policy │ Auto-update policy of the │
108 │ │ container │
109 ├───────────────┼──────────────────────────────┤
110 │.Updated │ Update status: │
111 │ │ true,false,failed │
112 └───────────────┴──────────────────────────────┘
113 --rollback
115 If restarting a systemd unit after updating the image has failed, roll‐
116 back to using the previous image and restart the unit another time.
117 Default is true.
118 Please note that detecting if a systemd unit has failed is best done by
121 the container sending the READY message via SDNOTIFY. This way,
122 restarting the unit will wait until having received the message or a
123 timeout kicked in. Without that, restarting the systemd unit may suc‐
124 ceed even if the container has failed shortly after.
125 For a container to send the READY message via SDNOTIFY it must be cre‐
128 ated with the --sdnotify=container option (see podman-run(1)). The ap‐
129 plication running inside the container can then execute systemd-notify
130 --ready when ready or use the sdnotify bindings of the specific pro‐
131 gramming language (e.g., sd_notify(3)).
132
135 Autoupdate with registry policy
136 ### Start a container
139 $ podman run --label "io.containers.autoupdate=registry"
140 --label "io.containers.autoupdate.authfile=/some/authfile.json"
141 -d --name=test registry.fedoraproject.org/fedora:latest sleep infinity
142 bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d
143 ### Generate a systemd unit for this container
145 $ podman generate systemd --new --files bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d
146 /home/user/container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service
147 ### Load the new systemd unit and start it
149 $ mv ./container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service ~/.config/systemd/user/container-test.service
150 $ systemctl --user daemon-reload
151 ### If the previously created containers or pods are using shared resources, such as ports, make sure to remove them before starting the generated systemd units.
153 $ podman stop bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d
154 $ podman rm bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d
155 $ systemctl --user start container-test.service
157 ### Check if a newer image is available
159 $ podman auto-update --dry-run --format "{{.Image}} {{.Updated}}"
160 registry.fedoraproject.org/fedora:latest pending
161 ### Autoupdate the services
163 $ podman auto-update
164 UNIT CONTAINER IMAGE POLICY UPDATED
165 container-test.service 08fd34e533fd (test) registry.fedoraproject.org/fedora:latest registry false
166 Autoupdate with local policy
170 ### Start a container
173 $ podman run --label "io.containers.autoupdate=local"
174 -d busybox:latest top
175 be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
176 ### Generate a systemd unit for this container
178 $ podman generate systemd --new --files be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
179 /home/user/container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service
180 ### Load the new systemd unit and start it
182 $ mv ./container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service ~/.config/systemd/user
183 $ systemctl --user daemon-reload
184 ### If the previously created containers or pods are using shared resources, such as ports, make sure to remove them before starting the generated systemd units.
186 $ podman stop be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
187 $ podman rm be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
188 $ systemctl --user start container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service
190 ### Get the name of the container
192 $ podman ps
193 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
194 01f5c8113e84 docker.io/library/busybox:latest top 2 seconds ago Up 3 seconds ago inspiring_galileo
195 ### Modify the image
197 $ podman commit --change CMD=/bin/bash inspiring_galileo busybox:latest
198 ### Auto-update the container
200 $ podman auto-update
201 [...]
202
206 podman(1), podman-generate-systemd(1), podman-run(1), sd_notify(3),
207 systemd.unit(5)
208 podman-auto-update(1)()