Golden Images

You can bake the Upwind Sensor into a golden image, such as an Amazon Machine Image (AMI), so that every instance launched from the image runs the Sensor. The process is split into two stages:

1. At image build time, install the Sensor binaries and systemd units, but keep the Sensor from starting and registering from the short-lived build instance.
2. At first boot of each instance, inject the credentials, apply the configuration, and start the services.

At Image Build Time

1. On the build instance, set the following environment variables before running the installer:

   export UPWIND_CLIENT_ID="<CLIENT_ID>"
   export UPWIND_CLIENT_SECRET="<CLIENT_SECRET>"
   export UPWIND_REGION="<REGION>"
   export UPWIND_AGENT_INSTALL_ONLY=true
   export UPWIND_SCANNER_ENABLED=true

   Variable	Why it matters for a golden image
   UPWIND_CLIENT_ID, UPWIND_CLIENT_SECRET	The installer requires credentials. You remove them from the image in a later step.
   UPWIND_REGION	Set the region at install time. The region requires additional configuration keys that the installer writes when the region is set at install time, so adding region to /etc/upwind/agent.yaml afterwards is not enough. The hostconfig service has its own configuration file, /etc/upwind/agent-hostconfig.yaml.
   UPWIND_AGENT_INSTALL_ONLY	Prevents the installer from starting the Sensor when the installation completes.
   UPWIND_SCANNER_ENABLED	Set this explicitly to true or false. If you leave it unset, the installer decides based on the memory of the build instance: on a host below the UPWIND_SCANNER_MIN_HOST_MEM threshold, the Scanner service and timer are not created at all, so no instance launched from the image has a Scanner.

2. Decide how the Sensor version is managed. If agent-version is unset or stable, each instance automatically updates to the latest stable release. If you pin a specific version, rebuilding the image becomes your upgrade mechanism. See the agent-version note under Configuring the Upwind Sensor.

3. Install the Sensor:

   curl -s https://get.upwind.io/sensor.sh | bash -s install

4. Disable the Sensor services. UPWIND_AGENT_INSTALL_ONLY does not stop the services from starting on boot, so without this step the Sensor starts on the build instance the next time it reboots, and on every instance before first-boot provisioning runs:

   sudo systemctl disable upwind-agent.service upwind-agent-hostconfig.service upwind-agent-update.timer

   If the Scanner is enabled, also disable its timer:

   sudo systemctl disable upwind-agent-scanner.timer

5. Remove the credentials from the image. The installer writes them to /etc/upwind/agent.yaml, so delete the auth-client-id and auth-client-secret lines from that file before you capture the image.

warning

If you keep the credentials in the image, anyone who can launch or copy the image can read the client secret. Treat such an image as a secret-bearing artifact and restrict who it is shared with.

At First Boot

In the instance user data or cloud-init script, provide the credentials and start the services:

1. Retrieve the client credentials from your secrets store, such as AWS Secrets Manager or AWS Systems Manager Parameter Store, and export them as UPWIND_CLIENT_ID and UPWIND_CLIENT_SECRET. Export any other per-environment environment variables at the same time.

2. Apply the configuration and start the services:

   curl -s https://get.upwind.io/sensor.sh | bash -s configure
   systemctl enable --now upwind-agent.service
   systemctl enable --now upwind-agent-hostconfig.service
   systemctl enable --now upwind-agent-update.timer
   systemctl enable --now upwind-agent-scanner.timer

   The configure step writes the exported credentials and settings to the configuration files. Omit the upwind-agent-scanner.timer line if you built the image with UPWIND_SCANNER_ENABLED=false.

3. Make sure /etc/upwind/agent.yaml is readable by root only:

   chmod 600 /etc/upwind/agent.yaml

Before You Build

• The base image must meet the host requirements, including the kernel version, architecture, and a read-write debugfs.
• If instances launched from the image can't reach the Instance Metadata Service (IMDS), set UPWIND_AGENT_CLOUD_PROVIDER and UPWIND_AGENT_CLOUD_ACCOUNT_ID so the Sensor can determine where it runs.