feat: add v1alpha4 API version for Backstage Custom Resource

[Fortune-Ndlovu]

Description

This PR introduces a new API version v1alpha4 for the Backstage custom resource, establishing the foundation for upcoming features while maintaining full backward compatibility with existing versions. Essentially the entention was to:

• Create new v1alpha4 API package copied from v1alpha3
• Update all version identifiers from v1alpha3 to v1alpha4
• Register v1alpha4 in operator scheme
• Regenerate CRD manifests to serve both versions
• Keep v1alpha3 as storage version, v1alpha4 as served only
• Update controller to handle API version
• No functional changes - v1alpha4 behaves identically to v1alpha3

This establishes the foundation for upcoming monitoring feature (RHIDP-5778)
while maintaining backward compatibility with v1alpha3.

Tests: All integration tests and unit tests pass

Which issue(s) does this PR fix or relate to

https://issues.redhat.com/browse/RHIDP-8248

PR acceptance criteria

• Tests
• Documentation

How to test changes / Special notes to the reviewer

Please read my testing procedure within my latest comment here https://issues.redhat.com/browse/RHIDP-8248

Summary by Sourcery

Introduce a new v1alpha4 API version for the Backstage custom resource while preserving full backward compatibility with v1alpha3

New Features:

• Add v1alpha4 API version with autogenerated deepcopy and type definitions for Backstage CRD

Enhancements:

• Serve v1alpha4 in CRD manifests and keep v1alpha3 as the storage version, registering the new version in the operator scheme
• Update operator CSVs, installation manifests, samples, scripts, and scorecards to reference v1alpha4
• Migrate all code and test imports from v1alpha3 to v1alpha4

Documentation:

• Update documentation and example configurations to reflect the v1alpha4 API version

Tests:

• Adjust integration and unit tests to use v1alpha4 imports and extend timeouts for end-to-end scenarios

[sourcery-ai]

Reviewer's Guide

This PR introduces a new v1alpha4 API version for the Backstage custom resource by duplicating the existing v1alpha3 scaffolding, updating all identifiers and imports, registering v1alpha4 with the operator, and regenerating CRDs and OLM manifests. It preserves backward compatibility by keeping v1alpha3 as the storage version and making v1alpha4 served only, with no functional changes to the resource behavior.

Entity relationship diagram for Backstage CRD versions (v1alpha3 and v1alpha4)

erDiagram
    Backstage_v1alpha3 ||--o{ BackstageStatus_v1alpha3 : has
    Backstage_v1alpha4 ||--o{ BackstageStatus_v1alpha4 : has
    Backstage_v1alpha3 {
        string apiVersion
        string kind
        object metadata
        BackstageSpec_v1alpha3 spec
        BackstageStatus_v1alpha3 status
    }
    Backstage_v1alpha4 {
        string apiVersion
        string kind
        object metadata
        BackstageSpec_v1alpha4 spec
        BackstageStatus_v1alpha4 status
    }
    BackstageSpec_v1alpha3 {
        Application application
        Database database
        BackstageDeployment deployment
        RuntimeConfig rawRuntimeConfig
    }
    BackstageSpec_v1alpha4 {
        Application application
        Database database
        BackstageDeployment deployment
        RuntimeConfig rawRuntimeConfig
    }
    BackstageStatus_v1alpha3 {
        Condition[] conditions
    }
    BackstageStatus_v1alpha4 {
        Condition[] conditions
    }
    Application {
        AppConfig appConfig
        string dynamicPluginsConfigMapName
        ExtraEnvs extraEnvs
        ExtraFiles extraFiles
        string image
        string[] imagePullSecrets
        int replicas
        Route route
    }
    Database {
        string authSecretName
        bool enableLocalDb
    }
    BackstageDeployment {
        object patch
    }
    RuntimeConfig {
        string backstageConfig
        string localDbConfig
    }
    Condition {
        string lastTransitionTime
        string message
        int observedGeneration
        string reason
        string status
        string type
    }

Loading

Class diagram for new Backstage v1alpha4 API types

classDiagram
    class Backstage {
        +TypeMeta
        +ObjectMeta
        +BackstageSpec Spec
        +BackstageStatus Status
    }
    class BackstageSpec {
        +Application Application
        +Database Database
        +BackstageDeployment Deployment
        +RuntimeConfig RawRuntimeConfig
    }
    class Application {
        +AppConfig AppConfig
        +string DynamicPluginsConfigMapName
        +ExtraEnvs ExtraEnvs
        +ExtraFiles ExtraFiles
        +string Image
        +string[] ImagePullSecrets
        +int32 Replicas
        +Route Route
    }
    class AppConfig {
        +FileObjectRef[] ConfigMaps
        +string MountPath
    }
    class ExtraEnvs {
        +EnvObjectRef[] ConfigMaps
        +EnvObjectRef[] Secrets
        +Env[] Envs
    }
    class ExtraFiles {
        +FileObjectRef[] ConfigMaps
        +FileObjectRef[] Secrets
        +PvcRef[] Pvcs
        +string MountPath
    }
    class Database {
        +string AuthSecretName
        +bool EnableLocalDb
    }
    class BackstageDeployment {
        +object Patch
    }
    class RuntimeConfig {
        +string BackstageConfig
        +string LocalDbConfig
    }
    class Route {
        +bool Enabled
        +string Host
        +string Subdomain
        +TLS TLS
    }
    class TLS {
        +string CaCertificate
        +string Certificate
        +string ExternalCertificateSecretName
        +string Key
    }
    class BackstageStatus {
        +Condition[] Conditions
    }
    class Condition {
        +string LastTransitionTime
        +string Message
        +int64 ObservedGeneration
        +string Reason
        +string Status
        +string Type
    }
    Backstage --> BackstageSpec
    Backstage --> BackstageStatus
    BackstageSpec --> Application
    BackstageSpec --> Database
    BackstageSpec --> BackstageDeployment
    BackstageSpec --> RuntimeConfig
    Application --> AppConfig
    Application --> ExtraEnvs
    Application --> ExtraFiles
    Application --> Route
    AppConfig --> FileObjectRef
    ExtraEnvs --> EnvObjectRef
    ExtraEnvs --> Env
    ExtraFiles --> FileObjectRef
    ExtraFiles --> PvcRef
    Route --> TLS
    BackstageStatus --> Condition

Loading

File-Level Changes

Change	Details	Files
Add and scaffold v1alpha4 API package	Created deepcopy functions for v1alpha4 types Defined BackstageSpec, Status, and related types under api/v1alpha4 Added groupversion_info for v1alpha4 registration	api/v1alpha4/zz_generated.deepcopy.go api/v1alpha4/backstage_types.go api/v1alpha4/groupversion_info.go
Regenerate CRD bundles to include v1alpha4	Inserted a new served v1alpha4 entry alongside v1alpha3 in all CRD schemas Regenerated bundle and dist install YAMLs under both backstage.io and rhdh namespaces Marked v1alpha3 as storage version and v1alpha4 as served only	bundle/backstage.io/manifests/rhdh.redhat.com_backstages.yaml bundle/rhdh/manifests/rhdh.redhat.com_backstages.yaml config/crd/bases/rhdh.redhat.com_backstages.yaml dist/backstage.io/install.yaml dist/rhdh/install.yaml tests/e2e/testdata/rhdh-operator-1.5.yaml
Register and wire v1alpha4 in operator code	Imported and registered the v1alpha4 scheme in cmd/main.go Updated controllers and watchers to use v1alpha4 API group Refactored pkg/model components and tests to import v1alpha4 instead of v1alpha3	cmd/main.go internal/controller/*.go pkg/model/*.go
Update OLM CSVs and sample manifests to v1alpha4	Bumped CSV version entries from v1alpha3 to v1alpha4 Added v1alpha4 sample Backstage CRs in CSV examples Extended kustomization to include the new v1alpha4 sample	bundle/backstage.io/manifests/backstage-operator.clusterserviceversion.yaml bundle/rhdh/manifests/backstage-operator.clusterserviceversion.yaml config/manifests/*clusterserviceversion.yaml config/samples/_v1alpha3_backstage.yaml config/samples/kustomization.yaml
Revise docs, examples, scorecard and tests for v1alpha4	Replaced apiVersion references in docs/configuration.md and example YAMLs Updated scorecard configuration versions to v1alpha4 Modified integration test imports and extended timeouts where needed	docs/configuration.md .rhdh/scripts/*.sh config/scorecard/kustomization.yaml bundle/*/tests/scorecard/config.yaml examples/*.yaml integration_tests/*.go

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @Fortune-Ndlovu - I've reviewed your changes - here's some feedback:

• Consider automating CRD manifest generation (e.g. via controller-gen/make scripts) instead of manually copying that large schema block across multiple directories to reduce drift and maintenance overhead.
• Verify that the CSV’s replaces/skips settings and owned CRD entries are updated so v1alpha4 properly replaces v1alpha3 and supports a seamless operator upgrade path.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- Consider automating CRD manifest generation (e.g. via controller-gen/make scripts) instead of manually copying that large schema block across multiple directories to reduce drift and maintenance overhead.
- Verify that the CSV’s replaces/skips settings and owned CRD entries are updated so v1alpha4 properly replaces v1alpha3 and supports a seamless operator upgrade path.

## Individual Comments

### Comment 1
<location> `integration_tests/config-refresh_test.go:19` </location>
<code_context>
 	"sigs.k8s.io/controller-runtime/pkg/webhook"

-	bsv1 "github.com/redhat-developer/rhdh-operator/api/v1alpha3"
+	bsv1 "github.com/redhat-developer/rhdh-operator/api/v1alpha4"
 	"github.com/redhat-developer/rhdh-operator/internal/controller"

</code_context>

<issue_to_address>
Integration tests now import v1alpha4, but do not explicitly test v1alpha3/v1alpha4 compatibility.

Please add tests to verify that both v1alpha3 and v1alpha4 resources are accepted by the operator, ensuring backward compatibility since v1alpha3 is still the storage version.

Suggested implementation:

```golang
	bsv1 "github.com/redhat-developer/rhdh-operator/api/v1alpha4"
	bsv1alpha3 "github.com/redhat-developer/rhdh-operator/api/v1alpha3"

```

```golang
			_, _, err = executeRemoteCommand(ctx, ns, podName, backstageContainerName(deploy), "cat /my/secret/sec11")
			g.Expect(err).ShouldNot(HaveOccurred())

			// --- Backward compatibility test for v1alpha3 ---
			By("creating a Backstage resource using v1alpha3 API")
			bsV1Alpha3 := &bsv1alpha3.Backstage{
				ObjectMeta: metav1.ObjectMeta{
					Name:      "test-v1alpha3",
					Namespace: ns,
				},
				Spec: bsv1alpha3.BackstageSpec{
					// Fill in required fields for v1alpha3 spec
				},
			}
			err = k8sClient.Create(ctx, bsV1Alpha3)
			g.Expect(err).ShouldNot(HaveOccurred())

			By("verifying the operator reconciles the v1alpha3 resource")
			Eventually(func() error {
				fetched := &bsv1alpha3.Backstage{}
				return k8sClient.Get(ctx, types.NamespacedName{Name: "test-v1alpha3", Namespace: ns}, fetched)
			}, timeout, interval).Should(Succeed())

			// --- Compatibility test for v1alpha4 ---
			By("creating a Backstage resource using v1alpha4 API")
			bsV1Alpha4 := &bsv1.Backstage{
				ObjectMeta: metav1.ObjectMeta{
					Name:      "test-v1alpha4",
					Namespace: ns,
				},
				Spec: bsv1.BackstageSpec{
					// Fill in required fields for v1alpha4 spec
				},
			}
			err = k8sClient.Create(ctx, bsV1Alpha4)
			g.Expect(err).ShouldNot(HaveOccurred())

			By("verifying the operator reconciles the v1alpha4 resource")
			Eventually(func() error {
				fetched := &bsv1.Backstage{}
				return k8sClient.Get(ctx, types.NamespacedName{Name: "test-v1alpha4", Namespace: ns}, fetched)
			}, timeout, interval).Should(Succeed())

```

- You will need to fill in the required fields for `BackstageSpec` in both v1alpha3 and v1alpha4 resources to match your CRD requirements.
- If the test file uses a test framework like Ginkgo, ensure the new test code is placed within the appropriate test context or `It` block.
- Make sure `metav1` is imported if not already present: `metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"`.
- Adjust variable names and context as needed to fit your test structure.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[github-actions]

⚠️ Files changed in bundle and installer generation!

Those changes to the operator bundle/installer manifests should have been pushed automatically to your PR branch.

NOTE: If the PR checks are stuck after this additional commit, manually close the PR and immediately reopen it to trigger the checks again.

[github-actions]

PR images are available:

1. https://quay.io/rhdh-community/operator:0.8.0-pr-1406-a654811
2. https://quay.io/rhdh-community/operator-bundle:0.8.0-pr-1406-a654811
3. https://quay.io/rhdh-community/operator-catalog:0.8.0-pr-1406-a654811

[github-actions]

⚠️ Files changed in bundle and installer generation!

Those changes to the operator bundle/installer manifests should have been pushed automatically to your PR branch.

NOTE: If the PR checks are stuck after this additional commit, manually close the PR and immediately reopen it to trigger the checks again.

[rm3l]

/lgtm

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: gazarenkov, rm3l

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [gazarenkov,rm3l]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

PR images are available:

1. https://quay.io/rhdh-community/operator:0.8.0-pr-1406-99a34e6
2. https://quay.io/rhdh-community/operator-bundle:0.8.0-pr-1406-99a34e6
3. https://quay.io/rhdh-community/operator-catalog:0.8.0-pr-1406-99a34e6