Document oidc-agent, fedcloudclient and terraform

gwarf commented 1 year ago

Document using oidc-agent, fedcloudclient and terraform altogether. Using Dynamic DNS too.

I had to do this for myself so thought it may be nice to have some kind of of very guided tutorial/setup for starting up with a more advanced CLI usage.

github-actions[bot] commented 1 year ago

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/515

github-actions[bot] commented 1 year ago

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/515

gwarf commented 1 year ago

I've also some bits allowing to prepare some kind of template repository, that could also include requirements.txt to setup the python module, required terraform files and also using terraform an ansible inventory file, and a requirements.yml to install some ansible module and run it against the deployed VM. Maybe having this as a ral repo template may be handy/useful for some?

EGI-ILM commented 1 year ago

I am getting 404 from https://docs.egi.eu/documentation/515

Not sure if this is related or useful, but I documented some guides here:

gwarf commented 1 year ago

The 404 is the usual one when the preview is marked as deployed but not yet reachable for real, now it's here: https://docs.egi.eu/documentation/515/users/tutorials/oidc-agent-fedcloudclient-terraform/ (it's a WIP, some content, like the terraform files, is missing).

Currently my position/feeling is to aim at "promoting" tools that are properly maintained by an upstream and that we are sure will stay for long (ie thinks like terraform, oidc-agent and fedcloudclient, compared to home made scripts) , but I think providing a bunch of places/repo where people could look for more advanced stuff would be nice. But drawing the line about what to document or not is always difficult, especially as some stuff may become outdated.

Concerning your repositories (nice work!), we may at least want to reference them somewhere, so that people can find them. In the end I feel we are apparently all maintaining some personal documentation or even advanced scripts like yours, so while it's expected people will have to dive into stuff to understand/own them, there is some duplication of effort and lack of reuse and sharing, and I feel those resources may be interesting for other users.

Maybe we could at least add a section with some references to advanced tools/resources/repositories with a short description?

EGI-ILM commented 1 year ago

I agree, there is an inherent peril in maintaining documentation about products and tools that change rapidly, as the documentation becomes outdated and it is impossible to keep up.

I shared the links in my comment exactly for the issue you mention: checking if my work could help to avoid duplicated work. There is actually overlapping between my Terraform repository and this new tutorial. In my case, I created the repositories to address specific requests from the community ("how can I use Terraform on EGI infrastructure" and "how can I run disposable containers with automated means on EGI infrastructure" respectively). I just wanted to give a tested, specific step-by-step guide, which is easier than going through the whole documentation of disparate sources. In the case of Terraform I gave manual steps, but also created a user-friendly script, something as simple as possible for the user to have all the work done for them (e.g. it automatically creates Terraform files with the available flavours of a specific site, etc). This will solve the current community needs, but may require some updates in future...

As you mention, maybe the best is to link these guides from the docs. This way, if something is not relevant anymore, the link can be easily removed. Or it can be kept to serve as the base for updates or new requests. I think it is important to keep track of this efforts and knowledge, otherwise it will get lost. For example, other people did also a similar exercise with Terraform in the past, but this effort is not registered anywhere.

github-actions[bot] commented 1 year ago