diff --git a/config/nav.yml b/config/nav.yml index 96320edba..f458e7cff 100644 --- a/config/nav.yml +++ b/config/nav.yml @@ -84,7 +84,11 @@ nav: - Knative Functions overview: functions/README.md - Installing Knative Functions: functions/install-func.md - Creating functions: functions/creating-functions.md - - Building, running, or deploying functions: functions/build-run-deploy-func.md + - Building functions: functions/building-functions.md + - Running functions: functions/running-functions.md + - Deploying functions: functions/deploying-functions.md + - Invoking functions: functions/invoking-functions.md + - Language packs: functions/language-packs.md ############################################################################### # Serving ############################################################################### diff --git a/docs/functions/build-run-deploy-func.md b/docs/functions/build-run-deploy-func.md deleted file mode 100644 index 60153fc6b..000000000 --- a/docs/functions/build-run-deploy-func.md +++ /dev/null @@ -1,41 +0,0 @@ -# Building, running, or deploying functions - -After you have created a function project, you can build, run, or deploy your function, depending on your use case. - -## Running a function - ---8<-- "run-func-intro.md" - -### Prerequisites - -- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation. - -### Procedure - ---8<-- "proc-running-function.md" - -## Deploying a function - ---8<-- "deploy-func-intro.md" - -### Prerequisites - -- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation. - -- You have access to a container registry and are able to push images to this registry. - -### Procedure - ---8<-- "proc-deploying-function.md" - -## Building a function - ---8<-- "build-func-intro.md" - -### Prerequisites - -- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation. - -### Procedure - ---8<-- "proc-building-function.md" diff --git a/docs/functions/building-functions.md b/docs/functions/building-functions.md new file mode 100644 index 000000000..ee2da447a --- /dev/null +++ b/docs/functions/building-functions.md @@ -0,0 +1,42 @@ +# Building functions + +--8<-- "build-func-intro.md" + +## Local builds + +You can build a container image for your function locally without deploying it to a cluster, by using the `build` command. + +### Prerequisites + +- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation. + +### Procedure + +--8<-- "proc-building-function.md" + +## On-cluster Builds + +If you do not have a local Docker daemon running, or you are using a CI/CD pipeline, you might want to build your function on the cluster instead of using a local build. You can create an on-cluster build by using the `func deploy --remote` command. + +### Prerequisites + +- The function must exist in a Git repository. +- You must configure your cluster to use Tekton Pipelines. See the [on-cluster build](https://github.com/knative/func/blob/main/docs/reference/on_cluster_build.md){target=_blank} documentation. + +### Procedure + +When running the command for the first time, you must specify the Git URL for the function: + +=== "func" + + ```{ .console } + func deploy --remote --registry --git-url -p hello + ``` + +=== "kn func" + + ```{ .console } + kn func deploy --remote --registry --git-url -p hello + ``` + +After you have specified the Git URL for your function once, you can omit it in subsequent commands. diff --git a/docs/functions/deploying-functions.md b/docs/functions/deploying-functions.md new file mode 100644 index 000000000..d71655ac8 --- /dev/null +++ b/docs/functions/deploying-functions.md @@ -0,0 +1,13 @@ +# Deploying functions + +--8<-- "deploy-func-intro.md" + +## Prerequisites + +- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation. + +- You have access to a container registry and are able to push images to this registry. + +## Procedure + +--8<-- "proc-deploying-function.md" diff --git a/docs/functions/invoking-functions.md b/docs/functions/invoking-functions.md new file mode 100644 index 000000000..c082a99eb --- /dev/null +++ b/docs/functions/invoking-functions.md @@ -0,0 +1,10 @@ +# Invoking functions + +You can use the `func invoke` command to send a test request to invoke a +function either locally or on your Knative cluster. + +This command can be used to test that a function is working and able to receive HTTP requests and CloudEvents correctly. + +If your function is running locally, `func invoke` sends a test request to the local instance. + +You can use the `func invoke` command to send test data to your function with the `--data` flag, as well as other options to simulate different types of requests. See the [func invoke](https://github.com/knative/func/blob/main/docs/reference/func_invoke.md){target=_blank} documentation for more information. diff --git a/docs/functions/language-packs.md b/docs/functions/language-packs.md new file mode 100644 index 000000000..795c0e564 --- /dev/null +++ b/docs/functions/language-packs.md @@ -0,0 +1,32 @@ +# Language packs + +Language packs can be used to extend Knative Functions to support additional runtimes, function signatures, operating systems, and installed tooling for functions. Language Packs are distributed through Git repositories or as a directory on a disc. + +For more information see the [language pack](https://github.com/knative/func/blob/main/docs/language-pack-providers/language-pack-contract.md){target=_blank} documentation. + +## Using external Git repositories + +When creating a new function, a Git repository can be specified as the source +for the template files. The Knative Sandbox maintains a set of [example templates](https://github.com/knative-sandbox/func-tastic){target=_blank} which can be used during project creation. + +For example, you can run the following command to use the [`metacontroller`](https://metacontroller.github.io/metacontroller/){target=_blank} template for Node.js: + +```{ .console } +func create myfunc -l nodejs -t metacontroller --repository https://github.com/knative-sandbox/func-tastic +``` + +## Installing language packs locally + +Language packs can be installed locally by using the [`func repository`](https://github.com/knative/func/blob/main/docs/reference/func_repository.md){target=_blank} command. + +For example, to add the Knative Sandbox example templates, you can run the following command: + +```{ .console } +func repository add knative https://github.com/knative-sandbox/func-tastic +``` + +After the Knative Sandbox example templates are installed, you can use the `metacontroller` template by specifying the `knative` prefix in the `create` command: + +```{ .console } +func create -t knative/metacontroller -l nodejs my-controller-function +``` diff --git a/docs/functions/running-functions.md b/docs/functions/running-functions.md new file mode 100644 index 000000000..9d74991c1 --- /dev/null +++ b/docs/functions/running-functions.md @@ -0,0 +1,11 @@ +# Running functions + +--8<-- "run-func-intro.md" + +## Prerequisites + +- You have a Docker daemon on your local machine. This is already provided if you have used the Quickstart installation. + +## Procedure + +--8<-- "proc-running-function.md" diff --git a/docs/snippets/build-func-intro.md b/docs/snippets/build-func-intro.md index 43d5c6052..c4f6b491c 100644 --- a/docs/snippets/build-func-intro.md +++ b/docs/snippets/build-func-intro.md @@ -1,5 +1,5 @@ Building a function creates an OCI container image for your function that can be pushed to a container registry. It does not run or deploy the function, which can be useful if you want to build a container image for your function locally, but do not want to automatically run the function or deploy it to a cluster, for example, in a testing scenario. diff --git a/docs/snippets/create-a-function.md b/docs/snippets/create-a-function.md index 43130ba07..9a3927e69 100644 --- a/docs/snippets/create-a-function.md +++ b/docs/snippets/create-a-function.md @@ -5,12 +5,24 @@ After you have installed Knative Functions, you can create a function project by === "`func` CLI" + ```bash + func create -l + ``` + + Example: + ```bash func create -l go hello ``` === "`kn func` plugin" + ```bash + kn func create -l + ``` + + Example: + ```bash kn func create -l go hello ``` @@ -20,3 +32,5 @@ After you have installed Knative Functions, you can create a function project by ```{ .bash .no-copy } Created go function in hello ``` + +For more information about options for function `create` commands, see the [func create](https://github.com/knative/func/blob/main/docs/reference/func_create.md){target=_blank} documentation. diff --git a/docs/snippets/deploy-func-intro.md b/docs/snippets/deploy-func-intro.md index 6c17490b8..a9e75670b 100644 --- a/docs/snippets/deploy-func-intro.md +++ b/docs/snippets/deploy-func-intro.md @@ -1,4 +1,5 @@ Deploying a function creates an OCI container image for your function, and pushes this container image to your image registry. The function is deployed to the cluster as a Knative Service. Redeploying a function updates the container image and resulting Service that is running on your cluster. Functions that have been deployed to a cluster are accessible on the cluster just like any other Knative Service. diff --git a/docs/snippets/proc-building-function.md b/docs/snippets/proc-building-function.md index f165f0a43..cffbbe33c 100644 --- a/docs/snippets/proc-building-function.md +++ b/docs/snippets/proc-building-function.md @@ -1,6 +1,6 @@ The `build` command uses the project name and the image registry name to construct a fully qualified container image name for the function. If the function project has not previously been built, you are prompted to provide an image registry. diff --git a/docs/snippets/proc-deploying-function.md b/docs/snippets/proc-deploying-function.md index c77ec9264..6681a35e1 100644 --- a/docs/snippets/proc-deploying-function.md +++ b/docs/snippets/proc-deploying-function.md @@ -1,6 +1,6 @@ The `deploy` command uses the function project name as the Knative Service name. When the function is built, the project name and the image registry name are used to construct a fully qualified image name for the function. diff --git a/docs/snippets/proc-running-function.md b/docs/snippets/proc-running-function.md index 946afa9f2..d09d43f16 100644 --- a/docs/snippets/proc-running-function.md +++ b/docs/snippets/proc-running-function.md @@ -1,6 +1,6 @@ The `run` command builds an image for your function if required, and runs this image locally, instead of deploying it on a cluster. diff --git a/docs/snippets/run-func-intro.md b/docs/snippets/run-func-intro.md index 4f1ec191b..210f16f21 100644 --- a/docs/snippets/run-func-intro.md +++ b/docs/snippets/run-func-intro.md @@ -1,5 +1,5 @@ Running a function creates an OCI container image for your function before running the function in your local environment, but does not deploy the function to a cluster. This can be useful if you want to run your function locally for a testing scenario.