Move ansible documentation into this repo

[Bubballoo3]

The https://github.com/osc/ood-ansible repo has a lot of information about automating deployments of OOD. Given that we encourage the community to use automation tools to help manage their instances, it could increase discoverability of the ansible role if we moved that documentation here under an 'Automation' tab or similar. This could also make it easier for maintainers to manage, by just having one less location to update.

[treydock]

If we document Ansible, we also need to document Puppet. Puppet is not as popular as Ansible but we do have some sites besides OSC using Puppet.

I will note that simply linking to the Ansible or Puppet repo is sufficient in my mind. I think that's pretty normal to have to look at automation-specific docs when deploying something. If we only supported 1 method and it was part of main OnDemand repo, then I think dedicated docs here would make sense. Maybe the most to do here is document some common recipes for Ansible and Puppet but don't think it makes sense to move all their docs to here.

[johrstrom]

Yea I think this is more like 'create an automation tab' and have some information there just to highlight these 2.

Moving that documentation here I don't think makes a lot of sense because galaxy picks up the README.md from the role itself when it's published, so if it's here, galaxy won't display it. Probably similar to puppetforge or whatever the open source version is.

[moffatsadeghi]

Having more documentation that what is currently here is the goal. Now, what should be here is I think what we are trying to determine.

There is only one line mentioning ansible and puppet here: https://osc.github.io/ood-documentation/latest/installation/add-cluster-config.html#cluster-configuration and I think it would benefit users to have a bit more here.

If we document Ansible, we also need to document Puppet. Puppet is not as popular as Ansible but we do have some sites besides OSC using Puppet.

Yes, I totally agree!

I will note that simply linking to the Ansible or Puppet repo is sufficient in my mind. I think that's pretty normal to have to look at automation-specific docs when deploying something. If we only supported 1 method and it was part of main OnDemand repo, then I think dedicated docs here would make sense.

I'd like to have a bit more than linking because that is what we have currently and for how much we push for automation, we just have a single link off to the galaxy docs.

Maybe the most to do here is document some common recipes for Ansible and Puppet but don't think it makes sense to move all their docs to here.

Common recipes to do what in Ansible or Puppet? Common ways to set it up, commands to grab the most recent release, or were you thinking something different?

[treydock]

Puppet still uses Puppet Forge, OpenVox hasn't forked that yet as Puppet Forge is still "open source".

Common recipes to do what in Ansible or Puppet? Common ways to set it up, commands to grab the most recent release, or were you thinking something different?

For Puppet it would be Hiera data (YAML) but that's also already present in the Puppet README so a bit of duplication. Personally I think just getting people the links to each repo might be enough but if we want more for at least Puppet just some YAML examples of how to define the data for Puppet. I don't think we should be in the business of documenting how to use the automation, that's the job of each tool (Ansible, Puppet). If someone learns about Ansible or Puppet for the first time on our docs, I don't think we need to teach them how to use those tools, and likely a first deployment being OnDemand is a terrible idea. People new to autmation need to deploy simple things first, not OnDemand.

Most sys-admins will have a way to deploy things at their site, they want to know how is OnDemand installed. We can basically do this:

1. Here's the manual way (dnf install etc)
2. Here's the Link to Ansible
3. Here's the Link the Puppet

If a site is already using Ansible or Puppet they are familiar with going to a specific Galaxy or Forge page to learn what to do. If they aren't using one of those tools, the first item tells them the manual steps which they have to translate into whatever they use to manage their systems. HPC centers tend to have very specific and long standing ways to deploy software and often they have to take install instructions and translate that into whatever they do locally to manage systems.