git.stella-ops.org/deploy/ansible/README.md

Zastava Agent Ansible Deployment

Ansible playbook for deploying StellaOps Zastava Agent on VM/bare-metal hosts.

Prerequisites

• Ansible 2.10 or later
• Target hosts must have:
  • Docker installed and running
  • SSH access with sudo privileges
  • systemd as init system
  • Internet access (for downloading agent binaries) OR local artifact repository

Quick Start

1. Create inventory file:

   cp inventory.yml.sample inventory.yml
   

2. Edit inventory with your hosts and configuration:

   zastava_agents:
     hosts:
       your-host:
         ansible_host: 192.168.1.100
         ansible_user: ubuntu
     vars:
       zastava_tenant: your-tenant
       scanner_backend_url: https://scanner.internal
   

3. Run the playbook:

   ansible-playbook -i inventory.yml zastava-agent.yml
   

Configuration Variables

Required Variables

Variable	Description
zastava_tenant	Tenant identifier for multi-tenancy isolation
scanner_backend_url	URL of the Scanner backend service

Optional Variables

Variable	Default	Description
zastava_version	latest	Agent version to deploy
zastava_node_name	hostname	Override node name in events
zastava_health_port	8080	Health check HTTP port
docker_socket	/var/run/docker.sock	Docker socket path
zastava_log_level	Information	Serilog log level
scanner_backend_insecure	false	Allow HTTP backend (NOT for production)
download_base_url	https://releases.stellaops.org	Base URL for agent downloads

Advanced Variables

Variable	Description
zastava_extra_env	Dictionary of additional environment variables

Directory Structure

After deployment, the agent is installed with the following structure:

/opt/stellaops/zastava-agent/        # Agent binaries
/etc/stellaops/zastava-agent.env     # Environment configuration
/var/lib/zastava-agent/              # Data directory
/var/lib/zastava-agent/runtime-events/  # Event buffer (disk-backed)
/etc/systemd/system/zastava-agent.service  # systemd unit

Post-Deployment Verification

Check Service Status

systemctl status zastava-agent

View Logs

journalctl -u zastava-agent -f

Health Endpoints

Endpoint	Description
/healthz	Liveness probe - agent is running
/readyz	Readiness probe - agent can process events
/livez	Alias for liveness probe

curl http://localhost:8080/healthz
curl http://localhost:8080/readyz

Air-Gapped Deployment

For air-gapped environments:

1. Download agent tarball to a local artifact server

2. Set download_base_url to your local server:

   download_base_url: https://artifacts.internal/stellaops
   

3. Ensure the URL structure matches: {download_base_url}/zastava-agent/{version}/zastava-agent-linux-{arch}.tar.gz

Security Notes

Docker Socket Access

The agent requires read access to the Docker socket to monitor container events. The service runs as the zastava-agent user in the docker group.

See docs/modules/zastava/operations/docker-socket-permissions.md for security considerations and alternative configurations.

systemd Hardening

The service unit includes security hardening:

• NoNewPrivileges=true - Prevent privilege escalation
• ProtectSystem=strict - Read-only system directories
• PrivateTmp=true - Isolated /tmp
• ProtectKernelTunables=true - No kernel parameter modification
• Resource limits on file descriptors and memory

Troubleshooting

Agent Won't Start

1. Check Docker service: systemctl status docker
2. Verify Docker socket permissions: ls -la /var/run/docker.sock
3. Check agent logs: journalctl -u zastava-agent -e

Cannot Connect to Backend

1. Verify network connectivity: curl -I ${scanner_backend_url}/healthz
2. Check TLS certificates if using HTTPS
3. Ensure firewall allows outbound connections

Events Not Being Sent

1. Check event buffer directory permissions
2. Verify health endpoint returns healthy: curl localhost:8080/readyz
3. Check agent logs for connection errors

Uninstallation

To remove the agent:

# Stop and disable service
sudo systemctl stop zastava-agent
sudo systemctl disable zastava-agent

# Remove files
sudo rm -rf /opt/stellaops/zastava-agent
sudo rm -f /etc/stellaops/zastava-agent.env
sudo rm -f /etc/systemd/system/zastava-agent.service
sudo rm -rf /var/lib/zastava-agent

# Remove user
sudo userdel zastava-agent

# Reload systemd
sudo systemctl daemon-reload