Pulumi

Pulumi (opens in a new tab) is a tool for provisioning and managing cloud infrastructure resources using the programming language (opens in a new tab) of your choice. The Koyeb Pulumi provider (opens in a new tab) 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 infrastructure resources needed to deploy a simple Go application on Koyeb. To successfully follow this documentation you will need to install Pulumi (opens in a new tab) and create 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.

You can read the official Koyeb Pulumi provider announcement blog post (opens in a new tab) to learn more about the tool and see Go and Python examples.

Generate a Koyeb API key

To use Pulumi to provision and manage Koyeb resources, you need a Koyeb API access token so that Pulumi can authenticate with your organization.

Generate a Koyeb API access token by going to the API access tokens page (opens in a new tab) for your organization, providing a name and description, and clicking the Create API Access Token button.

Save the generated token to a safe place. You will not be able to see the token again after leaving the page.

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 will be able to authenticate successfully now. In the next step, we will create a new Pulumi project.

Create a new Pulumi project

All Pulumi projects contain a Pulumi.yaml file that specifies which runtime to use and indicates 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 by typing:

mkdir koyeb-pulumi/
cd koyeb-pulumi/

From this directory, run the following command to create a new Pulumi project. The application we will be deploying is written in Go, but we will use TypeScript to define the infrastructure we need for Pulumi:

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

Now that the project has been created, the next step is to install the Koyeb Pulumi provider by typing:

npm install --save @koyeb/pulumi-koyeb

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

The Pulumi.yaml file in the project directory 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 Pulumi infrastructure code

In the last step, we chose TypeScript as the language to use to define our infrastructure. Pulumi executes our program by loading an "entrypoint" file as a Node module. The entrypoint file where we will write our infrastructure code is index.ts.

To deploy the Go application (opens in a new tab) on the Koyeb platform, we need to provision two Koyeb resources:

A Koyeb App
A Koyeb Service

You can define the App and Service resources for Koyeb with this infrastructure code, written in TypeScript:

index.ts

import * as koyeb from '@koyeb/pulumi-koyeb'
import * as pulumi from '@pulumi/pulumi'
 
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 defines a Koyeb App and a Koyeb Service running in the Frankfurt region on a Micro instance with port 8080 exposed.

Preview the Pulumi resources

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 the resources on Koyeb

The graph from the pulumi preview command shows information about the Koyeb resources that will be created. Since the output matches our expectations, we can run the following command to provision the resources and deploy our application on Koyeb.

pulumi up -y

The resources defined in the index.ts file will be provisioned on Koyeb. Pulumi will display information about the progress of the provisioning as it executes:

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

Your resources will be created and the Go sample application will be deployed to Koyeb.

View build logs and monitor the Deployment

If you want to track the deployment and view the build logs, run the following command with the Koyeb CLI:

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

Alternatively, you can go to the Koyeb control panel (opens in a new tab) to view the logs and verify that the Koyeb App and Service have been created successfully.

Access the App from its public URL

Once the Koyeb service becomes healthy, you can visit the Koyeb App's public URL to see the sample application in action.

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

If all goes well, you should see the following message: Hello from Koyeb

Additional resources

The Koyeb Pulumi provider is available via the official Pulumi Registry (opens in a new tab). You can learn more about available resources and how to use them by reading the Koyeb Pulumi provider documentation (opens in a new tab).

Terraform GitHub