1podman-auto-update(1) General Commands Manual 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 Auto Updates and Kubernetes YAML
61 Podman supports auto updates for Kubernetes workloads. As mentioned
62 above, podman auto-update requires the containers to be running sys‐
63 temd. Podman ships with a systemd template that can be instantiated
64 with a Kubernetes YAML file, see podman-generate-systemd(1).
65 To enable auto updates for containers running in a Kubernetes workload,
68 set the following Podman-specific annotations in the YAML:
69 * io.containers.autoupdate: "registry|local" to apply the auto-update
70 policy to all containers
71 * io.containers.autoupdate/$container: "registry|local" to apply the
72 auto-update policy to $container only
73 * io.containers.sdnotify: "conmon|container" to apply the sdnotify
74 policy to all containers
75 * io.containers.sdnotify/$container: "conmon|container" to apply the
76 sdnotify policy to $container only
77 By default, the autoupdate policy is set to "disabled", the sdnotify
80 policy is set to "conmon".
81 Systemd Unit and Timer
84 Podman ships with a podman-auto-update.service systemd unit. This unit
85 is triggered daily at midnight by the podman-auto-update.timer systemd
86 timer. The timer can be altered for custom time-based updates if de‐
87 sired. The unit can further be invoked by other systemd units (e.g.,
88 via the dependency tree) or manually via systemctl start podman-auto-
89 update.service.
90
93 --authfile=path
94 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
95 ers/auth.json, which is set using podman login. If the authorization
96 state is not found there, $HOME/.docker/config.json is checked, which
97 is set using docker login.
98 Note: There is also the option to override the default path of the au‐
101 thentication file by setting the REGISTRY_AUTH_FILE environment vari‐
102 able. This can be done with export REGISTRY_AUTH_FILE=path.
103 --dry-run
106 Check for the availability of new images but do not perform any pull
107 operation or restart any service or container. The UPDATED field indi‐
108 cates the availability of a new image with "pending".
109 --format=format
112 Change the default output format. This can be of a supported type like
113 'json' or a Go template. Valid placeholders for the Go template are
114 listed below:
115 ┌───────────────┬──────────────────────────────┐
118 │Placeholder │ Description │
119 ├───────────────┼──────────────────────────────┤
120 │.Unit │ Name of the systemd unit │
121 ├───────────────┼──────────────────────────────┤
122 │.ContainerName │ Name of the container │
123 ├───────────────┼──────────────────────────────┤
124 │.ContainerID │ ID of the container │
125 ├───────────────┼──────────────────────────────┤
126 │.Container │ ID and name of the container │
127 ├───────────────┼──────────────────────────────┤
128 │.Image │ Name of the image │
129 ├───────────────┼──────────────────────────────┤
130 │.Policy │ Auto-update policy of the │
131 │ │ container │
132 ├───────────────┼──────────────────────────────┤
133 │.Updated │ Update status: │
134 │ │ true,false,failed │
135 └───────────────┴──────────────────────────────┘
136 --rollback
138 If restarting a systemd unit after updating the image has failed, roll‐
139 back to using the previous image and restart the unit another time.
140 Default is true.
141 Please note that detecting if a systemd unit has failed is best done by
144 the container sending the READY message via SDNOTIFY. This way,
145 restarting the unit will wait until having received the message or a
146 timeout kicked in. Without that, restarting the systemd unit may suc‐
147 ceed even if the container has failed shortly after.
148 For a container to send the READY message via SDNOTIFY it must be cre‐
151 ated with the --sdnotify=container option (see podman-run(1)). The ap‐
152 plication running inside the container can then execute systemd-notify
153 --ready when ready or use the sdnotify bindings of the specific pro‐
154 gramming language (e.g., sd_notify(3)).
155
158 Autoupdate with registry policy
159 ### Start a container
162 $ podman run --label "io.containers.autoupdate=registry"
163 --label "io.containers.autoupdate.authfile=/some/authfile.json"
164 -d --name=test registry.fedoraproject.org/fedora:latest sleep infinity
165 bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d
166 ### Generate a systemd unit for this container
168 $ podman generate systemd --new --files bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d
169 /home/user/container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service
170 ### Load the new systemd unit and start it
172 $ mv ./container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service ~/.config/systemd/user/container-test.service
173 $ systemctl --user daemon-reload
174 ### 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.
176 $ podman stop bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d
177 $ podman rm bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d
178 $ systemctl --user start container-test.service
180 ### Check if a newer image is available
182 $ podman auto-update --dry-run --format "{{.Image}} {{.Updated}}"
183 registry.fedoraproject.org/fedora:latest pending
184 ### Autoupdate the services
186 $ podman auto-update
187 UNIT CONTAINER IMAGE POLICY UPDATED
188 container-test.service 08fd34e533fd (test) registry.fedoraproject.org/fedora:latest registry false
189 Autoupdate with local policy
193 ### Start a container
196 $ podman run --label "io.containers.autoupdate=local"
197 -d busybox:latest top
198 be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
199 ### Generate a systemd unit for this container
201 $ podman generate systemd --new --files be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
202 /home/user/container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service
203 ### Load the new systemd unit and start it
205 $ mv ./container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service ~/.config/systemd/user
206 $ systemctl --user daemon-reload
207 ### 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.
209 $ podman stop be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
210 $ podman rm be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
211 $ systemctl --user start container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service
213 ### Get the name of the container
215 $ podman ps
216 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
217 01f5c8113e84 docker.io/library/busybox:latest top 2 seconds ago Up 3 seconds ago inspiring_galileo
218 ### Modify the image
220 $ podman commit --change CMD=/bin/bash inspiring_galileo busybox:latest
221 ### Auto-update the container
223 $ podman auto-update
224 [...]
225
229 podman(1), podman-generate-systemd(1), podman-run(1), sd_notify(3),
230 systemd.unit(5)
231 podman-auto-update(1)