SFTP Gateway Support

3.0

Migrating from Compute Engine to Container Deployment

This guide walks you through migrating your SFTP Gateway deployment from a Compute Engine VM to a containerized deployment on Google Cloud. Whether you're modernizing your infrastructure, preparing for auto-scaling requirements, or standardizing on container-based deployments across your organization, this guide will help you complete the migration while preserving your existing users, folders, and configuration.

Prerequisite: This guide assumes you have already deployed SFTP Gateway as a container. If you haven't set up your container environment yet, see Deploying SFTP Gateway on GKE first, then return to this guide to migrate your configuration.

Overview

Many organizations are moving from traditional VM-based deployments to containers as part of their cloud modernization strategy. Container deployments offer several advantages over traditional Compute Engine VMs:

  • Easier scaling: Containers can be spun up or down in seconds, allowing you to respond quickly to changes in demand.

  • Improved portability: A containerized SFTP Gateway runs the same way regardless of the underlying environment. This consistency makes it easier to replicate your setup across development, staging, and production environments.

  • Reduced operational overhead: One of the top drivers for container adoption is eliminating the burden of VM patching. Containers have a significantly smaller software footprint than full VMs—you're not responsible for kernel updates, OS patches, or system-level security fixes.

  • Cost efficiency: If you're already running GKE or Cloud Run, adding another container to your existing infrastructure has minimal marginal cost. A dedicated VM, by contrast, requires its own compute resources that often sit underutilized.

The migration is straightforward: export your configuration from the Compute Engine VM and import it into the new container deployment. The process is designed to minimize downtime—most of the work happens in parallel with your existing deployment, and the actual cutover takes only a few minutes.

Prerequisites

Before beginning the migration, ensure you have the following:

  • A running SFTP Gateway container deployment — Follow the GKE deployment guide to set up your container environment first.

  • Administrative access to your existing SFTP Gateway Compute Engine VM — You'll need access to the Web Admin interface to export the configuration.

  • gcloud CLI configured with appropriate permissions — The CLI should be configured with credentials that have access to your GCP project for the cutover steps.

  • Understanding of your current network configuration — Document your VPC, subnets, firewall rules, and any static IPs or DNS hostnames associated with your current deployment.

Migration Process

The migration process consists of two phases: preparation (Steps 1-3) and cutover (Steps 4-5). The preparation phase can be done without any impact to your existing deployment. Only the cutover phase requires a brief maintenance window.

Phase 1: Preparation

The first phase focuses on capturing everything you need from your existing Compute Engine deployment. This includes your SFTP Gateway configuration and network settings. Taking the time to thoroughly document your current setup will make troubleshooting easier if any issues arise during or after the migration.

Step 1: Export Configuration from Compute Engine VM

Your SFTP Gateway configuration includes users, folders, permissions, and system settings. SFTP Gateway provides a built-in backup mechanism that exports all of this into a portable YAML file. This file is the key to migrating your setup—it contains everything the new container deployment needs to recreate your current configuration.

The easiest way to export your configuration is through the Web Admin interface:

  1. Log into your SFTP Gateway Web Admin interface
  2. Navigate to Settings > Backup & Recovery
  3. Click Export Backup File
  4. Save the downloaded .yml file securely

Store this backup file securely—you'll need it in Step 3, and it also serves as a disaster recovery backup for your current deployment.

Step 2: Document Current Network Configuration

Before making any changes, document your current network configuration. This serves two purposes: it provides a reference for configuring the new deployment, and it gives you the information you need to quickly roll back if something goes wrong.

The following commands capture the key network details:

# Note your current static IP (if applicable)
gcloud compute addresses list --filter="status=IN_USE" --format="table(name, address, region, users)"

# Note firewall rules for your VM
gcloud compute firewall-rules list --filter="network:your-network-name" --format="yaml" > firewall-backup.yaml

# Note your VPC and subnet configuration
gcloud compute instances describe your-vm-name --zone=your-zone \
  --format="table(networkInterfaces[0].network, networkInterfaces[0].subnetwork)"

Save this information somewhere accessible. You'll reference it during the cutover phase, and it provides the details needed for a quick rollback if necessary.

Step 3: Import Configuration to Container

Now it's time to bring your SFTP Gateway configuration into the container deployment. The import process is straightforward and uses the same backup file you created in Step 1.

  1. Access the Web Admin interface of your container deployment (via the Load Balancer IP or however your container environment is exposed)
  2. Navigate to Settings > Backup & Recovery
  3. Click Import Backup File
  4. Upload the .yml backup file from Step 1
  5. Review the import summary to verify all users and folders were imported successfully

After the import completes, the container deployment will have the same users, folders, permissions, and SSH host keys as your Compute Engine VM.

Phase 2: Cutover

With your container environment running and your configuration imported, you're ready for the cutover. This phase involves switching traffic from the old Compute Engine VM to the new container and verifying everything works. Plan for a brief maintenance window during the actual cutover (typically 5-15 minutes).

Step 4: Perform Cutover

This is the moment of truth. You'll redirect traffic from your Compute Engine VM to the container deployment. The method depends on how your users currently connect.

4a. Update DNS or Static IP

Option A: DNS Cutover (Recommended)

If users connect via a DNS hostname (e.g., sftp.yourcompany.com), update the DNS record to point to the container service's load balancer. This approach provides the most flexibility and allows for easy rollback.

Important: About 24 hours before your planned cutover, reduce the TTL on your DNS record to the lowest value your provider allows (e.g., 60 seconds). This ensures the cutover propagates quickly across the internet, and makes rollbacks faster if needed. After the migration is stable, you can increase the TTL back to a normal value.

# Get the Load Balancer external IP for your GKE service
kubectl get svc sftp-gateway-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

Update your DNS provider (Cloud DNS, Cloudflare, etc.) to point your SFTP hostname to the load balancer IP.

Option B: Static IP Reassociation

If users connect directly to a static external IP address, you can reassign that IP to the container service's load balancer.

# Remove static IP from VM
gcloud compute instances delete-access-config your-vm-name \
  --zone=your-zone \
  --access-config-name="external-nat"

# The static IP can then be assigned to the GKE load balancer
# This requires configuring the GKE service with the specific static IP

This approach provides instant cutover with no DNS propagation delay, but requires more complex GKE configuration.

4b. Verify Connectivity

Before declaring the migration complete, verify that everything is working:

# Test SFTP connectivity
sftp testuser@your-new-endpoint

# Test Web Admin access
curl -k https://your-new-endpoint/admin

Have a few users test file uploads and downloads to verify end-to-end functionality. Check container logs for any errors:

kubectl logs -f deployment/sftp-gateway

Step 5: Decommission Compute Engine VM

Once you've verified the container deployment is working correctly, you can begin decommissioning the Compute Engine VM. However, don't rush this step—keeping the old VM available for a few days provides a safety net in case issues emerge.

Recommended decommissioning timeline:

  1. Immediately after cutover: Keep the Compute Engine VM running but no longer receiving traffic. This allows instant rollback if critical issues emerge.

  2. After 24-48 hours: If no issues have been reported, stop the Compute Engine VM. Stopping eliminates compute costs while preserving the ability to restart if needed.

  3. After 1-2 weeks: If the container deployment has been stable, delete the Compute Engine VM and any associated resources (persistent disks, snapshots, etc.) that are no longer needed.

# Stop VM (preserves disk, stops compute billing)
gcloud compute instances stop your-vm-name --zone=your-zone

# Later, when ready to fully decommission
gcloud compute instances delete your-vm-name --zone=your-zone

Rollback Procedure

Despite careful planning, sometimes things don't go as expected. If you encounter critical issues with the container deployment that can't be quickly resolved, here's how to roll back to the Compute Engine VM.

The key is that your Compute Engine VM should still be available (either running or stopped) during the initial post-migration period. Rolling back is essentially the reverse of the cutover process:

  1. If using DNS: Update your DNS record to point back to the Compute Engine VM's IP address.

  2. If using Static IP: Re-associate the static IP with the Compute Engine VM:

    gcloud compute instances add-access-config your-vm-name \
  --zone=your-zone \
  --access-config-name="external-nat" \
  --address=your-static-ip

  3. If the Compute Engine VM is stopped: Start it first:

    gcloud compute instances start your-vm-name --zone=your-zone

  4. Verify the rollback: Test SFTP connectivity and Web Admin access to confirm the Compute Engine VM is serving traffic correctly.

Once rolled back, investigate the issues with the container deployment before attempting the migration again. Common causes include network configuration problems, service account permission issues, or persistent storage mount failures.

Post-Migration Checklist

After completing the migration, work through this checklist to ensure everything is properly configured for production use:

  • All users can authenticate successfully — Test with a sample of user accounts, including both password and key-based authentication if applicable.

  • File uploads and downloads work correctly — Verify files appear in the expected Cloud Storage location and can be retrieved.

  • Cloud Storage integration is functioning — Check that new files uploaded via SFTP appear in Cloud Storage, and that files added to Cloud Storage are accessible via SFTP.

  • Web Admin is accessible — Verify you can log in and perform administrative tasks.

  • SSL/TLS certificates are properly configured — Check that HTTPS connections use valid certificates.

  • Monitoring and alerting is configured — Set up Cloud Monitoring alerts for container health, CPU/memory usage, and error rates.

  • Backup automation is set up for container deployment — Configure regular exports of the SFTP Gateway configuration.

  • Documentation is updated with new architecture — Update runbooks, architecture diagrams, and any relevant documentation to reflect the container deployment.

Troubleshooting

Even with careful preparation, you may encounter issues during or after the migration. This section covers the most common migration-related problems. For infrastructure issues (container won't start, persistent volume failures, etc.), refer to the GKE deployment guide.

SSH Host Key Warning

Symptom: Users see a message like "WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!" when connecting.

Cause: The container is using different SSH host keys than the original Compute Engine VM.

Solution:

  1. Verify the backup was imported correctly in Step 3 (the backup includes SSH host keys)
  2. Check that the key files exist: ls -la /opt/sftpgw/ssh_host_*
  3. Verify ownership is correct for the container user (typically UID 1000)
  4. Restart the container to reload the keys

Users Cannot Authenticate

Symptom: Users who worked on the Compute Engine VM cannot log in after migration.

Cause: The configuration import may not have completed successfully, or there may be a mismatch in authentication settings.

Solution:

  1. Verify the import completed successfully in Settings > Backup & Recovery
  2. Check that the user exists in Users in the Web Admin
  3. For key-based authentication, verify the user's public key was imported correctly
  4. Check container logs for authentication errors

Cloud Storage Access Issues After Migration

Symptom: Users can authenticate but cannot access files, or files uploaded via SFTP don't appear in Cloud Storage.

Cause: The container's service account may not have access to the same bucket, or bucket permissions may differ.

Solution:

  1. Verify the container's service account has the "Storage Object Admin" role on the bucket
  2. Ensure the bucket name in the container environment matches your original configuration
  3. Check that any bucket IAM policies allow access from the container's service account

Related Articles

For more information on specific topics covered in this guide, see these related articles:

Support

If you encounter issues during migration that aren't covered in this guide, contact support at support@thorntech.com. To help us assist you quickly, please include:

  • A detailed description of the problem, including when it started and any error messages
  • The steps you've already tried to resolve the issue
← PreviousNext →