From a8e41590587e80835c58bce1643ac86d862b7ab7 Mon Sep 17 00:00:00 2001 From: Christoph Raaflaub Date: Wed, 28 Aug 2024 21:22:04 +0200 Subject: [PATCH] lab 1 updates by feedback --- content/en/docs/01/_index.md | 109 ++++++++++++++++++++++++----------- content/en/docs/_index.md | 3 +- 2 files changed, 75 insertions(+), 37 deletions(-) diff --git a/content/en/docs/01/_index.md b/content/en/docs/01/_index.md index d15e16b..c4d434e 100644 --- a/content/en/docs/01/_index.md +++ b/content/en/docs/01/_index.md @@ -4,39 +4,74 @@ weight: 1 sectionnumber: 1 --- -## {{% param sectionnumber %}}. Function Calls from the CLI +## The Dagger CLI +The Dagger CLI is the connection to your [Dagger Engine](https://dagger.io/dagger-engine). -Once installed, the `dagger` CLI offers you these functions: +On a common setup the Dagger CLI manages the Dagger Engine over the Docker API. + +The Dagger CLI lets you create, inspect and invoke Dagger Functions from the command line. + + +## Dagger CLI commands + +Once installed, the `dagger` CLI offers you these commands: ``` -call (Call one or more functions, interconnected into a pipeline) -completion (Generate the autocompletion script for the specified shell) -config (Get or set module configuration) -core (Call a core function) -develop (Prepare a local module for development) -functions (List available functions) -help (Help about any command) -init (Initialize a new module) -install (Install a dependency) -login (Log in to Dagger Cloud) -logout (Log out from Dagger Cloud) -query (Send API queries to a dagger engine) -run (Run a command in a Dagger session) -version (Print dagger version) +DAGGER CLOUD COMMANDS + login Log in to Dagger Cloud + logout Log out from Dagger Cloud + +DAGGER MODULE COMMANDS + call Call one or more functions, interconnected into a pipeline + config Get or set module configuration + core Call a core function + develop Prepare a local module for development + functions List available functions + init Initialize a new module + install Install a dependency + +EXECUTION COMMANDS + query Send API queries to a dagger engine + run Run a command in a Dagger session + +ADDITIONAL COMMANDS + completion Generate the autocompletion script for the specified shell + help Help about any command + version Print dagger version ``` {{% alert title="Note" color="primary" %}} -Checkout the autocompletion by tipping `dagger`, followed by some `Tab` keystrokes. +Checkout the autocompletion by tipping `dagger`, followed by some `Tab` keystrokes.\ +Or visit the official documentation: https://docs.dagger.io/reference/cli/ +{{% /alert %}} + + +## Function Calls from the CLI + +The easiest way to get to a function is to use a Dagger module. + +{{% alert title="Note" color="primary" %}} +Dagger Functions are packaged, shared and reused using Dagger Modules. {{% /alert %}} +Dagger Modules are published at the [Daggerverse](https://daggerverse.dev/). +It is similar to the [MvnRepository](https://mvnrepository.com/). The MvnRepository provides Java libraries and the Daggerverse provides Dagger Modules. + The most common way to call Dagger Functions is using the `dagger` CLI: ```bash -dagger -m github.com/shykes/daggerverse/hello@v0.3.0 call hello +dagger call --mod github.com/shykes/daggerverse/hello@v0.3.0 hello ``` -The `dagger` CLI is first loads a `hello` module directly from its [GitHub repository](https://github.com/shykes/daggerverse/tree/main/hello) and then executes the `Hello()` function from that module. +The `dagger` CLI first loads a `hello` module directly from its [GitHub repository](https://github.com/shykes/daggerverse/tree/main/hello) and then executes the `Hello()` function from that module. + +{{% alert title="Note" color="primary" %}} +Explanation to the dagger CLI call.\ +`dagger call` : execute the dagger CLI `call` command\ +`--mod github.com/shykes/daggerverse/hello@v0.3.0` : `call` command option to use the `hello` module (load its functions)\ +`hello` : execute the `hello` function +{{% /alert %}} After a while you should see: @@ -55,14 +90,14 @@ If you are curious, what other [Functions](https://docs.dagger.io/api/reference/ or you can explore its functions using: ```bash -dagger -m github.com/shykes/daggerverse/hello@v0.3.0 functions +dagger functions --mod github.com/shykes/daggerverse/hello@v0.3.0 ``` In this particular case, there aren't any other functions :( - but what about additional arguments of the `Hello()` function? Let's find out: ```bash -dagger -m github.com/shykes/daggerverse/hello@v0.3.0 call hello --help +dagger call --mod github.com/shykes/daggerverse/hello@v0.3.0 hello --help ``` {{% alert title="Note" color="primary" %}} @@ -81,7 +116,7 @@ Dagger also defines powerful core types: [Container](https://docs.dagger.io/api/ To pass a String argument to a Dagger Function, append the corresponding flag to the dagger call command, followed by the string value: ```bash -dagger -m github.com/shykes/daggerverse/hello@v0.3.0 call hello --name=sun +dagger call --mod github.com/shykes/daggerverse/hello@v0.3.0 hello --name=sun ``` @@ -108,7 +143,7 @@ Same as directories, you can pass a Container argument. To do so, add the corres The CLI will dynamically pull the image, and pass the resulting `Container` object as argument to the Dagger Function. ```bash -dagger -m github.com/jpadams/daggerverse/trivy@v0.4.0 call scan-container --ctr=alpine:latest +dagger call --mod github.com/jpadams/daggerverse/trivy@v0.4.0 scan-container --ctr=alpine:latest ``` {{% alert title="Note" color="primary" %}} It is important to know that in Dagger, a `Container` object is not merely a string referencing an image on a remote registry. @@ -127,58 +162,58 @@ Here is an example of passing a GitHub access token from an environment variable The Dagger Function uses the token to query the GitHub CLI for a list of issues in the Dagger open-source repository: ```bash -dagger -m github.com/aweris/daggerverse/gh@v0.0.2 call run --token=env:GITHUB_TOKEN --cmd="issue list --repo=dagger/dagger" +dagger call --mod github.com/aweris/daggerverse/gh@v0.0.2 run --token=env:GITHUB_TOKEN --cmd="issue list --repo=dagger/dagger" ``` -### Task {{% param sectionnumber %}}.1: Explore a module +## Task {{% param sectionnumber %}}.1: Explore a module Explore the `github.com/purpleclay/daggerverse/ponysay@v0.1.0` module. Make it return the phrase `Dagger puts a smile on my face!`. {{% details title="show hint" mode-switcher="normalexpertmode" %}} ```bash -dagger -m github.com/purpleclay/daggerverse/ponysay@v0.1.0 functions +dagger functions --mod github.com/purpleclay/daggerverse/ponysay@v0.1.0 ``` {{% /details %}} {{% details title="show hint" mode-switcher="normalexpertmode" %}} ```bash -dagger -m github.com/purpleclay/daggerverse/ponysay@v0.1.0 call say --help +dagger call --mod github.com/purpleclay/daggerverse/ponysay@v0.1.0 say --help ``` {{% /details %}} {{% details title="show solution" mode-switcher="normalexpertmode" %}} ```bash -dagger -m github.com/purpleclay/daggerverse/ponysay@v0.1.0 call say --msg="Dagger puts a smile on my face!" +dagger call --mod github.com/purpleclay/daggerverse/ponysay@v0.1.0 say --msg="Dagger puts a smile on my face!" ``` {{% /details %}} -### Task {{% param sectionnumber %}}.2: Make use of multiple arguments +## Task {{% param sectionnumber %}}.2: Make use of multiple arguments Call the `Hello()` function of `github.com/shykes/daggerverse/hello@v0.3.0` so that it returns the phrase `Welcome, sunshine!` in ASCII-art. {{% details title="show solution" mode-switcher="normalexpertmode" %}} ```bash -dagger -m github.com/shykes/daggerverse/hello@v0.3.0 call hello --giant --greeting=Welcome --name=sunshine +dagger call --mod github.com/shykes/daggerverse/hello@v0.3.0 hello --giant --greeting=Welcome --name=sunshine ``` {{% /details %}} -### Task {{% param sectionnumber %}}.3: Pass a secret +## Task {{% param sectionnumber %}}.3: Pass a secret Set and replace the `--token` value in the following call with a secret using an environment variable ```bash -dagger -m github.com/aweris/daggerverse/gh@v0.0.2 call run --token=visible --cmd="issue list --repo=dagger/dagger" +dagger call --mod github.com/aweris/daggerverse/gh@v0.0.2 run --token=visible --cmd="issue list --repo=dagger/dagger" ``` {{% details title="show solution" mode-switcher="normalexpertmode" %}} ```bash export SECRET=invisible -dagger -m github.com/aweris/daggerverse/gh@v0.0.2 call run --token=env:SECRET --cmd="issue list --repo=dagger/dagger" +dagger call --mod github.com/aweris/daggerverse/gh@v0.0.2 run --token=env:SECRET --cmd="issue list --repo=dagger/dagger" ``` {{% /details %}} @@ -187,7 +222,7 @@ or using a file {{% details title="show solution" mode-switcher="normalexpertmode" %}} ```bash echo $SECRET > secret.txt -dagger -m github.com/aweris/daggerverse/gh@v0.0.2 call run --token=file:./secret.txt --cmd="issue list --repo=dagger/dagger" +dagger call --mod github.com/aweris/daggerverse/gh@v0.0.2 run --token=file:./secret.txt --cmd="issue list --repo=dagger/dagger" ``` {{% /details %}} @@ -195,6 +230,10 @@ or using a command {{% details title="show solution" mode-switcher="normalexpertmode" %}} ```bash -dagger -m github.com/aweris/daggerverse/gh@v0.0.2 call run --token=cmd:"head -c10 /dev/random | base64" --cmd="issue list --repo=dagger/dagger" +dagger call --mod github.com/aweris/daggerverse/gh@v0.0.2 run --token=cmd:"head -c10 /dev/random | base64" --cmd="issue list --repo=dagger/dagger" ``` {{% /details %}} + +{{% alert title="Note" color="primary" %}} +Unless you provide a working token, the function execution will fail with an `HTTP 401` error. +{{% /alert %}} diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 4d11d47..922abc3 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -8,7 +8,6 @@ menu: ## Welcome to Dagger - No More "Push & Pray!" -Today we are going to learn how to use this powerful, programmable open-source CI/CD engine that also runs your machine! +Today we are going to learn how to use this powerful, programmable open-source CI/CD engine that also runs on your machine! So let's not waste any time and start exploring this brave new world :) -