Arvados

22866-single-node-ansible @ 4815b72d1d905cc362e5b9bc46811b7883920c15 - developer-run-tests: #4831

This replaces the single-node Salt installer documentation with instructions based on Ansible. We want the Ansible playbook to be replacing the Salt installer generally, and it's at a point where the Ansible playbook should be more ergonomic for this use case.

This is based on instructions that Peter prepared. I refined the example configurations some to fix some minor bugs, make it more ergonomic to edit, and support more recent Arvados features.

I did consciously choose to remove some of the configuration options from the original documentation. Instead this documentation prioritizes getting the simplest possible install working with minimum fuss. I think this is what most people installing with this option want. The provided configuration templates give pointers for ways you might change the configuration in more advanced ways.

• All agreed upon points are implemented / addressed. Describe changes from pre-implementation design.
  • Yes
• Anything not implemented (discovered or discussed during work) has a follow-up story.
  • Ideally we would rename the documentation page. If this gets merged I will make a follow-up ticket about that. It's not a priority with deadlines coming up.
• Code is tested and passing, both automated and manual, what manual testing was done is described.
  • See above. Also built and reviewed the documentation locally.
• New or changed UI/UX and has gotten feedback from stakeholders.
  • N/A
• Documentation has been updated.
  • Yes
• Behaves appropriately at the intended scale (describe intended scale).
  • N/A
• Considered backwards and forwards compatibility issues between client and server.
  • N/A
• Follows our coding standards and GUI style guidelines.
  • N/A

A few quick comments -

1. In "Option 2. Install Ansible in a virtualenv with pip", the examples rely on full (absolute) paths to binaries and mention manual manipulation of paths. Shall we instead take advantage of the venv activation script (. path/to/venv/bin/activate) to simplify this part? (see e.g. here: https://github.com/PGPinformatics/PGPincubator/tree/main/arvados-setup#step-0-install-ansible-and-clone-arvados-playbooks)
2. The URL of the doc page still says salt-single-host.html. Shall we move the file path to say ansible-single-host.html?

As a simplification suggestion: In the "Run diagnostics" section, I believe that we can shorten this by asking the user to use arvados-client with sudo like this:

$ sudo arvados-client sudo diagnostics <options>

This allows us to exclude the envvars & docker setup instructions.

Zoë Ma wrote in #note-10:

A few quick comments -

1. In "Option 2. Install Ansible in a virtualenv with pip", the examples rely on full (absolute) paths to binaries and mention manual manipulation of paths. Shall we instead take advantage of the venv activation script (. path/to/venv/bin/activate) to simplify this part?

I think there's a trade-off here and it's not obvious which option is better. Activating the virtualenv makes the happy path simpler, but the trade-off is that if a problem occurs, it can become harder to diagnose the problem and the effect on the system is less predictable. People also need to remember to activate the virtualenv every time they want to run Ansible, and that's easy to forget in my experience.

The instructions I chose are more verbose but safer. I agree it's also not ideal. That's part of the reason why I put so much effort into documenting the pipx option: it should automate a lot of what we're trying to do manually here, with proper error-checking.

1. The URL of the doc page still says salt-single-host.html. Shall we move the file path to say ansible-single-host.html?

We definitely should, but I also don't want to break the old URL, and figuring out how to achieve that is a completely separate task that isn't as high-priority right now. I will make a separate follow-up story for that.

Lucas Di Pentima wrote in #note-11:

As a simplification suggestion: In the "Run diagnostics" section, I believe that we can shorten this by asking the user to use arvados-client with sudo like this:

We sure can, that's way better, thank you. Now at b141c6e0f968f64c8f333530dd93a4dfa23be3b0.

Thank you! One thing I noticed is that for Firefox, the section about adding security exceptions for self-signed cert says we should repeat this for a bunch of origins one by one. I remember this used to be just importing a custom CA. Is the latter (CA import) still doable with Firefox?

Zoë Ma wrote in #note-13:

Thank you! One thing I noticed is that for Firefox, the section about adding security exceptions for self-signed cert says we should repeat this for a bunch of origins one by one. I remember this used to be just importing a custom CA. Is the latter (CA import) still doable with Firefox?

Importing a single certificate authority (CA) is still possible in Firefox. But the expected install process doesn't use a CA, it uses a standalone self-signed certificate. If you try to import a single certificate, Firefox reports that as an error.

I don't see any method analogous to Chrome's. On the flip side, Firefox's version is a little more secure, since it only trusts the certificate for the URLs you exempt, not every site.

Thanks, the new doc looks good to me!