Use this guide to migrate your existing installation of Knative serving on
Google Cloud to use a fleet with Cloud Service Mesh.

The previous "free trial" version of Knative serving, which is also referred to
as the "*GKE add-on*", includes a built-in and pared-down version of Istio 1.4
that is no longer supported starting in Anthos 1.8.

Upgrading your Knative serving installation to use fleets and
Cloud Service Mesh provides improved product upgrade and management independence as
well as improved integration across GKE Enterprise features.
[Learn more about what's new and changed](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install.md.txt#newandchanged).

> [!IMPORTANT]
> **Important:** Anthos Version 1.8 requires that previous installations of Knative serving (also referred to as the "GKE add-on") are migrated to use [fleets](https://docs.cloud.google.com/anthos/multicluster-management/fleets) and Cloud Service Mesh. Before you can upgrade your GKE Enterprise environment to Version 1.8 or later, you must first perform this migration process to upgrade your existing installations of Knative serving.

There are two paths for migrating your installation:

- The *recommended process* is to migrate your workloads from the cluster where
  the previous version of Knative serving is installed ("*GKE add-on*"), to a
  new cluster where you have installed and configured a new fleet installation
  of Knative serving. While this process is relatively straightforward and
  ideal, if your workloads serve traffic, migrating to a newly created cluster
  will cause down time. To perform this migration path, in your new cluster, you:

  1. [Install Knative serving as a fleet component](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install.md.txt).
  2. Deploy your services to the new installation.

     For example, you can use the instructions for
     [deploying a revision of an existing service](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/deploying.md.txt#revision)
     to individually download a YAML configuration file for each of your
     services and then deploy each YAML file to your new cluster in the
     fleet installation of Knative serving:
     1. In the *old* installation, you can run the following command to
        download a YAML configuration file, like `service.yaml`:

        `gcloud run services describe SERVICE --format export > service.yaml`

        Replace <var translate="no">SERVICE</var> with the name of your
        Knative serving service.
     2. In the **new** fleet component installation, you can then run the following
        command to deploy the same `service.yaml`:

        `gcloud run deploy service.yaml --cluster CLUSTER_NAME --cluster-location CLUSTER_LOCATION --project PROJECT_ID`

        Replace:
        - <var translate="no">CLUSTER_NAME</var> with the name of the cluster in your new
          fleet component installation of Knative serving.

        - <var translate="no">CLUSTER_LOCATION</var> with the
          [zone or region](https://docs.cloud.google.com/compute/docs/regions-zones.md.txt#available) of the
          cluster in your new fleet component installation of
          Knative serving.

        - <var translate="no">PROJECT_ID</var> with the ID of your Google Cloud project
          in which your new fleet component installation of
          Knative serving resides.

- Alternative: For users who are not able to create a new cluster and must
  migrate their active installation of Knative serving, you can follow the
  steps in this guide to:

  - Remove the previous "*GKE add-on*" and Istio resources.
  - Install new fleet resources.
  - Migrate to Cloud Service Mesh and then migrate your traffic.
  - Clean out all stale and unused resources.

The following guide walks you through the alternative process of upgrading your
existing and active installation of Knative serving, including all workloads,
to meet the requirements of GKE Enterprise 1.8 and later.

## Before you begin

- This upgrade process must be performed only on Google Kubernetes Engine clusters that
  previously installed Knative serving as the
  ["*GKE add-on*"](https://docs.cloud.google.com/anthos/run/archive/docs/setup#enabling-overview).

  #### Check if the "*GKE add-on*" is
  installed.


  To check if your installation of Knative serving is the
  "*GKE add-on*", run the following command:

  ```bash
  gcloud container clusters describe \
  CLUSTER_NAME \
  --region CLUSTER_LOCATION \
  --project PROJECT_ID --format='get(addonsConfig.cloudRunConfig)'
  ```


  Replace:
  - <var translate="no">CLUSTER_NAME</var> with the name of your cluster.
  - <var translate="no">CLUSTER_LOCATION</var> with the [location](https://docs.cloud.google.com/compute/docs/regions-zones.md.txt#identifying_a_region_or_zone) where your cluster is located.
  - <var translate="no">PROJECT_ID</var> with the ID of your Google Cloud project.


  Results:
  - **"*GKE add-on*" not installed** :
    - Nothing is returned to your terminal if the add-on was never installed.
    - `disabled=true` is returned if the add-on was previously uninstalled.
  - **"*GKE add-on*" is installed** : If the add-on is installed in your cluster, the configuration details for the add-on are returned. Example: `loadBalancerType=LOAD_BALANCER_TYPE_EXTERNAL`

  Example:
  :
      The following example demonstrates that Knative serving was installed in the
      `my-addon-cluster` cluster through the "*GKE add-on*", which
      is configured to handle external traffic:

      ```bash
      gcloud container clusters describe my-addon-cluster \
      --region us-central1-c --project my-gcp-project \
      --format='get(addonsConfig.cloudRunConfig)'
      ```


      Response:

      ```bash
      loadBalancerType=LOAD_BALANCER_TYPE_EXTERNAL
      ```

  <br />

- You must have adequate permissions in your Google Cloud project
  to meet the requirements for your cluster,
  fleet, and Cloud Service Mesh:

  - If you have the [*Owner*](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#basic) role for
    the Google Cloud project, then you have more than the necessary permissions to
    create clusters, install, and then configure Knative serving.

  - Note that the
    [Cloud Service Mesh permissions requirements](https://docs.cloud.google.com/service-mesh/v1.19/docs/installation-permissions.md.txt)
    also meet all the permission requirements for installing and configuring
    Knative serving.

  - Using other roles and the minimum requirements:

    Depending on your organization, you can also meet the permission
    requirements through a combination of the following predefined roles:
    - Google Cloud project permissions: [Basic *Editor* role](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#basic)

    - Fleet permissions:
      [*GKE Hub Admin*](https://docs.cloud.google.com/iam/docs/roles-permissions/gkehub.md.txt)
      or a role that includes the following permissions:

      - `gkehub.features.create`
      - `gkehub.features.update`
    - Cluster permissions:
      [A Kubernetes Engine Admin Role](https://docs.cloud.google.com/iam/docs/roles-permissions/container.md.txt):

      - *Kubernetes Engine Admin*
      - *Kubernetes Engine Cluster Admin*
- Only [specific platforms are supported](https://docs.cloud.google.com/service-mesh/docs/supported-platforms.md.txt).

  - Cloud Service Mesh requires that your cluster use a machine type with
    at least 4 vCPUs, such as `e2-standard-4`. See the Cloud Service Mesh
    installation guide for details about requirements.
    If you need to change your existing cluster's machine type, see
    [Migrating workloads to different machine types](https://docs.cloud.google.com/kubernetes-engine/docs/tutorials/migrating-node-pool).

  - Using [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt) the is recommended environment for
    running the commands and migration script during this process. Note that the
    [Cloud Service Mesh install script](https://docs.cloud.google.com/service-mesh/docs/onboarding/kubernetes-off-gcp/install/install-dependent-tools.md.txt#download_asmcli)
    supports only Linux or Cloud Shell.

  - If your existing installation of Knative serving uses the
    Istio on GKE add-on, you must migrate to the
    [Cloud Service Mesh Managed Control Plane](https://docs.cloud.google.com/service-mesh/docs/managed/supported-features-mcp).
    Migrating from *Istio on GKE add-on* to the
    [Cloud Service Mesh in-cluster control plane](https://docs.cloud.google.com/service-mesh/docs/supported-features-in-cluster.md.txt)
    is not currently supported.

## Upgrading Knative serving and migrating workloads

To assist with upgrading your existing installation of Knative serving and
migrating your workloads, you run a script which automates most steps and
prompts you for input throughout the process.

> [!NOTE]
> **Note:** At each of the following stages, there are options to rollback. There is also a final step for which resources are deleted and rollbacks are no longer possible.
>
>
> **Important**: You must follow each step of this process in the order listed.

1. [Prepare for the upgrade and set up your environment](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade/prepare.md.txt)

2. [Uninstall the GKE addon](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade/uninstall-addon.md.txt)

3. [Migrate to Cloud Service Mesh](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade/migrate-service-mesh.md.txt)

   - [Uninstall the Istio add-on to Cloud Service Mesh](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade/uninstall-istio-addon.md.txt)

   - [Migrate from the bundled Istio to Cloud Service Mesh](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade/install-configure-mesh.md.txt)

   - [Migrate from the Istio add-on to Cloud Service Mesh](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade/install-mesh-mcp.md.txt)

4. [Install the fleet component](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade/fleet-install-script.md.txt)

5. [Migrate workload traffic to Cloud Service Mesh](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade/migrate-traffic.md.txt)

6. [Finalize the upgrade and perform cleanup tasks](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade/finalize.md.txt)