docs: Add cts_user_defined_meta option #9561
Conversation
findkim
added
type/docs
| @@ -95,6 +95,8 @@ service { | |||
| - `name` - (string: required) The Consul logical name of the service (required). | |||
| - `namespace` <EnterpriseAlert inline /> - (string: "default") The namespace of the service. If not provided, the namespace will be inferred from the Consul-Terraform-Sync ACL token, or default to the `default` namespace. | |||
| - `tag` - (string) Tag is used to filter nodes based on the tag for the service. | |||
| - `cts_user_defined_meta` - (map[string]) User-defined metadata is a map of strings that will be appended to the [service input variable](/docs/nia/installation/requirements#module-specifications) for compatible Terraform modules. Not all modules may use this value. To determine if your task uses metadata or what the expected keys and format are, reference documentation for the module(s) configured for your tasks. | |||
| - If multiple tasks depend on the same service but require different metadata, you can declare different sets of metadata for the same service. Define multiple service blocks for the service with unique IDs (and identical names) for those blocks. The metadata can then be separated per task based on the service IDs. | |||
There was a problem hiding this comment.
I think we'll want an example of this somewhere... it makes sense in abstract but I'm still not 100% on what it would look like. Obviously not in here, in the reference section, but somewhere.
There was a problem hiding this comment.
+1 an example would be easier to follow. I don't know where I could write an example, if not here. Since we currently don't have a place for these edge case examples, would this section be so terrible as opposed to non-existent -- or do you have suggestions on places?
There was a problem hiding this comment.
I'm not sure where to put it at this point. I don't think the small examples in the configuration reference should get overloaded with all the different possible options, it gives the impressions that all those settings are needed. I'd say go ahead and merge this for now (ie. this is not a blocker) and we'll try to keep this in mind for the future. Maybe it can be worked into a learn guide or we could think about adding some documented examples.
There was a problem hiding this comment.
Thanks for starting this discussion. Slept on this and a few ideas came up
- Add examples in the PR for the feature. It's linked from the changelog -- it looks like a community member has already expressed interest on the PR! 😄
- Start including blogs as a part of our release workflow for features on hashicorp.com/blog
- ^ a less official blog in the repro's github wiki
There was a problem hiding this comment.
Oooo. I personally like 3 for the less official-ness and potential to organize a 'library' of examples. Another thing to pair with the ideas, I’ve always liked how the Go documentation has the expand/collapse option for go-playground examples. It’s nice for users who are skimming and want a quick example vs. users who want to understand a feature in-depth.
Just threw out the thought! Probably not feasible right now - I couldn’t find precedence in our docs besides the sidebar navigation. And the example you have in mind may be larger than just an expand/collapse section.
There was a problem hiding this comment.
Sure! And I wasn't very clear - I was imagining that examples could be in an expand/collapse section in the configuration page (not for us to include our Go docs).
There was a problem hiding this comment.
Ah even better. I like that
There was a problem hiding this comment.
I like the wiki idea, but wiki's are terribly hard to keep up to date and almost needs a dedicated resource. Probably the best way to make them work is to get the community to do it, but I'm not sure if we'll be allowed to have an publicly editable wiki in a hashicorp repo. Github wiki permissions do support granting wiki edit permissions by themselves... so maybe partners/volunteers?
Another thing I was thinking of working into hashicat was to have the examples all run as tests. To have the examples and enforce keeping them up to date by making them part of the CI test suite.
There was a problem hiding this comment.
I don't understand your difference between wiki / blog / learn guide upkeep? Other products publish blogs on describing new features (Terraform provider source, Vault 1.6) and aren't updated after published. These would be user-facing features and aren't pinned to implementation, and I imagine updates would involve breaking changes.
There was a problem hiding this comment.
Sorry, I was thinking more along the lines of documentation style examples, not blog posts. Using the wiki for informal blog posts is a much better idea that wouldn't have this sort of issues as people naturally understand that blog posts age.
So 👍 to that idea and sorry for the miscommunication.
preview