Getting Started with Qbee Terraform Provider¶

The Qbee Terraform Provider enables infrastructure as code (IaC) configuration of the Qbee IoT platform using Terraform. Define device configurations declaratively, manage them through version control, and apply them at scale. The provider supports 20 resources covering configuration management, file distribution, software management, container orchestration, security, monitoring, and organizational structure.

This guide walks you through installing the provider, authenticating with your Qbee account, and distributing your first file to a device. By the end, you will have a working Terraform setup that manages Qbee file distribution declaratively.

Prerequisites:

• Terraform CLI installed (version 1.0 or later)
• A Qbee account with administrator access (sign up for a free account if you don't have one)
• Basic familiarity with Terraform concepts (providers, resources, plan/apply)

1. Install the Provider¶

From Terraform Registry¶

Create a file called main.tf with the required provider block:

terraform {
  required_providers {
    qbee = {
      source  = "qbee-io/qbee"
      version = "~> 1.3"
    }
  }
  required_version = ">= 1.0"
}

Action: Initialize Terraform to download the provider.

terraform init

Expected output:

Initializing the backend...

Initializing provider plugins...
- Finding qbee-io/qbee versions matching "~> 1.3"...
- Installing qbee-io/qbee v1.3.x...

Terraform has been successfully initialized!

2. Configure Authentication¶

Set your Qbee credentials as environment variables. Reading the password with read -sr keeps it out of your shell history:

read -sr QBEE_PASSWORD
export QBEE_PASSWORD
export QBEE_USERNAME="user@example.com"

Then use a minimal provider block in main.tf:

provider "qbee" {}

Terraform picks up QBEE_USERNAME and QBEE_PASSWORD automatically.

3. Create Your First Configuration¶

This example distributes a configuration file to all devices tagged with example. File distribution is the most common Qbee use case — once you understand this pattern, every other resource follows the same workflow.

Create a Local File¶

Create a file called app.conf in the same directory as your main.tf:

log_level=info
app_version=1.0.0

Write the Configuration¶

Add the following to your main.tf file (after the provider block):

# Upload the file to the Qbee file manager
resource "qbee_filemanager_file" "app_config" {
  path        = "/configs/app.conf"
  sourcefile  = "${path.module}/app.conf"
  file_sha256 = filesha256("${path.module}/app.conf")
}

# Distribute the file to all devices tagged "example"
resource "qbee_filedistribution" "example" {
  tag    = "example"
  extend = true

  files = [
    {
      templates = [
        {
          source      = "/configs/app.conf"
          destination = "/etc/app/app.conf"
          is_template = false
        }
      ]
    }
  ]
}

This configuration:

• Uploads app.conf from your local directory to the Qbee file manager at /configs/app.conf; file_sha256 enables Terraform to detect file content changes
• Targets all devices with the example tag
• Distributes the file to /etc/app/app.conf on each device
• Sets extend = true to inherit configuration from parent nodes

Run the Terraform Workflow¶

Step 1: Plan

terraform plan

Expected output:

Terraform will perform the following actions:

  # qbee_filemanager_file.app_config will be created
  + resource "qbee_filemanager_file" "app_config" {
      + file_sha256 = "..."
      + id          = (known after apply)
      + path        = "/configs/app.conf"
      + sourcefile  = "./app.conf"
    }

  # qbee_filedistribution.example will be created
  + resource "qbee_filedistribution" "example" {
      + extend = true
      + files  = [...]
      + id     = (known after apply)
      + tag    = "example"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

Step 2: Apply

terraform apply

Type yes when prompted to confirm.

Expected output:

qbee_filemanager_file.app_config: Creating...
qbee_filemanager_file.app_config: Creation complete after 1s [id=/configs/app.conf]
qbee_filedistribution.example: Creating...
qbee_filedistribution.example: Creation complete after 1s [id=tag:example]

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Step 3: Verify

terraform show

You can also verify in the Qbee web UI by navigating to File Manager to confirm the file was uploaded, and Device Configuration → File Distribution to confirm the bundle is active for the example tag.

Updating the File¶

When you change the content of app.conf, Terraform detects the change and pushes the new version to the file manager. Devices receive the updated file automatically on their next agent run.

Step 1: Edit app.conf — for example, bump the version:

log_level=info
app_version=1.1.0

Step 2: Run terraform plan to preview the change:

terraform plan

Expected output:

Terraform will perform the following actions:

  # qbee_filemanager_file.app_config will be updated in-place
  ~ resource "qbee_filemanager_file" "app_config" {
        id          = "/configs/app.conf"
      ~ file_sha256 = "abc123..." -> "def456..."
    }

Plan: 0 to add, 1 to change, 0 to destroy.

Step 3: Apply to push the updated file:

terraform apply

4. Next Steps¶