Enable OS Config Agent Reporting for Compute Engine VM Instances

Risk Level: Medium (should be achieved)

Ensure that Compute Engine virtual machine (VM) instances have the OS Config agent enabled and actively reporting operating system (OS) and patch inventory data to Google Cloud. The OS Config agent is a VM Manager component that, once installed and running inside the guest OS, collects data such as the OS version, kernel details, and installed packages approximately every 10 minutes and reports it through the OS Config Inventory API ("osconfig.googleapis.com"). For a VM instance to report this data, the OS Config API must be enabled for the project, and the "enable-osconfig" metadata key must be set to "TRUE", either at the project level (applies to all instances) or on the individual instance, which overrides the project-level setting.

Security

Without OS Config agent reporting enabled, Google Cloud has no visibility into the operating system version, kernel, or installed packages running on your Compute Engine VM instances, making it impossible to determine whether a VM instance is missing critical OS updates. Enabling and verifying OS/patch inventory reporting is the prerequisite step for patch compliance visibility which calls for confirming that the latest operating system updates are installed across every VM instance in every project.

Note: Confirming that the OS Config agent is enabled and actively reporting inventory data verifies that patch compliance can be evaluated for a VM instance — it does not by itself confirm that the VM instance is already running the latest OS updates. Determining actual patch currency requires the separate Patch Compliance capability of VM Manager, which reads this reported inventory data to identify missing updates.

Audit

To determine if Compute Engine VM instances have the OS Config agent enabled and actively reporting OS inventory data, perform the following operations:

Note: The OS Config agent reports inventory data through the OS Config Inventory API, and the compute os-config inventories describe command used in this audit (step 11 below) reads that data through the same API. This is unaffected by the "Disable Guest Attributes of Compute Engine Metadata" organization policy (the compute.disableGuestAttributesAccess constraint).

If your organization or project enforces that policy, be aware that the older compute instances os-inventory describe command — which reads inventory data through the guest attributes endpoint instead — returns an error, even when the OS Config API is enabled, "enable-osconfig" is set to "TRUE" for the VM instance, and the OS Config agent is installed, running, and actively reporting. Use compute os-config inventories describe for this audit to avoid that error.

Using GCP Console

Sign in to Google Cloud Management Console.
Select the GCP project that you want to examine from the console top navigation bar.
Navigate to the API Library page available at https://console.cloud.google.com/apis/library.
Type VM Manager (OS Config API) in the Search for APIs & Services search box and press Enter.
Click on the name of the API to open its overview page.
On the API overview page, check whether a MANAGE button or an ENABLE button is displayed. If the ENABLE button is displayed, the OS Config API is not enabled for the selected project, and every VM instance in the project fails this check. Otherwise, if the MANAGE button is displayed, the API is enabled and you can continue the audit process.
Navigate to Compute Engine console available at https://console.cloud.google.com/compute.
In the navigation panel, under Settings, choose Metadata to access the project-wide metadata.
Select the METADATA tab and check whether an item with the key enable-osconfig exists and is set to TRUE. Note this project-level value — VM instances inherit it unless they define their own enable-osconfig metadata item. If instead you see this setting from the VM Manager settings page and it shows Per VM instance, that means no project-level override is set; treat it the same as the item not existing, and continue to steps 10–14 below to check each VM instance's own metadata individually.
In the navigation panel, under Virtual Machines, select VM instances to access the list of VM instances provisioned within the selected project.
Click on the name of the VM instance that you want to examine.
Select the Details tab and check the Custom metadata section for an enable-osconfig item. If this item exists, its value overrides the project-level value noted in step 9; if it doesn't exist, the instance inherits the project-level value. If the resulting (instance-level or inherited) enable-osconfig value is not TRUE, the OS Config agent is not enabled for the selected VM instance.
If enable-osconfig resolves to TRUE for the selected instance, select the OS info tab on the same Instance details page. If the console prompts you to enable VM Manager, displays an error instead of inventory data, or does not display OS details together with a recent collection time, the OS Config agent is not currently installed, running, or reporting inventory data for the selected VM instance — use the Audit CLI section below to confirm the specific reason. Otherwise, if the OS info tab displays the operating system details and a recent update time, the VM instance is compliant.
Repeat steps no. 11 – 13 for each VM instance provisioned within the selected project.
Repeat steps no. 2 – 14 for each project deployed in your Google Cloud account.

Using GCP Command Line Interface (CLI)

Run projects list command (Windows/macOS/Linux) using custom query filters to list the ID of each GCP project available within your Google Cloud account:
```
gcloud projects list
--format="table(projectId)"
```
The command output should return the requested GCP project identifiers:
```
PROJECT_ID
cc-web-project-112233
cc-bigdata-project-123123
```
Run services list command (Windows/macOS/Linux) using the ID of the GCP project that you want to examine as identifier parameter and custom filtering to determine if the OS Config API is enabled for the selected project:
```
gcloud services list
--project cc-web-project-112233
--enabled
--filter=name:osconfig.googleapis.com
```
The command output should return the name and title of the requested API:
```
NAME                     TITLE
osconfig.googleapis.com  OS Config API
```
If the services list command output returns Listed 0 items. instead of the API shown above, the OS Config API is disabled for the selected project, and every VM instance in the project fails this check. Otherwise, continue the audit process with the next step.
Run compute project-info describe command (Windows/macOS/Linux) using the ID of the GCP project that you want to examine as identifier parameter and custom query filters to describe the metadata items configured at the project level:
```
gcloud compute project-info describe
--project cc-web-project-112233
--format="json(commonInstanceMetadata.items)"
```
The command output should return the requested GCP project metadata items, which are inherited by every VM instance in the project unless overridden:
```
{
    "commonInstanceMetadata": {
        "items": [
            {
                "key": "enable-osconfig",
                "value": "true"
            }
        ]
    }
}
```
Metadata values are stored as plain, case-sensitive strings, so check the "enable-osconfig" value case-insensitively — it may be reported as "true", "True", or "TRUE" depending on how it was originally set.
Run compute instances list command (Windows/macOS/Linux) using the ID of the GCP project that you want to examine as identifier parameter and custom query filters to list the name and zone of each VM instance provisioned in the selected project:
```
gcloud compute instances list
--project cc-web-project-112233
--format="table(name,zone)"
```

The command output should return the requested VM instance names:

NAME                      ZONE
cc-backend-vm-instance    us-central1-a
cc-frontend-vm-instance   us-central1-a

Run compute instances describe command (Windows/macOS/Linux) using the name and the zone of the instance that you want to examine as identifier parameter and custom query filters to describe the metadata items configured for the selected VM instance:
```
gcloud compute instances describe cc-backend-vm-instance
--project cc-web-project-112233
--zone us-central1-a
--format="json(metadata.items)"
```
The command output should return the requested VM instance metadata items:
```
{
    "metadata": {
        "items": [
            {
                "key": "enable-osconfig",
                "value": "true"
            }
        ]
    }
}
```
If the command output does not return a metadata item with the key "enable-osconfig", the selected VM instance inherits the project-level value returned in step 6. If the instance-level or inherited "enable-osconfig" value is not "true" (checked case-insensitively), the OS Config agent is not enabled for the selected VM instance, and the audit process ends here for this instance. Otherwise, continue the audit process with the next step.
Run compute os-config inventories describe command (Windows/macOS/Linux) using the name and the location (zone) of the instance that you want to examine as identifier parameter, to confirm that the OS Config agent is installed, running, and actively reporting OS inventory data for the selected VM instance:
```
gcloud compute os-config inventories describe cc-backend-vm-instance
--location us-central1-a
--project cc-web-project-112233
--format=json
```
The command output should return the OS inventory data collected for the selected VM instance:
```
{
    "installed_packages": {},
    "system_information": {
        "architecture": "x86_64",
        "hostname": "cc-backend-vm-instance",
        "kernelRelease": "6.1.0-53-cloud-amd64",
        "kernelVersion": "#1 SMP PREEMPT_DYNAMIC Debian 6.1.187-1 (2026-09-07)",
        "longName": "Debian GNU/Linux 12 (bookworm)",
        "osconfigAgentVersion": "20260624.00-g1",
        "shortName": "debian",
        "updateTime": "2026-09-16T06:18:46.411367Z",
        "version": "12"
    },
    "updatedable_packages": {}
}
```
If the compute os-config inventories describe command returns an error (for example, NOT_FOUND) or an empty result, or the "system_information.updateTime" value corresponds to a timestamp that is significantly older than the OS Config agent's default 10-minute reporting interval, the OS Config agent is not installed, not running, or not actively reporting inventory data for the selected VM instance, and the instance is not compliant. installed_packages and updatedable_packages are populated only when the command is run with --view=full; they are expected to be empty objects otherwise and this does not indicate non-compliance.

Note: The compute instances os-inventory describe command reads inventory data through the guest attributes endpoint instead of the OS Config Inventory API used above. If the "Disable Guest Attributes of Compute Engine Metadata" organization policy (compute.disableGuestAttributesAccess) is enforced, that command fails with the following error even when the OS Config agent itself is healthy and reporting successfully (see the note at the beginning of this Audit section):
```
ERROR: (gcloud.compute.instances.os-inventory.describe) Could not fetch resource:
 - Constraint constraints/compute.disableGuestAttributesAccess violated for project PROJECT_NUMBER.
```
Otherwise, if the compute os-config inventories describe command returns OS inventory data with a recent "updateTime" value, as shown in the example above, the selected VM instance is compliant.
Repeat steps no. 9 – 12 for other VM instances provisioned within the selected project.
Repeat steps no. 3 – 13 for each GCP project deployed in your Google Cloud account.

Remediation / Resolution

To enable the OS Config API and configure the "enable-osconfig" metadata so that the OS Config agent runs and reports OS inventory data for your Compute Engine VM instances, perform the following operations:

Note: Setting the "enable-osconfig" metadata key to "TRUE" does not, by itself, install the OS Config agent inside a VM instance's guest operating system — it only instructs Compute Engine that the agent should run. Every current Compute Engine public OS image (Debian, Ubuntu, CentOS, RHEL, SLES, Windows, and Container-Optimized OS) ships with the OS Config agent pre-installed, and the agent starts reporting automatically once the API is enabled and "enable-osconfig" is set to "TRUE". VM instances built from older or custom images that don't include the agent must have it installed manually before they can report inventory data.

If the "Disable Guest Attributes of Compute Engine Metadata" organization policy (the compute.disableGuestAttributesAccess constraint) is enforced for the project, organization, or folder, the steps below still resolve the issue — the OS Config agent's reporting mechanism does not depend on the guest attributes endpoint. Verify the result with compute os-config inventories describe (Remediation CLI step 7 below) rather than the older compute instances os-inventory describe command, which continues to return an error under that policy regardless of remediation.

VM instances also need a service account attached with sufficient access (at minimum, the https://www.googleapis.com/auth/cloud-platform scope, or an equivalent narrower scope covering osconfig.googleapis.com) for the OS Config agent to authenticate and report inventory data. Without one, the agent fails to obtain the identity token it needs and never reports, independent of the API/metadata configuration above or the organization policy — check the VM's serial console output for error getting token from metadata if inventory data still doesn't appear after allowing time for the agent's reporting cycle.

Using GCP Console

Sign in to Google Cloud Management Console.
Select the GCP project that you want to reconfigure from the console top navigation bar.
Navigate to the API Library page available at https://console.cloud.google.com/apis/library (see Audit section part I to identify a project where the OS Config API is not enabled).
Type VM Manager (OS Config API) in the Search for APIs & Services search box and press Enter.
Click on the name of the API to open its overview page.
Choose ENABLE to enable the OS Config API for the selected GCP project.
Navigate to Compute Engine console available at https://console.cloud.google.com/compute.
In the navigation panel, under Settings, choose Metadata.
Choose EDIT, then choose ADD ITEM to add a metadata entry where the Key is enable-osconfig and the Value is TRUE (or update the existing item's value to TRUE). Choose SAVE to apply the changes. All VM instances in the selected project will inherit this setting unless they define their own override (see Audit section part I to identify the right instance).
In the navigation panel, select VM instances to access the list of VM instances provisioned for the selected project.
Click on the name of the VM instance that overrides the project-level metadata with an enable-osconfig value that is not TRUE (see Audit section part I to identify the right instance).
Select the Details tab and choose EDIT.
In the Custom metadata section, either remove the enable-osconfig override so the instance inherits the project-level value, or update its value to TRUE. Choose SAVE to apply the changes.
Select the OS info tab on the same Instance details page. If prompted, choose Enable for this VM to enable VM Manager for the selected instance. Allow a few minutes for the OS Config agent to complete its first reporting cycle.
If required, repeat steps no. 11 – 14 for other VM instances that override the project-level metadata within the selected project.
Repeat steps no. 2 – 15 for each GCP project available in your Google Cloud account.

Using GCP Command Line Interface (CLI)

Run services enable command (Windows/macOS/Linux) using the ID of the GCP project that you want to reconfigure as identifier parameter (see Audit section part II to identify the right resource), to enable the OS Config API for the selected project:
```
gcloud services enable osconfig.googleapis.com
--project cc-web-project-112233
```

If successful, the command output should return the ID and status of the performed operation:

Operation "operations/acat.p0-123456789012-abcd1234-abcd-1234-abcd-1234abcd1234" finished successfully.

Run compute project-info add-metadata command (Windows/macOS/Linux) using the ID of the GCP project that you want to reconfigure as identifier parameter, to set the "enable-osconfig" metadata to "TRUE" at the project level. All VM instances in the selected project will inherit this setting unless they define their own override:
```
gcloud compute project-info add-metadata
--project cc-web-project-112233
--metadata=enable-osconfig=TRUE
```

The command output should return the URL of the reconfigured GCP project:

Updated [https://www.googleapis.com/compute/v1/projects/cc-web-project-112233].

Run compute instances add-metadata command (Windows/macOS/Linux) using the name and the zone of the VM instance that overrides the project-level metadata with an "enable-osconfig" value that is not "TRUE" as identifier parameter (see Audit section part II to identify the right instance), to update the override:
```
gcloud compute instances add-metadata cc-backend-vm-instance
--project cc-web-project-112233
--zone us-central1-a
--metadata=enable-osconfig=TRUE
```
Alternatively, run the compute instances remove-metadata command to remove the override entirely, so the instance inherits the project-level value set in step 3:
```
gcloud compute instances remove-metadata cc-backend-vm-instance
--project cc-web-project-112233
--zone us-central1-a
--keys=enable-osconfig
```

The command output should return the URL of the reconfigured VM instance:

Updated [https://www.googleapis.com/compute/v1/projects/cc-web-project-112233/zones/us-central1-a/instances/cc-backend-vm-instance].

Run compute os-config inventories describe command (Windows/macOS/Linux) using the name and the location (zone) of the reconfigured VM instance as identifier parameter (see Audit section part II to identify the right resource), to confirm that the OS Config agent has started reporting inventory data:
```
gcloud compute os-config inventories describe cc-backend-vm-instance
--location us-central1-a
--project cc-web-project-112233
--format=json
```
The command output should return the OS inventory data collected for the selected VM instance, with a "system_information.updateTime" value that reflects the agent's most recent reporting cycle:
```
{
    "installed_packages": {},
    "system_information": {
        "architecture": "x86_64",
        "hostname": "cc-backend-vm-instance",
        "kernelRelease": "6.1.0-53-cloud-amd64",
        "kernelVersion": "#1 SMP PREEMPT_DYNAMIC Debian 6.1.187-1 (2026-09-07)",
        "longName": "Debian GNU/Linux 12 (bookworm)",
        "osconfigAgentVersion": "20260624.00-g1",
        "shortName": "debian",
        "updateTime": "2026-09-16T06:18:46.411367Z",
        "version": "12"
    },
    "updatedable_packages": {}
}
```
If the command still returns an error (for example, NOT_FOUND) or stale data after allowing sufficient time for the agent's reporting cycle, confirm that the OS Config agent is installed and running inside the guest OS (see the Set up VM Manager documentation referenced below), and that the VM instance has a service account attached with sufficient access for the agent to authenticate to osconfig.googleapis.com (see the Remediation Note above).
If required, repeat steps no. 5 – 8 for other VM instances that override the project-level metadata within the selected project.
Repeat steps no. 1 – 9 for each GCP project deployed in your Google Cloud account.

References

CIS Security Documentation
CIS Google Cloud Computing Platform Benchmarks

Publication date Sep 18, 2026

Audit

Using GCP Console

Using GCP Command Line Interface (CLI)

Remediation / Resolution

Using GCP Console

Using GCP Command Line Interface (CLI)

References

Related ComputeEngine rules