> ## Documentation Index
> Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL.
> Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other.
> Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking.
> Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify.

# ZEDEDA Terraform Provider

> Use the Terraform Provider for ZEDEDA Cloud to manage Edge Infrastructure Services configuration as code, including nodes, applications, networks, and projects.

## Introduction

The Terraform Provider for ZEDEDA Cloud lets you define and manage your Edge Infrastructure Services configuration as code using HashiCorp Terraform. The provider is an external CLI-based tool that runs on your local system or automation environment. It communicates with Edge Infrastructure Services through the API.

The Terraform provider is an alternative to the Edge Infrastructure Services console and zCLI for configuration management. It is best suited for teams that need repeatable, version-controlled infrastructure definitions or integration with CI/CD pipelines.

### Limitations

The Terraform provider has two important constraints to be aware of before you begin:

* **Use either the Terraform provider or the console and zCLI — not both.** Managing the same resources with the Terraform provider and the Edge Infrastructure Services console (or zCLI) simultaneously is likely to cause configuration conflicts. Choose one management path and use it consistently.
* **Configuration management only.** The provider creates, updates, and deletes resources. It does not provide monitoring capability. Use the Edge Infrastructure Services console or zCLI for observability.

### Prerequisites

* You have the SysManager or SysAdmin role in your enterprise. See [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md).
* Depending on which objects the Terraform configuration will manage, the token must belong to a user with CRUD permissions on those specific object types.
* [Terraform CLI installed](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) on your local system.
* A ZEDEDA Cloud API token. To generate one, go to your user profile (click your name in the header) and select the **API Tokens** tab.

## How the Provider Works

The Terraform Provider for ZEDEDA Cloud communicates with Edge Infrastructure Services through the API. Terraform Core sends execution commands to the Terraform provider, which calls the Edge Infrastructure Services API. The API returns responses that Terraform uses to reconcile state.

ZEDEDA Cloud objects correspond to Terraform **resources** (for objects you create and manage) and **data sources** (for objects you reference). For example, `zedcloud_edgenode` is a resource type, while `data.zedcloud_project` is a data source type.

![Diagram showing how Terraform Core communicates with the ZEDEDA Terraform Provider, which calls the Edge Infrastructure Services API](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/integrations-and-automation/images/terraform_provider_interaction.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=36d1a88bfc47593d83988feb18813550)

## Object Relationships

The following ZEDEDA Cloud object types depend on other objects. You must declare these dependencies correctly in your Terraform configuration file so that Terraform provisions resources in the correct order.

Key dependencies:

* **Application instances** depend on: volume instances, edge apps, nodes, and network instances.
* **Nodes** depend on: networks.
* **Edge apps** depend on: images.

You can declare dependencies explicitly using `depends_on` blocks, or implicitly by referencing other resources or data sources. Implicit dependencies are preferred because Terraform resolves them automatically.

![Diagram showing the dependency relationships between ZEDEDA Cloud object types including Application Instance, Node, Edge App, Volume Instance, Network Instance, Image, Datastore, and Network](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/integrations-and-automation/images/zededa_object_model.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=d46e9a74ae49f04d3d859b4cf8f60a1f)

For more information on dependency configuration, see [Create Resource Dependencies](https://developer.hashicorp.com/terraform/tutorials/configuration-language/dependencies) in the Terraform documentation.

## Quick Start

The following steps set up the Terraform provider and provision a basic configuration.

1. Create a directory for your Terraform files:

   ```text theme={"dark"}
   mkdir my-zededa-infra
   cd my-zededa-infra
   ```

2. Create a `main.tf` file and declare the provider version:

   ```text theme={"dark"}
   terraform {
     required_providers {
       zedcloud = {
         source  = "zededa/zedcloud"
         version = "2.2.7"
       }
     }
   }
   ```

3. Set the following environment variables in your shell session. Replace the placeholder values with your actual API token and ZEDEDA Cloud URL:

   ```text theme={"dark"}
   export TF_VAR_zedcloud_url="zedcontrol.zededa.net"
   export TF_VAR_zedcloud_token=YOUR_API_TOKEN
   export TF_LOG=ERROR
   export TF_LOG_PATH=./terraform.log
   ```

4. In `main.tf`, add the provider configuration block and declare the token as a sensitive variable:

   ```text theme={"dark"}
   variable "zedcloud_token" {
     description = "ZEDEDA Cloud API token"
     sensitive   = true
     type        = string
   }

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

   Marking the token as `sensitive = true` prevents Terraform from displaying it in plan and apply output.

5. Add the resources you want to manage. See the [resource schema documentation](https://registry.terraform.io/providers/zededa/zedcloud/latest/docs/resources/application) on the Terraform Registry for available resource types and their fields. An example `main.tf` is available in the [provider GitHub repository](https://github.com/zededa/terraform-provider-zedcloud/blob/main/main.tf).

6. Initialize the working directory:

   ```text theme={"dark"}
   terraform init
   ```

7. Preview the planned changes:

   ```text theme={"dark"}
   terraform plan
   ```

8. Apply the configuration:

   ```text theme={"dark"}
   terraform apply
   ```

## Common Terraform Commands

| Command | Description |
| - | - |
| `terraform init` | Initializes the working directory. Downloads the provider and sets up the backend. Run this once per directory, and again whenever you add or update provider version requirements. |
| `terraform plan` | Creates an execution plan showing what Terraform will create, update, or delete. No changes are made. |
| `terraform apply` | Applies the configuration to reach the desired state. Creates, updates, or deletes resources as needed. |
| `terraform destroy` | Removes all resources managed by the configuration. Useful for tearing down a test environment. |
| `terraform validate` | Checks configuration files for syntax errors. Does not contact the API. |
| `terraform fmt` | Formats configuration files to the standard Terraform style. |
| `terraform state list` | Lists all resources in the Terraform state file. |
| `terraform state show <resource>` | Shows detailed information about a specific resource in state. |
| `terraform import` | Imports an existing ZEDEDA Cloud object into Terraform state. See [Import Existing Resources](#import-existing-resources) below. |
| `terraform output` | Displays output variable values from the current state. |

## Import Existing Resources

You can bring existing Edge Infrastructure Services objects under Terraform management using the `terraform import` command. This is useful when you have resources created through the Edge Infrastructure Services console or zCLI that you want to start managing with Terraform.

To import an existing object:

1. Obtain the object's ID using the Edge Infrastructure Services console or zCLI.
2. Add a corresponding resource block in your Terraform configuration file.
3. Run the import command using the format `terraform import RESOURCE_TYPE.RESOURCE_NAME ID`. For example:

   ```text theme={"dark"}
   terraform import zedcloud_edgenode.my-node 3ab53292-ad51-4807-9ae7-d2882cc3c600
   ```

Data sources support names as the key rather than IDs.

The Terraform provider does not currently support all Edge Infrastructure Services object types as resources. For the current list of supported resource types, see the [resource schema documentation](https://registry.terraform.io/providers/zededa/zedcloud/latest/docs#schema). To follow ongoing work to add support for additional resources, see the [ZEDEDA Terraform Provider GitHub repository](https://github.com/zededa/terraform-provider-zedcloud).

## Protect Secrets

To protect sensitive values (for example, API tokens, passwords, or private keys) in your Terraform configuration, assign them to environment variables prefixed with `TF_VAR_`. Terraform automatically reads variables with this prefix and passes them to your configuration without storing them in plain text in your files.

For example, to protect a database password:

```text theme={"dark"}
export TF_VAR_db_password=YOUR_SECRET_VALUE
```

Declare the variable as sensitive in your configuration:

```text theme={"dark"}
variable "db_password" {
  sensitive = true
  type      = string
}
```

## Next Steps

> [card] [Rename Terraform Objects](https://zededa.mintlify.site/new-ui/infrastructure-services/integrations-and-automation/rename-terraform-objects.md)
>
> Rename Terraform-managed resources safely without triggering unintended deletions.

> [card] [Terraform Registry: ZEDEDA Provider](https://registry.terraform.io/providers/zededa/zedcloud/latest/docs)
>
> Full resource and data source schema reference.

> [card] [ZEDEDA Terraform Provider on GitHub](https://github.com/zededa/terraform-provider-zedcloud)
>
> Source code, example configurations, and issue tracker.