Collect vertical Pod autoscaler event logs

This page provides information about decision events emitted by the vertical Pod autoscaler in Google Kubernetes Engine (GKE). By analyzing these events, you can both gain insights into how the vertical Pod autoscaler controller manages your workload scaling and understand the decision-making process behind its actions.

The vertical Pod autoscaler emits decision events, which are stored as log entries in Cloud Logging.

Before you begin

Make sure to complete the following prerequisites:

Select or create a project

You can use an existing project, or create a new one for this tutorial.

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Go to project selector

2. Verify that billing is enabled for your Cloud de Confiance project.

Enable the APIs

Enable the GKE, and Cloud Logging APIs.

Enable the APIs

Set up Cloud Shell

In this tutorial, you use Cloud Shell to run gcloud and kubectl commands. Cloud Shell is a shell environment for managing resources hosted on Cloud de Confiance by S3NS. It comes preinstalled with the Google Cloud CLI and kubectl command-line tool.

In the Cloud de Confiance console, activate Cloud Shell.

Activate Cloud Shell

A Cloud Shell session opens inside a frame lower on the console.

Before you run commands in this tutorial, make sure that your default project is set to the project ID where you want to deploy the sample app. If it's not already set, run the following command in the Cloud Shell:

gcloud config set project PROJECT_ID

Replace PROJECT_ID with your project ID.

Required roles and permissions

To get the permissions that you need to enable log generation, and to access and process logs, ask your administrator to grant you the following IAM roles on the project:

• To enable vertical Pod autoscaler event logging in your cluster: Kubernetes Engine Cluster Admin (roles/container.clusterAdmin)
• To access logs and to use Logs Explorer and Observability Analytics: Logs Viewer (roles/logging.viewer)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Requirements

• Your GKE cluster must be running version 1.36.0-gke.1601000 or later.
• Enable Cloud Logging in your GKE cluster.
• Ensure you have a vertical Pod autoscaler that you want to monitor. Ensure that the vertical Pod autoscaler fields don't include confidential, sensitive, or personally identifiable information.

Costs

Cloud Logging pricing applies when you enable Cloud Logging and collect vertical Pod autoscaler decision logs.

Enable vertical Pod autoscaler decision logs

The commands in the following sections enable exporting the logs generated by KCP_VPA and save the logs at the logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fvpa-controller" destination within Cloud Logging.

Enable logs on a new cluster

To create a new cluster with the KCP_VPA decision logs enabled, run the following command.

gcloud container clusters create CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --logging=SYSTEM,KCP_VPA

Replace the following:

• CLUSTER_NAME: the name of the cluster you want to create or update.
• PROJECT_ID: your Cloud de Confiance project ID.
• LOCATION: the compute regions or zones for your cluster.

Enable logs on an existing cluster

To enable the KCP_VPA decision logs on an existing cluster, do the following:

1. Review the existing configuration of the cluster. If the cluster has specific logging components already configured, then decide if you want to add to or overwrite the existing logging configuration.

2. To enable the vertical Pod autoscaler decision logs, run the following command. If you are adding to an existing configuration, then add the existing logging configuration to the command as well.

   gcloud container clusters update CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --logging=SYSTEM,KCP_VPA
   

   Replace the following:

   • CLUSTER_NAME: name of the cluster you want to create or update.
   • PROJECT_ID: your Cloud de Confiance project ID.
   • LOCATION: compute regions or zones for your cluster.

Verify that logging is enabled

To verify that the KCP_VPA decision logs are enabled on a cluster, retrieve the updated logging configuration of the cluster and review the list of logs. To do so, run the following command:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=loggingConfig \
    --format='csv[delimiter=",",no-heading](componentConfig.enableComponents)'

Replace the following:

• CLUSTER_NAME: the name of the cluster.
• LOCATION: the compute regions or zones for your cluster.

When KCP_VPA decision logs are enabled on a cluster, the output is similar to the following:

SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER,KCP_VPA

View vertical Pod autoscaler logs in the Logs Explorer

You can monitor the behavior of the vertical Pod autoscaler in the Logs Explorer. To view vertical Pod autoscaler logs, complete the following steps:

1. Go to the Logs Explorer page:

   Go to Logs Explorer

2. Select All log names, and search the log names for vpa-controller.

   The logs explorer displays all vertical Pod autoscaler logs, including logs from all clusters that enabled vertical Pod autoscaler logs in the project.

3. You can filter the logs by using the cluster name or workload name. For example, to list events from a specific workload in a cluster, specify the cluster name and workload name by using the following query:

   resource.labels.cluster_name="CLUSTER_NAME" AND
   jsonPayload.target.name="WORKLOAD_NAME"
   

   Replace the following:

   • CLUSTER_NAME: the name of the cluster.
   • WORKLOAD_NAME: the name of the workload.

Disable vertical Pod autoscaling decision logs

1. To disable the KCP_VPA decision logs on an existing cluster, run the following command:

   gcloud container clusters update CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --logging=SYSTEM
   

2. Verify that the KCP_VPA decision logs are disabled. To do so, run the following command:

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --flatten=loggingConfig \
       --format='csv[delimiter=",",no-heading](componentConfig.enableComponents)'
   

   When KCP_VPA decision logs are disabled on a cluster, the output is similar to the following:

   SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER
   

Types of logs

The decision events for the vertical Pod autoscaler are stored in Cloud Logging, at the logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fvpa-controller" location that's in the _Default bucket in the same project as your GKE cluster. All logged events are in the JSON format and can be found in the jsonPayload field of a log entry.

The type and frequency of logs generated depend on the vertical Pod autoscaling mode configured for your workload. There are four types of VPA logs, categorized by the operation they perform:

• Update recommendation: each vertical Pod autoscaler generates one new update recommendation log every minute.
• Evict Pod: each vertical Pod autoscaler generates one evict Pod log for each Pod when the vertical Pod autoscaler decides to resize in Recreate mode.
• Apply recommendation on eviction: each vertical Pod autoscaler generates one apply recommendation log for each Pod when the vertical Pod autoscaler decides to resize in Recreate mode.
• Apply recommendation in place: each vertical Pod autoscaler generates one apply recommendation in place log for each Pod when the vertical Pod autoscaler decides to resize in InPlaceOrRecreate mode.

The types of logs that the controller can emit depends on the mode of the vertical Pod autoscaler. The following table lists the logs that can be emitted for each mode.

For a vertical Pod autoscaler with InPlaceOrRecreate mode, when In-place resize fails, the autoscaler has the same behavior as the Recreate mode.

Update recommendation

An update recommendation log can be produced with the following vertical Pod autoscaler modes: Auto (deprecated), Recreate, and InPlaceOrRecreate.

The jsonPayload of this decision log includes the following fields:

Example update recommendation log:

{
 "insertId": "ehz6w9d304v4zttg",
 "jsonPayload": {
   "state": "SUCCEEDED",
   "instance": {
     "vm_name": "my-unique-vm-identifier",
     "zone": "us-central1-c"
   },
   "recommendedResources": [
     {
       "lowerBound": {
         "memory": "5Mi",
         "cpu": "5m"
       },
       "containerName": "nginx",
       "uncappedTarget": {
         "memory": "5Mi",
         "cpu": "1m"
       },
       "upperBound": {
         "memory": "5Mi",
         "cpu": "5m"
       },
       "target": {
         "memory": "5Mi",
         "cpu": "5m"
       }
     }
   ],
   "operation": "UPDATE_RECOMMENDATION",
   "target": {
     "name": "my-workload",
     "kind": "Deployment",
     "apiVersion": "apps/v1"
   },
   "vpaNamespace": "default",
   "vpaName": "my-vpa"
 },
 "resource": {
   "type": "k8s_control_plane_component",
   "labels": {
     "component_location": "us-central1-c",
     "project_id": "my-project",
     "cluster_name": "my-cluster",
     "location": "us-central1-c",
     "component_name": "vpa-controller"
   }
 },
 "timestamp": "2026-01-22T19:28:16.069635605Z",
 "severity": "INFO",
 "labels": {
   "compute.googleapis.com/resource_name": "my-unique-vm-identifier"
 },
 "logName": "projects/my-project/logs/container.googleapis.com%2Fvpa-controller",
 "sourceLocation": {
   "file": "vpa_event_logger.go",
   "line": "23"
 },
 "receiveTimestamp": "2026-01-22T19:28:17.750678359Z"
}

Evict Pod

An evict Pod log is available with VPA mode Auto (deprecated) and Recreate. This log type is also possible with VPA mode InPlaceOrRecreate if the In-place resize operation fails.

The jsonPayload of this decision log includes the following fields:

Example evict Pod log:

{
 "insertId": "8x278gc4f75oowf4",
 "jsonPayload": {
   "target": {
     "kind": "Deployment",
     "apiVersion": "apps/v1",
     "name": "my-deployment"
   },
   "operation": "EVICT_POD",
   "vpaName": "my-vpa",
   "pod": "my-deployment-856ff7966-gr4rh",
   "state": "SUCCEEDED",
   "vpaNamespace": "default",
   "instance": {
     "vm_name": "my-unique-vm-identifier",
     "zone": "us-central1-c"
   }
 },
 "resource": {
   "type": "k8s_control_plane_component",
   "labels": {
     "component_name": "vpa-controller",
     "cluster_name": "my-cluster",
     "component_location": "us-central1-c",
     "location": "us-central1-c",
     "project_id": "my-project"
   }
 },
 "timestamp": "2026-01-22T19:26:25.283067078Z",
 "severity": "INFO",
 "labels": {
   "compute.googleapis.com/resource_name": "my-unique-vm-identifier"
 },
 "logName": "projects/my-project/logs/container.googleapis.com%2Fvpa-controller",
 "sourceLocation": {
   "file": "vpa_event_logger.go",
   "line": "23"
 },
 "receiveTimestamp": "2026-01-22T19:26:27.766941073Z"
}

Apply recommendation on eviction

An apply recommendation on eviction log is available with VPA mode Auto (deprecated) and Recreate. This log type is also possible with VPA mode InPlaceOrRecreate if In-place resize fails.

The jsonPayload of this decision log includes the following fields:

Example apply recommendation on eviction log:

{
 "insertId": "366tcmgdkq94eppg",
 "jsonPayload": {
   "appliedResources": [
     {
       "containerName": "my-container",
       "requests": {
         "memory": "15Mi",
         "cpu": "15m"
       }
     }
   ],
   "vpaName": "my-vpa",
   "vpaNamespace": "default",
   "instance": {
     "zone": "us-central1-c",
     "vm_name": "my-unique-vm-identifier"
   },
   "pod": "my-deployment-856ff7966-%",
   "state": "SUCCEEDED",
   "target": {
     "name": "my-deployment",
     "kind": "Deployment",
     "apiVersion": "apps/v1"
   },
   "operation": "APPLY_RECOMMENDATION_ON_EVICTION"
 },
 "resource": {
   "type": "k8s_control_plane_component",
   "labels": {
     "location": "us-central1-c",
     "component_location": "us-central1-c",
     "cluster_name": "my-cluster",
     "component_name": "vpa-controller",
     "project_id": "my-project"
   }
 },
 "timestamp": "2026-01-22T19:26:25.344313199Z",
 "severity": "INFO",
 "labels": {
   "compute.googleapis.com/resource_name": "my-unique-vm-identifier"
 },
 "logName": "projects/my-project/logs/container.googleapis.com%2Fvpa-controller",
 "sourceLocation": {
   "file": "vpa_event_logger.go",
   "line": "23"
 },
 "receiveTimestamp": "2026-01-22T19:26:32.744122156Z"
}

Apply recommendation in place

An apply recommendation in place log is available with VPA mode InPlaceOrRecreate.

The jsonPayload of this decision log includes the following fields:

Example apply recommendation in place log:

{
 "insertId": "suzfuepgyiwap7hb",
 "jsonPayload": {
   "pod": "my-deployment-cdc7fd7b4-grxlk",
   "vpaNamespace": "default",
   "state": "SUCCEEDED",
   "target": {
     "name": "my-deployment",
     "apiVersion": "apps/v1",
     "kind": "Deployment"
   },
   "operation": "APPLY_RECOMMENDATION_IN_PLACE",
   "appliedResources": [
     {
       "containerName": "my-container",
       "limits": {
         "cpu": "10m",
         "memory": "10Mi"
       },
       "requests": {
         "cpu": "5m",
         "memory": "5Mi"
       }
     }
   ],
   "instance": {
     "zone": "us-central1-c",
     "vm_name": "my-unique-vm-identifier"
   },
   "vpaName": "my-vpa"
 },
 "resource": {
   "type": "k8s_control_plane_component",
   "labels": {
     "project_id": "my-project",
     "component_location": "us-central1-c",
     "cluster_name": "my-cluster",
     "location": "us-central1-c",
     "component_name": "vpa-controller"
   }
 },
 "timestamp": "2026-01-22T19:26:25.214095375Z",
 "severity": "INFO",
 "labels": {
   "compute.googleapis.com/resource_name": "my-unique-vm-identifier"
 },
 "logName": "projects/my-project/logs/container.googleapis.com%2Fvpa-controller",
 "sourceLocation": {
   "file": "vpa_event_logger.go",
   "line": "23"
 },
 "receiveTimestamp": "2026-01-22T19:26:27.766941073Z"
}

Troubleshooting

This section describes issues and resolution steps related to vertical Pod autoscaler events.

No events

If you don't see any vertical Pod autoscaler decision events, make sure you have done all of the following:

• You have enabled Cloud Logging for the cluster.
• You have enabled the KCP_VPA logs for the cluster.
• You have deployed at least one correctly configured vpa object to your cluster.

To view your vpa object configuration, run the following command:

kubectl describe vpa $VPA_NAME

If you still don't see any KCP_VPA logs, reach out to Cloud de Confiance Support.

What's next

• See About GKE logs.
• Understand your GKE logs.
• Learn how to find specific GKE logs using sample queries.
• Learn how to optimize Pod autoscaling based on metrics.
• Learn more about vertical Pod autoscaling.