Getting started with Akita is as simple as dropping our Agent into your service. Below are instructions for installing the Akita Agent as a sidecar in Amazon Fargate.

🚧

Akita Account Required

You must have an Akita account to use Akita. You can create an account here.

You will be configuring Fargate to run the Akita Agent as a sidecar in each container you deploy. To set up the Akita Agent you will:

1. Create an Akita Project
2. Generate an API key for the Akita Agent
3. Run the ECS Add command
4. Verify that the Akita Agent is working

Create a project

Log into the Akita App, and go to the Settings page.
Enter a project name and click "Create Project". We suggest naming the project after your app or deployment stack.

Give your project a name that's easy to remember – you'll need it later, when you start the Akita agent on the CLI.

Generate API key

On the same Settings page, locate and click the “API Keys” tab. Click the “Set up the Akita client” button. Copy your API key secret into your favorite password manager or somewhere else you can easily access it. Also note your API key, as you will need it later.

Run the ECS Add command

The Akita CLI has the capability to automate installation of the Akita agent in ECS. If you want to carry out these steps on the AWS console instead, or understand what the installation will be doing, see Modifying the task definition by hand below.

The easiest way to run the Akita CLI is via Docker. Your command like should look like this:

docker run --rm -it \
  -e AKITA_API_KEY_ID={key id} \
  -e AKITA_API_KEY_SECRET={key secret} \
  -v ~/.aws:/aws:ro \
  akitasoftware/cli:latest \
    ecs add --project {your project}

Use the ID and secret of the API key you created above, and the project name. The option -v ~/.aws:/aws:ro maps the directory containing your AWS credentials into the container so that the CLI can use them to perform actions on your behalf. (The necessary permissions are listed below.)

The CLI will interactively prompt you for several pieces of information, and query AWS to find out what is available.

1. Enter which profile's credentials to use. If you only have one in your .aws/credentials file, just hit enter. (The tool cannot list the available profiles, unfortunately.)
2. Select the region in which your ECS application runs.
3. From the list of task definitions, select the one which you want to monitor with Akita. The CLI will warn you if the Akita agent is already present.
4. From the list of services running that task definition, select the one to restart once Akita has been added to the task definition. This will cause Akita to start monitoring that service.

If at any point you make a mistake, just select "go back to previous step" or hit Ctrl+C to exit.

The CLI will show you the changes it intends to make; enter "Y" to proceed.

After you accept the proposed changes, the CLI will create a new revision of the task definition that you selected. The new revision will include the Akita agent as a sidecar, and leave all other settings unchanged. After the task definition has been updated, Akita will update the service you selected to use that task definition. Finally, the Akita CLI will monitor the status of the service to ensure that the new deployment which includes the Akita sidecar comes up correctly.

If the service does not start correctly, please contact us for help -- but, don't worry, the old task definition should still be running. You can simply delete the new task definition that was created by Akita; it will have an akita.software:created_by tag to help you identify it.

AWS Permissions needed

The Akita CLI needs access to the following permissions in order to install Akita in ECS. If the profile you selected lacks any of these permissions, the CLI output will show an error message with which action it was attempting to perform.

The AmazonECS_FullAccess policy provided by Amazon is a superset of these actions; you could add that entire policy as an easy way to ensure your permissions are sufficient, if they are not already.

Verify

In the Akita web console, check out the incoming data on the Model page. You should see a map of your API being generated as the Akita Agent gathers data.

Then check out the Metrics and Errors page to get real-time information on the health of your app or service.

If everything has been set up successfully, your Akita deployment will look like this:

Modifying the task definition by hand

If the Akita CLI fails to install the Akita agent, or you wish to install the agent by yourself, the installation can be performed using the AWS console. Start by going to the "Elastic Container Service" portion of the AWS web console and select the Task Definitions.

Add to task definition

Within the containerDefinitions section of your task, add a new section containing the Akita Docker image as shown below.
Fill in the workspace name and the API key that you created earlier.
Specify a logConfiguration section in order to see the output from the Akita Agent. Use the destination where you store your application logs, or store them separately.

...
"containerDefinitions": [
  ...
  {
        "name": "akita",
        "image": "public.ecr.aws/akitasoftware/akita-cli:latest",
        "entryPoint": ["/akita", "apidump", "--project", "{project name}"],
        "environment" : [
             { "name" : "AKITA_API_KEY_ID", "value" : "{key id}" },
             { "name" : "AKITA_API_KEY_SECRET", "value" : "{key secret}" }
         ]
    }
]

The Akita token can also be stored in an AWS Secret instead.

If you edit the task definition from the console, the settings look like the following, though please note that the entry point is comma-separated on the console /akita,apidump,--project,{project_name}.

Give your project a name that's easy to remember – you'll need it later, when you start the Akita Agent on the CLI.

Generate API key

On the same Settings page, locate and click the “API Keys” tab. Click the “Set up the Akita client” button. Copy your API key secret into your favorite password manager or somewhere else you can easily access it. Also note your API key, as you will need it later.

Launch task definition

Once the task definition is saved, update your service as you ordinarily would. The Akita Agent will automatically start capturing traffic, and upload it for analysis.