Generating a Provider guide #130

turkenh · 2021-11-01T20:27:53Z

Description of your changes

This PR adds two document:

Generating a Provider using Terrajet
Configuring a Resource

Fixes #42

I have:

Read and followed Crossplane's contribution process.
Run make reviewable to ensure this PR is ready for review.
Added backport release-x.y labels to auto-backport this PR if necessary.

How has this code been tested

Run the steps end to end and verify it works.

docs/generating-a-provider.md

sergenyalcin · 2021-11-06T21:48:08Z

I tried creating a provider and configuring a resource in the provider, following the steps in the documentation. I completed the tests without any problems. These documents are clear to me.

turkenh · 2021-11-08T06:12:31Z

I tried creating a provider and configuring a resource in the provider, following the steps in the documentation. I completed the tests without any problems. These documents are clear to me.

Thanks for trying it out @sergenyalcin, much appreciated!

docs/generating-a-provider.md

displague · 2021-11-12T19:58:29Z

docs/generating-a-provider.md

+
+       Run:
+       ```bash
+       go mod tidy


It may be helpful to note that providers that are >v1 without being compatible with https://go.dev/blog/v2-go-modules will need to update their go.mod and set the version of their provider with the hyphenated format (I don't know what to call this format and I don't know how to get it back from a command - I always dig up and truncate the commit sha and timestamp by hand).

After this, they will need to run go mod tidy again.

$ go mod tidy go: downloading github.com/equinix/terraform-provider-metal v1.1.1-0.20210929123308-2d7fb2c4b0ce

docs/generating-a-provider.md

muvaf · 2021-11-15T16:37:47Z

docs/generating-a-provider.md

+   mkdir config/branch
+   ```
+
+   ```bash


Suggested change

```bash

```go

Because they won't write the exact code, seeing it in command format won't really help as much. So, I'd suggest having YAMLs and Go snippets as is to get syntax highlighting and get users to copy-paste them in their editors instead of running commands. The same doesn't go for the generic find&replace commands we have at the top for example, because they will run them regardless of the provider they're generating.

these files don't exist at this point and I found this to be more convenient while following the guide, instead of creating directory, file and copy/pasting file content to an editor.

muvaf · 2021-11-15T16:38:17Z

docs/generating-a-provider.md

+           "github_repository$",
+           "github_branch$",


Suggested change

"github_repository$",

"github_branch$",

"github_repository",

"github_branch",

Would it be easier to understand if we targeted single resources here instead of having prefixes?

Including a commented out .* example would demonstrate that regex is available and showcase (what I imagine) would be the most common setting.

It is difficult to exclude patterns. Perhaps a WithExcludeList feature (or equivalent example) would help.

This comes in handy when you don't want to persist your deprecated Terraform resources types.

nm - I found WithSkipList

@muvaf not sure I got your point. We are already including single resource when we append $ to end. Otherwise, it will generate all resources starting with github_repository or github_branch

docs/generating-a-provider.md

muvaf · 2021-11-15T16:46:42Z

docs/generating-a-provider.md

+       }))
+   ```
+
+7. Finally, we would need to add some custom configurations for these two


Because the custom config doc goes into great detail, what do you think leaving provider generation part end here? i.e. use .* to generate all and then let them know they can now provide custom configs by following that other guide.

I was about to leave the same comment.

I'm about to run through this guide for a second provider and I plan on skipping steps 4, 6, and 7. I'll use .*.

Once I have all of the CRDs generated (and pushed), I will revisit step 7 to set up references. This will be an open issue on my new project "setup referencers".

I'll revisit step 6 if I have to remove any resources that don't convert well.

I would prefer to create an end-to-end experience here.
Starting from scratch and having some resources provisioned. I am a bit hesitant that if people try to generate all resources at this point, they might be discouraged due to some unexpected issues (e.g. conflicts due to a missing resource configuration).

I've extended the note after step 8 to mention how all resources could be generated and configuring them could be a next step.

muvaf · 2021-11-15T16:49:06Z