Role survey spec

[chouseknecht]

Summary

In order to make Galaxy content immediately useful in Ansible Tower, we're building a POC that adds a survey spec to roles. A survey spec is metadata describing the variables required to execute the role, including each variable's data type, optional default value, and an optional list of valid choices.

The intention is for a survey spec to closely follow the format and specification of a Tower job template survey, such that a future version of Tower is able to consume it. Looking into the future, Tower will be able to read a role's spec file, generate a playbook, generate an HTML form representation of the survey that prompts the user for the required variables, and then execute the playbook and role.

That's the future vision. For now, the POC will focus on building a CLI tool in Ansible that's able to consume the survey spec, and make it simple to immediately execute a role.

POC

As mentioned above, the POC will focus on creating a CLI tool within Ansible that's able to consume the survey spec, validate that required variables are present, and execute the requested role.

The following describes the scope of the first iteration:

• New CLI tool ansible-role
• Survey spec will live in meta/survey.yml
• Format of the survey will match Tower’s survey API, as closely as possible.
• Execution of the role will involve the generation of an in-memory playbook object that looks something like: https://gist.github.com/alikins/24cf015b41d5222d3a560fc2791bf8cb
• Variables will be passed as ‘extra vars’
• The validation task will check that values required by the survey are available
• survey.yml and defaults/main.yml will be treated as mutually exclusive
• A dependent role's survey.yml will be ignored, if it exists, and the dependent role will execute as normal.

[bcoca]

Not the same, but this proposal does have some overlap as both use very similar 'source data' https://github.com/ansible/proposals/issues/39

[tima]

I hope it's similar @bcoca -- you're linking this proposal back to itself. ;)

[bcoca]

@tima fixed

[abadger]

Also: https://github.com/ansible-network/network-engine/pull/119 ( @privateip @ikhan2010 )

[privateip]

One thing to consider is that a given role could have more than one survey.yml file. With the introduction of tasks_from in include_role and import_role, it cannot be assumed that there is a 1:1 mapping between role and use case. It is absolutely conceivable that a single role could have more than one entry point for execution and therefore need to support more than one survey that requires validation.

[chouseknecht]

@privateip

Depends on how we scope survey.yml. Not saying that we should, but one option would be to ignore any downstream survey.yml files, and only care about the one contained in the root role. If we don't do that, then we have to traverse the potential tree of roles, and find all of the survey.yml files, and mash them together into a single set of parameters. Not impossible, but potentially ugly.

Other thoughts that comes to mind... include_role is dynamic. Technically, the role it points to doesn't have to exist at execution time. You can literally generate and execute the entire role on the fly. I don't know if anyone actually does that, but you can. Execution can also be made conditional by the addition of when. What's the expectation in these cases?

The goal here is to execute the role being invoked. We want to check that we have the expected parameters. If we don't, fail fast with a meaningful message. If we do, execute.

If we say that the scope of survey.yml is limited to the parent role, then it becomes the role developer's job to put all the required parameters, options, defaults, etc. into the root survey. Which seems better than us attempting programmatically to decipher their intentions.

[privateip]

You are talking about role dependencies. I'm talking about role entry points. Take the following role struct:

roles/example
  /tasks
     |--- foo.yaml
     |--- bar.yaml

The following is a perfectly valid implementation in the playbook:

tasks:
  - name: entry point #1
    import_role:
      name: example
      tasks_from: foo

- name: entry point #2
  import_role:
    name: example
    tasks_from: bar

Its possible that both foo and bar required vastly different data structures to execute properly. That was what I was eluding to in my response. I agree with your commentary around role dependencies.

[chouseknecht]

@privateip

Ah. OK. Sorry. I was thinking of it wrong.

Your examples above make sense, and they point to why we're not executing the role within the context of ansible-playbook, or a user defined playbook. Instead we're contemplating a new CLI tool, ansible-role, that executes the role by generating an in-memory playbook object.

Here's what we think the in-memory playbook will look like: https://gist.github.com/alikins/24cf015b41d5222d3a560fc2791bf8cb

We just want to focus on basic role execution, which I think matches the majority of roles found in Galaxy, and sidesteps all the complexities and issues that arise when we're not in control of the playbook.

That being said, I think overtime we could expand on the complexity of the generated playbook. I can see, for example, adding some command options to ansible-role that enable choosing an entry point and a corresponding survey spec file. Maybe there are config options we can introduce, or metadata. Lots of direction this could go.

[alikins]

The ansible/ansible POC branch wip is at https://github.com/ansible/ansible/compare/devel...alikins:role_survey

For examples, see:

• https://gist.github.com/alikins/67513ca586676f5bf354a64515a8eaa8 (thats an example sans survey.yml)
• https://gist.github.com/alikins/a48fc89c89946acc8355626638c6202f (example with a survey.yml, one showing invalid input causing a fail, and another with valid input from extravars working)

[wenottingham]

If we don't do that, then we have to traverse the potential tree of roles, and find all of the survey.yml files, and mash them together into a single set of parameters. Not impossible, but potentially ugly.

Note that this is why AWX's workflows (as an example) only have a single, workflow-wide, survey.

[chouseknecht]

After a bit of deliberation we decided the following:

• Take Merged Approach -- survey and validation together, difference of two fields. Basically, bring this proposal together with #39
• Single file spec to put out for user input as POC
• Spec will mirror this link
• Separate ansible-role (or like) command line tool
• Follow up meeting on implementation (@bcoca, @privateip, @chouseknecht, @alikins)
• Need to work on better naming of this stuff. (TBD)
• Proposal #39 to be marked “Accepted” (or whatever the proper tag)

Marking 'rejected' in favor of #39 with the above caveats.