How to Use Terraform with the Cato Cloud

This article explains the different ways to use Terraform to automate the deployment of Cato infrastructure resources.

Before starting you will need to install Terraform (version 1.5 or greater is recommended). Refer to this document for more information:

Using the Provider (Resource and Data Source)

The provider documentation is available here:

Configuring the Provider

To start using the provider, you need to create a new folder and manifest using these commands:

mkdir cato-terraform-test
cd cato-terraform-testtouch

Then edit the file (we recommend using an IDE) and add the following code:

terraform {
  required_providers {
    cato-oss = {
      source = ""

provider "cato-oss" {}

Now you must configure the provider by setting the required parameters. In the terminal, define the environment variables CATO_BASEURL and CATO_TOKEN:

export CATO_BASEURL=""
export CATO_TOKEN="You_API_Key"

CATO_TOKEN is the API Key (it requires EDIT permissions). For more information about generating an API key, see Generating API Keys for the Cato API

You can now test the provider by initializing it. Into your IDE’s terminal, you can execute the command:

terraform init

You should have a result similar to this:


Defining the accountID

Most resources and data sources have an accountID parameter. To easily share this parameter, we are going to use a local value.

You can add the following code to the terraform manifest :

locals {
  account_id = "your_account_id"

For more information about locating the ID for your account in the Cato Management Application, see Viewing the General Account Info.

Creating a Socket Site

In the manifest you can add the following code at the end of your manifest to create a new resource:

resource "cato-oss_socketsite" "site1" {
    account_id = local.account_id
    name = "site1"
    description = "site1 AWS Datacenter"
    site_type = "DATACENTER"
    connection_type = "SOCKET_AWS1500"
    native_network_range = ""
    site_location = {
        country_code = "FR",
        timezone = "Europe/Paris"

You can now start to plan the deployment using the following command in your terminal:

terraform plan

After executing this command you will see a result similar to this:


You can now apply the following command to apply the desired state:

terraform apply -auto-approve

After executing this command you will see a result similar to this:


Now a file terraform.tfstate has been created. It contains the state of the current deployment. If you open this document, you can retrieve the defined parameter for the site created, and the computed parameter (like the site ID):


If you check the Cato Management Application, a new site has been created with the desired state:


Retrieving the S/N for the Socket Site

It can be useful to retrieve some parameters of the previously created site, for example, the serial number of the vSocket (this information is mandatory to deploy vSocket into cloud environments (ie. Azure, AWS).

To retrieve the serial number of the socket, you can add the following code at the end of your manifest:

data "cato-oss_accountSnapshot" "site1" {
    account_id = "5242"
    site_id =

output "site1_serial" {
  value = data.cato-oss_accountSnapshot.site1.sites[0].info.sockets[0].serial

The output isn’t mandatory, it only shows you the way to retrieve the value from the data source.

Now you can use the following command to add data source into your state and output the serial number of the Socket :

terraform apply -auto-approve

After running this command, you will see the following screen:


Destroying the Site Deployment

You can use the following command to destroy the current deployment:

terraform destroy -auto-approve

After running this command, you will see the following screen:


Using the HTTP Utility Provider (Data Source Only)

If you want to retrieve data from the Cato API, you can use the HTTP Provider from Hashicorp :

The HTTP Provider can execute any GraphQL request. Here is an example of how to retrieve all networks from a specific site. To make it work, you need to customize the catokey variable, the accountID and the ID for the parent (which is the site ID) :

variable "catokey" {
 type = string
 default = "you_api_key"

data "http" "site_range" {
  url    = ""
  method = "POST"

  request_headers = {
    Accept = "application/json"
    Content-Type = "application/json"
    x-api-key = var.catokey

  request_body = <<EOF
  "query": "query entityLookup ($accountID: ID!, $type: EntityType!, $parent: EntityInput!) { entityLookup (accountID: $accountID, type: $type, parent: $parent) { items { entity { id name type } description helperFields } }}",
  "variables": {
    "accountID": "5242",
    "type": "networkInterface",
    "parent": {
      "id": "40422",
      "type": "site"


output "siterange" {
  value = jsondecode(data.http.site_range.response_body)

By executing this terraform manifest with a terraform apply command, you will get a result similar to this:


Was this article helpful?

0 out of 0 found this helpful


Add your comment