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:**

   ```bash
   cp inventory.yml.sample inventory.yml
   ```

2. **Edit inventory with your hosts and configuration:**

   ```yaml
   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:**

   ```bash
   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

```bash
systemctl status zastava-agent
```

### View Logs

```bash
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 |

```bash
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:

   ```yaml
   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:

```bash
# 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
```