Thecontainer startup agent that deploys containers on Compute Engineinstances during VM creation is deprecated.

This document describes how to plan the migration of containers that you createdduring VM creation to other Google Cloud services.

General information

What is a container startup agent in Compute Engine?

The container startup agent lets youdeploy and configure containers on Compute Engineinstances or on instances in a managed instance group (MIG) during VM creationand launches a Docker container.

Why is the container startup agent deprecated?

Based on customer feedback, Google Cloud enhances container deployment options.We have deprecated the container startup agent to enable us to provide you with moreflexible options for deploying your containers.

For more information about the options that are deprecated, seeDeprecated options for configuring containers on VMs.

What are the key milestones for this deprecation and what happens if I fail to take action by the deadline?

StartingJuly 31, 2026, any workflows that rely on the container startup agentor thegce-container-declaration instance metadata will stop working.

StartingJuly 31, 2027, Google will discontinue support for the container startup agent andno further updates will be provided for any running VMs that use thegce-container-declaration metadata. You will be running the workloads at yourown risk and it can affect your workflow.

We recommend that youmigrate containers to alternative solutions well beforethese dates to ensure a smooth transition.

When will I no longer be able to create new VMs or MIGs with containers deployed directly using thegce-container-declaration metadata?

12 months from the initial deprecation notification, which isJuly 31, 2026.

When will I no longer be able to run container deployments on VMs or MIGs that use thegce-container-declaration metadata?

We will stop supporting any workloads deployed using container startup agent24 months from the initial deprecation notification, which isJuly 31, 2027.

How does this deprecation impact my Terraform configuration?

If you use Terraform or similar automation to create or update VMs or MIGs byexplicitly setting thegce-container-declaration metadata key, yourworkflow will stop working onJuly 31, 2026. To avoid disruption,update your Terraform configuration to use a startup script for containerdeployment and remove the dependency on thegce-container-declarationmetadata key. For detailed instructions, see themigration guide.

Does this deprecation mean that Container-Optimized OS images will be deprecated?

No, Container-Optimized OS images are not being deprecated. The change is abouthow containers are deployed on VMs that use Container-Optimized OS.Newer versions of Container-Optimized OS will no longer supportkonlet, the startup agent that uses thegce-container-declaration metadata key to deploy containers. Container-Optimized OS images continue to be available and supported.However, you must update your VM configuration to use a startup script orcloud-initto deploy containers instead of relying on thegce-container-declaration metadata key.

I usecloud-init to run containers on VMs. Am I impacted by this change?

No. This deprecation does not impact VMs that are configured usingcloud-init.You can continue to usecloud-init for configuring instances. For more information,seeUsing cloud-init with Cloud config.

How do I know if I am impacted by this change?

If you are deploying a container on a VM during VM creation using thecontainer startup agent or by specifying thegce-container-declaration, youare impacted by this deprecation.To validate if there are any instances impacted inyour project, run thefollowing gcloud CLI command:

gcloudcomputeinstanceslist--filter="metadata.items.key:gce-container-declaration"

This command provides a list of all VM instances in your project that containthegce-container-declaration metadata key. The metadata key uniquely identifiesVMs that are in scope of the deprecation. If you are using multiple projects,then run the command across all of the active projects.

For more information about viewing project metadata, seemetadata documentation.

If you have aspecific instance that you want to check,then run the following gcloud CLI command:

gcloudcomputeinstancesdescribeVM_NAME

ReplaceVM_NAME with the name of the VM instance.This command provides all the information for a given instance, includingthe metadata. If you see thegce-container-declaration metadata key in thecommand output, then your VM is impacted by this change.

Note: Ensure that you validate and select the right zone when running the command.

Is there any risk to project security or privacy during the migration?

No. Security and privacy are foundational to everything we do at Google.When using our scripts or managed solutions, you have the flexibility to configurespecific security and privacy settings to meet your requirements.For more information, see themigration guide.

Alternative solutions

What are the recommended alternative solutions to containers on Compute Engine, and how do I choose the right one for my requirements?

You can choose one of the following options to migrate your container:

• If you want to continue deploying containers on VMs or MIGs, or run containers for testingand development, or run a workload that consists of a single VM,then usestartupscripts orcloud-init.
• If you have stateless container applications and small to medium jobs,consider Cloud Run. You can also usestartupscripts.
• If your container is a batch job that has a definite end state and requiresadditional computing resources, consider Batch. You can alsousestartupscripts.
• If you need advanced control and scalability or you cannot meet yourrequirements with the other options, considerGKE.

For detailed guidance and recommendations on migration options,read themigration guide.

Why should I consider migrating to a managed service such as Cloud Run, GKE or Batch versus using a startup script?

We recommend that you consider migrating to container solutions such asGoogle Kubernetes Engine, Cloud Run, and Batch. These managed servicesoffer significant advantages over conventional VM-based deployments, includingenhanced scalability, flexibility, and advanced management capabilities.

Key benefits include the following:

• Reduce management overhead: As fully managed services,Google Cloudhandles the underlying infrastructure (VMs, patching, scaling).This approach frees up valuable staff time and reduces your operational burden.
• Automatically scale and ensure elasticity: These servicesautomatically adjust resources based on demand. This leads to betterresource utilization and potential cost savings compared toover-provisioning VMs.
• Achieve cost efficiency for idle loads: Unlike VMs, which incur costseven when idle, managed services can be more cost-effective forapplications with fluctuating or low traffic.
• Utilize free tier availability: GKE,Cloud Run, and Batch offer a freetier, allowing you to run smaller workloads or conduct testing atpotentially no cost.

For detailed guidance on migration, see themigration guide.

What are the cost considerations for each alternative solution, and how do they compare to the current setup?

Container deployment startup scripts or cloud-init: Usingstartup scripts orcloud-init as a direct replacement does not inherently change yourCompute Engine costs. You still pay for the underlying VM resources.

Managed services: Moving to services such as Cloud Runor Batch can offer cost savings, especially for applications withvariable usage. Unlike VMs that charge even when idle, these managed servicescan be more efficient. Additionally, free tiers can further reduce costs forsmaller, temporary workloads.

For more information, seeCompare the container deployment options.Pricing varies based on the chosen service and your specificconfiguration. Use thepricingcalculator for an accurateestimate.

Does this deprecation mean that Container-Optimized OS images will be deprecated and so if we want to run Dockers on Compute Engine VMs, we'll need to configure our own VM template?

No, Container-Optimized OS images themselves are not beingdeprecated. The change is about how containers start on VMs usingContainer-Optimized OS. Newer Container-Optimized OS versionswill no longer supportkonlet, which is the startup agentthat starts containers using thegce-container-declaration metadata key.This means Container-Optimized OS images will still be available andsupported. However, you must update your VM to use a startup script orcloud-initconfiguration to deploy containers instead of using thegce-container-declaration metadata key.

Migration Process

What is the recommended approach for migrating containers to the alternative solutions?

We recommend that you take the following steps toward your migration:

• Understand your options: Review themigrationguide to explore alternativeways to run your containers.
• Plan your migration early: To ensure a smooth transition, start planningthe migration of your current container deployments well beforeJuly 31,2026.
• Prepare for new workloads: Ensure that your new container workloads are readyto run on alternative solutions byJuly 31, 2026, as direct deploymentof containers to VMs or MIGs will no longer be possible.
• Final migration deadline: Ensure that all your existing container workloadsare migrated to alternative solutions byJuly 31, 2027, when the directdeployment method will be fully retired.

Am I required to migrate to one of the recommended solutions or are there alternatives that I can use?

We support your flexibility to adopt any solution that aligns with yourbusiness needs and is actively supported. Resources such as themigration guide are availableto help you choose the most suitable option.

Is data backup or export required as part of the migration process?

While performing a data backup or export is always a critical best practicefor data safety and business continuity, it is not a necessary step for this migration process.

How much time will it take me to migrate to one of the alternatives, and are there factors that could affect my time commitment?

Container deployment startup script:Initial setup and testing using startup scripts should take around 1-2 hours. Subsequent deployments should only take a few minutes each.

Managed services: Opting forGoogle Cloud solutions such as Cloud Run, Batch, or GKE,which are serverless and fully managed PaaS offerings, might involve a greaterupfront investment of time and effort. This is due to the fundamental changefrom a VM-centric (IaaS) approach where you manage the infrastructure,to a PaaS model where the platform handles much of this.This adaptation may necessitate changes to your application, such as ensuring it'sstateless, but the long-term benefits can include substantial gains in operationalefficiency, scalability, and cost-effectiveness.

For guidance on this transition, see themigration guide.

If I choose to migrate to an alternative, does it involve any interruptions or downtime for Google Cloud projects, VMs, services, and apps?

Generally, the transition to the recommended alternative solution is designedto be a zero-downtime process.

For migration of long-running containers on Compute Engine VMs, in order to avoid disruptions, we recommend setting up new VMs with the alternative configuration and switching over the traffic once they are tested.

How does this migration impact my Terraform configuration?

If you are using Terraform or similar automation to create or updateVMs or MIGs with containers by explicitly setting thegce-container-declarationmetadata key, your workflow will stop working on July 31st, 2026.To avoid disruption, you must update your configuration to include a startupscript for container deployment and remove the dependency on thegce-container-declaration metadata key. For detailed instructions on how toimplement this change, seeMigrate containers that were deployed on VMs during VM creation.

Getting support

Who should I reach out to in Compute Engine if I have questions about the migration process?

If you have any questions or require assistance, contactGoogle Cloud Support.

What resources are available to support me with the migration and provide technical guidance?

This FAQ, amigration guide andGoogle Cloud Support are available to supportyou with the migration process.