feat(rbg): support role-level metadata

[Syspretor]

Ⅰ. Motivation

Support configuring Role-level labels/annotations; these settings will be propagated to the labels/annotations of workloads created from the Role definition.

Ⅱ. Modifications

Introducing new API Fields under rbg.spec.role

// RoleSpec defines the specification for a role in the group
type RoleSpec struct {
	// Unique identifier for the role
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`

	// Map of string keys and values that can be used to organize and categorize
	// (scope and select) objects. May match selectors of replication controllers
	// and services.
	// More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
	// +optional
	Labels map[string]string `json:"labels,omitempty"`

	// Annotations is an unstructured key value map stored with a resource that may be
	// set by external tools to store and retrieve arbitrary metadata. They are not
	// queryable and should be preserved when modifying objects.
	// More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
	// +optional
	Annotations map[string]string `json:"annotations,omitempty"`

	// ......
}

Ⅲ. Does this pull request fix one issue?

fixes #XXXX

Ⅳ. List the added test cases (unit test/integration test) if any, please explain if no tests are needed.

Ⅴ. Describe how to verify it

1. create RBG with the following yaml contains a custom label declaration of a role:

apiVersion: workloads.x-k8s.io/v1alpha1
kind: RoleBasedGroup
metadata:
  name: demo
spec:
  roles:
  - name: engine
    labels:
      custom-label-key:"custome-label-value"
    replicas: 10
    template:
      spec:
        containers:
        - name: main
          image: nginx:latest

2. check the custom label of Statefulset created by RBG

# kubectl get sts demo-engine -o jsonpath="{.metadata.labels['custom-label-key']}{'\n'}"
custome-label-value

VI. Special notes for reviews

Checklist

• Format your code make fmt.
• Add unit tests or integration tests.
• Update the documentation related to the change.

[gemini-code-assist]

Summary of Changes

Hello @Syspretor, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant feature that allows for the specification of custom labels and annotations directly within the RoleSpec of RoleBasedGroup and RoleBasedGroupSet resources. This enhancement provides greater flexibility for users to organize and manage their Kubernetes workloads by propagating these role-level metadata to the underlying Deployments, LeaderWorkerSets, and StatefulSets. The changes involve updating API definitions, generating deepcopy and apply configuration code, modifying CRDs, and adjusting reconciler logic to correctly merge and apply the new metadata, all backed by new unit tests.

Highlights

• Role-Level Metadata Support: Introduced a new RoleMetadata struct within RoleSpec to allow users to define custom labels and annotations directly at the role level for RoleBasedGroup and RoleBasedGroupSet resources.
• Metadata Propagation to Workloads: The controller logic for Deployments, LeaderWorkerSets, and StatefulSets has been updated to merge these new role-level labels and annotations with existing workload-specific metadata, ensuring user-defined metadata is applied to the generated Kubernetes resources.
• API and CRD Updates: Corresponding updates were made to the Custom Resource Definitions (CRDs) and generated client-go apply configurations to properly support the new RoleMetadata field and its integration into RoleSpec.
• Comprehensive Unit Testing: New unit tests were added for DeploymentReconciler, LeaderWorkerSetReconciler, and StatefulSetReconciler to verify the correct merging and application of role-level labels and annotations, including handling of potential conflicts.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces support for role-level metadata (labels and annotations) in RoleBasedGroup resources. The changes are well-structured, touching the API types, generated client code, CRD definitions, and reconcilers. The reconcilers for Deployment, LeaderWorkerSet, and StatefulSet are correctly updated to merge the new role-level metadata with system-generated metadata. New tests have been added to cover this new functionality, which is great. I have a few suggestions to improve the CRD documentation and strengthen the new tests.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cheyang]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a valuable feature by adding support for role-level labels and annotations, which will be propagated to the workloads. The implementation is mostly correct and is accompanied by thorough tests for the new functionality.

However, I've found a couple of critical compilation errors in deploy_reconciler.go and sts_reconciler.go due to a missing maps package import. These need to be fixed.

Additionally, I've identified some medium-severity issues:

• There is significant code duplication across the new test files. I've suggested refactoring this into a shared helper to improve maintainability.
• The CRD and Helm chart YAML files contain truncated URLs in the descriptions for labels, which should be corrected for better documentation.

Once these issues are addressed, the pull request should be in good shape.

[Copilot]

Pull request overview

This PR adds support for role-level labels and annotations in RoleBasedGroup resources. These metadata fields can be configured at the role level and are automatically propagated to the labels and annotations of workloads (StatefulSet, Deployment, LeaderWorkerSet) created from the role definition. The implementation ensures system-generated labels always take precedence over user-provided values.

Key changes:

• Added Labels and Annotations fields to the RoleSpec API type
• Updated all three workload reconcilers to merge role-level metadata with system-generated metadata
• Added comprehensive test coverage for the new functionality

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
api/workloads/v1alpha1/rolebasedgroup_types.go	Added Labels and Annotations fields to RoleSpec with proper documentation
api/workloads/v1alpha1/zz_generated.deepcopy.go	Auto-generated deep copy methods for new map fields
client-go/applyconfiguration/workloads/v1alpha1/rolespec.go	Auto-generated apply configuration helpers for Labels and Annotations
config/crd/bases/workloads.x-k8s.io_rolebasedgroups.yaml	CRD schema updated with Labels and Annotations field definitions
config/crd/bases/workloads.x-k8s.io_rolebasedgroupsets.yaml	CRD schema updated with Labels and Annotations field definitions
deploy/helm/rbgs/crds/workloads.x-k8s.io_rolebasedgroups.yaml	Helm CRD updated with Labels and Annotations field definitions
deploy/helm/rbgs/crds/workloads.x-k8s.io_rolebasedgroupsets.yaml	Helm CRD updated with Labels and Annotations field definitions
pkg/reconciler/sts_reconciler.go	StatefulSet reconciler updated to merge role labels/annotations using labels.Merge
pkg/reconciler/lws_reconciler.go	LeaderWorkerSet reconciler updated to merge role labels/annotations using labels.Merge
pkg/reconciler/deploy_reconciler.go	Deployment reconciler updated to merge role labels/annotations using labels.Merge
pkg/reconciler/sts_reconciler_test.go	Added comprehensive tests for label/annotation merging with priority verification
pkg/reconciler/lws_reconciler_test.go	Added comprehensive tests for label/annotation merging with priority verification
pkg/reconciler/deploy_reconciler_test.go	Added comprehensive tests for label/annotation merging with priority verification

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cheyang]

/lgtm
/approve