Services

Services represent a component of your application like web services, APIs, and workers. When you create a Service, we deploy autoscaling containers for you. Services are automatically versioned to provide full traceability. They can be deployed using Docker containers or directly from Git.

This documentation explains :

Service types: the different types of services you can deploy on Koyeb.
Continuous Deployment and automatic versionning: the deployment options available to perform continuous deployment with Koyeb. Koyeb lets you deploy services using Docker containers or from Git.
Service options: the different service options including resource allocation, regions, network port mapping, horizontal scaling, and environment variables configuration.
What powers your Services: the technology used to run and secure your services.

Service types

Services are designed to let you run the various components of your stack including:

web apps and APIs: you can run any HTTP web application or API. We support running both public (accessible through the internet) and private (only accessible by other services of your app) APIs. The only requirement for the code you deploy is that it should be able to handle HTTP requests.
workers: you can easily run workers to perform background tasks and asynchronous jobs. Workers are not exposed to the internet and private network. If you're not familiar with the concept of asynchronous processing, read our introduction to synchronous and asynchronous processing.
functions: you can easily break down your app into small functions and deploy them on Koyeb.

These different components are all represented as Services inside of Koyeb.

Continuous Deployment and automatic versioning

We provide two main options to deploy Services in an app:

Git: simply git push, we build your app, deploy it and run it for you. Read our documentation on how-to deploy with git for more details.
Docker images: you can deploy your application using docker images stored on any private or public registry. When you build your own Docker image, you control the whole execution environment of your app. Read our documentation on how-to deploy a Docker image for more details.

We provide full traceability and record all the changes you make to the configuration of your application.

Services Options

Container size: Select the correct amount of resources for an instance of your application. The recommended way to scale your application is to enjoy the seamless horizontal scaling provided by the Koyeb platform but some applications require a significant amount of resources for a single instance to perform well.
Check out our pricing page to explore our container sizes. We provide options with up to 64GB of RAM, 32vCPU, and 640GB of SSD, and even more for demanding applications.
Regions: You have the possibility to select in which region of the world your services will run. You can select one or more regions in which your service will be available. End-users will automatically be redirected to the nearest region where your service is running thanks to our global edge network.
Horizontal scaling: You can easily define the number of simultaneous containers running per region for your Service. If you select a different minimum and maximum, the number of simultaneous containers will be autoscaled between these values depending on the number of incoming requests.
Ports: By default, all network ports are blocked, you need to explicitly define on which network port your application listens for incoming traffic. Exposing ports is needed for public and private services receiving incoming requests but not for workers. The protocol and ports are also used to perform health checks.
To make your Service reachable for everyone through the internet, select Expose publicly. Koyeb will automatically make your service available at https://<appname-orgname>.koyeb.app<path>. All requests will be proxyfied to the port you selected and load-balanced between your instances.
Environments variables: Environments variables can be used to configure your app during both execution and build (if you deploy from git). Secrets can be exposed to your app through environment variables.

Service, deployment and instance status

For all services on the Koyeb platform, we show status and messages that help you understand the current state of your service.

This section explains the different statuses you will encounter when creating and updating services.

While reading this section, keep in mind that:

service statuses are based on deployments statuses,
deployment statuses are based on the deployment's instance statuses.

Service status

Services represent a component of your application and their statuses are crucial to understanding what's happening in your app.

Services can have several statuses during their lifecycle:

Starting: It's the initial state of a service when you create a new service and it's about to start.
Healthy: The service is healthy and correctly answering to requests as traffic is routed toward a healthy deployment. A new deployment might be in progress.
Degraded: The deployment where the traffic is routed is degraded or the latest deployment failed. This might be temporary in case of an instance failure which can be automatically resolved or you may have to fix some configuration.
Unhealthy: No deployment can serve requests.
Deleting: The service is being deleted.
Pausing: The service is being paused (someone triggered a pause on the service).
Paused:: All service deployments are stopped, and no traffic will be handled by the service.
Resuming: The service is being redeployed using the latest deployment configuration. This happens when you resume your service after having paused it.

Deployment status

Deployments contain your service configuration. Each time you update your service configuration, a new deployment is created and provisioned.

Deployments can have several statuses during their lifecycle:

Pending: This is the initial state, we have registered the deployment request and we will process it quickly.
Provisioning: This is the build stage. We're taking what you have provided and converting it to something runnable on our platform.
Scheduled: All requirements are satisfied, we successfully prepared your service to be runnable on the paltform.
Allocating: We successfully requested a deployment internally, instances are about to start.
Starting: The deployment instances are starting and the service mesh configuration is being deployed.
Healthy: The deployment instances are running and health checks are passing for all instances.
Degraded: At least one instance is healthy and one is unhealthy. Traffic is still served from healthy instances and unhealthy instances are automatically removed from production traffic.
Unhealthy: There is no healthy instance to serve traffic, the deployment doesn't work.
Stopping: The deployment is being stopped and waiting for instances to shut down.
Stopped: All instances of the deployment are stopped.
Error: The deployment failed. This can happen when the build of your application failed, your application crashed, or because of an internal error of the platform.

Instance status

Instances are Firecracker MicroVMs running to support your service. Each instance relates to a single deployment of a service.

When deploying using git, the instances are provisioned after the build has succeeded.

Instances can have several statuses during their lifecycle:

Allocating: Start request has been sent and the instance is about to start.
Starting: The instance is running, health checks didn't succeed yet.
Healthy: The instance is running and health checks are succeeding.
Unhealthy: The instance is running but health checks are failing. Check out our Troubleshooting an unhealthy instance documentation to understand why health checks can fail.
Stopping: The instance is being stopped. This happens when a change on the service has been requested and the instance's deployment is torn down.
Stopped: The instance is stopped.
Error: The instance failed due to an internal error of the platform.

For services, deployments, and instances, status messages provide more information than simply the status. To troubleshoot your service, we recommend reading the status messages of each resource to get a correct understanding of the problem.

What powers Services?

Services are serverless, secure, isolated, virtualized containers running all or a part of your App. The virtualization technology we use to run your containers, Firecracker, offers a lot of advantages in terms of security and performance. You can learn more about Firecracker on our blog: