From 37db71104cef6e09cb44d34550663cf1dca7b2df Mon Sep 17 00:00:00 2001 From: Marcos Lilljedahl Date: Mon, 11 Apr 2022 18:55:36 -0300 Subject: [PATCH] docs: Add guide to showcase handling outputs Add a guide which highlights how to handle action's outputs by writing them to the client filesystem and using CUE's integrations to marshal them as JSON. Signed-off-by: Marcos Lilljedahl --- docs/guides/1227-contributing.md | 2 +- docs/guides/1228-handling-outputs.md | 28 +++++++++++++++++++ .../client/plans/output_marshal.cue.fragment | 18 ++++++++++++ .../client/plans/output_simple.cue.fragment | 15 ++++++++++ website/sidebars.js | 2 ++ 5 files changed, 64 insertions(+), 1 deletion(-) create mode 100644 docs/guides/1228-handling-outputs.md create mode 100644 docs/tests/core-concepts/client/plans/output_marshal.cue.fragment create mode 100644 docs/tests/core-concepts/client/plans/output_simple.cue.fragment diff --git a/docs/guides/1227-contributing.md b/docs/guides/1227-contributing.md index a31bba14..6c149f1c 100644 --- a/docs/guides/1227-contributing.md +++ b/docs/guides/1227-contributing.md @@ -1,6 +1,6 @@ --- slug: /1227/contributing -displayed_sidebar: europa +displayed_sidebar: 0.2 --- # Contributing to Dagger diff --git a/docs/guides/1228-handling-outputs.md b/docs/guides/1228-handling-outputs.md new file mode 100644 index 00000000..2e87274a --- /dev/null +++ b/docs/guides/1228-handling-outputs.md @@ -0,0 +1,28 @@ +--- +slug: /1226/handling-outputs +displayed_sidebar: 0.2 +--- + +# Handling action outputs + +It's most likely that upon executing a Dagger action, you'll find in the situation of having to parse some outputs. In Dagger 0.1 (pre-Europa), inputs and outputs had to be specifically defined; starting Dagger 0.2 (Europa) we introduced a brand new API which removed this capability temporarily until we come up with the [right UX](https://github.com/dagger/dagger/issues/1351) to bring this back. Until the API is ready, you can follow this guide which shows different **temporary** alternatives of parsing dagger outputs. + +## Writing outputs to the filesystem + +As showcased in the [interacting with the client](/1203/client) docs, Dagger already has the ability to write into the client filesystem through the `client` API. Using this capability we can then output any value into our local filesystem for further automation. + +Here's a simple example of a plain text output: + +```cue file=../tests/core-concepts/client/plans/output_simple.cue.fragment +``` + +After performing `dagger do test`, a new file named `output.txt` will be present in the current working directory with the output of the `bash.#Run` action. + +## Marshalling multiple outputs + +The above example works well for simple outputs, but most of the time some actions like [Netlify's](https://github.com/dagger/dagger/blob/main/pkg/universe.dagger.io/netlify/netlify.cue) can output mutiple values. In this case, Netlify's action is returning the deployment `url`, `deployUrl` and `logsUrl`. On this case, we can leverage on CUE's [default integrations](https://cuelang.org/docs/integrations/) and marshal all the values into a single `json` or `yaml` file. + +Here's an example on how to marshal multiple output values: + +```cue file=../tests/core-concepts/client/plans/output_marshal.cue.fragment +``` diff --git a/docs/tests/core-concepts/client/plans/output_marshal.cue.fragment b/docs/tests/core-concepts/client/plans/output_marshal.cue.fragment new file mode 100644 index 00000000..864a197d --- /dev/null +++ b/docs/tests/core-concepts/client/plans/output_marshal.cue.fragment @@ -0,0 +1,18 @@ +#SomeAction: { + // Nop to make dagger run the action + core.#Nop & {} + url: "test.com" + deployUrl: "test.com/deploy" + logsUrl: "test.com/logs" +} + +dagger.#Plan & { + client: filesystem: "output.json": write: contents: json.Marshal({ + url: actions.test.url + deployUrl: actions.test.deployUrl + logsUrl: actions.test.logsUrl + }) + actions: { + test: #SomeAction & {} + } +} diff --git a/docs/tests/core-concepts/client/plans/output_simple.cue.fragment b/docs/tests/core-concepts/client/plans/output_simple.cue.fragment new file mode 100644 index 00000000..f933348f --- /dev/null +++ b/docs/tests/core-concepts/client/plans/output_simple.cue.fragment @@ -0,0 +1,15 @@ +dagger.#Plan & { + client: filesystem: "output.txt": write: contents: actions.test.export.files["/hello.txt"] + + actions: { + _image: alpine.#Build & { + packages: bash: {} + } + test: bash.#Run & { + input: _image.output + script: contents: "echo Hello World! > /hello.txt" + export: files: "/hello.txt": string + } + + } +} diff --git a/website/sidebars.js b/website/sidebars.js index af53c087..d9dffe93 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -53,6 +53,8 @@ module.exports = { "guides/custom-buildkit", "guides/self-signed-certificates", "guides/pushing-plan-dependencies", + "guides/coding-style", + "guides/handling-outputs", ], }, {