Skip to content

feat: readme update #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gauron99 merged 1 commit into from
Jul 15, 2025
Merged

feat: readme update #45

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 61 additions & 34 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@
## Quick search

1. [Basic Information](#templates-for-knative-functions)
2. [Prerequisites](#prerequisites) TODO: link to Luke's separate readme
2. [Prerequisites](#prerequisites)
3. [How To Use](#how-to-use)
1. [Build a Function](#build-a-function)
2. [Deploy a Function](#deploy-a-function)
4. [Function Templates Structure](#templates-structure)
6. [Contact](#contact)
7. [F&Q](F&Q)
7. [F&Q](#fq)

## Templates for Knative Functions
This repository showcases some use-cases for your Knative Functions!
Expand All @@ -23,7 +23,7 @@ Templates in this repository include:
- The easiest Hello World (`hello`)
- Simple splash screen with **referenced .css file** and **.funcignore** (`splash`)
- Web blog with **serverside rendering** and **import statements** (`blog`)
- A "Contact Us" function with a **secret password** (`contact-us`)
- upcoming: A "Contact Us" function with a **secret password** (`contact-us`)

See [templates structure](#templates-structure) to learn about repository and
see how to [deploy](#deploy-a-function) your function.
Expand All @@ -32,7 +32,7 @@ see how to [deploy](#deploy-a-function) your function.
In order to use Functions, you will need a few things:

### Download the `func` binary
You can clone our [GitHub repository](https://github.com/knative/func/) and
You can clone our [GitHub repository](https://github.com/knative/func/) and
build your binary from the source or download it straight from the
[release pages](https://github.com/knative/func/releases) under *Assets*.

Expand All @@ -55,14 +55,14 @@ curl -L -o /usr/local/bin/func https://github.com/knative/func/releases/latest/d

#### PowerShell
```powershell
Invoke-WebReqest -Uri "https://github.com/knative/func/releases/latest/download/func_windows_amd64.exe" -OutFile <"C:\path\to\your\destination\func.exe">
Invoke-WebRequest -Uri "https://github.com/knative/func/releases/latest/download/func_windows_amd64.exe" -OutFile <"C:\path\to\your\destination\func.exe">
```
alternatively if `curl` is pre-installed
```powershell
curl -L -o <C:\path\to\your\destination\func.exe> "https://github.com/knative/func/releases/latest/download/func_windows_amd64.exe"
curl -L -o <C:\path\to\your\destination\func.exe> "https://github.com/knative/func/releases/latest/download/func_windows_amd64.exe"
```
*NOTE: You need to change the part in <> to your desired destination*
*(don't include the "<>" symbols)*
> [!NOTE] You need to change the part in <> to your desired destination
> (don't include the "<>" symbols)
### Mac (darwin OS)

#### amd64
Expand All @@ -77,16 +77,16 @@ curl -L -o /usr/local/bin/func "https://github.com/knative/func/releases/latest/
curl -L -o /usr/local/bin/func "https://github.com/knative/func/releases/latest/download/func_darwin_arm64"
```

*NOTE: After downloading on MacOS and Linux, you might need to make the file
executable*
> [!NOTE] After downloading on MacOS and Linux, you might need to make the file
> executable

```sh
chmod +x /usr/local/bin/func
```

### Get a containerization technology
These are some open-source examples of what you can use with Functions. You will
need some tools to atleast build and push your images. This list is not exhaustive.
need some tools to at least build and push your images. This list is not exhaustive.

[Buildah](https://github.com/containers/buildah/blob/main/install.md) - CLI tool
to build your images.
Expand All @@ -95,7 +95,7 @@ to build your images.
to Buildah. Helps you manage and modify your images. Uses Buildah's golang API.
Can be installed independently. (*You can get this as a standalone tool*)

[Docker Engine](https://docs.docker.com/engine/install/) - Helps you build and
[Docker Engine](https://docs.docker.com/engine/install/) - Helps you build and
containerize your applications. (*You can get this as a standalone tool*)

#### Download local cluster runner (kind)
Expand All @@ -108,49 +108,75 @@ In order to interact with the objects in k8s, its recommended to get

## How To Use
You use these templates by creating your function via `--repository` flag which
means "create my function with this template".
means "create my function from this repository".

Create your functions directory and `cd` into it

```
mkdir -p ~/testing/myfunc && cd ~/testing/myfunc
```

- Create a function in **golang** with **hello template** within the new (current and empty) directory
Create a function in **golang** with **hello template** within the new (current and empty) directory

```
func create --repository=https://github.com/gauron99/func-templates --language go --template=hello
```

- TODO add more examples / explanations
Alternatively create the directory with it:

```
func create myfunc --repository=https://github.com/gauron99/func-templates --language go --template=hello
```

where `--language` conveniently matches the runtime and `--template` matches
it's subdirectory containing the Function template, hence:

```
root
├── go
| ├── hello
| | ├── README.md
| | ├── function/
| | ├── tests/
| | └── go.mod
| ├── blog
| | ├── ...
| | ...
├── python
| ├─ ...
| ...
```

see detailed info in [Templates structure](#templates-structure) section.

### Build a Function

#### Using the Host Builder
***NOTE**: Currently, this is under heavy construction and will become the default in the
future.*
> [!NOTE]
> Some languages already have the host builder enabled but not all.
> If available, we recommend using the host builder.

In order to use the Host Builder in the mean time, you will need to enable it via a ENV variable
and specify some flags in `func` via CLI.
In order to use the Host Builder, simply add `--builder=host` to build your
Function. If you want to `func run` your Function locally first, it's also
recommended to use `--container=false`.

Alternativelly, run this in your terminal, or put in your config file (*bashrc etc.*)
```bash
export FUNC_ENABLE_HOST_BUILDER=1
#deploy to a running cluster (this will also build if needed)
func deploy --builder=host
```

Then simply add `--builder=host` to build your Function with the Host builder.
If you want to `func run` your Function locally first, make sure to use `--container=false`

#### Using Alternative Builders
Alternative built-in builders are `pack` and `s2i` (for supported languages).
The way to use them is simple. Just specify which one you want using the
`--builder` flag (eg. `--builder=pack`)
### Deploy a Function
*NOTE: In order to deploy anything to a cluster, you will need to have one set up
and running along with atleast [Knative-Serving](https://knative.dev/docs/serving/) installed.*

### Deploy a Function
> [!NOTE]
> In order to deploy anything to a cluster, you will need to have one set up and
> running along with at least [Knative-Serving](https://knative.dev/docs/serving/) installed.

You can skip the building step entirely and deploy straight after creating your
function. (building is included in the `deploy`).
function. (building is included in the `func deploy`).

#### Local
You can deploy your local code (from your machine) to a cluster using a standard
Expand All @@ -169,7 +195,7 @@ func deploy --image=registry.com/username/myimage@sha256:xxx
```

*NOTE: If you know what you want, at any point you can add a `--build` flag to
your command which will explicitely tell `func` if you want to build (or not)
your command which will explicitly tell `func` if you want to build (or not)
your image. (truthy values will work).*

#### Remote
Expand All @@ -181,9 +207,9 @@ your cluster).
You can simply add `--remote` to your `func deploy` command.

## Templates structure
Directory structure is as follows: **root/[language]/[template]** where *root* is
Directory structure is as follows: **root/[language]/[template]** where *root* is
the github repository itself, *language* is the programming language used and
*template* is the name of the template. Function is created using templates via
*template* is the name of the template. Function is created from Git repo via
`--repository` flag when using `func create` command. More in [How-To-Use](#how-to-use) section.

```
Expand All @@ -192,17 +218,18 @@ github.com/gauron99/func-templates <--[root]
│   ├── hello <-----------------------[template]
│   │ └── <function source files>
│ └── splash-screen
│ └── ...
│ └── ...
├── node
│ ├── hello
│ └── splash-screen
├── ...
```

# Contact
You can contact us on CNCF Slack [knative-functions](https://cloud-native.slack.com/archives/C04LKEZUXEE) channel

### F&Q
1.
## F&Q
1. **Function signature error**
```
Error: function may not implement both the static and instanced method signatures simultaneously
```
Expand Down
Loading