fct-kiwi 1.10.0

Balena fleet management

FCT-Kiwi

A command-line tool for Balena device configuration management, allowing you to easily change, clone, purge, retrieve, and manage variables across devices and fleets.

Table of Contents

• FCT-Kiwi
  • Table of Contents
  • Installation
  • Authentication
    • Environment variables
  • Commands
    • Usage in other scripts
    • Change
    • Clone
    • Purge
    • Get
    • Delete
    • Move
    • Schedule
      • Schedule change
      • Schedule update
    • Initialize
    • Rename
    • Converter
    • Pin
  • File Format
    • Changing variables
    • Scheduling
      • Variable changes
      • Pin devices to release
    • Tags by version
  • Error Handling
  • Dependencies
  • Author

Installation

pip install fct-kiwi

Authentication

To use this tool, you need to set up some environment variables if you haven't already, please refer to the Environment variables section to set all the variables that don't have a default, this can be done in your terminal as environment variables, for example:

export BALENA_API_KEY="your_api_key_here"

Or an environment variables file to handle all at once can be defined as shown in the next section.

Environment variables

By default, this is the order in which variables are read:

1. .env file
2. default
3. os.environ

Other variables might be needed for certain commands and are set by default, but can be overridden if necessary.

1. Create a .env file in the same directory as the script or set the path into your environment as export FCT_ENV_PATH="/path/to/my/.env"
2. Add your Balena API key: BALENA_API_KEY=your_api_key_here
3. Add other variables as needed.

Note:

✔ in the Required column means the variable is required for the script to function.

Empty Default fields mean the variable is optional unless needed by a specific command.

Variable	Description	Default	Required
BALENA_API_KEY	Balena API key		✔
PROJECT_ID	GCP Project
SPREADSHEET_NAME	Google Sheets file for logging	SD Logs
LOCATION_ID	GCP Queue location
QUEUE_ID	GCP Queue identifier
AUTHOR	Google Sheets author signature	default
GOOGLE_APPLICATION_CREDENTIALS	GCP Service account file
TAGS_BY_VERSION_FILE	Tags by version file location	tags_by_version.json

Commands

Usage in other scripts

To use this packages functionality in other scripts simply import the functions you need from the following list.

from fleet_control import clone, change, etc...

Otherwise you can use all commands from your terminal.

Change

Change or create specified variable(s) to target device(s).

# Basic usage
fct change 'VAR_NAME=0=*' 4X002 4X003

# Change multiple variables
fct change 'VAR_NAME=0=* ANOTHER_VAR=value=service_name' 4X002 4X003

# Target a fleet
fct change 'VAR_NAME=0=*' FLEET_NAME

# Use a file containing variables
fct change --file variables.txt '' 4X002 4X003

Clone

Clone configuration from a source device or fleet to target device(s).

# Clone from one device to others
fct clone 4X001 4X002 4X003

# Clone from a fleet to a device
fct clone FLEET_NAME 4X002

# Clone from a fleet to another fleet
fct clone FLEET_NAME ANOTHER_FLEET_NAME

# Clone with exclusions
fct clone --exclude "VAR1 VAR2" 4X001 4X002 4X003

Purge

Purge all custom variables in target device(s).

# Purge all custom variables from devices
fct purge 4X001 4X002 4X003

# Purge with exclusions
fct purge --exclude "VAR1 VAR2" 4X001 4X002 4X003

Get

Fetch variable value(s) for a device.

# Get a specific variable
fct get 4X001 VAR_NAME

# Get all custom variables
fct get 4X001 --custom

# Get all variables (device + fleet)
fct get 4X001 --all-vars

# Save variables to a file
fct get 4X001 --output result.json

Delete

Delete the overwritten value for specified variable(s) on the target device(s).

# Delete a variable
fct delete 'VAR_NAME=0=*' 4X002 4X003

# Delete multiple variables
fct delete 'VAR1=value=service VAR2=value=*' 4X002 4X003

# Delete variables from a file
fct delete --file variables.txt '' 4X002 4X003

Move

Move target(s) from its current fleet to a specified fleet.

# Move devices to a new fleet
fct move FLEET_NAME 4X001 4X002 4X003

# Move keeping custom device variables
fct move --keep-vars FLEET_NAME 4X001 4X002 4X003

# Move keeping custom device and service variables
fct move --keep-service-vars FLEET_NAME 4X001 4X002 4X003

# Move with cloning (keep custom and previous fleet variables)
fct move --clone FLEET_NAME 4X001 4X002 4X003

# Move and pin to specific release
fct move --semver "1.3.11+rev87" FLEET_NAME 4X001 4X002 4X003

Schedule

Schedule functions to run at a specific time. Service account file path required for creating the task. Set with the GOOGLE_APPLICATION_CREDENTIALS variable set in the .env file or in your environment.

Required environment variables for all schedule commands:

• PROJECT_ID (GCP Project)
• LOCATION_ID (GCP Queue location)
• QUEUE_ID (GCP Queue identifier)
• SERVICE_ACCOUNT (path to your Google service account credentials)

Schedule change

Change or create specified variable(s) to target device(s).

# Schedule a change for tomorrow at 3 AM (default)
fct schedule change 'VAR_NAME=0=main' 4X001 4X002

# Schedule with a specific date and time
fct schedule change --date '2025-02-25 12:06:00' 'VAR_NAME=0=main' 4X001 4X002

# Schedule with a file containing variables
fct schedule change --date '2025-02-25 12:06:00' --file vars.json 

# Schedule with different timezone
fct schedule change --tz 'America/New_York' 'VAR_NAME=0=main' 4X001 4X002

Schedule update

Pins the specified devices to the selected release in that fleet.

# Schedule a pin to release for tomorrow at 3 AM (default)
fct schedule update FLEET_NAME 1.3.19+rev43 4X001 4X002

# Direct input with date and timezone
fct schedule update --date '2025-04-01T15:30:00Z' --tz 'Europe/London' FLEET_NAME 1.3.19+rev43 4X001 

# Use a JSON file for targets and release info
fct schedule update --date '2025-02-25 12:06:00' --file file.json 

Initialize

Initialize a target device with previous device tags, remove old device, delete default config variables, and move to specified fleet.

# Initialize a device and move it to a fleet
fct initialize FLEET_NAME 4X001

Rename

Rename a target device with new ID. Optional new tags for corresponding version read from configuration file. Configuration file path set with the TAGS_BY_VERSION_FILE variable set in the .env file or in your environment.

Required environment variables:

• SERVICE_ACCOUNT (path to your Google service account credentials)
• SPREADSHEET_NAME (Google Sheets file for logging)

# Rename a device
fct rename 4A001 4B222

# Rename a device and specify new version
fct rename --version "4.3F" 4A001 4B222

Converter

Convert a shell env var file to a JSON config file. All variables starting with NODE_ go to env_vars. All others go to service_vars > main.

# Convert a shell env var file to JSON config
fct converter input.sh output.json

Pin

Pin target device(s) to a specific fleet release. If no targets are specified, pins the entire fleet. You can also pin all devices in a fleet or exclude specific devices.

# Pin specific devices to a release
fct pin FLEET_NAME 4X001 4X002 4X003

# Pin a fleet to a specific release
fct pin FLEET_NAME --semver 1.3.12+rev12

# Pin all devices in a fleet
fct pin FLEET_NAME --all

# Pin all devices except some
fct pin FLEET_NAME --all --exclude 4X001 4X002

File Format

Changing variables

When using the --file option, the file should contain JSON formatted variables:

{
  "env_vars": {
      "VAR1_NAME": "VAR1_VALUE",
      "VAR2_NAME": 2
  },
  "service_vars": {
      "main": {
        "SERVICE_VAR1_NAME": "SERVICE_VAR1_VALUE",
        "SERVICE_VAR2_NAME": "SERVICE_VAR2_VALUE"
      }
  }
}

Scheduling

Variable changes

{
  "targets": [
    "TARGET1_NAME",
    "TARGET2_NAME"
  ],
  "variables": {
    "env_vars": {
        "VAR1_NAME": "VAR1_VALUE",
        "VAR2_NAME": 2
    },
    "service_vars": {
        "main": {
          "SERVICE_VAR1_NAME": "SERVICE_VAR1_VALUE",
          "SERVICE_VAR2_NAME": "SERVICE_VAR2_VALUE"
        }
    }
  }
}

Pin devices to release

{
    "targets": [
        "TARGET1_NAME",
        "TARGET2_NAME"
    ],
    "fleet": "FLEET_NAME",
    "release": "RELEASE_SEMVER"
}

Tags by version

{
    "4.3B":{
        "Tag1": "value1",
        "Tag2": "value2",
    }
}

Error Handling

The tool will return appropriate error messages if:

• The Balena API key is not set
• No variables are provided when required
• Target devices or fleets cannot be found
• API requests fail

Dependencies

• balena-sdk
• click
• python-dotenv

Author

Juan Pablo Castillo - [e-mail]