Architecture

May 18, 2026 · View on GitHub

High level overview

Knative Func is a CLI that simplifies building and deploying serverless functions on Kubernetes. Instead of writing Dockerfiles and Kubernetes manifests, developers run func create, func build, and func deploy. The CLI handles image building (via Buildpacks, S2I, or direct OCI), registry pushing, and Knative Service creation or newly available bare K8s deployment.

Code Map

cmd/                    # CLI commands (Cobra) - START HERE
  func/main.go          # Entry point
  build.go, deploy.go   # Individual commands

pkg/
  functions/            # Core library - the "brain"
    client.go           # Central orchestrator, defines all interfaces
    function.go         # Function type representing a project

  buildpacks/           # Pack/Cloud Native Buildpacks builder (in container)
  s2i/                  # Source-to-Image builder (in container)
  oci/                  # Direct OCI image builder (on host)
  builders/             # Builder coordination utilities
  docker/               # Docker client, image pushing

  knative/              # Knative Serving deployer
  deployer/             # Deployment coordination
  k8s/                  # Kubernetes utilities
  operator/             # Knative func-operator integration
  keda/                 # KEDA autoscaler support

  config/               # User/global configuration
  scaffolding/          # Project scaffolding logic
  pipelines/tekton/     # Remote builds via Tekton
  mcp/                  # AI agent integration (MCP server)

templates/              # Function scaffolding (go, node, python, etc.)
generate/               # Embedded filesystem (generated)
schema/                 # JSON schemas

Entry Point

cmd/func/main.go
    └── pkg/app.Main()
        └── cmd.NewRootCmd()
            └── Individual commands (build, deploy, create, ...)

The CLI in cmd/ servers as a terminal frontend and a reference implementation for using pkg/functions. Commands parse flags, create a Client and delegate to pkg/functions/client.go:

// Typical command pattern
client, _ := fn.New(fn.WithBuilder(buildpacks.NewBuilder()))
client.Build(ctx, f)

Key Search Terms

When exploring the codebase, search for these:

Term	Where	What it does
`fn.Client`	`pkg/functions/client.go`	Main client type for all operations
`NewClient`	`cmd/client.go`	Creates fully-configured client
`ClientFactory`	`cmd/root.go`	Function type for client creation
`Builder`	`pkg/functions/client.go`	Interface for function builders
`Deployer`	`pkg/functions/client.go`	Interface for function deployers
`Function`	`pkg/functions/function.go`	Type representing a function

Layer Architecture

flowchart TB
    CLI[CLI Layer<br/>cmd/] --> Client[Client Layer<br/>pkg/functions/]
    Client --> Builders[Builders]
    Client --> Deployers[Deployers<br/>pkg/k8s/, pkg/knative/]
    Client --> Pipelines[Pipelines<br/>pkg/pipelines/]
    Client --> Other[Other Providers]

    Builders --> Buildpack[Buildpacks<br/>pkg/buildpacks/]
    Builders --> S2I[S2I<br/>pkg/s2i/]
    Builders --> OCI[OCI<br/>pkg/oci/]

CLI Layer (`cmd/`)

Cobra commands: build.go, deploy.go, create.go, run.go, delete.go, etc.
Handles flags, user prompts, output formatting
Delegates all business logic to Client

Client Layer (`pkg/functions/`)

client.go: Central orchestrator for all function operations
Defines core interfaces: Builder, Pusher, Deployer, Runner, Remover, Lister, Describer
function.go: Function type representing a function project

Builders

Implement the Builder interface (source → OCI image):

pkg/buildpacks/: Cloud Native Buildpacks via Pack
pkg/s2i/: Red Hat Source-to-Image
pkg/oci/: Direct OCI image building on host

Deployers

pkg/knative/: Creates/updates Knative Services
pkg/k8s/: Kubernetes utilities & Services

Function Lifecycle

flowchart LR
    Create[func create] --> Build[func build]
    Create[func create] --> Deploy[func Deploy]
    Create[func create] --> Run[func Run]
    Deploy --> Invoke[func invoke]
    Run --> Invoke[func invoke]

    Build --> Deploy[func deploy]
    Build --> Run[func run]

    subgraph "Optional"
        Build[func build]
    end

    subgraph "Local Dev"
        Run[func run]
    end

Stage	Client Method	Description
Create	`Init()`	Create boilerplate project from template
Scaffold	`Scaffold()`	Scaffold project as a service
Build	`Build()`	Produce OCI image via Builder
Deploy	`Deploy()`	Push image, create K8s/Knative Service
Run	`Run()`	Local execution for development
Invoke	`Invoke()`	Send request to deployed function

Key Interfaces

Defined in pkg/functions/client.go:

Interface	Purpose
`Builder`	Source → OCI image
`Pusher`	Image → Registry
`Deployer`	Image → Service on K8s
`Runner`	Local execution
`Remover`	Delete deployed function
`Lister`	List deployed functions
`Describer`	Describe function instances
`PipelinesProvider`	Remote build orchestration

Subsystems

Pipelines (Remote Builds)

Located in pkg/pipelines/tekton/. Enables func deploy --remote to build on-cluster via Tekton instead of locally. Supports Pipelines-as-Code (PAC) for GitOps workflows.

MCP Server

Located in pkg/mcp/. Started via func mcp start (Agents should run this). Allows AI agents (Claude Code, Cursor) to create/build/deploy functions programmatically. Read-only by default; set FUNC_ENABLE_MCP_WRITE=true for full access.

Configuration

func.yaml: Function metadata, build/deploy options, environment variables. Schema: schema/func_yaml-schema.json
Templates in templates/ embedded at build time into generate/zz_filesystem_generated.go
Runtimes: go, node, python, rust, quarkus, springboot, typescript
Invocation styles: http, cloudevents

AI

Custom instructions file

Currently the AGENTS.md file is read by many agents by default. The very top of that file defines an optional custom override AGENTS.override.md and instructs agents to read it with highest precedence. You can create that file and add it at root of the repository if you so desire. It won't be source controlled (see .gitignore)