Upgrading Linkerd

There are three components that need to be upgraded:

In this guide, we’ll walk you through how to upgrade all three components incrementally without taking down any of your services.

Upgrade notice: stable-2.2.0

There are two breaking changes in stable-2.2.0. One relates to Service Profiles, the other relates to Automatic Proxy Injection. If you are not using either of these features, you may skip directly to the full upgrade instructions.

Service Profile namespace location

Service Profiles, previously defined in the control plane namespace in stable-2.1.0, are now defined in their respective client and server namespaces. Service Profiles defined in the client namespace take priority over ones defined in the server namespace.

Automatic Proxy Injection opt-in

The linkerd.io/inject annotation, previously opt-out in stable-2.1.0, is now opt-in.

To enable automation proxy injection for a namespace, you must enable the linkerd.io/inject annotation on either the namespace or the pod spec. For more details, see the Automatic Proxy Injection doc.

A note about application updates

Also note that auto-injection only works during resource creation, not update. To update the data plane proxies of a deployment that was auto-injected, do one of the following:

  • Manually re-inject the application via linkerd inject (more info below under Upgrade the data plane)
  • Delete and redeploy the application

Auto-inject support for application updates is tracked on github

Upgrade notice: stable-2.1.0

As of the stable-2.1.0 release, the Linkerd control plane components have been renamed to reduce possible naming collisions. If you’re upgrading from an older version, you will need to clean up the old components manually as part of the upgrade. Perform the upgrade in the following order:

  1. If Linkerd is installed with automatic proxy injection, enabled, then you’ll need to start by removing the webhook that was created when it was installed, by running:

    kubectl -n linkerd delete \
      mutatingwebhookconfigurations/linkerd-proxy-injector-webhook-config \
      --ignore-not-found
    
  2. Upgrade the CLI. Note that right after upgrading the CLI, most of its commands will fail. You can only rely on the linkerd install command to complete the following steps, and only after doing so will the CLI be fully usable again.

  3. Upgrade the control plane

  4. Remove the old control plane deployments and configmaps, by running:

    kubectl -n linkerd delete \
      deploy/ca \
      deploy/controller \
      deploy/grafana \
      deploy/prometheus \
      deploy/proxy-injector \
      deploy/web \
      cm/grafana-config \
      cm/prometheus-config \
      cm/proxy-injector-sidecar-config \
      --ignore-not-found
    
  5. Upgrade the data plane

  6. Remove the old control plane services, by running:

    kubectl -n linkerd delete \
      svc/api \
      svc/grafana \
      svc/prometheus \
      svc/proxy-api \
      svc/proxy-injector \
      svc/web \
      --ignore-not-found
    

Step-by-step instructions

Upgrade the CLI

This will upgrade your local CLI to the latest version. You will want to follow these instructions for anywhere that uses the linkerd CLI.

To upgrade the CLI locally, run:

curl -sL https://run.linkerd.io/install | sh

Alternatively, you can download the CLI directly via the Linkerd releases page.

Verify the CLI is installed and running correctly with:

linkerd version

Which should display:

Client version: stable-2.2.1
Server version: stable-2.1.0

It is expected that the Client and Server versions won’t match at this point in the process. Nothing has been changed on the cluster, only the local CLI has been updated.

Upgrade the control plane

Now that you have upgraded the CLI running locally, it is time to upgrade the Linkerd control plane on your Kubernetes cluster. Don’t worry, the existing data plane will continue to operate with a newer version of the control plane and your meshed services will not go down.

To upgrade the control plane in your environment, run the following command. This will cause a rolling deploy of the control plane components that have changed.

linkerd install | kubectl apply -f -

The output will be:

namespace "linkerd" configured
serviceaccount "linkerd-controller" unchanged
clusterrole.rbac.authorization.k8s.io "linkerd-linkerd-controller" configured
clusterrolebinding.rbac.authorization.k8s.io "linkerd-linkerd-controller" configured
serviceaccount "linkerd-prometheus" unchanged
clusterrole.rbac.authorization.k8s.io "linkerd-linkerd-prometheus" configured
clusterrolebinding.rbac.authorization.k8s.io "linkerd-linkerd-prometheus" configured
service "linkerd-controller-api" configured
service "linkerd-proxy-api" configured
deployment.extensions "linkerd-controller" configured
customresourcedefinition.apiextensions.k8s.io "serviceprofiles.linkerd.io" configured
serviceaccount "linkerd-web" created
service "linkerd-web" configured
deployment.extensions "linkerd-web" configured
service "linkerd-prometheus" configured
deployment.extensions "linkerd-prometheus" configured
configmap "linkerd-prometheus-config" configured
serviceaccount "linkerd-grafana" created
service "linkerd-grafana" configured
deployment.extensions "linkerd-grafana" configured
configmap "linkerd-grafana-config" configured

Check to make sure everything is healthy by running:

linkerd check

This will run through a set of checks against your control plane and make sure that it is operating correctly.

To verify the Linkerd control plane version, run:

linkerd version

Which should display:

Client version: stable-2.2.1
Server version: stable-2.2.1

Upgrade the data plane

With a fully up-to-date CLI running locally and Linkerd control plane running on your Kubernetes cluster, it is time to upgrade the data plane. This will change the version of the linkerd-proxy sidecar container and run a rolling deploy on your service.

For each of your meshed services, you can re-inject your applications in-place. Retrieve your YAML resources via kubectl, and pass them through linkerd inject. This will update the pod spec to have the latest version of the linkerd-proxy sidecar container. By using kubectl apply, Kubernetes will do a rolling deploy of your service and update the running pods to the latest version.

Example command to upgrade an application in the emojivoto namespace, composed of deployments:

kubectl -n emojivoto get deploy -l linkerd.io/control-plane-ns=linkerd -oyaml \
  | linkerd inject - \
  | kubectl apply -f -

Check to make sure everything is healthy by running:

linkerd check --proxy

This will run through a set of checks against both your control plane and data plane to verify that it is operating correctly.

You can make sure that you’ve fully upgraded all the data plane by running:

kubectl get po --all-namespaces -o yaml \
  | grep linkerd.io/proxy-version

The output will look something like:

linkerd.io/proxy-version: stable-2.2.1
linkerd.io/proxy-version: stable-2.2.1

If there are any older versions listed, you will want to upgrade them as well.