General Upgrade Steps

This guide takes you through the recommended steps to take when upgrading your Panfactum version.

Before you being, please ensure you have reviewed the guide for pinning the Panfactum version.

Review the Changelogs

Some version upgrades require taking specific actions that we call out in the new release's changelog. Make sure you have reviewed the changes and understand what steps you need to take.

Update Local Development Environment

1. Update the version in your flake.nix file.

   {
       inputs = {
           pkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
   -       panfactum.url = "github:NixOS/nixpkgs/old-version";
   +       panfactum.url = "github:NixOS/nixpkgs/new-version";
       };
   
       outputs = { self, panfactum, pkgs, ... }@inputs: {
           devShells = panfactum.lib.mkDevShells {
               inherit pkgs;
               modules = [ (import ./devenv.nix) ];
           };
       };
   }
   

2. Run nix flake update. This will update your lockfile and then download the new versions of all utilities.

3. If you receive some warnings when your devenv reloads, run the recommended commands to update your repo files.

Update your Infrastructure

1. After updating your development environment, run pf-update-iac to upgrade the versions of all Panfactum submodules in your first-party infrastructure code.

2. Update the pf_stack_version terragrunt variable in only your lowest environment level: 1

   environment: "development"
   - pf_stack_version: "old-version"
   + pf_stack_version: "new-version"
   

3. Ensure that the terragrunt version for that environment is set to local in order to deploy the local changes from step 1 (review these docs). 2

4. Run pf-tf-init in the module directory to automatically upgrade your module.yaml and .terraform.lock.hcl files for every module.

5. On your local machine, run terragrunt apply across all modules in that environment. You can run terragrunt run-all apply to update all modules at once.

6. Check to ensure that the environment is functioning as expected.

7. Once you are satisfied, cut a new release of your stack repository indicating you have updated the Panfactum version.

8. Repeat step 2-5 for all environments in sequence, testing each environment before moving on to the next. For step 3, set the version to the release ref that you created in step 6.