docs: permissions & reference roles

[0x2b3bfa0]

Closes #75; may need extra eyes and opinions on documentation and some awkward kubectl scripting.

Potential follow–ups

• Validate all this code as part of our CI/CD smoke test workflow¹
• Migrate Kubernetes YAML to HCL for consistency²
• Provide tighter ABAC apart from basic RBAC permissions³

Exporting credentials (one–liner)

eval "$(terraform output --json | jq --raw-output 'to_entries[]|"export \(.key|ascii_upcase)=\(.value.value|@sh)"')"

Note: added eval to support multi–line variables like gcp service account credentials.

Originally posted by @0x2b3bfa0 in #75 (comment)

Footnotes

1. Requires some internal infrastructure work to create the appropriate sandboxes. ↩

2. Doesn't seem possible without a https://github.com/hashicorp/terraform-provider-kubernetes/issues/1641 ↩

3. https://twitter.com/michaelgat/status/1017166804139954176 ↩

[casperdcl]

I presume the permissions root folder is WIP? Would it be placed in docs/, tests/, .github/workflows or somewhere else?

[0x2b3bfa0]

Either tests/ or examples/ could be a good shoehorn–in–hand fit. Using docs/permissions/ might be also appropriate.

[casperdcl]

Yes in any case could you also add a page docs/guides/permissions.md? (Actually I'd suggest also deleting the current permissions/README.md to avoid duplication/maintenance sync troubles).

Could then cross-ref the main.tf example files.

[0x2b3bfa0]

Then,

• Rename permissions/README.md to docs/guides/permissions.md
• Rename permissions to docs/permissions ❓

[0x2b3bfa0]

d2b9e1a

[casperdcl]

actually can we merge permissions.md with authentication.md? They shouldn't be separate pages IMO. The latter name is probably better to keep.

[casperdcl]

getting there!

[casperdcl]

minor

[casperdcl]

one slight concern I have is the syntax won't work on all shells (e.g. windows) but is probably understandable to the sort of users it targets.

[casperdcl]

lgtm.

(minor) could we remove as many of the empty newlines in the *.tf/*.sh files as possible?

[0x2b3bfa0]

• When both arguments and blocks appear together inside a block body, place all of the arguments together at the top and then place nested blocks below them. Use one blank line to separate the arguments from the blocks [...]
• Use empty lines to separate logical groups of arguments within a block [...]
• Top-level blocks should always be separated from one another by one blank line. Nested blocks should also be separated by blank lines [...]

(Infimum) Not at the cost of breaking the Style Conventions?

[casperdcl]

Not at the cost of breaking the Style Conventions

I think those conventions were written without deep thought.

If terraform fmt is happy we should be too, no?

[0x2b3bfa0]

I think those conventions were written without deep thought.

Deep Thought, I presume?

If terraform fmt is happy we should be too, no?

Inversely, I believe that terraform fmt was written without deep thought™

[0x2b3bfa0]

• terraform fmt should add an empty line at the end of the file hashicorp/terraform#23223 (comment)

adding and removing newlines is relatively easier to do [compared to horizontal whitespace] and often done for subjective reasons that an automatic tool cannot reason about

I was right, terraform fmt doesn't alter vertical whitespace because it was written without Deep Thought™

[0x2b3bfa0]

I'd prefer not to remove these newlines myself, on principle. 😅 Still, a commit with that change would be welcome.

[0x2b3bfa0]

Terraform configuration is usually formatted like in this example, following the style guide. Neither abd6742 nor omitting newlines are common practices.

Anyway, this boils down to a matter of taste, and adherence (or not) to official guidelines; I don't want to block a pull request because of an existential quandary. ⚔️ 😅

🔔 @casperdcl, please make the changes you deem opportune and merge this pull request.

[casperdcl]

Hope b74a784 is fine (specifically set -euxo pipefail).

About style, there are two options: 1) aim for comprehension-over-rules, or 2) use a comprehensive linter¹. Since as you say terraform fmt isn't quite (2) then I'd revert to (1) i.e. aid first-time readers 76bb6a9.

Footnotes

1. e.g. I detest black & yapf but tolerate them since at least they're comprehensive ↩

[0x2b3bfa0]

Yes, there is no canonical representation for HCL apart from @casperdcl–taste-format and @0x2b3bfa0-style-guide-format. In absence of machines there is no clear way of make a neutral choice and differences are minimal, so my pragmatic vote is for the former. 🏳️

set -euxo pipefail in b74a784 is great to have, although I don't know if users will be misled somehow by set -x to stderr 🤔

---

Post scriptum: I adore black... --line-length=79.

[0x2b3bfa0]

Ready to merge unless you want to sed '/^$/d' any other file. 😄