From eb12e6ff9433c932c2616cd2d4b60ccf37d3befe Mon Sep 17 00:00:00 2001 From: xuezhaojun Date: Tue, 11 Nov 2025 23:29:58 +0800 Subject: [PATCH] docs: enhance cluster-proxy blog post with improved text, structure, and section hierarchy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix typos and grammar issues throughout the document - Standardize terminology (Hub/Spoke → hub/managed clusters) - Improve section structure with better logical flow (Setup → Install → Use) - Add detailed explanation for GATEWAY_IP configuration - Fix cluster name inconsistencies (cluster1 → managed) - Move 'Verifying the Deployment' under 'Installing Cluster Proxy' section - Rename main usage section for better clarity These improvements enhance readability and make the tutorial easier to follow. Signed-off-by: xuezhaojun --- .../index.md | 313 ++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 content/en/blog/cluster-proxy-support-service-proxy/index.md diff --git a/content/en/blog/cluster-proxy-support-service-proxy/index.md b/content/en/blog/cluster-proxy-support-service-proxy/index.md new file mode 100644 index 000000000..614e576c9 --- /dev/null +++ b/content/en/blog/cluster-proxy-support-service-proxy/index.md @@ -0,0 +1,313 @@ +--- +title: Cluster Proxy Now Supports "Service Proxy" — An Easy Way to Access Services in Managed Clusters +date: 2025-11-11 +author: Zhao Xue [@xuezhaojun](https://github.com/xuezhaojun) +toc_hide: true +--- + +## Introduction + +Cluster Proxy is an [OCM addon](https://github.com/open-cluster-management-io/cluster-proxy) that provides L4 network connectivity between hub and managed clusters through a reverse proxy tunnel. In previous versions, accessing services on managed clusters through cluster-proxy required using a specialized Go package, the [konnectivity client](https://github.com/open-cluster-management-io/cluster-proxy/blob/main/examples/test-client.md). + +With the new v0.9.0 release, we've introduced a more convenient approach — "Service Proxy". This feature provides an HTTPS service that allows users to access the kube-apiserver and other services in managed clusters through a specific URL structure. Additionally, it introduces a more user-friendly authentication and authorization mechanism using **Impersonation**, enabling users to authenticate and authorize against the managed cluster's kube-apiserver using their hub user token. + +Let's set up a simple test environment to demonstrate these new capabilities. + +## Setting Up the Environment + +First, create a basic OCM environment with one hub cluster and one managed cluster. + +Create a hub cluster with port mapping for the proxy-entrypoint service. The `extraPortMappings` configuration exposes port 30091 from the container to the host machine, allowing external access to the proxy service: + +```bash +# Create hub cluster with port mapping for proxy-entrypoint service +cat </managed/g") + +# Accept the managed cluster +echo "Accepting managed cluster..." +clusteradm accept --context kind-hub --clusters managed --wait + +# Verify the setup +echo "Verifying the setup..." +kubectl get managedclusters --all-namespaces --context kind-hub +``` + +## Installing Cluster Proxy + +Next, install the Cluster Proxy addon following the [official installation guide](https://open-cluster-management.io/docs/getting-started/integration/cluster-proxy/): + +```shell +helm repo add ocm https://open-cluster-management.io/helm-charts/ +helm repo update +helm search repo ocm/cluster-proxy +``` + +Verify that the CHART VERSION is v0.9.0 or later: + +```shell +$ helm search repo ocm/cluster-proxy +NAME CHART VERSION APP VERSION DESCRIPTION +ocm/cluster-proxy 0.9.0 1.1.0 A Helm chart for Cluster-Proxy OCM Addon +``` + +### Setting Up TLS Certificates + +The new deployment `cluster-proxy-addon-user` requires server certificates for its HTTPS service, otherwise the deployment will hang in the container creating state: + +To create the certificates, first install cert-manager: + +```shell +kubectl --context kind-hub apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.yaml +kubectl --context kind-hub wait --for=condition=ready pod -l app.kubernetes.io/instance=cert-manager -n cert-manager --timeout=300s +``` + +Next, create the certificate resources: + +```shell +kubectl --context kind-hub apply -f - < 443/TCP 10s +``` + +## Using Service Proxy to Access Managed Clusters + +Now that the installation is complete, let's demonstrate how to use the Service Proxy feature to access resources in managed clusters. We'll access pods in the `open-cluster-management-agent` namespace in the `managed` cluster, which will also showcase the impersonation authentication mechanism. + +### Creating a Hub User + +First, create a hub user (a service account in the hub cluster) named `test-sa`: + +``` +kubectl --context kind-hub create serviceaccount -n open-cluster-management-hub test-sa +``` + +### Configuring RBAC Permissions + +Next, create a Role and RoleBinding in the `managed` cluster to grant the `test-sa` user permission to list and get pods in the `open-cluster-management-agent` namespace: + +``` +kubectl --context kind-managed apply -f - <:`, where `` and `` are the namespace and name of the service account in the hub cluster. +- Alternatively, you can use [cluster-permission](https://github.com/open-cluster-management-io/cluster-permission) to create roles and role bindings from the hub cluster side. + +### Generating an Access Token + +Generate a token for the `test-sa` service account: + +```shell +TOKEN=$(kubectl --context kind-hub -n open-cluster-management-hub create token test-sa) +``` + +### Testing the Service Proxy + +Now let's test accessing pods in the `managed` cluster through the `cluster-proxy-addon-user` service. We'll start a debug container in the hub cluster and use curl to make the request: + +```bash +POD=$(kubectl get pods -n open-cluster-management-addon -l component=cluster-proxy-addon-user --field-selector=status.phase=Running -o jsonpath='{.items[0].metadata.name}') + +kubectl debug -it $POD -n open-cluster-management-addon --image=praqma/network-multitool -- sh -c "curl -k -H 'Authorization: Bearer $TOKEN' https://cluster-proxy-addon-user.open-cluster-management-addon.svc.cluster.local:9092/managed/api/v1/namespaces/open-cluster-management-agent/pods" +``` + +The URL structure for accessing resources is: + +``` +https://cluster-proxy-addon-user..svc.cluster.local:9092// +``` + +You should see a JSON response listing the pods in the `open-cluster-management-agent` namespace of the `managed` cluster, demonstrating successful authentication and authorization through the impersonation mechanism. + +## Summary + +In this blog post, we've demonstrated the new Service Proxy feature introduced in cluster-proxy v0.9.0. The key highlights include: + +- **Service Proxy**: A new HTTPS-based method to access services in managed clusters without requiring the konnectivity client package +- **Impersonation**: A user-friendly authentication mechanism that allows hub users to access managed cluster resources using their hub tokens +- **Simple URL Structure**: Access managed cluster resources through a straightforward URL pattern + +These features significantly simplify the process of accessing managed cluster services, making it easier to build tools and integrations on top of OCM's multi-cluster management capabilities. + +We hope you find these new features useful! For more information, please visit the [cluster-proxy GitHub repository](https://github.com/open-cluster-management-io/cluster-proxy).