Setting up VM Manager

On Compute Engine you can manage the operating systems that are running on your virtual machines (VMs) by using VM Manager.

To review the steps needed to set up your VMs to use VM Manager, see Setup overview.

After setting up VM Manager, you can view audit logs for API operations performed with the OS Config API, see Viewing VM Manager audit logs.

Note: If you already have VM Manager set up and want to update your environment to use the features available for OS inventory management (preview) and OS configuration management (preview), see Updating VM Manager.

Before you begin

• If you want to use the command-line examples in this guide, do the following:
  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.

Setup overview

To enable VM Manager, you have two options:

• Automatic enablement: applies to your entire Google Cloud project. You complete automatic enablement from the Cloud Console. You might still need to manually complete some steps.

• Manual enablement: can be done per VM or for the entire Google Cloud project.

Manual

To manually set up VM Manager, complete the following steps:

1. In your Google Cloud project, enable the OS Config API.
2. In your Google Cloud project, enable the Container Analysis API.
3. On each VM, check if the OS Config agent is installed. If the agent is not already installed, install the OS Config agent.
4. On either your project or on each VM, set instance metadata for the OS Config agent. This step is needed to make the OS Config agent active in your VM or project.
5. Verify that all VMs have an attached service account. You do not need to grant any IAM roles to this service account. VM Manager uses this service account to sign requests to the API service.
6. If your VM is running within a private VPC network and does not have public internet access, enable Private Google Access.
7. Optional. On either your project or on each VM, disable the features that you don't need.

Automatic

The first time you navigate to any of the VM Manager pages in the Cloud Console, you can choose to automatically enable VM Manager.

If you follow the guided steps, you can use the automatic enablement to complete the following:

• Enable OS Config service API on the Google Cloud project
• Enable Container Analysis API on the Google Cloud project
• Activate OS Config agents on all VMs in the Google Cloud project that have the agent installed

Supported operating systems

For the full list of operating systems and versions that support VM Manager, see Operating system details.

Enable the OS Config service API

In your Cloud project, enable the OS Config API.

Console

In the Google Cloud Console, enable the OS Config API.

Enable the OS Config API

gcloud

To enable the API run the following command:

gcloud services enable osconfig.googleapis.com

Check if the OS Config agent is installed

The OS Config agent is installed by default on Red Hat Enterprise Linux (RHEL), Debian, CentOS, and Windows images that have a build date of v20200114 or later. These agents run idly until you enable the agent metadata, and enable the service API.

Linux

To check whether your Linux VM has the agent installed, run the following command:

sudo systemctl status google-osconfig-agent

If the agent is installed and running, the output resembles the following:

google-osconfig-agent.service - Google OSConfig Agent
Loaded: loaded (/lib/systemd/system/google-osconfig-agent.service; enabled; vendor preset:
Active: active (running) since Wed 2020-01-15 00:14:22 UTC; 6min ago
Main PID: 369 (google_osconfig)
 Tasks: 8 (limit: 4374)
Memory: 102.7M
CGroup: /system.slice/google-osconfig-agent.service
        └─369 /usr/bin/google_osconfig_agent

If the agent is not installed, install the OS Config agent.

Windows

To check whether your Windows VM has the agent installed, run the following command:

PowerShell Get-Service google_osconfig_agent

If the agent is installed and running, the output resembles the following:

Status   Name               DisplayName
------   ----               -----------
Running  google_osconfig... Google OSConfig Agent

If the agent is not installed, install the OS Config agent.

Install the OS Config agent

Before you follow these steps to install the agent, check if the agent is already running on your VM.

On each VM, install the OS Config agent. You can install the OS Config agent by using one of the following options:

• Install the agent manually using the terminal.
• Use a startup script on your VMs.
• Automate the installation of OS Config on multiple VMs by using a Google Cloud's operations suite agent policy.

Install the agent manually

Use this option to install the OS Config agent on an existing VM.

To install the agent, complete the following steps:

1. Connect to the VM that you want to install the OS Config agent on.

2. Install the OS Config agent.

   Windows Server

   To install the OS Config agent on a Windows server, run the following command:

   googet -noconfirm install google-osconfig-agent
   

   Ubuntu

   To install the OS Config agent on an Ubuntu VM, run the following commands:

   1. Set up the Ubuntu repository.

      • For Ubuntu 20.04 and later versions, run the following commands:

        1. Add the Ubuntu repository.

           sudo su -c "echo 'deb http://packages.cloud.google.com/apt google-compute-engine-focal-stable main' > \
           /etc/apt/sources.list.d/google-compute-engine.list"
           

        2. Import the Google Cloud public key.

           curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | \
           sudo apt-key add -
           

      • For Ubuntu 18.04 and later versions, run the following commands:

        1. Add the Ubuntu repository.

           sudo su -c "echo 'deb http://packages.cloud.google.com/apt google-compute-engine-bionic-stable main' > \
           /etc/apt/sources.list.d/google-compute-engine.list"
           

        2. Import the Google Cloud public key.

           curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | \
           sudo apt-key add -
           

      • For Ubuntu 16.04, run the following commands:

        1. Add the Ubuntu repository.

           sudo su -c "echo 'deb http://packages.cloud.google.com/apt google-compute-engine-xenial-stable main'> \
           /etc/apt/sources.list.d/google-compute-engine.list"
           

        2. Import the Google Cloud public key.

           curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | \
           sudo apt-key add -
           

   2. Install the OS Config agent.

      sudo apt update
      sudo apt -y install google-osconfig-agent
      

   Debian

   To install the OS Config agent on a Debian VM, run the following commands:

   sudo apt update
   sudo apt -y install google-osconfig-agent
   

   Note: If you are using a VM instance that was not created from a Google-provided image or you see the error E: Unable to locate package google-osconfig-agent, you need to add the Google Cloud repository and public key.

   Adding the Google Cloud repository and public key

   If you are using a VM instance that was not created from a Google-provided image or got a "unable to locate package" error message, complete the following steps to add the Google Cloud repository and import the public key.

   After you add the repository and import the key, you can then run the commands to install the OS Config agent.

   • For Debian 9 (Stretch), run the following commands:

     1. Add the Debian repository.

        sudo su -c "echo 'deb http://packages.cloud.google.com/apt \
        google-compute-engine-stretch-stable main'> /etc/apt/sources.list.d/google-compute-engine.list"
        

     2. Import the Google Cloud public key.

        curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | \
        sudo apt-key add -
        

   • For Debian 10 (Buster), run the following commands:

     1. Add the Debian repository.

        sudo su -c "echo 'deb http://packages.cloud.google.com/apt \
        google-compute-engine-buster-stable main'> /etc/apt/sources.list.d/google-compute-engine.list"
        

     2. Import the Google Cloud public key.

        curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | \
        sudo apt-key add -
        

   RHEL/CentOS

   To install the OS Config agent on a RHEL 7/8 or CentOS 7/8 VM, run the following command:

   sudo yum -y install google-osconfig-agent
   

   SLES/openSUSE

   To install the OS Config agent on a SLES or openSUSE VM, run the following commands:

   1. Set up the SLES repository.

      • For SLES 12, run the following command:

        sudo su -c "cat > /etc/zypp/repos.d/google-compute-engine.repo <<EOM
        [google-compute-engine]
        name=Google Compute Engine
        baseurl=https://packages.cloud.google.com/yum/repos/google-compute-engine-sles12-stable
        enabled=1
        gpgcheck=1
        repo_gpgcheck=0
        gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg
          https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
        EOM"
        

      • For SLES 15 and OpenSUSE 15, run the following command:

        sudo su -c "cat > /etc/zypp/repos.d/google-compute-engine.repo <<EOM
        [google-compute-engine]
        name=Google Compute Engine
        baseurl=https://packages.cloud.google.com/yum/repos/google-compute-engine-sles15-stable
        enabled=1
        gpgcheck=1
        repo_gpgcheck=0
        gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg
          https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
        EOM"
        
        

   2. Import the GPG keys for Google Cloud.

      sudo rpm --import https://packages.cloud.google.com/yum/doc/yum-key.gpg \
      --import https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
      

   3. Install the OS Config agent.

      sudo zypper -n --gpg-auto-import-keys install --from google-compute-engine google-osconfig-agent
      

Install the agent using a startup script

You can also use the manual installation commands to create a startup script that installs the OS Config agent during VM creation.

1. Copy the manual commands for your operating system.

2. Provide the startup script to your VM creation method.

   For example, if you are using the gcloud compute instances create command to create a new Debian 9 VM, your command resembles the following:

   gcloud compute instances create VM_NAME \
      --image-family=debian-9 --image-project=debian-cloud \
      --metadata startup-script='#! /bin/bash
      sudo apt update
      sudo apt -y install google-osconfig-agent'

   Replace VM_NAME with the name of your VM.

3. Verify that the startup script completes. To verify whether the startup script completes, review the logs or check the serial console.

Set the metadata values

You can either set instance metadata on each VM or project metadata that applies to all VMs in your project.

On your Cloud project or VM, set the enable-osconfig metadata value to TRUE. Setting the enable-osconfig metadata value to TRUE enables the following:

• OS patch management
• OS configuration management

• OS inventory management.

  • For OS inventory management (earlier version) to work, you must also set the enable-guest-attributes metadata value to TRUE.
  • For OS inventory management (preview), you do not need to enable guest attributes.

  For more information about the two OS inventory management versions, see OS inventory management versions.

Pro Tip: After you have set the enable-osconfig metadata value to TRUE, you can disable the features that you don't need.

Console

You can apply the metadata values on your Cloud projects or VMs using one of the following options:

• Option 1: Set enable-osconfig in project-wide metadata, so that it applies to all of the VMs in your project.

  1. In the Google Cloud Console, go to the Metadata page.

     Go to Metadata

  2. Click Edit.

  3. Add the following metadata entry:

     Key: enable-osconfig
     Value: TRUE

     For OS inventory management (earlier version) to work, you need to set both enable-osconfig and enable-guest-attributes:

     • Key: enable-osconfig
       Value: TRUE
     • Key: enable-guest-attributes
       Value: TRUE

  4. Click Save to apply the changes.

• Option 2: Set enable-osconfig in VM metadata when you create an instance.

  1. In the Google Cloud Console, go to the Create an instance page.

     Go to Create an instance

  2. Specify the VM details.

  3. Expand the Networking, disks, security, management, sole tenancy section, and do the following:

     1. Expand the Management section.

     2. In the Metadata section, click Add item and add the following metadata entries:

        Key: enable-osconfig
        Value: TRUE.

        For OS inventory management (earlier version) to work, you need to set both enable-osconfig and enable-guest-attributes:

        • Key: enable-osconfig
          Value: TRUE
        • Key: enable-guest-attributes
          Value: TRUE

  4. To create the VM, click Create.

• Option 3: Set enable-osconfig in metadata of an existing VM.

  1. In the Google Cloud Console, go to the VM instances page.

     Go to VM instances

  2. Click the name of the VM for which you want to set the metadata value.

  3. On the Instance details page, click Edit to edit the settings.

  4. Under Custom metadata, add the following metadata entries:

     Key: enable-osconfig
     Value: TRUE.

     For OS inventory management (earlier version) to work, you need to set both enable-osconfig and enable-guest-attributes:

     • Key: enable-osconfig
       Value: TRUE
     • Key: enable-guest-attributes
       Value: TRUE

  5. Click Save to apply your changes to the VM.

gcloud

Use the project-info add-metadata or the instances add-metadata command with the --metadata=enable-osconfig=TRUE flag.

Note: To enable OS inventory management, you must set both enable-osconfig and enable-guest-attributes.

You can apply the metadata values on your projects or VMs using one of the following options:

• Option 1: Set enable-osconfig in project-wide metadata, so that it applies to all of the instances in your project:

  gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata=enable-osconfig=TRUE
  

  For OS inventory management (earlier version) to work, you need to set both enable-osconfig and enable-guest-attributes:

  gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata=enable-guest-attributes=TRUE,enable-osconfig=TRUE
  

  Replace PROJECT_ID with your project ID.

• Option 2: Set enable-osconfig in metadata of an existing instance.

  gcloud compute instances add-metadata VM_NAME \
    --metadata=enable-osconfig=TRUE
  

  For OS inventory management (earlier version) to work, you need to set both enable-osconfig and enable-guest-attributes:

  gcloud compute instances add-metadata VM_NAME \
    --metadata=enable-guest-attributes=TRUE,enable-osconfig=TRUE
  

  Replace VM_NAME with the name of your VM.

• Option 3: Set enable-osconfig in instance metadata when you create an instance.

  gcloud compute instances create VM_NAME \
    --metadata=enable-osconfig=TRUE
  

  For OS inventory management (earlier version) to work, you need to set both enable-osconfig and enable-guest-attributes:

  gcloud compute instances create VM_NAME \
    --metadata=enable-guest-attributes=TRUE,enable-osconfig=TRUE
  

  Replace VM_NAME with the name of your VM.

API

You can set the metadata value at either the Cloud project or instance level.

• For instructions on setting project-wide metadata, follow the API instructions for setting project-wide custom metadata.
• For instructions on setting instance metadata, follow the API instructions for setting instance metadata.

The following key-value pair is required as part of the metadata property:

• Key: enable-osconfig
  Value: TRUE

For OS inventory management, also add the following key-value pair:

• Key: enable-guest-attributes
  Value: TRUE

Disable features that you don't need

Note: Disabling features is an optional step.

For features that you might not need, you can disable them by setting the following metadata values: osconfig-disabled-features=FEATURE1,FEATURE2.

Replace FEATURE1,FEATURE2 with any of the following values:

• OS inventory management: osinventory
• OS patch management: tasks
• OS configuration management: guestpolicies

You can set these values using either the Google Cloud Console, the gcloud command-line tool, or the Compute Engine API.

Console

You can disable the metadata values on your Cloud projects or VMs by using one of the following options:

• Option 1: Disable feature in project-wide metadata so that it applies to all of the instances in your project.

  1. In the Google Cloud Console, go to the Metadata page.

     Go to Metadata

  2. Click Edit.

  3. Add the following metadata entry:

     Key: osconfig-disabled-features
     Value: FEATURE1,FEATURE2

     For example:
     Key: osconfig-disabled-features
     Value: osinventory,guestpolicies

  4. Click Save to apply the changes.

• Option 2: Disable feature in metadata of an existing VM.

  1. In the Google Cloud Console, go to the VM instances page.

     Go to VM instances

  2. Click the name of the VM on which you want to set the metadata value.

  3. On the Instance details page, click Edit to edit the VM settings.

  4. Under Custom metadata, add the following metadata entries:

     Key: osconfig-disabled-features
     Value: FEATURE1,FEATURE2

     For example:
     Key: osconfig-disabled-features
     Value: osinventory

  5. Click Save to apply your changes to the VM.

gcloud

Use the project-info add-metadata or the instances add-metadata gcloud command with the --metadata=osconfig-disabled-features flag.

If you are disabling multiple features, the flag must have the format --metadata=osconfig-disabled-features=FEATURE1,FEATURE2. See example 2.

Examples

Example 1 To disable OS patch management at the Cloud project level using the gcloud command-line tool, run the following command:

gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata=osconfig-disabled-features=tasks

Example 2 To disable OS configuration management and OS inventory management at the project level using the gcloud command-line tool, run the following command:

gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata=osconfig-disabled-features=osinventory,guestpolicies

Replace PROJECT_ID with your project ID.

API

You can set the metadata value at either the Cloud project or instance level.

• For instructions on setting project-wide metadata, follow the API instructions for setting project-wide custom metadata.
• For instructions on setting instance metadata, follow the API instructions for setting instance metadata.

The following key-value pair is required as part of the metadata property:

• Key: osconfig-disabled-features
  
• Value: Can be any one or a combination of the following flags:
  • osinventory
  • tasks
  • guestpolicies

Requirements for an active OS Config agent

For the OS Config agent to be considered active and billable, it must satisfy all of the following requirements:

• VM Manager must be set up.

• The VM must be in RUNNING state and the OS Config agent must be communicating with the OS Config service.

  If a VM is stopped, suspended, or disconnected from the network, the agent on that VM is not counted as an active agent.

Verify the setup

After completing the setup procedure, you can verify the setup by using the verification checklist.

What's next?

• Create an OS policy assignment.
• View operating system details.
• Create patch jobs.
• Learn more about the VM Manager.