Offline docs (switch to live docs)                         UI-only         CLI-only

MAAS Terraform provider reference

If you wish to use MAAS with Terraform↗, we have made a provider available↗. This article provides reference information about the data sources and resources that can be accessed via this provider. It does not attempt to explain the mechanics or usage of Terraform or offer any tutorial information related to this MAAS Terraform provider.

The MAAS Terraform provider

The MAAS provider is a Terraform provider that allows you to manage MAAS resources using the Terraform (CRUD) tool. This provider can be used to manage many aspects of a MAAS environment, including networking, users, machines, and VM hosts.

These aspects can be divided into three categories of Terraform-compliant HCL:

We will deal with each of these categories in turn. For each data source and resource, we will offer a brief definition and description of how that item is employed in MAAS. If you are new to Terraform↗, or want to explore what terraforming may provide for your MAAS instance, you may wish to consult the Terraform documentation↗ or one of the many tutorials available↗.

API linkages

The schema that provides an API linkage to MAAS from Terraform consists of a standard HCL provider block and a provider API block. As with all Terraform providers, the provider block contains at least two items:

The provider block would look something like this:

terraform {
  required_providers {
    maas = {
      source  = "maas/maas"
      version = "~>1.0"
    }
  }
}

The provider API block contains the necessary credentials to allow Terraform to access your MAAS instance, which include three things:

A typical provider API block might look like this:

provider "maas" {
  api_version = "2.0"
  api_key = "<YOUR API KEY>"
  api_url = "http://127.0.0.1:5240/MAAS"
}

A completed definition would also include some data sources and resources, like this typical example:

terraform {
  required_providers {
    maas = {
      source  = "maas/maas"
      version = "~>1.0"
    }
  }
}

provider "maas" {
  api_version = "2.0"
  api_key = "<YOUR API KEY>"
  api_url = "<YOUR API URL>"
}

resource "maas_space" "tf_space" {
  name = "tf-space"
}

resource "maas_fabric" "tf_fabric" {
  name = "tf-fabric"
}

resource "maas_vlan" "tf_vlan" {
  fabric = maas_fabric.tf_fabric.id
  vid = 14
  name = "tf-vlan14"
  space = maas_space.tf_space.name
}
resource "maas_subnet" "tf_subnet" {
  cidr = "10.88.88.0/24"
  fabric = maas_fabric.tf_fabric.id
  vlan = maas_vlan.tf_vlan.vid
  name = "tf_subnet"
  gateway_ip = "10.88.88.1"
  dns_servers = [
    "1.1.1.1",
  ]
  ip_ranges {
    type = "reserved"
    start_ip = "10.88.88.1"
    end_ip = "10.88.88.50"
  }
  ip_ranges {
    type = "dynamic"
    start_ip = "10.88.88.200"
    end_ip = "10.88.88.254"
  }
}

See the Terraform HCL documentation↗ for more details about these blocks.

Data sources

The MAAS Terraform provider offers three data sources, all representing network elements:

Each of these data sources has a specific HCL block with elements structured appropriately to manage that MAAS element.

Fabric

The fabric↗ data source provides minimal details, namely, the fabric ID, of an existing MAAS fabric. It takes one argument (the fabric name) and exports one attribute (the fabric ID):

data "maas_fabric" "default" {
  name = "maas"
}

Fabrics within MAAS are not widely manipulated in and of themselves, but rather serve as containers for storing VLAN/subnet combinations.

Subnet

The subnet↗ data source provides a number of details about an existing MAAS network subnet. The element takes one argument, the subnet CIDR, and exports a number of attributes:

Declaring a subnet looks something like this example:

data "maas_subnet" "vid10" {
  cidr = "10.10.0.0/16"
}

Subnets are the network backbone of MAAS, and thus provide a number of attributes that can be manipulated to alter the behaviour of MAAS.

VLAN

The VLAN↗ data source provides details about an existing MAAS VLAN. A VLAN takes two arguments:

A VLAN data source exports a few useful attributes:

VLAN spaces↗ are used mostly by Juju, but can be employed by other tools, if desired.

The typical definition of a MAAS VLAN in HCL might look like this:

data "maas_vlan" "vid10" {
  fabric = data.maas_fabric.default.id
  vlan = 10
}

VLANs are available as data sources, but generally, subnets are the workhorses of most MAAS instances.

Resources

The MAAS Terraform provider makes a large number of resources available, currently including the following items. Because of the large number of items, details of arguments and attributes are not duplicated here, but instead provided from a single source at the given links:

Please visit the links to get details on these resources, since the documentation at those links will always be the most current information available.