Announcing US-East 🇺🇸 region: Deploy your apps in Washington, DC

Terraform Koyeb Provider

Use Terraform to manage your Koyeb resources and applications.

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

The Terraform Koyeb provider 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 already created a Koyeb account. 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 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 {
  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 the provider. You can use an API access token to do this.

To retrieve your Koyeb API access token, go to your Account settings page and click the Create API Access Token button. Name your Koyeb API access token and give it a description to differentiate it from other tokens. 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:

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. The app_name and service_name variables will be used to name the Koyeb app and service. The domain_name variable contains the custom domain we will assign to the Koyeb app.

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

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 var.xxx to reference the variables defined the variables.tf file to give the name of the Koyeb app and service resource.

Initialize Terraform

With the resources created, run a terraform init command to initializae the Terraform working directory:

terraform init

If you followed the previous steps properly, the initialization should occur 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 visualize the changes that will be made to the infrastructure:

terraform plan -out tf.plan

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"

Above is the output of the terraform plan command. It shows a wealth of information about the resources that will be created and the changes that will be made to your infrastructure.

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

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 go to the Koyeb console, you should see 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:

curl https://sample-app-<your-org-name>.koyeb.app
Hello from Koyeb

Make sure to replace the sample-app and your-org-name with your values.

Additional Terraform Koyeb Provider resources

← PulumiHeroku vs Koyeb →