Coder Terraform Provider v1.0 Docs

[stirby]

Customers have requested that we promote our terraform provider to v1.0. The product is quite stable and, of course, is used in every one of our customers' deployments.

To show that this is no longer breaking, we should promote the release versioning to v1.X.X; before we do so, the docs should meet v1.0 standards. As I mentioned, we don't get many stability requests, but there are often requests for elaboration on the provider's behavior. There are a few resources/data sources that are missing code examples, or may be enriched via context.

Docs checklist for v1.0

• Resource docs
  • coder_env
    • Code examples
  • coder_script
    • Code examples
    • Explanation on parallel execution
    • Startup script implications
    • Link to discussion on execution ordering (frequently requested)
      • not necessary
• Data source docs
  • coder_external_auth
    • Code examples
    • Link to coder.com external auth docs
  • coder_parameter
    • Code examples (show validation types, monotonicity, etc)
      • Should just grep the closed customer requests on coder_parameter (like this)
    • Code example not consumed in docs generation #242
    • Optional: Fix inline link under icon
    • Optional: Link to discussion on coder_parameter extension
  • coder_provisioner
    • Code example
    • Optional: Fix inline links
  • coder_workspace
    • Optional: Expand code examples
      • Not enough attributes to warrant further examples
  • coder_workspace_owner
    • Code examples
• Get template details in terraform coder#13122 - indicate required version of coder for resource functionality
• Improve version compatibility #224
• bump go version #222
• docs missing deprecation notice and migration steps #237
• [ ] Remove deprecated resources/data sources #250
• docs: improve docs by using code-styled markdown #260

[stirby]

A candidate to further improve the docs here:
coder/coder#13122

[matifali]

Yes we should mention the minimum required coder version on the main page of provider docs for each release.

For example when we publish version 1.0.3 of the provider, we should mention as a warning block on main page that

Important

This provider version requires Coder version 2.11.0 or above.

Or we can move the warning to only the resources that are affected.

Like for coder_env page we can include.

Important

This provider version requires Coder version 2.7.0 or above.

[matifali]

Before realizing 1.0, we should do migration #180. Otherwise, it will stay a debt.

[bpmct]

coder/envbuilder#174 (comment) a good idea to add a new coder_user data source and deprecate the owner_ stuff

[matifali]

coder/envbuilder#174 (comment) a good idea to add a new coder_user data source and deprecate the owner_ stuff

@bpmct filed #219 and #220

[stirby]

Before realizing 1.0, we should do migration #180. Otherwise, it will stay a debt.

@matifali I understand the motivation here, but do not want to block v1.0 for the migration. I would even call this a candidate for v2.0. I'd rather rush these documentation changes + any minor changes and promote the versioning for the comfort of our customers.

If this unblocks feature development today, we can discuss.

For posterity

We recommend using the framework to develop new provider functionality because it offers significant advantages as compared to the SDKv2. We also recommend migrating existing providers to the framework when possible.

• List of benefits from migration

[matifali]

@stirby Sure, let's do that in v2.0, then.

[stirby]

I am re-opening since we need to cut the v1.0

[matifali]

@stirby I think we should resolve #203 too before we cut the 1.0 release.

It doesn't matter if we are removing all deprecated items. But that needs to be done too #250.