Improve gcp_compute plugin parameters documentation

[walterdolce]

SUMMARY

The gcp_compute inventory plugin has a less-than-ideal documentation, I would say. None of the non-trivial parameters are documented and I could not find any documentation or example usages around showing how one would want/have to use them.

By "them" here I refer to parameters like groups, keyed_groups, etc.

I think the lack of documentation might get in the way of adopting the tool.

ISSUE TYPE

• Documentation Report

COMPONENT NAME

gcp_compute

ANSIBLE VERSION

The latest at this time of writing

CONFIGURATION

N/A

OS / ENVIRONMENT

N/A

ADDITIONAL INFORMATION

It would be nice if you would add comprehensive documentation to everything you do. Perhaps add "document this thing and show how to use it" as the definition of done?

Thank you.

[ansibot]

Hi @walterdolce, thank you for submitting this issue!

click here for bot help

[ansibot]

Files identified in the description:

• lib/ansible/plugins/inventory/gcp_compute.py

If these files are inaccurate, please update the component name section of the description or use the !component bot command.

click here for bot help

[sivel]

Is the documentation provided at https://docs.ansible.com/ansible/latest/plugins/inventory/gcp_compute.html insufficient to answer your questions?

needs_info

[walterdolce]

Unfortunately yes, it's insufficient.

For example, I don't know how add hosts to group based on Jinja2 conditionals for the groups parameter translates to code. Please see #47574

[sivel]

Is there a reason we cannot keep both discussion in a single issue? I believe that answering your question in this issue, would also answer your question in #47574

[sivel]

However, there is documentation that applies to all inventory plugins, that should explain how to use groups at https://docs.ansible.com/ansible/latest/plugins/inventory.html

keyed_groups:
  # add hosts to tag_Name_value groups for each aws_ec2 host's tags.Name variable
  - key: tags.Name
    prefix: tag_Name_
    separator: ""
groups:
  # add hosts to the group development if any of the dictionary's keys or values is the word 'devel'
  development: "'devel' in (tags|list)"

[walterdolce]

Hmm I didn't come across this page before. Thanks @sivel.

add hosts to the group development if any of

How do I add all hosts to the group development by default, regardless?

[walterdolce]

that should explain how to use groups at https://docs.ansible.com/ansible/latest/plugins/inventory.html

Would it make sense to add a link to this page on the gcp_compute plugin page?

Something like "for more info and examples on how to use group, etc please see {{page}}"?

Happy to send a PR for this

[sivel]

How do I add all hosts to the group development by default, regardless?

I believe like the following:

development: true

Would it make sense to add a link to this page on the gcp_compute plugin page?

I'll defer this question to our docs team.

cc @acozine

[acozine]

@walterdolce yes, a PR adding links to the gce_compute plugin docs would be very welcome!

[acozine]

@walterdolce take a look at https://docs.ansible.com/ansible/devel/community/documentation_contributions.html#community-documentation-contributions for some pointers on updating documentation, and feel free to join the #ansible-docs channel on Freenode IRC if you get stuck or have questions.

[walterdolce]

I believe like the following

Thanks @sivel. That seemed to have worked. But now it seems that my GCP project-specific compose variables are not being picked up.

Inventory file:

---
plugin: gcp_compute
projects:
  - myproject
filters:
- name = instancename
scopes:
- https://www.googleapis.com/auth/compute
service_account_file: ./serviceaccountkeyfile.json
auth_kind: serviceaccount
groups:
  mygroup: true
compose:
  ansible_connection: ssh
  ansible_ssh_private_key_file: ./.ssh/provisioned_gce_vm_ssh_priv_key
  ansible_user: myuser

During the play, I get the following:

Failed to connect to the host via ssh ...
...
...

Trying private key: path/to/local/system/user/.ssh/id_xmss\r\ndebug3: no such identity: /path/to/local/system/user/.ssh/id_xmss: No such file or directory\r\ndebug2: we did not send a packet, disable method\r\ndebug1: No more authentication methods to try.\r\nmysystemuser@the-intance-ip: Permission denied (publickey).

[walterdolce]

Never mind. Moving the vars in the relevant group_vars/mygroup/vars.yml got Ansible to pick those up. It would be good to clarify why having vars defined within compose didn't work though.

I consider my issue as solved for now, but I will leave this open until I manage to send the PR for the documentation update if you don't mind.

[jeanfabrice]

@walterdolce Did you try "composing" like this :

...
compose:
  ansible_connection: "'ssh'"
  ansible_ssh_private_key_file: "'./.ssh/provisioned_gce_vm_ssh_priv_key'"
  ansible_user: "'myuser'"

=> Without double-quote & single quotes, Ansible dynamic inventory resolves values as jinja variables, not string

[ansibot]

cc @erjohnso @rambleraptor
click here for bot help

[walterdolce]

Hi @jeanfabrice, no I did not. It would be fairly confusing if I had to resort to that kind of workaround. As an Ansible user, I would expect to either use {{jinja_variables}}, or simply plain YAML.

[walterdolce]

Hi all. Quick update regarding the documentation issue. I have by chance discovered that if you have a group name containing a dash (-) in its name, somewhere along the line it will be converted to an underscore (_).

I haven't seen this documented anywhere. Please correct me if I'm wrong. Thanks!

[ansibot]

Files identified in the description:
None

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

[sivel]

!component=lib/ansible/plugins/inventory/gcp_compute.py

[ansibot]

Files identified in the description:

• lib/ansible/plugins/inventory/gcp_compute.py

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

[ansibot]

Thank you very much for your interest in Ansible. Ansible has migrated much of the content into separate repositories to allow for more rapid, independent development. We are closing this issue/PR because this content has been moved to one or more collection repositories.

• lib/ansible/plugins/inventory/gcp_compute.py -> https://galaxy.ansible.com/google/cloud

For further information, please see:
https://github.com/ansible/ansibullbot/blob/master/docs/collection_migration.md