Create a cluster with Terraform

With the metal-stack-cloud/metal Terraform provider we offer developers to write Infrastructure-as-Code. This guide helps you with the first steps to create resources on metalstack.cloud via Terraform.

Prerequisites

In order to get started, you need to have a valid Access Token. Follow the steps described in our user manual to create one. Moreover, make sure to install Terraform on your computer.

If you start with a blank project, a possible directory structure could look like this:

/my-terraform-project
|-- main.tf
|-- resource.tf

Add the Terraform Provider

First, enter your Terraform project. Next, add the metal-stack-cloud/metal provider to your main.tf file:

terraform {
  required_providers {
    metal = {
      source = "metal-stack-cloud/metal"
    }
  }
}

Configure the Terraform Provider

After requesting and copying your access token, you can configure the metal provider. Do this by using the template below, replacing the placeholder with your token. You only need to provide this value. All other information like the api_url or project to create the resources in, will be derived from the token itself.

provider "metal" {
    api_token = "<YOUR_TOKEN>"
}

Now, you are ready to define your metalstack.cloud resources in the next step.

Create Cluster Resources

The following example defines a Kubernetes cluster in Terraform. Get started, by adding the following resource definition template to your resource configuration file e.g., resource.tf:

resource "metal_cluster" "cluster" {
  name       = "my-cluster"
  kubernetes = "1.27.8" # see our user manual for supported Kubernetes versions
  partition  = "eqx-mu4"
  workers = [
    {
      name         = "default"
      machine_type = "n1-medium-x86"
      min_size     = 1
      max_size     = 3
    }
  ]
}

After setting up the provider and defining the desired resources, you need to initialize your project for working with Terraform. Execute the following command in your terminal to do so:

$ terraform init

The framework will initialize the backend and provider plugin, as well as create a .terraform/ directory and .terraform.lock.hcl file. They are necessary for Terraform to perform further steps.

The result of this command should output a success message, like below:

Terraform has been successfully initialized!

Create an execution plan, to see which resources will be created by your Terraform plan at metalstack.cloud:

$ terraform plan

In the final step, you need to execute the Terraform plan and initiate the creation of the specified resources. After submitting the command, Terraform will ask you once again, if you really want to create the resources. You need to confirm with yes.

$ terraform apply

This can take some time. Grab a cup of coffee and relax - we will set up everything for you. You can see the creation progress in your terminal and in the console, after logging in.

After successfull creation, the terminal will print a success message:

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Remove Cluster Resources

In case you want to remove your cluster resources, you need to execute below terminal command inside your project. After confirming with yes, it will destroy your Kubernetes cluster in a few minutes:

$ terraform destroy