Building and Installing from Source

Building and running the Konflux Operator from source for development or custom deployments.

Building from source is intended for contributors to the Operator or anyone who needs to run a custom build. There are two modes:

ModeWhen to use
Run Operator locallyIterative development - Operator runs on your machine, connects to a cluster
Deploy Operator imageTest a containerised build in-cluster

Prerequisites

ToolMinimum version
Gov1.25.0
podman or dockerpodman v5.3.1 / docker v27.0.1 (required only when building an Operator image)
kubectlv1.31.4
make—
opensslv3.0.13
  • cluster-admin permissions
  • A Kubernetes cluster with the following dependencies installed (see Setup):
    • Tekton (or OpenShift Pipelines when using OpenShift)
    • cert-manager
    • trust-manager
    • Kyverno
    • Pipelines-as-Code

Setup

  1. Clone the repository:
git clone https://github.com/konflux-ci/konflux-ci.git
cd konflux-ci
  1. Deploy the cluster dependencies:
# Generic Kubernetes
SKIP_DEX=true SKIP_INTERNAL_REGISTRY=true SKIP_SMEE=true ./deploy-deps.sh

# OpenShift - use native operators instead of upstream ones
USE_OPENSHIFT_PIPELINES=true USE_OPENSHIFT_CERTMANAGER=true \
SKIP_DEX=true SKIP_INTERNAL_REGISTRY=true SKIP_SMEE=true \
./deploy-deps.sh

Alternatively, apply the individual kustomizations under dependencies/ manually.

Run Operator locally

Running the Operator locally is the recommended workflow for most development scenarios. The Operator process runs on your machine and uses your kubectl context to connect to the cluster - no image build required.

Step 1: Install the CRDs

cd operator
make install

Step 2: Start the Operator

make run

The Operator connects to your cluster, watches for Konflux Custom Resources, and reconciles them. Keep this terminal open while you work.

Step 3: Create and verify the Konflux Custom Resource

In a separate terminal, see Applying the Konflux Custom Resource for instructions on creating a Konflux CR and verifying that all components are ready.

Development workflow

  • After making code changes, stop the Operator with Ctrl+C and restart: make run
  • No image rebuild or deployment restart is needed
  • Run make help to see all available targets

Deploy Operator image

Use this approach when you want to run your custom build as an in-cluster deployment (e.g. to test Operator-managed upgrades or RBAC behaviour). There are two paths depending on your setup.

Path 1: Full Kind deployment using the script

If you are working with a local Kind cluster, deploy-local.sh with OPERATOR_INSTALL_METHOD=build handles the entire flow in one step - it builds the Operator image from your local checkout, loads it into Kind, deploys all dependencies, and installs the Operator:

OPERATOR_INSTALL_METHOD=build ./scripts/deploy-local.sh

See Local Deployment (Kind) for setup instructions and all configuration options.

Path 2: Manual deployment on an existing cluster

Use this path when you have an existing cluster that already has Konflux’s dependencies deployed — either manually or using the built-in scripts described in Setup — and you want to deploy only the Operator image.

Step 1: Build and push the image

cd operator
make docker-build docker-push IMG=<your-registry>/konflux-operator:<tag>

Make sure you have push access to the registry and that the cluster can pull from it.

Step 2: Install the CRDs

make install

Step 3: Deploy the Operator

make deploy IMG=<your-registry>/konflux-operator:<tag>

Step 4: Create and verify the Konflux Custom Resource

See Applying the Konflux Custom Resource for instructions on creating a Konflux CR and verifying that all components are ready.

Uninstall

Remove the Konflux CR:

kubectl delete konflux konflux

Remove the CRDs:

make uninstall

Undeploy the Operator (in-cluster mode only):

make undeploy

What’s next