Terraform

Installing Terraform

2. Install Terraform.

3. Set the Terraform path in the environmental variables.

4. To verify that Terraform is installed, type terraform at the command line to display an options list.

Authentication: Setting your ClearBlade credentials

Navigate to the ClearBlade IoT Core Developer Portal and log in with your existing ClearBlade IoT Core account. Within the ClearBlade IoT Core Console, generate your ClearBlade service account credentials and save the JSON file with your service account's credentials.

Use the provider block to configure the path to your service account's JSON file for authentication. The following environment variable can be used to set your credentials in your terminal or IDE environment:

CODE

 export CLEARBLADE_CONFIGURATION=/path/to/file.json

Downloading the provider

1. Head to the ClearBlade Terraform Provider page.

2. Click the Use Provider button in the top-right corner.

3. Copy and paste the source code into a file named versions.tf.

4. Place all of the required .tf files into the same folder.

5. Run terraform init.

6. Run terraform plan.

7. Run terraform apply.

Using the provider

This section describes using the Terraform Provider to provision a registry resource in ClearBlade IoT Core. First, you must include the ClearBlade Terraform Provider in your provider's list. If you already have a Terraform file set up, add the following:

CODE

terraform {
  required_providers {
    clearblade = {
      source  = "ClearBlade/clearblade"
      version = "0.3.0"
    }
  }
}

provider "clearblade" {
  # Configuration options
  credentials = var.clearblade-creds
  project     = var.gcp_project_id
  region      = var.gcp_region
}

resource "clearblade_iot_registry" "example" {
    id = var.registry_id

    event_notification_configs = [
      {
        pubsub_topic_name = var.event_topic_name
        subfolder_matches = var.event_subfolder_matches
      },

      {
        pubsub_topic_name = var.event_topic_name
        subfolder_matches = ""
      }
    ]

    state_notification_config = {
      pubsub_topic_name = var.state_topic_name
    }

    mqtt_config = {
      mqtt_enabled_state = "MQTT_ENABLED"
    }

    http_config = {
      http_enabled_state = "HTTP_ENABLED"
    }

    log_level = var.log_level

}

resource "clearblade_iot_registry" "example1" {
  id = var.registry_id_1

  event_notification_configs = [
    {
      pubsub_topic_name = var.event_topic_name
      subfolder_matches = var.event_subfolder_matches
    },

    {
      pubsub_topic_name = var.event_topic_name
      subfolder_matches = ""
    }
  ]

  state_notification_config = {
    pubsub_topic_name = var.state_topic_name
  }

  mqtt_config = {
    mqtt_enabled_state = "MQTT_ENABLED"
  }

  http_config = {
    http_enabled_state = "HTTP_DISABLED"
  }

  log_level = var.log_level
}

You should use a file named variables.tf that can hold things like your credentials, which would look like this:

CODE

variable "clearblade-creds" {
  type    = string
  default = "Path to ClearBlade's service-account JSON Auth File"
}

variable "gcp_project_id" {
  type    = string
  default = "gcp_project_id"
}

variable "gcp_region" {
  type    = string
  default = "gcp_region_here"
}

variable "registry_id" {
  type    = string
  default = "registry_id_here"
}

variable "registry_id_1" {
  type    = string
  default = "registry_id_here"
}

variable "event_subfolder_matches" {
  type    = string
  default = "test-path"
}

variable "event_topic_name" {
  type    = string
  default = "projects/gcp_project_id_here/topics/rootevent"
}

variable "state_topic_name" {
  type    = string
  default = "projects/gcp_project_id_here/topics/rootevent"
}

variable "log_level" {
  type    = string
  default = "INFO"
}

Importing an existing registry created elsewhere, e.g., via the console UI, under Terraform management:

CODE

# Format is registryID: Import external or existing registry for terraform management
terraform import clearblade_iot_registry.example 'your-existing-registry-id'

Creating a module

This section describes using the Terraform provider with a Terraform module to provision registries in ClearBlade IoT Core. In a new directory, create your root module by constructing a new main.tf configuration file. Then, create a directory called modules that contains another folder called clearblade-registry. You will work with three Terraform configuration files inside the clearblade-registry directory: main.tf, variables.tf, and versions.tf.

First, create the directory for your new module. Create a file named versions.tf inside the module and include the ClearBlade Terraform Provider in your provider's list. If you followed the steps above, you should already have a file named versions.tf. If you have not, add the following to your versions.tf in modules/clearblade-registry:

CODE

terraform {
  required_providers {
    clearblade = {
      source  = "ClearBlade/clearblade"
      version = "0.3.0"
    }
  }
}

Add this ClearBlade IoT registry resource to your main.tf file inside the modules/clearblade-registry directory:

CODE

# Resource(s)

resource "clearblade_iot_registry" "registry" {
  id = var.registry_id

  event_notification_configs = [
    {
      pubsub_topic_name = var.event_topic_name
      subfolder_matches = var.sub_folder_matches
    }
  ]

  state_notification_config = {
    pubsub_topic_name = var.state_topic_name
  }

  mqtt_config = {
    mqtt_enabled_state = var.mqtt_enabled_state
  }

  http_config = {
    http_enabled_state = var.http_enabled_state
  }

  log_level = var.log_level

  credentials = var.registry_credentials
  
}

resource "clearblade_iot_device" "test-device" {
  id       = var.device_id

  registry = clearblade_iot_registry.registry.id

  credentials = var.device_credentials

  blocked = var.device_blocked

  log_level = var.device_log_level

  metadata = {
    Location     = var.device_metadata_location
    Manufacturer = var.device_metadata_manufacturer
  }

  gateway_config = {
    gateway_type        = var.device_gateway_type
    gateway_auth_method = var.device_gateway_auth_method
  }
}

Navigate to the variables.tf file in your module and add the following code:

CODE


variable "gcp_project" {
  type = string
}

variable "gcp_region" {
  type = string
}

variable "registry_id" {
  type = string
}

variable "sub_folder_matches" {
  type = string
}

variable "event_topic_name" {
  type = string
}

variable "event_topic_name2" {
  type = string
}

variable "state_topic_name" {
  type = string
}

variable "log_level" {
  type = string
}

variable "mqtt_enabled_state" {
  type = string
  description = "ClearBlade registry MQTT state"
}

variable "http_enabled_state" {
  type = string
  description = "ClearBlade registry HTTP state"
}

variable "registry_credentials" {
  type        = list(any)
  default     = []
  description = "ClearBlade registry certificate"
}

variable "device_id" {
  type = string
}

variable "device_blocked" {
  type        = bool
  description = "If a device is blocked, connections or requests from this device will fail. Can be used to temporarily prevent the device from connecting if, for example, the sensor is generating bad data and needs maintenance."
}

variable "device_log_level" {
  type        = string
  description = "The logging verbosity for device activity. If unspecified, DeviceRegistry.log_level will be used."
}

variable "device_metadata_location" {
  type        = string
  description = "The metadata location key-value pair assigned to the device."
}

variable "device_metadata_manufacturer" {
  type        = string
  description = "The metadata manufacturer key-value pair assigned to the device."
}

variable "device_gateway_type" {
  type        = string
  description = "Indicates whether the device is a gateway."
}
variable "device_gateway_auth_method" {
  type        = string
  description = "Indicates how to authorize and/or authenticate devices to access the gateway."
}

variable "device_credentials" {
  type        = list(any)
  default     = []
  description = "Device certificates"
}

Return to your root directory with the main.tf and create two additional Terraform configuration files: locals.tf, and versions.tf.

Navigate to your locals.tf and add this reference:

CODE

locals {
  gcp_project      = "your-project-id"
  gcp_region       = "your-gcp-region"
  auth_credentials = "path-to-your-json-credential-auth-file"
  registry_credentials = []
  device_credentials   = []
}

Add the following to the versions.tf:

CODE

terraform {
  required_providers {
    clearblade = {
      source  = "ClearBlade/clearblade"
      version = "0.3.0"
    }
  }
}

provider "clearblade" {
  # Configuration options
  credentials = local.auth_credentials
  project     = local.gcp_project
  region      = local.gcp_region
}

Add this to your main.tf in the root directory:

CODE

module "bas-1" {
  source                       = "./modules/clearblade-registry"
  registry_credentials         = local.registry_credentials
  gcp_project                  = local.gcp_project
  gcp_region                   = local.gcp_region
  log_level                    = "your-log-level"
  registry_id                  = "bas-1"
  event_topic_name             = "projects/${local.gcp_project}/topics/your-topic-name"
  event_topic_name2            = "projects/${local.gcp_project}/topics/your-topic-name"
  event_subfolder_matches      = "your-path"
  state_topic_name             = "projects/${local.gcp_project}/topics/your-state-name"
  mqtt_enabled_state           = "MQTT_ENABLED"
  http_enabled_state           = "HTTP_DISABLED"
  device_id                    = "your-device-id"
  device_log_level             = "DEBUG"
  device_blocked               = false
  device_metadata_location     = "device-location"
  device_metadata_manufacturer = "manufacturer-name"
  device_gateway_type          = "NON_GATEWAY"
  device_gateway_auth_method   = "ASSOCIATION_AND_DEVICE_AUTH_TOKEN"
  device_credentials           = local.device_credentials
}

module "bas-2" {
  source                       = "./modules/clearblade-registry"
  registry_credentials         = local.registry_credentials
  gcp_project                  = local.gcp_project
  gcp_region                   = local.gcp_region
  log_level                    = "your-log-level"
  registry_id                  = "bas-2"
  event_topic_name             = "projects/${local.gcp_project}/topics/your-topic-name"
  event_topic_name2            = "projects/${local.gcp_project}/topics/your-topic-name"
  event_subfolder_matches      = "your-path"
  state_topic_name             = "projects/${local.gcp_project}/topics/your-state-name"
  mqtt_enabled_state           = "your-mqtt-config"
  http_enabled_state           = "your-http-config"
  device_id                    = "your-device-id"
  device_log_level             = "DEBUG"
  device_blocked               = false
  device_metadata_location     = "device-location"
  device_metadata_manufacturer = "manufacturer-name"
  device_gateway_type          = "NON_GATEWAY"
  device_gateway_auth_method   = "ASSOCIATION_AND_DEVICE_AUTH_TOKEN"
  device_credentials           = local.device_credentials
}

Installing the local module

When a new module is added to a configuration, Terraform must install it before it can be used. The terraform get or terraform init command will install and update the module.

Install the module:

CODE

terraform init

Provision your registries:

CODE

terraform apply

Respond yes to the prompt. Your registries will be provisioned.

Deleting a registry

Delete a registry by commenting out that registry’s module block. Run terraform plan or terraform apply.

Importing a registry

DeviceRegistry can be imported using this format:

terraform import module.bas-4.clearblade_iot_registry.registry bas-4.