Managing guest policies

After you create a guest policy, you can use the following procedures to review and manage your policies:

Update guest policies: Modify your guest policy configurations.
Describe guest policies: Get details about a specific guest policy.
List guest policies: View a list of guest policies in a project.
Delete a guest: Delete a specific guest policy.
View configurations for a VM instance: View configurations that are applied to a VM instance.
Debug a guest policy: Troubleshoot a guest policy.

Since the OS Config agent runs every 10-15 minutes, when you set up a update or deletion of a policy it will take roughly 10-15 minutes to take effect.

You can manage your guest policies using either the gcloud command-line tool or the Cloud OS Config API.

In the gcloud command-line tool and the Cloud OS Config API, the name of the guest policy name is referred to as the policy-id.

Before you begin

If you want to use the command-line examples in this guide:
1. Install or update to the latest version of the gcloud command-line tool.
2. Set a default region and zone.
If you want to use the API examples in this guide, set up API access.

Updating guest policies

To update a guest policy, complete the following steps:

Update the YAML or JSON file.
Run an update or patch command. The update process is similar to the create process with the addition of support for etags that allow for concurrency and consistency control.

gcloud

Use the os-config guest-policies update command to update a guest policy.

gcloud beta compute os-config guest-policies update policy-id \
     --file=file

Replace the following:

policy-id: The name of the guest policy that you want to update.
file: The JSON or YAML file that contains the updated guest policy specifications.

API

In the API, create a PATCH request to the projects.guestPolicies.patch method.

PATCH https://osconfig.googleapis.com/v1beta/projects/project-id/guestPolicies/policy-id

{
  For more information, see Guest policy JSON
}

Replace the following:

project-id: Your project ID.
policy-id: The name of your guest policy.

Describing a guest policy

gcloud

To view details about a guest policy, use the os-config guest-policies describe command. Replace policy-id with the name of the guest policy that you want to describe.

gcloud beta compute os-config guest-policies describe policy-id

API

In the API, create a GET request to the projects.guestPolicies.get method.

GET https://osconfig.googleapis.com/v1beta/projects/project-id/guestPolicies/policy-id

Replace the following:

project-id: Your project ID.
policy-id: The name of your guest policy.

Listing guest policies

gcloud

To view a list of guest policies in your project, use the os-config guest-policies list command.

gcloud beta compute os-config guest-policies list

API

In the API, create a GET request to the projects.guestPolicies.list method. Replace project-id with your project ID.

GET https://osconfig.googleapis.com/v1beta/projects/project-id/guestPolicies

Deleting guest policies

When the OS Config agent detects that a deletion of a guest policy is triggered, the current state of the system is maintained, but no further maintenance of the configuration is done. For example, say you have a guest policy package-update- zone2b set up that installs a package my-package on all VMs in zone us- west2-b and keeps the package UPDATED.

If you delete the package-update-zone2b policy, the following changes take place:

All VMs in us-west2-b that have my-package installed, keeps my-package installed. There is no reversion of the current system state.
On all future runs of the OS Config agent, after the policy deletion, the following takes place:
- If a new VM is added to us-west2-b,my-package is not installed on this new VM.
- For instances with my-package installed, the package is not updated.

gcloud

To delete a guest policy, use the os-config guest-policies delete command. Replace policy-id with the name of the guest policy that you want to delete.

gcloud beta compute os-config guest-policies delete policy-id

API

In the API, create a DELETE request to the projects.guestPolicies.delete method.

DELETE https://osconfig.googleapis.com/v1beta/projects/project-id/guestPolicies/policy-id

Replace the following:

project-id: Your project ID.
policy-id: The name of your guest policy.

Viewing configurations for a VM instance

gcloud

To see the policies that are applied to a single VM instance, use the os-config guest-policies lookup command.

gcloud beta compute os-config guest-policies lookup instance-name \
    --zone=zone

Replace the following:

instance-name: The name of the instance.
zone: The zone for the instance.

API

To see the policies that are applied to a single VM instance, use the following POST request.

POST https://osconfig.googleapis.com/v1beta/projects/project-id/zones/zone/instances/instance-name:lookupEffectiveGuestPolicy

Replace the following:

project-id: Your project ID.
zone: The zone for the instance.
instance-name: The name of your instance.

Debugging a guest policy

You can enable debug logging by setting the metadata osconfig-log-level=debug on the VM instance or project. You can then review either the Cloud Logging or serial port (console) logs for the instance. The OS Config agent writes its log entries to both locations.

Inspect Cloud Logging

After you enable Cloud Logging, the OS Config agent publishes messages in the logs. These logs entries track the following information for the OS Config agent:

The version of the OS Config Agent that is installed in the VM.
Polling of the OS Config API for any guest policies applicable to this VM.
Reception of all guest policies applicable to this VM instance.
Execution of guest policies steps.
Any errors encountered during the process.

You can use the Cloud Console or gcloud command-line tool to inspect Cloud Logging logs corresponding to a specific VM instance.

Console

Go to the Logging > Logs (Logs Viewer) page in the Cloud Console:

Go to the Logs Viewer page
Select an existing Google Cloud project at the top of the page, or create a new project.
Using the drop-down menus, select GCE VM Instance.
Click on the VM that you want to view.
From the All logs drop-down menu, select OSConfigAgent.
Click on Load newer logs.

gcloud

Use the gcloud logging read command to inspect log messages that satisfy the following conditions:

Messages posted by the OS Config agent
Messages originating from VM instances
Messages containing errors

gcloud logging read "resource.type=gce_instance AND logName=projects/${DEVSHELL_PROJECT_ID}/logs/OSConfigAgent AND severity=ERROR"

For more details, see Viewing Cloud Logging logs

Inspecting guest policies

You can use the Cloud Console or gcloud command-line tool to inspect the guest policies associated with your project.

Console

In the Google Cloud Console, go to the OS Guest Policies page.

Go to the OS Guest Policies page
Select the guest policy that you want to inspect, and then click VIEW DETAILS.

gcloud

Use the os-config guest-policies list command to list all your guest policies.
```
gcloud beta compute os-config guest-policies list
```
From the list of guest policies, copy the IDs of the guest policies you would like to inspect, and then run the command to inspect each of the guest policies. Replace POLICY_ID with the policy ID that you want to review.
```
gcloud beta compute os-config guest-policies describe POLICY_ID
```

Inspecting guest policies for a particular VM instance

You can also run the lookup command for a given instance to see which configurations apply to that VM instance.

In cases where a VM instance does not seem to be appying the requirements of the expected guest policy, it is useful to inspect the list of guest policies whose assignments include that specific VM instance. This helps to determine if the Assignment field in the guest policy matches this particular VM.

Use the os-config guest-policies lookup command to list the guest policies that might be targeting a particular VM. Replace VM_NAME with the name of the VM to inspect.

gcloud beta compute os-config guest-policies lookup VM_NAME

For more information, see Viewing configurations for a VM instance.

The output from the command might reveal that the VM is not actually targeted in the VM assignment properties of the guest policy. For example, it might not be listed in the list of Labels or the list of VM name prefixes.

Recovering from failure

A failed software recipe installation is not retried. This is because the system doesn't know the state in which the failed software recipe left things. When debugging failed software recipes, we recommend deleting and recreating the VM instance.

What's next?

Learn more about the OS configuration management service.
Set up a guest policy.