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
   export UPWIND_SCANNER_MIN_HOST_MEM=0

   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, so the image doesn't depend on the installer's defaults.
   UPWIND_SCANNER_MIN_HOST_MEM	Even with UPWIND_SCANNER_ENABLED=true, the installer skips the Scanner on a build instance with less memory than this threshold, so no instance launched from the image has a Scanner. Setting it to 0 creates the Scanner service and timer regardless of the build instance size. Instances launched from the image don't re-check memory at first boot, so use the image only on instance types with 8 GiB of memory or more, or set enable-scans: false on smaller ones.

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 -fsSL 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.timer

   If the Scanner is enabled, also disable its timer:

   sudo systemctl disable upwind-agent-scanner.timer

5. Remove the credentials and the update timer setting from the image. The installer writes them to /etc/upwind/agent.yaml, so delete the auth-client-id, auth-client-secret, and update-timer lines from that file before you capture the image. Removing update-timer lets each instance pick its own random update minute at first boot, instead of every instance updating at the same minute. If you exported the credentials in an interactive shell, also clear the shell history (history -c and remove ~/.bash_history). If you passed them in cloud-init user data, run cloud-init clean.

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.

   If the image includes the Scanner, also export UPWIND_SCANNER_MEMORYMAX and UPWIND_SCANNER_MEMORYHIGH sized for the instance type. Otherwise the Scanner keeps the memory limits calculated from the build instance's memory. Include a unit suffix, for example UPWIND_SCANNER_MEMORYMAX=3276M, because a value without a suffix is read as bytes. By default, MemoryMax is 20% of host memory, capped at 4096M, and MemoryHigh is 100M below it. Refer to Resource Limits.

2. Apply the configuration and start the services:

   curl -fsSL 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.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 or tracefs.
• 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.