Problem: There are several inconsistencies in our current upgrade documentation and the approach suggested to upgrade PE.
CS team engaged upgrading PE and the upgrade did not go very smoothly. This ticket is was created out of a retrospective we did as a CS team.
Here is a list of issues identified with our Public upgrade docs
- The doc itself ** is not presented in a very consumable fashion and we need to revisit how the information is laid out. My suggestion would be to split out the upgrade paths. There are 2 potential upgrade paths for Puppet. We need break out the single document into two documents.
- An upgrade -> when going from version x to version y
- A migration -> where the underlying O/S and infrastructure needs to be recreated and a new Puppet deployment has to be done
- Additionally, the upgrade cautions are contextual - they don't apply to all the versions of Puppet. We should re-structure it so that customers can clearly identify if the caution is applicable for their Puppet version
- The documented upgrade process itself needs to be revisited as we found a few discrepancies:
- Under the steps for retired platform we ask customers to Install your current PE version on the new node but this step is actually not required. In a large environment, doing prep for this step actually takes 1-2 day
- Running the backup/restore as documented is not feasible in very large Puppet deployments - support asked us to use their KB and do dump/restore of selective tables instead
- We need more detailed steps when doing a migration