Skip to content

FAQ

Jump to bottom
Nageswara Nandigam edited this page Jan 18, 2024 · 15 revisions

List of frequently asked questions:

What does "Goal state agent" mean in "waagent --version" output?

The command waagent --version displays output similar to the following.

# sudo waagent -version
WALinuxAgent-2.2.20 running on ubuntu 16.04
Python: 3.5.2
Goal state agent: 2.2.26

NOTE: waagent is typically located in /usr/sbin.

Two versions are displayed:

  1. WALinuxAgent-x.x.xx
  2. Goal state agent: x.x.xx

The agent is split into two parts.

  1. Provision handler and daemon which is WALinuxAgent-x.x.xx
  2. Extension handler which is Goalstate agent: x.x.xx

WALinuxAgent-x.x.xx represents provisioning and daemon. This version ships with the image, and is not upgraded except by the package manager. The version can be queried using the package manager.

  1. yum list WALinuxAgent for CentOS and RHEL
  2. apt list WALinuxAgent for Debian and Ubuntu
  3. zypper info python-azure-agent for SuSE

During provisioning, the agent will configure the user name and password (or SSH key), and signal Azure that provisioning has completed.

The daemon is responsible for ensuring the extension handler is always running. If the extension handler process dies, the daemon will automatically restart it.

The extension handler is responsible for managing extensions and reporting VM status. Extension Handler is auto-upgraded by default as new releases roll out. This is controlled via the configuration option AutoUpdate.Enabled in /etc/waagent.conf. A value of 'y' enables auto-update (the default), and 'n' disables it. The core functionality of the agent is contained in the extension handler, which is why we encourage users to maintain an up to date version.

NOTE: distro vendors control the setting of this flag, and not all distros default to a value of 'y'.

The relationship between the daemon and extension handler can be see using the ps command.

# ps -ef | grep -i agent
root       2058      1  0 04:49 ?        00:00:00 /usr/bin/python -u /usr/sbin/waagent -daemon
root       2063   2058  2 04:49 ?        00:08:21 python -u bin/WALinuxAgent-2.2.25-py2.7.egg -run-exthandlers

Please review the Configuration section of the documentation to learn more about /etc/waagent.conf and the options available.

AutoUpdate.Enabled Type: Boolean Default: y
Enable or disable auto-update for goal state processing; default is enabled.

Please review the How to update the Azure Linux Agent on a VM to learn more about keeping your agent up to date.

how auto-update works for Extension Handler?

The Daemon is tasked with ensuring the continuous operation of the Extension Handler, and Extension Handler initiation depends on the value of AutoUpdate.Enabled.

AutoUpdate.Enabled=y

  1. Daemon picks up the highest version downloaded in the VM and starts that version of the Extension Handler.
  2. The Extension Handler periodically checks for updates. Upon detection, it downloads the latest version and exits the process.

AutoUpdate.Enabled=n

  1. The Daemon picks up the version shipped with the image and starts that version of the Extension Handler.
  2. The Extension Handler does not check for updates to download the latest version.

New VMs: New VMs initially start with the shipped version. Upon startup, if a higher version is available, the Extension Handler will promptly download and Daemon will install it.

Existing VMs: Existing VMs also periodically check for Extension Handler updates. Upon detection of an update, it will be downloaded and installed.

NOTE: The version shipped with the image is managed by distro owners, and we do not have control over it.

AutoUpdate.Enabled vs AutoUpdate.UpdateToLatestVersion

Both flags are intended to control the auto-update for the Extension Handler, but there is a crucial difference in behavior:

AutoUpdate.Enabled:
If set to 'n', it will roll back to the version shipped with the image. This behavior has been historically implemented and changing it may disrupt users accustomed to this process. The flag is retained for legacy purposes. If the version shipped with the image is below 2.10.0.8, this flag will be used for the first agent update. Once the agent is updated to version 2.10.0.8 or higher, the new flag, AutoUpdate.UpdateToLatestVersion, takes effect.

AutoUpdate.UpdateToLatestVersion:
If set to 'n', it will not update to the latest version but will not roll back to the version shipped with the image. Introduced to address the need for users who want to control updates and stay on their current version until they choose to update. This flag takes effect from version 2.10.0.8 and higher.

Example, waagent --version

WALinuxAgent-2.2.53 running on ubuntu 18.04
Python: 3.8.2
Goal state agent: 2.2.53

Assuming the version shipped with the image is 2.2.53, and the latest published version is 2.10.0.8, since the initial agent version is below 2.10.0.8, it will adhere to the existing flag behavior.

AutoUpdate.Enabled=y
Update to the latest version (2.10.0.8)

AutoUpdate.Enabled=n
Roll back to the version (2.2.53)

Now, if the latest version installed on the VM is 2.10.0.8 and we publish a new version, say 2.11.0.0

AutoUpdate.Enabled=y and AutoUpdate.UpdateToLatestVersion=y
Update to the latest version (2.11.0.0)

AutoUpdate.Enabled=y and AutoUpdate.UpdateToLatestVersion=n
Stay on latest installed version on the vm (2.10.0.8)

AutoUpdate.Enabled=n and AutoUpdate.UpdateToLatestVersion=y|n
Roll back to the version (2.2.53)

This distinction allows users to have more control over updates, facilitating choices based on their preferences.

Clone this wiki locally