Skip to content

Deploying functions

Deploying a function normally builds an OCI image when needed, publishes it to your configured registry, and creates or updates a Knative Service on the selected cluster. Build and push can be disabled when using an already published image. A deployed function uses the same routing and access configuration as other Knative Services; publishing an image alone does not deploy it.

Prerequisites

For every Knative Service deployment route on this page:

  • You have installed the CLI. Project/source prerequisites depend on the route below; a local project is not required for every deployment.
  • You have kubectl and a trusted kubeconfig for a cluster with Knative Serving installed, an existing target namespace, and permission to create or update the function's Knative Service. Complete the cluster-selection guard before deployment.
  • The cluster can pull the intended image. Private images do not need to be made public: configure private registry access for the cluster. Publishing credentials on your machine do not automatically grant the cluster pull access.

Choose the additional prerequisites for your route:

  • Build and publish locally (procedure below): create/open an initialized local function project and run commands from its directory containing func.yaml. Meet the selected builder's prerequisites and have write access to the chosen registry. A Docker-compatible daemon is needed for pack/s2i, not for every builder.
  • Use an already published image with local --image: an initialized local project containing func.yaml is still required, but no local builder, Docker daemon, or registry write permission is required. Go directly to Use an image that is already published, after the cluster-selection guard.
  • Build on the cluster: use the separate on-cluster procedure and its infrastructure/authentication prerequisites, not this local procedure. Local-source upload requires an initialized local project; explicit Git-reference --source uses a committed project/configuration in the repository and requires no local copy. Its manifest/deployer/namespace rules differ from the local routes.

The raw Kubernetes alternative has a different resource and verification scope; it is not a Knative Service deployment.

Deployment creates or updates the Service named by the project. Check the project's name and existing resources in the target namespace before deploying; do not use a Service owned by another application. If func.yaml records a different deploy.namespace or deploy.deployer, stop: a namespace change can remove the previous deployment, and v1.24 refuses in-place deployer changes. Migration between namespaces/deployers is outside this task.

Select and check the cluster

func uses the effective kubeconfig and its current context. Running a kubectl or kn check with --context does not select that context for a later func command. Neither --remote=false nor invoke --target=remote selects a cluster.

In every shell used for cluster-facing Functions commands, select a trusted kubeconfig file and set the expected context and namespace. Replace all three example values with your intended environment; use a single kubeconfig file for this procedure, not a merged file list:

export KUBECONFIG=/absolute/path/to/intended-kubeconfig
EXPECTED_CONTEXT=your-intended-context
NAMESPACE=your-namespace

check_func_context() {
  if [ -z "$EXPECTED_CONTEXT" ] || [ -z "$NAMESPACE" ]; then
    printf '%s\n' 'STOP: set the intended context and namespace.' >&2
    return 1
  fi
  if [ ! -f "$KUBECONFIG" ]; then
    printf '%s\n' 'STOP: intended kubeconfig file is missing.' >&2
    return 1
  fi
  actual_context=$(kubectl config current-context) || return 1
  if [ "$actual_context" != "$EXPECTED_CONTEXT" ]; then
    printf '%s\n' 'STOP: kubeconfig current context does not match the intended context.' >&2
    return 1
  fi
}

check_func_context

Stop on failure. Do not deploy or invoke remotely until the effective current context matches the intended cluster. Confirm that the selected file/context belongs to that cluster using information from your operator or provider; see CLI connection guidance. Do not change the user's default kubeconfig to make a check pass.

Keep KUBECONFIG set and use check_func_context && before each cluster-facing func or kn func command, as below. If you open another terminal, repeat this setup there. The guard checks context selection, not resource ownership or authorization.

Procedure

This route builds/publishes locally and explicitly selects the Knative deployer.

The deploy command uses the function project name as the Knative Service name. When the function is built, the project name and the image registry name are used to construct a fully qualified image name for the function.

Replace <registry> with your registry prefix. Complete the Functions cluster-selection guard in this shell first; it defines check_func_context and NAMESPACE. The commands explicitly build locally (--remote=false) and select the Knative deployer, overriding remembered workflow choices. Those flags do not select a cluster.

Deploy the function by running the command inside the project directory:

check_func_context && func deploy --remote=false --deployer=knative \
  --registry <registry> --namespace "$NAMESPACE"

Deploy the function by running the command inside the project directory:

check_func_context && kn func deploy --remote=false --deployer=knative \
  --registry <registry> --namespace "$NAMESPACE"

Note

The raw Kubernetes alternative creates different resources and requires Kubernetes Deployment/Service verification. It is separate from the Knative checks below.

Example deployment output

🙌 Function image built: <registry>/hello:latest
✅ Function deployed in namespace "default" and exposed at URL:
http://hello.default.127.0.0.1.sslip.io

The namespace, URL, and build messages depend on your environment and whether a rebuild was needed. Use the URL reported by your deployment, not this example URL.

Private Registry Authentication

For private registries that require authentication, you can set credentials using environment variables:

  • FUNC_USERNAME: The username for registry authentication
  • FUNC_PASSWORD: The password for registry authentication

These credentials are used for publishing the function image; cluster image-pull access is configured separately. See the deploy options in the upstream command reference for other authentication methods.

Avoid putting passwords in command-line arguments, which may be visible in process listings or shell history. Environment variables also require care; do not include secrets in diagnostic output.

From the same project directory, explicitly invoke the remote instance. Without --target=remote, the CLI prefers a locally running instance, which would not verify this deployment:

check_func_context && func invoke --target=remote

check_func_context && kn func invoke --target=remote

Example response

Received response
POST / HTTP/1.1 hello.default.127.0.0.1.sslip.io
  User-Agent: Go-http-client/1.1
  Content-Length: 25
  Accept-Encoding: gzip
  Content-Type: application/json
  K-Proxy-Request: activator
  X-Request-Id: 9e351834-0542-4f32-9928-3a5d6aece30c
  Forwarded: for=10.244.0.15;proto=http
  X-Forwarded-For: 10.244.0.15, 10.244.0.9
  X-Forwarded-Proto: http
Body:

Headers and response bodies depend on your environment and handler. Confirm your application's expected response, not just that the CLI received a response.

Verify readiness and diagnose failures

Use the namespace reported by deployment and the project name in func.yaml for this read-only check:

FUNCTION_NAME=hello
check_func_context && kubectl --context "$EXPECTED_CONTEXT" get kservice "$FUNCTION_NAME" --namespace "$NAMESPACE"
check_func_context && kubectl --context "$EXPECTED_CONTEXT" describe kservice "$FUNCTION_NAME" --namespace "$NAMESPACE"

Replace hello with your project name. Keep the guarded kubeconfig/context and the namespace you selected for deployment; confirm that it matches the namespace reported by the command. Check the Service's Ready condition and URL, then use the remote invocation check above. Ready is not proof that the handler returns the intended result or that a Broker can deliver events.

  • Build failed: return to the build guide and check builder/toolchain requirements and dependency access.
  • Push failed: check the image destination and your registry write credentials. A local build does not prove a push succeeded.
  • Service not Ready: inspect its conditions, especially image pull and startup failures. Follow Serving application diagnostics or consult the cluster operator rather than repeatedly rebuilding an unchanged handler.
  • Service Ready, invocation failed: check the reported URL, network/DNS access from your machine, and handler logs. Direct invocation does not verify the event-delivery route.

To receive events through a Broker, continue with Subscribe functions to CloudEvents.

Use an image that is already published

If this initialized project's intended image is already in a registry and pullable by the cluster, you can deploy it without local build/push tools or registry write access. In v1.24, local func deploy --image still requires an initialized project; supplying an image alone does not replace func.yaml. The manifest supplies the Service name and configuration, while this route's --namespace selects the destination. Stop on a saved deployment-namespace mismatch as above. Complete the cluster-selection guard in this shell first:

check_func_context && func deploy --remote=false --deployer=knative \
  --image ghcr.io/your-username/hello:tested \
  --build=false --push=false --namespace "$NAMESPACE"

check_func_context && kn func deploy --remote=false --deployer=knative \
  --image ghcr.io/your-username/hello:tested \
  --build=false --push=false --namespace "$NAMESPACE"

Replace the image with your published artifact; NAMESPACE is the intended namespace from the guard setup. This route does not include local source changes. Verify readiness and invoke remotely as above. For an arbitrary application container without a Functions project, use Serving's service deployment guide instead.

Raw Kubernetes alternative

The raw deployer creates a Kubernetes Deployment and Service, not a Knative Service. This alternative requires a Kubernetes cluster and permissions for those resources, but not Knative Serving. Local builder/push requirements still apply when building and publishing; complete the same kubeconfig/current-context guard and check resource ownership before proceeding.

The v1.24 raw deployer defaults to cluster-local exposure; this example explicitly uses --expose=none to avoid a remembered exposure choice. OpenShift Route exposure (--expose=route) has separate platform, DNS, and TLS requirements covered upstream. A returned Service URL is not proof of access from your machine.

From the initialized project directory, replace <registry> with your writable registry prefix:

check_func_context && func deploy --remote=false --registry <registry> \
  --namespace "$NAMESPACE" --deployer raw --expose=none

check_func_context && kn func deploy --remote=false --registry <registry> \
  --namespace "$NAMESPACE" --deployer raw --expose=none

Do not use this page's kservice Ready/Knative URL checks to verify these resources. Inspect the Kubernetes Deployment's rollout/readiness and the Kubernetes Service's endpoints/access path, then test the handler through that path. Consult Kubernetes Deployment verification and the deploy options in the upstream command reference; a raw deployment does not establish Knative routing or autoscaling.

We use analytics and cookies to understand site traffic. Information about your use of our site is shared with Google for that purpose. Learn more.