search

ansible / molecule

Molecule aids in the development and testing of Ansible content: collections, playbooks and roles
https://ansible.readthedocs.io/projects/molecule/
MIT License
3.87k stars 659 forks source link

Documentation on Platforms is either incomplete or missing references #2854

Open ghost opened 3 years ago

ghost commented 3 years ago

Issue Type

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 commented 3 years ago

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

ghost commented 3 years ago

I have found the solution for the environment variables.

platforms:
- ...
  env:
    ENV_VARIABLE: "value"
jkirk commented 3 years ago

I was looking for some docs regarding the platforms, especially pre_build_image, too. I just found this: https://github.com/ansible-community/molecule/discussions/2735

jkirk commented 3 years ago

This is the commit, where pre_build_image was added: https://github.com/ansible-community/molecule/commit/9170961cd814e55f376d7fdd4c040b749b313924

ghost commented 3 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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.
jkirk commented 2 years ago

Oh, nice! This info has been added via @timblaktu in https://github.com/ansible-community/molecule/pull/3604! Thanks very much!

ghost commented 2 years ago

@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.

jkirk commented 2 weeks ago

The links above do not work anymore. examples.rst by @timblaktu (see: #3603) has been split up to several locations (see: #4102). The most relevant links for this issue are here now:

FTR, the code for the molecule docker driver can now be found here:

FTR, the code for the podman docker driver can now be found here:

So, I also still can not answer the following questions when looking at the documentation:

What is a good location to put this info in and prepare a documentation proposal?