Kubernetes

Automatic installation of the Spyderbat AWS Agent on a Kubernetes Cluster

This guide provides detailed instructions on how to deploy the Spyderbat AWS Agent on a Kubernetes cluster. In a cluster deployment, the AWS Agent runs as a single-pod StatefulSet.

The most straightforward option is to run the AWS Agent on an EKS cluster within the AWS account that you want to monitor. In this case, the required configuration is minimal, and the deployment process is streamlined. This scenario is described in this guide.

More advanced configurations are also possible:

• The agent can poll information from another AWS account, or you can deploy a Helm chart to monitor multiple AWS accounts within a single Helm installation. This requires configuring additional IAM roles to be assumed.

• The Spyderbat registration key can be managed in AWS Secrets Manager if your organization uses Secrets Manager as the standard secret management technology for cluster workloads.

For more details on these configurations, please consult the AWS Agent Configuration Guide for Helm.

Prerequisites

Before deploying the Spyderbat AWS Agent on an AWS EKS cluster, ensure you have the following prerequisites in place:

1. Outbound Network Access: The cluster you’re installing Spyderbat's AWS Agent on must have outbound access on port 443 to https://orc.spyderbat.com.

2. Kubectl and Helm: Install Kubectl and Helm clients, and configure Kubectl for the cluster where you want to install the agent.

3. AWS Account: The cluster the agent is deployed on must reside in the AWS account that you wish to monitor.

4. IAM Role: Create an IAM Role that will be associated with the service account used by the AWS Agent.

   • Role Permissions: The role must have the following permissions attached:

     • EC2: ec2:Describe*

     • EKS: eks:List*, eks:Describe*

     • IAM Roles and Policies: iam:Get*, iam:List*, iam:Put*

     • STS: sts:AssumeRole, sts:AssumeRoleWithWebIdentity

     • Secrets Manager (Optional): Access to the ARN of the configured secret for the registration key.

   • Role Trust Policy: The IAM Role for the Spyderbat AWS Agent requires a trust policy that allows the Kubernetes Service Account associated with the AWS Agent to assume the role. Below is the trust policy:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::<account-id>:oidc-provider/oidc.eks.<region>.amazonaws.com/id/<open-id-provider-id>"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringLike": {
             "oidc.eks.<region>.amazonaws.com/id/<open-id-provider-id>:aud": "sts.amazonaws.com",
             "oidc.eks.<region>.amazonaws.com/id/<open-id-provider-id>:sub": "system:serviceaccount:*:aws-agent"
           }
         }
       }
     ]
   }

   Note that <account-id>, <region>, and <open-id-provider-id> are dependent on your local deployment of the EKS cluster. Take note of the ARN of this role, as it will be an input for the Helm chart deployment.

   You do not need to create the Kubernetes service account associated with the role, as the Helm chart installation will handle that.

Installation with AWS Agent Helm Chart

Step 1 - Copy the Helm install command from the Spyderbat UI

• Log in to the Spyderbat UI

• Navigate to the Sources menu (top left)

• Click on the Add Source button, and select Install AWS Agent

Add AWS Agent Source

This will bring you to the following screen where you can click on the Helm tab to select installation using the Helm chart.

AWS Helm Install

In the input fields, enter the following:

• Cluster Name: The name of the cluster you are deploying to. This will help the AWS Agent associate itself with the cluster and facilitate recognition in the Cluster Health and Sources UI. This is not required but recommended.

• IAM Role ARN: Enter the ARN of the role you created earlier. This is a required field.

Upon entering the information, the UI will generate a command that you can use to start the installation. Copy the command. It will be similar to the following (your registration key will differ):

helm repo add awsagent https://spyderbat.github.io/aws_agent_helmchart/
helm repo update
helm install awsagent awsagent/awsagent \
  --set credentials.spyderbat_registration_key=<registrationKey> \
  --set spyderbat_orc_url=https://orc.kangaroobat.net \
  --set serviceAccount.awsRoleArn=<AWS IAM Role ARN> \
  --namespace spyderbat \
  --create-namespace \
  --set CLUSTER_NAME=<cluster-name>

Step 2 - Run the Helm Command

In your command-line shell, with Kubectl and Helm installed and configured to use the target cluster as the active context, paste the copied Helm command.

Step 3 - Validate the Installation

Check for any reported errors during the installation, and use the following command to validate that awsagent is installed:

helm list

Then use:

kubectl get all -n spyderbat

You should see a StatefulSet named awsagent-auto and an associated pod named awsagent-auto-0 running if the installation was successful.

To check the logs of the AWS Agent pod, use:

kubectl logs pod/awsagent-auto-0

Uninstalling the AWS Agent from Your Cluster

To remove the AWS Agent, use Helm uninstall:

helm list -n spyderbat
helm uninstall awsagent -n spyderbat

Advanced Configuration

There are various settings that can be customized to address specific needs. These can be achieved by using a custom values.yaml file or by using the --set option during Helm installation.

For more details on these settings, please consult the AWS Agent Configuration Guide for Helm.