Configuration File

Processes

The [[processes]] section is used to define the different processes that make up your application. You can define multiple processes, such as a web server or a background worker.

Each process is defined as a separate [[processes]] table.

# Configuration file with a processes section
app = 'myapp'

# App process
[[processes]]
  name = 'app'
  command = 'php artisan serve'
  size = 'small'

  [processes.http]
    internal_port = 8080

  [[processes.ports]]
    port = 9090
    protocol = 'tcp'
  [[processes.ports]]
    port = 53
    protocol = 'udp'

  [processes.autoscaling]
    min_replicas = 1
    max_replicas = 5
  [[processes.autoscaling.metrics]]
    resource = 'cpu'
    avg_utilization = 70
  [[processes.autoscaling.metrics]]
    resource = 'memory'
    avg_value = '512Mi'

  [processes.liveness]
    type = 'http'
    path = '/up'
    port = 8080
    initial_delay_seconds = 30
    timeout_seconds = 5
    period_seconds = 10
    success_threshold = 1
    failure_threshold = 3

  [processes.readiness]
    type = 'tcp'
    port = 9090
    initial_delay_seconds = 40
    timeout_seconds = 4
    period_seconds = 8
    success_threshold = 2
    failure_threshold = 4

# Worker process
[[processes]]
  name = 'worker'
  command = 'php artisan queue:work'

  [processes.resources]
    [processes.resources.requests]
      cpu = '500m'
      memory = '256Mi'
    [processes.resources.limits]
      cpu = '1'
      memory = '512Mi'

  [processes.liveness]
    type = 'exec'
    command = 'php artisan health:check'
    initial_delay_seconds = 20
    timeout_seconds = 15
    period_seconds = 30
    success_threshold = 1
    failure_threshold = 3

  [processes.readiness]
    type = 'exec'
    command = 'php artisan health:check'
    initial_delay_seconds = 22
    timeout_seconds = 18
    period_seconds = 32
    success_threshold = 2
    failure_threshold = 4

Common fields

  • name: The name of the process. (Required)
  • command: The command to execute to start the process. If not specified, Deckrun will use the CMD instruction from your Dockerfile.

Naming a Process

The name field is used to identify each process and must adhere to the following rules:

  • Uniqueness: Each process name must be unique within the [[processes]] list in your deckrun.toml file. Duplicate names will cause a validation error.
  • Formatting: The name must consist of lowercase alphanumeric characters and dashes.
  • Length: The name must be between 3 and 63 characters long.

These conventions ensure that process names are valid and compatible with the underlying infrastructure.

Sizing your process

You can define the CPU and memory for a process using either pre-defined sizes or custom resource allocation. You cannot use both at the same time.

Understanding Resource Units

You might be wondering what 250m of CPU or 256Mi of memory means. Let's break it down.

CPU

CPU resources are measured in "millicores" or "millicpu". 1000m is equivalent to one full CPU core. So, 250m represents a quarter of a CPU core (0.25).

Memory

Memory is measured in bytes. The Mi suffix stands for "Mebibytes", which is a standard unit for memory (1 Mebibyte = 2^20 bytes).

For a more in-depth explanation of resource units in Kubernetes, you can refer to the official Kubernetes documentation.

Using pre-defined sizes

The size attribute allows you to select from a pre-defined set of CPU and memory resources. This is the simplest way to allocate resources to your process.

Below is a table with the available sizes and their corresponding CPU and memory resources.

SizeCPUMemory
pico250m256Mi
nano500m256Mi
micro500m512Mi
mini1000m512Mi
small1000m1Gi
medium2000m2Gi
standard2000m4Gi
large4000m8Gi
xlarge4000m12Gi
xxlarge6000m16Gi
xxxlarge8000m32Gi

Using custom resource allocation

If you need more control over the resources, you can use the [processes.resources] section.

Note: Deckrun enforces minimum resource requests to ensure stable application performance. The minimum CPU request is 100m, and the minimum memory request is 32Mi. Any values specified below these thresholds will be rejected during validation.

Note: You cannot use size and [processes.resources] at the same time.

The [processes.resources] section allows you to specify the CPU and memory resources for your process.

  • requests: The amount of resources that are guaranteed for the process.
  • limits: The maximum amount of resources that the process can use.

Here is an example of how to use the resources section:

# Worker process
[[processes]]
  name = 'worker'
  command = 'php artisan queue:work'

  [processes.resources]
    [processes.resources.requests]
      cpu = '500m'
      memory = '256Mi'
    [processes.resources.limits]
      cpu = '1'
      memory = '512Mi'

processes.http

The [processes.http] section exposes a process to the internet, making it accessible via a public URL.

In Deckrun, only one process can be designated as the main web-facing service. By convention, this process must be named app. The [processes.http] section is only valid for the process named app and will be ignored for any other process.

  • internal_port: The port inside the container on which your application is listening for HTTP traffic. This field is required.

processes.ports

The [[processes.ports]] section allows you to expose additional ports for your process.

  • port: The port to expose. (Required)
  • protocol: The protocol to use (tcp or udp). Defaults to tcp if not specified.

Port Validation

When configuring ports in Deckrun, all port numbers must be valid and within the standard TCP/UDP range.

  • Valid Range: Port numbers must be between 1 and 65535.
  • Affected Fields: This validation applies to processes.http.internal_port and the port field in any [[processes.ports]] definition.

Specifying a port number outside of this valid range (such as 0, a negative number, or a number greater than 65535) will cause a validation error during the deployment process.

processes.autoscaling

The [processes.autoscaling] section allows you to configure autoscaling for your process, automatically adjusting the number of replicas based on observed metrics.

  • min_replicas: The minimum number of replicas that should be running at all times. (Required)
  • max_replicas: The maximum number of replicas that the autoscaler can create. (Required)

Both min_replicas and max_replicas are required fields and must be positive integers greater than zero. The value of min_replicas must be less than or equal to max_replicas.

Note: Autoscaling is only effective when resource requests are defined for the process. This is because the autoscaler calculates utilization targets based on these requests. You can set resource requests either by selecting a size or by specifying them explicitly in the [processes.resources] section. If you configure autoscaling without defining resource requests, Deckrun will return a validation error.

processes.autoscaling.metrics

To define autoscaling triggers, you must specify one or more metrics in the [[processes.autoscaling.metrics]] table array. Deckrun supports scaling based on CPU and memory usage.

There are two primary ways to define a metric target:

  1. Average Utilization (avg_utilization): This scales the process based on the average percentage of a resource request being used across all replicas. This is most commonly used for CPU.
  2. Average Value (avg_value): This scales the process based on the average absolute value of a resource being consumed across all replicas. This is the standard way to scale based on memory.

CPU Scaling

To scale based on CPU, you define a metric with resource = 'cpu' and set a target average utilization percentage with avg_utilization. The autoscaler will add more replicas when the average CPU usage across all pods exceeds this threshold.

# Scale up when CPU usage averages over 70%
[processes.autoscaling]
  min_replicas = 1
  max_replicas = 5
  [[processes.autoscaling.metrics]]
    resource = 'cpu'
    avg_utilization = 70

In this example, Deckrun will ensure the number of replicas is adjusted so that the average CPU usage for the process remains around 70% of what was requested (either via the size parameter or the resources.requests.cpu field).

Memory Scaling

To scale based on memory, you define a metric with resource = 'memory' and set a target average value with avg_value. This value represents the target memory consumption in Mebibytes (Mi).

# Scale up when memory usage averages over 512Mi
[processes.autoscaling]
  min_replicas = 1
  max_replicas = 5
  [[processes.autoscaling.metrics]]
    resource = 'memory'
    avg_value = '512Mi'

In this example, the autoscaler will add replicas if the average memory consumption across all pods for this process exceeds 512 Mebibytes.

You can also combine metrics. The autoscaler will trigger a scale-up if any of the metric thresholds are breached.

# Scale up if CPU averages > 70% OR memory averages > 256Mi
[processes.autoscaling]
  min_replicas = 2
  max_replicas = 10
  [[processes.autoscaling.metrics]]
    resource = 'cpu'
    avg_utilization = 70
  [[processes.autoscaling.metrics]]
    resource = 'memory'
    avg_value = '256Mi'

  • You must provide at least one metric in the [[processes.autoscaling.metrics]] table for the autoscaler to function.

  • Only one metric per resource type is allowed. For example, you cannot define two separate CPU metrics, even if one uses avg_utilization and the other uses avg_value. Doing so will result in a validation error for duplicate metrics. For instance, the following configuration is invalid because it defines two metrics for the cpu resource:

    # Invalid configuration: two metrics for the same resource
[[processes.autoscaling.metrics]]
  resource = "cpu"
  avg_utilization = 70

[[processes.autoscaling.metrics]]
  resource = "cpu"
  avg_value = "200m"

Each [[processes.autoscaling.metrics]] block is subject to the following rules:

  • The resource field must be either "cpu" or "memory". Any other value will be considered invalid.
  • You must set exactly one of avg_utilization or avg_value. Providing both or neither will result in an error.
  • For CPU metrics (resource = "cpu"):
    • If using avg_utilization, the value must be an integer percentage between 1 and 100. Values outside this range are invalid.
    • If using avg_value, the value must be a valid CPU resource quantity string, such as "200m".
  • For Memory metrics (resource = "memory"):
    • avg_value is the recommended field and must be a valid memory resource quantity string, such as "256Mi" or "1Gi".
    • While avg_utilization is permitted for memory, it must be an integer percentage between 1 and 100.
  • Any incorrectly formatted values will cause a validation error.

Health Checks

Deckrun uses liveness and readiness probes to monitor the health of your application's containers.

  • Liveness Probe: Checks if the container is running. If it fails, Deckrun restarts the container.
  • Readiness Probe: Checks if the container is ready to accept traffic. If it fails, the container is removed from service discovery until it passes again.

Both liveness and readiness probes are configured with the same set of options.

Configuration Fields

  • type: The type of probe to perform. This is a required field and must be one of http, tcp, or exec.
  • path: The HTTP path to request for http probes. This field is required for http probes.
  • port: The port to connect to for http and tcp probes.
  • command: The command to execute for exec probes. This field is required for exec probes.
  • initial_delay_seconds: The number of seconds to wait after the container starts before performing the first probe. Cannot be negative.
  • timeout_seconds: The number of seconds after which the probe times out. Cannot be negative.
  • period_seconds: The frequency (in seconds) at which to perform the probe. Cannot be negative.
  • success_threshold: The minimum number of consecutive successes required for the probe to be considered successful after a failure. Cannot be negative.
  • failure_threshold: The number of consecutive failures after which the probe is considered to have failed. Cannot be negative.

Note on Liveness Probes: For liveness probes, the success_threshold must be 1. A liveness probe only needs to succeed once to confirm the container is running, so a higher value is not permitted.

Probe Types and Port Configuration

The behavior of health checks can vary depending on the type you choose.

HTTP Probes

  • Requirement: An http probe can only be used on a process that is exposed via HTTP, meaning a [processes.http] section must be defined for it.
  • Port: The port for an http probe is implicitly set to the value of processes.http.internal_port. You do not need to specify it, but if you do, it must match the internal_port.
# HTTP probe example
[processes.liveness]
  type = 'http'
  path = '/up'

TCP Probes

  • Port: The port for a tcp probe must be one of the ports exposed by the process. This can be either the processes.http.internal_port (if defined) or a port listed in the [[processes.ports]] section. If the specified port is not exposed by the process, Deckrun will return a validation error.
# TCP probe example
[processes.readiness]
  type = 'tcp'
  port = 9090

Exec Probes

exec probes run a command inside your container and do not have any port-related requirements.

  • Requirement: An exec probe requires the command field to be specified.
# Exec probe example
[processes.liveness]
  type = 'exec'
  command = 'php artisan health:check'
Previous
Deploy
Next
Cron Jobs