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 Google Cloud CLI or REST.
Before you begin
- Review OS Config quotas.
-
If you haven't already, 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 as follows.
Select the tab for how you plan to use the samples on this page:
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.
-
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.
REST
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
REST
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.
List 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
REST
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 havemy-package
installed, keepsmy-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.
- If a new VM is added to
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
REST
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.
View 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 VM_NAME \ --zone=ZONE
Replace the following:
VM_NAME
: the name of the VM instance.ZONE
: the zone for the VM instance.
REST
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/VM_NAME:lookupEffectiveGuestPolicy
Replace the following:
PROJECT_ID
: your project ID.ZONE
: the zone for the VM instance.VM_NAME
: the name of your VM instance.
Troubleshooting
Inspect guest policies
You can use the Google Cloud console or Google Cloud CLI to inspect the guest policies associated with your project.
Console
In the Google Cloud console, 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
Inspect guest policies for a specific VM
You can run the lookup
command for a given VM to see which
configurations apply to that VM.
In cases where a VM does not seem to be applying 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 the following steps:
- Rename the software recipe.
- Delete and recreate the guest policy using the renamed software recipe.
For more troubleshooting steps, see Troubleshooting VM Manager.
What's next?
- Learn more about the OS guest policies (legacy).
- Set up a guest policy.