Google Cloud has deprecated the container startup agent in Compute Engine, which currently allows you to deploy containers directly on Compute Engine instances during VM creation. This change affects any workloads using the “Deploy container” option in the console, specific gcloud commands, or Terraform configurations that leverage the gce-container-declaration metadata key.
Critical Timeline and Deadlines
July 31, 2026: All workflows relying on the container startup agent or gce-container-declaration metadata will stop working. You will no longer be able to create new VMs or MIGs with containers using this method.
July 31, 2027: Google will discontinue support entirely. Any running VMs still using gce-container-declaration metadata will operate at your own risk with no updates or security patches.
Action Required
You must migrate affected workloads to alternative solutions before July 31, 2026, to ensure continued operation and access to future updates and security patches. We strongly recommend completing migration well before these deadlines to ensure a smooth transition.
What’s Changing?
The deprecated container startup agent encompasses several deployment methods:
Console Interface
- The “Deploy container” option on the Create an instance page
Command Line Tools
- gcloud compute instances create-with-container
- gcloud compute instances update-container
- gcloud compute instance-templates create-with-container
- Commands using –metadata with gce-container-declaration
Infrastructure as Code
- Terraform gce-container module
- Any configuration using the gce-container-declaration metadata key
Important Note: This deprecation does NOT affect VMs configured using cloud-init. You can continue using cloud-init for instance configuration.
Impact Assessment
How to Check if You’re Affected
Project-wide check:
- gcloud compute instances list –filter=“metadata.items.key:gce-container-declaration”
Individual instance check:
- gcloud compute instances describe VM_NAME
If these commands return instances with the gce-container-declaration metadata key, those workloads require migration. Run this check across all your active projects if you manage multiple projects.
Migration Options
Choose a migration path based on your specific requirements:
Option 1: Continue with VMs (Direct Replacement)
Best for: Workloads requiring VM-level control, specific OS configurations, privileged access, or single VM deployments
Solutions:
- Startup Scripts
- cloud-init configuration
Benefits:
- Minimal changes to existing architecture
- Maintains VM-level control
- Suitable for testing and development environments
Cost Impact: No additional cost beyond existing VM expenses Effort: Low to moderate
Timeline: Can be implemented immediately Migration Time: 1-2 hours for initial setup, minutes for subsequent deployments
Option 2: Cloud Run (Recommended for Most Web Applications)
Best for: Stateless container applications, web services, and small to medium jobs
Benefits:
- Fully managed with automatic scaling
- Pay-per-request pricing model (no idle costs)
- Built-in load balancing and HTTPS
- Free tier available
- Reduced management overhead
Cost Impact: Often more cost-effective for variable workloads due to pay-per-use model Timeline: Usually straightforward migration Effort: Moderate (may require application changes for stateless operation)
Option 3: Batch (For Batch Processing)
Best for: Batch jobs with definite end states requiring additional computing resources
Benefits:
- Optimized for batch processing workflows
- Automatic resource management
- Free tier available
- No costs when not running jobs
Cost Impact: More efficient resource utilization for batch workloads Timeline: Depends on batch job complexity
Option 4: Google Kubernetes Engine (GKE)
Best for: Complex applications requiring advanced control, scalability, or microservices architecture
Benefits:
- Full Kubernetes capabilities
- Advanced orchestration and scaling
- Free tier available for smaller workloads
- Excellent for microservices architectures
Cost Impact: Additional management services but better cost control for complex deployments Effort: Higher (requires Kubernetes knowledge)
Container-Optimized OS Clarification
Important: Container-Optimized OS images are NOT being deprecated. Only the konlet startup agent that processes the gce-container-declaration metadata is being removed. You can continue using Container-Optimized OS images with startup scripts or cloud-init for container deployment.
Migration Process Recommendations
-
- Understand Your Options: Review the complete migration guide and evaluate which solution best fits your needs
- Plan Early: Start migration planning well before July 31, 2026
- Test Thoroughly: Set up new configurations alongside existing ones and test before switching traffic
- Zero-Downtime Migration: For long-running containers, deploy new VMs with alternative configurations and switch traffic after testing
- Update Automation: Modify Terraform and other Infrastructure as Code configurations to remove gce-container-declaration dependencies
Terraform Impact
If you’re using Terraform with the gce-container-declaration metadata key, your workflows will stop working on July 31, 2026. Update your Terraform configurations to:
- Remove the gce-container-declaration metadata dependency
- Include startup scripts for container deployment
- Test the new configuration before the deadline
Cost Considerations
Startup Scripts/cloud-init: No additional cost beyond existing VM expenses
Cloud Run: Potentially lower costs for variable workloads due to pay-per-request model and no idle charges
Batch: More efficient resource utilization for appropriate workloads with no idle costs
GKE: Additional management services but better cost control for complex applications, plus free tier availability
Use the Google Cloud Pricing Calculator for accurate cost estimates based on your specific configuration.
Security and Privacy
There are no additional security or privacy risks during migration. Google Cloud’s managed services provide flexible security and privacy configuration options to meet your requirements.
Getting Support
- Review the official migration guide
- Reach out to us via email on [email protected] in case you need any assistance with this.
Next Steps
- Immediate: Run the impact assessment commands to identify affected workloads
- Within 30 days: Choose your migration strategy based on workload requirements
- Within 90 days: Begin implementing and testing your chosen solution
- Before July 2026: Complete migration and update all automation scripts
Don’t wait until the deadline approaches. Start your migration planning now to ensure a smooth transition and take advantage of the enhanced capabilities offered by Google Cloud’s alternative container deployment solutions.