[DOCS] Configuration of custom mount for salt-master to use when authentication against vault is documented incorrectly.

[sscotter]

Description
Documentation at https://salt-extensions.github.io/saltext-vault/topics/basic_configuration.html say it should be configured as below.

vault:
  auth:
    method: approle
    mount: salt-master-approle
    role_id: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
    secret_id: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX  

However, this doesn't work. The salt master makes requests to the default /auth/approle/login rather than auth/salt-master-approle/login as expected.

However the documentation at https://github.com/salt-extensions/saltext-vault/blob/main/docs/ref/configuration.md#approle_mount indicates it should be

vault:
  auth:
    method: approle
    approle_mount: salt-master-approle
    role_id: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
    secret_id: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Note the third line is different (mount vs approle_mount). Using approle_mount works as expected.

Suggested Fix
Either one of the following

• Update documentation at https://salt-extensions.github.io/saltext-vault/topics/basic_configuration.html
• Update saltext-vault to use auth:auth:mount instead of auth:auth:approle_mount and update https://github.com/salt-extensions/saltext-vault/blob/main/docs/ref/configuration.md to match

I'll leave it to you to decide what makes the most sense.

Location or format of documentation

• https://salt-extensions.github.io/saltext-vault/topics/basic_configuration.html
• https://github.com/salt-extensions/saltext-vault/blob/main/docs/ref/configuration.md#approle_mount

Additional context
My, discussing with myself on Salt Users discussion group trying to get the bottom of the issue.

[lkubb]

Thanks a lot for taking the time to get to the bottom of this! Imo the best way forward is to correct the example AppRole configuration.

Do you want to submit the fix yourself? Otherwise, I'll do it.

On a side note, sorry about your setup issues. The docs could definitely be improved a lot, especially for beginners. If you want to voice any specific issues or have further questions, you're welcome to submit or ask them. :) Note that I don't monitor the mailing list (unsure how active it is these days).

[sscotter]

Hi @lkubb,

Thanks for the prompt response.

Imo the best way forward is to correct the example AppRole configuration.

I'd agree!

Do you want to submit the fix yourself? Otherwise, I'll do it.

I'd be happy to help, but I'm not sure how I'd go about fixing https://salt-extensions.github.io/saltext-vault/topics/basic_configuration.html as it's outside of the repo.

On a side note, sorry about your setup issues. The docs could definitely be improved a lot, especially for beginners. If you want to voice any specific issues or have further questions, you're welcome to submit or ask them. :) Note that I don't monitor the mailing list (unsure how active it is these days).

It's been a steep learning curve but I'm getting there :)
I do plan to document the salt/vault integration from start to finish for those that follow in my footsteps. I'm not sure where best to host it. I do have a little wordpress blog but it gets no traffic and is primarily for me to make a note of things I need to remember. If you have a suggestion of a better location to host the documentation I create I'm so ears. Happy to give you the content once created.

Thanks

Steve

[lkubb]

I'd be happy to help

Awesome :)

I'm not sure how I'd go about fixing salt-extensions.github.io/saltext-vault/topics/basic_configuration.html as it's outside of the repo.

That's the compiled documentation, the source of which is part of this repo:

saltext-vault/docs/topics/basic_configuration.md

Line 340 in 9794f02

mount: approle # <-- mount the salt master authenticates at

It's been a steep learning curve but I'm getting there :)

When I started using the legacy Salt-Vault integration, I climbed a similar steep curve – there was essentially no documentation to follow, just some hints and an outdated blog post by a third party. With the rewrite, I wanted to create much more detailed documentation. Sadly, once you're in too deep, it becomes more difficult to write beginner-friendly documentation... :) I really think you can make a difference here.

If you have a suggestion of a better location to host the documentation I create

If it's helpful for other people and you're fine with it, I'd like to make it part of the official docs. Once you're finished, you can create a new doc page, e.g. docs/topics/bootstrap_tutorial.md, and submit it as a PR.

[lkubb]

@sscotter I just merged the doc fix myself. If you want to publish your guide here at some point, you're very welcome to open a PR. :)

Thanks again for taking the time to investigate and sorry about the oversight!