Upgrade Apigee managed instance groups

This page applies to Apigee, but not to Apigee hybrid.

View Apigee Edge documentation.

This document describes how to inspect and upgrade Compute Engine managed instance groups that route northbound traffic to Apigee.

Overview

Some Apigee deployments route proxy traffic from a load balancer through Compute Engine MIGs that run in your project and forward requests to the Apigee runtime endpoint, including northbound load balancing and active health checks with Private Service Connect. Apigee does not manage these MIGs. As a security and reliability best practice, you must track, manage, and upgrade these MIGs and their VMs yourself to stay current with the Compute Engine operating system lifecycle.

When an OS reaches end of life, Compute Engine removes the image family alias for new VMs. Existing VMs in the MIG continue to run and survive live host maintenance events. However, if the MIG attempts to create a new VM during autoscaling, autohealing, or a rolling replacement, VM creation fails because the source image family is no longer found. If healthy proxy VMs become unavailable, the load balancer returns HTTP 502 Bad Gateway errors and API traffic stops.

Before you begin

The commands in this document are examples. Your deployment might use different network tags, machine types, disk sizes, metadata, or VM counts. Inspect your existing configuration first and adjust the command flags to match your environment.

Replace the following placeholders in the example commands with values from your environment:

PROJECT_ID: the Google Cloud project ID where your MIGs and instance templates are deployed.
REGION: the Compute Engine region of your MIG.
EXISTING_MIG_NAME: the name of your existing MIG.
OLD_TEMPLATE_NAME: the name of the instance template attached to EXISTING_MIG_NAME.
NEW_TEMPLATE_NAME: the name of the new instance template that you create.
VPC_NAME: the name of the VPC network used by your MIG.
VPC_SUBNET: the name of the VPC subnet in REGION used by your MIG.
IMAGE_FAMILY: a supported OS image family from the Compute Engine operating system details.
IMAGE_PROJECT: the image project that contains IMAGE_FAMILY.
APIGEE_ENDPOINT: the target IP address configured in the ENDPOINT metadata of your existing instance template.
STARTUP_SCRIPT_URL: the Cloud Storage URL configured in the startup-script-url metadata of your existing instance template.

Inspect your MIGs and instance templates

Apigee routing MIGs typically use the apigee-mig-proxy tag and ENDPOINT metadata. Complete the following steps to inspect your MIGs and instance templates:

List the MIGs in your project and identify the attached instance templates:

gcloud compute instance-groups managed list --project=PROJECT_ID \
  --format="table(name,region.basename(),zone.basename(),instanceTemplate.basename())"

Check the source OS image of your existing instance template. Add --region=REGION if the template is regional:

gcloud compute instance-templates describe OLD_TEMPLATE_NAME \
  --project=PROJECT_ID \
  --format="value(properties.disks[0].initializeParams.sourceImage)"

Inspect the machine type, disk configuration, network, subnet, tags, and metadata of OLD_TEMPLATE_NAME so that you can match these settings when creating the new template. Add --region=REGION if the template is regional:
```
gcloud compute instance-templates describe OLD_TEMPLATE_NAME \
  --project=PROJECT_ID \
  --format="yaml(properties.machineType,properties.disks,properties.networkInterfaces,properties.tags,properties.metadata)"
```

Create a new instance template and execute a rolling update

Create a new instance template with a supported OS image family and start a rolling update on the MIG. Using --max-surge with --max-unavailable=0 provisions and verifies new VMs before draining and removing old instances, which prevents traffic disruption even if new VMs fail to start due to a resource stockout or configuration error.

Create a new instance template. The following command is an example; adjust the network, subnet, tags, machine type, disk size, and metadata to match your existing template configuration:
```
gcloud compute instance-templates create NEW_TEMPLATE_NAME \
  --project=PROJECT_ID \
  --region=REGION \
  --network=VPC_NAME \
  --subnet=VPC_SUBNET \
  --tags=https-server,apigee-mig-proxy,gke-apigee-proxy \
  --machine-type=e2-medium \
  --image-family=IMAGE_FAMILY \
  --image-project=IMAGE_PROJECT \
  --boot-disk-size=20GB \
  --no-address \
  --metadata=ENDPOINT=APIGEE_ENDPOINT,startup-script-url=STARTUP_SCRIPT_URL
```
This command creates a global instance template at projects/PROJECT_ID/global/instanceTemplates/NEW_TEMPLATE_NAME. If you prefer to create a regional instance template, add --instance-template-region=REGION and use projects/PROJECT_ID/regions/REGION/instanceTemplates/NEW_TEMPLATE_NAME in the next step.

Start a rolling update on the MIG. Adjust --max-surge if needed based on the size and quota of your MIG:

gcloud compute instance-groups managed rolling-action start-update EXISTING_MIG_NAME \
  --project=PROJECT_ID \
  --region=REGION \
  --version=template=projects/PROJECT_ID/global/instanceTemplates/NEW_TEMPLATE_NAME \
  --max-surge=3 \
  --max-unavailable=0

Verify that all VMs in the MIG run NEW_TEMPLATE_NAME and report a RUNNING status:

gcloud compute instance-groups managed list-instances EXISTING_MIG_NAME \
  --project=PROJECT_ID \
  --region=REGION