Koyeb Pulumi Provider

Manage Koyeb resources using Pulumi and your favorite programming languages.

Pulumi is a tool for provisioning and managing cloud infrastructure resources using the programming language of your choice. The Koyeb Pulumi provider enables Pulumi to manage Koyeb resources such as apps, services, custom domains, environment variables and other features that make up your infrastructure.

In this guide, we will use Pulumi 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 installed Pulumi and created a Koyeb account. If you prefer to follow this guide without leaving the terminal, you can install and use the Koyeb CLI.

Read our official Koyeb Pulumi provider announcement blog post to learn more about this developer tool and see Golang and Python examples.

Configure your API key to authenticate the Koyeb Pulumi provider

Before you can use Pulumi to provision and manage Koyeb resources, you first need a Koyeb API access token that Pulumi can use to authenticate us. You can find your Koyeb API access token by going to your Account settings page and clicking the Create API Access Token button.

Name your Koyeb API access token and give it a description to differentiate it from other tokens. Careful: You will not be able to see the generated token again, so store it in a safe place.

To use your Koyeb API access token to authenticate the Koyeb Pulumi provider, set the KOYEB_TOKEN environment variable by running:

export KOYEB_TOKEN=<YOUR_KOYEB_API_ACCESS_TOKEN>

The Koyeb Pulumi provider is now authenticated. In the next step, we will create a new Pulumi project.

Create a new Pulumi project

All Pulumi projects contain a Pulumi.yaml, specify which runtime to use, and indicate where to find the program to execute during deployments. From your terminal, navigate to the location where you will store the Pulumi project. Create a new directory for the project and move into it:

mkdir koyeb-pulumi/ cd koyeb-pulumi/

From this directory, run the following command to create a new Pulumi project for the sample TypeScript application:

pulumi new typescript \ --name koyeb-pulumi-typescript \ --description "An example application on how to use the Koyeb Pulumi provider" \ --stack demo

With the project created, the next step is to install the Koyeb Pulumi provider.

npm install --save @koyeb/pulumi-koyeb

The Pulumi project is now properly configured, the Koyeb provider is installed, and the project now contains a set of files.

There is a Pulumi.yaml file in the project directory that contains the project's metadata such as the project's name, description, and the programming language used. In the next step, we will create the infrastructure code to deploy our sample application on Koyeb.

Create the infrastructure code to deploy a Typescript application on Koyeb

Pulumi executes our program by loading the entrypoint file as a Node module. The entrypoint file where we will write our infrastructure code is index.ts.

To deploy our sample Typescript application on the Koyeb platform, we need to provision two Koyeb resources:

  1. A Koyeb app
  2. A Koyeb service

You can create the App and Service resources on Koyeb with this infrastructure code:

import * as pulumi from "@pulumi/pulumi"; import * as koyeb from "@koyeb/pulumi-koyeb"; const koyebApp = new koyeb.KoyebApp("sample-app", { name: "sample-app", }); const koyebService = new koyeb.KoyebService("sample-service", { appName: koyebApp.name, definition: { name: "sample-service", regions: ["fra"], git: { repository: "github.com/koyeb/example-golang", branch: "main", }, instanceTypes: { type: "micro", }, routes: [ { path: "/", port: 8080, }, ], ports: [ { port: 8080, protocol: "http", }, ], scalings: { min: 1, max: 1, }, }, });

This infrastructure code creates a Koyeb app and a Koyeb service that will be running in the Frankfurt region on a Micro instance with port 8080 exposed. The next step is to provision the resources on Koyeb.

Provision the resources on Koyeb

In your terminal, preview the resources that will be created by running the following command:

pulumi preview

A graph listing the resources will appear.

Previewing update (demo) View Live: https://app.pulumi.com/edouardb/koyeb-pulumi-typescript/demo/previews/a3e073a3-7548-46d7-a890-7b0b434898cd Type Name Plan + pulumi:pulumi:Stack koyeb-pulumi-typescript-demo create + β”œβ”€ koyeb:index:KoyebApp sample-app create + └─ koyeb:index:KoyebService sample-service create Resources: + 3 to create

Deploying on Koyeb with Pulumi

The graph displays a lot of information about the Koyeb resources that will be created. As the resources look as expected, we can run the following command to provision our resources and deploy our application on Koyeb.

pulumi up -y Previewing update (demo) View Live: https://app.pulumi.com/edouardb/koyeb-pulumi-typescript/demo/previews/3214f68d-b118-494d-9b07-7036e55c8a19 Type Name Plan + pulumi:pulumi:Stack koyeb-pulumi-typescript-demo create + β”œβ”€ koyeb:index:KoyebApp sample-app create + └─ koyeb:index:KoyebService sample-service create Resources: + 3 to create Updating (demo) View Live: https://app.pulumi.com/edouardb/koyeb-pulumi-typescript/demo/updates/5 Type Name Status + pulumi:pulumi:Stack koyeb-pulumi-typescript-demo created (0.51s) + β”œβ”€ koyeb:index:KoyebApp sample-app created (0.83s) + └─ koyeb:index:KoyebService sample-service created (0.57s) Resources: + 3 created Duration: 5s

View build logs and monitor the app deployment

Your resources have been created and the Typescript sample application is being deployed. If you want to track the app deployment and visualize its build logs, run the following command:

koyeb service logs sample-app/sample-service -t build

Similarly, if you go to the Koyeb control panel, you should see the Koyeb app and service have been created successfully.

Access the app from its public URL

Once your Koyeb service becomes healthy, you can perform a request to the Koyeb app public URL to see the sample application in action.

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

Koyeb Pulumi Provider

The Koyeb Pulumi provider is available via the official Pulumi Registry and you can learn more about available resources and how to use them by reading the Koyeb Pulumi provider documentation.