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 with Istio/Envoy.

We recommend adding the Akita Agent as a sidecar in your deployment template. However, if you are using Kubernetes v1.18+ and have Kubernetes alpha features enabled, you can attach the Akita Agent as a sidecar directly to a running container.

🚧

Per-container monitoring

When deploying the Akita Agent in a sidecar, it can only monitor other containers in the same pod. You will need to configure a sidecar for each pod you wish to monitor.

Installing the Akita Agent as a sidecar

To get the Akita Agent running in a single Kubernetes service, you will:

1. Meet the prerequisites
2. Create an Akita Project
3. Generate an API key for the Akita Agent
4. Add your Akita credentials as a Kubernetes secret
5. Add Akita Agent as a sidecar in a deployment template
6. Apply the deployment template
7. Verify that the Akita Agent is working

When you’ve completed the steps, you can also look at what is needed to scale your Akita deployment.

Prerequisites

🚧

Akita Account Required

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

Your Kubernetes service must:

• have access to the public internet
• use unencrypted HTTP
• be able to be restarted, as the installation process will cause a restart

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.

Add secret

You will need to add a base64-encoded version of the Akita API key ID and key secret you created in a previous step to a YAML file.

You can encode your key and key secret by inserting them in the following commands:

$ echo -n $AKITA_API_KEY_ID | base64
$ echo -n $AKITA_API_KEY_SECRET | base64 -w 0

Then create or edit a YAML file to include the below using the encoded key ID and key secret values:

apiVersion: v1
kind: Secret
metadata:
  name: akita-secrets
type: Opaque
data:
  api-key-id: <base64-encoded key id>
  api-key-secret: <base64-encoded key secret>

Then run kubectl apply to create or update the secret.

If you run the deployment in a namespace, the secret must be in the same namespace as your deployment.

Add sidecar

Find the file that describes the deployment of the service you want to monitor, or a standalone definition of a pod. It will have a section called “template” that describes the containers to run inside the pod, that will look something like this:

...
  template:
    metadata:
      labels:
        app: my-example-app
    spec:
      containers:
      - name: app
        image: bfwaterdog/app-example
        ports:
        - containerPort: 5000

You will then edit this file to add a second container in the same spec that specifies akitasoftware/cli, along with its command-line arguments. You will need to include the following:

• Replace your-project-name with the Akita Project name you created earlier.
• Do not edit the API key ID and secret section, as those will be pulled from the secret you created in the previous step.

Your new section should look like this:

...
      - name: akita
        image: akitasoftware/cli:latest
        env:
          - name: AKITA_API_KEY_ID
            valueFrom:
              secretKeyRef:
                name: akita-secrets
                key: api-key-id
          - name: AKITA_API_KEY_SECRET
            valueFrom:
              secretKeyRef:
                name: akita-secrets
                key: api-key-secret
        lifecycle:
          preStop:
            exec:
              command: ["/bin/sh", "-c", "AKITA_PID=$(pgrep akita) && kill -2 $AKITA_PID && tail -f /proc/$AKITA_PID/fd/1"]
        args:
          - apidump
          - --project
          - your-project-name
        securityContext:
          capabilities:
            add: ["NET_RAW"]

Add template

Run kubectl apply to create the new deployment or modify an existing one.

If you want to create an ephemeral pod using Akita as a sidecar, run kubectl run.

Verify

Find the pod that was created in response to the change, and run the following command to see the Akita Agent output.

kubectl logs <pod name> akita

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.

Adding an Akita Agent sidecar to a running Kubernetes pod

Below are instructions for starting a new ephemeral container with an Akita Agent sidecar in an existing Kubernetes pod.

📘

Requirements

• Kubernetes v1.18+
• Alpha features in Kubernetes enabled
• kubectly debug specifically must be enabled

To get the Akita agent running as a sidecar in a new ephemeral container in a single Kubernetes service, you will:

1. Meet the prerequisites
2. Create an Akita Project
3. Generate an API key for the Akita Agent
4. Attach the Akita Agent as a sidecar
5. Verify that the Akita Agent is working

Thanks to Bruno Felix, who experimented with this method and provided us with his examples!

Prerequisites

You’ll need to be in our beta.

Your Kubernetes service must:

• have access to the public internet
• use unencrypted HTTP
• be version 1.18 or higher
• have alpha features enabled
• have kubectly debug enabled

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.

Attach Agent

To attach the Akita Agent as a sidecar:

1. Identify the name of the pod that is running the app or service you want Akita to monitor.
2. Identify the port the pod is running on.
3. Run the below command, inserting your Akita Project name, API key ID, and key secret.

kubectl debug -it myservice-xyzabc \
   --image=akitasoftware/cli:latest \
   --env="AKITA_API_KEY_ID=$AKITA_API_KEY_ID" \
   --env="AKITA_API_KEY_SECRET=$AKITA_API_KEY_SECRET" \
   -- akita apidump --project my-project-name

Verify

If the command was successful, you will see the akita apidump output. Use Ctrl+C to stop the trace as if you were running normally from the command line.

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.