Configuring updates of dynamic host agents

The dynamic host agents in Instana automatically update to new versions of bundles, such as agent, sensors, and discoveries. You can control this updates as you require, by setting a preferred update schedule, by pinning a version, or by disabling the updates altogether.

The automatic updates apply only to Instana dynamic host agents. If you use a static host agent, you must manually update the agent by installing the required host agent packages. You can use technologies such as Ansible or Terraform to perform the update. For more information on the difference between static and dynamic agents, see Host agent types.

The automatic updates of the dynamic host agents update only the agent bundles. To update the agent bootstrap, you must reinstall the agent manually. You are suggested to periodically (for example, every 6 months) reinstall the agent to make sure that you get the necessary bootstrap changes. See the Planned updates to the agent section plan your manual updates to avoid risks.

Setting agent version update controls

Dynamic agents check for new versions every day between 4:15 AM and 4:45 AM by default. You can schedule this automatic check to run at a specific frequency, time, and days. You can also disable it if you do not want the agent to check for updates. Additionally, the agents run their version check and updates randomly over a specified period to avoid congesting the network with synchronized requests. You can modify this period by using the jitter setting and set the time range in which the agent restarts.

Scheduled updates are not suggested for production environments that run critical workloads. If you select this approach, make sure to run the scheduled updates during a maintenance window and then restart the workloads.

You can also configure the agent to use a specific pinned version to minimize the risks in the production environment during the agent updates. This approach ensures full control over version updates. By using a pinned agent version update strategy, you can keep the agent’s capability to update itself at a specific time without manually reinstalling the agent. This approach is suggested for critical production environments.

The processes to control the agent updates and pin versions depend on whether the agent is deployed on a host or a containerized environment.

If you run multiple agents that are deployed across different environments and require a centralized version control, see Controlling agent updates with Git.

Notes:
  • Disabling automatic updates is not suggested. If you disable the automatic updates, the agent still updates to the latest version when it is restarted. In Kubernetes and Red Hat OpenShift environments, every pod restart pulls the latest agent version.
  • Instana supports agents for 6 months after their release, addressing any issues identified during this timeframe. For issues discovered after the 6-months, fixes are included in the next agent version. Therefore, you are suggested to avoid pinning agent versions for longer than 6 months to ensure access to the latest updates and fixes.

Control updates in host agents

To schedule the automatic check in host agent deployments, open the etc/instana/com.instana.agent.main.config.UpdateManager.cfg file and modify the settings as required. See the following example:

# Instana Update Manager configuration.
# AUTO for automatic updates with given schedule. OFF for no automatic updates.
mode = AUTO
# DAY for daily, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
every = DAY
# Time is hh:mm in 24 hours format.
at = 04:30
# Spread updates randomized over 30 minutes around the configured time
jitter = 30

To pin a version for the agent and stop all future updates, open the <instana-agent-dir>/etc/instana/com.instana.agent.bootstrap.AgentBootstrap.cfg file before startup and add the following configuration:

version = <sha or tag>

where sha is the SHA value of the agent version commit in the Agent Updates Git repository, and tag is the release identifier of the agent version as given in the Agent Updates - tags page.

Control updates in containerized agents

To schedule the automatic check in host agent deployments, you must use the following environment variables:

  • INSTANA_AGENT_UPDATES_FREQUENCY: Specifies the frequency of version check and update. Valid values are DAY (for daily updates), MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY or SUNDAY. You can add multiple options separated by a colon.
  • INSTANA_AGENT_UPDATES_TIME: Specifies the time at which the version check and update is run.

To pin a version for the agent and stop all future updates, use the INSTANA_AGENT_UPDATES_VERSION environment variable and specify the SHA value of the agent version commit in the Agent Updates Git repository.

For more information on these environment variables, see Environment variables for host agent.

To configure the environment variables, use either of the following methods:

  • Save your environment variable configurations under spec.agent.env in the agent custom resource file instana-agent.customresource.yaml and apply the changes by running the following command:

    kubectl apply -f instana-agent.customresource.yaml

  • Specify the configuration on the command line directly by using the flag --set agent.env.<ENVIRONMENT_VARIABLE>=<value>.

Retrieving the current version

The following host agent API endpoint provides the version of the host agent's components:

curl localhost:42699/version