Creating applications and components

Create applications and components using the Konflux UI or kubectl.

Creating an application

An application is a logical grouping of components that are developed and deployed together.

With the UI

Prerequisites:

  • Enabled build pipelines for your instance of Konflux.

  • Enabled image controller for your instance of Konflux.

Procedures

  1. In the Konflux UI, go to the Applications page.

  2. Click the Create application button.

  3. Enter a name for the application.

  4. Click Create application.

With the CLI

Prerequisites:
Procedures

  1. Create an Application.yaml file locally.

    Example Application.yaml object
    apiVersion: appstudio.redhat.com/v1alpha1
kind: Application (1)
metadata:
  name: <application-name>
  namespace: <namespace>
spec:
  displayName: <application-name>
    1 At least one application should be created. Multiple applications can be created by adding additional CR specifications.

  2. Apply the resource to your namespace by running the following command:

    $ kubectl apply -f Application.yaml
    You can create additional applications by adding their custom resource configurations to the Application.yaml file. Separate multiple resources with ---: 
    # Application A
---
# Application B

Creating components

A component is an individual part of an application that contains source code and a build configuration.

Before onboarding a component to Konflux, ensure that the instance has appropriate access to the git repository. This means either installing your organization’s Konflux GitHub App on the source code repository or creating a secret to enable access to a GitLab or Forgejo repository.

Supported source control providers

Konflux supports onboarding components from the following source control providers:

Provider Authentication Method Requirements

GitHub

GitHub App installation

Install the Konflux GitHub App on your organization or repository

GitLab

Source control secret

Create a source control secret before onboarding

Forgejo

Source control secret

Create a source control secret before onboarding
Component names must be unique in a namespace, even when components are used in different applications.
Konflux pushes directly to branches in your onboarded repositories. In order to properly onboard, ensure that no rules prevent pushes to the branch patterns konflux-* and konflux/mintmaker/*.

With the UI

Prerequisites:

  • Enabled build pipelines for your instance of Konflux.

  • Enabled image controller for your instance of Konflux.

  • An existing application in your namespace.

Procedures

  1. In the Konflux UI, go to the Applications page.

  2. Click on the name of the application that you want to add a component to.

  3. Click on Actions and Add component.

    For GitLab and Forgejo providers, create a source control secret before creating the component. See GitLab or Forgejo access token guides.

  4. Enter the URL for the git repository.

  5. (Optional) After clicking out of the repository URL, expand the Show advanced Git options.

  6. Enter the branch name to the Git reference dialogue.

  7. Enter the path to the context directory if the build context is contained somewhere other than the repository root.

  8. Enter the path to the Dockerfile within the git repository. This will be the path within the context directory.

  9. (Optional) Change the component name if desired.

  10. (Optional) Click on the Pipeline drop down box and select the desired pipeline to configure your component with.

  11. (Optional) Click on Add secret to add a secret which will be needed for the component build. See creating secrets for more information.

  12. Click Add component.

    When Component is immediately removed after creation it might result with orphaned ImageRepository which ownership wasn’t yet assigned to the Component and when trying to create Component again with the same name UI will complain with error that ImageRepository already exists, solution is to remove manually ImageRepository from OCP.

With the CLI

Konflux supports onboarding components from multiple source control providers using the CLI. Choose the guide for your provider:

Provider Guide

GitHub

Onboarding a component from GitHub with the CLI

GitLab

Onboarding a component from GitLab with the CLI (requires source control secrets)

Forgejo

Onboarding a component from Forgejo with the CLI (requires source control secrets)

Using different from default image repository

When using ImageRepository object, you will end up with image repository in a default organization, if you want to use your own repository don’t create ImageRepository and follow this section.

Create your own repository in quay.io (or other registry, our example will be for quay.io)

In quay.io web UI, go to your organization and click on Create New Repository, enter repository name and visibility and click on Create Public/Private Repository button. eg. quay.io/test_organization/own-repository

Create robot account in your organization and grant write permission to your repository, you can also create another robot account only with read permissions.

In quay.io web UI, go to your organization, click on Robot Accounts in the left menu, then click on Create Robot Account, enter name of robot account and click on Create robot account button, in the list of repos find your repository and set write permission for it and then click on Add permissions button.

When you click on the newly created robot account on Robot Accounts page, you can get details of the account. In the openened popup for the account first you will see credentials Username and Token (we will use them later), when you click on Kubernetes Secret you can download secret yml file (we will use it later).

Now we will have to create secret with repository credentials.

Creating Secret via Konflux UI

You can now create a secret with the credentials above. Make sure to use the most narrowly valid scope for the registry server address field when adding the secret.

When adding the secret (image registry) with the UI, you will have to choose components to which component specific service accounts build-pipeline-$COMPONENT_NAME secret will be linked to, so that it can be leveraged by builds.

Creating Secret manually

If you aren’t using quay.io registry and have only login & password, you will have to podman login with credentials, and then get docker config json from $XDG_RUNTIME_DIR/containers/auth.json base64 encode it and add to the secret.

Download secret yml for your robot account (from Robot Accounts page described above) and save it as Secret.yaml.

It will look like this:

apiVersion: v1
kind: Secret
metadata:
  name: secret-name
data:
  .dockerconfigjson: <base64-encoded-credentials>
type: kubernetes.io/dockerconfigjson

Edit the file and add metadata.namespace with value of your namespace: <your-tenant>

Encoded credentials from quay.io will be by default for quay.io repository, unless you are using only custom repository for whole namespace, with robot account for all repos and will have only one secret in the namespace for registry, you will have to change the repository in the encoded credentials from quay.io to quay.io/test_organization/own-repository.

To get new <base64-encoded-credentials> follow these steps:

Decode encoded credentials save them to file : echo <base64-encoded-credentials> | base64 -d > auth.json

file will look like

{
  "auths": {
    "quay.io": {
      "auth": "<base64-encoded-auth>",
      "email": ""
    }
  }
}

Edit file and change quay.io to full repository name quay.io/test_organization/own-repository.

Encode credentials again: cat auth.json | base64 -w0 and change <base64-encoded-credentials> to newly generated credentials in Secret.yaml.

And create the secret:

$ kubectl apply -f Secret.yaml

Now we will have to also link the secret to the component specific service account build-pipeline-$COMPONENT_NAME, edit service account either with OCP UI or Cli and to the secrets section of the service account add your newly created secret, service account should look like:

kind: ServiceAccount
apiVersion: v1
metadata:
  name: build-pipeline-$COMPONENT_NAME
  namespace: <your-tenant>
secrets:
  - name: secret-name

Creating component which will be using your own repository

Now that we have create secret with credential to our own repository, we can finally create component using it. Follow examples above about how to create Component via Cli, but now you will have to set spec.containerImage to your own repository quay.io/test_organization/own-repository.

Finding the built images

After a pipeline completes with a built artifact, you may want to test the resulting image to ensure that it works properly. The IMAGE_URL Tekton result (discoverable from the UI or CLI) should be set to the pullspec for the image.

Konflux automatically deletes images built for PR pipelines five days after building them.

With the UI

All build PipelineRuns are visible in the Konflux UI. The location of these images in the OCI registry is reported on the Activity page.

Procedure

In the console, complete the following steps to find the image pullspec for a completed PipelineRun:

  1. Navigate to the Activity > Pipeline runs tab.

  2. For the component whose SBOM you want to view, select its most recent pipeline run.

  3. Find the Results section at the bottom of the page and look for the IMAGE_URL row. It should resemble quay.io/redhat-user-workloads/your-tenant/application/component:tag. You can use the IMAGE_DIGEST provided as an alternate mechanism for referencing the image.

With the CLI

After the build PipelineRuns are completed from git push events, the Components are updated with the location of the artifact in the OCI registry.

Prerequisites

  • Login to Konflux.

  • Install the jq CLI tool.

Procedure

In the CLI, complete the following steps to find the latest pullspec for a component:

  1. List your components.

    $ kubectl get components
    Example output
    NAME                               AGE   STATUS   REASON   TYPE
devfile-sample-go-basic-8wqt       8m54s True     OK       Updated
devfile-sample-python-basic-ikch   20d   True     OK       Updated

  2. Choose which component’s image you want to discover. Then use kubectl get and the jq CLI tool to get the component image path.

    $ kubectl get component <component name> -o json | jq '.status.containerImage'

  3. For convenience, you may want to save the image path to a local variable.

    Example:

    IMAGE=quay.io/redhat-user-workloads/your-tenant/application/component@sha256:<output omitted>