Getting started with Konflux

In Kubernetes, namespaces provide a foundational mechanism for isolating groups of resources within a single cluster. Konflux scopes all the resources and APIs you interact with to namespaces, including your components, applications, snapshots, secrets, and the Tekton PipelineRuns that perform builds, tests, and releases.

Tenant namespaces are where Tekton Pipelines produce artifacts that more than one individual can access according to their roles and the permissions defined by those roles. The tenant namespaces can be either for an individual or a team.

In Konflux, you operate in a tenant namespace scoped to your team. One team can span multiple namespaces if needed, each with many applications and components. We recommend that you not share namespaces with many teams.

You will use your tenant namespaces to do the following:

Managed namespaces are where you manage release pipelines and credentials for your organization. The primary interaction between a tenant and managed namespaces involves creating a release in a tenant namespace that references a specific snapshot in the managed namespace. You can then trigger the release pipeline for that snapshot in the managed namespace. See release documentation for more information.

OCI is the open containers initiative. This initiative contains an image spec that permits storing artifacts other than container images in container registries, which we call OCI Artifacts.

Konflux pushes artifacts that you build in your tenant namespace to an OCI registry along with their supporting metadata (including SLSA provenance attestations and SBOMs).

In Kubernetes, a Custom Resource (CR) is an extension of the Kubernetes API.

All Konflux APIs are Kubernetes CRs. If you’re familiar with common Kubernetes resources such as Pods and Deployments, you’ll find that Konflux resources appear on the cluster in the same way:

This setup enables commonplace Kubernetes client tools, such as kubectl, to understand and interact with Konflux APIs.

A Component CR describes the properties of an OCI artifact. These properties include the following:

The CR also contains a reference to the single application that owns it. Component names are unique in a namespace, even when you use the components in different applications.

When you create a component in Konflux, the system pushes a build pipeline to the Git repository in the .tekton directory and installs a webhook.

Upon a new push or pull request (pull requests are referred to as merge requests in GitLab’s terminology), the system runs the pipeline defined in the Git repository. This pipeline describes the process necessary to build and test a specific artifact.

The build process includes Tekton Tasks such as:

The test process includes Tekton Tasks such as:

Konflux inherits the pattern of defining Tekton build pipelines in Git from its use of Pipelines as Code (PaC). PaC enables you to use a Tekton PipelineDefinition within your Git repository, and for the system to trigger that pipeline whenever a team member submits a new commit or pull request to the repository.

An Application CR owns multiple components. It helps to logically group components in the UI.

When a new component’s build pipeline is complete, the Integration Service, which contains the latest Git and OCI references, creates a new snapshot from each of the Component CRs, as well as the just-produced component artifact. The IntegrationTestScenarios use this output to run.

A Snapshot CR is an immutable set of component references. It can be created from push or pull request events. A snapshot defines a set of components, which are either tested or released together.

Over time, as you produce more builds, your tenant namespace will contain many snapshots. Understand that at any point in time, a given snapshot might not necessarily represent the latest built artifacts for all components in your tenant namespace.

An IntegrationTestScenario (ITS) CR is a Tekton Pipeline that defines a test to run against an entire snapshot. The Integration Service runs all configured ITSs for the snapshot’s application. The system also creates a default ITS for every new application to enable EnterpriseContractPolicy checks on all components.

You can configure each ITS as optional for release. All non-optional tests must pass before the new component build is "promoted" to update the references on the component CR.

Building in Konflux follows a "build once, release multiple times" mentality, where each release can have separate requirements on the builds before allowing the action. You codify these build requirements in an EnterpriseContractPolicy (ECP).

When Konflux evaluates an ECP against a snapshot, it returns a single result based on the highest violation. For example, if all components pass the policy requirements, the policy evaluation is true. If a single component in a snapshot fails the policy, however, the overall result is a failure even if all of the rest have clean passes.

A ReleasePlan (RP) CR maps an Application you want to release with a release action. It defines the process to release future Snapshots of your Application in the managed namespace. It also determines whether automatic releases are enabled and whether you want to provide additional data to each future release pipeline.

You also need to create a ReleasePlanAdmission (RPA) CR in the managed namespace. It defines the specific pipeline to run and a given ECP, which must pass for each snapshot before that pipeline can proceed. It also establishes essential details about the delivery of your content that we want to exercise some control over. For example, if your release pipeline uses an apply-mapping task, the .spec.data.mapping.components section of this resource will define which destination repositories to push your content to.

Every time you want to release newly built artifacts, you will create a Release CR in your tenant namespace. The Release CR represents your intent to release some content to customers. It is an active resource that, when present, will initiate the push of content.

A Release CR references a specific Snapshot and ReleasePlan. It indicates your intention to ship the content in the Snapshot by way of the referenced ReleasePlan.

Before anyone can use it, you need to install Konflux. After installing Konflux, you can add users and assign them to a Konflux tenant namespace. We use Konflux tenant namespaces for role-based access control (RBAC).

The purpose of Konflux is to help your applications get out into the world. Be aware that, in Konflux, we specifically define an application as one or more components that run together. And a component is an image built from a source repository.

To access Konflux, your PE needs to give you the URL to your team’s instance and your user credentials. Once you have that access, you can use Konflux to do many different things. But the actions you can take generally fall into 3 key categories: