After VM Manager applies an OS policy assignment to a virtual machine (VM) instance, an OS policy assignment report is generated. The report contains the compliance status of all the OS policies that are applied to a specific VM for a given OS policy assignment.
This document describes the following tasks:
- View the OS policy compliance report for all VMs in an organization or folder.
- View OS policy assignment reports for all VMs in a specified zone. This is useful for providing an overview of compliance status in a specific zone. See View OS policy assignment reports.
- Review the OS policy assignment for a specific VM. This is useful when reviewing compliance status for a specific VM. See Review an OS policy assignment report.
Before you begin
- Review OS Config quotas.
-
If you haven't already, then set up authentication.
Authentication is
the process by which your identity is verified for access to Google Cloud services and APIs.
To run code or samples from a local development environment, you can authenticate to
Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
-
Required roles and permissions
To get the permissions that you need to view OS policy compliance data, ask your administrator to grant you the following IAM roles:
-
View OS policy compliance summary for VMs in an organization or folder:
-
OSPolicyAssignmentReport Viewer (
roles/osconfig.osPolicyAssignmentReportViewer
) on the organization or folder -
OSPolicyAssignment Viewer (
roles/osconfig.osPolicyAssignmentViewer
) on the organization or folder
-
OSPolicyAssignmentReport Viewer (
-
View OS policy assignment reports for VMs in a project:
OSPolicyAssignmentReport Viewer (
roles/osconfig.osPolicyAssignmentReportViewer
) on the project
For more information about granting roles, see Manage access to projects, folders, and organizations.
These predefined roles contain the permissions required to view OS policy compliance data. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to view OS policy compliance data:
-
View OS policy compliance summary for VMs in an organization or folder:
-
osconfig.osPolicyAssignmentReports.searchSummaries
-
osconfig.osPolicyAssignments.searchPolicies
-
resourcemanager.projects.get
-
resourcemanager.projects.list
-
You might also be able to get these permissions with custom roles or other predefined roles.
View OS policy compliance summary for all VMs in an organization or folder
You can view the OS policy compliance summary for all VMs in an organization or folder by using the Google Cloud console.
VM Manager displays OS policy compliance summary only for those projects that meet one of the following requirements:
- Contains one or more VMs on which VM Manager is enabled and running.
- Contains one or more VMs on which VM Manager was running in the past 7 days and OS policy compliance data is available.
To view OS policy compliance data, do the following:
In the Google Cloud console, go to the Compute Engine > VM Manager > OS policies page.
In the project drop-down list at the top of the Google Cloud console, select the organization or folder for which you want to see the OS policy compliance summary.
Use the following options to view the OS policy compliance data:
- To view OS policy compliance summary per project, click the Projects tab.
- To view OS policy compliance summary per policy, click the OS policies tab.
Optional: Specify the criteria for computing the OS policy compliance summary by using the query builder.
Review OS policy compliance summary for VMs. The table in the Projects tab includes a row for each project as shown in the following figure:
The table lists the following information that meets the criteria you've specified in the query builder:
- Project: The name of projects in the organization that contain at least one VM and have VM Manager enabled.
- Total VMs: Total number of VMs in each project.
- Monitored VMs: Number of VMs in the project that have VM Manager agent enabled and are being scanned for policy compliance.
- VMs with policy: Number of VMs with at least one policy assigned.
- Compliant: Number of VMs with all their assigned policies reported as
COMPLIANT
. - Non compliant: Number of VMs with at least one assigned policy reported as
NON-COMPLIANT
. - Unknown: Number of VMs with at least one assigned policy reported as
UNKNOWN
, and no policy reported asNON-COMPLIANT
. TheUNKNOWN
state is due to one of the following reasons:- The VM is not running.
- VM Manager agent is not enabled for the VM.
- An error occurred during the process.
- No report: Number of VMs with assigned policies, but no policy compliance
report was found due to one of the following reasons:
- VM Manager agent is not enabled for the VM.
- Compliance scan is in progress. The report is not ready yet.
Optional: Apply table filters if you want to view specific rows in the OS policy compliance summary table.
For example, if you want to see OS policy compliance summary for projects that have more than 10 VMs, then set the filter option Total VMs to
>= 10
.Optional: Click the number of VMs to view more details about the VMs in a particular state. For example, clicking the number of VMs for a given project in the Unknown column opens the VM instances tab with a list of unknown OS policies for each VM in that project.
For more information, see View OS policy assignment reports.
Use query builder to filter OS policy compliance data
Based on the criteria that you specified in the query builder, VM Manager displays the OS policy compliance data for VMs in the projects in your organization or folder. You can then use the table filters in the OS policy compliance table to filter the displayed data.
For example, when you set the OS
attribute in the Query builder as Debian
,
VM Manager displays OS policy compliance data for VMs with Debian OS.
If you want to view the compliance data for a specific project, use the
table filter to specify the project ID.
To set a query in the query builder in the Projects tab, do the following:
Select an Attribute. The query builder supports the following attributes:
- OS: Specify the short names of the operating systems such as
Windows
orDebian
. - OS version: Specify the version of the operating system. For example,
21.04
or10.0.22000
. You can specify a single asterisk (*
) at the end of the OS version string to denote partial match, for example10*
. - VM running: Specify whether you want to view patch summary for VMs
that are in the
RUNNING
state. - Policy fingerprint: Specify the unique policy fingerprint for the OS policy. When you set this attribute, VM Manager computes compliance summary only for those OS policies with the specified fingerprint.
- Compliance state: Specify one of the compliance states for the policy:
COMPLIANT
: VMs with all assigned policies reported asCOMPLIANT
NON-COMPLIANT
: VMs with at least one assigned policy reported asNON-COMPLIANT
UNKNOWN
: VMs with at least one assigned policy reported asUNKNOWN
- OS: Specify the short names of the operating systems such as
Choose one of the attributes and specify a value for the attribute. For example, if you want to see patch summary for VMs with a specific operating system, then select OS. You then get a list of comparison operators to choose from.
- Select an Operator, for example,
==
. - In the Value field, specify the comparison value. For example
Debian
.
- Select an Operator, for example,
To add another attribute, click Add condition.
Click Search.
View OS policy assignment reports
To view the OS policy assignment reports, you can use either Google Cloud console, the Google Cloud CLI, or REST.
Use this procedure to view a list of OS policy assignment reports for a specified location.
Console
If you use VPC Service Controls to protect your services, add the Cloud Asset Inventory service to your list of allowed services. For more information, see VPC accessible services.
In the Google Cloud console, go to the OS policies > VM instances page.
gcloud
To view a list of OS policy assignment reports, use the
os-config os-policy-assignment-reports list
command.
To view all OS policy assignment reports for a specific location, run the following
command. Replace ZONE
with the zone where the VMs are
located.
gcloud compute os-config os-policy-assignment-reports list --location=ZONE
Example command and output (all VMs)
gcloud compute os-config os-policy-assignment-reports list --location=us-central1-a INSTANCE ASSIGNMENT_ID LOCATION UPDATE_TIME SUMMARY centos7 my-test-assignment1 us-central1-a 2021-11-02T18:14:03.908341Z 0/1 policies compliant centos7 my-test-assignment2 us-central1-a 2021-11-02T18:14:03.908341Z 0/1 policies compliant rhel-8 my-test-assignment1 us-central1-a 2021-11-02T19:13:28.468290Z 0/1 policies compliant rhel-8 my-test-assignment2 us-central1-a 2021-11-02T19:13:28.468290Z 0/1 policies compliant my-centos my-test-assignment1 us-central1-a 2021-11-02T18:14:37.418883Z 1/1 policies compliant my-centos my-test-assignment2 us-central1-a 2021-11-02T18:14:37.418883Z 0/1 policies compliant deb-10 my-test-assignment2 us-central1-a 2021-11-02T19:00:11.777748Z 0/1 policies compliant windows my-test-assignment2 us-central1-a 2021-11-02T18:24:07.935711Z 0/1 policies compliant windows my-test-assignment3 us-central1-a 2021-11-02T18:24:07.935711Z 0/1 policies compliant sles15 my-test-assignment2 us-central1-a 2021-11-02T18:38:07.335276Z 0/1 policies compliant
You can also use optional flags such as --instance
or --assignment-id
to filter the results.
gcloud compute os-config os-policy-assignment-reports list --location=ZONE \ [--instance=VM_NAME | --assignment-id=ASSIGNMENT_ID]
Replace the following:
ZONE
: the zone where the VM is located- Optional: provide one of the following:
VM_NAME
: the name or ID of the VM that you want to view OS policy assignment reports forASSIGNMENT_ID
: the ID of the OS policy assignment that you want to view OS policy assignment reports for
Example command and output (specific VM)
gcloud compute os-config os-policy-assignment-reports list --location=us-central1-a \ --instance=my-centos INSTANCE ASSIGNMENT_ID LOCATION UPDATE_TIME SUMMARY my-centos my-test-assignment1 us-central1-a 2021-11-02T18:14:37.418883Z 1/1 policies compliant my-centos my-test-assignment2 us-central1-a 2021-11-02T18:14:37.418883Z 0/1 policies compliant
Example command and output (specific assignment)
gcloud compute os-config os-policy-assignment-reports list --location=us-central1-a \ --assignment-id=my-test-assignment1 INSTANCE ASSIGNMENT_ID LOCATION UPDATE_TIME SUMMARY centos7 my-test-assignment1 us-central1-a 2021-11-02T18:14:03.908341Z 0/1 policies compliant rhel-8 my-test-assignment1 us-central1-a 2021-11-02T19:13:28.468290Z 0/1 policies compliant my-centos my-test-assignment1 us-central1-a 2021-11-02T18:14:37.418883Z 1/1 policies compliant
REST
In the API, create a GET
request to the
projects.locations.osPolicyAssignments.reports.list
method.
GET https://osconfig.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/instances/VM_NAME/osPolicyAssignments/OS_POLICY_ASSIGNMENT_ID/report
Replace the following:
PROJECT_ID
: your project IDZONE
: the zone where the VMs are located- Optional. Provide one of the following:
VM_NAME
: the name or ID of the VM that you want to view OS policy assignment reports for. If not required, use a-
for the value.ASSIGNMENT_ID
: the ID of the OS policy assignment that you want to view OS policy assignment reports for. If not required, use a-
for the value.
Examples:
- To view reports for all VMs in the project
my-project-12345
and zoneus-central1-a
, use the following URI:projects/my-project-12345/locations/us-central1-a/instances/-/osPolicyAssignments/-/report
- To view reports for the VM
my-test-vm
in the projectmy-project-12345
and located in zoneus-central1-a
, use the following URI:projects/my-project-12345/locations/us-central1-a/instances/my-test-vm/osPolicyAssignments/-/report
- To view reports for all VMs in the project
my-project-12345
and zoneus-central1-a
that have themy-test-assignment
OS policy assignment, use the following URI:projects/my-project-12345/locations/us-central1-a/instances/-/osPolicyAssignments/my-test-assignment/report
Review an OS policy assignment report
Use this procedure to get a detailed view of an OS policy assignment report associated with a specific VM.
Console
If you use VPC Service Controls to protect your services, add the Cloud Asset Inventory service to your list of allowed services. For more information, see VPC accessible services.
In the Google Cloud console, go to the OS policies > VM instances page.
To view the OS policy assignment report for a specific VM, click the name of the VM.
Review the State, State reason, and Logs fields. The Logs field provides a link to the Cloud Logging dashboard where you can access debug logs for the OS Config agent running on the VM.
- For more information about the returned compliance states, review the
ComplianceState
section in the API reference documentation. - For more information about the returned compliance reasons, review the
complianceStateReason
field in theOSPolicyResourceCompliance
API reference documentation.
To fix these issues, you can also review the logs for the OS policy and make the required updates. To check the logs, see Troubleshooting VM Manager.
- For more information about the returned compliance states, review the
gcloud
To view the OS policy assignment report for a specific VM, use the
os-config os-policy-assignment-reports describe
command.gcloud compute os-config os-policy-assignment-reports describe OS_POLICY_ASSIGNMENT_ID \ --instance=VM_NAME \ --location=ZONE
Replace the following:
OS_POLICY_ASSIGNMENT_ID
: the ID of the OS policy assignment that you want to review for the specified VMVM_NAME
: the name or ID of the VM that you want to view OS policy assignment report forZONE
: the zone where the VM is located
Example
gcloud compute os-config os-policy-assignment-reports describe my-test-assignment1 \ --instance=centos7 \ --location=us-central1-a
Output
instance: centos7 lastRunId: 96a61b92-3e14-4155-a3e8-dd66520f49ae name: projects/1234578882888/locations/us-central1-a/instances/29255009728795105/osPolicyAssignments/my-test-assignment1/report osPolicyAssignment: projects/1234578882888/locations/us-central1-a/osPolicyAssignments/my-test-assignment1t@3428384d-fa61-478e-b7e2-3d5fae74bea3 osPolicyCompliances: – complianceState: UNKNOWN complianceStateReason: os-policies-not-supported-by-agent osPolicyId: setup-repo-and-install-package-policy osPolicyResourceCompliances: – complianceState: UNKNOWN complianceStateReason: os-policy-execution-attempt-failed osPolicyResourceId: setup-repo – complianceState: UNKNOWN complianceStateReason: os-policy-execution-attempt-failed osPolicyResourceId: install-pkg updateTime: '2021-11-02T19:14:34.314831Z'
Review the
complianceState
andcomplianceStateReason
.- For more information about the returned compliance states, review the
ComplianceState
section in the API reference documentation. - For more information about the returned compliance reasons, review the
complianceStateReason
field in theOSPolicyResourceCompliance
API reference documentation.
To fix these issues, you can also review the logs for the OS policy and make the required updates. To check the logs, see Troubleshooting VM Manager.
- For more information about the returned compliance states, review the
REST
In the API, create a
GET
request to theprojects.locations.osPolicyAssignments.reports.get
method.GET https://osconfig.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/instances/VM_NAME/osPolicyAssignments/OS_POLICY_ASSIGNMENT_ID/report
Replace the following:
PROJECT_ID
: your project IDZONE
: the zone where the VM is locatedVM_NAME
: the name or ID of the VM that you want to view OS policy assignment report forOS_POLICY_ASSIGNMENT_ID
: the ID of the OS policy assignment that you want to view OS policy assignment report for
Review the
complianceState
andcomplianceStateReason
.- For more information about the returned compliance states, review the
ComplianceState
section in the API reference documentation. - For more information about the returned compliance reasons, review the
complianceStateReason
field in theOSPolicyResourceCompliance
API reference documentation.
To fix these issues, you can also review the logs for the OS policy and make the required updates. To check the logs, see Troubleshooting VM Manager.
- For more information about the returned compliance states, review the
What's next?
- Learn more about the OS policies.
- Manage OS policies.