Getting started with Konflux
Adopting new platforms is always challenging. While we aim to make use of industry standard terminology and processes, sometimes we will need to introduce additional concepts. More definitions can be found in the glossary.
Key concepts
Namespace
In Kubernetes, namespaces provide a foundational mechanism for isolating groups of resources within a single cluster. All of the Konflux resources and APIs that you interact with are scoped to namespaces, including your Components, Applications, Snapshots, Secrets and the Tekton PipelineRuns that perform builds, tests, and releases.
Tenant namespace
These are namespaces where artifacts are produced from Tekton Pipelines. These can be accessed by more than one individual 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 which is scoped to your team. One team can span multiple namespaces if needed, each with many applications with components. Namespaces should NOT be shared by many teams.
In your tenant namespace, you will create Components and Applications, run the build PipelineRuns that are defined in your git repositories, view and iterate on the results of your IntegrationTestScenarios, and create Releases to release specific Snapshots according to specific ReleasePlans.
Managed namespace
These are namespaces where a managed environment team manages release pipelines and credentials for your organization.
The primary interaction mode between tenant and managed namespaces is to create a Release in a tenant namespace referencing a specific Snapshot which will trigger a specific release pipeline in the managed namespace. See release documentation for more.
OCI Artifact
OCI is the open containers initiative. It contains an image spec that permits storing artifacts other than container images in container registries, which we call "OCI Artifacts".
Artifacts that you build in your tenant namespace are pushed to an OCI registry along with their supporting metadata (including SLSA provenance attestations and SBOMs).
Custom Resource (CR)
In Kubernetes, a Custom Resources (CR) is an extension of the Kubernetes API.
All Konflux APIs are implemented as Kubernetes CRs. If you’re familiar with common Kubernetes resources such as Pods and Deployments, you’ll find that Konflux resources appear on cluster in the same way: Applications, Components, Snapshots, and PipelineRuns.
A consequence of this fact is that commonplace Kubernetes client tools such as kubectl understand and can work with Konflux APIs.
Component
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, and any relationships to other Components. The CR also contains a reference to its single owning Application. Component names are unique in a namespace, even when components are used in different application.
Build pipeline
When you create a Component in Konflux, a build pipeline is pushed to the git repository in the .tekton/
directory and a webhook is installed.
Upon a new push or pull request (merge request in GitLab) event, the pipeline defined in the repository is run. This pipeline describes the process to build and test a specific artifact. The build process includes Tekton Tasks such as cloning the git repository, prefetching dependencies, building the OCI artifact and source SBOM, and generating the source container. The test process includes Tekton Tasks such as running Snyk scans, checking for CVEs with clair-in-ci, and running an antivirus scan on the artifact.
Konflux inherits the pattern of defining Tekton build pipelines in git from its use of Pipelines as Code (PaC). PaC enables the use of a Tekton PipelineDefinition within a git repository and for that pipeline to be triggered upon new commits and PRs to the repository.
Application
An Application CR owns multiple Components. It helps to logically group Components in the UI.
When a new Component’s build pipeline is complete, a new Snapshot is created by the Integration Service containing the latest git and OCI reference from each of the Component CRs plus the just-produced Component artifact. This is used as the input to an IntegrationTestScenario.
Snapshot
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 have many Snapshots in it. 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.
IntegrationTestScenario
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.
EnterpriseContractPolicy
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).
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 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.
ReleasePlan
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 defines whether or not you have automatic releases enabled and additional data to be supplied to each release pipeline that runs in the future.
ReleasePlanAdmission
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 is pushed to.
Release
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.
| It is possible to configure your ReleasePlan with auto-release. When enabled, the Konflux system will generate your Releases for you whenever your Snapshots pass all of their IntegrationTestScenarios. |
| Future functionality, will allow you to automatically collect dynamic metadata for inclusion in the autogenerated Release CRs. |
Konflux personas
Konflux is a platform that helps teams develop applications. How you use Konflux depends on what role you have on your team. Konflux users generally fall into one of two categories:
-
Platform Engineers (PEs): These are the people whose job isn’t to engineer applications, but to make it possible for others to do so. They usually own the instance of Konflux. They manage that instance and its users.
-
Developers: These are the people who engineer applications for their organization. They are the typical users of Konflux, who productize their software with it.
Depending on your role, read whichever following section applies best to you, to get more information and links to further documentation.
Platform Engineers
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).
Developers
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:
-
Build: as mentioned, to form an application, you build its components as images from a repository. While building, Konflux also runs certain checks against those images and their source repository.
-
Test: bring components together and test them as a whole application.
-
Release: transfer ownership of your application to somewhere outside of Konflux, like a container registry.