View OS policy assignment reports

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.

To review OS policy assignment reports, you can complete the following tasks:

  • List 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 List 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.

To view the OS policy assignment reports, you can use either Google Cloud console, the Google Cloud CLI, or the Cloud OS Config API.

Before you begin

Permissions

Owners of a project have full access to manage OS policy assignments. For all other users, you need to grant permissions. To view OS policy assignment reports, you can grant the following role:

  • OSPolicyAssignmentReport Viewer (roles/osconfig.osPolicyAssignmentReportViewer). Contains permissions to list and describe OS policy assignment reports.

Example command to set permissions

To grant a user report viewer access to OS policy assignments, run the following command:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member user:USER_ID@gmail.com \
        --role roles/osconfig.osPolicyAssignmentReportViewer

Replace the following:

  • PROJECT_ID: the project ID
  • USER_ID: the user's Google Workspace username

List OS policy assignment reports

Use this procedure to view a list of OS policy assignment reports for a specified location.

Console

  1. 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.

  2. In the Google Cloud console, go to the OS configuration management > VM instances page.

    Go to Cloud console

    View VM compliance.

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 for
    • ASSIGNMENT_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

API

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 ID
  • ZONE: 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 zone us-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 project my-project-12345 and located in zone us-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 zone us-central1-a that have the my-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 adssignment report associated with a specific VM.

Console

  1. 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.

  2. In the Google Cloud console, go to the OS configuration management > VM instances page.

    Go to Cloud console

  3. To view the OS policy assignment report for a specific VM, click the name of the VM.

    View VM compliance.

  4. 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.

    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.

gcloud

  1. 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 VM
    • VM_NAME: the name or ID of the VM that you want to view OS policy assignment report for
    • ZONE: 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'
    
  2. Review the complianceState and complianceStateReason.

    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.

API

  1. In the API, create a GET request to the projects.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 ID
    • ZONE: the zone where the VM is located
    • VM_NAME: the name or ID of the VM that you want to view OS policy assignment report for
    • OS_POLICY_ASSIGNMENT_ID: the ID of the OS policy assignment that you want to view OS policy assignment report for
  2. Review the complianceState and complianceStateReason.

    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.

What's next?