Skip to content
This repository was archived by the owner on May 9, 2023. It is now read-only.

Commit c620c37

Browse files
cab105cab105
committed
Add a how-to guide for additional usage/configuration notes
1 parent 84f1968 commit c620c37

File tree

2 files changed

+200
-0
lines changed

2 files changed

+200
-0
lines changed

‎HOWTO.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# TriggerMesh CLI How-To Guide
2+
3+
- [TriggerMesh CLI How-To Guide](#triggermesh-cli-how-to-guide)
4+
- [Overview](#overview)
5+
- [Generating a Serverless Function](#generating-a-serverless-function)
6+
- [Deploying `tm` to Deploy a Service](#deploying-tm-to-deploy-a-service)
7+
- [Deploying a Function](#deploying-a-function)
8+
- [Deleteing a Function](#deleteing-a-function)
9+
- [Obtaining Details About a Function](#obtaining-details-about-a-function)
10+
- [Serverless.yaml Configuration](#serverlessyaml-configuration)
11+
- [Top-Level Definition](#top-level-definition)
12+
- [Provider](#provider)
13+
- [Function](#function)
14+
15+
## Overview
16+
17+
The [TriggerMesh CLI][tm-cli] provides a quick and easy way to create and manage
18+
serverless functions.
19+
20+
## Generating a Serverless Function
21+
22+
`tm generate --(python|go|ruby|node) <name>` will create a directory with
23+
`<name>` or the name of the runtime environment passed as a flag, and
24+
containing two files:
25+
* `handler.(js|rb|py|go)` The source file containing the serverless implementation
26+
* `serverless.yaml` The [serverless][serverless] manifest file
27+
28+
The [serverless.yaml](#serverlessyaml-configuration) contains the details required
29+
to build the serverless functions, and the handler contains the specific code.
30+
31+
The generated handlers are designed for [AWS Lambda][aws-lambda], but make
32+
use of the [Triggermesh Knative Lambda Runtime][tm-klr] which will allow the
33+
handler to run on Knative, however there is no restriction to the types of
34+
runtimes that can be used when combined with the [serverless.yaml](#serverlessyaml-configuration) file.
35+
36+
## Deploying `tm` to Deploy a Service
37+
38+
When given a `serverless.yaml` file, `tm` can be used to deploy and/or build a
39+
serverless function. In addition, `tm` can be used to delete the function once
40+
deployed, and retrieve details from a running function.
41+
42+
The remaining commands will require a configuration file for the
43+
[TriggerMesh Cloud](https://cloud.triggermesh.io) or a Kubernetes configuration
44+
file.
45+
46+
In the target Kubernetes cluster, there may be some additional requirements:
47+
* [Knative Local Registry][knative-local-registry] to provide a Docker Registry for deploying built services
48+
* [Tekton Pipeline][tekton] for building the containers that will run the service
49+
50+
---
51+
52+
_NOTE_: An alternate Docker Registry can be used by passing `--registry-host` with
53+
`tm`, or specifying the registry in the
54+
[serverless.yaml](#serverlessyaml-configuration) file. If credentials are
55+
required to read or write to the registry, then run `tm set registry-auth <registry-secret-name>` to add the credentials to the cluster and use `--registry-secret` for the `tm deploy` command.
56+
57+
---
58+
59+
_NOTE_: If the [serverless.yaml](#serverlessyaml-configuration) file will point
60+
to pre-built images, then Tekton will not be required.
61+
62+
---
63+
64+
The global parameters that can be used:
65+
* `--namespace` or `-n` The kubernetes namespace to perform the action in
66+
* `--registry-host` The alternate Docker registry host to use (defaulting to [Knative Local Registry][knative-local-registry])
67+
* `--registry-secret` The kubernetes secret in the namespace to use for authenticating against the Docker registry
68+
69+
Other flags to help with debugging or usability:
70+
* `-d` Debug mode to enable verbose output
71+
* `--dry` Print the Kubernetes manifests instead of applying them directly to the cluster
72+
* `--wait` Run the command and wait for the service to become available
73+
74+
### Deploying a Function
75+
76+
Deploying a new function or service can be done in one of two ways:
77+
* `serverless.yaml` file
78+
* Git repo, docker image, or source directory to upload
79+
80+
To deploy using the `serverless.yaml` file, then the command to run would be:
81+
82+
tm deploy [-f path/to/serverless.yaml]
83+
84+
or (assuming the serverless.yaml file is in the same directory as the invocation):
85+
86+
tm deploy
87+
88+
To deploy using the repo, docker, or source variant:
89+
90+
tm depoly service <name> -f [repo|image|source]
91+
92+
Note that `repo` points to a Git based repository such as
93+
`https://github.com/triggermesh/tm.git,` `image` is a docker image such as
94+
`docker.io/hello-world:latest`, and source is a path to the handler.
95+
96+
When using `repo` or `source`, the `--runtime` flag is required to reference a
97+
Tekton task or a runtime recipe such as the
98+
[Triggermesh Knative Lambda Runtime][tm-klr] or [Triggermesh OpenFaaS Runtime][tm-openfaas] to build the function.
99+
100+
Lastly, if using `repo`, then the `--revision <tag>` flag can be used to select
101+
the branch, tag, or changeset from the repo.
102+
103+
### Deleteing a Function
104+
105+
To delete the functions defined with a serverless.yaml file:
106+
107+
tm delete [-f path/to/serverless.yaml]
108+
109+
To delete the service:
110+
111+
tm delete svc_name
112+
113+
114+
### Obtaining Details About a Function
115+
116+
Details on the function can be obtained using:
117+
118+
tm get service <svc_name>
119+
120+
# Serverless.yaml Configuration
121+
122+
The `serverless.yaml` file syntax follows a structure similar to the
123+
[Serverless.com][serverless].
124+
125+
A sample `serverless.yaml` file would look like:
126+
```yaml
127+
service: go-demo-service
128+
description: Sample knative service
129+
provider:
130+
name: triggermesh
131+
functions:
132+
go-function:
133+
source: main.go
134+
runtime: https://raw.githubusercontent.com/triggermesh/knative-lambda-runtime/master/go-1.x/runtime.yaml
135+
```
136+
137+
## Top-Level Definition
138+
139+
| Name | Type | Description |
140+
|---|---|---|
141+
|service|string|Name of this collection of services|
142+
|description|string|_optional_ Human readable description of the services|
143+
|provider|[TriggermeshProvider](#provider)| specific attributes|
144+
|repository|string|_optional_ Git or local base of the serverless function repository|
145+
|functions|map[string][function](#function)| pairs describing serverless functions|
146+
|include|[]string|List of additional files containing function definitions|
147+
148+
Describes the attributes at the 'top' level of the `serverless.yaml` file.
149+
150+
### Provider
151+
152+
The provider will always be `triggermesh` when using the `tm` CLI. The other
153+
attributes reflect where the service will be deployed, and the global parameters
154+
to apply towards the defined functions.
155+
156+
| Name | Type | Description |
157+
|---|---|---|
158+
|name|string|Name of the serverless provider being targeted, and must be `triggermesh`|
159+
|pull-policy|string||_optional_ The container pull policy to apply for after the functions are built|
160+
|namespace|string|_optional_ target namespace to deploy the services|
161+
|runtime|string|_optional default runtime environment to use to build the services|
162+
|buildtimeout|string|_optional_ Max runtime for building the functions before timing out the build process|
163+
|environment|map[string]string|_optional_ Global dictionary of environment variables|
164+
|env-secrets|[]string|_optional_ Global list of secrets that will be exposed as environment variables|
165+
|annotations|map[string]string|_optional_ Dictionary of metadata annotations to apply to all services defined in this file|
166+
|registry|string|_optional_ **deprecated** Docker registry server to push the services to when built|
167+
|registry-secret|string|_optional_ **deprecated** secret name for authenticated access to the registry|
168+
169+
### Function
170+
171+
Define the attributes required for building and running a function.
172+
173+
| Name | Type | Description |
174+
|---|---|---|
175+
|handler|string|_optional_ **deprecated** Analogous to _source_|
176+
|source|string|_optional_ Source file that provides the function implementation|
177+
|runtime|string|file or URL path to a yaml runtime definition on how to build the function as a container|
178+
|buildargs|[]string|_optional_ Arguments to pass to the runtime definition during the function build process|
179+
|description|string|_optional_ Human readable description of the function|
180+
|labels|[]string|_optional_ Kubernetes labels to apply to the function at runtime|
181+
|environment|map[string]string|_optional_ Environment name/value pairs to pass to the serverless function at runtime|
182+
|env-secrets|[]string|_optional_ List of secrets which get expanded as environment variables during the function runtime|
183+
|annotations|map[string]string|_optional_ Dictionary of metadata annotations to apply to the serverless function|
184+
185+
At a minimum, one of `source` or `handler` is required. If `source` points to a
186+
file, then `runtime` will be required as well.
187+
188+
189+
[tm-cli]: https://github.com/triggermesh/tm
190+
[tm-klr]: https://github.com/triggermesh/knative-lambda-runtime
191+
[tm-openfaas]: https://github.com/triggermesh/openfaas-runtime
192+
193+
[knative-local-registry]: https://github.com/triggermesh/knative-local-registry
194+
[serverless]: https://github.com/serverless/serverless/tree/master/docs
195+
[aws-lambda]: https://docs.aws.amazon.com/lambda
196+
[tekton]: https://tekton.dev

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,10 @@ As a result, Knative service image will be pushed to `eu.gcr.io/my-org/my-projec
222222

223223
Besides hosted registries, triggermesh CLI may work with unauthenticated registries which does not require setting access credentials. For such cases, you may simply add `--registry-host` argument to deployment command with registry domain name parameter and resulting image will be pushed to `registry-host/namespace/service_name` URL
224224

225+
### How-To
226+
227+
For additional details on how to use `tm`, consult the [HOWTO Guide](./HOWTO.md)
228+
225229
### Support
226230

227231
We would love your feedback on this CLI tool so don't hesitate to let us know what is wrong and how we could improve it, just file an [issue](https://github.com/triggermesh/tm/issues/new)

0 commit comments

Comments
 (0)