All blog posts
Article

Announcing Koyeb Pulumi Provider

8 min

Today, we are glad to share that you can interact with your Koyeb resources in your infrastructure using Pulumi.

Pulumi is a modern infrastructure as code platform that allows you to define, deploy, and manage cloud infrastructure on any cloud using your favorite programming languages.

This provider enhances the Koyeb developer toolbox, which already includes the Koyeb CLI, API and SDKs to keep the developer experience easy, intuitive and integrate with tools you already use.

In this article, we will showcase how to deploy a simple Golang application on Koyeb using Pulumi by writing infrastructure code in TypeScript, Golang, and Python.

What is Pulumi?

Pulumi is a tool for defining, deploying and managing cloud infrastructure using general-purpose programming languages including TypeScript, Python, C#, and Golang. This means that you can use the same programming language you use for your application to define your infrastructure and get strong type checking, functions, loop constructs, and other features that make it easier to write and maintain your infrastructure.

The Koyeb Pulumi provider allows you to manage all Koyeb resources such as apps, services, domains, and so on. Deployments are performed from the Pulumi CLI and can also be integrated with your CI/CD pipeline.

Installing Pulumi and the Koyeb provider

If you are not already using Pulumi, check out Pulumi's installation instructions to learn how to install Pulumi for your system.

Configure your API key

To be able to manage Koyeb resources using Pulumi, you first need a Koyeb API access token to allow Pulumi to authenticate to Koyeb. To retrieve your Koyeb API access token, go to your Account settings and click the Create API Access Token button.

Give your API access token a name and description to differentiate it from other tokens and save the generated token in a safe place as you will not be able to see it again.

Then, to use your Koyeb API access token to authenticate the Koyeb Pulumi provider, set the KOYEB_TOKEN environment variable running the following command:

export KOYEB_TOKEN=<YOUR_KOYEB_API_ACCESS_TOKEN>

We are now ready to create and deploy our first application using Pulumi.

Create a new Pulumi project

With the previous steps completed, we are now ready to create a new Pulumi project. A Pulumi project contains a Pulumi.yaml and all projects specify which runtime to use and indicate where to find the program that should be executed during deployments. Open your terminal and navigate to a location of your choice and create a directory that will store the Pulumi project:

mkdir koyeb-pulumi/
cd koyeb-pulumi/

Within the newly created directory, run one of the following commands to create a new Pulumi project depending on the language you want to use:

Python

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

Golang

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

Typescript

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. As for the previous step, this operation depends on the language you chose to use.

Python

pip install pulumi-koyeb
pip freeze > requirements.txt

Golang

go mod tidy

TypeScript

npm install --save @koyeb/pulumi-koyeb

The Pulumi project is now properly configured with the Koyeb provider installed. In the next step, we will create the infrastructure code to deploy our sample application on Koyeb.

Create the infrastructure code to deploy a Golang application on Koyeb

The Pulumi project created in the previous step generates a set of files that vary depending on the language you chose. The entry point file where we will write our infrastructure code is:

  • index.ts for TypeScript
  • main.go for Golang
  • __main__.py for Python

You may notice a Pulumi.yaml file is also present in the project directory. This file contains the project metadata such as the name, description, and the programming language used.

To be able to deploy our sample Golang application on Koyeb, we will need to create two Koyeb resources:

Depending on the language you selected, use the appropriate infrastructure code below to create the App and Service resources on Koyeb:

Python

import pulumi
import pulumi_koyeb as koyeb

app = koyeb.KoyebApp("sample-app", name="sample-app")

koyeb.KoyebService("sample-service", app_name=app.name,  definition=koyeb.KoyebServiceDefinitionArgs(
    name="sample-service",
    regions=["fra"],
    git=koyeb.KoyebServiceDefinitionGitArgs(
        repository="github.com/koyeb/example-golang",
        branch="main",
    ),
    instance_types=koyeb.KoyebServiceDefinitionInstanceTypesArgs(
        type="micro",
    ),
    routes=[koyeb.KoyebServiceDefinitionRouteArgs(
        path="/",
        port=8080,
    )],
    ports=[koyeb.KoyebServiceDefinitionPortArgs(
        port=8080,
        protocol="http",
    )],
    scalings=koyeb.KoyebServiceDefinitionScalingsArgs(
        min=1,
        max=1,
    ),
))

Golang

package main

import (
	"github.com/koyeb/pulumi-koyeb/sdk/go/koyeb"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		app, err := koyeb.NewKoyebApp(ctx, "sample-app", &koyeb.KoyebAppArgs{
			Name: pulumi.String("sample-app"),
		})

		if err != nil {
			return err
		}

		_, err = koyeb.NewKoyebService(ctx, "sample-service", &koyeb.KoyebServiceArgs{
			AppName: app.Name,
			Definition: &koyeb.KoyebServiceDefinitionArgs{
				Name: pulumi.String("sample-service"),
				Regions: pulumi.StringArray{
					pulumi.String("fra"),
				},
				Git: &koyeb.KoyebServiceDefinitionGitArgs{
					Repository: pulumi.String("github.com/koyeb/example-golang"),
					Branch:     pulumi.String("main"),
				},
				InstanceTypes: &koyeb.KoyebServiceDefinitionInstanceTypesArgs{
					Type: pulumi.String("micro"),
				},
				Routes: koyeb.KoyebServiceDefinitionRouteArray{
					&koyeb.KoyebServiceDefinitionRouteArgs{
						Path: pulumi.String("/"),
						Port: pulumi.Int(8080),
					},
				},
				Ports: koyeb.KoyebServiceDefinitionPortArray{
					&koyeb.KoyebServiceDefinitionPortArgs{
						Port:     pulumi.Int(8080),
						Protocol: pulumi.String("http"),
					},
				},
				Scalings: &koyeb.KoyebServiceDefinitionScalingsArgs{
					Min: pulumi.Int(1),
					Max: pulumi.Int(1),
				},
			},
		})

		if err != nil {
			return err
		}

		return nil
	})
}

TypeScript

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,
    },
  },
})

Provision the resources on Koyeb

We are now ready to provision the resources and deploy our sample application on Koyeb. In your terminal, run the following command to generate the graph of the resources that will be created.

$ pulumi preview
Previewing update (demo)

View Live: https://app.pulumi.com/edouardb/koyeb-pulumi-golang/demo/previews/a3e073a3-7548-46d7-a890-7b0b434898cd

     Type                         Name                       Plan
 +   pulumi:pulumi:Stack          koyeb-pulumi-golang-demo   create
 +   ├─ koyeb:index:KoyebApp      sample-app                 create
 +   └─ koyeb:index:KoyebService  sample-service             create


Resources:
    + 3 to create

In our case the graph is pretty simple and shows a wealth of information about the resources that will be created such as the type and name of the resources that will be created.

As everything looks as expected, we can now 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-golang/demo/previews/3214f68d-b118-494d-9b07-7036e55c8a19

     Type                         Name                       Plan
 +   pulumi:pulumi:Stack          koyeb-pulumi-golang-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-golang/demo/updates/5

     Type                         Name                       Status
 +   pulumi:pulumi:Stack          koyeb-pulumi-golang-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 are then created and our Golang sample application is being deployed. If you go to the Koyeb control panel, you should see the Koyeb app and service have been created successfully. 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

Conclusion

You now have everything you need to manage your Koyeb resources using Pulumi. We covered how to use the Koyeb Pulumi provider to provision resources and deploy a sample Golang application on Koyeb using infrastructure-as-code written in Python, Golang, and TypeScript.

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

If you have any comments or simply want to contribute, the code is available on GitHub. If you have an idea to improve the platform, you can tell us on our request platform. Lastly, if you want to join our mission to build Koyeb, we are hiring! Check out our careers pages for more information.

Want to stay in the loop about what is going on at Koyeb? Join the friendliest serverless community or tweet us at @gokoyeb.

Ready to give the platform a try? Create your account and receive $5 per month of free credit. That is the equivalent of two nano services, which means you can use up to 512MB of RAM. 😉

Latest posts

Koyeb

Welcome to Koyeb

Koyeb is a developer-friendly serverless platform to deploy any apps globally.

  • Start for free, pay as you grow
  • Deploy your first app in no time
Start for free
The fastest way to deploy applications globally.