Creating applications and components

Onboarding components to Konflux

Konflux supports two methods for creating applications and components.

Before being able to onboard a component to Konflux, you will need to 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 create a secret to enable access to a GitLab repository.

With the UI

Prerequisites:

Enabled build pipelines for your instance of Konflux.
Enabled image controller for your instance of Konflux.

Create initial Application and Component

Procedures

In the Konflux UI, go to the Applications page.
Click the Create application button.
Enter a name for the application
Click the Add a component button.

For Gitlab provider, make sure to create a source control secret before creating the component.
Enter the URL for the git repository.
(Optional) After clicking out of the repository URL, expand the Show advanced Git options.
Enter the branch name to the Git reference dialogue.
Enter the path to the context directory if the build context is contained somewhere other than the repository root.
Enter the path to the Dockerfile within the git repository. This will be the path within the context directory.
(Optional) Change the component name if desired.
(Optional) Click on the Pipeline drop down box and select the desired pipeline to configure your component with.
(Optional) Click on Add secret to add a secret which will be needed for the component build. See creating secrets for more information.
Click Create application.

GitHub and GitLab are supported source control providers. GitLab support requires the configuration of source control secrets.

Create additional Components in an Application

Procedures

In the Konflux UI, go to the Applications page.
Click on the name of the application that you want to add a component to.
Click on Actions and Add component.
Follow the procedure above for specifying the component.
Click Add component.

With the CLI

Prerequisites:

Enabled build pipelines for your instance of Konflux.
kubectl CLI tool
You have completed the steps listed in the Getting started in the CLI page.

Procedures

Create an ApplicationComponent.yaml file locally.

Example ApplicationComponent.yaml object

---
apiVersion: appstudio.redhat.com/v1alpha1
kind: Application (1)
metadata:
  name: <application-name>
  namespace: <namespace>
  annotations:
    application.thumbnail: "1"
spec:
  displayName: <application-name>
---
apiVersion: appstudio.redhat.com/v1alpha1
kind: Component (2)
metadata:
  name: <component-name>
  namespace: <namespace>
  annotations:
    build.appstudio.openshift.io/request: configure-pac
    build.appstudio.openshift.io/pipeline: '{"name":"<name-of-the-pipeline-to-use>","bundle":"latest"}' (3)
spec:
  application: <owning-application-name> (4)
  componentName: <component-name>
  source:
    git:
      url: https://github.com/konflux-ci/testrepo.git (5)
      revision: main (6)
      context: ./ (7)
      dockerfileUrl: Containerfile (8)
  containerImage: <oci-repository-to-push-image-to> (9)
---
apiVersion: appstudio.redhat.com/v1alpha1
kind: ImageRepository (10)
metadata:
  annotations:
    image-controller.appstudio.redhat.com/update-component-image: 'true'
  name: imagerepository-for-<application-name>-<component-name>
  namespace: <namespace>
  labels:
    appstudio.redhat.com/application: <application-name>
    appstudio.redhat.com/component: <component-name>
spec:
  image:
    name: <namespace>/<component-name>
    visibility: public (11)

1	At least one application should be created. Multiple applications can be created by adding additional CR specifications.
2	A component is required to map to a git repository to build.
3	Optional: If used, it should point to a configured pipeline. If not specified, the default configured pipeline will be used.
4	Each component belongs to one application. That application should be defined in the same file if it does not already exist.
5	URL for the source repository. This MUST use the `https://[…]` format for cloning a repository.
6	Optional: Branch to build in the repository. If not specified, the default branch will be used.
7	Optional: The context to build within the git repository. If not specified, the default defined in the configured pipeline will be used.
8	Optional: Path to the Containerfile within the context. If not specified, the default value of "Dockerfile" will be used.
9	Optional: If the image controller is not deployed, this is required. You must create a registry secret that has permissions to push and pull for the specified path. If an ImageRepository is created, this should be omitted.
10	Optional: If the `spec.containerImage` has been defined for the component, this should not be created. If the image controller is not deployed, this custom resource will have no effect.
11	Supported values are "public" and "private".

In your workspace, save the ApplicationComponent.yaml file and add the resource to your cluster by running the following command:
```
$ kubectl apply -f ApplicationComponent.yaml
```
You can create additional components and applications with the same file locally by adding additional custom resource configurations.

Now, you can trigger your application’s first build pipeline. In the git repository for your application, using your preferred text editor, open a pull request against the /.tekton/pull-request.yaml file.

Specifically, replace any existing value for the git-url field with the git URL for your application’s repository. (This is the URL you would use to clone the repository locally; it ends with .git.)

The PipelineRun will run only for submitters who have permission to run PipelineRuns or who receive an /ok-to-test comment from an authorized user.
For further details on PipelineRun permissions, please refer to the PipelinesAsCode documentation.

Once the PR is made, a build pipeline should start. You can track its progress in the Konflux UI or you can see the final status in GitHub after the pipeline completes. If the pipeline is successful, you can merge the PR.

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:

Navigate to the Activity > Pipeline runs tab.
For the component whose SBOM you want to view, select its most recent pipeline run.
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/workspace-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:

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

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'
```

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

Example:

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