Documentation on Platforms is either incomplete or missing references

[ghost]

Issue Type

• Feature request

Molecule and Ansible details

N/A - This is about the latest documentation at https://molecule.readthedocs.io/en/latest/configuration.html#platforms

Desired Behavior

Perhaps I am missing something here, but I cannot seem to find any proper documentation about the supported properties for the class molecule.platforms.Platforms. I understand these may differ per platform type. Eg. docker may have other properties than Podman? But I would like to be able to somehow find what may be specified.

At time of writing this issue, the most verbose example in your documentation is the following

platforms:
  - name: instance-1
    groups:
      - group1
      - group2
    children:
      - child_group1

However, through trial and error I have found many more working properties.

platforms:
  - name: some-platform
    image: # docker image
    command: # docker run CMD instruction
    volumes:
    - # volume mounts
    privileged: true/false
    pre_build_image: true/false

Where would I start to look for a specification of all supported properties? Could the documentation be updated to refer to that?

I run into this problem when trying to find out how to pass "--env" variables to the container.

[ghost]

PS. If someone could point me to a source of truth for all options I would be happy to open a PR.

[ghost]

I have found the solution for the environment variables.

platforms:
- ...
  env:
    ENV_VARIABLE: "value"

[jkirk]

I was looking for some docs regarding the platforms, especially pre_build_image, too. I just found this: #2735

[jkirk]

This is the commit, where pre_build_image was added: 9170961

[ghost]

Seems like docker driver was removed from the core project #2811 and the documentation has moved with it.

Looks like theres a full list of properties here https://github.com/ansible-community/molecule-docker/blob/master/molecule_docker/driver.py#L56

I don't know your doc generator so I can't answer this. Is it possible to pull python classes from another github repo? Would be great to have documentation for the drivers on the molecule documentation. If maintainers are not interested in this feel free to close.

[mkesper]

It's really annoying when you have to dive into the source to find out every detail of configuration. Ease of finding full documentation is a key aspect of software quality.

[timblaktu]

@jkirk @gmolkvk, I don't see any docs anywhere about how the docker driver is used. Just examples and blog posts around the internet where people have grokked how it works from the source code. I just spent several days figuring out how to do the most basic of things with molecule - test a playbook using docker driver. Figuring out what image is used for each scenario, and how dependencies get installed on it (prepare.yml?? Dockerfile.j2?? pre_build_image?? the answer is "yes" :-() is not documented. scouring the web for answers finds numerous other molecule newbies that have been similarly frustrated, but I don't see any evidence of why this has never been changed/adopted? I will start with a simple fork/PR to improve the immediate issues I see.

[jkirk]

JFTR, I just stumbled about some notes about "pre_build_image", see: https://molecule.readthedocs.io/en/latest/examples.html?highlight=service%20started%20failed#customizing-the-docker-image-used-by-a-scenario-platform

platforms[*].pre_build_image: Whether to customize base image or use as-is[^1].

* When true, use the specified platform[].image as-is.
* When false, exec docker build to customize base image using either:

  * Dockerfile specified by platforms[*].dockerfile or
  * Dockerfile rendered from Dockerfile.j2 template (in scenario dir)

The Dockerfile.j2 template is generated at molecule init scenario-time when --driver-name is docker. The template can be customized as needed to create the desired modifications to the Docker image used in the scenario.

Note: platforms[*].pre_build_image defaults to true in each scenario’s generated molecule.yml file.

• [^1]: Implementation in molecule-docker

[jkirk]

Oh, nice! This info has been added via @timblaktu in #3604! Thanks very much!

[ghost]

@zhan9san Could you clarify how you believe this issue is completed?

As far as I can tell, the MR linked here is about "pre_build_image", which is just one of the many available properties for the docker "platform". See https://github.com/ansible-community/molecule-docker/blob/legacy/master/molecule_docker/driver.py#L62

The original topic of this issue is about the sparse documentation at https://molecule.readthedocs.io/en/latest/configuration.html#platforms

I estimate that many (new) users may be frustrated when trying to find how to work with molecule when they cannot find this information.