Prepare to upgrade your previous installation of Knative serving and migrate
your workloads by setting up your command-line environment, creating environment
variables, and downloading the migration script.

## Before you begin

- You must first review and ensure that you meet the
  [requirements](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade.md.txt) before upgrading.

- By default, Cloud Shell includes the latest versions of the `gcloud` and
  `kubectl` commands. If you choose to use the command-line environment of your
  local machine, you must ensure that you meet the following minimum
  requirements:

  - `gcloud` version 346.0.0 or newer
  - `kubectl` client version 1.21 or newer

  [Learn more about setting up your command-line tools](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/command-line-tools.md.txt)
- The preparation steps on this page are required throughout the
  [upgrade and migration process](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/install/on-gcp/upgrade.md.txt).

  **Important**: All the commands that are used during the process rely on the
  environment variables that you set below. For example, if you close
  Cloud Shell or your session timesout, you must ensure that the required
  environment variables are reset.

## Setup your environment

1. To use Cloud Shell, open Cloud Shell in the Google Cloud console:

   [Activate Cloud Shell](https://console.cloud.google.com/kubernetes/run?cloudshell=true%22)

   **Important** : Cloud Shell has
   [usage limits](https://docs.cloud.google.com/shell/docs/limitations#usage_limits) and can timeout. If your
   session timesout, you must ensure that the required environment variables
   are reset.
2. Create the following required environment variables:

   1. Set variables for your Google Cloud project and cluster details:

      ```bash
      export PROJECT_ID=PROJECT_ID
      export CLUSTER_NAME=CLUSTER_NAME
      export CLUSTER_LOCATION=CLUSTER_LOCATION
      ```

      Replace the following:
      - <var translate="no">PROJECT_ID</var> with the ID of your Google Cloud project.
      - <var translate="no">CLUSTER_NAME</var> with the ID of your cluster or the fully qualified identifier for the cluster.
      - <var translate="no">CLUSTER_LOCATION</var> with the [region or zone](https://docs.cloud.google.com/compute/docs/regions-zones.md.txt#available) in which your cluster is located.
   2. Depending on your configuration, you must identify the ingress gateway
      that is handling traffic in your cluster. It is important to identify
      which version of Istio is actually configured and serving traffic.

      - If you use the bundled version of Istio, verify that the ingress
        service name is `istio-ingress` in the `gke-system` namespace:

        ```bash
        kubectl get svc istio-ingress -n gke-system
        ```

        Result: The details of your configuration are returned.
      - If you installed the
        "*Istio add-on*", you must
        determine which ingress gateway is configured and actively handling
        traffic by obtaining the IP addresses of the services and identifying
        which one is configured to your domain.

        1. Obtain the `EXTERNAL-IP` address for each ingress service:

           Run the following commands to obtain the configuration details of
           both the "bundled version of Istio" (`istio-ingress`) and
           "Istio add-on" (`istio-ingressgateway`) ingress services:

           ```bash
           kubectl get svc istio-ingress -n gke-system
           kubectl get svc istio-ingressgateway -n istio-system
           ```

           **Example output**:

           Note the value of `EXTERNAL-IP` for each service.

           ```bash
            NAME                 TYPE         CLUSTER-IP  EXTERNAL-IP    PORT(S)                                     AGE
            istio-ingress        LoadBalancer 11.11.1.111 12.345.678.910 15020:31265/TCP,80:30059/TCP,443:32004/TCP  8d

            NAME                 TYPE         CLUSTER-IP  EXTERNAL-IP    PORT(S)                                                                     AGE
            istio-ingressgateway LoadBalancer 22.22.2.222 10.987.654.321 15021:32747/TCP,80:30695/TCP,443:32695/TCP,15012:32369/TCP,15443:30909/TCP  88d
           ```
        2. Identify which external IP address is configured to handle
           traffic through the DNS record of your custom domain:

           1. Go to the Knative serving domain mappings page:

              [Go to Domain mappings](https://console.cloud.google.com/kubernetes/run/domains)
           2. Click the 3-dot vertical ellipse icon to the right of your
              service, then click **DNS RECORDS** to display all the DNS
              records:

              ![select DNS records](https://docs.cloud.google.com/static/kubernetes-engine/enterprise/knative-serving/docs/images/select-dns.png)

              Using the example above, the *Istio add-on* ingress gateway is
              in use and serving traffic if the DNS record configuration is
              set to the `10.987.654.321` IP address of the
              `istio-ingressgateway` service.
   3. Set variables for the name and namespace of the ingress service that is
      serving traffic for your cluster:

      ```bash
      export INGRESS_NAME=INGRESS_NAME
      export INGRESS_NAMESPACE=INGRESS_NAMESPACE
      ```

      Replace the following:
      - <var translate="no">INGRESS_NAME</var> with the name of the ingress service that
        you identified in the previous step.

      - <var translate="no">INGRESS_NAMESPACE</var> with the namespace of the ingress
        service that you identified in the previous step.

3. Configure the Google Cloud CLI:

   ```bash
   gcloud config set project ${PROJECT_ID}
   gcloud container clusters get-credentials ${CLUSTER_NAME} --region ${CLUSTER_LOCATION}
   ```
4. For private clusters:

   - If you already have access to your private cluster from the client where
     you will run the migration script, you can skip to the
     next step.

   - If your private cluster has `master-authorized-network` enabled, you can
     enable access from the client where you will run the migration script by
     adding the client's IP address to the `master-authorized-networks`
     allowlist:

     ```bash
     gcloud container clusters update ${CLUSTER_NAME} \
         --region=${CLUSTER_LOCATION} \
         --enable-master-authorized-networks \
         --master-authorized-networks $(curl ifconfig.me)/32
     ```
5. Download the Knative serving migration script:

   ```bash
   TMP_DIR=$(mktemp -d)
   gcloud storage cp gs://crfa-to-hub-upgrade/migration-addon.sh $TMP_DIR
   cd $TMP_DIR
   chmod +x ./migration-addon.sh
   ```
6. Run the following command to disable "scaling to zero", otherwise
   scaling will fail and cause errors when the master node gets updated:

   ```bash
   kubectl patch cm config-autoscaler -n knative-serving -p '{"data":{"enable-scale-to-zero": "false"}}'
   ```

   Note that the final step in this upgrade and migration process is to
   re-enable "scaling to zero".

## What's next

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