What is the best documentation to understand how to upgrade a provider (I believe I'm using the terms correctly)? I'm using pulumi (written in python) to manage gcp using the classic provider. I've run into a resource which I can't manage because its quite recent. If my understanding is correct upgrading providers can be a challenge because the new provider doesn't necessarily read the old providers state. I think there are some state export / import tricks that can help. Are there best practices for this (or maybe least painful)?

If you mean, upgrade the version of the same provider, then it should just work. Just update your dependencies file, refresh the dependencies, and try again. It is reasonable to be concerned about this, if it's a big jump from your current version to the latest. As a safety net, you could export your current state. Since you're not going to be running any updates during this process (

pulumi preview

will be enough to tell if everything is continuing to work), you can rest assured that if you need to roll back your source, then you can import that state file and everything will be exactly as it was when you started.