Getting started with Konflux

A namespace in a Kubernetes cluster can have sole or shared ownership. As a user, it is the most global resource that is generally available to you. Most of the Kubernetes Custom Resources (CRs) which you interact with are scoped to a single namespace including Components, Applications, Snapshots, and Secrets.

All builds are performed by Tekton PipelineRuns within a namespace and usually driven by PipelineDefinitions committed to git repositories and triggered via Pipelines as Code.

A Component CR describes the properties for an OCI artifact including the git repository where the artifact is from, its latest built commit, initial build configuration parameters (i.e. Containerfile path), and any relationships to other Components. The CR also contains a reference to its single owning Application. Component names must be unique in a namespace, even when components are used in different application.

Pipelines as Code is a project that provides opinionated tooling to define a Tekton-based CI/CD pipeline. It enables the use of a Tekton PipelineDefinition within a git repository and for that pipeline to be triggered upon new commits/PR to the repository. In Konflux, these pipelines are pushed to the git repositories in the .tekton directory.

Upon a new push or pull request (merge request in GitLab) event, the pipeline defined in the repository will be run. This pipeline describes the process to build and test a specific artifact. The build process includes Tekton Tasks like cloning the git repository, prefetching dependencies, building the OCI artifact and source SBOM, and generating the source container. The test process includes Tekton Tasks like running Snyk scans, checking for CVEs with clair-in-ci, and running an antivirus scan on the artifact.

An Application CR owns multiple Components. You can think of it as the closest object in Konflux that models an ongoing supported product version. If for some reason you decide you need to, you can decompose your product version further and model different sub-products each as their own Application.

An Application contains information about all of the Components which they own and the git repositories that they are built from. When a new Component’s build pipeline is complete, a new Snapshot is created by the Integration Service containing the latest git/OCI reference from each of the Component CRs plus the just-produced Component artifact. This will be used as the input to an IntegrationTestScenario.

A Snapshot CR is an immutable set of Component references. It can be created from push or pull request events and it may not necessarily represent the latest built artifacts for all Components. A Snapshot defines a set of Components which are either tested or released together.

An IntegrationTestScenario (ITS) CR is a Tekton Pipeline defining a test which is intended to run against an entire Snapshot. The Integration Service runs all ITSs which are configured for the Snapshot’s Application. A default ITS is automatically created for every new Application to enable all Components to be checked against a specified EnterpriseContractPolicy.

Each ITS can be configured 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. These build requirements are codified in an EnterpriseContractPolicy (ECP) which may also be a CR.

When an ECP is evaluated against a Snapshot, a single result is returned according to the highest violation. If, for example, all Components pass the policy requirements, the contract evaluation will be true. If a single Component in a Snapshot fails the policy, however, the result will be a failure even if all of the rest have clean passes. This behavior can present issues when running the default enterprise contract ITS when an Application contains multiple Components.

You need to create a ReleasePlan (RP) CR mapping an Application you want to release with a desired release action. It defines the process to release future Snapshots of your Application in the managed namespace. It also defines whether or not you have automatic releases enabled, as well as additional data that should be supplied to each release pipeline that runs in the future.

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 needs to pass for any Snapshot before that pipeline can proceed. It also defines important 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 your content should be pushed to (i.e. registry.redhat.io/foo/bar if you are on the foo team releasing the bar image).

Every time you want to release newly built artifacts, you will create a Release CR in your 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 the users' intention to ship the content in the Snapshot by way of the referenced ReleasePlan.

Konflux users operate in namespaces (with sole or shared ownership) which are scoped to individual projects (or project depending on the organization). One project can use multiple namespaces if desired, each with many applications with components. Namespaces should NOT be shared by many projects.

You will create Components and Applications, run the PipelineRuns that are defined in your git repositories, view and iterate on the results of the IntegrationTestScenarios, and create Releases for specific Snapshots.

Artifacts build in your namespace (from git pull/merge request or push events) will be pushed to an OCI registry along with their supporting metadata (including SLSA provenance attestations and SBOMs). Once the artifacts are pushed to the registry, they can be used for any common intended activity including development, testing, deployments, and releasing (i.e. pushing the images elsewhere either with credentials that you own or that someone else owns). The model of building artifacts in Konflux is to create them once and release them to as many places as needed/desired where each release action have a unique ECP gating the actions.

Before anyone can use it, you need to install Konflux. After installing Konflux, you can add users and assign them to a Konflux workspace. We use Konflux workspaces 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: