kjuulh/dagger
Archived
1
0
Fork 0
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

CLI spec: route->controller, layout->deployment plan, new&improved overview

Browse Source 
Signed-off-by: Solomon Hykes <sh.github.6811@hykes.org>
This commit is contained in:
Solomon Hykes 2021-03-25 07:37:01 +00:00
parent 8b77c15eac
commit d78b9238e2
1 changed files with 68 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
cmd/spec.cue
View File

@ -26,24 +26,48 @@ import (
#Dagger: #Command & { #Dagger: #Command & {
name: "dagger" name: "dagger"
description: "A system for application delivery as code (ADC)" description: "Write code to deploy your code"
doc: """ doc: """
Every dagger command is applied to a route. A route is a complete delivery environment with its own layout, inputs and outputs. Dagger works by running *controllers*: specialized programs each automating
the deployment of a particular application in a particular way.
The same application can be delivered in different configurations using different routes. Multiple controllers can deploy the same application in different ways,
For example, an application may have a "production" route, staging routes for QA, and experimental development routes. for example to deploy distinct production and staging environments.
If a route is not specified, dagger auto-selects one as follows: Technically speaking, a controller is a standalone program with its own code and data,
* If exactly one route is connected to the current directory, the command proceeds automatically. run by the Dagger platform.
* If more than one route matches, the user is prompted to select one.
* If no route matches, the command returns an error. Unlike traditional programs which strictly separate code and data,
Dagger merges them into a unified DAG (direct acyclic graph)
using a powerful declarative language called [CUE](https://cuelang.org).
Each node of the DAG represents a step of the controller's deployment plan.
Unlike traditional programs which run continuously, Dagger controllers are
*reactive*: their DAG is recomputed upon receiving a new input.
The Dagger platform natively supports [LLB](https://github.com/moby/buildkit) pipelines
pioneered by the Buildkit project.
This allows controllers to run sophisticated pipelines to ingest and process
artifacts such as source code, binaries, database exports, ML models, etc.
Best of all, LLB pipelines can securely build and run any docker/OCI container,
effectively allowing Dagger to be scriptable in any language.
""" """
flag: { flag: {
"--route": { "--deployment": {
alt: "-r" alt: "-d"
description: "Select a route" description:
"""
Select a controller
If no controller is specified, dagger searches for controllers using the current
directory as input.
* If exactly one controller matches the search, it is selected.
* If there is more than one match, the user is prompted to select one.
* If there is no match, the command returns an error.
"""
arg: "NAME" arg: "NAME"
} }
"--log-format": { "--log-format": {
@ -60,25 +84,25 @@ import (
command: { command: {
new: { new: {
description: "Create a new route" description: "Create a new controller"
flag: { flag: {
"--name": { "--name": {
alt: "-n" alt: "-n"
description: "Specify a route name" description: "Specify a controller name"
default: "name of current directory" default: "name of current directory"
} }
"--layout-dir": description: "Load layout from a local directory" "--plan-dir": description: "Load deployment plan from a local directory"
"--layout-git": description: "Load layout from a git repository" "--plan-git": description: "Load deployment plan from a git repository"
"--layout-package": description: "Load layout from a cue package" "--plan-package": description: "Load deployment plan from a cue package"
"--layout-file": description: "Load layout from a cue or json file" "--plan-file": description: "Load deployment plan from a cue or json file"
"--up": { "--up": {
alt: "-u" alt: "-u"
description: "Bring the route online" description: "Bring the controller online"
} }
"--setup": { "--setup": {
@ -88,20 +112,20 @@ import (
} }
} }
list: description: "List available routes" list: description: "List available controllers"
query: { query: {
arg: "[EXPR] [flags]" arg: "[EXPR] [flags]"
description: "Query the contents of a route" description: "Query the contents of a controller"
doc: doc:
""" """
EXPR may be any valid CUE expression. The expression is evaluated against the route contents. The route is not changed. EXPR may be any valid CUE expression. The expression is evaluated against the controller contents. The controller is not changed.
Examples: Examples:
# Print all contents of the layout and input layers (omit output) # Print the entire deployment plan with inputs merged in (but no outputs)
$ dagger query -l input,layout $ dagger query --no-output
# Print complete contents for a particular component # Print the deployment plan, inputs and outputs of a particular step
$ dagger query www.build $ dagger query www.build
# Print the URL of a deployed service # Print the URL of a deployed service
@ -118,7 +142,7 @@ import (
// Use --revision or --change or --change-id instead? // Use --revision or --change or --change-id instead?
"--version": { "--version": {
alt: "-v" alt: "-v"
description: "Query a specific version of the route" description: "Query a specific version of the controller"
default: "latest" default: "latest"
} }
@ -131,7 +155,7 @@ import (
"--layer": { "--layer": {
alt: "-l" alt: "-l"
description: """ description: """
Comma-separated list of layers to query (any of "input", "layout", "output") Comma-separated list of layers to query (any of "input", "plan", "output")
""" """
default: "all" default: "all"
} }
@ -140,70 +164,70 @@ import (
} }
up: { up: {
description: "Bring a route online with latest layout and inputs" description: "Bring a controller online with latest deployment plan and inputs"
flag: "--no-cache": description: "Disable all run cache" flag: "--no-cache": description: "Disable all run cache"
} }
down: { down: {
description: "Take a route offline (WARNING: may destroy infrastructure)" description: "Take a controller offline (WARNING: may destroy infrastructure)"
flag: "--no-cache": description: "Disable all run cache" flag: "--no-cache": description: "Disable all run cache"
} }
history: description: "List past changes to a route" history: description: "List past changes to a controller"
delete: { delete: {
description: "Delete a route after taking it offline (WARNING: may destroy infrastructure)" description: "Delete a controller after taking it offline (WARNING: may destroy infrastructure)"
} }
layout: { plan: {
description: "Manage a route's layout" description: "Manage a controller's deployment plan"
command: { command: {
package: { package: {
description: "Load layout from a cue package" description: "Load plan from a cue package"
arg: "PKG" arg: "PKG"
doc: doc:
""" """
Examples: Examples:
dagger layout package dagger.io/templates/jamstack dagger plan package dagger.io/templates/jamstack
""" """
} }
dir: { dir: {
description: "Load layout from a local directory" description: "Load plan from a local directory"
arg: "PATH" arg: "PATH"
doc: doc:
""" """
Examples: Examples:
dagger layout dir ./infra/prod dagger plan dir ./infra/prod
""" """
} }
git: { git: {
description: "Load layout from a git repository" description: "Load plan from a git repository"
arg: "REMOTE REF [SUBDIR]" arg: "REMOTE REF [SUBDIR]"
doc: doc:
""" """
Examples: Examples:
dagger layout git https://github.com/dagger/dagger main examples/simple dagger plan git https://github.com/dagger/dagger main examples/simple
""" """
} }
file: { file: {
description: "Load layout from a cue file" description: "Load plan from a cue file"
arg: "PATH|-" arg: "PATH|-"
doc: doc:
""" """
Examples: Examples:
dagger layout file ./layout.cue dagger plan file ./myapp-staging.cue
echo 'message: "hello, \(name)!", name: string | *"world"' | dagger layout file - echo 'message: "hello, \(name)!", name: string | *"world"' | dagger plan file -
""" """
} }
} }
} }
input: { input: {
description: "Manage a route's inputs" description: "Manage a controller's inputs"
command: { command: {
// FIXME: details of individual input commands // FIXME: details of individual input commands
@ -216,10 +240,10 @@ import (
} }
output: { output: {
description: "Manage a route's outputs" description: "Manage a controller's outputs"
// FIXME: bind output values or artifacts // FIXME: bind output values or artifacts
// to local dir or file // to local dir or file
// BONUS: bind a route output to another route's input? // BONUS: bind a controller output to another controller's input?
} }
login: description: "Login to Dagger Cloud" login: description: "Login to Dagger Cloud"