flame_k8s

# FlameK8s

Kubernetes backend integration for [FLAME](https://github.com/phoenixframework/flame).

This library implements `FLAME.Backend` and delegates runner lifecycle to
Kubernetes through the `FlameRunner` and `FlamePool` custom resources managed
by the flame-k8s operator.

## Installation

Add the dependency to your `mix.exs`:

```elixir
def deps do
  [
    {:flame_k8s, "~> 0.1.0"}
  ]
end
```

## Configure Your Application

Enable the backend in your runtime configuration (usually in production):

```elixir
if config_env() == :prod do
  config :flame, :backend, FLAME.K8sBackend
  config :flame, FLAME.K8sBackend,
    log: :debug,
    boot_timeout: 30_000
end
```

## How It Works

1. Your app invokes FLAME work (`FLAME.call/3`, `FLAME.cast/3`).
2. `FLAME.K8sBackend` creates a `FlameRunner` custom resource.
3. The operator reconciles `FlameRunner` and creates the runner pod.
4. The runner pod connects back via distributed Erlang.
5. Work executes remotely and runner resources are cleaned up.

## Install The Operator

This backend requires the operator and CRDs installed in the target cluster.

Use the release assets published with each GitHub release. No repository clone is required.

Latest release:

```bash
curl -fsSL https://github.com/eigr-labs/flame-k8s-operator/releases/latest/download/install-operator.sh \
  -o /tmp/install-operator.sh
bash /tmp/install-operator.sh --namespace flame
```

Pinned release tag:

```bash
curl -fsSL https://github.com/eigr-labs/flame-k8s-operator/releases/download/v0.1.2/install-operator.sh \
  -o /tmp/install-operator.sh
bash /tmp/install-operator.sh --tag v0.1.2 --namespace flame
```

This installer downloads the release bundle, creates or reuses the Erlang cookie secret,
waits for CRDs to be established, and applies the operator manifests in the target namespace.

If you need to apply individual YAML manifests directly, use the release asset files instead of cloning the repository.

## Generate A FLAME-Ready Deployment

The library includes a mix task that generates a Deployment with the FLAME
annotations already filled in.

```bash
mix flame.gen.deployment \
  --name flame-parent-example \
  --namespace default \
  --image ghcr.io/eigr-labs/flame-parent-example:latest
```

Optional flags include `--pool-config-ref`, `--otp-app`, `--cookie-secret-ref`,
and `--runner-termination-timeout`.

## Apply Example CR Instances

After installing the operator, apply example resources:

```bash
kubectl apply -f examples/crds/flamepool-apply.yaml
kubectl apply -f examples/flame_example/.k8s/deployment.yaml
```

The direct `FlameRunner` manifest is still available for manual CR testing, but
the normal application flow is driven by the annotated Deployment and the
mutating webhook.

Inspect status:

```bash
kubectl get flamepools -A
kubectl get flamerunners -A
```

## Environment Notes

- In cluster, backend auth uses service account credentials.
- Outside cluster, backend reads kubeconfig from `KUBECONFIG` (first path when
  multiple are provided), with fallback to `~/.kube/config`.
- Backend includes `FLAME_NODE_BASE` in generated `FlameRunner` env so runner
  pods can derive `RELEASE_NODE` as `$(FLAME_NODE_BASE)@$(POD_IP)`.