AWS ECS

• 1. Setup the environment
• 3. Run Kuma DP

Before continuing with the next steps, make sure to have AWS CLI installed (opens new window) and .

The AWS CloudFormation scripts described in this page are parametrized, and we suggest to take a deeper look at those parameters before deploying Kuma.

Also, the scripts are leveraging AWS Fargate on top of AWS ECS.

First we need to download the scripts that will setup our environment. The scripts are stored in the main GitHub repository of Kuma in the examples folders (opens new window).

To download the scripts locally:

Then we can proceed to install a VPC:

$ aws cloudformation deploy \
    --capabilities CAPABILITY_IAM \
    --stack-name kuma-vpc \

We can run Kuma in either standalone or multi-zone mode:

To deploy the kuma-cp stack in standalone mode we can execute:

$ aws cloudformation deploy \
    --capabilities CAPABILITY_IAM \
    --stack-name kuma-cp \
    --template-file kuma-cp-standalone.yaml \
    --parameter-overrides AllowedCidr=0.0.0.0/0

To learn more, read about the .

Multi-zone mode is perfect when running one deployment of Kuma that spans across multiple Kubernetes clusters, clouds and VM environments under the same Kuma deployment. This mode also supports hybrid Kubernetes + VMs deployments.

To run Kuma in multi-zone mode, we must install our global control plane first:

$ aws cloudformation deploy \
    --capabilities CAPABILITY_IAM \
    --stack-name kuma-cp-global \
    --template-file kuma-cp-global.yaml \
    --parameter-overrides AllowedCidr=0.0.0.0/0

A Kuma ingress data plane proxy is needed in each zone to enable cross-zone communication. Like every other data plane proxy type, it also needs a if the data plane proxy and control plane communication is secured. Learn more about DP and CP security.

We can provision a token with the following command:

$ ssh root@<kuma-cp-remote-ip> "wget --header='Content-Type: application/json' --post-data='{\"mesh\": \"default\", \"type\": \"ingress\"}' -qO- http://localhost:5681/tokens"

And finally deploy the ingress data plane proxy:

$ aws cloudformation deploy \
    --capabilities CAPABILITY_IAM \
    --stack-name ingress \
    --template-file remote-ingress.yaml \
    --parameter-overrides \

To learn more, read the .

The examples described above will allow access to the to all IPs. In production we should change --parameter-overrides AllowedCidr=0.0.0.0/0 to point to a more restricted subnet that will be used to administer the Kuma control plane.

Security Note

Explore kuma-cp.yaml and kuma-cp-remote.yaml to set the appropriate ServerCert and ServerKey parameters. The examples above include pre-generated server certificate and key that are not suitable for production usage, therefore we recommend overriding these values with properly generated certificates with the DNS name in place.

Removing the Kuma control plane

To remove the kuma-cp stack use (similarly for kuma-cp-global and kuma-cp-remote) we can execute:

$ aws cloudformation delete-stack --stack-name kuma-cp

Before moving forward with the next steps, please write down the kuma-cp IP address accordingly as we will need its value to continue with the installation.

Kuma DNS

The services within the Kuma mesh are exposed through their names (as defined in the kuma.io/service tag) in the . In the default workload example presented in these instructions, our services will be available on httpbin.mesh.

Run the following command to create the necessary forwarding rules in AWS Route53 and to leverage the integrated service discovery in kuma-cp:

The <kuma-cp-ip> value (retrieved from the AWS ECS web console or CLI) can be either the public or the private IP of kuma-cp. In multi-zone deployments, we will use the remote control plane IP address.

While we have installed the Kuma control plane successfully, we still need to start kuma-dp alongside our workloads. The workload.yaml file provided in the examples is an AWS CloudFormation template that showcases how we can kuma-dp as a sidecar container alongside an arbitrary, single port, service container in AWS ECS.

Generate the DP token

In order to run the kuma-dp container, we have to issue an access token. The latter can be generated using the Admin API of the Kuma CP. Learn more about .

In this example we’ll show the simplest way to generate a new data plane proxy token by executing the following command on the same machine where kuma-cp is running (although this is only one of many ways to generate the data plane proxy token):

Where <kuma-cp-ip> is the IP address of kuma-cp as it shows in AWS ECS. When asked, supply the default password root.

The generated token is valid for all data plane proxies in the default mesh. Kuma also allows to generate data plane proxy token in a more restrictive way and bound to its name or tags (opens new window).

Kuma allows much more advanced and secure ways to expose the /tokens endpoint. The full procedure is described in the following security documentation: , user to control plane communication (opens new window).

Finally, retrieve the data plane proxy token generated in the previous step and use it in the following <token> placeholder:

$ aws cloudformation deploy \
    --capabilities CAPABILITY_IAM \
    --stack-name workload \
    --template-file workload.yaml \
    --parameter-overrides \
      DesiredCount=2 \
      DPToken="<token>"

$ aws cloudformation deploy \
    --capabilities CAPABILITY_IAM \
    --stack-name workload \
    --template-file workload.yaml \
    --parameter-overrides \
    DesiredCount=2 \
    DPToken="<token>" \

The CPAddress value is the default value provided in the examples, however this should be changed to whatever matches your deployment.

By doing so, we are deploying two instances of the httpbin container with a sidecar running alongside each one of them.

The workload template has many parameters so that it can be customized with different workload images, service name and port, and more. You can find more information by looking at the template itself.

Congratulations! You have successfully installed Kuma on AWS ECS 🚀.