Defining component relationships

When a workspace includes multiple components, their repositories might contain references to image builds of another component. For instance, an application might include multiple child components that, using a Dockerfile FROM clause, reference the image build of a common parent. Or, a component might reference image builds from another application altogether. OpenShift operators, for example, often have references to several components across applications.

In such instances, whenever you build a new image of the common parent component, you need to update the references to it. Specifically, you need to copy and paste the pullspec and image digest of that new image to your other source repositories. This process is tedious and error-prone.

However, if you build an application with Konflux and make references between components with image digests (sha256:…​), Konflux can automatically generate pull requests to update those references. To use this functionality, simply define the relationships between your components, either in the Konflux UI, or in your CLI.

Konflux only updates image digest references. If images use tag references, these will not be updated.

If image digests are pointing to an architecture-specific Image Manifest, nudging will update the digest to a matching architecture. In order for nudging to update to the digest to an Image Index, the current digest needs to be pointing to an Image Index.

By default, Konflux only looks for image digest references in Dockerfiles, Containerfiles, and YAML files. However, you can customize your build pipeline to adjust that list of files with an annotation on the push PipelineRun definition. This annotation supports a comma-separated list of regex or glob patterns. The following annotation would replicate the default behavior.

 
metadata:
  annotations:
    build.appstudio.openshift.io/build-nudge-files: ".*Dockerfile.*, .*.yaml, .*Containerfile.*"

In the UI

Procedure

To define the relationships between components in a workspace, complete the following steps in the Konflux UI:

Currently, applications with only one component do not have the option to define relationships in the UI. To achieve the same result for single-component applications, you can define the relationship in the CLI.

  1. Navigate to your application.

  2. On any tab, use the Actions drop-down menu to select Define component relationships.

    1. Alternatively, go to the Components tab and select the Define component relationships.

  3. In the Component relationships window, select one component from the Select a component drop-down menu.

  4. Select Nudges or Is nudged by, depending on the relationship you wish to define.

    Component A nudges Component B (or Component B is nudged by Component A) if Component B contains a reference, by image digest, to a build of Component A. After successful push builds of Component A, nudging updates the image digest that Component B references.

  5. Use the remaining drop-down menu to choose which other components belong to this relationship.

  6. To define multiple relationships, select Add another component relationship.

  7. Once you have defined all necessary relationships, select Save relationships.

Verification

To verify the new relationship in the UI: . Go to the Components tab for your application. . Select a component that belongs to the relationship you defined. . Scroll to the end of the page and select Show related components.

Alternatively, in the git repo for the component that nudges, push a commit. When the build for that component completes, you should see a new pull request appear for the component that is nudged. This new pull request contains the image digest for the new build of its parent image.

Troubleshooting

  • On any tab, use the Actions drop-down menu to select Define component relationships. If you do not see the relationship, try to define it again and then make sure to select Save relationships.

  • Ensure that the existing references in the repositories of your components are correct.

In the CLI

Prerequisites:

Procedure

  1. In your CLI, login to Konflux.

  2. List your components, and identify the names of the components you want to relate to each other.

    kubectl get components

    Component A nudges Component B (or Component B is nudged by Component A) if Component B contains a reference by image digest to a build of Component A. After successful push builds of Component A, nudging updates the image digest that Component B references.

  3. Patch the components to establish the nudging relationship.

    kubectl patch components/<name of component that nudges> -p '{"spec":{"build-nudges-ref": ["<name of component that is nudged>"]}}' --type=merge --kubeconfig=<path to kubeconfig>

    You can also use kubectl edit to add the build-nudges-ref instead of patching the component.

    1. You found the names of the two components in the last step.

    2. The kubeconfig and its path are the same you used to login to Konflux.

Verification

  • Get the component custom resource (CR) definition for the components that nudges. The definition should include a line that says build-nudges-ref:, and beneath that, the name of the component that is nudged.

    kubectl get components/<name of component that nudges> -o yaml --kubeconfig=<path to kubeconfig> | less

  • Push a commit to the component that nudges. When the build completes, you should see a new pull request appear for the component that is nudged. This new pull request contains the image digest for the new build of the parent image.

Troubleshooting

  • Ensure that the existing references in the repositories of your components are correct.

  • Try running the necessary commands again, and ensure you have the correct syntax.

Customizing nudging PRs

Nudging feature is using renovate https://docs.renovatebot.com/ to actually do the job, for which you can supply your own renovate config, which will be used during nudging. Renovate config has to be specified in ConfigMap in your namespace.

There are two possible options:

  1. Create namespace wide config in ConfigMap named namespace-wide-nudging-renovate-config which will be used for all nudged components in your namespace, unless component specific config exists.

  2. Create config for specific nudged component in ConfigMap named nudging-renovate-config-<component-name> and it will be used for the component in your namespace.

Both ConfigMaps have the same format, can contain config.json or config.js keys, if both specified config.json has precedence. In the value of the key is js or json in the string.

When you have either of ConfigMaps, your config will be used unmodified and it is user’s responsibility to fix it when renovate pipeline will be failing because of it.

Examples

config.json: '{"platform":"gitlab","username":"red-hat-konflux",

config.js: 'module.exports = {platform: "gitlab",\n\t\tusername: "red-hat-konflux",