ZEDEDA Terraform Provider

Overview

The ZEDEDA Cloud Terraform Provider helps you automate and manage your edge node configurations. In this regard, it serves as an alternative user agent to ZEDEDA's Graphical User Interface (GUI) and ZEDEDA's Command Line Interface (ZCLI). Note however, that the Provider is strictly for managing your configurations.

The following diagram shows how Terraform Core, the ZEDEDA Provider, and ZEDEDA Cloud interact with one another. Terraform core sends an execute command to the ZEDEDA Cloud provider, which interfaces with ZEDEDA Cloud. ZEDEDA Cloud, in turn, sends its responses to Terraform through the ZEDEDA Provider.

This guide will get you set up and using the ZEDEDA Provider. Before you proceed, however, consider two significant limitations of the ZEDEDA Provider:

• You must choose either the ZEDEDA Provider or any combination of the ZEDEDA GUI and ZCLI. Using both simultaneously to manage your configurations is likely to cause significant corruptions in your configurations.
• Because the ZEDEDA Provider is strictly a configuration management tool, it doesn't provide any monitoring capability. For monitoring, the ZEDEDA GUI and the ZCLI are the best solutions.

Object Relationships

The following diagram shows how ZEDEDA Cloud objects (called resources in Terraform) relate to one another. For example, edge app instances depend on the following: volume instances, edge apps, edge nodes, and network instances.

 These dependencies must be represented in your Terraform configuration file. For instructions and examples of how to add dependencies to your configuration file, see the Configure object dependencies section in this document.

Prerequisites

You must have Admin privileges in the ZEDEDA system. You also need either physical or ssh access to your edge node.

Walkthroughs

Use secrets with Terraform

To protect your secrets in Terraform, you can use sensitive environment variables. On your edge node’s system, where your Terraform instance will run, you can assign your secret to an environment variable that will be recognized by Terraform. Then, you can flag it as “sensitive” in your Terraform configuration. The Terraform Plan and Apply processes identify any environment values prefixed with TF_VAR. After that, your secret will no longer be readable in plain text.

In the following procedure, sensitive information must be provided in plain text, but they will not be readable in plain text after they have been created.

1. Access your edge node’s CLI. You will either need physical or SSH access to your node to do so.
2. Next, copy the command below and paste it into your node’s CLI. Be sure to replace “your_sensitive_variable” and “YOUR_SENSITIVE_VALUE” with the appropriate values.

export TF_VAR_your_sensitive_variable=YOUR_SENSITIVE_VALUE

Configure your edge environment for Terraform

Before you can use Terraform, you need to set the following environment variables on your edge node. Note the prefixes on these environment variables: TF_VAR and TF_LOG. These are required for Terraform to recognize your variables.

export TF_VAR_zedcloud_url="zedcontrol.zededa.net"
export TF_LOG=ERROR
export TF_LOG_PATH=./terraform.log

Authenticate the Provider with ZEDEDA Cloud

You can authenticate the ZEDEDA Provider using your ZEDEDA Cloud API key. After you have your API key, assign it to an environment variable and add it to the provider section of your Terraform configuration file.

Set the token in your shell session to make it accessible to Terraform. Ensure that you use the prefix, “TF”.

export TF_VAR_zedcloud_token=YOUR_API_TOKEN

Ensure that the value “sensitive” is set to “true”, otherwise Terraform will not treat your API token as a sensitive value, and it will be viewable in plain text to anyone with access to your node. 

variable "zedcloud_token" {
  description = "YOUR_ZEDEDA_ClOUD_API_TOKEN"
  sensitive = true
  type = string
}

provider "zedcloud" {
 zedcloud_url = "https://zedcontrol.zededa.net"
 zedcloud_token = var.zedcloud_token
}

Note: you can find your API token in the Session Information section of your user profile page in the ZEDEDA GUI.

Import Terraform configurations

​​You can import the current states of your existing ZEDEDA Cloud objects into your Terraform configuration file with the import command. All ZEDEDA Cloud objects supported by the provider can be imported. Note, however, that not all ZEDEDA Cloud objects are supported as resources in the terraform provider yet.

For a list of supported resources, check the ZEDEDA Terraform registry, which contains resource schema documentation. To track the ongoing work to support additional resources, follow the ZEDEDA Terraform Provider’s GitHub repository.  The Provider’s GitHub repository also contains an example Terraform configuration file, main.tf. Additionally, the testdata directory holds the currently supported resource configurations organized by resource type.

To import an existing ZEDEDA CLOUD object into Terraform state:

1. Obtain the ID of the target object using ZEDEDA GUI or CLI.
2. Add a corresponding resource block for the object in the Terraform configuration file.
3. Import the resource with the 'import' command.
   • The import command uses the following format: terraform import RESOURCE_TYPE.RESOURCE_NAME ID

terraform import RESOURCE_TYPE.RESOURCE_NAME ID
terraform import zedcloud_edgenode.Sample-Device 3ab53292-ad51-4807-9ae7-d2882cc3c600

Note: data sources support only names as the key.

Configure object dependencies

You can create dependencies explicitly using the 'depends_on' block, or implicitly using references to other data sources or resources. We recommend using implicit dependencies whenever possible. Note that Terraform will only configure your resources in the appropriate order if you specify the dependencies for each resource correctly.

See Create Resource Dependencies for more help with Terraform dependencies.

Explicit dependencies

Edge-App (zedcloud_edgenode) depends on an image (zedcloud_image).

resource "zedcloud_image" "Sample-Image1" {
  name = "sample-image1"
  ...
}

resource "zedcloud_edgeapp" "Sample-EdgeApp" {
   // Explicit dependency on Sample-Image1
   depends_on = [
     zedcloud_Image.Sample-Image1
   ]
}

Implicit dependencies

Edge-Node (zedcloud_edgenode) depends on a network (zedcloud_network).

resource "zedcloud_network" "Sample-Network1" {
  name = "sample-network1"
  ...
}

resource "zedcloud_edgenode" "Sample-Device" {
  interface {
    // This creates implicit dependency on zedcloud_network.Sample-Network2
    netname = zedcloud_network.Sample-Network1.name
...
  }
}

Next steps

If you have any questions about using the ZEDEDA Terraform Provider, please contact ZEDEDA support.

Additionally, you can find the Provider’s open source code in our GitHub repository, which also hosts our developer documentation for those who intend to contribute.