At a broad level, upgrading a Porter-provisioned EKS cluster involves the following main steps:

  1. Upgrading the EKS control plane
  2. Updating the launch configuration for the cluster’s autoscale groups to use a new EKS AMI
  3. Refreshing the instances in the cluster to use the new AMI
Application Downtime

Please note - this process may incur downtime for a couple of minutes at the end, as your cluster’s nodes are switched out for newer nodes - at this stage, Kubernetes will be responsible for switching your applications to working nodes, which may render them inaccessible for a few minutes.

Upgrading the EKS control plane

To upgrade the cluster’s control plane, navigate to the EKS dashboard on your AWS account, and for the cluster in question, click on Update now, in the Kubernetes version column.



This process may take 20-30 minutes; you can check whether the upgrade’s finished by hitting the Refresh button above your cluster list. Once the cluster’s version is successfully upgraded, you can proceed to the next step.

Modifying launch groups

Porter-provisioned EKS clusters make use of AWS autoscaling groups, which take care of ensuring your clusters have the resources they need to run your applications. The next step in the upgrade process involves modifying the launch configurations used by your cluster’s autoscaling groups, to use a new AMI containing the Kubernetes version you’re upgrading to.

Install the AWS CLI

We need the AWS CLI v2 to retrieve the AMI ID we need to seed in our launch configurations. If you don’t have the CLI installed, please follow the links below specific to your platform for installing and configuring the CLI:

Next, run the following command to retrieve the AMI ID; replace K8S_VERSION with the Kubernetes version you need, and AWS_REGION with the region your cluster is placed in:

$ aws ssm get-parameter --name /aws/service/eks/optimized-ami/<K8S_VERSION>/amazon-linux-2/recommended/image_id --region <AWS_REGION> --query "Parameter.Value" --output text


Running this gives you an AMI ID, which you should save for later.


Updating launch configurations

Navigate to the Auto Scaling groups in the EC2 dashboard, and locate the autoscaling groups used by your cluster - they’ll contain the cluster’s name in them. First we’ll modify the launch configuration for the autoscaling group used by system nodes - that’s the group where Instances is set to 2. Click on the launch template/configuration assigned to that autoscaling group:


In the screen that opens up, select Modify template (Create new version) from the Actions menu:


Now, scroll down to the Application and OS Images section, and paste the AMI ID you retrieved earlier.


In the search results that pop up, go to the Community AMIs section and select the single AMI displayed there:


This takes you right back to the launch configuration modification screen - ensure that the AMI has indeed changed.


Now scroll to the bottom and click Create template version.


Now you need to go back to the launch configuration you just modified, and set the new template as the default version. After going back to the launch configuration, select Set default version from the Actions menu, and in the popup that appears, set the version you just created as the default version.



And that’s it! Repeat these steps for the second autoscaling group, using the same AMI ID, and your launch configurations will be updated.

Refreshing instances

The last step in the upgrade process involves refreshing your autoscaling groups to run new instances, based on the latest versions of the launch configurations we modified; the autoscaling groups provision new instances and swap out older nodes running the older Kubernetes version in your cluster, for the newer nodes with the new Kubernetes version.

To get started, navigate back to the Auto Scaling groups section on the EC2 dashboard, and click on the name of the autoscaling group where Instances is set to 2 - that’s for system nodes, and we’ll upgrade those nodes first. In the screen that opens up next, select the Instance refresh section, and click Start instance refresh.


Now, scroll down and expand the Desired configuration section. In the options that appear, ensure that Update launch template is selected, and that the version of the launch configuration you created with the new AMI, is selected in the Version dropdown. Then click Start instance refresh.


This triggers a refresh for the system nodes in your cluster, and you can monitor the status of the refresh by clicking the Refresh button. This process can take up to 15 minutes; once it’s complete, you can move on and repeat the same procedure for the other autoscaling group.