feat(registration): managed cluster self-registration via OIDC client credentials

components/api-server/openapi/openapi.managedClusters.yaml

@@ -87,6 +87,67 @@ paths:
             application/json:
               schema:
                 $ref: 'openapi.yaml#/components/schemas/Error'
+  /api/hypershell/v1/managed_clusters/registration:
+    post:
+      operationId: registerManagedCluster
+      summary: Self-register a spoke control-plane as a managed cluster
+      description: |
+        Idempotent. Creates a ManagedCluster record on first call; returns the existing
+        cluster_id on subsequent calls from the same OIDC identity. Updates last_seen_at
+        on every call, making this endpoint double as a heartbeat. Requires the
+        managed-cluster-registrar Keycloak realm role.
+      security:
+        - Bearer: []
+      requestBody:
+        description: Registration request
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ManagedClusterRegistrationRequest'
+      responses:
+        '200':
+          description: Already registered; last_seen_at updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ManagedClusterRegistrationResponse'
+        '201':
+          description: Registered for the first time
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ManagedClusterRegistrationResponse'
+        '400':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: 'openapi.yaml#/components/schemas/Error'
+        '401':
+          description: Auth token is invalid
+          content:
+            application/json:
+              schema:
+                $ref: 'openapi.yaml#/components/schemas/Error'
+        '403':
+          description: Missing managed-cluster-registrar role
+          content:
+            application/json:
+              schema:
+                $ref: 'openapi.yaml#/components/schemas/Error'
+        '409':
+          description: Same OIDC subject already registered under a different name
+          content:
+            application/json:
+              schema:
+                $ref: 'openapi.yaml#/components/schemas/Error'
+        '500':
+          description: Unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: 'openapi.yaml#/components/schemas/Error'
   # NEW ENDPOINT START
   /api/hypershell/v1/managed_clusters/{id}:
   # NEW ENDPOINT END
@@ -240,6 +301,34 @@ components:
               type: string
             api_server_url:
               type: string
+            oidc_subject:
+              type: string
+              readOnly: true
+              description: OIDC sub claim of the service account that registered this cluster. Server-assigned; not writable.
+            last_seen_at:
+              type: string
+              format: date-time
+              readOnly: true
+              description: Timestamp of the most recent registration call. Updated on every POST /registration.
+    ManagedClusterRegistrationRequest:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: Human-readable spoke name, unique per fleet (e.g. hyp0-mc1). Must match on every subsequent call.
+        description:
+          type: string
+          description: Optional description of the spoke.
+    ManagedClusterRegistrationResponse:
+      type: object
+      required:
+        - cluster_id
+      properties:
+        cluster_id:
+          type: string
+          description: Stable KSUID assigned to this managed cluster. Use as the cluster filter for WatchGateways.
     # NEW SCHEMA START
     ManagedClusterList:
     # NEW SCHEMA END

components/api-server/openapi/openapi.yaml

@@ -28,6 +28,8 @@ paths:
                 $ref: '#/components/schemas/ObjectReference'
   /api/hypershell/v1/managed_clusters:
     $ref: 'openapi.managedClusters.yaml#/paths/~1api~1hypershell~1v1~1managed_clusters'
+  /api/hypershell/v1/managed_clusters/registration:
+    $ref: 'openapi.managedClusters.yaml#/paths/~1api~1hypershell~1v1~1managed_clusters~1registration'
   /api/hypershell/v1/managed_clusters/{id}:
     $ref: 'openapi.managedClusters.yaml#/paths/~1api~1hypershell~1v1~1managed_clusters~1{id}'
   /api/hypershell/v1/managed_databases:
@@ -112,6 +114,10 @@ components:
       $ref: 'openapi.managedClusters.yaml#/components/schemas/ManagedClusterList'
     ManagedClusterPatchRequest:
       $ref: 'openapi.managedClusters.yaml#/components/schemas/ManagedClusterPatchRequest'
+    ManagedClusterRegistrationRequest:
+      $ref: 'openapi.managedClusters.yaml#/components/schemas/ManagedClusterRegistrationRequest'
+    ManagedClusterRegistrationResponse:
+      $ref: 'openapi.managedClusters.yaml#/components/schemas/ManagedClusterRegistrationResponse'
     ManagedDatabase:
       $ref: 'openapi.managedDatabases.yaml#/components/schemas/ManagedDatabase'
     ManagedDatabaseList:

components/api-server/pkg/api/openapi/.openapi-generator/FILES

@@ -22,6 +22,8 @@ docs/List.md
 docs/ManagedCluster.md
 docs/ManagedClusterList.md
 docs/ManagedClusterPatchRequest.md
+docs/ManagedClusterRegistrationRequest.md
+docs/ManagedClusterRegistrationResponse.md
 docs/ManagedDatabase.md
 docs/ManagedDatabaseList.md
 docs/ManagedDatabasePatchRequest.md
@@ -61,6 +63,8 @@ model_list.go
 model_managed_cluster.go
 model_managed_cluster_list.go
 model_managed_cluster_patch_request.go
+model_managed_cluster_registration_request.go
+model_managed_cluster_registration_response.go
 model_managed_database.go
 model_managed_database_list.go
 model_managed_database_patch_request.go

components/api-server/pkg/api/openapi/README.md

@@ -111,6 +111,7 @@ Class | Method | HTTP request | Description
 *DefaultAPI* | [**ListRoleBindings**](docs/DefaultAPI.md#listrolebindings) | **Get** /api/hypershell/v1/role_bindings | List role bindings
 *DefaultAPI* | [**ListRoles**](docs/DefaultAPI.md#listroles) | **Get** /api/hypershell/v1/roles | List all roles
 *DefaultAPI* | [**ListUsers**](docs/DefaultAPI.md#listusers) | **Get** /api/hypershell/v1/users | List registered users
+*DefaultAPI* | [**RegisterManagedCluster**](docs/DefaultAPI.md#registermanagedcluster) | **Post** /api/hypershell/v1/managed_clusters/registration | Self-register a spoke control-plane as a managed cluster
 *DefaultAPI* | [**RevokeGatewayServiceAccount**](docs/DefaultAPI.md#revokegatewayserviceaccount) | **Post** /api/hypershell/v1/gateways/{gateway_id}/service_accounts/{service_account_id}/revoke | Permanently revoke an OpenShell gateway service account
 *DefaultAPI* | [**UpdateGateway**](docs/DefaultAPI.md#updategateway) | **Patch** /api/hypershell/v1/gateways/{id} | Update an gateway
 *DefaultAPI* | [**UpdateGatewayNetwork**](docs/DefaultAPI.md#updategatewaynetwork) | **Patch** /api/hypershell/v1/gateway_networks/{id} | Update an gatewayNetwork
@@ -136,6 +137,8 @@ Class | Method | HTTP request | Description
  - [ManagedCluster](docs/ManagedCluster.md)
  - [ManagedClusterList](docs/ManagedClusterList.md)
  - [ManagedClusterPatchRequest](docs/ManagedClusterPatchRequest.md)
+ - [ManagedClusterRegistrationRequest](docs/ManagedClusterRegistrationRequest.md)
+ - [ManagedClusterRegistrationResponse](docs/ManagedClusterRegistrationResponse.md)
  - [ManagedDatabase](docs/ManagedDatabase.md)
  - [ManagedDatabaseList](docs/ManagedDatabaseList.md)
  - [ManagedDatabasePatchRequest](docs/ManagedDatabasePatchRequest.md)

components/api-server/pkg/api/openapi/api/openapi.yaml

@@ -154,6 +154,67 @@ paths:
       security:
       - Bearer: []
       summary: Create a new managedCluster
+  /api/hypershell/v1/managed_clusters/registration:
+    post:
+      description: |
+        Idempotent. Creates a ManagedCluster record on first call; returns the existing
+        cluster_id on subsequent calls from the same OIDC identity. Updates last_seen_at
+        on every call, making this endpoint double as a heartbeat. Requires the
+        managed-cluster-registrar Keycloak realm role.
+      operationId: registerManagedCluster
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ManagedClusterRegistrationRequest"
+        description: Registration request
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ManagedClusterRegistrationResponse"
+          description: Already registered; last_seen_at updated
+        "201":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ManagedClusterRegistrationResponse"
+          description: Registered for the first time
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Validation error
+        "401":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Auth token is invalid
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Missing managed-cluster-registrar role
+        "409":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Same OIDC subject already registered under a different name
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Unexpected error
+      security:
+      - Bearer: []
+      summary: Self-register a spoke control-plane as a managed cluster
   /api/hypershell/v1/managed_clusters/{id}:
     delete:
       operationId: deleteManagedCluster
@@ -2290,21 +2351,34 @@ components:
             type: string
           api_server_url:
             type: string
+          oidc_subject:
+            description: OIDC sub claim of the service account that registered this
+              cluster. Server-assigned; not writable.
+            readOnly: true
+            type: string
+          last_seen_at:
+            description: Timestamp of the most recent registration call. Updated on
+              every POST /registration.
+            format: date-time
+            readOnly: true
+            type: string
         required:
         - kubeconfig_secret
         - name
         - provider
         type: object
       example:
+        kind: kind
+        created_at: 2000-01-23T04:56:07.000+00:00
+        oidc_subject: oidc_subject
         updated_at: 2000-01-23T04:56:07.000+00:00
         provider: provider
-        kind: kind
         name: name
-        created_at: 2000-01-23T04:56:07.000+00:00
         kubeconfig_secret: kubeconfig_secret
         id: id
         href: href
         region: region
+        last_seen_at: 2000-01-23T04:56:07.000+00:00
         status: status
         api_server_url: api_server_url
     ManagedClusterList:
@@ -2326,26 +2400,30 @@ components:
         id: id
         href: href
         items:
-        - updated_at: 2000-01-23T04:56:07.000+00:00
+        - kind: kind
+          created_at: 2000-01-23T04:56:07.000+00:00
+          oidc_subject: oidc_subject
+          updated_at: 2000-01-23T04:56:07.000+00:00
           provider: provider
-          kind: kind
           name: name
-          created_at: 2000-01-23T04:56:07.000+00:00
           kubeconfig_secret: kubeconfig_secret
           id: id
           href: href
           region: region
+          last_seen_at: 2000-01-23T04:56:07.000+00:00
           status: status
           api_server_url: api_server_url
-        - updated_at: 2000-01-23T04:56:07.000+00:00
+        - kind: kind
+          created_at: 2000-01-23T04:56:07.000+00:00
+          oidc_subject: oidc_subject
+          updated_at: 2000-01-23T04:56:07.000+00:00
           provider: provider
-          kind: kind
           name: name
-          created_at: 2000-01-23T04:56:07.000+00:00
           kubeconfig_secret: kubeconfig_secret
           id: id
           href: href
           region: region
+          last_seen_at: 2000-01-23T04:56:07.000+00:00
           status: status
           api_server_url: api_server_url
     ManagedClusterPatchRequest:
@@ -2370,6 +2448,32 @@ components:
         api_server_url:
           type: string
       type: object
+    ManagedClusterRegistrationRequest:
+      example:
+        name: name
+        description: description
+      properties:
+        name:
+          description: "Human-readable spoke name, unique per fleet (e.g. hyp0-mc1).\
+            \ Must match on every subsequent call."
+          type: string
+        description:
+          description: Optional description of the spoke.
+          type: string
+      required:
+      - name
+      type: object
+    ManagedClusterRegistrationResponse:
+      example:
+        cluster_id: cluster_id
+      properties:
+        cluster_id:
+          description: Stable KSUID assigned to this managed cluster. Use as the cluster
+            filter for WatchGateways.
+          type: string
+      required:
+      - cluster_id
+      type: object
     ManagedDatabase:
       allOf:
       - $ref: "#/components/schemas/ObjectReference"