Terraform

The Koyeb cloud platform transparently provisions microVMs (opens in a new tab) to run containerized workloads on bare metal servers in core locations around the world. HashiCorp's Terraform (opens in a new tab) is a powerful infrastructure as code tool that lets you build, version, and change your infrastructure resources efficiently and safely.

The Terraform Koyeb provider (opens in a new tab) enables developers to interact with and manage Koyeb resources such as Apps, Services, Domains, and Secrets as a part of their Terraform workflow.

In this guide, we will use Terraform to provision the cloud infrastructure resources needed to deploy a simple Go application on Koyeb. To successfully follow this documentation you will need to have a Koyeb account (opens in a new tab). If you prefer to follow this guide without leaving the terminal, you can install and use the Koyeb CLI.

Install Terraform

To begin using Terraform, you will need to install it on your machine. Follow Terraform's installation instructions (opens in a new tab) for your system.

As the Koyeb Terraform provider is officially available on the Terraform Registry, it will automatically be installed when specified in the required_providers block of the Terraform configuration file:

Terraform configuration file

terraform {
  required_providers {
    koyeb = {
      source = "koyeb/koyeb"
      version = "0.1.2"
    }
  }
}

Configure your API key to authenticate the Terraform Koyeb provider

Before you can use Terraform to provision and manage cloud resources, Terraform needs to authenticate with the provider. You can use an API access token to do this.

To retrieve your Koyeb API access token, go to your Account settings (opens in a new tab) page, fill out a name and description, and click the Create API Access Token button. Store the generated token in a safe place. You will not be able to see it again.

To use your Koyeb API access token to authenticate the Terraform Koyeb provider, run the following command to set the KOYEB_TOKEN environment variable:

export KOYEB_TOKEN=<YOUR_KOYEB_API_ACCESS_TOKEN>

Next, we are ready to create and deploy our first application on Koyeb using Terraform.

Create a simple Go application

To begin creating a simple Go application, open your terminal and create the directory that will store the Terraform configuration file and variable definition:

mkdir koyeb-terraform/
cd koyeb-terraform/

Create resources

Create a new file variables.tf to store the variable definition that will be used in the Terraform configuration. Add the following content to this file:

variables.tf

variable "app_name" {
  description = "Koyeb app name"
  default     = "sample-app"
}

variable "service_name" {
  description = "Koyeb service name"
  default     = "sample-service"
}

You can change the default values above with your own values. The app_name and service_name variables will be used to name the Koyeb App and Service.

Next, create a new file named main.tf and add the following to it:

main.tf

terraform {
  required_providers {
    koyeb = {
      source = "koyeb/koyeb"
      version = "0.1.2"
    }
  }
}

resource "koyeb_app" "sample-app" {
  name = var.app_name
}

resource "koyeb_service" "sample-service" {
  app_name = var.app_name
  definition {
    name = var.service_name
    instance_types {
      type = "micro"
    }
    ports {
      port     = 8080
      protocol = "http"
    }
    scalings {
      min = 1
      max = 1
    }
    env {
      key   = "PORT"
      value = "8080"
    }
    routes {
      path = "/"
      port = 8080
    }
    regions = ["fra"]
    git {
      repository = "github.com/koyeb/example-golang"
      branch     = "main"
    }
  }

  depends_on = [
    koyeb_app.sample-app
  ]
}

The configuration describes our infrastructure and contains the resources that we will provision on Koyeb:

A Koyeb App named sample-app defined under the koyeb_app resource block
A Koyeb Service sample-service defined in the koyeb_service resource block with the Service definition

We use the var.<variable_name> format to reference the variables defined the variables.tf file. We use these to name the Koyeb App and Service resources.

Initialize Terraform

Now that the resources are defined, run the terraform init command to initialize the Terraform working directory:

terraform init

Providing there are no syntax errors, Terraform will initialize the directory successfully.

Create a plan file

Before applying the configuration, it is helpful to run the terraform plan command to review the changes that will be made to your infrastructure before applying them.

In a terminal, run the following command to display and record the changes that will be made to the infrastructure:

terraform plan -out tf.plan

The output of the command shows a wealth of information about the resources that will be created and the changes that will be made to your infrastructure:

Terraform used the selected providers to generate the following execution plan. Resource actions
are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # koyeb_app.sample-app will be created
  + resource "koyeb_app" "sample-app" {
      + created_at      = (known after apply)
      + domains         = (known after apply)
      + id              = (known after apply)
      + name            = "sample-app"
      + organization_id = (known after apply)
      + updated_at      = (known after apply)
    }

  # koyeb_service.sample-service will be created
  + resource "koyeb_service" "sample-service" {
      + active_deployment = (known after apply)
      + app_id            = (known after apply)
      + app_name          = "sample-app"
      + created_at        = (known after apply)
      + id                = (known after apply)
      + latest_deployment = (known after apply)
      + messages          = (known after apply)
      + name              = (known after apply)
      + organization_id   = (known after apply)
      + paused_at         = (known after apply)
      + resumed_at        = (known after apply)
      + status            = (known after apply)
      + terminated_at     = (known after apply)
      + updated_at        = (known after apply)
      + version           = (known after apply)

      + definition {
          + name    = "sample-service"
          + regions = [
              + "fra",
            ]

          + env {
              + key   = "PORT"
              + value = "8080"
            }

          + git {
              + branch     = "main"
              + repository = "github.com/koyeb/example-golang"
            }

          + instance_types {
              + type = "micro"
            }

          + ports {
              + port     = 8080
              + protocol = "http"
            }

          + routes {
              + path = "/"
              + port = 8080
            }

          + scalings {
              + max = 1
              + min = 1
            }
        }
    }

Plan: 2 to add, 0 to change, 0 to destroy.

──────────────────────────────────────────────────────────────────────────────────────────────────

Saved the plan to: tf.plan

To perform exactly these actions, run the following command to apply:
    terraform apply "tf.plan"

After creating and reviewing the plan file, the next step is to apply the changes.

Apply the changes

With the plan file created and everything looking as expected, we can tell Terraform to apply the generated plan by running:

terraform apply tf.plan

Terraform will apply the plan you created. As it creates the necessary resources, it will display messages about the actions it is taking:

koyeb_app.sample-app: Creating...
koyeb_app.sample-app: Creation complete after 0s [id=78eef767-211f-4d02-a468-cea43c9f9201]
koyeb_service.sample-service: Creating...
koyeb_service.sample-service: Creation complete after 1s [id=164e971f-fbb7-4176-97cd-e7205787f01e]

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

If you check in the Koyeb console (opens in a new tab), you should see that the Koyeb App and Service have been created successfully using the configuration defined in the main.tf file.

Access the deployed Go app from its public URL

Once your Koyeb service becomes healthy, you can perform a request to the Koyeb App's public domain to ensure the application is properly running:

Make sure to replace the <YOUR_APP_NAME> and <YOUR_KOYEB_ORG> with your values.

curl https://<YOUR_APP_NAME>-<YOUR_ORG_NAME>-<HASH>.koyeb.app

If all goes well, you should see Hello from Koyeb.

Additional Terraform Koyeb Provider resources

The provider is available via the official Terraform Registry (opens in a new tab)
Learn more about this tool by reading our Koyeb Terraform provider blog post (opens in a new tab).

Upstash Pulumi