Add a documentation entry about hooks for podman-run

[jerabaul29]

Add a documentation entry about hooks for podman-run, by documenting the hooks-dir argument.

Fixes: #27281

[openshift-ci]

Adding the "do-not-merge/release-note-label-needed" label because no release-note block was detected, please follow our release note process to remove it.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: jerabaul29
Once this PR has been reviewed and has the lgtm label, please assign ygalblum for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[jerabaul29]

I don't understand why it says that "Signed-off-by" is missing, this is how the commit message looks to me in the github UI:

A few notes:

• there is already a hooks-dir argument entry for the podman-build command: https://docs.podman.io/en/stable/markdown/podman-build.1.html#hooks-dir-path . However, I think that this is a bit different from the hooks-dir for the podman-run command, so I created a new doc entry for the hooks-dir argument of podman run

• I was a bit unsure of how / how much I should fill it; after a bit of googling around, I think the best is to link to the doc of the OCI spec, which is how I did it. I think this is a bit hard to read / obscure for people who don't know in advance how this is used, but I don't think it would make sense to link to some blog posts etc? In particular, this documents well the stages (for example createContainer that I struggled finding), but this does not document e.g. annotation as a way to use with the when json parameter such as in

{
    "version": "1.0.0",
    "hook": {
        "path": "/home/jeanr/Desktop/Git/2025_podman_iptable_rules/set_iptable_rules_denyall_allowsome.sh"
    },
    "when": {
        "annotations": {
            "^apply_iptables_denyall_allowsome_hook$": ".+"
        }
    },
    "stages": ["createContainer"]
}

• All in all, I think it will be useful to get a hit for "hooks" also for the podman run command, but this is definitely very shallow documentation. Not sure if more documentation could be added here, or if this should be blog posts and other examples.

Unfortunately I don't have the possibility to use too much time on this, so I think this is all I will have time to contribute for now - but feel free to modify / extend etc of course :) .

[ninja-quokka]

Hi @jerabaul29,

I believe it would make more sense to enhance our existing docs on --hooks-dir here:

podman/docs/source/markdown/podman.1.md

Lines 60 to 74 in d5b5710

	#### **--hooks-dir**=*path*
	Each `*.json` file in the path configures a hook for Podman containers. For more details on the syntax of the JSON files and the semantics of hook injection, see `oci-hooks(5)`. Podman and libpod currently support both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is deprecated.
	This option may be set multiple times; paths from later options have higher precedence (`oci-hooks(5)` discusses directory precedence).
	For the annotation conditions, libpod uses any annotations set in the generated OCI configuration.
	For the bind-mount conditions, only mounts explicitly requested by the caller via `--volume` are considered. Bind mounts that libpod inserts by default (e.g. `/dev/shm`) are not considered.
	If `--hooks-dir` is unset for root callers, Podman and libpod currently default to `/usr/share/containers/oci/hooks.d` and `/etc/containers/oci/hooks.d` in order of increasing precedence. Using these defaults is deprecated. Migrate to explicitly setting `--hooks-dir`.
	Podman and libpod currently support an additional `precreate` state which is called before the runtime's `create` operation. Unlike the other stages, which receive the container state on their standard input, `precreate` hooks receive the proposed runtime configuration on their standard input. They may alter that configuration as they see fit, and write the altered form to their standard output.
	**WARNING**: the `precreate` hook allows powerful changes to occur, such as adding additional mounts to the runtime configuration. That power also makes it easy to break things. Before reporting libpod errors, try running a container with `precreate` hooks disabled to see if the problem is due to one of the hooks.

It makes more sense to me to have it documented under podman rather than podman-run:

$ podman --help | grep hooks
      --hooks-dir stringArray       Set the OCI hooks directory path (may be set multiple times) (default [/usr/share/containers/oci/hooks.d])

$ podman run --help | grep hooks
...

[jerabaul29]

Thanks for your comments @ninja-quokka :) . As a person who knows very little about these hooks and unfortunately does not have too much time to go in depth and check the details, it was not clear to me if the hooks in context of podman-build and podman-run were working the same way / referring to the same thing. For example in podman-build, I suppose the hooks work differently / do something else, as there is not yet if I understand correctly a container namespace on which to run e.g. network configuration?

Unfortunately I wont have time to work more on this - but feel free to take over, and / or close and open something better :) .

[mheon]

Concur with @ninja-quokka - this is a global option, so we should document in the podman manpage, not podman run. Though, honestly, this should probably be documented mostly in the containers.conf manpage, I expect that's how most people will interact with hooks... Anyways, if you're unable to complete, we can take this over.

[jerabaul29]

You certainly know better than me where this should live - I am a n00b on these topics :) .

I think it is best that you take over this indeed :) .