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
The Terraform Koyeb provider
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
To begin using Terraform, you will need to install it on your machine. Follow Terraform's installation instructions
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" } } }
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
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.
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 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:
sample-app
defined under the koyeb_app
resource blocksample-service
defined in the koyeb_service
resource block with the service definitionWe use var.xxx
to reference the variables defined the variables.tf
file to give the name of the Koyeb app and service resource.
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.
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.
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 consolemain.tf
file.
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.