This package contains the Python guest environment which was historically installed on Google supported Compute Engine Linux images. It has been superceded by the guest agent, but is still provided here for interested consumers. The google_compute_engine
library is also available as a PyPI package.
Table of Contents
The Linux guest environment is made up of the following components:
The Linux guest environment is written in Python and is version agnostic between Python 2.6 and 3.7. There is complete unittest coverage for every Python library and script. The design of various guest libraries, daemons, and scripts, are detailed in the sections below.
The Python libraries are shared with each of the daemons and the instance setup tools.
The guest environment relies upon retrieving content from the metadata server to configure the VM environment. A metadata watching library handles all communication with the metadata server.
The library exposes two functions:
Metadata server requests have custom retry logic for metadata server unavailability; by default, any request has one minute to complete before the request is cancelled. In case of a brief network outage where the metadata server is unavailable, there is a short delay between retries.
The Google added daemons and scripts write to the serial port for added transparency. A common logging library is a thin wrapper around the Python logging module. The library configures appropriate SysLog handlers, sets the logging formatter, and provides a debug options for added logging and console output.
A configuration file allows users to disable daemons and modify instance setup behaviors from a single location. Guest environment daemons and scripts need a mechanism to integrate user settings into the guest. A configuration management library retrieves and modifies these settings.
The library exposes the following functions:
Guest environment daemons and scripts use a common library for file management. The library provides the following functions:
flock
and releases the lock on exit.A network-utilities library retrieves information about a network interface. The library is used for IP forwarding and for setting up an Ethernet interface on boot. The library exposes a GetNetworkInterface
function that retrieves the network interface name associated with a MAC address.
The guest environment daemons import and use the common libraries described above. Each daemon reads the configuration file before execution. This allows a user to easily disable undesired functionality. Additional daemon behaviors are detailed below.
The accounts daemon is responsible for provisioning and deprovisioning user accounts. The daemon grants permissions to user accounts, and updates the list of authorized keys that have access to accounts based on metadata SSH key updates. User account creation is based on adding and remove SSH Keys stored in metadata.
The accounts management daemon has the following behaviors.
google-sudoers
Linux group.google-sudoers
group.The clock skew daemon is responsible for syncing the software clock with the hypervisor clock after a stop/start event or after a migration. Preventing clock skew may result in system time has changed
messages in VM logs.
The network daemon uses network interface metadata to manage the network interfaces in the guest by performing the following tasks:
66
. This ID is a namespace for daemon configured IP addresses.Instance setup runs during VM boot. The script configures the Linux guest environment by performing the following tasks.
boto
config for using Google Cloud Storage.The defaults configuration file incorporates any user provided setting in /etc/default/instance_configs.cfg.template
and does not override other conflicting settings. This allows package updates without overriding user configuration.
Metadata scripts implement support for running user provided startup scripts and shutdown scripts. The guest support for metadata scripts is implemented in Python with the following design details.
startup-script
and startup-script-url
) both are executed.startup-script
and startup-script-url
) a URL is executed first.Users of Google provided images may configure the guest environment behaviors using a configuration file. To make configuration changes, add settings to /etc/default/instance_configs.cfg.template
. If you are attempting to change the behavior of a running instance, run /usr/bin/google_instance_setup
before reloading the affected daemons.
Linux distributions looking to include their own defaults can specify settings in /etc/default/instance_configs.cfg.distro
. These settings will not override /etc/default/instance_configs.cfg.template
. This enables distribution settings that do not override user configuration during package update.
The following are valid user configuration options.
Section | Option | Value |
---|---|---|
Accounts | deprovision_remove | true makes deprovisioning a user destructive. |
Accounts | groups | Comma separated list of groups for newly provisioned users. |
Accounts | useradd_cmd | Command string to create a new user. |
Accounts | userdel_cmd | Command string to delete a user. |
Accounts | usermod_cmd | Command string to modify a user's groups. |
Accounts | gpasswd_add_cmd | Command string to add a user to a group. |
Accounts | gpasswd_remove_cmd | Command string to remove a user from a group. |
Accounts | groupadd_cmd | Command string to create a new group. |
Daemons | accounts_daemon | false disables the accounts daemon. |
Daemons | clock_skew_daemon | false disables the clock skew daemon. |
Daemons | ip_forwarding_daemon | false (deprecated) skips IP forwarding. |
Daemons | network_daemon | false disables the network daemon. |
InstanceSetup | host_key_types | Comma separated list of host key types to generate. |
InstanceSetup | optimize_local_ssd | false prevents optimizing for local SSD. |
InstanceSetup | network_enabled | false skips instance setup functions that require metadata. |
InstanceSetup | set_boto_config | false skips setting up a boto config. |
InstanceSetup | set_host_keys | false skips generating host keys on first boot. |
InstanceSetup | set_multiqueue | false skips multiqueue driver support. |
IpForwarding | ethernet_proto_id | Protocol ID string for daemon added routes. |
IpForwarding | ip_aliases | false disables setting up alias IP routes. |
IpForwarding | target_instance_ips | false disables internal IP address load balancing. |
MetadataScripts | default_shell | String with the default shell to execute scripts. |
MetadataScripts | run_dir | String base directory where metadata scripts are executed. |
MetadataScripts | startup | false disables startup script execution. |
MetadataScripts | shutdown | false disables shutdown script execution. |
NetworkInterfaces | setup | false skips network interface setup. |
NetworkInterfaces | ip_forwarding | false skips IP forwarding. |
NetworkInterfaces | dhcp_command | String path for alternate dhcp executable used to enable network interfaces. |
Setting network_enabled
to false
will skip setting up host keys and the boto
config in the guest. The setting may also prevent startup and shutdown script execution.