-
Notifications
You must be signed in to change notification settings - Fork 226
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
fn sink and source reference docs #2013
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,51 +1,52 @@ | ||
--- | ||
title: "Sink" | ||
title: "`sink`" | ||
linkTitle: "sink" | ||
type: docs | ||
description: > | ||
Specify a directory as an output sink package | ||
Write resources to a local directory | ||
--- | ||
|
||
<!--mdtogo:Short | ||
Specify a directory as an output sink package | ||
Write resources to a local directory | ||
--> | ||
|
||
Implements a [sink function] by reading STDIN and writing configuration. | ||
`sink` reads resources from `stdin` and writes them to a local directory. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The format of stdin for There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Added brief note about the input for |
||
Resources must be in one of the following input formats: | ||
|
||
Sink will not prune / delete files for delete resources because it only knows | ||
about files for which it sees input resources. | ||
1. Multi object YAML where resources are separated by `---`. | ||
|
||
### Examples | ||
|
||
<!--mdtogo:Examples--> | ||
2. `Function Specification` wire format where resources are wrapped in an object | ||
of kind ResourceList. | ||
|
||
```shell | ||
# run a function using explicit sources and sinks | ||
kpt fn source DIR/ | | ||
kpt fn run --image gcr.io/example.com/my-fn | | ||
kpt fn sink DIR/ | ||
``` | ||
|
||
<!--mdtogo--> | ||
`sink` is useful for chaining functions using Unix pipe. For more details, | ||
refer to [Chaining functions]. | ||
|
||
### Synopsis | ||
|
||
<!--mdtogo:Long--> | ||
|
||
```shell | ||
kpt fn sink [DIR] | ||
``` | ||
kpt fn sink DIR [flags] | ||
|
||
DIR: | ||
Path to a package directory. Defaults to stdout if unspecified. | ||
Path to a local directory to write resources to. Directory must exist. | ||
``` | ||
|
||
<!--mdtogo--> | ||
|
||
### Next Steps | ||
### Examples | ||
|
||
<!--mdtogo:Examples--> | ||
|
||
- Learn about [functions concepts] like sources, sinks, and pipelines. | ||
- See more examples of sink functions in the functions [catalog]. | ||
``` | ||
# read resources from DIR directory, execute my-fn on them and write the | ||
# output to DIR directory. | ||
$ kpt fn source DIR | | ||
kpt fn eval --image gcr.io/example.com/my-fn - | | ||
kpt fn sink DIR | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. All of the examples here with There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
``` | ||
|
||
<!--mdtogo--> | ||
|
||
[sink function]: https://kpt.dev#todo | ||
[functions concepts]: /book/02-concepts/02-functions | ||
[catalog]: https://kpt.dev#todo | ||
[Chaining functions]: /book/04-using-functions/02-imperative-function-execution?id=chaining-functions-using-the-unix-pipe | ||
[Function Specification]: /book/05-developing-functions/02-function-specification |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,71 +1,64 @@ | ||
--- | ||
title: "Source" | ||
title: "`source`" | ||
linkTitle: "source" | ||
type: docs | ||
description: > | ||
Specify a directory as an input source package | ||
Source resources from a local directory | ||
--- | ||
|
||
<!--mdtogo:Short | ||
Specify a directory as an input source package | ||
Source resources from a local directory | ||
--> | ||
|
||
Implements a [source function] by reading configuration and writing to STDOUT. | ||
`source` reads resources from a local directory and writes them in [Function Specification] | ||
wire format to `stdout`. The output of the `source` can be pipe'd to commands | ||
such as `kpt fn eval` that accepts [Function Specification] wire format. `source` | ||
is useful for chaining functions using Unix pipe. For more details, refer to | ||
[Chaining functions] and [Function Specification]. | ||
|
||
### Examples | ||
### Synopsis | ||
|
||
{{% hide %}} | ||
<!--mdtogo:Long--> | ||
|
||
<!-- @makeWorkplace @verifyExamples--> | ||
``` | ||
# Set up workspace for the test. | ||
TEST_HOME=$(mktemp -d) | ||
cd $TEST_HOME | ||
kpt fn source [DIR] [flags] | ||
``` | ||
|
||
<!-- @fetchPackage @verifyExamples--> | ||
```shell | ||
export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git | ||
kpt pkg get $SRC_REPO/package-examples/helloworld-set@next DIR/ | ||
``` | ||
#### Args | ||
|
||
{{% /hide %}} | ||
``` | ||
DIR: | ||
Path to the local directory containing resources. Defaults to the current | ||
working directory. | ||
``` | ||
|
||
<!--mdtogo:Examples--> | ||
#### Flags | ||
|
||
<!-- @fnSource @verifyExamples--> | ||
```shell | ||
# print to stdout configuration from DIR/ formatted as an input source | ||
kpt fn source DIR/ | ||
``` | ||
--fn-config: | ||
Path to the file containing `functionConfig`. | ||
|
||
```shell | ||
# run a function using explicit sources and sinks | ||
kpt fn source DIR/ | | ||
kpt fn run --image gcr.io/example.com/my-fn | | ||
kpt fn sink DIR/ | ||
``` | ||
|
||
<!--mdtogo--> | ||
### Examples | ||
|
||
### Synopsis | ||
|
||
<!--mdtogo:Long--> | ||
<!--mdtogo:Examples--> | ||
|
||
```shell | ||
kpt fn source [DIR...] | ||
``` | ||
# read resources from DIR directory and write the output on stdout. | ||
$ kpt fn source DIR | ||
``` | ||
|
||
DIR: | ||
Path to a package directory. Defaults to stdin if unspecified. | ||
``` | ||
# read resources from DIR directory, execute my-fn on them and write the | ||
# output to DIR directory. | ||
$ kpt fn source DIR | | ||
kpt fn eval --image gcr.io/example.com/my-fn - | | ||
kpt fn sink DIR | ||
``` | ||
|
||
<!--mdtogo--> | ||
|
||
### Next Steps | ||
|
||
- Learn about [functions concepts] like sources, sinks, and pipelines. | ||
- See more examples of source functions in the functions [catalog]. | ||
|
||
[source function]: https://kpt.dev#todo | ||
[functions concepts]: /book/02-concepts/02-functions | ||
[catalog]: https://kpt.dev#todo | ||
[Chaining functions]: /book/04-using-functions/02-imperative-function-execution?id=chaining-functions-using-the-unix-pipe | ||
[Function Specification]: /book/05-developing-functions/02-function-specification |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If there is no directory specified,
sink
will output to stdout. Will we change this in v1?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
DIR is required argument now. This is changed in
v1
. Not sure output tostdout
makes any sense. If that is the intention, output fromsource
oreval
should be good enough, no need ofsink
. Right ?