TypeScript Developer Guide

This guide will walk you through developing a config function using the Typescript SDK.

Setup

System Requirements

Currently supported platforms: amd64 Linux/Mac

Setting Up Your Local Environment

• Install node
  • The SDK requires npm version 6 or higher.
  • If installing node from binaries (i.e. without a package manager), follow these installation instructions.
• Install docker

Your Kubernetes Cluster

For the type generation functionality to work, you need a Kubernetes cluster with the CRD OpenAPI Publishing feature which is beta with Kubernetes 1.15.

Alternatively, you can use an existing NPM package with pre-generated types such as the hello-world package discussed in the Quickstart and skip to implementing the function.

Using a kind Cluster

The easiest way to get developing is to use kind to bring up a cluster running in a local container.

1. Download the kind binary version 0.5.1 or higher

2. Use this config file:

   cat > kind.yaml <<EOF
   kind: Cluster
   apiVersion: kind.sigs.k8s.io/v1alpha3
   kubeadmConfigPatches:
   - |
     apiVersion: kubeadm.k8s.io/v1beta2
     kind: ClusterConfiguration
     metadata:
       name: config
     apiServer:
       extraArgs:
         "feature-gates": "CustomResourcePublishOpenAPI=true"
   nodes:
   - role: control-plane
   EOF
   

   Note the use of the beta feature.

3. Create the cluster:

   kind create cluster --name=kpt-functions --config=kind.yaml --image=kindest/node:v1.15.7
   

Using a GKE Cluster

You can also use a deployed cluster in GKE. The beta k8s feature is available only when using GKE’s --enable-kubernetes-alpha flag, as seen here:

gcloud container clusters create $USER-1-15 --cluster-version=latest --region=us-central1-a --project <PROJECT>
gcloud container clusters get-credentials $USER-1-15 --zone us-central1-a --project <PROJECT>

Working with CRDs

The SDK uses the k8s server to generate the typescript classes. If your function uses a Custom Resource Definition, make sure you apply it to the cluster used for type generation:

kubectl apply -f /path/to/my/crd.yaml

Create the NPM Package

To initialize a new NPM package, first create a package directory:

mkdir my-package
cd my-package

Note: All subsequent commands are run from the my-package/ directory.

Run the interactive initializer:

npm init kpt-functions

Follow the instructions and respond to all prompts.

This process will create the following:

1. package.json: The kpt-functions framework library is the only item declared in dependencies. Everything required to compile and test your config function is declared as devDependencies, including the create-kpt-functions CLI discussed later in the README.
2. src/: Directory containing the source files for all your functions, e.g.:
   • my_func.ts: Implement your function’s interface here.
   • my_func_test.ts: Unit tests for your function.
   • my_func_run.ts: The entry point from which your function is run.
3. src/gen/: Contains Kubernetes core and CRD types generated from the OpenAPI spec published by the cluster you selected.
4. build/: Contains Dockerfile for each function, e.g.:
   • my_func.Dockerfile

Next, install all package dependencies:

npm install

In addition to installation, install compiles your function into the dist/ directory.

You can run your function directly:

node dist/my_func_run.js --help

Currently, it simply passes through the input configuration data. Let’s remedy this.

Implement the Function

You can now start implementing the function using your favorite IDE, e.g. VSCode:

code .

In src/my_func.ts, implement the KptFunc interface from the TS SDK API.

Take a look at these demo functions to better understand how to use the typescript library.

Once you’ve written some code, build the package with:

npm run build

Alternatively, run the following in a separate terminal. It will continuously build your function as you make changes:

npm run watch

To run the tests, use:

npm test

Debug and Test the Function

You may want to run a function developed with one of the config function SDKs using the exec runtime in order to avoid the overhead associated with running a container. To run your function in the exec runtime, you will first need to package your function as an executable.

The below example shows how to run a typescript function using the kpt exec runtime.

Prerequisites

• Install the pkg CLI.

  npm install -g pkg
  

• Install your kpt-functions package module to create your function’s distributable file.

  npm i
  

Steps

1. Use the pkg CLI to create an executable from your function’s distributable file. For a my_fn function built using the typescript SDK, this is dist/my_fn_run.js.

   npx pkg dist/my_fn_run.js
   

2. Pass the path to the appropriate executable for your OS when running kpt using the exec runtime.

   kpt fn run DIR/ --enable-exec --exec-path /path/to/my_fn_run-macos -- a=b
   

Build and push container images

With your working function in-hand, it’s time to package your function into an executable container image.

To build the docker image:

npm run kpt:docker-build

You can now run the function container, e.g.:

docker run gcr.io/kpt-functions-demo/my-func:dev --help

To push the image to your container registry of choice:

npm run kpt:docker-push

You’ll need proper authentication/authorization to push to your registry.

kpt:docker-push pushes to the registry specified in the kpt.docker_repo_base field in package.json. You can manually edit this field at any time.

The default value for the container image tag is dev. This can be overridden using--tag flag:

npm run kpt:docker-build -- --tag=latest
npm run kpt:docker-push -- --tag=latest

Use the SDK CLI

The create-kpt-functions package (installed as devDependencies), provides a CLI for managing the NPM package you created above. The CLI sub-commands can be invoked via npm run. For example, to add a new function to the package:

npm run kpt:function-create

These sub-commands are available:

kpt:docker-create       Generate Dockerfiles for all functions. Overwrite
                        files if they exist.
kpt:docker-build        Build container images for all functions.
kpt:docker-push         Push container images to the registry for all
                        functions.
kpt:function-create     Generate stubs for a new function. Overwrites files
                        if they exist.
kpt:type-create         Generate classes for core and CRD types. Overwrite
                        files if they exist.

Flags are passed to the CLI after the -- separator. For example, to pass a tag when building a container image:

npm run kpt:docker-build -- --tag=latest

Next Steps

• Learn how to run functions.
• Find out how to structure a pipeline of functions from the functions concepts page.
• Take a look at these demo functions to better understand how to use the typescript SDK.