From fee85fa2d5d3fba01b79af20d086f6e3a769dff6 Mon Sep 17 00:00:00 2001
From: Ashleigh Brennan <abrennan@redhat.com>
Date: Fri, 23 Apr 2021 10:33:31 -0500
Subject: [PATCH] Add tech preview functions docs

---
 _topic_map.yml                                | 10 ++++
 modules/serverless-build-func-kn.adoc         | 53 +++++++++++++++++++
 modules/serverless-create-func-kn.adoc        | 53 +++++++++++++++++++
 modules/serverless-deploy-func-kn.adoc        | 32 +++++++++++
 modules/serverless-document-attributes.adoc   |  2 +
 modules/serverless-functions-podman.adoc      | 27 ++++++++++
 serverless/functions/images                   |  1 +
 serverless/functions/modules                  |  1 +
 .../functions/serverless-functions-about.adoc | 26 +++++++++
 .../serverless-functions-getting-started.adoc | 22 ++++++++
 .../functions/serverless-functions-setup.adoc | 26 +++++++++
 11 files changed, 253 insertions(+)
 create mode 100644 modules/serverless-build-func-kn.adoc
 create mode 100644 modules/serverless-create-func-kn.adoc
 create mode 100644 modules/serverless-deploy-func-kn.adoc
 create mode 100644 modules/serverless-functions-podman.adoc
 create mode 120000 serverless/functions/images
 create mode 120000 serverless/functions/modules
 create mode 100644 serverless/functions/serverless-functions-about.adoc
 create mode 100644 serverless/functions/serverless-functions-getting-started.adoc
 create mode 100644 serverless/functions/serverless-functions-setup.adoc

diff --git a/_topic_map.yml b/_topic_map.yml
index 7d84ffdc45..78f224e754 100644
--- a/_topic_map.yml
+++ b/_topic_map.yml
@@ -2914,6 +2914,16 @@ Topics:
 # Knative Kafka
 - Name: Using Apache Kafka with OpenShift Serverless
   File: serverless-kafka
+# Functions - uncomment at tech preview
+#- Name: Functions
+#  Dir: functions
+#  Topics:
+#  - Name: About Functions
+#    File: serverless-functions-about
+#  - Name: Setting up Functions
+#    File: serverless-functions-setup
+#  - Name: Getting started with Functions
+#    File: serverless-functions-getting-started
 # Networking
 - Name: Networking
   Dir: networking
diff --git a/modules/serverless-build-func-kn.adoc b/modules/serverless-build-func-kn.adoc
new file mode 100644
index 0000000000..106fce42e9
--- /dev/null
+++ b/modules/serverless-build-func-kn.adoc
@@ -0,0 +1,53 @@
+// Module included in the following assemblies:
+//
+// * serverless/serverless-functions-getting-started.adoc
+
+[id="serverless-build-func-kn_{context}"]
+= Building functions
+
+Before you can run a function, you must build the function project by using the `kn func build` command. The build command reads the `func.yaml` file from the function project directory to determine the image name and registry.
+
+.Example `func.yaml`
+[source,yaml]
+----
+name: fn.example.io
+namespace: default
+runtime: node
+image: <image_from_registry>
+imageDigest: ""
+trigger: http
+builder: default
+builderMap:
+  default: quay.io/boson/faas-nodejs-builder
+envVars: {}
+----
+
+If the image name and registry are not set in the `func.yaml` file, you must either specify the registry flag, `-r` when using the `kn func build` command, or you are prompted to provide a registry value in the terminal when building a function. An image name is then derived from the registry value that you have provided.
+
+.Example command using the `-r` registry flag
+[source,terminal]
+----
+$ kn func build [-i <image> -r <registry> -p <path>]
+----
+
+.Example output
+[source,terminal]
+----
+Building function image
+Function image has been built, image: quay.io/username/fn.example.io:latest
+----
+
+This command creates an OCI container image that can be run locally on your computer, or on a Kubernetes cluster.
+
+.Example using the registy prompt
+[source,terminal]
+----
+$ kn func build
+A registry for function images is required (e.g. 'quay.io/boson').
+
+Registry for function images: quay.io/username
+Building function image
+Function image has been built, image: quay.io/username/fn.example.io:latest
+----
+
+The values for image and registry are persisted to the `func.yaml` file, so that subsequent invocations do not require the user to specify these again.
diff --git a/modules/serverless-create-func-kn.adoc b/modules/serverless-create-func-kn.adoc
new file mode 100644
index 0000000000..4b45f16b87
--- /dev/null
+++ b/modules/serverless-create-func-kn.adoc
@@ -0,0 +1,53 @@
+// Module included in the following assemblies:
+//
+// * serverless/serverless-functions-getting-started.adoc
+
+[id="serverless-create-func-kn_{context}"]
+= Creating functions
+
+You can create a basic serverless function using the `kn` CLI.
+
+You can specify the runtime, trigger, image, and namespace as flags on the command line, or use the `-c` flag to start the interactive experience using the CLI prompt.
+
+The values provided for image and registry are persisted to the `func.yaml` file, so that subsequent invocations do not require the user to specify these again.
+
+.Example `func.yaml`
+[source,yaml]
+----
+name: fn.example.io
+namespace: default
+runtime: node
+image: <image_from_registry>
+imageDigest: ""
+trigger: http
+builder: default
+builderMap:
+  default: quay.io/boson/faas-nodejs-builder
+envVars: {}
+----
+
+.Procedure
+
+* Create a {FunctionsProductShortName} project:
++
+[source,terminal]
+----
+$ kn func create <path> -r <registry> -l <runtime> -t <trigger> -i <image> -n <namespace>
+----
++
+If the image is unspecified, you are prompted for a registry name. The image name is derived from this registry and the function name.
++
+.Example command
+[source,terminal]
+----
+$ kn func create functions/fn.example.io
+----
++
+.Example output
+[source,terminal]
+----
+Project path: /home/user/functions/fn.example.io
+Function name: fn.example.io
+Runtime: node
+Trigger: http
+----
diff --git a/modules/serverless-deploy-func-kn.adoc b/modules/serverless-deploy-func-kn.adoc
new file mode 100644
index 0000000000..1ca8689fc2
--- /dev/null
+++ b/modules/serverless-deploy-func-kn.adoc
@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * serverless/serverless-functions-getting-started.adoc
+
+[id="serverless-deploy-func-kn_{context}"]
+= Deploying functions
+
+You can deploy a function to your cluster as a Knative service by using the `kn func deploy` command.
+
+If the targeted function is already deployed, it is updated with a new container image that is pushed to a container image registry, and the Knative service is updated.
+
+.Prerequisites
+
+* You must have already initialized the function that you want to deploy.
+
+.Procedure
+
+* Deploy a function:
++
+[source,terminal]
+----
+$ kn func deploy [-n <namespace> -p <path> -i <image> -r <registry>]
+----
++
+.Example output
+[source,terminal]
+----
+Function deployed at: http://func.example.com
+----
+** If no `namespace` is specified, the function is deployed in the current namespace.
+** The function is deployed from the current directory, unless a `path` is specified.
+** The Knative service name is derived from the project name, and cannot be changed using this command.
diff --git a/modules/serverless-document-attributes.adoc b/modules/serverless-document-attributes.adoc
index 9a789135b1..394a60bbc0 100644
--- a/modules/serverless-document-attributes.adoc
+++ b/modules/serverless-document-attributes.adoc
@@ -10,6 +10,8 @@
 :ServerlessProductName: OpenShift Serverless
 :ServerlessProductShortName: Serverless
 :ServerlessOperatorName: OpenShift Serverless Operator
+:FunctionsProductName: OpenShift Serverless Functions
+:FunctionsProductShortName: Functions
 //
 // Documentation publishing attributes used in the master-docinfo.xml file
 // Note that the DocInfoProductName generates the URL for the product page.
diff --git a/modules/serverless-functions-podman.adoc b/modules/serverless-functions-podman.adoc
new file mode 100644
index 0000000000..075cfd0f39
--- /dev/null
+++ b/modules/serverless-functions-podman.adoc
@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * serverless/serverless-functions-setup.adoc
+
+[id="serverless-functions-podman_{context}"]
+= Using podman
+
+If you are using podman, you must run the following commands before getting started with {FunctionsProductName}:
+
+. Start the podman service that listens on port `1234`:
++
+[source,terminal]
+----
+$ podman system service --time=0 tcp:0.0.0.0:1234 & # let run in background or another terminal
+----
+
+. Establish the environment variable that is used to build a function:
++
+[source,terminal]
+----
+$ export DOCKER_HOST=tcp://127.0.0.1:1234
+----
++
+[source,terminal]
+----
+$ func build -v
+----
diff --git a/serverless/functions/images b/serverless/functions/images
new file mode 120000
index 0000000000..5e67573196
--- /dev/null
+++ b/serverless/functions/images
@@ -0,0 +1 @@
+../images
\ No newline at end of file
diff --git a/serverless/functions/modules b/serverless/functions/modules
new file mode 120000
index 0000000000..464b823aca
--- /dev/null
+++ b/serverless/functions/modules
@@ -0,0 +1 @@
+../modules
\ No newline at end of file
diff --git a/serverless/functions/serverless-functions-about.adoc b/serverless/functions/serverless-functions-about.adoc
new file mode 100644
index 0000000000..1cd1f72584
--- /dev/null
+++ b/serverless/functions/serverless-functions-about.adoc
@@ -0,0 +1,26 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-functions-about"]
+= About {FunctionsProductShortName}
+:context: serverless-functions-about
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+:FeatureName: {FunctionsProductName}
+include::modules/technology-preview.adoc[leveloffset=+2]
+
+{FunctionsProductName} enables developers to create and deploy stateless, event-driven functions as a Knative service on {product-title}.
+
+The `kn func` CLI is provided as a plug-in for the Knative `kn` CLI. {FunctionsProductName} uses the link:https://buildpacks.io/[CNCF Buildpack API] to create container images. Once a container image has been created, you can use the `kn func` CLI to deploy the container image as a Knative service on the cluster.
+
+[id="serverless-functions-about-runtimes"]
+== Supported runtimes
+
+{FunctionsProductName} provides templates that can be used to create basic functions for the following runtimes:
+
+// add xref links to docs once added
+* Node.js
+* Python
+* Golang
+* Quarkus
+//* SpringBoot - TBC
diff --git a/serverless/functions/serverless-functions-getting-started.adoc b/serverless/functions/serverless-functions-getting-started.adoc
new file mode 100644
index 0000000000..046d81947f
--- /dev/null
+++ b/serverless/functions/serverless-functions-getting-started.adoc
@@ -0,0 +1,22 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-functions-getting-started"]
+= Getting started with {FunctionsProductShortName}
+:context: serverless-functions-getting-started
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+:FeatureName: {FunctionsProductName}
+include::modules/technology-preview.adoc[leveloffset=+2]
+
+This guide explains how you can create and manage a function on an {ServerlessProductName} installation by using the `kn` CLI.
+// TODO: add info about developer console at 4.8 when this is supported.
+
+[id="prerequisites_serverless-functions-getting-started]
+== Prerequisites
+
+Before you can complete the following procedures, you must ensure that you have completed all of the prerequisite tasks in xref:../../serverless/functions/serverless-functions-setup.adoc#serverless-functions-setup[Setting up {FunctionsProductShortName}].
+
+include::modules/serverless-create-func-kn.adoc[leveloffset=+1]
+include::modules/serverless-build-func-kn.adoc[leveloffset=+1]
+include::modules/serverless-deploy-func-kn.adoc[leveloffset=+1]
diff --git a/serverless/functions/serverless-functions-setup.adoc b/serverless/functions/serverless-functions-setup.adoc
new file mode 100644
index 0000000000..3c15236257
--- /dev/null
+++ b/serverless/functions/serverless-functions-setup.adoc
@@ -0,0 +1,26 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-functions-setup"]
+= Setting up {FunctionsProductShortName}
+:context: serverless-functions-setup
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+:FeatureName: {FunctionsProductName}
+include::modules/technology-preview.adoc[leveloffset=+2]
+
+To enable the use of {FunctionsProductShortName} for your {ServerlessProductName} installation, you must complete the following steps:
+
+* {ServerlessProductName} is installed on your cluster.
+* You have installed the xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-getting-started[`oc` CLI].
+* You have installed the xref:../../serverless/installing-kn.adoc#installing-kn[`kn` CLI]. Installing the `kn` CLI enables the use of the `kn func` commands used to create and manage functions.
+* You have installed Docker Container Engine or podman, and have access to an available image registry.
+* If you are using https://quay.io/[Quay.io] as the image registry, you must ensure that either the repository is not private, or that you have followed the {product-title} documentation on xref:../../openshift_images/managing_images/using-image-pull-secrets.adoc#images-allow-pods-to-reference-images-from-secure-registries_using-image-pull-secrets[Allowing pods to reference images from other secured registries].
+
+include::modules/serverless-functions-podman.adoc[leveloffset=+1]
+
+[id="next-steps_serverless-functions-about"]
+== Next steps
+
+* For more information about Docker Container Engine or podman, see xref:../../architecture/understanding-development.adoc#container-build-tool-options[Container build tool options].
+* To get started with {ServerlessProductShortName}, see the xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-functions-getting-started[Developer guide].