From 07c633a70792230cc66988991c65ff531ffbd43f Mon Sep 17 00:00:00 2001 From: Luke K Date: Tue, 4 Aug 2020 11:28:49 +0000 Subject: [PATCH] docs: separate repository and system docs --- README.md | 54 +----------- docs/README.md | 60 +++++++++++++ docs/getting_started_kubernetes.md | 8 +- docs/installing_cli.md | 1 + docs/provision_kind.md | 135 +++++++++++++++++++++++++++++ 5 files changed, 202 insertions(+), 56 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/provision_kind.md diff --git a/README.md b/README.md index 50ab3cf4c..68656b1c1 100644 --- a/README.md +++ b/README.md @@ -11,59 +11,7 @@ faas is a "Function as a Service" Client Library and CLI for enabling the development of implicitly deployed, platform agnostic code. -For examples of what's possible, see the [Screencast Series](docs/getting_started_screencast.md) or the [Functions Cookbook](docs/functions_cookbook.md). - -Functions can be written in the following languages: - -* Go (Golang) -* Node.js (JavaScript) -* Quarkus (Java) -* Rust - -Functions can be deployed on the following platforms: - -* Kubernetes -* OpenShift -* Localhost - -[Quickstart Video] - -## Client Installation - -[Install the latest CLI](docs/installing_cli.md) - -[Install the VS Code Plugin](docs/installing_vscode.md) - -[Install the VIM Plugin](docs/installing_vim.md) - -[Install the Emacs Extension](docs/installing_emacs.md) - -Functions can be created and managed using the CLI interactively, scripted, using one of the IDE plugins, or by direct integration with the client library. The [Function Developer's Guide](docs/developers_guide.md)and examples herein demonstrate the CLI-based approach. - -For direct integration using the Go client library, it is advisible to first follow these CLI-based guides to become familiar with creating and deploying software in this way, and then proceed to the [Function Integrator's Guide](docs/integrators_guide.md). - -## Platform Configuration - -[Getting Started with Kubernetes](docs/getting_started_kubernetes.md) - -[Getting Started with OpenShift](docs/getting_started_openshift.md) - -[Getting Started on Localhost](docs/getting_started_localhost.md) - -Functions are portable between different infrastructure configurations. While your Funciton itself remains the same, the platform upon which it is deployed will provide different services and guarantees. For instance, a Function deployed to localhost will not autoscale, nor be either highly available or externally routable. Deploying to a properly configured Kubernetes cluster would however provide these features. There is also variance within infrastrucutre types. For instance, a small kubernetes cluster will be limited in the amount of resources which will be ultimately available for allocation to your Function. - -## Function Development - -[Function Developer's Guide](docs/developers_guide.md) - -Any code which provides one of a set of supported function signatures can be deployed to any of the supported platforms using this client library. No process boundary code, container, or configuration outside of the function itself is required. - -At their most fundamental, a Function is a set of instructions which export a public function whose method signature conforms to one of the supported forms. It is implicitly deployed to a supported platform when created using the client library, and can be migrated between platforms without code changes. Runtime execution is handled by the platform, which may offer guarantees such as autoscaling and load balancing. For more, continue with the Developer's Guide - - -## Learn More - -[Function Architecture](docs/architecture.md) +[Read the Documentation](docs/README.md) ## Contributing diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..ab69b62de --- /dev/null +++ b/docs/README.md @@ -0,0 +1,60 @@ +# FAAS Documentation + +[Demo Screencast] + +faas is a "Function as a Service" Client Library and CLI for enabling the development of implicitly deployed, platform agnostic code. + +For examples of what's possible, see the [Screencast Series](getting_started_screencast.md) or the [Functions Cookbook](functions_cookbook.md). + +Functions can be written in the following languages: + +* Go (Golang) +* Node.js (JavaScript) +* Quarkus (Java) +* Rust + +Functions can be deployed on the following platforms: + +* Kubernetes +* OpenShift +* Localhost + +[Quickstart Video] + +## Client Installation + +[Install the latest CLI](installing_cli.md) + +[Install the VS Code Plugin](installing_vscode.md) + +[Install the VIM Plugin](installing_vim.md) + +[Install the Emacs Extension](installing_emacs.md) + +Functions can be created and managed using the CLI interactively, scripted, using one of the IDE plugins, or by direct integration with the client library. The [Function Developer's Guide](developers_guide.md)and examples herein demonstrate the CLI-based approach. + +For direct integration using the Go client library, it is advisible to first follow these CLI-based guides to become familiar with creating and deploying software in this way, and then proceed to the [Function Integrator's Guide](integrators_guide.md). + +## Platform Configuration + +[Getting Started with Kubernetes](getting_started_kubernetes.md) + +[Getting Started with OpenShift](getting_started_openshift.md) + +[Getting Started on Localhost](getting_started_localhost.md) + +Functions are portable between different infrastructure configurations. While your Function itself remains the same, the platform upon which it is deployed will provide different services and guarantees. For instance, a Function deployed to your local host will not autoscale, nor be highly available nor externally routable by default. Deploying to a properly configured Kubernetes cluster would however provide these features. There is also variance within infrastrucutre types. For instance, a small kubernetes cluster will be limited in the amount of resources which will be ultimately available for allocation to your Function. + +## Function Development + +[Function Developer's Guide](developers_guide.md) + +Any code which provides one of a set of supported function signatures can be deployed to any of the supported platforms using this client library. No process boundary code, container, or configuration outside of the function itself is required. + +At their most fundamental, a Function is a set of instructions which export a public function whose method signature conforms to one of the supported forms. It is implicitly deployed to a supported platform when created using the client library, and can be migrated between platforms without code changes. Runtime execution is handled by the platform, which may offer guarantees such as autoscaling and load balancing. + + +## Learn More + +[Function Architecture](architecture.md) + diff --git a/docs/getting_started_kubernetes.md b/docs/getting_started_kubernetes.md index bf7294236..4e4304de6 100644 --- a/docs/getting_started_kubernetes.md +++ b/docs/getting_started_kubernetes.md @@ -6,10 +6,11 @@ This guide was developed using the dependency versions listed in their requisite Any Kubernetes-compatible API should be capable. Included herein are instructions for two popular variants: Kind and EKS. -## Local dependencies +[Provision using Kind](provision_kind.md) -This guide assumes the following local shared dependncies: -* Kubectl v1.17.3 - [Install `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl) +[Provision using Minikube](provision_minikube.md) + +[Provision using Amazon EKS](provision_eks.md) ## Provisioning a Kind (Kubernetes in Docker) Cluster @@ -17,6 +18,7 @@ This guide assumes the following local shared dependncies: This guide walks through the process of configuring a kind cluster to run Functions with the following vserions: * kind v0.8.1 - [Install Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) +* Kubectl v1.17.3 - [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) Start a new cluster: ``` diff --git a/docs/installing_cli.md b/docs/installing_cli.md index 3e5ac5a70..a0a182db4 100644 --- a/docs/installing_cli.md +++ b/docs/installing_cli.md @@ -27,3 +27,4 @@ To build and install from source check out the repository, run `make`, and insta make mv faas /usr/local/bin/ ``` + diff --git a/docs/provision_kind.md b/docs/provision_kind.md new file mode 100644 index 000000000..ed86e415c --- /dev/null +++ b/docs/provision_kind.md @@ -0,0 +1,135 @@ +# Provisioning a Kind (Kubernetes in Docker) Cluster + +[kind](https://github.com/kubernetes-sigs/kind) is a lightweight tool for running local Kubernetes clusters using containers. It can be used as the underlying infrastructure for Functions, though it is intended for testing and development rather than production deployment. + +This guide walks through the process of configuring a kind cluster to run Functions with the following vserions: +* kind v0.8.1 - [Install Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) +* Kubectl v1.17.3 - [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) + +## Quickstart + +Starting a new cluster with all defaults is as simple as: +``` +kind create cluster +``` +List available clusters: +``` +kind get clusters +``` +List running containers will now show a kind process: +``` +docker ps +``` + +## Configure Remotely + +This section is optional. + +Kind is intended to be a locally-running service, and exposing externally is not recommended. However, a fully configured kubernetes cluster can often quickly outstrip the resources available on even a well-specd development workstation. Therefore, creating a Kind cluster network appliance of sorts can be helpful. One possible way to connect to your kind cluster remotely would be to create a [wireguard](https://www.wireguard.com/) interface upon which to expose the API. Following is an example assuming linux hosts with systemd: + + +First [Install Wireguard](https://www.wireguard.com/install/) + +Create keypair for the host and client. +``` +wg genkey | tee host.key | wg pubkey > host.pub +wg genkey | tee client.key | wg pubkey > client.pub +chmod 600 host.key client.key +``` +Assuming IPv4 addresses, with the wireguard-protected network 10.10.10.0/24, the host being 10.10.10.1 and the client 10.10.10.2 + +On the host, create a Wireguard Network Device: +`/etc/systemd/network/99-wg0.netdev` +``` +[NetDev] +Name=wg0 +Kind=wireguard +Description=WireGuard tunnel wg0 + +[WireGuard] +ListenPort=51111 +PrivateKey=HOST_KEY + +[WireGuardPeer] +PublicKey=HOST_PUB +AllowedIPs=10.10.10.0/24 +PersistentKeepalive=25 +``` +(Replace HOST_KEY and HOST_PUB with the keypair created earlier.) + +`/etc/systemd/network/99-wg0.network` +``` +[Match] +Name=wg0 + +[Network] +Address=10.10.10.1/24 +``` + +On the client, create the Wireguard Network Device and Network: +`/etc/systemd/network/99-wg0.netdev` +``` +[NetDev] +Name=wg0 +Kind=wireguard +Description=WireGuard tunnel wg0 + +[WireGuard] +ListenPort=51871 +PrivateKey=CLIENT_KEY + +[WireGuardPeer] +PublicKey=CLIENT_PUB +AllowedIPs=10.10.10.0/24 +Endpoint=HOST_ADDRESS:51111 +PersistentKeepalive=25 +``` +(Replace HOST_KEY and HOST_PUB with the keypair created earlier.) + +Replace HOST_ADDRESS with an IP address at which the host can be reached prior to to wireguard interface becoming available. + +`/etc/systemd/network/99-wg0.network` +``` +[Match] +Name=wg0 + +[Network] +Address=10.10.10.2/24 +``` +_On both systems_, restrict the permissions of the network device file as it contains sensitive keys, then restart systemd-networkd. +``` +chown root:systemd-network /etc/systemd/network/99-*.netdev +chmod 0640 /etc/systemd/network/99-*.netdev +systemctl restart systemd-networkd +``` +The hosts should now be able to ping each other using their wireguard-protectd 10.10.10.0/24 addresses. Additionally, statistics about the connection can be obtaned from the `wg` command: +``` +wg show +``` +Create a Kind configuration file which instructs the API server to listen on the Wireguard interface and a known port: +`kind-config.yaml` +``` +kind: Cluster +apiVersion: kind.x-k8s.io/v1alpha4 +networking: + apiServerAddress: "10.10.10.1" # default 127.0.0.1 + apiServerPort: 6443 # default random, must be different for each cluster +``` +Delete the current cluster if necessary: +``` +kind delete cluster --name kind +``` +Start a new cluster using the config: +``` +kind create cluster --config kind-config.yaml +``` +Export a kubeconfig and move it to the client machine: +``` +kind export kubeconfig --kubeconfig kind-kubeconfig.yaml +``` +From the client, confirm that pods can be listed: +``` +kubectl get po --all-namespaces --kubeconfig kind-kubeconfig.yaml +``` + +