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

HOWTO.md

Latest commit

 

History

History
196 lines (142 loc) · 8.41 KB

HOWTO.md

File metadata and controls

196 lines (142 loc) · 8.41 KB
Raw

TriggerMesh CLI How-To Guide

Overview

The TriggerMesh CLI provides a quick and easy way to create and manage serverless functions.

Generating a Serverless Function

tm generate --(python|go|ruby|node) <name> will create a directory with <name> or the name of the runtime environment passed as a flag, and containing two files:

  • handler.(js|rb|py|go) The source file containing the serverless implementation
  • serverless.yaml The serverless manifest file

The serverless.yaml contains the details required to build the serverless functions, and the handler contains the specific code.

The generated handlers are designed for AWS Lambda, but make use of the Triggermesh Knative Lambda Runtime which will allow the handler to run on Knative, however there is no restriction to the types of runtimes that can be used when combined with the serverless.yaml file.

Deploying tm to Deploy a Service

When given a serverless.yaml file, tm can be used to deploy and/or build a serverless function. In addition, tm can be used to delete the function once deployed, and retrieve details from a running function.

The remaining commands will require a configuration file for the TriggerMesh Cloud or a Kubernetes configuration file.

In the target Kubernetes cluster, there may be some additional requirements:

NOTE: An alternate Docker Registry can be used by passing --registry-host with tm, or specifying the registry in the serverless.yaml file. If credentials are 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.

NOTE: If the serverless.yaml file will point to pre-built images, then Tekton will not be required.

The global parameters that can be used:

  • --namespace or -n The kubernetes namespace to perform the action in
  • --registry-host The alternate Docker registry host to use (defaulting to Knative Local Registry)
  • --registry-secret The kubernetes secret in the namespace to use for authenticating against the Docker registry

Other flags to help with debugging or usability:

  • -d Debug mode to enable verbose output
  • --dry Print the Kubernetes manifests instead of applying them directly to the cluster
  • --wait Run the command and wait for the service to become available

Deploying a Function

Deploying a new function or service can be done in one of two ways:

  • serverless.yaml file
  • Git repo, docker image, or source directory to upload

To deploy using the serverless.yaml file, then the command to run would be:

tm deploy [-f path/to/serverless.yaml]

or (assuming the serverless.yaml file is in the same directory as the invocation):

tm deploy

To deploy using the repo, docker, or source variant:

tm depoly service <name> -f [repo|image|source]

Note that repo points to a Git based repository such as https://github.com/triggermesh/tm.git, image is a docker image such as docker.io/hello-world:latest, and source is a path to the handler.

When using repo or source, the --runtime flag is required to reference a Tekton task or a runtime recipe such as the Triggermesh Knative Lambda Runtime or Triggermesh OpenFaaS Runtime to build the function.

Lastly, if using repo, then the --revision <tag> flag can be used to select the branch, tag, or changeset from the repo.

Deleteing a Function

To delete the functions defined with a serverless.yaml file:

tm delete [-f path/to/serverless.yaml]

To delete the service:

tm delete svc_name

Obtaining Details About a Function

Details on the function can be obtained using:

tm get service <svc_name>

Serverless.yaml Configuration

The serverless.yaml file syntax follows a structure similar to the Serverless.com.

A sample serverless.yaml file would look like:

service: go-demo-service
description: Sample knative service
provider:
  name: triggermesh
functions:
  go-function:
    source: main.go
    runtime: https://raw.githubusercontent.com/triggermesh/knative-lambda-runtime/master/go-1.x/runtime.yaml

Top-Level Definition

Name Type Description
service string Name of this collection of services
description string optional Human readable description of the services
provider TriggermeshProvider specific attributes
repository string optional Git or local base of the serverless function repository
functions map[string]function pairs describing serverless functions
include []string List of additional files containing function definitions

Describes the attributes at the 'top' level of the serverless.yaml file.

Provider

The provider will always be triggermesh when using the tm CLI. The other attributes reflect where the service will be deployed, and the global parameters to apply towards the defined functions.

Name Type Description
name string Name of the serverless provider being targeted, and must be triggermesh
pull-policy string
namespace string optional target namespace to deploy the services
runtime string _optional default runtime environment to use to build the services
buildtimeout string optional Max runtime for building the functions before timing out the build process
environment map[string]string optional Global dictionary of environment variables
env-secrets []string optional Global list of secrets that will be exposed as environment variables
annotations map[string]string optional Dictionary of metadata annotations to apply to all services defined in this file
registry string optional deprecated Docker registry server to push the services to when built
registry-secret string optional deprecated secret name for authenticated access to the registry

Function

Define the attributes required for building and running a function.

Name Type Description
handler string optional deprecated Analogous to source
source string optional Source file that provides the function implementation
runtime string file or URL path to a yaml runtime definition on how to build the function as a container
buildargs []string optional Arguments to pass to the runtime definition during the function build process
description string optional Human readable description of the function
labels []string optional Kubernetes labels to apply to the function at runtime
environment map[string]string optional Environment name/value pairs to pass to the serverless function at runtime
env-secrets []string optional List of secrets which get expanded as environment variables during the function runtime
annotations map[string]string optional Dictionary of metadata annotations to apply to the serverless function

At a minimum, one of source or handler is required. If source points to a file, then runtime will be required as well.