Deploy the Distributed Cloud AIP Containerized Agent

Overview

Containers are a standardized unit of software. A container packages an application’s code, configurations, and dependencies into a single unit that can be quickly and reliably deployed to any environment that supports containers, regardless of the underlying operating system (OS).

The F5 Distributed Cloud App Infrastructure Protection (AIP) Agent can be deployed as a container. You can deploy the containerized Agent on any supported Linux distribution in Docker-based container environments. The Agent deploy script includes the configuration file.

Since customers deploy the containerized Agent in containerized environments, Distributed Cloud AIP does not support direct commands to the Agent. Do not use the following commands:

• Agent 3.x and 2.x series:
  • sudo tsagent start
  • sudo tsagent stop
  • sudo tsagent restart
  • sudo tsagent config

Notes

• After deployment, customers only access the containerized Agent directly to gather logs for support requests. Container restarts, starts, and stops can be performed outside of the container, through the orchestration layer. For more information on the orchestration level, see Distributed Cloud AIP Kubernetes DaemonSet.
• The containerized Agent is a standalone Agent and cannot be run side-by-side on the host with another Distributed Cloud AIP Agent.
• Securing AWS Elastic Container Search (ECS) workloads requires the Distributed Cloud AIP host-based Agent. For more information, see FAQ: How do I secure my AWS ECS workload with Distributed Cloud AIP?
• If you want to constrain Agent memory and CPU utilization, you can configure the Agent to use Self-Control to further conserve resources. For more information, see Self-Control Agent Resource Utilization.

System Consideration for the Containerized Agent

To optimize performance of your containerized Agent, we recommend configuring your host following these guidelines:

• Allocate enough host memory to run a 256 mebibyte (MiB) application.
  • It can be increased to 384MiB or more for performance as necessary.

  Tip

  Specify limits for CPU and memory values the Agent can utilize. For more information about the minimum and maximum ranges for these values, see:

  • Docker Guidelines
  • Kubernetes Guidelines
• Ability to disable auditd on the host to ensure all Agent services run, including the Audit Collection Service.
  • From the Command Line, enter the following commands to stop and disable auditd:

    sudo systemctl stop auditd
    sudo systemctl disable auditd

• Configure outbound network connectivity over port 443.
• Allow the container to mount a file system on the host.

What Information Does the Containerized Agent Collect?

The containerized Agent collects the same information collected by the non-containerized Agent.

Additionally, the Docker rule set is recommended to be added for the containerized Agent.

How Do I Deploy the Containerized Agent?

Prerequisites

• Access to DockerHub
• Docker installed and running

  Note

  If Docker is not installed or is not running, then any attempt to start the Agent will result in the Agent exiting and an error message that states: “If problems persist, please disable tscontainers.”.

• Access to the Distributed Cloud AIP containerized Agent
• Access to the Distributed Cloud AIP console

Warning

There is a known Linux issue where the default auditd process only allows one connection for audit socket control. As a result, any applications that use auditd conflict with the Distributed Cloud AIP Agent over access to socket control. This can cause customer issues for several reasons:

• The customer uses non-Distributed Cloud AIP audit rules to process logs.
• The customer sends all logs to an SIEM or other log aggregator.
• The customer deploys non-Distributed Cloud AIP agents that need access to auditd data.

For information about a workaround that addresses this issue, see FAQ: Workaround for the Known Linux Limitation with auditd.

Tip

Distributed Cloud AIP recommends using side-by-side windows – one browser window for DockerHub and one window for the Command Line – to deploy the Agent.

Docker Restart Policies and the Distributed Cloud AIP Agent

Docker provides restart policies to control whether your containers start automatically when they exit, or when Docker restarts. Restart container policies can be used in conjunction with containerized Agent deployments.

To configure the restart policy for a container, use the --restart flag when using the docker run command.

• --restart no: Indicates the container will not automatically be restarted. Specify this command to be immediately alerted if you are using a monitoring solution, and if the Distributed Cloud AIP Agent and the related container are no longer present on the host.
• --restart always: Indicates the container will always be restarted if it stops. Specify this command to prevent the Distributed Cloud AIP Agent and the related container from being terminated when automatic updates are run.

Note

Distributed Cloud AIP does not have a recommended default restart policy.

For more information, see Docker restart policies.

Deploy Containerized Agent for 3.x Series

Note

Beginning with Linux Containerized Agent version 2.3.3, the Distributed Cloud AIP Agent supports both ARM 64-bit and x86 64-bit architecture. The multi-architecture Agent tag allows you to pull the correct container Agent for your environment's underlying system architecture. However, as the Agent only pulls the target architecture's image, if you tag or push the container Agent to your own container registry, rather than directly from Docker, then you will only push the single architecture that you pulled.

To recreate the multi-architecture tag for a private registry, we recommend pulling the architecture-specific images and using the docker manifest command to create your own internal multiarchitecture-image.

1. Open the Command Line.
2. Paste the deploy command from threatstack/ts-docker2, append the following, and press ENTER: :latest

   Example:

   docker pull threatstack/ts-docker2:latest
3. To find your image ID, type the following command and press ENTER: docker images

   Note

   Running this command displays a list of docker repositories, along with their respective IMAGE ID.

4. Copy the image ID.
5. The following command is the deploy command for the container. It should be entered as one block. Type or copy and paste the following command and press ENTER:

   export DEPLOY_KEY=<your deploy key> 
   sudo docker run -it -d \ 
   -e THREATSTACK_SETUP_ARGS="-deploy-key ${DEPLOY_KEY} -ruleset 'Base Rule Set, Docker Rule Set'" \ 
   -e THREATSTACK_CONFIG_ARGS="log.level info" \ 
   --name=ts-docker \ 
   --network=host \ 
   --pid=host \ 
   --security-opt=apparmor=unconfined \ 
   --cap-add=AUDIT_CONTROL \ 
   --cap-add=SYS_ADMIN \ 
   --cap-add=SYS_PTRACE \ 
   --cap-add=SYS_NICE \ 
   --cap-add=SYS_RESOURCE \ 
   --cap-add=IPC_LOCK \ 
   --cap-add=NET_RAW \
   -v /:/threatstackfs/:ro \ 
   -v /sys/kernel/debug:/sys/kernel/debug \
   <paste IMAGE ID here>

   Replace <your deploy key> with your deployment key.

   Replace <paste your IMAGE ID here> with your Image ID you copied in step 4.

   Note

   The apparmor:unconfined parameter enables additional Distributed Cloud AIP Agent network syscall event enrichment. Specifically, it includes information about the local IP and port. If you do not want to receive this information, then you can delete this line from the command.

   The containerized Agent successfully deploys to the Docker environment.

6. Confirm the containerized Agent deployed correctly.
   1. Log into Distributed Cloud AIP and view the new server.
   2. Log into the container and run the following command:

      sudo docker exec <container name> tsagent status

      Replace <container name> with the container name specified in step 5 for --name.

Deploy Containerized Agent for 2.x Series

Note

Beginning with Linux Containerized Agent version 2.3.3, the Distributed Cloud AIP Agent supports both ARM 64-bit and x86 64-bit architecture. The multi-architecture Agent tag allows you to pull the correct container Agent for your environment's underlying system architecture. However, as the Agent only pulls the target architecture's image, if you tag or push the container Agent to your own container registry, rather than directly from Docker, then you will only push the single architecture that you pulled.

To recreate the multi-architecture tag for a private registry, we recommend pulling the architecture-specific images and using the docker manifest command to create your own internal multiarchitecture-image.

1. Open the Command Line.
2. Paste the deploy command from threatstack/ts-docker2, append the following, and press ENTER: :latest

   Example:

   docker pull threatstack/ts-docker2:latest
3. To find your image ID, type the following command and press ENTER: docker images

   Note

   Running this command displays a list of docker repositories, along with their respective IMAGE ID.

4. Copy the image ID.
5. The following command is the deploy command for the container. It should be entered as one block. Type or copy and paste the following command and press ENTER:

   $ export DEPLOY_KEY=<your deploy key>
   $ sudo docker run -it -d \
   -e THREATSTACK_SETUP_ARGS="--deploy-key ${DEPLOY_KEY} --ruleset 'Base Rule Set, Docker Rule Set'" \
   -e THREATSTACK_CONFIG_ARGS="enable_containers 1" \
   --name=ts-docker \
   --network=host \
   --pid=host \
   --security-opt=apparmor:unconfined \
   --cap-add=AUDIT_CONTROL \
   --cap-add=SYS_ADMIN \
   --cap-add=SYS_PTRACE \
   --cap-add=SYS_NICE \
   -v /:/threatstackfs/ \
   -v /run/containerd/containerd.sock:/run/containerd/containerd.sock \
   -v /var/run/docker/containerd/docker-containerd.sock:/var/run/docker/containerd/docker-containerd.sock \
   -v /var/run/docker.sock:/var/run/docker.sock \
   <paste IMAGE ID here>

   Replace <your deploy key> with your deployment key.

   Replace <paste your IMAGE ID here> with your Image ID you copied in step 4.

   Note

   The apparmor:unconfined parameter enables additional Distributed Cloud AIP Agent network syscall event enrichment. Specifically, it includes information about the local IP and port. If you do not want to receive this information, then you can delete this line from the command.

   The containerized Agent successfully deploys to the Docker environment.

6. Confirm the containerized Agent deployed correctly.
   1. Log into Distributed Cloud AIP and view the new server.
   2. Log into the container and run the following command:

      sudo docker exec <container name> tsagent status

      Replace <container name> with the container name specified in step 5 for --name.