AWS Cloud Map MCS Controller for K8s

Introduction

AWS Cloud Map multi-cluster service discovery for Kubernetes (K8s) is a controller that implements existing multi-cluster services API that allows services to communicate across multiple clusters. The implementation relies on AWS Cloud Map for enabling cross-cluster service discovery.

See the demo from AWS Container Day x KubeCon!

Usage

⚠ There must exist network connectivity (i.e. VPC peering, security group rules, ACLs, etc.) between clusters: Undefined behavior may occur if controller is set up without network connectivity between clusters.

Setup clusters

First, install the controller with latest release on at least 2 AWS EKS clusters. Nodes must have sufficient IAM permissions to perform CloudMap operations.

NOTE: AWS region environment variable should be set like export AWS_REGION=us-west-2

kubectl apply -k "github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release"

📌 See Releases section for details on how to install other versions.

Export services

Then 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.

kind: ServiceExport
apiVersion: multicluster.x-k8s.io/v1alpha1
metadata:
  namespace: [Your service namespace here]
  name: [Your service name]

Example: This will export a service with name my-amazing-service in namespace hello

kind: ServiceExport
apiVersion: multicluster.x-k8s.io/v1alpha1
metadata:
  namespace: hello
  name: my-amazing-service

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

kubectl create namespace example
kubectl apply -f https://raw.githubusercontent.com/aws/aws-cloud-map-mcs-controller-for-k8s/main/samples/example-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/aws/aws-cloud-map-mcs-controller-for-k8s/main/samples/example-service.yaml
kubectl apply -f https://raw.githubusercontent.com/aws/aws-cloud-map-mcs-controller-for-k8s/main/samples/example-serviceexport.yaml

Import services

In your other cluster, the controller will automatically sync services registered in AWS Cloud Map by applying the appropriate ServiceImport. To list them all, run

kubectl get ServiceImport -A

Releases

AWS Cloud Map MCS Controller for K8s adheres to the SemVer 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.

NOTE: AWS region environment variable should be set like export AWS_REGION=us-west-2

To install from a release run

kubectl apply -k "github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release[?ref=*git version tag*]"

Example to install latest release

kubectl apply -k "github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release"

Example to install v0.1.0

kubectl apply -k "github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release?ref=v0.1.0"

We 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.

To install from latest tag run

kubectl apply -k "github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_latest"

Integration testing

The end-to-end integration test suite can be run locally to validate controller core functionality. This will provision a local Kind cluster and build and run the AWS Cloud Map MCS Controller for K8s. The test will verify service endpoints sync with AWS Cloud Map. If successful, the suite will then de-provision the local test cluster and delete AWS Cloud Map namespace aws-cloud-map-mcs-e2e along with test service and service instance resources.

make integration-suite

Contributing

aws-cloud-map-mcs-controller-for-k8s is an open source project. See CONTRIBUTING for details.

License

This project is distributed under the Apache License, Version 2.0, see LICENSE and NOTICE for more information.