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.
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:
- Install Knative serving as a fleet component.
Deploy your services to the new installation.
For example, you can use the instructions for deploying a revision of an existing service 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:
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 SERVICE with the name of your Knative serving service.
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:
CLUSTER_NAME with the name of the cluster in your new fleet component installation of Knative serving.
CLUSTER_LOCATION with the zone or region of the cluster in your new fleet component installation of Knative serving.
PROJECT_ID 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".
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:
gcloud container clusters describe \ CLUSTER_NAME \ --region CLUSTER_LOCATION \ --project PROJECT_ID --format='get(addonsConfig.cloudRunConfig)'
Replace:
- CLUSTER_NAME with the name of your cluster.
- CLUSTER_LOCATION with the location where your cluster is located.
- PROJECT_ID 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:gcloud container clusters describe my-addon-cluster \ --region us-central1-c --project my-gcp-project \ --format='get(addonsConfig.cloudRunConfig)'
Response:
loadBalancerType=LOAD_BALANCER_TYPE_EXTERNAL
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 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 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
Fleet permissions: GKE Hub Admin or a role that includes the following permissions:
gkehub.features.create
gkehub.features.update
Cluster permissions: A Kubernetes Engine Admin Role:
- Kubernetes Engine Admin
- Kubernetes Engine Cluster Admin
Only Cloud Service Mesh version 1.18 is supported.
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.Using Cloud Shell the is recommended environment for running the commands and migration script during this process. Note that the Cloud Service Mesh install script 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. Migrating from Istio on GKE add-on to the Cloud Service Mesh in-cluster control plane 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.