Cluster Proxy enables secure network connectivity between hub clusters and managed clusters in Open Cluster Management (OCM) environments. It provides a solution for accessing services in managed clusters from the hub cluster, even when clusters are deployed in different networks or VPCs.
Cluster Proxy is a pluggable addon for Open Cluster Management (OCM) built on the extensibility provided by addon-framework that automates the installation of apiserver-network-proxy on both hub cluster and managed clusters. The network proxy establishes reverse proxy tunnels from the managed cluster to the hub cluster, enabling clients from the hub network to access services in the managed clusters' network even when all the clusters are isolated in different VPCs.
Cluster Proxy always deploys two components:
-
Addon-Manager: Manages the installation of proxy servers (proxy ingress) in the hub cluster.
-
Addon-Agent: Manages the installation of proxy agents for each managed cluster.
When service proxying is enabled, cluster-proxy also deploys:
-
User-Server: Accepts authenticated HTTP requests on the hub and sends them through the cluster-proxy tunnel.
-
Service-Proxy: Runs beside the proxy agent on each managed cluster, authenticates Kubernetes API requests, and supports managed-cluster tokens, hub-token impersonation, and optional external OIDC ID tokens.
The overall architecture is shown below:
- Open Cluster Management (OCM) registration component installed
- A Kubernetes cluster serving as the hub cluster
- One or more managed Kubernetes clusters registered with the hub
- Add the OCM Helm repository:
helm repo add ocm https://open-cluster-management.io/helm-charts/
helm repo update
helm search repo ocm/cluster-proxyExpected output:
NAME CHART VERSION APP VERSION DESCRIPTION
ocm/cluster-proxy <chart-version> <app-version> A Helm chart for Cluster-Proxy
- Install the Helm chart:
helm install \
-n open-cluster-management-addon --create-namespace \
cluster-proxy ocm/cluster-proxy - Verify the installation:
kubectl get pods -n open-cluster-management-addonExpected output:
NAME READY STATUS RESTARTS AGE
cluster-proxy-5d8db7ddf4-265tm 1/1 Running 0 12s
cluster-proxy-addon-manager-778f6d679f-9pndv 1/1 Running 0 33s
...
- The addon will be automatically installed to your registered clusters. Verify the addon installation:
kubectl get managedclusteraddon -A | grep cluster-proxyExpected output:
NAMESPACE NAME AVAILABLE DEGRADED PROGRESSING
<your cluster> cluster-proxy True
By default, the proxy servers are running in gRPC mode so the proxy clients are expected to proxy through the tunnels by the konnectivity-client. Konnectivity is the underlying technique of Kubernetes' egress-selector feature and an example of konnectivity client is visible here.
In code, proxying to the managed cluster is simply a matter of overriding the dialer of the Kubernetes client config object, e.g.:
// Set this to the proxy entrypoint address for your deployment.
proxyServiceAddress := "proxy-entrypoint.open-cluster-management-addon.svc:8090"
// instantiate a gRPC proxy dialer
tunnel, err := konnectivity.CreateSingleUseGrpcTunnel(
context.TODO(),
proxyServiceAddress,
grpc.WithTransportCredentials(grpccredentials.NewTLS(proxyTLSCfg)),
)
cfg, err := clientcmd.BuildConfigFromFlags("", kubeconfig)
if err != nil {
return err
}
// The managed cluster's name.
cfg.Host = clusterName
// Override the default TCP dialer
cfg.Dial = tunnel.DialContext The optional user-server and service-proxy provide an HTTPS endpoint for proxying HTTP traffic to managed cluster Services through the tunnel. Kubernetes API requests can authenticate with a managed cluster token, a hub token that is impersonated on the managed cluster, or a per-cluster external OIDC issuer.
Service proxying is disabled by default. Enable it with the Helm values
enableServiceProxy=true and enableImpersonation=true; use
userServer.enabled=true when the controller should generate and rotate the
user-server serving certificate.
These Helm values enable the shared proxy infrastructure only. OIDC must be
configured per managed cluster through an AddOnDeploymentConfig referenced by
that cluster's ManagedClusterAddOn.
See the service-proxy authentication and impersonation guide for the complete OpenShift LDAP and OIDC configuration procedures. See the Helm chart documentation for installation and certificate options.
The following table shows network bandwidth benchmarking results via goben comparing direct connections with connections through Cluster-Proxy (Apiserver-Network-Proxy). The proxying through the tunnel involves approximately 50% performance overhead, so it's recommended to avoid transferring data-intensive traffic over the proxy when possible.
| Bandwidth | Direct | over Cluster-Proxy |
|---|---|---|
| Read/Mbps | 902 Mbps | 461 Mbps |
| Write/Mbps | 889 Mbps | 428 Mbps |