Managing your operating systems

On Compute Engine you can manage the operating systems that are running on your Virtual Machine (VM) instances by enabling the OS Config service API and installing the OS Config agent.

With the OS Config service API and the OS Config agent set up, you can get access to a variety of features that let you perform the following tasks across a group or your entire set of VM instances:

To enable these services, complete the following steps:

  1. On your project, enable the OS Config API .
  2. On each VM, check if the OS Config agent is installed .
  3. On each VM, if the agent is not already installed, install the OS Config agent .
  4. On either your project or on each VM, set the service metadata.
  5. (Optional) On either your project or on each VM, disable the features that you don't need.

To view audit logs for API operations performed with the OS Config API, see Viewing OS Config audit logs.

Before you begin

Enabling the OS Config service API

In your project, enable the OS Config API. To enable the API run the following command:

gcloud services enable osconfig.googleapis.com

Checking if the OS Config agent is installed

Some Google-provided public images already have the OS Config agent installed. VMs created using these images have the OS Config agent running on them.

The OS Config agent is installed on Red Hat Enterprise Linux (RHEL), Debian, CentOS, and Windows images that have a build date of v20200114 or later.

Linux

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

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

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

Installing 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:

Installing 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 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 --keyring /usr/share/keyrings/cloud.google.gpg add -
      • For Ubuntu 18.04, 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 --keyring /usr/share/keyrings/cloud.google.gpg add -
    2. Install the OS Config agent.

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

    Debian

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

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

    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 --keyring /usr/share/keyrings/cloud.google.gpg 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 --keyring /usr/share/keyrings/cloud.google.gpg add -

    RHEL/CentOS

    To install the OS Config agent on a RHEL or CentOS 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=1
        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, 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=1
        gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg
          https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
        EOM"
        
    2. Install the OS Config agent.

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

Installing 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 would resemble the following. Replace instance-name with the name of your VM.

    gcloud compute instances create instance-name \
       --image-family=debian-9 --image-project=debian-cloud \
       --metadata startup-script='#! /bin/bash
       sudo apt-get update
       sudo apt-get install -y google-osconfig-agent'
  3. Verify that the startup script completes. To verify whether the startup script completes, review the logs or check the serial console.

Setting the metadata values

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

  • OS inventory management
  • OS patch management
  • OS configuration management

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 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 the Metadata page

    2. Click Edit.
    3. Add the following metadata entry.

      Key: enable-osconfig Value: TRUE

      For OS inventory management 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 VM instances page.

      Go to the VM instances page

    2. Click Create.
    3. On the Create an instance page, set the properties you want for your VM.
    4. Expand Management, security, disks, networking, sole tenancy.
    5. In the Metadata section, add the following metadata entries:

      Key: enable-osconfig, Value: TRUE.

      For OS inventory management to work, you need to set both enable-osconfig and enable-guest-attributes.

      • Key: enable-osconfig Value: TRUE
      • Key: enable-guest-attributes Value: TRUE
    6. Click Create to create the instance.

  • 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 the VM instances page

    2. Click the name of the VM for which you want to set the metadata value.
    3. At the top of 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 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 gcloud command with the --metadata=enable-osconfig=TRUE flag.

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. Replace project-id with your project ID.

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

    For OS inventory management 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
    
  • Option 2: Set enable-osconfig in metadata of an existing instance. Replace instance-name with the name of your VM.

    gcloud compute instances add-metadata instance-name \
      --metadata=enable-osconfig=TRUE
    

    For OS inventory management to work, you need to set both enable-osconfig and enable-guest-attributes.

    gcloud compute instances add-metadata instance-name \
      --metadata=enable-guest-attributes=TRUE,enable-osconfig=TRUE
    
  • Option 3: Set enable-osconfig in instance metadata when you create an instance. Replace instance-name with the name of your VM.

    gcloud compute instances create instance-name \
      --metadata=enable-osconfig=TRUE
    

    For OS inventory management to work, you need to set both enable-osconfig and enable-guest-attributes.

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

API

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

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

Disabling features that you don't need

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 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 the Metadata page

    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 the VM instances page

    2. Click the name of the VM on which you want to set the metadata value.
    3. At the top of 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 below.

Examples

Example 1 To disable OS patch management at the project level using the gcloud command-line tool, run the following command. Replace project-id with your project ID.

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. Replace project-id with your project ID.

gcloud compute project-info add-metadata \
    --project project-id \
    --metadata=^:^osconfig-disabled-features=osinventory,guestpolicies

api

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

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

What's next?