Add documentation for gRPC-based cluster registration #526

qiujian16 · 2025-10-23T07:45:34Z

This commit adds comprehensive documentation for the gRPC-based registration feature introduced in OCM v0.15.0, addressing issue #521.

Key additions:

New guide: register-cluster-via-grpc.md covering:
- Architecture and benefits of gRPC registration
- Complete ClusterManager configuration with registrationDrivers
- Instructions for exposing gRPC server via Ingress/Route
- Klusterlet configuration with gRPC authType
- Troubleshooting guide and migration instructions
- Important note about add-on limitations with gRPC
Updated start-the-control-plane.md to reference the new gRPC registration option as an alternative to standard registration

The documentation provides accurate API configurations based on the open-cluster-management-io/api repository and includes practical examples for both Kubernetes and OpenShift environments.

Fixes #521

netlify · 2025-10-23T07:45:39Z

❌ Deploy Preview for open-cluster-management failed.

Name	Link
🔨 Latest commit	`20c295d`
🔍 Latest deploy log	https://app.netlify.com/projects/open-cluster-management/deploys/68fad73cee4b1d000827edfd

openshift-ci · 2025-10-23T07:45:40Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: qiujian16

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

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [qiujian16]

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

skeeey · 2025-10-23T08:23:05Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+   ```
+
+## Migration from API-based to gRPC-based registration
+


we may not support this?

skeeey · 2025-10-23T08:23:10Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+
+### TLS certificate issues
+
+If you encounter TLS certificate validation errors:


the custom ca is not supported, currently we generate the cert automatically

kubectl -n open-cluster-management-hub get cm ca-bundle-configmap -ojsonpath='{.data.ca-bundle\.crt}' kubectl -n open-cluster-management-hub get secrets signer-secret -ojsonpath="{.data.tls\.crt}" kubectl -n open-cluster-management-hub get secrets signer-secret -ojsonpath="{.data.tls\.key}"

skeeey · 2025-10-23T08:23:20Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+{{< tabpane text=true >}}
+{{% tab header="kind" %}}
+```shell
+clusteradm join \


cluseradm is not supported yet

skeeey · 2025-10-23T08:23:29Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+
+## Register a managed cluster using gRPC
+
+### Step 1: Generate the join token


the clusteradm is not supported yet, we may use the helm chart to register for now
see https://github.com/stolostron/cloudevents-conductor/tree/main?tab=readme-ov-file#import-your-managed-cluster

is it ok we use clusteradm join at first, then update klusterlet? I think the missing part is setting grpc config in bootstrap secret?

yes, the missing part is setting grpc config in bootstrap secret, but need some test

skeeey · 2025-10-23T08:23:39Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+    name: cluster-manager-grpc-server
+    weight: 100
+  port:
+    targetPort: grpc


Suggested change

targetPort: grpc

targetPort: 8090

skeeey · 2025-10-23T08:23:47Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+  name: cluster-manager-grpc-server
+  namespace: open-cluster-management-hub
+spec:
+  host: hub-grpc.apps.example.com


for ocp route, we don't need to set the host

skeeey · 2025-10-23T08:24:05Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+
+**Important**: The hostname in your Ingress/Route **must match** the `host` value specified in the ClusterManager's `serverConfiguration.endpointsExposure[].grpc.hostname.host` field.
+
+**Option 1: Using Ingress (for Kubernetes)**


current we may only put the route here

we would need ingress test, otherwise, it cannot be used without openshift.

OK, will test this

skeeey · 2025-10-23T08:24:14Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+            # The hostname where managed clusters will connect
+            # This should match your Ingress/Route hostname
+            host: hub-grpc.example.com
+            # Optional: CA bundle for TLS (base64 encoded)


the custom ca bundle does not support yet

skeeey · 2025-10-23T08:24:46Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+          type: hostname
+          hostname:
+            # The hostname where managed clusters will connect
+            # This should match your Ingress/Route hostname


only route is tested, we may focus on route firstly

skeeey · 2025-10-23T08:24:56Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+- **OCM v1.1.0 or later** (when gRPC support was introduced)
+- Hub cluster with cluster manager installed
+- Network connectivity from managed clusters to the hub's gRPC server endpoint
+- The managed clusters should be `v1.11+`


what is the v1.11?

skeeey · 2025-10-23T08:25:04Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+- Network connectivity from managed clusters to the hub's gRPC server endpoint
+- The managed clusters should be `v1.11+`
+- Ensure [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) and [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/) are installed
+- A method to expose the gRPC server (using Ingress, Route, or LoadBalancer)


current we only tested the route, the ingress and loadbalancer are not tested

we need at least one way that works in non ocp.

for non ocp, we may start with the LoadBalancer service as an example.
For ingress, the configuration depends on the platform and is more complex.

create a LoadBalancer service firstly

apiVersion: v1 kind: Service metadata: name: cluster-manager-grpc-server-lb namespace: open-cluster-management-hub spec: type: LoadBalancer ports: - name: grpc port: 443 targetPort: 8090 protocol: TCP selector: app: cluster-manager-grpc-server

note: for eks, the annotation service.beta.kubernetes.io/aws-load-balancer-type: nlb is required

find external ip as the grpc host

kubectl get svc cluster-manager-grpc-lb -n open-cluster-management-hub -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

then using clusteradm init hub and join the cluster

This commit adds comprehensive documentation for the gRPC-based registration feature introduced in OCM v0.15.0, addressing issue open-cluster-management-io#521. Key additions: - New guide: register-cluster-via-grpc.md covering: - Architecture and benefits of gRPC registration - Complete ClusterManager configuration with registrationDrivers - Instructions for exposing gRPC server via Ingress/Route - Klusterlet configuration with gRPC authType - Troubleshooting guide and migration instructions - Important note about add-on limitations with gRPC - Updated start-the-control-plane.md to reference the new gRPC registration option as an alternative to standard registration The documentation provides accurate API configurations based on the open-cluster-management-io/api repository and includes practical examples for both Kubernetes and OpenShift environments. Fixes open-cluster-management-io#521 Signed-off-by: Jian Qiu <[email protected]>

ncr38 · 2025-10-24T09:49:03Z

content/en/docs/getting-started/installation/register-cluster-via-grpc.md

+          autoApprovedIdentities: []
+
+  # Server configuration for the gRPC server
+  serverConfiguration:


This option is not there in helm charts. Can I raise a PR for same ?

@ncr38 sorry for missing the message. I opened a PR to add serverConfiguration into clustermanager helm chart since clusteradm init needs to support grpc import.

openshift-ci bot requested a review from dhaiducek October 23, 2025 07:45

openshift-ci bot requested a review from mikeshng October 23, 2025 07:45

openshift-ci bot added the approved label Oct 23, 2025

qiujian16 force-pushed the grpc branch from ffc768a to f3100bb Compare October 23, 2025 07:47

skeeey reviewed Oct 23, 2025

View reviewed changes

qiujian16 force-pushed the grpc branch from f3100bb to 20c295d Compare October 24, 2025 01:32

ncr38 reviewed Oct 24, 2025

View reviewed changes


		### TLS certificate issues

		If you encounter TLS certificate validation errors:


		## Register a managed cluster using gRPC

		### Step 1: Generate the join token


		Important: The hostname in your Ingress/Route must match the `host` value specified in the ClusterManager's `serverConfiguration.endpointsExposure[].grpc.hostname.host` field.

		Option 1: Using Ingress (for Kubernetes)

Add documentation for gRPC-based cluster registration #526

Are you sure you want to change the base?

Add documentation for gRPC-based cluster registration #526

Uh oh!

Conversation

qiujian16 commented Oct 23, 2025

Uh oh!

netlify bot commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for open-cluster-management failed.

Uh oh!

openshift-ci bot commented Oct 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

skeeey Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify bot commented Oct 23, 2025 •

edited

Loading

skeeey Oct 24, 2025 •

edited

Loading