expanding on credential usage docs #505
Conversation
…credentials differently in File vs Vault Storage configurations.
There was a problem hiding this comment.
Thank you very much for the PR! I left a comment, tests should actually not use different notation for _CREDS so that you can just use local creds as an override.
I understand that the reason you made this was because there was clearly some lack in clarity in how to set up/use vault, if you think that the .env portion needs to be more front and center then I'd suggest making that this PR's contents.
docs/credentials.md
Outdated
|
|
||
| ```xml | ||
| <fillField stepKey="FillApiToken" selector=".api-token" userInput="{{_CREDS.my_data_key}}" /> | ||
| <fillField stepKey="FillApiToken" selector=".api-token" userInput="{{_CREDS.secret/mftf/vendor/my_data_key}}" /> |
There was a problem hiding this comment.
This is actually incorrect, you need to be able to just use vendor/my_data_key for both (MFTF checks file storage, then vault).
If you're having issues with getting MFTF to read the vault version, see this section of devdocs:
https://devdocs.magento.com/mftf/docs/credentials.html#setup-mftf-to-use-vault
I think you just need to set this in .env:
CREDENTIAL_VAULT_SECRET_BASE_PATH=secret
MFTF should automatically call <CREDENTIAL_VAULT_ADDRESS>/<CREDENTIAL_VAULT_SECRET_BASE_PATH>/mftf/<vendor/my_data_key> in your case.
There was a problem hiding this comment.
Thanks @KevinBKozan ! I actually do not have Vault set up locally, so I was completely shooting in the dark with the Vault portion of the docs.
Do you have suggestions on how to modify this section? Ideally, I would imagine the best developer experience here would be to use the same token to access the secret regardless of the underlying storage leveraged. If that is the case, then I can definitely simplify the wording in the docs here to make that clear! Just let me know.
There was a problem hiding this comment.
Gotcha. I think some background info is kind of necessary to be able to make good changes to the docs, but the tl;dr is Vault integration with MFTF is about 50% done in the whole picture (framework integration is complete, build/EQP integration is not).
The primary purpose of the vault integration is actually to connect to the (as of yet, non-existant) MFTF vault credential store. This is the thing that builds are going to be using to run tests, so it becomes the "canonical" list of credentials that if you submit an extension, you can submit creds to your sandbox or testing environment.
So with that said, for local test running the prefered way would actually be for you to just define creds in .credentials as you need them. If you're running a test that requires _CREDS.some_api_key it'd be then on you to define it in .credentials since you would conceivably know the value (if you have access to it).
You can still use vault to resolve these _CREDS references though. So say a test is using _CREDS.some_api_key, the user flow would have to be
brew install vaultvault login <username/token/whatever EQP decides to use>-
- vault is now authenticated on the machine, MFTF will use this auth to access creds
-
- you don't need to tell vault where the server is AFAIK, it will know by your token to map it to the right server
- define details in
.env: -
CREDENTIAL_VAULT_ADDRESS=<whatever it ends up being>
-
CREDENTIAL_VAULT_SECRET_BASE_PATH=<probably just "secret">
-
- MFTF now knows what the vault address is, what the base path is, and has auth to access it
There was a problem hiding this comment.
So I guess the followup question is, what are you trying to use vault for, connecting to that central service or a local instance? That may help guide how we can make this document better to use.
There was a problem hiding this comment.
Oh, I'm using File Storage (.credentials file) locally so the updated File Storage docs is all I would add. I assumed Vault Storage was ready; if it's not, perhaps best to leave out any details for now. What do you think?
There was a problem hiding this comment.
You're honestly probably right. We can make reasonable assumptions about how it all ends up being implemented outside MFTF (as a framework), but we can leave out details for now. 👍
There was a problem hiding this comment.
Cool, I've updated the docs to remove the Vault details.
|
@filmaj thank you for the contribution + discussion! We'll keep you all updated as the vault implementations get further along 👍 |
Description
Expanding on the usage section in the Credentials docs. When trying to set up my project for use with MFTF Credentials the first time, I kept getting errors around the key not being found.
Turns out I was following the docs too explicitly. In the usage section, there is no mention of providing the vendor prefix in the key name, whereas in the section on how to add secrets (at least to File Storage), the instructions indicate to prefix your key names with a vendor prefix.
This PR, then, calls out how to use credentials and makes it explicit to, in the File Storage case, prefix your key name with the vendor.
Also tried to be explicit about different usage in File vs Vault Storage configurations, but, I have no experience with Vault Storage, so am assuming a lot about how to use it! This PR could definitely use a once-over with someone who has hands-on experience with using Vault Storage credentials.
Contribution checklist