[Documentation: podman_container] The behavior of the state key is inconsistent with docker_container and not well documented

[gotmax23]

This issue is regarding the container.podman.podman_container module. I discarded the regular bug template because it is not applicable to this issue.

It appears that state: present and state: started do the same thing. In general, the documentation for the state key is unclear.

Additionally, the state key for the community.docker.docker_container module has different options and behavior than podman_container. For example, the docker_container module lacks the state: created option. Instead, on docker_container, state: stopped stops existing containers and also creates new containers without starting them (the role of state: created on podman_container). state: present with docker_container maintains the current state of existing containers and recreates the container if necessary, but with podman_container, it always starts a container, which is the same thing state: started does.

Related: #45

[sshnaidm]

OK, let's put things in order:

Docker choices:

absent
present
stopped
started - default

Podman choices:

- absent
- present -> alias to started
- stopped
- started - default
- created

• absent does the same in all.
• present in docker Asserts the existence of a container matching the name and any provided configuration parameters. which checks idempotency and recreates in case it's needed.
  present in podman does the same, but ensures containers is started and its alias is started. In docker it ensures container is created (if didn't exist) and does NOT start it. So actually dockers present is acting as created in podman.
  We can change alias in podman from present -> started to present -> created and it should be same as in docker.
• started behaves same in docker in podman
• stopped - if no containers, it acts as created/present, if container exists it stops it. and it's exactly as in podman.

So what's required if I understand correctly, is changing 'present -> started' in podman to 'present -> created'.
@gotmax23 what do you think?

[gotmax23]

@sshnaidm Yes, I think that makes sense.

I think it is also necessary to change the documentation to state that state: present is just an alias to state: created (or vice-versa). It's confusing to have seperate descriptions for two options that do the same thing.

For good measure, I think the docs should clarify that state: created (and its new alias) will not stop an existing container matching the config parameters if it's already started.

Thanks!

[sshnaidm]

Yeah, makes sense.