{"id":13491030,"url":"https://github.com/oam-dev/cluster-gateway","last_synced_at":"2025-05-15T11:06:01.649Z","repository":{"id":37936690,"uuid":"402645818","full_name":"oam-dev/cluster-gateway","owner":"oam-dev","description":"Multi-cluster api gateway based on apiserver-aggregation.","archived":false,"fork":false,"pushed_at":"2024-12-18T03:49:35.000Z","size":628,"stargazers_count":102,"open_issues_count":13,"forks_count":39,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-19T13:18:06.865Z","etag":null,"topics":["kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oam-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-03T04:26:22.000Z","updated_at":"2025-04-11T06:09:38.000Z","dependencies_parsed_at":"2024-12-15T21:06:39.867Z","dependency_job_id":"b20b5642-1a70-4343-9c5e-5312c7406091","html_url":"https://github.com/oam-dev/cluster-gateway","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oam-dev%2Fcluster-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oam-dev%2Fcluster-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oam-dev%2Fcluster-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oam-dev%2Fcluster-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oam-dev","download_url":"https://codeload.github.com/oam-dev/cluster-gateway/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328385,"owners_count":22052632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kubernetes"],"created_at":"2024-07-31T19:00:52.983Z","updated_at":"2025-05-15T11:06:01.629Z","avatar_url":"https://github.com/oam-dev.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Cluster Gateway\n\n## Overall\n\n\"Cluster Gateway\" is a gateway apiserver for routing kubernetes api traffic\nto multiple kubernetes clusters. Additionally, the gateway is completely \npluggable for a running kubernetes cluster natively because it is developed\nbased on the native api extensibility named [apiserver-aggregation](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/).\nA new extended resource \"cluster.core.oam.dev/ClusterGateway\" will be \nregistered into the hosting cluster after properly applying corresponding \n`APIService` objects, and a new subresource named \"proxy\" will be available \nfor every existing \"Cluster Gateway\" resource which is inspired by the \noriginal kubernetes \"service/proxy\", \"pod/proxy\" subresource.\n\nOverall our \"Cluster Gateway\" also has the following merits as a multi-cluster \napi-gateway solution:\n\n- __Etcd Free__: Normally an aggregated apiserver must be deployed along \n  with a dedicated etcd cluster which is bringing extra costs for the admins. \n  While our \"Cluster Gateway\" can be running completely without etcd instances,\n  because the extended \"ClusterGateway\" resource are virtual read-only \n  kubernetes resource which is converted from secret resources from a namespace\n  in the hosting cluster.\n  \n- __Scalability__: Our \"Cluster Gateway\" can scale out to arbitrary instances\n  to deal with the increasing loads \n  \n![Arch](./docs/images/arch.png)\n\n\n## Image\n\n```shell\n$ docker pull oamdev/cluster-gateway:v1.1.12 # Or other newer tags\n```\n\n## Documentation\n\n- __Run locally__: https://github.com/oam-dev/cluster-gateway/blob/master/docs/local-run.md\n- __Sample cluster-gateway converting secret__:\n  - __ServiceAccountToken type secret__: https://github.com/oam-dev/cluster-gateway/blob/master/hack/samples/cluster-gateway-secret-serviceaccount-token.yaml\n  - __X.509 certificate type secret__: https://github.com/oam-dev/cluster-gateway/blob/master/hack/samples/cluster-gateway-secret-x509.yaml\n\n### Performance\n\nCompile the e2e benchmark suite by:\n\n```shell\n$ make e2e-benchmark-binary\n```\n\nThe benchmark suite will be creating-updating-deleting configmaps in a flow\nrepeatly for 100 times. Here's a comparison of the performance we observed\nin a local experiment:\n\n\n|  Bandwidth  |  Direct          |  ClusterGateway  | ClusterGateway(over Konnectivity) |\n|-------------|------------------|------------------|-----------------------------------|\n|  Fastest    |  0.059s          |  0.190s          | 0.428s                            |\n|  Slowest    |  0.910s          |  0.856s          | 1.356s                            |\n|  Average    |  0.583s ± 0.104s |  0.581s ± 0.087s | 0.608s ± 0.135s                   |\n\n### Open-Cluster-Management Integration\n\nCluster-gateway has native integration with [Open-Cluster-Management(OCM)](https://open-cluster-management.io/)\nto provide the KubeVela admin a more coherent user experience in distributing\napplications across multiple clusters:\n\n#### Enabling OCM seamlessly in your KubeVela environment\n\nThe official vela addon named [ocm-cluster-manager](https://github.com/oam-dev/catalog/tree/master/addons/ocm-cluster-manager)\nwill help you easily bootstrap the OCM control plane (in the hosting cluster\nwhere your KubeVela control plane lives). Note that the OCM environment \ninstalled from the addon above will not take any effect until we opt-in to\nenable the functional integration between KubeVela and OCM as is elaborated \nbelow. It's just a minimal trial setup to try out OCM instantly, while in order\nto enable the further integration with OCM, we will need to adjust the \nconfiguration of cluster-gateway to make it detect and aware of the local OCM\nenvironment.\n\n#### Aligning ClusterGateway to OCM's cluster registry\n\nBy opt-in to the flag `--ocm-integration=true`, the cluster-gateway will be\ndetecting and loading the OCM environment in the hosting cluster and connecting\neach `ClusterGateway` custom resource from cluster-gateway to OCM's original\ncluster model in OCM named `ManagedCluster`. The `ClusterGateway` is a\ngateway \"ingress\" abstraction for the Kubernetes clusters managed by KubeVela,\nso after integrating with OCM it's intuitive to regard the gateway resource\nas a \"satellite\" child resource around `ManagedCluster`. Setting the flag will\nmake the cluster-gateway filter out those dangling `ClusterGateway` that doesn't\nhave a valid `ManagedCluster` bound with. In addition to that, we won't need to\nexplicitly set the master URL in the cluster secret because the cluster-gateway\nwill be merging the URL list from the corresponding `ManagedCluster`. \n\nFurthermore, by enabling the integration, we will also reflect/aggregate the \nhealthiness of the corresponding clusters by partially merging the original\nhealthiness status from OCM's `ManagedCluster`. So we can save the troubles \nbefore attempting to talk to an unavailable cluster.\n\n#### Delegating the upgrading/rotation of cluster-gateway to OCM\n\nInstalling the cluster-gateway via the [standalone chart](https://github.com/oam-dev/cluster-gateway/tree/master/charts/cluster-gateway)\nor [KubeVela's chart](https://github.com/oam-dev/kubevela/tree/master/charts/vela-core)\nprovides us a one-time light-weighting setup of cluster-gateway, but sadly \nthere are still some missing puzzles we should notice before we bring the \ncluster-gateway into sustainable production environment:\n\n- The rotation of cluster-gateway's server TLS certificate.\n- Automatic addition/removal of the `ClusterGateway` resource upon cluster \n  discovery.\n\nIn order to fill the blanks in cluster-gateway above, optionally we can delegate\nthe management of cluster-gateway to OCM by introducing a new component named [cluster-gateway-addon-manager](https://github.com/oam-dev/cluster-gateway/tree/master/cmd/addon-manager)\nto the hosting cluster which is basically responsible for:\n\n1. Sustainable installation as a typical \"operator\" dedicated for\n   cluster-gateway.\n2. Modelling cluster-gateway as an [OCM addon](https://open-cluster-management.io/concepts/addon/).\n\nThe addon-manager can be installed via simple helm commands, please refer to\nthe installation guide [here](https://open-cluster-management.io/scenarios/pushing-kube-api-requests/#installation).\n\n### Identity Passing\n\nWhen feature flag `ClientIdentityPenetration` is enabled, cluster-gateway will \nrecognize the identity in the incoming requests and use the [impersonation mechanism](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation)\nto send requests to managed clusters with identity impersonated. By default,\nthe impersonated identity is consistent with the identity in the incoming requests.\n\nIn the cases that the identity in different clusters are not aligned, the [ClientIdentityExchanger](https://github.com/oam-dev/cluster-gateway/issues/120)\nfeature would be helpful to make projections. You can use either the global configuration\nor the cluster configuration for declaring the identity exchange rules, like the given \n[example](https://github.com/oam-dev/cluster-gateway/tree/master/examples/client-identity-exchanger/config.yaml).\nFor global configuration, you need to set up the `--cluster-gateway-proxy-config=\u003cthe configuration file path\u003e`\nto enable it. For cluster configuration, you can set the annotation `cluster.core.oam.dev/cluster-gateway-proxy-configuration`\nvalue to enable the configuration for the requests to the attached cluster.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foam-dev%2Fcluster-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foam-dev%2Fcluster-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foam-dev%2Fcluster-gateway/lists"}