Deploy on Google Kubernetes Engine

Use this path when you run migrations on Google Cloud Platform (GCP). You receive the same Migration Assistant engine, workflow model, and console experience as every other path. Google Kubernetes Engine (GKE) is the recommended production path on GCP because a Terraform module prepares the GCP platform pieces that a real migration needs: the cluster, networking, snapshot storage, and workload identity.

GKE makes the migration easier to deploy, easier to secure, and easier to operate without changing how migrations run.

GKE deployment components

The Terraform module prepares GCP infrastructure around the workflow engine, including:

• A GKE Standard cluster deployed into a new or existing virtual private cloud (VPC).
• Private nodes with Cloud NAT for outbound access.
• Workload Identity so migration pods can authenticate to GCP services without long-lived keys.
• A Cloud Storage bucket for snapshots, with the node service account granted access to it.
• Secondary IP ranges for GKE pods and services, and configurable control-plane access.

Prerequisites

Before you begin, make sure you have the following:

• A GCP project with billing enabled.
• Terraform 1.6 or later, or OpenTofu 1.6 or later.
• The gcloud CLI, authenticated with gcloud auth application-default login.
• kubectl and Helm 3 installed.
• The required GCP APIs enabled:

gcloud services enable container.googleapis.com storage.googleapis.com

Step 1: Provision the cluster with Terraform

The Terraform module is published in the opensearch-migrations repository under deployment/terraform/gcp. Clone the release tag you want to deploy.

The most common variables are described in the following table. Check the module’s variables.tf for the complete list.

Optional: Keep migration traffic private

If your migration must not traverse the public internet, configure private networking before you apply, because the connectivity options are set through the same Terraform variables used in this step. You can make the source, target, snapshot, and control-plane legs private independently. Go to Private networking on GKE, add the connectivity variables you need, and then return here to apply.

Apply the configuration

Provision the cluster by planning and applying the module:

terraform apply \
  -var="project=<your-gcp-project>" \
  -var="region=<your-gcp-region>"

The module provisions a GKE Standard cluster.

Step 2: Get cluster credentials

The cluster name is generated by Terraform. Fetch credentials with the following command:

gcloud container clusters get-credentials $(terraform output -raw cluster_name) \
  --region $(terraform output -raw cluster_location) \
  --project <your-gcp-project>

Step 3: Install the Migration Assistant Helm chart

Install the chart using the GKE values file, which sets cloudProvider: gcp and wires the GCP-specific snapshot storage and identity settings:

helm install migration-assistant \
  charts/aggregates/migrationAssistantWithArgo \
  --values charts/aggregates/migrationAssistantWithArgo/valuesGke.yaml \
  --set gcp.project=<your-gcp-project>

Step 4: Verify the deployment

Verify that the platform pods are running:

kubectl get pods -n ma

You should see the Migration Console, the Argo workflow controller, and the Argo server in Running state.

Step 5: Access the Migration Console

Access the Migration Console:

kubectl exec -it migration-console-0 -n ma -- /bin/bash

After you access the console, the migration flow is the same as any other deployment: verify the version, load the sample configuration, run a pilot migration, validate it, and then run the full migration.

GCP helpers the deployment created for you

The GKE path provisions a Cloud Storage bucket and configures identity so you do not have to build them manually.

Snapshot bucket

Terraform creates a Cloud Storage bucket for migration snapshots and generates a unique name for it. The Helm chart exposes the bucket to workflows through the migrations-default-gcs-config config map. By default, the migration workflow creates a fresh snapshot in this bucket as its first step.

If you already have a snapshot in the bucket, you can configure the workflow to reuse it instead of creating a new one. For the workflow configuration, see Using an existing snapshot. For best performance, keep the bucket in the same region as the GKE cluster; cross-region reads work but are slower and incur egress charges.

Workload Identity

The module binds the Kubernetes service accounts that run migrations (the Migration Console and the Argo workflow executor) to a GCP service account through Workload Identity. This means the console and the migration jobs can reach Cloud Storage and other GCP services without you distributing long-lived credentials. This is one of the main reasons GKE is the recommended GCP production path.

Authentication on GKE

Migration Assistant supports the following authentication methods on GKE.

Basic authentication

Basic authentication works the same way as every other path: create Kubernetes secrets and reference them in authConfig.basic.secretName.

Workload Identity for GCP services

For access to GCP services such as Cloud Storage, the GKE path uses Workload Identity to assign a GCP identity to the Migration Console pod and the Argo workflow executor pods. The Terraform module configures these bindings for you.

Removal

Once you no longer need Migration Assistant for rollback, replay, or comparison, remove it. Do not remove it immediately after cutover. For the readiness checklist, see Removing migration infrastructure.

To remove Migration Assistant from GKE, uninstall the Helm release and then destroy the Terraform-managed infrastructure:

helm uninstall migration-assistant -n ma
kubectl -n ma delete pvc --all
terraform destroy \
  -var="project=<your-gcp-project>" \
  -var="region=<your-gcp-region>"

Next steps

1. Open the Migration Console and run console --version.
2. Load the sample workflow with workflow configure sample --load.
3. Run console clusters connection-check.
4. Continue with Using the Workflow CLI.