Crossplane: Knowledge bank for common configuration missteps and observations

[hasheddan]

What problem are you facing?

While building out https://github.com/hasheddan/crosscd I have tested out deployeing quite a few combinations of resources using Crossplane. There are frequent situations where there is not a bug in Crossplane, but the cloud provider fails provisioning because some combination of configurations leads to an error. For instance, I tried to provision a CloudSQLInstance with private service connectivity to a Network, but the Subnetwork in that region had a secondary ip range of 10.0.0.0/8, which cause the CloudSQLInstance provisioning to fail because there was not a large enough ip range for it to provision a new subnet (which is how GCP does secure connectivity). When the secondary ip range was scoped down to 10.128.0.0/20 all provisioning was successful. There are numerous situations like this that one may encounter while provisioning infrastructure.

How could Crossplane help solve your problem?

While I certainly do not believe we should be documenting how to provision resources on every cloud provider (that is what their documentation is for), and many of these types of questions can be found by googling the error surfaced in the resource status, it would be nice for the experiences Crossplane community members have when provisioning resources to be documented in a central location. This could be Stack Overflow or Reddit or some other service, but deciding on a primary location will make knowledge discovery easier and more efficient.

[hasheddan]

cc @suskin @displague

[negz]

I really like this idea @hasheddan. I (strongly) agree that we don't want to be in the game of trying to interpret cloud provider errors on behalf of users at the code level. On the other hand, we want to do anything we can to make it easier for our users to troubleshoot issues they encounter while using Crossplane.

One idea that immediately comes to mind is to enable and use the crossplaneio/crossplane Github wiki for this, and to add code to Crossplane that generates a link to said wiki for each error encountered. We could either build a search query from the error, or attempt to hash it and link to a stable page. If we took the latter approach we'd need to be sure to strip unique identifiers from the error (e.g. https://github.com/crossplaneio/stack-aws/issues/69) and possibly to include context (e.g. CloudSQLInstance, condition deleting) when generating the hash.

https://crossplane.slack.com/archives/CEF5N8X08/p1574102246321500

[tommyknows]

Some kind of wiki / knowledge base would definitely be nice to have.

As a newbie with Crossplane, I see two things here:

• it should be "informal" enough so that everyone can add their issues, comments and experiences to the wiki.
• it needs to be advertised enough so that not only people that search for it will find it, but also normal users know about it and document their findings.

Both points are definitely "easy" hurdles to tackle, and I think the git wiki would be a good place to start.

It would also be helpful to be able to search for specific error codes, maybe not pinned down to the cloud providers (i imagine that the error codes are not too different between them?).

I don't think it is necessary to link to a stable page. It would, however, be cool if one could add tags to pages (I don't know if that's possible with the github wiki).
Basically, I could imagine a workflow like this:

1) I find an error - for example the 409 (resource name taken), on GCP with CloudSQL Instances
2) I know how to resolve it, so I'll create a wiki page for it (if none exists). I write down my findings, possibly also link to the google documentation that explains this.
3) I tag it with "HTTP: 409", "GCP", "CloudSQLInstance" (or something similar, I think there should be "tag groups", like CloudProvider, HTTP Code, Resource at least. probably more 🙂

What do you think? Is it even doable? Just tried to brainstorm a bit 🙂