1 Your First Application with Kumori DSL

This guide will walk you through creating your first application definition with kdsl and generating the deployable artifacts. By the end of this guide, you will have:

  • Initialized a new kdsl module.
  • Defined a basic Kumori DSL application with a component interface and implementation.
  • Built your application definition into a deployable artifact.
  • Validated your application definition.

1.1 Prerequisites

  • kdsl installed. See the Installation Guide.
  • A local copy of the example code. You can either:
    • Clone the repository: sh git clone https://github.com/jrovira-kumori/kdsl-my-first-deployment my-first-kumori-app -b 0.0.1-alpha.8 cd my-first-kumori-app If you clone the repository, you can skip to Step 3: Build Your Deployable Artifact.
    • Manually create the files: Follow the instructions below.

1.2 Step 1: Initialize Your Project Module

kdsl applications are organized into modules. Each module is defined by a kumori.mod.json file, which acts as a manifest for your project.

  1. Create a new directory for your module: bash mkdir my-first-kumori-app cd my-first-kumori-app

  2. Initialize the kdsl module: bash kdsl mod init kumori.systems/example This creates a kumori.mod.json file with the following content: json { "spec": "kumori/module/v1", "module": "kumori.systems/example", "kumori": "0.0.1", "requires": [] }

1.3 Step 2: Define Your First Application

Kumori DSL separates a component’s interface (its contract) from its implementation. We’ll create three files:

  • component.h.kumori: The component’s interface.
  • component.kumori: The component’s implementation.
  • deployment.kumori: The deployment definition.

1.3.1 Component Interface (component.h.kumori)

This file defines the contract for our EchoServer component, specifying its inputs and outputs.

// component.h.kumori
import "kumori"

component EchoServer {
    srv {
        client { RemotePostgres "tcp" }
        server { HTTPServer "http" }
        duplex { InternalChannel { protocol "grpc", port 1337 } }
    }

    resource {
        Port:   kumori.Port
        Volume: kumori.Volume
    }

    config {
        Port:       number
        Response:   string = "Hello world!"
    }
}

1.3.2 Component Implementation (component.kumori)

This file provides the concrete implementation for the EchoServer component.

// component.kumori
import "strconv"

component EchoServer {
    var (
        Port = strconv.Concat([":", strconv.Format(interface.config.Port, 10)])
    )

    size {
        bandwidth    1G
        minbandwidth 1G
        mincpu       self.code.EchoServer.size.mincpu
    }

    code {
        EchoServer {
            cmd     ["-listen", var.Port, "-text", interface.config.Response],
            image   "docker.io/hashicorp/http-echo:latest",
            size {
                memory  500M,
                cpu     400m,
                mincpu  200m,
            },
            env {
                MyEnvVar "hello",
                Another  string(interface.resource.Port),
            },
            fs {
                "/config.json"  "123",
                "/another.json" strconv.JSON({ A interface.config })
            },
        }
    }
}

1.3.3 Deployment (deployment.kumori)

This file defines the deployment, which orchestrates the EchoServer component and provides concrete values for its configuration and resources.

// deployment.kumori
import "kumori"

deployment {
    name        "my-first-deployment"
    artifact    EchoServer
    resilience  1

    config {
        Port        8080
        Response    "Hello Kumori from KDSL!"
    }

    resource {
        Port    kumori.Port("http-endpoint")
        Volume  kumori.Ephemeral(33G)
    }
}

1.4 Step 3: Build Your Deployable Artifact

Now that you’ve defined your application, you can build it into a deployable artifact.

kdsl build .

This command compiles your DSL files and outputs a solution.json file to standard output. To save it to a file, you can redirect the output:

kdsl build . > solution.json

1.5 Step 4: Validate Your Application

The kdsl build command implicitly validates your application as its first step. This means that if there are any errors in your DSL definition, kdsl build will report them and stop before generating the solution.json artifact.

However, you can also explicitly run kdsl check to perform a type check and validate your application definition without generating any output artifacts. This is useful for quickly verifying correctness during development.

kdsl check

If your files are correct, you won’t see any output. If there are errors, kdsl will report them, indicating the file, line, and column where the error occurred.

1.6 What’s Next?

Congratulations! You’ve successfully created, built, and validated your first Kumori DSL application. You can now hand off the generated solution.json to the Kumori platform for deployment.

To learn more, explore the following resources: