Golden Images and Ephemeral Collectors

This document will guide the reader through creating golden images for systems such as Citrix XenDesktop. It will also explain how to use the ephemeral label.

Golden Images

Creating a golden image for systems like Citrix XenDesktop, VMware, and others is quite simple. The basic process is to run your golden image, install the Bindplane Distro for OpenTelemetry (BDOT), and then edit the newly installed collector's manager.yaml to trim it back to the bare minimum needed.

Step 1: Install BDOT

The first step, is to install BDOT using the one liner obtained from within the Bindplane UI, as described in the getting started guide.

Step 2: Edit the manager.yaml file

The manager.yaml file location varies by operating system. On Linux/UNIX/MacOS, the default path is /opt/observiq-otel-collector/manager.yaml and on Windows it is C:/Program Files/observIQ OpenTelemetry Collector/manager.yaml.

The contents of this file should be simplified down to:

endpoint: <YOUR_ENDPOINT_WEBSOCKET_URL>
secret_key: <YOUR_PROJECT_ULID>
labels: ephemeral=true,configuration=<THE_NAME_OF_THE_CONFIGURATION_TO_ATTACH>

This is the minimal information needed, and most of the other information options need to be removed so that they get generated (and are unique) on first connection to the Bindplane server. Additionally, the ephemeral=true label must be present, and this will be explained further in the next section.

Ephemeral Collectors

By definition, ephemeral collectors are those that are expected to be transient. To appear, do some work for awhile, and then go away and never come back. This could be anything from virtual desktops, such as Citrix XenDesktop, to things such as Google Managed Instance Groups that are similar to Kubernetes but for VMs.

There are basically 2 ways to assign the ephemeral tag: 1. as discussed in the previous section, one can have a static golden image that includes the ephemeral label; and 2. one can also pass it into the install script (Linux/UNIX) along with the --quiet flag.

What Does "Ephemeral" Actually Do?

The purpose of the ephemeral tag, is to clean up agents that aren't likely to ever come back. If they do come back, the system will just treat them as a new agent again while using the previous agent ID.

This is done by evaluating all disconnected agents with this tag. If they have been disconnected 15 or more minutes, they get purged from the system.

Installing The Collector as Ephemeral

There are 2 ways to install BDOT as ephemeral agents:

1. Using the install script, and passing everything as script arguments

2. Using DevOps tools such as Anisble, Chef, Puppet, etc...

Using The Install Script

Using the install script is a great way to handle it for systems such as Google Managed Instance Groups (MIG). There are a few required parameters:

• -q or --quiet - This is required to prevent the install script from asking interactive questions

• -e 'BINDPLANE_WS_URL' or --endpoint 'BINDPLANE_WS_URL' - This is required to set the websocket endpoint URL in the BDOT manager.yaml

• -s 'SECRET_KEY' or --secret-key 'SECRET_KEY' - This is the secret key that authenticates the collector to the appropriate project in Bindplane

• -k ephemeral=true,configuration=YOUR_DESIRED_CONFIGURATION or --labels ephemeral=true,configuration=YOUR_DESIRED_CONFIGURATION - This makes the collector ephemeral, and assigns it to the configuration it should run.

• (Optional) -v BDOT_VERSION_TAG or --version BDOT_VERSION_TAG - To specify a specific collector version to install

Below is my Google MIG install script:

#! /bin/bash
sudo sh -c "$(curl -fsSlL 'https://github.com/observIQ/bindplane-otel-collector/releases/latest/download/install_unix.sh')" install_unix.sh -q -e 'wss://app.bindplane.com/v1/opamp' -s 'SECRET_KEY' -k 'configuration=intermediate-gateway,ephemeral=true'

In the MIG script, I do not specify a version because I always want the latest at the time that MIG VM deploys. It requests to be assigned to intermediate-gateway configuration, and the ephemeral=true label.

Using A DevOps Tool

When using a tool such as Anisble, Chef, Puppet or others; the only thing that needs to be done is write a manager.yaml that is the same as the one in the Golden Images section above, repeated here for convenience:

endpoint: <YOUR_ENDPOINT_WEBSOCKET_URL>
secret_key: <YOUR_PROJECT_ULID>
labels: ephemeral=true,configuration=<THE_NAME_OF_THE_CONFIGURATION_TO_ATTACH>

This can be done in whatever fashion is most appropriate for the tool being used, though I recommend making use of templates if your tool allows it.

Bindplane provides an ansible role.