{"id":15710417,"url":"https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s","last_synced_at":"2025-04-05T13:06:24.753Z","repository":{"id":37608539,"uuid":"408620399","full_name":"aws/aws-cloud-map-mcs-controller-for-k8s","owner":"aws","description":"K8s controller implementing Multi-Cluster Services API based on AWS Cloud Map.","archived":false,"fork":false,"pushed_at":"2024-12-11T23:37:47.000Z","size":1431,"stargazers_count":92,"open_issues_count":33,"forks_count":28,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-29T12:06:33.970Z","etag":null,"topics":["aws","aws-cloudmap","eks","golang","k8s","k8s-controller","kubernetes","kubernetes-controller","multicluster"],"latest_commit_sha":null,"homepage":"https://aws.amazon.com/blogs/opensource/kubernetes-multi-cluster-service-discovery-using-open-source-aws-cloud-map-mcs-controller/","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/aws.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-20T22:40:27.000Z","updated_at":"2025-02-26T11:59:58.000Z","dependencies_parsed_at":"2024-10-23T03:58:58.804Z","dependency_job_id":"5e012c46-68a3-4cd2-b13e-16d6e9fa7429","html_url":"https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s","commit_stats":{"total_commits":178,"total_committers":16,"mean_commits":11.125,"dds":0.7191011235955056,"last_synced_commit":"a66f87a63522b60072563fe5fc6697d8db60a45a"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-cloud-map-mcs-controller-for-k8s","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-cloud-map-mcs-controller-for-k8s/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-cloud-map-mcs-controller-for-k8s/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-cloud-map-mcs-controller-for-k8s/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/aws-cloud-map-mcs-controller-for-k8s/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339155,"owners_count":20923014,"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":["aws","aws-cloudmap","eks","golang","k8s","k8s-controller","kubernetes","kubernetes-controller","multicluster"],"created_at":"2024-10-03T21:07:20.942Z","updated_at":"2025-04-05T13:06:24.736Z","avatar_url":"https://github.com/aws.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Cloud Map MCS Controller for K8s\n\n[![Documentation](https://img.shields.io/badge/godoc-reference-blue.svg)](https://godoc.org/github.com/aws/aws-cloud-map-mcs-controller-for-k8s)\n[![CodeQL](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/actions/workflows/codeql-analysis.yml/badge.svg?branch=main)](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/actions/workflows/codeql-analysis.yml)\n[![Build status](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/actions/workflows/build.yml)\n[![Deploy status](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/actions/workflows/deploy.yml)\n[![Integration status](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/actions/workflows/integration-test.yml/badge.svg?branch=main)](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/actions/workflows/integration-test.yml)\n[![codecov](https://codecov.io/gh/aws/aws-cloud-map-mcs-controller-for-k8s/branch/main/graph/badge.svg)](https://codecov.io/gh/aws/aws-cloud-map-mcs-controller-for-k8s)\n\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg?color=success)](http://www.apache.org/licenses/LICENSE-2.0)\n[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/issues)\n[![GitHub issues](https://img.shields.io/github/issues-raw/aws/aws-cloud-map-mcs-controller-for-k8s?style=flat)](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/issues)\n[![Go Report Card](https://goreportcard.com/badge/github.com/aws/aws-cloud-map-mcs-controller-for-k8s)](https://goreportcard.com/report/github.com/aws/aws-cloud-map-mcs-controller-for-k8s)\n\n## Introduction\nThe AWS Cloud Map Multi-cluster Service Discovery Controller for Kubernetes (K8s) implements the Kubernetes [KEP-1645: Multi-Cluster Services API](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/1645-multi-cluster-services-api) and [KEP-2149: ClusterId for ClusterSet identification](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid), which allows services to communicate across multiple clusters. The implementation relies on [AWS Cloud Map](https://aws.amazon.com/cloud-map/) for enabling cross-cluster service discovery. We have detailed [step-by-step setup guide](https://aws.amazon.com/blogs/opensource/kubernetes-multi-cluster-service-discovery-using-open-source-aws-cloud-map-mcs-controller/)!\n\n**⚠ NOTE: The current version [![GitHub Release](https://img.shields.io/github/release/aws/aws-cloud-map-mcs-controller-for-k8s.svg?style=flat\u0026label=)]() is in *Alpha* phase, and NOT intended for production use. The support will be limited to critical bug fixes.** \n\n*Checkout the [Graduation Criteria](#graduation-criteria) for moving the project to the next phase.*\n\n## Installation\n\nPerform the following installation steps on each participating cluster.\n\n- For multi-cluster service discovery and consumption, the controller should be installed on a minimum of 2 EKS clusters.\n- Participating clusters should be provisioned into a single AWS account, within a single AWS region.\n\n### Dependencies\n\n#### Network\n\n\u003e **The AWS Cloud Map MCS Controller for K8s provides service discovery and communication across multiple clusters, therefore implementations depend on end-end network connectivity between workloads provisioned within each participating cluster.** \n\n- In deployment scenarios where participating clusters are provisioned into separate VPCs, connectivity will depend on correctly configured  [VPC Peering](https://docs.aws.amazon.com/vpc/latest/peering/create-vpc-peering-connection.html), [inter-VPC routing](https://docs.aws.amazon.com/vpc/latest/peering/vpc-peering-routing.html), and Security Group configuration. The [VPC Reachability Analyzer](https://docs.aws.amazon.com/vpc/latest/reachability/getting-started.html) can be used to test and validate end-end connectivity between worker nodes within each cluster.\n- Undefined behavior may occur if controllers are deployed without the required network connectivity between clusters.\n\n#### Configure CoreDNS\n\nInstall the CoreDNS multicluster plugin into each participating cluster. The multicluster plugin enables CoreDNS to lifecycle manage DNS records for `ServiceImport` objects.\n\nTo install the plugin, run the following commands.\n\n```bash\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/samples/coredns-clusterrole.yaml\"\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/samples/coredns-configmap.yaml\"\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/samples/coredns-deployment.yaml\"\n```\n\n### Install Controller\n\nTo install the latest release of the controller, run the following commands.\n\n\u003e **_NOTE:_** AWS region environment variable can be _optionaly_ set like `export AWS_REGION=us-west-2` Otherwise the controller will infer region in the order `AWS_REGION` environment variable, ~/.aws/config file, then EC2 metadata (for EKS environment)\n\n```sh\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release\"\n```\n\n\u003e 📌 See [Releases](#Releases) section for details on how to install other versions.\n\nThe controller must have sufficient IAM permissions to perform required Cloud Map operations. Grant IAM access rights `AWSCloudMapFullAccess` to the controller Service Account to enable the controller to manage Cloud Map resources.\n\n## Usage\n\n### Configure `cluster.clusterset.k8s.io` and `clusterset.k8s.io`\n\n`cluster.clusterset.k8s.io` is a unique identifier for the cluster.\n\n`clusterset.k8s.io` is an identifier that relates to the `ClusterSet` in which the cluster belongs. \n\n```yaml\napiVersion: about.k8s.io/v1alpha1\nkind: ClusterProperty\nmetadata:\n  name: cluster.clusterset.k8s.io\nspec:\n  value: [Your Cluster identifier]\n---\napiVersion: about.k8s.io/v1alpha1\nkind: ClusterProperty\nmetadata:\n  name: clusterset.k8s.io\nspec:\n  value: [Your ClusterSet identifier]\n```\n\n**Example:**\n```yaml\napiVersion: about.k8s.io/v1alpha1\nkind: ClusterProperty\nmetadata:\n  name: cluster.clusterset.k8s.io\nspec:\n  value: my-first-cluster\n---\napiVersion: about.k8s.io/v1alpha1\nkind: ClusterProperty\nmetadata:\n  name: clusterset.k8s.io\nspec:\n  value: my-clusterset\n```\n\n### Export services\n\nThen assuming you already have a Service installed, apply a `ServiceExport` yaml to the cluster in which you want to export a service. This can be done for each service you want to export.\n\n```yaml\nkind: ServiceExport\napiVersion: multicluster.x-k8s.io/v1alpha1\nmetadata:\n  namespace: [Your service namespace here]\n  name: [Your service name]\n```\n\n**Example:** This will export a service with name *my-amazing-service* in namespace *hello*\n```yaml\nkind: ServiceExport\napiVersion: multicluster.x-k8s.io/v1alpha1\nmetadata:\n  namespace: hello\n  name: my-amazing-service\n```\n\n*See the `samples` directory for a set of example yaml files to set up a service and export it. To apply the sample files run the following commands.*\n\n```sh\nkubectl create namespace example\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/samples/example-deployment.yaml\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/samples/example-service.yaml\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/samples/example-serviceexport.yaml\n```\n\n### Import services\n\nIn your other cluster, the controller will automatically sync services registered in AWS Cloud Map by applying the appropriate `ServiceImport`. To list them all, run the following command.\n```sh\nkubectl get ServiceImport -A\n```\n\n## Releases\n\nAWS Cloud Map MCS Controller for K8s adheres to the [SemVer](https://semver.org/) specification. Each release updates the major version tag (eg. `vX`), a major/minor version tag (eg. `vX.Y`) and a major/minor/patch version tag (eg. `vX.Y.Z`). To see a full list of all releases, refer to our [Github releases page](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/releases).\n\n\u003e **_NOTE:_** AWS region environment variable can be _optionally_ set like `export AWS_REGION=us-west-2` Otherwise controller will infer region in the order `AWS_REGION` environment variable, ~/.aws/config file, then EC2 metadata (for EKS environment)\n\nThe following command format is used to install from a particular release.\n```sh\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release[?ref=*git version tag*]\"\n```\n\nRun the following command to install the latest release.\n```sh\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release\"\n```\n\nThe following example will install release v0.1.0.\n```sh\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release?ref=v0.1.0\"\n```\n\nWe also maintain a `latest` tag, which is updated to stay in line with the `main` branch. We **do not** recommend installing this on any production cluster, as any new major versions updated on the `main` branch will introduce breaking changes.\n\nTo install from `latest` tag run the following command.\n```sh\nkubectl apply -k \"github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_latest\"\n```\n\n## Graduation Criteria\n\n### Alpha -\u003e Beta Graduation\n* Implement the [resiliency milestone](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/milestone/3).\n\n### Beta -\u003e GA Graduation\n* Scalability/performance testing.\n* Implement the [observability and deployment milestone](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/milestone/6).\n* [KEP-1645: Multi-Cluster Services API](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/1645-multi-cluster-services-api) and [KEP-2149: ClusterId for ClusterSet identification](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid) are Beta or GA. \n\n## Slack community\nWe have an open Slack community where users may get support with integration, discuss controller functionality and provide input on our feature roadmap. https://awsappmesh.slack.com/#k8s-mcs-controller\nJoin the channel with this [invite](https://join.slack.com/t/awsappmesh/shared_invite/zt-dwgbt85c-Sj_md92__quV8YADKfsQSA).\n\n## Contributing\n`aws-cloud-map-mcs-controller-for-k8s` is an open source project. See [CONTRIBUTING](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/blob/main/CONTRIBUTING.md) for details.\n\n## License\n\nThis project is distributed under the\n[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0),\nsee [LICENSE](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/blob/main/LICENSE) and [NOTICE](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/blob/main/NOTICE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-cloud-map-mcs-controller-for-k8s","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Faws-cloud-map-mcs-controller-for-k8s","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-cloud-map-mcs-controller-for-k8s/lists"}