Add terrajet-to-upjet migration guide

[ulucinar]

Description of your changes

This guide aims to help the community to migrate their Terrajet-based Crossplane providers to Upjet as Terrajet is being deprecated.

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

Tested following the guide on github.com/crossplane-contrib/provider-aws.

[jeanduplessis]

Suggested change

	2. Some code that will be generated by Upjet requires go1.18 or later. If you
	provider's Go module declares go1.17 or smaller, you will need to update your
	module's Go version, and run a `go mod tidy` to make sure that `go.mod` matches
	the source code in the provider's module:
	2. Some code that will be generated by Upjet requires go1.18 or later. If your
	provider's Go module declares go1.17 or smaller, you will need to update your
	module's Go version, and run a `go mod tidy` to make sure that `go.mod` matches
	the source code in the provider's module:

[ulucinar]

Done.

[jeanduplessis]

Suggested change

	4. Now, you may attempt to run the Upjet's code generation pipelines:
	4. Now, you may attempt to run Upjet's code generation pipelines:

[ulucinar]

Done.

[jeanduplessis]

Suggested change

	At this step, you will most probably get some compile errors. Here are some
	changes that you will probably need to do, assuming the provider was
	bootstrapped using Terrajet's now deprecated [provider template
	At this step, you will most probably get some compile errors. Here are some
	potential changes you need to make, assuming the provider was
	bootstrapped using Terrajet's now deprecated [provider template

[ulucinar]

Done.

[jeanduplessis]

Suggested change

	You will also need to fix the referencer configurations for such managed
	resources using the [resource configuration API].
	You will also need to fix the referenced configurations for such managed
	resources using the [resource configuration API].

[ulucinar]

Replaced with "reference configurations" and added a link.

[muvaf]

I think we should also tell them to check some files in upjet-provider-template and sync with their repository. The ones that come to my mind are:

• apis/generate.go to see the new statements regarding deletion/generation.
• cluster/provider-X/images folder to integrate single image building process.
• Updating the build submodule.
• Checking Makefile.

I almost wonder if we should just suggest starting from upjet-provider-template by cloning it and move their config package into that and regenerate 🤔 What do you think? It would give them the terrajet->upjet move for free along with other changes.

[ulucinar]

Hi @muvaf,

I think we should also tell them to check some files in upjet-provider-template and sync with their repository.

Added new steps to be followed after the module migration from terrajet to upjet is done so that new upjet features can be used.

I almost wonder if we should just suggest starting from upjet-provider-template by cloning it and move their config package into that and regenerate

I think this is a good idea. It would make a full migration to utilize all upjet features and to publish the provider package in the Upbound marketplace (like what's been done for the https://github.com/crossplane-contrib/provider-pagerduty repo) easier.
And I think there's utility in a Go module migration guide that tells the steps needed to replace the github.com/crossplane/terrajet module with the github.com/upbound/upjet because there may be terrajet-based repos (maybe private ones) with heavily customized CI pipelines, or some new features that we enable by default in Upjet template repo like shared gRPC server, metadata extraction, doc/example generation may not be wanted/required and even not working for those providers.

What I would suggest would be to have a module migration guide that allows more flexibility and control on the migration process with some optional steps and may be in this guide point to another guide with proper explanation, which would instruct the user to bootstrap (initial cloning) from the upjet-provider-template repo.

What do you think?

[Upbound-CLA]

All committers have signed the CLA.

[muvaf]

there may be terrajet-based repos (maybe private ones) with heavily customized CI pipelines, or some new features that we enable by default in Upjet template repo like shared gRPC server, metadata extraction, doc/example generation may not be wanted/required and even not working for those providers.

Makes total sense, thanks @ulucinar !