# ansible-role-kraken-bot

Deploys the current Kraken Trader container as a continuously running Kubernetes
Deployment. The role creates a namespace, PVC, ConfigMap, Kubernetes Secret,
Deployment, and internal ClusterIP Service. It does not use a CronJob.

The Deployment is fixed at one replica: multiple pods could place duplicate trades
and cannot safely share the SQLite state file.

## Requirements

- Ansible 2.14 or newer.
- The `kubernetes.core` collection and Python `kubernetes` package on the Ansible
  controller. Install the collection with `ansible-galaxy collection install -r requirements.yml`.
- A configured Kubernetes context, or set `kraken_bot_kubeconfig` and optionally
  `kraken_bot_kube_context`.
- A published app image and dashboard password at least 16 characters long.

## Example playbook

```yaml
- name: Deploy Kraken Trader
  hosts: localhost
  gather_facts: false
  vars:
    kraken_bot_image: ghcr.io/example/kraken-trader:2.0.0
    kraken_bot_dashboard_password: "{{ vault_kraken_dashboard_password }}"
    kraken_bot_api_key: "{{ vault_kraken_api_key | default('') }}"
    kraken_bot_api_secret: "{{ vault_kraken_api_secret | default('') }}"
    kraken_bot_config:
      poll_interval_seconds: 60
      snapshot_interval_seconds: 300
      fee_rate: 0.004
      slippage: 0.0005
      min_trade_fraction: 0.01
      strategies:
        - id: hodl-btc
          type: buy_and_hold
          mode: paper
          starting_capital: 1000
          pairs: [XBTUSD]
          interval: 1440
  roles:
    - ansible-role-kraken-bot
```

Store passwords and Kraken credentials in Ansible Vault or an external secret
manager. Do not commit plaintext credentials to playbooks or inventory.

## Variables

| Variable | Default | Description |
|---|---|---|
| `kraken_bot_image` | required | Full published image reference, preferably pinned to a version or digest. |
| `kraken_bot_namespace` | `kraken-trader` | Namespace to create and deploy into. |
| `kraken_bot_name` | `kraken-trader` | Resource name prefix. |
| `kraken_bot_dashboard_password` | required | Dashboard Basic Auth password (minimum 16 characters). |
| `kraken_bot_dashboard_username` | `admin` | Dashboard Basic Auth username. |
| `kraken_bot_api_key` / `kraken_bot_api_secret` | empty | Kraken credentials. Read-only keys display account values; live trading needs order permission. Never enable withdrawals. |
| `kraken_bot_live_trading_enabled` | `false` | Explicit live-trading guard. Live mode requires both Kraken credentials. |
| `kraken_bot_config` | paper `buy_and_hold` example | Full application `strategies.yaml` content as a mapping. |
| `kraken_bot_storage_size` | `1Gi` | Persistent volume request. |
| `kraken_bot_storage_class` | cluster default | Optional storage class. |
| `kraken_bot_service_type` | `ClusterIP` | Keep internal unless adding a secured ingress. |
| `kraken_bot_kubeconfig` | current context | Optional kubeconfig path. |
| `kraken_bot_kube_context` | current context | Optional kubeconfig context. |
| `kraken_bot_image_pull_policy` | `IfNotPresent` | Kubernetes image pull policy. |
| `kraken_bot_log_level` | `INFO` | Application log level. |

The role rejects multiple replicas, short or missing dashboard passwords, and
live strategies unless live trading is explicitly enabled and credentials are
present. Trading remains in paper mode by default.

## Network and secrets

The Service is `ClusterIP`; the dashboard requires HTTP Basic authentication.
Use TLS at any ingress or reverse proxy; do not expose Basic Auth over plain HTTP.
`/healthz` is unauthenticated for Kubernetes probes. Kubernetes Secret values are
stored in etcd, so configure encryption at rest and restrict namespace access.
Secret rotation requires restarting the Deployment so environment variables
refresh.

## Configuration updates

Re-run the role after editing `kraken_bot_config`. A checksum annotation rolls
pods when the strategy config changes. The SQLite database remains on the PVC;
changing a strategy ID creates a separate portfolio rather than resetting state.

## License

BSD-3-Clause