Add rolling-updates feature flag and compatibility framework

[everettbu]

Test 4

Summary by CodeRabbit

• New Features

  • Introduced a new "Rolling Updates" feature, now available as a preview option.

• Documentation

  • Updated guides to highlight the need to enable the "rolling-updates" feature for certain operations and commands.
  • Enhanced documentation with new example configurations and clarified exit codes for feature-related failures.

• Bug Fixes

  • Improved error handling and messaging when the "rolling-updates" feature is not enabled.

• Chores

  • Adjusted test setups and build scripts to ensure the "rolling-updates" feature is enabled by default where required.

[coderabbitai]

Walkthrough

A new preview feature flag, ROLLING_UPDATES, was introduced in the codebase and integrated into both the application logic and documentation. Feature checks were added to relevant CLI commands, requiring the flag to be enabled for rolling update operations. Documentation and build scripts were updated to reflect and support this requirement.

Changes

Files/Paths	Change Summary
common/src/main/java/org/keycloak/common/Profile.java	Added ROLLING_UPDATES as a new PREVIEW feature in the Feature enum.
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/AbstractUpdatesCommand.java	Added printFeatureDisabled() method to display an error when the feature is not enabled.
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/UpdateCompatibilityCheck.java quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/UpdateCompatibilityMetadata.java	Added feature flag checks to abort command execution if ROLLING_UPDATES is not enabled.
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/compatibility/CompatibilityResult.java	Changed RECREATE_UPGRADE_EXIT_CODE from 4 to 3; added FEATURE_DISABLED exit code 4 with comments.
docs/guides/operator/advanced-configuration.adoc docs/guides/server/update-compatibility.adoc	Updated documentation to require enabling rolling-updates feature; added caution notes and updated exit code docs.
docs/guides/templates/kc.adoc	Updated macro to include --features=rolling-updates in CLI command examples.
operator/scripts/Dockerfile-custom-image	Added --features=rolling-updates to the build command in the Dockerfile.
operator/src/test/java/org/keycloak/operator/testsuite/integration/UpgradeTest.java	Modified test to enable ROLLING_UPDATES feature in the deployment spec.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI_Command
    participant Profile
    participant System

    User->>CLI_Command: Execute update-compatibility command
    CLI_Command->>Profile: Check if ROLLING_UPDATES feature is enabled
    alt Feature enabled
        CLI_Command->>System: Proceed with compatibility check
        System-->>CLI_Command: Return result
        CLI_Command->>User: Output result and exit
    else Feature disabled
        CLI_Command->>User: Print error (feature not enabled)
        CLI_Command->>System: Exit with FEATURE_DISABLED code (4)
    end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

In the warren of code, a new flag appears,
"Rolling Updates" hops in, allaying old fears.
Docs and commands now check if it’s there,
Or else they’ll complain with a bunny’s stern glare.
So enable the flag—let your updates roll free,
And hop on, dear dev, with glee! 🐇✨

---

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 690b0e4 and 0f91e67.

⛔ Files ignored due to path filters (1)

• quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/UpdateCommandDistTest.java is excluded by !**/dist/**

📒 Files selected for processing (10)

• common/src/main/java/org/keycloak/common/Profile.java (1 hunks)
• docs/guides/operator/advanced-configuration.adoc (2 hunks)
• docs/guides/server/update-compatibility.adoc (2 hunks)
• docs/guides/templates/kc.adoc (1 hunks)
• operator/scripts/Dockerfile-custom-image (1 hunks)
• operator/src/test/java/org/keycloak/operator/testsuite/integration/UpgradeTest.java (3 hunks)
• quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/AbstractUpdatesCommand.java (1 hunks)
• quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/UpdateCompatibilityCheck.java (2 hunks)
• quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/UpdateCompatibilityMetadata.java (2 hunks)
• quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/compatibility/CompatibilityResult.java (1 hunks)

🔇 Additional comments (15)

common/src/main/java/org/keycloak/common/Profile.java (1)

134-136: LGTM! Feature flag addition follows established patterns.

The new ROLLING_UPDATES feature is properly defined as a preview feature with an appropriate label. The implementation follows the existing enum conventions and is correctly positioned in the feature list.

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/compatibility/CompatibilityResult.java (1)

31-35: Well-structured exit code reorganization with clear documentation.

The addition of picocli reference comments and the logical restructuring of exit codes (moving recreate upgrade to 3, adding feature disabled as 4) follows standard conventions and provides clear semantics for different failure scenarios.

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/AbstractUpdatesCommand.java (1)

83-85: Clean helper method for consistent feature disabled messaging.

The new printFeatureDisabled() method provides a standardized way to communicate feature availability issues across CLI commands. The error message is clear and actionable, and the implementation reuses existing error display infrastructure.

docs/guides/templates/kc.adoc (1)

53-53: Smart template update ensures documentation consistency.

Adding the --features=rolling-updates flag to the macro ensures all documentation examples will include the required feature flag, preventing outdated examples and user confusion during the preview phase.

operator/scripts/Dockerfile-custom-image (1)

5-5: Appropriate build-time feature enablement for operator image.

Adding --features=rolling-updates to the build command ensures the custom operator image has the necessary feature enabled, consistent with the operator's need to support rolling updates functionality.

docs/guides/server/update-compatibility.adoc (2)

12-16: Well-placed caution notice for preview feature requirement.

The caution block appropriately warns users about the rolling-updates feature requirement at the beginning of the guide, preventing potential confusion when commands fail.

---

132-134: Clear documentation of new exit code for feature-disabled scenario.

The addition of exit code 4 with a clear description helps users understand why commands fail when the rolling-updates feature is disabled, supporting automation and scripting use cases.

operator/src/test/java/org/keycloak/operator/testsuite/integration/UpgradeTest.java (2)

20-20: Appropriate import updates for feature flag support.

The import changes correctly replace UnsupportedSpec with FeatureSpec and add necessary imports for List and Profile to support the new feature flag functionality.

Also applies to: 31-31, 35-35

---

110-110: Proper feature flag enablement in test setup.

The test correctly enables the ROLLING_UPDATES feature by:

1. Initializing FeatureSpec if null
2. Setting the enabled features list with the proper feature key from Profile.Feature.ROLLING_UPDATES

This ensures the test environment properly exercises the rolling updates functionality.

Also applies to: 112-115

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/UpdateCompatibilityCheck.java (2)

23-23: Correct imports for feature flag support.

The imports for Profile and CompatibilityResult are necessary for the feature flag check and exit code handling respectively.

Also applies to: 25-25

---

46-50: Proper feature flag gating implementation.

The feature flag check is correctly implemented:

1. Early validation prevents unnecessary processing when feature is disabled
2. Uses appropriate helper method printFeatureDisabled() for user feedback
3. Exits with the correct FEATURE_DISABLED exit code as documented
4. Clean early return prevents further execution

docs/guides/operator/advanced-configuration.adoc (2)

446-450: Consistent caution notice across documentation.

The caution block appropriately mirrors the server documentation, ensuring users understand the rolling-updates feature requirement for the Keycloak Operator as well.

---

475-477: Clear YAML example and explanatory notes.

The YAML example properly demonstrates how to enable the rolling-updates feature, and the updated notes clearly distinguish between:

1. Enabling the preview feature (note 1)
2. Setting the update strategy (note 2)

This helps users understand both requirements for rolling updates functionality.

Also applies to: 481-482

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command/UpdateCompatibilityMetadata.java (2)

24-24: Consistent imports for feature flag support.

The imports match those in UpdateCompatibilityCheck, maintaining consistency across the update compatibility commands.

Also applies to: 26-26

---

46-50: Consistent feature flag implementation across commands.

The feature flag check implementation is identical to UpdateCompatibilityCheck, ensuring consistent behavior across both update compatibility commands. This consistency provides a better user experience and easier maintenance.

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature-rolling-updates-implementation

---

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai generate unit tests to generate unit tests for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.