diff --git a/versioned_docs/version-4.0.0/concepts/installation.md b/versioned_docs/version-4.0.0/concepts/installation.md index 5eedcb989..aee316557 100644 --- a/versioned_docs/version-4.0.0/concepts/installation.md +++ b/versioned_docs/version-4.0.0/concepts/installation.md @@ -111,6 +111,13 @@ keploy test --c "docker run -p : --name --ne +
+Install using Podman (Linux) + +Keploy also records and tests applications that run in rootful Podman on Linux, started with `podman run` or `podman compose`: see the **Podman** tab under Linux in [Installing Keploy](/docs/server/installation/). + +
+
Install Manually diff --git a/versioned_docs/version-4.0.0/concepts/platform-requirements.md b/versioned_docs/version-4.0.0/concepts/platform-requirements.md index 364b60460..dd0866a95 100644 --- a/versioned_docs/version-4.0.0/concepts/platform-requirements.md +++ b/versioned_docs/version-4.0.0/concepts/platform-requirements.md @@ -2,13 +2,14 @@ id: platform-requirements title: Keploy Platform-Specific Requirements sidebar_label: Platform-Specific Requirements -description: "Platform-specific requirements for Keploy on macOS, Windows, and Linux — native support on each, when to use Docker, Lima or WSL, and kernel version prerequisites." +description: "Platform-specific requirements for Keploy on macOS, Windows, and Linux — native support on each, when to use Docker, Podman, Lima or WSL, and kernel version prerequisites." tags: - linux - ebpf - installation - install keywords: + - podman - ebpf - installation - install @@ -35,3 +36,13 @@ Linux: Keploy runs natively on macOS (Apple Silicon / arm64) and Windows (x86‑64) — neither has eBPF, so it intercepts traffic in userspace on both, and neither needs `sudo` or Administrator. Natively on macOS and Windows, Keploy understands HTTP/HTTPS, MySQL and MongoDB calls; calls to other services — PostgreSQL, Redis, Kafka, gRPC and the like — are captured only as raw bytes and usually don't replay, so for an app that runs in containers or depends on them, use Docker. Docker, Lima (macOS) and WSL (Windows) remain supported alternatives, and WSL is the route on Windows on ARM. On an Intel Mac use Lima: the Docker route on macOS still runs the native CLI on the host, so it is Apple Silicon only too. Low-latency recording (`keploy record --low-latency`, or a Kubernetes Sidecar with `low_latency_mode`) and the Kubernetes DaemonSet agent capture with eBPF hooks that arm64 kernels support only from 6.4 (x86-64 kernels from 5.10). On an older arm64 kernel, record without low latency, and use Sidecar mode without `low_latency_mode` in Kubernetes. + +## Podman + +On Linux, Keploy records and tests applications that run in Podman as well as in Docker. In a `keploy record` or `keploy test` command, use `podman run` (or `podman compose`) where these docs use `docker run` (or `docker compose`). Run every other container command they give, such as creating the network, building the image or starting a database with `docker run -d`, as `sudo podman ...`, so that it is in the rootful Podman Keploy uses. See the **Podman** tab under Linux in [Installing Keploy](/docs/server/installation/) for the commands. + +- **Rootful Podman.** Keploy's agent loads eBPF, which a rootless Podman can't grant, so Keploy drives the rootful Podman and runs as root (it re-runs itself with `sudo` when it needs to). Images and containers you created with Podman without `sudo` aren't visible to it: build or pull your app's image with `sudo podman`. +- **Podman's API.** Keploy talks to Podman's Docker-compatible API. If the rootful `podman.socket` is enabled (`sudo systemctl enable --now podman.socket`) it uses that; otherwise it starts Podman's API service for the run and stops it when Keploy exits. +- **Compose.** `podman compose` (Podman 4.7 or later; Keploy is tested with Podman 5) works with Docker Compose v2 or later (`docker-compose`) as its compose provider, on a host that runs systemd: Podman runs healthchecks with systemd timers, and your app's service waits for the healthcheck of Keploy's agent service. podman-compose isn't supported. +- **Local Podman on Linux only.** A Podman set up as a podman-remote client (for example with `CONTAINER_HOST`, `CONTAINER_CONNECTION`, or `remote = true` in containers.conf) runs containers in another Podman service, but Keploy's agent runs in the local rootful Podman, so Keploy refuses it. On macOS and Windows, including Podman machine, Keploy refuses Podman commands: its agent uses Linux's eBPF. +- **Which Keploy.** Podman support is in the Keploy that `curl --silent -O -L https://keploy.io/install.sh && source install.sh` installs (free with an account), from v3.8.60. A `keploy` built from the open-source repository refuses Podman commands and says where to get it. diff --git a/versioned_docs/version-4.0.0/keploy-explained/common-errors.md b/versioned_docs/version-4.0.0/keploy-explained/common-errors.md index 6d6691712..dbd2c0755 100644 --- a/versioned_docs/version-4.0.0/keploy-explained/common-errors.md +++ b/versioned_docs/version-4.0.0/keploy-explained/common-errors.md @@ -245,6 +245,53 @@ The recording is missing those bytes, and the test cases or mocks that carried t - Follow the `toRecordIt` field, if the line has one. [Capture loss warnings](../running-keploy/capture-loss.md), which the line's `docs` field links, describes each cause and what to do about it. +### 14. Podman: the command is refused, the app doesn't start, or its image isn't found + +#### Description: + +Recording or testing an application that runs in Podman stops before it starts, with one of these: + +``` +this keploy build cannot record or test applications that run in Podman. ... +``` + +``` +failed to prepare podman: keploy records and tests applications that run in Podman on Linux only +``` + +``` +podman is set up as podman-remote's client, ... +``` + +``` +podman could not say whether it runs locally ... +``` + +or, with compose, the app's container never starts and Podman says: + +``` +Error: unrecognized namespace mode service:keploy-agent passed +``` + +or Podman can't find the application's image although `podman images` (without `sudo`) lists it, or the app runs but nothing is recorded. + +#### Possible Cause: + +- The `keploy` binary doesn't include Podman support: one built from the open-source repository, installed with `install.sh --oss`, or downloaded from the keploy/keploy GitHub releases. +- Keploy is older than v3.8.60 (`keploy -v`): it runs a Podman command as a host process, so the app starts but nothing is recorded, with no error. +- Keploy is running on macOS or Windows (including with Podman machine). Keploy records Podman applications on Linux only. +- Podman is a podman-remote client (set by `CONTAINER_HOST`, `CONTAINER_CONNECTION`, or `remote = true` in containers.conf), so the app would run in another Podman service, while Keploy's agent runs in the local rootful Podman. +- With compose, the compose provider is podman-compose, which Keploy doesn't support. Keploy re-runs itself with `sudo -E` and your `PATH`, so `sudo -E env "PATH=$PATH" podman compose version` shows the provider it gets. Podman takes `PODMAN_COMPOSE_PROVIDER`, else the first of containers.conf's `compose_providers` it finds (by default Docker's compose plugin, then `docker-compose`, then `podman-compose` on that `PATH`). +- With compose, the host doesn't run systemd, so Podman never runs the healthcheck of Keploy's agent service and the app's service, which waits for it, never starts. +- The image is in your rootless Podman. Keploy runs as root and drives the rootful Podman, which has its own images. + +#### Solution: + +- Install or update Keploy with `curl --silent -O -L https://keploy.io/install.sh && source install.sh` (free with an account): Podman needs v3.8.60 or later. +- Run Keploy on the Linux machine whose rootful Podman runs the app, with `CONTAINER_HOST` and `CONTAINER_CONNECTION` unset (or `CONTAINER_HOST` set to the rootful socket, `unix:///run/podman/podman.sock`, with the rootful `podman.socket` enabled) and without `remote = true` in containers.conf. +- For compose, install Docker Compose (`docker-compose`) on that `PATH` and keep `podman-compose` out of containers.conf's `compose_providers`, or set `PODMAN_COMPOSE_PROVIDER` to docker-compose's path; and run it on a host with systemd, or use `podman run`. +- Build or pull the image with `sudo podman`. See [Platform requirements](/docs/concepts/platform-requirements/#podman). + If you’re still encountering issues after trying these solutions, feel free to reach out to the Keploy team on [Slack](https://keploy.io/slack). Happy Testing! diff --git a/versioned_docs/version-4.0.0/running-keploy/cli-commands.md b/versioned_docs/version-4.0.0/running-keploy/cli-commands.md index 83d347a7d..edada8f29 100755 --- a/versioned_docs/version-4.0.0/running-keploy/cli-commands.md +++ b/versioned_docs/version-4.0.0/running-keploy/cli-commands.md @@ -72,6 +72,8 @@ In the above command, `config-dir` is the directory in the CWD where the Keploy keploy record -c "docker compose up" --container-name "my-app-container" ``` +> **Podman:** on Linux, with the Keploy that `install.sh` installs (v3.8.60 or later), an application started in rootful Podman with `podman run` or `podman compose` works the same way: `keploy record -c "podman compose up" --container-name "my-app-container"`. See [Platform requirements](/docs/concepts/platform-requirements/#podman) for what `podman compose` needs. + - `-d, --delay uint` - Delay in seconds to run user application. The default is 5 seconds. ```bash diff --git a/versioned_docs/version-4.0.0/server/installation_tabs.md b/versioned_docs/version-4.0.0/server/installation_tabs.md index 38b95c0cb..3aed4a83d 100644 --- a/versioned_docs/version-4.0.0/server/installation_tabs.md +++ b/versioned_docs/version-4.0.0/server/installation_tabs.md @@ -8,6 +8,7 @@ tags: - installation keywords: - linux + - podman - macos - windows - ebpf @@ -223,6 +224,51 @@ Examples: Use "keploy [command] --help" for more information about a command. ``` + + + + +## Install Keploy with Podman on Linux + +Keploy records and tests applications that run in **rootful** Podman, started with `podman run` (or `podman compose`, below). Its agent loads eBPF, which a rootless Podman can't grant, so Keploy runs as root and drives the rootful Podman. See [Platform requirements](/docs/concepts/platform-requirements/#podman) for the details. + +1. **Make sure Podman is installed** on the Linux machine that runs your app. A Podman set up as a podman-remote client isn't supported. + +2. **Install Keploy.** Podman needs v3.8.60 or later; re-run this to update an older Keploy. + +```bash +curl --silent -O -L https://keploy.io/install.sh && source install.sh +``` + +The installer may say Docker isn't found; with Podman, ignore it. + +3. **Build or pull your application's image with `sudo podman`**, since images in your rootless Podman aren't visible to Keploy, and create a network: + +```bash +sudo podman build -t . +sudo podman network exists keploy-network || sudo podman network create keploy-network +``` + +4. **Record and test.** The first `keploy record` asks you to sign in (see [2. Log in to Keploy](#2-log-in-to-keploy) below). + +```bash +keploy record -c "podman run --rm --name --network keploy-network -p 8080:8080 " +``` + +```bash +keploy test -c "podman run --rm --name --network keploy-network -p 8080:8080 " --delay 10 +``` + +**With compose:** `podman compose` (Podman 4.7 or later; Keploy is tested with Podman 5) works with Docker Compose v2 or later (`docker-compose`) as its compose provider, on a host that runs systemd, which Podman's healthchecks need. Name the application's container, as with Docker Compose: + +```bash +keploy record -c "podman compose up" --container-name "" +``` + +podman-compose isn't supported. + +If the rootful `podman.socket` is enabled (`sudo systemctl enable --now podman.socket`), Keploy uses it; otherwise it starts Podman's API service for the run and stops it when Keploy exits. + @@ -960,6 +1006,11 @@ You’ve successfully set up **Keploy on Linux** using **Docker**. + + + +You’ve successfully set up **Keploy on Linux** using **Podman**. Record and test your app with the `keploy record -c "podman run ..."` and `keploy test -c "podman run ..."` commands above. +