Skip to content

Latest commit

 

History

History
398 lines (280 loc) · 13.5 KB

CONTRIBUTING.md

File metadata and controls

398 lines (280 loc) · 13.5 KB

Contributing to OpenDataHub GitOps Repository

Thank you for your interest in contributing to the OpenDataHub GitOps repository! This document provides guidelines and instructions for contributing to this project.

Table of Contents

Getting Started

Prerequisites

  • Git
  • kubectl or oc CLI
  • Access to an OpenShift cluster (for testing)
  • Kustomize v5 or later

Add a New Kustomize Dependency Operator

When adding a new dependency operator required by OpenDataHub:

Step 1: Create a New Operator Component

Create a new directory under components/operators/ named after your operator:

mkdir -p components/operators/your-operator

Step 2: Create Required Manifests

Create the files required to install the dependency operator in your operator directory, including a kustomization.yaml file.

Note

Do not set the namespace name in the kustomization.yaml file, but set it as a string in the individual resource files where needed.

Step 3: Create Dependency Operator Directory

Create a new directory under dependencies/operators/ named after your operator:

mkdir -p dependencies/operators/your-operator

Add a kustomization.yaml file to the directory, for example:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

components:
  - ../../../components/operators/your-operator/

Add patches if needed.

If your operator depends on other operators, add them to the components list. For an example, see the kueue operator directory.

Step 4: Update Operators Parent Kustomization

Add your operator to dependencies/operators/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

components:
  - ../../../components/operators/cert-manager/
  - ...
  - ../../../components/operators/your-operator/ # Add this line

Step 5: Add Base Configuration for Your Operator

If your operator needs a configuration which depends on CRDs installed by OLM, you can add it to the configurations/your-operator folder.

For an example, see the Kueue configuration directory.

Step 6: Update Configurations Parent Kustomization

Add your operator to configurations/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ...
  - your-operator

Step 7: Update Scripts

Update the maintenance scripts to support your new operator.

Verify Dependencies Script

Add your operator to scripts/verify-dependencies.sh to enable automated verification.

The script performs the following checks:

  • Verifies the operator's Subscription is in the Succeeded phase
  • Confirms the operator's ClusterServiceVersion (CSV) is in the Succeeded phase
  • Optionally validates additional resources managed by the operator

You can extend the verification logic to include custom health checks for resources created by your operator.

Remove Dependencies Script

Only update scripts/remove-dependencies.sh if your operator requires special cleanup steps during uninstallation (e.g., removing CRDs, finalizers, or dependent resources that block deletion).

For most operators, the default cleanup process is sufficient, and no changes are needed.

Step 8: Document the Operator

Add documentation about your operator:

  1. Update README.md with operator information.
  2. Add any special configuration requirements.

Step 9: Test Your Changes

See Testing Your Changes section below.

Contributing to the Helm Chart

The repository includes a Helm chart (chart/) that provides an alternative installation method alongside Kustomize. When adding or modifying dependencies, you should also update the Helm chart.

Adding a New Dependency to the Helm Chart

When adding a new dependency operator, follow these steps:

Step 1: Add Values Configuration

Add your dependency to chart/values.yaml under the dependencies section.

Structure:

  • enabled: Tri-state value - auto (install if needed by a component), true (always install), false (never install)
  • dependencies: Other dependencies this dependency requires (for transitive deps)
  • olm: OLM subscription configuration
  • config (optional): CR spec fields - user can add any fields supported by the CR
dependencies:
  yourOperator:
    # -- Enable your-operator: auto (if needed), true (always), false (never)
    enabled: auto
    # -- Dependencies required by your-operator
    dependencies:
      certManager: true
    olm:
      channel: stable
      name: your-operator
      namespace: your-operator-namespace
      targetNamespaces: [] # optional, for OperatorGroups with specific target namespaces
    config: # optional
      # -- YourOperator CR spec (user can add any fields supported by the CR)
      spec:
        managementState: Managed

Step 2: Create Dependency Templates

Create a new directory chart/templates/dependencies/your-operator/ with:

operator.yaml - OLM installation:

{{- $dep := .Values.dependencies.yourOperator -}}
{{- $shouldInstall := include "rhoai-dependencies.shouldInstall" (dict "dependencyName" "yourOperator" "dependency" $dep "dependencies" .Values.dependencies "components" .Values.components) -}}
{{- if eq $shouldInstall "true" }}
{{- $installType := include "rhoai-dependencies.installationType" (dict "dependency" $dep "global" .Values.global) -}}
{{- if eq $installType "olm" }}
{{ include "rhoai-dependencies.operator.olm" (dict "name" $dep.olm.name "namespace" $dep.olm.namespace "channel" $dep.olm.channel "root" $) }}
{{- end }}
{{- end }}

config.yaml (optional) - CR configuration:

{{- $dep := .Values.dependencies.yourOperator -}}
{{- $shouldInstall := include "rhoai-dependencies.shouldInstall" (dict "dependencyName" "yourOperator" "dependency" $dep "dependencies" .Values.dependencies "components" .Values.components) -}}
{{- if and (eq $shouldInstall "true") (include "rhoai-dependencies.crdExists" (dict "crdName" "yourresources.your.domain.io" "root" $)) }}
apiVersion: your.domain.io/v1
kind: YourResource
metadata:
  name: cluster
  labels:
    {{- include "rhoai-dependencies.labels" . | nindent 4 }}
{{- with $dep.config.spec }}
spec:
  {{- toYaml . | nindent 2 }}
{{- end }}
{{- end }}

Step 3: Update JSON Schema

Add your dependency to chart/values.schema.json to enable validation.

Step 4: Update Documentation

Run make helm-docs to regenerate chart/api-docs.md.

Adding a New Component to the Helm Chart

Components are high-level features (like kserve, kueue, aipipelines) that configure the DataScienceCluster and auto-enable their required dependencies.

Step 1: Add Component Configuration

Add your component to chart/values.yaml under the components section.

Structure:

  • dependencies: Dependencies required (or optional) your component requires
  • dsc: Configuration that goes into the DataScienceCluster CR
  • defaults (optional): Operator-type-specific defaults for dsc fields (odh or rhoai)
components:
  # -- Your component description
  yourComponent:
    # -- Dependencies required by YourComponent
    dependencies:
      certManager: true
    # -- DSC configuration for YourComponent
    dsc:
      # -- Management state for YourComponent (Managed or Removed)
      managementState: Managed
    # -- Operator-type-specific defaults for dsc fields
    defaults:
      odh:
        someField: odh-value
      rhoai:
        someField: rhoai-value

Step 2: Update DataScienceCluster Template

Add your component to chart/templates/operator/datasciencecluster.yaml:

spec:
  components:
    kserve:
      {{- include "rhoai-dependencies.componentDSCConfig" (dict "component" .Values.components.kserve "root" $) | nindent 6 }}
    yourComponent:
      {{- include "rhoai-dependencies.componentDSCConfig" (dict "component" .Values.components.yourComponent "root" $) | nindent 6 }}

Step 3: Update JSON Schema

Add your component to chart/values.schema.json under the components section.

Step 4: Update Documentation

  1. Update chart/README.md with component information
  2. Run make helm-docs to regenerate chart/api-docs.md

Testing Helm Chart Changes

  1. Lint the chart:

    helm lint ./chart

  2. Update snapshots:

    make chart-snapshots

  3. Test on a cluster:

    make helm-install-verify

Testing Your Changes

Always test your changes before submitting a PR.

Kustomize Validation

  1. Validate Kustomize Build:

Run make validate-all to validate the kustomization files.

  1. Check for YAML Errors:

    kustomize build . | kubectl apply --dry-run=client -f -

  2. Validate Installation on a Real Cluster: Test the operator installation on an actual OpenShift cluster to ensure it works as expected.

Helm Validation

  1. Lint the chart:

    helm lint ./chart

  2. Update snapshots:

    make chart-snapshots

  3. Update documentation:

    make helm-docs

  4. Optional: deploy OpenDataHub Operator Catalog:

    bash ./scripts/install-catalog-source.sh

  5. Test on a cluster:

    make helm-install-verify

    If you want to use the custom catalog from step 4, run:

    make helm-install-verify HELM_EXTRA_ARGS="--set operator.odh.olm.source=opendatahub-catalog-test --set operator.odh.olm.channel=fast"

Pull Requests

Workflow

  1. Fork the Repository: Create your own fork of the repository to work on your changes.
  2. Create a Branch: Create your own branch for the feature or bug fix off of the main branch.
  3. Work on Your Changes: Commit often, and ensure Kustomize builds correctly.
  4. Testing: Make sure to test your changes in a real cluster. See the Testing Your Changes section above.
  5. Open a PR Against main: See the PR guidelines below.

Open a Pull Request

  1. Link to Jira Issue: Include the Jira issue link in your PR description.
  2. Description: Provide a detailed description of the changes and what they fix or implement.
  3. Add Testing Steps: Provide information on how the PR has been tested, and list testing steps for reviewers.
  4. Review Request: Tag the relevant maintainers or team members for a review. We follow the Kubernetes review process.
  5. Resolve Feedback: Be open to feedback and iterate on your changes.

Commit Messages

We follow the Conventional Commits format for writing commit messages. A good commit message should include:

  1. Type: fix, feat, docs, chore, etc. Note: All commits except chore require an associated Jira issue. Please add a link to your Jira issue.
  2. Scope: A short description of the area affected.
  3. Summary: A brief explanation of what the commit does.