diff --git a/docs/README.md b/docs/README.md index 16b983d679d..7cb6b4fa802 100644 --- a/docs/README.md +++ b/docs/README.md @@ -91,4 +91,19 @@ Already using AWS or another cloud provider? Read on. +
+
+ + + +
+
+ +
+
diff --git a/docs/getting-started.md b/docs/getting-started.md index b4fdd74b38f..a5a81825290 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -64,4 +64,14 @@ npm install -g serverless Google Cloud Functions
Quick Start Guide +
+
+ + + +
+
+ Kubeless
Quick Start Guide +
+
diff --git a/docs/providers/README.md b/docs/providers/README.md index bd5a7e1edbb..8efd27b5d40 100644 --- a/docs/providers/README.md +++ b/docs/providers/README.md @@ -53,6 +53,16 @@ Under the hood, the serverless framework is deploying your code to a cloud provi Cloud Functions Docs +
+
+ + + +
+
+ Kubeless Docs +
+

diff --git a/docs/providers/kubeless/README.md b/docs/providers/kubeless/README.md new file mode 100644 index 00000000000..25256cb1d8d --- /dev/null +++ b/docs/providers/kubeless/README.md @@ -0,0 +1,70 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/) + + +# Kubeless Provider Documentation + +Welcome to the Serverless Kubeless documentation! + +If you have questions, join the [chat in gitter](https://gitter.im/serverless/serverless) or [post over on the forums](https://gitter.im/serverless/serverless) + +
+
+
+ + Serverless Framework Kubeless Guide + +
+
+ +
+
+ +
+
+ + Serverless Framework Kubeless CLI Reference + +
+
+ +
+
+ +
+
+ + Serverless Framework Kubeless Events Reference + +
+
+ +
+
+
diff --git a/docs/providers/kubeless/cli-reference/README.md b/docs/providers/kubeless/cli-reference/README.md new file mode 100644 index 00000000000..246c0aed1c2 --- /dev/null +++ b/docs/providers/kubeless/cli-reference/README.md @@ -0,0 +1,15 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/cli-reference/) + + +# Serverless Kubeless CLI Reference + +Welcome to the Serverless Kubeless CLI Reference! Please select a section on the left to get started. + +If you have questions, join the [chat in gitter](https://gitter.im/serverless/serverless) or [post over on the forums](http://forum.serverless.com/). diff --git a/docs/providers/kubeless/cli-reference/create.md b/docs/providers/kubeless/cli-reference/create.md new file mode 100644 index 00000000000..a331f280154 --- /dev/null +++ b/docs/providers/kubeless/cli-reference/create.md @@ -0,0 +1,74 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/cli-reference/create) + + +# Kubeless - Create + +Creates a new Serverless service in the current working directory based on the provided template. + +**Create service in current working directory:** + +```bash +serverless create --template kubeless-python +``` + +```bash +serverless create --template kubeless-nodejs +``` + +**Create service in new folder:** + +```bash +serverless create --template kubeless-python --path my-service +``` + +```bash +serverless create --template kubeless-nodejs --path my-service +``` + +## Options +- `--template` or `-t` The name of one of the available templates. **Required**. +- `--path` or `-p` The path where the service should be created. +- `--name` or `-n` the name of the service in `serverless.yml`. + +## Provided lifecycle events +- `create:create` + +## Available Templates for Kubeless + +To see a list of available templates run `serverless create --help` + +These are the current available templates for Kubeless: + +- kubeless-nodejs +- kubeless-python + +## Examples + +### Creating a new Serverless service + +```bash +serverless create --template kubeless-python --name my-special-service +``` + +This example will generate scaffolding for a service with `kubeless` as a provider and `python2.7` as runtime. The scaffolding will be generated in the current working directory. + +The provider which is used for deployment later on is Kubeless. + +### Creating a named service in a (new) directory + +```bash +serverless create --template kubeless-python --path my-new-service +``` + +This example will generate scaffolding for a service with `kubeless` as a provider and `python2.7` as runtime. The scaffolding will be generated in the `my-new-service` directory. This directory will be created if not present. Otherwise Serverless will use the already present directory. + +Additionally Serverless will rename the service according to the path you provide. In this example the service will be renamed to `my-new-service`. \ No newline at end of file diff --git a/docs/providers/kubeless/cli-reference/deploy.md b/docs/providers/kubeless/cli-reference/deploy.md new file mode 100644 index 00000000000..202a8913d5f --- /dev/null +++ b/docs/providers/kubeless/cli-reference/deploy.md @@ -0,0 +1,42 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/cli-reference/deploy) + + +# Kubeless - Deploy + +The `sls deploy` command deploys your entire service via the Kubeless API. Run this command when you have made service changes (i.e., you edited `serverless.yml`). + +Use `serverless deploy function -f my-function` when you have made code changes and you want to quickly upload your updated code to your Kubernetes cluster or when you want to deploy just a function of your Serverless service. + +```bash +serverless deploy +``` + +This is the simplest deployment usage possible. With this command Serverless will deploy your service to the default Kubernetes cluster in your kubeconfig file. + +## Options +- `--noDeploy` or `-n` Skips the deployment steps and leaves artifacts in the `.serverless` directory +- `--verbose` or `-v` Shows all stack events during deployment, and display any Stack Output. +- `--function` or `-f` The name of the function which should be deployed + +## Artifacts + +After the `serverless deploy` command runs all created deployment artifacts are placed in the `.serverless` folder of the service. + +## Provided lifecycle events +- `deploy:cleanup` +- `deploy:initialize` +- `deploy:setupProviderConfiguration` +- `deploy:createDeploymentArtifacts` +- `deploy:compileFunctions` +- `deploy:compileEvents` +- `deploy:deploy` +- `deploy:function:deploy` diff --git a/docs/providers/kubeless/cli-reference/info.md b/docs/providers/kubeless/cli-reference/info.md new file mode 100644 index 00000000000..a38028071c4 --- /dev/null +++ b/docs/providers/kubeless/cli-reference/info.md @@ -0,0 +1,58 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/cli-reference/info) + + +# Kubeless - Info + +Displays information about the deployed service. + +```bash +serverless info +``` + +## Options +- `--verbose` or `-v` Shows the metadata of the Kubernetes objects. + +## Provided lifecycle events +- `info:info` + +## Examples + +On Kubeless the info plugin uses the Kubernetes API to gather the necessary +information about deployed functions and Kubernetes services. See the example +below for an example output. + +**Example:** + +```bash +$ serverless info -v + +Service Information "hello" +Cluster IP: 10.0.0.203 +Type: ClusterIP +Ports: + Protocol: TCP + Port: 8080 + Target Port: 8080 +Metadata + Self Link: /api/v1/namespaces/default/services/hello + UID: 7c2494ea-8976-11e7-b8c4-0800275c88b3 + Timestamp: 2017-08-25T09:19:24Z +Function Info +Handler: handler.hello +Runtime: python2.7 +Trigger: HTTP +Dependencies: +Metadata: + Self Link: /apis/k8s.io/v1/namespaces/default/functions/hello + UID: 7c214cab-8976-11e7-b8c4-0800275c88b3 + Timestamp: 2017-08-25T09:19:23Z +``` diff --git a/docs/providers/kubeless/cli-reference/invoke.md b/docs/providers/kubeless/cli-reference/invoke.md new file mode 100644 index 00000000000..cee892cc5d5 --- /dev/null +++ b/docs/providers/kubeless/cli-reference/invoke.md @@ -0,0 +1,68 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/cli-reference/invoke) + + +# Kubeless - Invoke + +Invokes deployed function. It allows to send event data to the function, read logs and display other important information of the function invocation. + +```bash +serverless invoke --function functionName +``` + +## Options +- `--function` or `-f` The name of the function in your service that you want to invoke. **Required**. +- `--data` or `-d` String data to be passed as an event to your function. By default data is read from standard input. +- `--path` or `-p` The path to a json file with input data to be passed to the invoked function. This path is relative to the root directory of the service. +- `--log` or `-l` If set to `true`, it will output logging data of the invocation. Default is `false`. + +## Provided lifecycle events +- `invoke:invoke` + +## Examples + +### Kubeless + +```bash +serverless invoke --function functionName +``` + +This example will invoke your deployed function on the configured platform +endpoint. This will output the result of the invocation in your terminal. + +#### Function invocation with data + +```bash +serverless invoke --function functionName --data '{"name": "Bernie"}' +``` + +#### Function invocation with data from standard input + +```bash +node dataGenerator.js | serverless invoke --function functionName +``` + +#### Function invocation with logging + +```bash +serverless invoke --function functionName --log +``` + +Just like the first example, but will also outputs logging information about your invocation. + +#### Function invocation with data passing + +```bash +serverless invoke --function functionName --path lib/data.json +``` + +This example will pass the json data in the `lib/data.json` file (relative to the root of the service) while invoking +the specified/deployed function. diff --git a/docs/providers/kubeless/cli-reference/logs.md b/docs/providers/kubeless/cli-reference/logs.md new file mode 100644 index 00000000000..29d620d0ac3 --- /dev/null +++ b/docs/providers/kubeless/cli-reference/logs.md @@ -0,0 +1,73 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/cli-reference/logs) + + +# Kubeless - Logs + +Lets you watch the logs of a specific function. + +```bash +serverless logs -f hello +``` + +## Options + +- `--function` or `-f` The function you want to fetch the logs for. **Required** +- `--startTime` A specific unit in time to start fetching logs from (ie: `2010-10-20` or `1469705761`). Here's a list of the supported string formats: + +```bash +30m # since 30 minutes ago +2h # since 2 hours ago +3d # since 3 days ago + +2013-02-08 # A calendar date part +2013-W06-5 # A week date part +2013-039 # An ordinal date part + +20130208 # Basic (short) full date +2013W065 # Basic (short) week, weekday +2013W06 # Basic (short) week only +2013050 # Basic (short) ordinal date + +2013-02-08T09 # An hour time part separated by a T +20130208T080910,123 # Short date and time up to ms, separated by comma +20130208T080910.123 # Short date and time up to ms +20130208T080910 # Short date and time up to seconds +20130208T0809 # Short date and time up to minutes +20130208T08 # Short date and time, hours only +``` + +- `--filter` You can specify a filter string to filter the log output. This is useful if you want to to get the `error` logs for example. +- `--tail` or `-t` You can optionally tail the logs and keep listening for new logs in your terminal session by passing this option. +- `--interval` or `-i` If you choose to tail the output, you can control the interval at which the framework polls the logs with this option. The default is `1000`ms. + +## Examples + +```bash +serverless logs -f hello --startTime 5h +``` +This will fetch the logs that happened in the past 5 hours. + +```bash +serverless logs -f hello --startTime 1469694264 +``` +This will fetch the logs that happened starting at epoch `1469694264`. + +```bash +serverless logs -f hello -t +``` + +Serverless will tail the platform log output and print new log messages coming in. + +```bash +serverless logs -f hello --filter serverless +``` +This will fetch only the logs that contain the string `serverless` diff --git a/docs/providers/kubeless/cli-reference/remove.md b/docs/providers/kubeless/cli-reference/remove.md new file mode 100644 index 00000000000..2b6992a4999 --- /dev/null +++ b/docs/providers/kubeless/cli-reference/remove.md @@ -0,0 +1,24 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/cli-reference/remove) + + +# Kubeless - Remove + +The `sls remove` command will remove the deployed service, defined in your current working directory, from the provider. + +```bash +serverless remove +``` + +It will remove the Kubeless Function objects from your Kubernetes cluster, the Kubernetes Deployments and the Kubernetes Services associated with the Serverless service. + +## Provided lifecycle events +- `remove:remove` diff --git a/docs/providers/kubeless/events/README.md b/docs/providers/kubeless/events/README.md new file mode 100644 index 00000000000..05e2139b9b0 --- /dev/null +++ b/docs/providers/kubeless/events/README.md @@ -0,0 +1,18 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/events/) + + +# Serverless Kubeless Events + +Welcome to the Serverless Kubeless Events Glossary! + +Please select a section on the left to get started. + +If you have questions, join the [chat in gitter](https://gitter.im/serverless/serverless) or [post over on the forums](http://forum.serverless.com/) + diff --git a/docs/providers/kubeless/events/http.md b/docs/providers/kubeless/events/http.md new file mode 100644 index 00000000000..a6440fe42a8 --- /dev/null +++ b/docs/providers/kubeless/events/http.md @@ -0,0 +1,93 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/events/http) + + +# Kubeless HTTP Events + +The first type of events that you can create in Kubeless are HTTP events. + +When creating HTTP events, Kubeless will create a Kubernetes Service that you can call through Serverless or directly calling the HTTP endpoint. + +## Single HTTP Endpoint + +If you don't specify the type of event in your `serverless.yml` Kubeless will create an HTTP endpoint by default: + +```yml +service: testing-pkg + +provider: + name: kubeless + runtime: python2.7 + +plugins: + - serverless-kubeless + +functions: + hello: + handler: handler.hello +``` + +When deploying this `serverless.yml` file, Kubeless will create a Kubernetes service with a single endpoint. Calling that HTTP endpoint will trigger the function associated with it. + +## Multiple endpoints with Ingress rules + +You can also deploy several endpoints in a single `serverless.yml` file: + +```yml +service: todos + +provider: + name: kubeless + runtime: nodejs6 + +plugins: + - serverless-kubeless + +functions: + create: + handler: todos-create.create + events: + - http: + path: /create + read-all: + handler: todos-read-all.readAll + events: + - http: + path: /read-all + read-one: + handler: todos-read-one.readOne + events: + - http: + path: /read + update: + handler: todos-update.update + events: + - http: + path: /update + delete: + handler: todos-delete.delete + events: + - http: + path: /delete + +``` + +If the events HTTP definitions contain a `path` attribute, when deploying this Serverless YAML definition, Kubeless will create the needed [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) rules to redirect each of the requests to the right service: + +``` +kubectl get ingress +NAME HOSTS ADDRESS PORTS AGE +ingress-create * 192.168.99.100 80 2m +ingress-delete * 192.168.99.100 80 2m +ingress-read-all * 192.168.99.100 80 2m +ingress-read-one * 192.168.99.100 80 2m +ingress-update * 192.168.99.100 80 2m +``` \ No newline at end of file diff --git a/docs/providers/kubeless/events/pubsub.md b/docs/providers/kubeless/events/pubsub.md new file mode 100644 index 00000000000..d3ef2065b74 --- /dev/null +++ b/docs/providers/kubeless/events/pubsub.md @@ -0,0 +1,52 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/events/pubsub) + + +# Kubeless PubSub Events + +Kubeless functions can also be registered to listen to PubSub events in a Kafka topic. Kafka (and Zookeeper) are deployed in your Kubernetes cluster as part of the Kubeless deployment. + +The function then will be triggered whenever a message is published under a certain topic. + +The topic in which the function will be listening is defined in the events section of the `serverless.yml`: + +``` +service: hello + +provider: + name: kubeless + runtime: python2.7 + +plugins: + - serverless-kubeless + +functions: + hello: + handler: handler.hello + events: + - trigger: 'hello_topic' +``` + +## Triggering a function + +You can trigger a function by publishing a message under a certain topic. + +The Kubeless CLI allows to do this from your command line: + +``` +kubeless topic publish --topic hello_topic --data 'hello world!' # push a message into the queue +serverless logs -f hello + +# Output +hello world! +``` + +You can install the Kubeless CLI tool following the [../guide/installation](installation guide). diff --git a/docs/providers/kubeless/guide/README.md b/docs/providers/kubeless/guide/README.md new file mode 100644 index 00000000000..52f54ab6673 --- /dev/null +++ b/docs/providers/kubeless/guide/README.md @@ -0,0 +1,17 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/guide/) + + +# Serverless Kubeless Guide + +Welcome to the Serverless Kubeless Guide! + +Get started with the **[Introduction to the Serverless framework](./intro.md)** + +If you have questions, join the [chat in gitter](https://gitter.im/serverless/serverless) or [post over on the forums](http://forum.serverless.com/) diff --git a/docs/providers/kubeless/guide/debugging.md b/docs/providers/kubeless/guide/debugging.md new file mode 100644 index 00000000000..8e58324b660 --- /dev/null +++ b/docs/providers/kubeless/guide/debugging.md @@ -0,0 +1,164 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/guide/debugging) + + +# Kubeless - Debugging + +How can we debug errors in our Kubeless functions? + +Let's imagine that we have deployed the following Python code as a Kubeless function using Serverless: + +```python +import urllib2 +import json + +def find(request): + term = request.json["term"] + url = "https://feeds.capitalbikeshare.com/stations/stations.json" + response = urllib2.urlopen(url) + stations = json.loads(response.read()) + + hits = [] + + for station in stations["stationBeanList"]: + if station["stAddress1"].find(term) > -1: + hits.append(station) + + return json.dumps(hits) +``` + +And its corresponding Serverless YAML file: + +```yml +# serverless.yml +service: bikesearch +provider: + name: kubeless + runtime: python2.7 + +plugins: + - serverless-kubeless + +functions: + bikesearch: + handler: handler.find +``` + +Let's invoke correctly that function + +``` +serverless invoke --function bikesearch --data '{"term":"Albemarle"}' -l + +# Output +Serverless: Calling function: bikesearch... +-------------------------------------------------------------------- +[ { availableDocks: 6, + totalDocks: 15, + city: '', + altitude: '', + stAddress2: '', + longitude: -77.079382, + lastCommunicationTime: '2017-08-25 04:46:09 AM', + postalCode: '', + statusValue: 'In Service', + testStation: false, + stAddress1: 'Tenleytown / Wisconsin Ave & Albemarle St NW', + stationName: 'Tenleytown / Wisconsin Ave & Albemarle St NW', + landMark: '', + latitude: 38.947607, + statusKey: 1, + availableBikes: 9, + id: 80, + location: '' } ] +``` + +What happens when something goes wrong? The function currently has no error handling, so that's easy enough to test. Let's invoke the function again with a typo (use *trm* as the name of the input parameter instead of *term*): + +``` +serverless invoke --function bikesearch --data '{"trm":"Albemarle"}' -l + +# Output +Serverless: Calling function: bikesearch... + + Serverless Error --------------------------------------- + + Internal Server Error + + Get Support -------------------------------------------- + Docs: docs.serverless.com + Bugs: github.com/serverless/serverless/issues + Forums: forum.serverless.com + Chat: gitter.im/serverless/serverless + + Your Environment Information ----------------------------- + OS: darwin + Node Version: 8.3.0 + Serverless Version: 1.20.2 +``` + +Serverless returned an error message with a 500 server code, which is what you would expect from a web framework. However, it would be useful to see Python stack trace to better debug the source of the error. To achieve this, first find the container where the function is running using *kubectl*: + +``` +kubectl get pods + +# Output +NAME READY STATUS RESTARTS AGE +bikesearch-3894699941-mbt2t 1/1 Running 1 2d +``` + +Once the name of the container is known, use *kubectl logs* to check the logs: + +``` +kubectl logs bikesearch-3894699941-mbt2t + +# Output +Bottle v0.12.13 server starting up (using CherryPyServer())... +Listening on http://0.0.0.0:8080/ +Hit Ctrl-C to quit. + +172.17.0.1 - - [25/Aug/2017:08:45:20 +0000] "GET /healthz HTTP/1.1" 200 2 "" "Go-http-client/1.1" 0/171 +172.17.0.1 - - [25/Aug/2017:08:45:34 +0000] "GET /healthz HTTP/1.1" 200 2 "" "Go-http-client/1.1" 0/72 +172.17.0.1 - - [25/Aug/2017:08:46:04 +0000] "GET /healthz HTTP/1.1" 200 2 "" "Go-http-client/1.1" 0/82 +172.17.0.1 - - [25/Aug/2017:08:46:07 +0000] "POST / HTTP/1.1" 200 459 "" "" 1/957186 +Traceback (most recent call last): + File "/usr/local/lib/python2.7/site-packages/bottle.py", line 862, in _handle + return route.call(**args) + File "/usr/local/lib/python2.7/site-packages/bottle.py", line 1740, in wrapper + rv = callback(*a, **ka) + File "/kubeless.py", line 35, in handler + return func(bottle.request) + File "/kubeless/handler.py", line 5, in find + term = request.json["term"] +KeyError: 'term' +172.17.0.1 - - [25/Aug/2017:08:46:16 +0000] "POST / HTTP/1.1" 500 746 "" "" 0/6703 +172.17.0.1 - - [25/Aug/2017:08:46:34 +0000] "GET /healthz HTTP/1.1" 200 2 "" "Go-http-client/1.1" 0/122 +172.17.0.1 - - [25/Aug/2017:08:46:46 +0000] "POST / HTTP/1.1" 200 459 "" "" 0/892144 +172.17.0.1 - - [25/Aug/2017:08:47:04 +0000] "GET /healthz HTTP/1.1" 200 2 "" "Go-http-client/1.1" 0/75 +172.17.0.1 - - [25/Aug/2017:08:47:34 +0000] "GET /healthz HTTP/1.1" 200 2 "" "Go-http-client/1.1" 0/102 +172.17.0.1 - - [25/Aug/2017:08:48:04 +0000] "GET /healthz HTTP/1.1" 200 2 "" "Go-http-client/1.1" 0/113 +172.17.0.1 - - [25/Aug/2017:08:48:34 +0000] "GET /healthz HTTP/1.1" 200 2 "" "Go-http-client/1.1" 0/69 +172.17.0.1 - - [25/Aug/2017:08:49:04 +0000] "GET /healthz HTTP/1.1" 200 2 "" "Go-http-client/1.1" 0/98 +172.17.0.1 - - [25/Aug/2017:08:49:23 +0000] "POST / HTTP/1.1" 500 746 "" "" 0/655 +Traceback (most recent call last): + File "/usr/local/lib/python2.7/site-packages/bottle.py", line 862, in _handle + return route.call(**args) + File "/usr/local/lib/python2.7/site-packages/bottle.py", line 1740, in wrapper + rv = callback(*a, **ka) + File "/kubeless.py", line 35, in handler + return func(bottle.request) + File "/kubeless/handler.py", line 5, in find + term = request.json["term"] +KeyError: 'term' +``` + +It should be clear from the second-to-last line that the error originates in an incorrect key name. + +This is a very basic example of debugging a Kubeless function, but it should hopefully highlight the basic principles. Obviously, in production environments, you would want to have more formal and sophisticated error handling built into your code. \ No newline at end of file diff --git a/docs/providers/kubeless/guide/deploying.md b/docs/providers/kubeless/guide/deploying.md new file mode 100644 index 00000000000..9c8288c1de1 --- /dev/null +++ b/docs/providers/kubeless/guide/deploying.md @@ -0,0 +1,87 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/guide/deploying) + + +# Kubeless - Deploying + +The Serverless Framework was designed to provision your Kubeless Functions and Events. It does this via a couple of methods designed for different types of deployments. + +## Deploy All + +This is the main method for doing deployments with the Serverless Framework: + +```bash +serverless deploy -v +``` + +Use this method when you have updated your Function, Event or Resource configuration in `serverless.yml` and you want to deploy that change (or multiple changes at the same time) to your Kubernetes cluster. + +### How It Works + +The Serverless Framework translates all syntax in `serverless.yml` to [the Function object API](https://github.com/kubeless/kubeless/blob/master/pkg/spec/spec.go) calls to provision your Functions and Events. + +For each function in your `serverless.yml` file, Kubeless will create an Kubernetes Function object and for each HTTP event, it will create a [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/). + +For example, let's take the following example `serverless.yml` file: + +```yaml +service: new-project +provider: + name: kubeless + runtime: python2.7 + +plugins: + - serverless-kubeless + +functions: + hello: + handler: handler.hello +``` + +When deploying that file, the following objects will be created in your Kubernetes cluster: + +``` +$ kubectl get functions + +NAME KIND +hello Function.v1.k8s.io +``` + +``` +$ kubectl get all + +NAME READY STATUS RESTARTS AGE +po/hello-699783077-dk15r 1/1 Running 0 2m + +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +svc/hello 10.0.0.39 8080/TCP 2m + +NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +deploy/hello 1 1 1 1 2m + +NAME DESIRED CURRENT READY AGE +rs/hello-699783077 1 1 1 2m +``` + +Kubeless will create a [Kubernetes Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) for your function and a [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) for each event. + + +## Deploy Function + +This deployment method updates a single function. It performs the platform API call to deploy your package without the other resources. It is much faster than redeploying your whole service each time. + +```bash +serverless deploy function --function myFunction +``` + +### Tips + +Check out the [deploy command docs](../cli-reference/deploy.md) for all details and options. diff --git a/docs/providers/kubeless/guide/events.md b/docs/providers/kubeless/guide/events.md new file mode 100644 index 00000000000..4f5a42c06b4 --- /dev/null +++ b/docs/providers/kubeless/guide/events.md @@ -0,0 +1,19 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/guide/events) + + +# Kubeless - Events + +Simply put, events are the things that trigger your functions to run. + +If you are using Kubeless as your provider, all `events` in the service are anything in Kubeless that can trigger your Functions, like HTTP endpoints or message queues. + +[View the Kubeless events section for a list of supported events](../events) diff --git a/docs/providers/kubeless/guide/functions.md b/docs/providers/kubeless/guide/functions.md new file mode 100644 index 00000000000..b85619a2694 --- /dev/null +++ b/docs/providers/kubeless/guide/functions.md @@ -0,0 +1,90 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/guide/functions) + + +# Kubeless - Functions + +If you are using Kubeless as a provider, all *functions* inside the service are Kubernetes Function.v1.k8s.io objects. + +## Configuration + +All of the Kubeless Functions in your serverless service can be found in `serverless.yml` under the `functions` property. + +```yml +# serverless.yml +service: my-service + +provider: + name: kubeless + runtime: python2.7 + +plugins: + - serverless-kubeless + +functions: + # The top name will be the name of the Function object + # and the K8s service object to get a request to call the function + hello: + # The function to call as a response to the HTTP event + handler: handler.hello +``` + +The `handler` property points to the file and module containing the code you want to run in your function. + +```python +// handler.py +import json + +def hello(request): + body = { + "message": "Go Serverless v1.0! Your function executed successfully!", + "input": request.json + } + + response = { + "statusCode": 200, + "body": json.dumps(body) + } + + return response +``` + +You can add as many functions as you want within this property. + +```yml +# serverless.yml +service: my-service + +provider: + name: kubeless + runtime: python2.7 + +plugins: + - serverless-kubeless + +functions: + hello_one: + handler: handler.hello_one + hello_two: + handler: handler.hello_two +``` + +## Runtimes + +The Kubeless provider plugin supports the following runtimes. + +- Node.js +- Python +- Ruby + +Please see the following repository for sample projects using those runtimes: + +[https://github.com/serverless/serverless-kubeless/tree/master/examples](https://github.com/serverless/serverless-kubeless/tree/master/examples) diff --git a/docs/providers/kubeless/guide/installation.md b/docs/providers/kubeless/guide/installation.md new file mode 100644 index 00000000000..19eed289224 --- /dev/null +++ b/docs/providers/kubeless/guide/installation.md @@ -0,0 +1,109 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/guide/installation) + + +# Kubeless - Installation + +## Installing Kubeless in your Kubernetes cluster + +Kubeless runs on [Kubernetes](https://kubernetes.io), you need a working Kubernetes cluster to run kubeless. For testing you can use [minikube](https://github.com/kubernetes/minikube). + +You should deploy Kubeless in your cluster using one of YAML manifests found in the release package. It will create a *kubeless* Namespace and a *function* ThirdPartyResource. You will see a *kubeless* Controller, and *kafka*, *zookeeper* StatefulSet running. + +There are several kubeless manifests being shipped for multiple k8s environments (non-rbac and rbac), please consider to pick up the correct one: + +* *kubeless-$RELEASE.yaml* is used for non-RBAC Kubernetes cluster. +* *kubeless-rbac-$RELEASE.yaml* is used for RBAC-enabled Kubernetes cluster. + +For example, this below is a show case of deploying kubeless to a non-RBAC Kubernetes cluster. + + $ export RELEASE=0.0.20 + $ kubectl create ns kubeless + $ kubectl create -f https://github.com/kubeless/kubeless/releases/download/$RELEASE/kubeless-$RELEASE.yaml + + $ kubectl get pods -n kubeless + NAME READY STATUS RESTARTS AGE + kafka-0 1/1 Running 0 1m + kubeless-controller-3331951411-d60km 1/1 Running 0 1m + zoo-0 1/1 Running 0 1m + + $ kubectl get deployment -n kubeless + NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE + kubeless-controller 1 1 1 1 1m + + $ kubectl get statefulset -n kubeless + NAME DESIRED CURRENT AGE + kafka 1 1 1m + zoo 1 1 1m + + $ kubectl get thirdpartyresource + NAME DESCRIPTION VERSION(S) + function.k8s.io Kubeless: Serverless framework for Kubernetes v1 + + $ kubectl get functions + +## Installing the Kubeless CLI (optional) + +You can optionally install the Kubeless CLI tool. + +On Linux, use these commands to install Kubeless CLI in your system: + + $ curl -L https://github.com/kubeless/kubeless/releases/download/0.0.20/kubeless_linux-amd64.zip > kubeless.zip + $ unzip kubeless.zip + $ sudo cp bundles/kubeless_linux-amd64/kubeless /usr/local/bin/ + +On Mac OS X, use these commands to install Kubeless CLI in your system: + + $ curl -L https://github.com/kubeless/kubeless/releases/download/0.0.20/kubeless_darwin-amd64.zip > kubeless.zip + $ unzip kubeless.zip + $ sudo cp bundles/kubeless_darwin-amd64/kubeless /usr/local/bin/ + +| TIP: For detailed installation instructions, visit the [Kubeless releases page](https://github.com/bitnami/kubeless/releases). + +## Installing Node.js + +Serverless is a [Node.js](https://nodejs.org) CLI tool so the first thing you need to do is to install Node.js on your machine. + +Go to the official [Node.js website](https://nodejs.org), download and follow the [installation instructions](https://nodejs.org/en/download/) to install Node.js on your local machine. + +**Note:** Serverless runs on Node v4 or higher. + +You can verify that Node.js is installed successfully by runnning `node --version` in your terminal. You should see the corresponding Node version number printed out. + +## Installing the Serverless Framework + +Next, install the Serverless Framework via [npm](https://npmjs.org) which was already installed when you installed Node.js. + +Open up a terminal and type `npm install -g serverless` to install Serverless. + +```bash +npm install -g serverless +``` + +Once the installation process is done you can verify that Serverless is installed successfully by running the following command in your terminal: + +```bash +serverless +``` + +To see which version of serverless you have installed run: + +```bash +serverless --version +``` + +## Installing Kubeless Provider Plugin + +Now we need to install the provider plugin to allow the framework to deploy services to the platform. This plugin is also [published](http://npmjs.com/package/serverless-kubeless) on [npm](https://npmjs.org) and can installed using the same `npm install` command. + +``` +npm install -g serverless-kubeless +``` diff --git a/docs/providers/kubeless/guide/intro.md b/docs/providers/kubeless/guide/intro.md new file mode 100644 index 00000000000..52165829269 --- /dev/null +++ b/docs/providers/kubeless/guide/intro.md @@ -0,0 +1,60 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/guide/intro) + + +# Kubeless - Introduction + +The Serverless Framework helps you develop and deploy serverless applications using Kubeless. It's a CLI that offers structure, automation and best practices out-of-the-box, allowing you to focus on building sophisticated, event-driven, serverless architectures, comprised of [Functions](#functions) and [Events](#events). + +The Serverless Framework is different than other application frameworks because: +* It manages your code as well as your infrastructure +* It supports multiple languages (Node.js, Python, Ruby) + +## Core Concepts + +Here are the Serverless Framework's main concepts and how they pertain to Kubeless. + +### Functions + +A Function is an [Kubeless Function](http://kubeless.io/). It's an independent unit of deployment, like a microservice. It's merely code, deployed in the cloud, that is most often written to perform a single job such as: + +* *Saving a user to the database* +* *Processing a file in a database* +* *Performing a scheduled task* (To be added in newer versions) + +You can perform multiple jobs in your code, but we don't recommend doing that without good reason. Separation of concerns is best and the Framework is designed to help you easily develop and deploy Functions, as well as manage lots of them. + +### Events + +Anything that triggers an Kubeless Event to execute is regarded by the Framework as an **Event**. Events are platform events on Kubeless such as: + +* *An API Gateway HTTP endpoint (e.g., for a REST API)* +* *A Kafka queue message (e.g., a message)* +* *A scheduled timer (e.g., run every 5 minutes)* (To be added in newer versions) + +### Services + +A **Service** is the Serverless Framework's unit of organization (not to be confused with [Kubernetes Services](https://kubernetes.io/docs/concepts/services-networking/service/). You can think of it as a project file, though you can have multiple services for a single application. It's where you define your Functions and the Events that trigger them, all in one file entitled `serverless.yml` (or `serverless.json`). It looks like this: + +```yml +# serverless.yml + +service: users + +functions: # Your "Functions" + usersCreate: + handler: hello.hello # The code to call as a response to the event + events: # The "Events" that trigger this function + - http: + path: /hello +``` + +When you deploy with the Framework by running `serverless deploy`, everything in `serverless.yml` is deployed at once. diff --git a/docs/providers/kubeless/guide/quick-start.md b/docs/providers/kubeless/guide/quick-start.md new file mode 100644 index 00000000000..141dc194f7a --- /dev/null +++ b/docs/providers/kubeless/guide/quick-start.md @@ -0,0 +1,73 @@ + + +# Kubeless - Quick Start + +## Pre-requisites + +1. Node.js `v6.5.0` or later. +2. Serverless CLI `v1.20` or later. You can run +`npm install -g serverless` to install it. +3. Install Kubeless & Dependencies(./installation.md). + +## Create a new service + +Create a new service using the Python template, specifying a unique name and an optional path for your service. + +```bash +# Create a new Serverless Service/Project +$ serverless create --template kubeless-python --path new-project +# Change into the newly created directory +$ cd new-project +# Install npm dependencies +$ npm install +``` + +## Deploy, test and diagnose your service + +1. **Deploy the Service** + + Use this when you have made changes to your Functions, Events or Resources in `serverless.yml` or you simply want to deploy all changes within your Service at the same time. + + ```bash + serverless deploy -v + ``` + +2. **Deploy the Function** + + Use this to quickly upload and overwrite your function code, allowing you to develop faster. + + ```bash + serverless deploy function -f hello + ``` + +3. **Invoke the Function** + + Invokes the Function and returns results. + + ```bash + $ serverless invoke --function hello --data '{"Kubeless": "Welcome!"}' -l + # results +{ body: '{"input": {"Kubeless": "Welcome!"}, "message": "Go Serverless v1.0! Your function executed successfully!"}', + statusCode: 200 } + ``` + +4. **Fetch the Function Logs** + + Open up a separate tab in your console and stream all logs for a specific Function using this command. + ```bash + serverless logs -f hello -t + ``` + +## Cleanup + +If at any point, you no longer need your service, you can run the following command to remove the Functions, Events and Resources that were created. + +```bash +serverless remove +``` diff --git a/docs/providers/kubeless/guide/services.md b/docs/providers/kubeless/guide/services.md new file mode 100644 index 00000000000..a34b0d2fe1c --- /dev/null +++ b/docs/providers/kubeless/guide/services.md @@ -0,0 +1,167 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/guide/services) + + +# Kubeless - Services + +A `service` in the Serverless Framework is like a project ((not to be confused with [Kubernetes Services](https://kubernetes.io/docs/concepts/services-networking/service/). It's where you define your Kubeless Functions and the `events` that trigger them, all in a file called `serverless.yml`. + +To get started building your first Serverless Framework project, create a `service`. + +## Organization + +In the beginning of an application, many people use a single Service to define all of the Functions and Events. This is what we recommend in the beginning. + +```bash +myService/ + serverless.yml # Contains all functions and infrastructure resources +``` + +However, as your application grows, you can break it out into multiple services. A lot of people organize their services by workflows or data models, and group the functions related to those workflows and data models together in the service. + +```bash +users/ + serverless.yml # Contains 4 functions that do Users CRUD operations and the Users database +posts/ + serverless.yml # Contains 4 functions that do Posts CRUD operations and the Posts database +comments/ + serverless.yml # Contains 4 functions that do Comments CRUD operations and the Comments database +``` +This makes sense since related functions usually use common infrastructure resources, and you want to keep those functions and resources together as a single unit of deployment, for better organization and separation of concerns. + +## Creation + +To create a service, use the `create` command. You must also pass in a runtime (e.g., node.js, python etc.) you would like to write the service in. You can also pass in a path to create a directory and auto-name your service: + +```bash +# Create service with the Python template in the folder ./new-project +$ serverless create --template kubeless-python --path new-project +``` + +Here are the available runtimes for Kubeless using the Serverless plugin: + +* kubeless-python +* kubeless-nodejs + +Check out the [create command docs](../cli-reference/create) for all the details and options. + +## Contents + +You'll see the following files in your working directory: +- `serverless.yml` +- `handler.py` +- `package.json` + +### serverless.yml + +Each `service` configuration is managed in the `serverless.yml` file. The main responsibilities of this file are: + +- Declare a Serverless service +- Define one or more functions in the service + - Define the provider the service will be deployed to (in our case, kubeless) + - Define any custom plugins to be used (in our case, we will need to use the serverless-kubeless plugin) + - Define events that trigger each function to execute (e.g. HTTP requests) + - Allow events listed in the `events` section to automatically create the resources required for the event upon deployment + - Allow flexible configuration using Serverless Variables + +You can see the name of the service, the provider configuration and the first function inside the `functions` definition which points to the `handler.py` file. Any further service configuration will be done in this file. + +```yml +# serverless.yml +# This is a serverless framework way to group +# several functions. Not to be confused with K8s services +service: new-project +provider: + name: kubeless + runtime: python2.7 + +plugins: + - serverless-kubeless + +functions: + # The top name will be the name of the Function object + # and the K8s service object to get a request to call the function + hello: + # The function to call as a response to the HTTP event + handler: handler.hello +``` + +### handler.py + +The `handler.py` file contains your function code. The function definition in `serverless.yml` will point to this `handler.py` file and the function exported here. + +### package.json + +The `package.json` file is the npm package definition of our functions with all their dependencies, including the kubeless-serverless plugin. + +## Deployment + +When you deploy a Service, all of the Functions and Events in your `serverless.yml` are translated into calls to the Kubernetes cluster API to dynamically define those resources. + +To deploy a service, use the `deploy` command: + +```bash +serverless deploy +``` + +Check out the [deployment guide](https://serverless.com/framework/docs/providers/kubeless/guide/deploying/) to learn more about deployments and how they work. Or, check out the [deploy command docs](../cli-reference/deploy) for all the details and options. + +## Removal + +To easily remove your Service from your Kubernetes cluster, you can use the `remove` command. + +Run `serverless remove -v` to trigger the removal process. As in the deploy step we're also running in the `verbose` mode so you can see all details of the remove process. + +Serverless will start the removal and informs you about it's process on the console. A success message is printed once the whole service is removed. + +The removal process will only remove the service on your Kubernetes cluster. The service directory will still remain on your local machine so you can still modify and (re)deploy it to the same or a new Kubernetes provider. + +## Version Pinning + +The Serverless framework is usually installed globally via `npm install -g serverless`. This way you have the Serverless CLI available for all your services. + +Installing tools globally has the downside that the version can't be pinned inside package.json. This can lead to issues if you upgrade Serverless, but your colleagues or CI system don't. + +### Pinning a Version + +To configure version pinning define a `frameworkVersion` property in your serverless.yml. Whenever you run a Serverless command from the CLI it checks if your current Serverless version is matching the `frameworkVersion` range. The CLI uses [Semantic Versioning](http://semver.org/) so you can pin it to an exact version or provide a range. In general we recommend to pin to an exact version to ensure everybody in your team has the exact same setup and no unexpected problems happen. + +### Examples + +#### Exact Version + +```yml +# serverless.yml +frameworkVersion: "=1.20" + +service: users + +provider: + name: kubeless + runtime: python2.7 +… +``` + +#### Version Range + +```yml +# serverless.yml + +frameworkVersion: ">=1.20 <2.0.0" + +service: users + +provider: + name: kubeless + runtime: python2.7 + +… +``` \ No newline at end of file diff --git a/docs/providers/kubeless/guide/workflow.md b/docs/providers/kubeless/guide/workflow.md new file mode 100644 index 00000000000..8d78f10d89e --- /dev/null +++ b/docs/providers/kubeless/guide/workflow.md @@ -0,0 +1,66 @@ + + + +### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/providers/kubeless/guide/workflow) + + +# Kubeless - Workflow + +Intro. Quick recommendations and tips for various processes. + +### Development Workflow + +1. Write your functions +2. Use `serverless deploy` only when you've made changes to `serverless.yml` and in CI/CD systems. +3. Use `serverless deploy function -f myFunction` to rapidly deploy changes when you are working on a specific Kubeless Function. +4. Use `serverless invoke -f myFunction -l` to test your Kubeless Functions. +5. Open up a separate tab in your console and stream logs in there via `serverless logs -f myFunction -t`. +6. Write tests to run locally. + +### Larger Projects +* Break your application/project into multiple Serverless Services. +* Model your Serverless Services around Data Models or Workflows. +* Keep the Functions and Resources in your Serverless Services to a minimum. + +## Cheat Sheet +A handy list of commands to use when developing with the Serverless Framework. + +##### Create A Service: +Creates a new Service + +``` +serverless create -p [SERVICE NAME] -t kubeless-python +``` +``` +serverless create -p [SERVICE NAME] -t kubeless-nodejs +``` + +##### Deploy All +Use this when you have made changes to your Functions, Events or Resources in `serverless.yml` or you simply want to deploy all changes within your Service at the same time. +``` +serverless deploy +``` + +##### Deploy Function +Use this to quickly overwrite your Kubeless Functinos, allowing you to develop faster. +``` +serverless deploy function -f [FUNCTION NAME] +``` + +##### Invoke Function +Invokes an Kubeless Function and returns logs. +``` +serverless invoke function -f [FUNCTION NAME] -l +``` + +##### Streaming Logs +Open up a separate tab in your console and stream all logs for a specific Function using this command. +``` +serverless logs -f [FUNCTION NAME] +```