feat: pod port allocator (kep 171) by NoobDream2568 · Pull Request #210 · sgl-project/rbg

NoobDream2568 · 2026-03-16T11:52:05Z

Ⅰ. Motivation

Ⅱ. Modifications

Ⅲ. 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

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 · 2026-03-16T11:52:34Z

Summary of Changes

Hello, 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 crucial new feature for RBG applications: dynamic pod port allocation. It aims to solve the problem of port conflicts when deploying services, especially large language models (LLMs) that often require hostNetwork: true for performance. By automatically assigning unique or shared ports and injecting them into Pods, this change significantly improves deployment density and operational flexibility without manual port management.

Highlights

Dynamic Pod Port Allocation: Introduced a new feature to dynamically allocate service ports for Pods within RBG applications, specifically addressing port conflicts in hostNetwork: true scenarios common in LLM services.
Configurable Port Policies: Implemented support for both 'Dynamic' (per-Pod unique) and 'Static' (shared per-Role) port allocation policies, allowing flexibility in how ports are assigned.
Port Injection and Discovery: Enabled the injection of allocated port values into Pods via container environment variables and Pod annotations, facilitating service discovery and configuration within the application.
Kubernetes ConfigMap Integration: Utilized Kubernetes ConfigMaps to store and manage the state of allocated ports, ensuring persistence and visibility across the cluster.
Controller Lifecycle Management: Integrated port allocation and release logic into the RoleInstance and RoleInstanceSet controllers, ensuring ports are properly managed during Pod creation, updates, and deletion.
New KEP Document: Added a new Kubernetes Enhancement Proposal (KEP-171) detailing the motivation, design, API, and implementation of the Pod Port Allocation feature.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

cmd/rbgs/main.go
- Added import for the new portallocator package.
- Introduced new command-line flags (port-allocate-strategy, start-port, port-range) to configure the port allocator.
- Initialized the global port allocator during controller startup using the provided configuration.
internal/controller/workloads/roleinstanceset_controller.go
- Added imports for time and klog/v2.
- Implemented cleanupInstanceSetPortsOnDeletion function to release all ports and delete the associated ConfigMap when an InstanceSet is deleted.
- Modified the Reconcile method to call cleanupInstanceSetPortsOnDeletion when an InstanceSet is not found (indicating deletion).
keps/171-pod-port-allocation/README.md
- Added a new KEP document outlining the motivation, goals, user stories, design details (API, interface, implementation), and test plan for the Pod Port Allocation feature.
keps/171-pod-port-allocation/kep.yaml
- Added KEP metadata, including title, number, authors, status, and milestones.
pkg/port-allocator/configmap.go
- Added a new file containing utility functions for managing Kubernetes ConfigMaps used to store port allocation state.
- Defined constants for ConfigMap naming conventions and labels.
- Provided functions for creating, getting, updating, deleting, and parsing port data within ConfigMaps.
- Implemented ReleasePortsAndDeleteCM to handle the release of all ports and deletion of a ConfigMap.
pkg/port-allocator/constant.go
- Added a new file defining constants, including the annotation key used for port allocator configurations.
pkg/port-allocator/manager.go
- Added a new file introducing the PortManager struct to encapsulate port allocation logic for an Instance.
- Implemented methods for allocating dynamic and static ports for Pods, handling ConfigMap interactions, and resolving referenced ports.
- Provided functionality to inject allocated ports into Pod specifications as environment variables and annotations.
- Added logic for releasing dynamic ports associated with deleted Pods and syncing port allocations during updates.
pkg/port-allocator/parser.go
- Added a new file with functions to parse port allocator configurations from Pod annotations and PodTemplateSpecs.
- Included validation logic for the parsed configurations and helper methods to categorize allocations (dynamic/static) and parse references.
pkg/port-allocator/parser_test.go
- Added unit tests for the ParsePortAllocatorConfig, GetDynamicAllocations, GetStaticAllocations, ParseReference, FormatPortKey, ParsePortKey, ConfigMapNameGeneration, and HasPortAllocatorConfig functions.
pkg/port-allocator/port_allocator.go
- Added a new file defining the PortAllocatorInterface for different port allocation strategies.
- Implemented a singleton PortAllocator and functions for registering strategies, setting up the allocator, and performing batch allocations and releases.
pkg/port-allocator/port_allocator_test.go
- Added comprehensive unit tests for the core port allocation and management logic, including dynamic/static allocation, release, ConfigMap operations, and PortManager functionality.
pkg/port-allocator/random.go
- Added a new file implementing a RandomAllocator strategy for port allocation, which assigns random ports within a defined range.
pkg/port-allocator/random_test.go
- Added unit tests for the RandomAllocator, verifying port uniqueness, range adherence, and registration.
pkg/port-allocator/type.go
- Added a new file defining the Go types for port allocation configuration, including PortPolicy, PortAllocatorConfig, PortAllocation, and PortReference.
pkg/reconciler/roleinstance/instance_reconciler.go
- Added import for the portallocator package.
- Implemented cleanupInstancePortsOnDeletion to release all ports and delete the associated ConfigMap when an Instance is deleted.
- Modified the Reconcile method to call cleanupInstancePortsOnDeletion when an Instance is not found (indicating deletion).
pkg/reconciler/roleinstance/sync/instance_scale.go
- Added import for the portallocator package.
- Modified createPods to parse port allocator configurations from component templates, initialize a PortManager, allocate ports for new Pods, and inject them into the Pod specifications.
- Modified deletePods to initialize a PortManager and release dynamic ports for Pods being deleted.
pkg/reconciler/roleinstance/sync/instance_update.go
- Added imports for encoding/json and fmt.
- Added import for the portallocator package.
- Modified the Update function to call syncPortAllocationsForUpdate before updating Pods, ensuring port changes are handled.
- Implemented syncPortAllocationsForUpdate to compare old and new port configurations and update ConfigMaps accordingly.
- Added hasPortConfigChanged to detect changes in port allocator configuration, which triggers Pod recreation instead of in-place updates if the configuration changes.

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.

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 a port allocation mechanism for the RBG (RoleBasedGroup) system. It includes changes to the main application, a new controller for managing port allocation, and a KEP (Kubernetes Enhancement Proposal) document detailing the design and implementation. The changes involve adding new flags for configuring the port allocator, integrating the port allocator into the RBG controller, and implementing ConfigMap management for storing port assignments. The code introduces a new port-allocator package with functionalities for allocating, releasing, and managing ports using ConfigMaps. The KEP document provides a comprehensive overview of the motivation, goals, proposal, design details, and test plan for the pod port allocation feature.

cheyang · 2026-03-16T14:06:51Z

@NoobDream2568 Thanks a lot for your contribution.

I think port allocation is not a controller-wide mandatory behavior. It is an object-level opt-in feature: some
RBGs/workloads may enable dynamic port allocation, while others may not use it at all.

Because of that, the reconciler path should stay backend-agnostic and only express the lifecycle semantics. It should not directly encode
ConfigMap-specific cleanup behavior for all objects.

In particular, I think code at this layer should say something like:

  Cleanup()

meaning:

if port allocation is enabled for this object, release its allocation state
if not enabled, just no-op

But it should not directly construct ConfigMap names and call ConfigMap-specific cleanup helpers such as:

  GetInstancePortConfigMapName(... )
  ReleasePortsAndDeleteCM(...)

For an object-level opt-in feature, those backend details should stay inside the port-allocation subsystem.

Copilot

Pull request overview

Implements KEP-171 “Pod Port Allocation” by introducing a port allocator subsystem, wiring it into RoleInstanceSet/RoleInstance reconciliation, and adding unit + e2e coverage to validate port annotation/env injection and reference resolution.

Changes:

Add pkg/port-allocator (config parsing, allocation/injection helpers, random policy, unit tests).
Integrate port allocation into RoleInstanceSet creation (RoleScoped) and RoleInstance/pod creation (PodScoped + env/annotation injection).
Add KEP docs and an e2e testcase for the end-to-end port allocation flow.

Reviewed changes

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

Show a summary per file

File	Description
test/envtest/testutil/setup.go	Register v1alpha2 scheme for tests.
test/e2e/e2e_test.go	Add port allocator test suite to e2e run.
test/e2e/testcase/v1alpha2/port_allocator.go	New e2e validating RoleScoped/PodScoped allocation + injection + reference env.
pkg/reconciler/roleinstanceset_reconciler.go	Allocate RoleScoped ports and store on RoleInstanceSet annotations.
pkg/reconciler/roleinstanceset/statelessmode/core/implement.go	Allocate/copy ports onto new RoleInstances in stateless mode.
pkg/reconciler/roleinstanceset/statefulmode/stateful_instance_set_utils.go	Allocate/copy ports onto new RoleInstances in stateful mode.
pkg/reconciler/roleinstance/sync/instance_scale.go	Inject resolved ports into Pod env/annotations at pod creation time.
pkg/port-allocator/type.go	Define port allocator config types/scopes.
pkg/port-allocator/parser.go	Parse/validate allocator config + reference parsing helpers.
pkg/port-allocator/manager.go	Allocation/injection logic and annotation key formatting.
pkg/port-allocator/port_allocator.go	Global allocator singleton + setup/registration plumbing.
pkg/port-allocator/random.go	“random” allocation policy implementation.
pkg/port-allocator/*_test.go	Unit tests for parsing, allocation, injection, random policy.
keps/171-pod-port-allocation/kep.yaml	KEP metadata for feature tracking.
keps/171-pod-port-allocation/README.md	Detailed design/spec for port allocation feature.
cmd/rbgs/main.go	Add flags and initialize allocator at controller startup.

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

Copilot

Pull request overview

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

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

Syspretor

/lgtm

gemini-code-assist Bot reviewed Mar 16, 2026

View reviewed changes

Comment thread cmd/rbgs/main.go

Comment thread internal/controller/workloads/roleinstanceset_controller.go Outdated

Comment thread keps/171-pod-port-allocation/README.md Outdated

NoobDream2568 force-pushed the port-allocator branch from 28eaf8e to c224b82 Compare March 16, 2026 12:03

cheyang reviewed Mar 16, 2026

View reviewed changes

Comment thread pkg/port-allocator/configmap.go Outdated

cheyang reviewed Mar 16, 2026

View reviewed changes

Comment thread pkg/reconciler/roleinstance/instance_reconciler.go Outdated

NoobDream2568 force-pushed the port-allocator branch from c224b82 to 117f49c Compare March 17, 2026 07:59

cheyang reviewed Mar 18, 2026

View reviewed changes

Comment thread keps/171-pod-port-allocation/README.md Outdated

cheyang reviewed Mar 18, 2026

View reviewed changes

Comment thread pkg/port-allocator/configmap.go Outdated

NoobDream2568 force-pushed the port-allocator branch from 117f49c to ac5de64 Compare March 18, 2026 10:09

diw-zw reviewed Mar 18, 2026

View reviewed changes

Comment thread pkg/port-allocator/manager.go Outdated

diw-zw reviewed Mar 18, 2026

View reviewed changes

Comment thread pkg/port-allocator/manager.go Outdated

NoobDream2568 force-pushed the port-allocator branch 2 times, most recently from e724cf2 to 450f196 Compare March 19, 2026 07:57

cheyang reviewed Mar 19, 2026

View reviewed changes

Comment thread keps/171-pod-port-allocation/README.md Outdated

NoobDream2568 force-pushed the port-allocator branch 2 times, most recently from 616ea6b to ccbe364 Compare March 24, 2026 08:11

cheyang requested a review from Copilot March 24, 2026 11:22

Copilot started reviewing on behalf of cheyang March 24, 2026 11:22 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

NoobDream2568 force-pushed the port-allocator branch from ccbe364 to 871e59b Compare March 24, 2026 11:56

cheyang reviewed Mar 24, 2026

View reviewed changes

Comment thread pkg/port-allocator/random.go

cheyang reviewed Mar 24, 2026

View reviewed changes

Comment thread pkg/port-allocator/parser.go

cheyang reviewed Mar 24, 2026

View reviewed changes

Comment thread pkg/port-allocator/random.go

feat: implement random port allocator

59839e0

NoobDream2568 force-pushed the port-allocator branch from 871e59b to 59839e0 Compare March 25, 2026 08:58

cheyang requested a review from Copilot March 26, 2026 10:24

Copilot started reviewing on behalf of cheyang March 26, 2026 10:24 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

Syspretor approved these changes Mar 27, 2026

View reviewed changes

Syspretor merged commit be21587 into sgl-project:main Mar 27, 2026
13 checks passed

NoobDream2568 deleted the port-allocator branch April 22, 2026 08:13

Conversation

NoobDream2568 commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Ⅰ. Motivation

Ⅱ. Modifications

Ⅲ. Does this pull request fix one issue?

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

Ⅴ. Describe how to verify it

VI. Special notes for reviews

Checklist

Uh oh!

gemini-code-assist Bot commented Mar 16, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cheyang commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Syspretor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

NoobDream2568 commented Mar 16, 2026 •

edited

Loading

cheyang commented Mar 16, 2026 •

edited

Loading