To install and run Kuma on AWS ECS execute the following steps:

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

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.

# 1. Setup the environment

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:

curl --location --output - https://github.com/kumahq/kuma/archive/.tar.gz | tar -z --strip 3 --extract --file=- "./kuma-/examples/ecs/*yaml"

Then we can proceed to install a kuma VPC:

aws cloudformation deploy \
    --capabilities CAPABILITY_IAM \
    --stack-name kuma-vpc \
    --template-file kuma-vpc.yaml

# 2. Run Kuma CP

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

    The examples described above will allow access to the kuma-cp to all IPs. In production we should change --parameter-overrides AllowedCidr= 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-zone.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-zone) 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 .mesh DNS zone. 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:

    aws cloudformation deploy \
        --capabilities CAPABILITY_IAM \
        --stack-name kuma-dns \
        --template-file kuma-dns.yaml \
        --parameter-overrides \

    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 zone control plane IP address.

    We strongly recommend exposing the kuma-cp instances behind a load balancer, and use the IP of the load balancer as the DNSServer parameter value. This will ensure a more robust operation during upgrades, restarts and re-configurations.

    # 3. Run Kuma DP

    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 DP and CP security.

    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):

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

    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: data plane proxy authentication (opens new window), user to control plane communication (opens new window).

    # 4. Use Kuma

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

      By doing so, we are deploying two instances of the httpbin container with a kuma-dp 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.

      # 4. Quickstart

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

      In order to start using Kuma, it's time to check out the quickstart guide for Universal deployments. If you are using Docker you may also be interested in checking out the Kubernetes quickstart as well.

      Last Updated: 1/18/2022, 12:31:35 PM