Simulators/README.md

**Language / Язык:** [English](README.md) | [Русский](README.ru.md)

# API simulators lab (self-contained)

Four published simulators and one PostgreSQL. No source checkouts required.
Run locally with Docker Compose, or on Kubernetes with the Helm chart.

## Layout

```
simulators/
  Makefile
  docker-compose.yml
  docker/
    postgres-init/01-simulators.sql
    tls/server.{crt,key}         # shared lab TLS for Compose gateways
    ovirt/ovirt-engine.conf
    vmware/vmware-ports.conf
    openstack/openstack-ports.conf
  charts/api-simulators-lab/     # Helm: all four simulators + Ingress
```

Images: `inecs/proxmox-api-simulator`, `inecs/ovirt-api-simulator`,
`inecs/vmware-api-simulator`, `inecs/openstack-api-simulator`.

---

## Docker Compose

Postgres data lives in the Compose volume `postgres-data`.

```bash
cd /Users/inecs/Разработка/simulators
make help
make up          # pull → migrate → apps → seed; prints URLs
make urls        # print Compose endpoints again
make logs        # or: make logs SERVICE=proxmox
make restart
make down        # stop containers, keep DB volume
make clean       # stop + remove volumes, leftovers, project networks
make shell       # or: make shell SERVICE=ovirt
make push        # git add . → multiline commit (Ctrl-D) → push origin
```

`make up` runs migrate/seed via `docker compose run --rm` (profile `init`), so those
containers do not stay in `Exited` state.

Equivalent Compose:

```bash
docker compose pull
docker compose up -d
```

The first start creates databases via `docker/postgres-init` (only on an empty
`postgres-data` volume). Seed jobs run once after each simulator becomes healthy.

Pin an image tag:

```bash
IMAGE_TAG=0.1.0 docker compose up -d
# or: IMAGE_TAG=0.1.0 make up
```

### Compose endpoints

| Simulator | URL |
|---|---|
| Proxmox | http://localhost:8006/ |
| oVirt Engine | https://localhost:7443/ |
| oVirt Web UI | http://localhost:7500/ |
| VMware (HTTPS) | https://localhost:8443/ |
| VMware (HTTP) | http://localhost:8081/ |
| OpenStack Keystone | http://localhost:9500/ |
| OpenStack Nova | http://localhost:8774/ |
| OpenStack HTTPS | https://localhost:9443/ |
| PostgreSQL | `127.0.0.1:5432` (user `lab` / `lab`) |

### Reset the Compose database

```bash
make clean
make up
# or: docker compose down -v && docker compose up -d
```

---

## Kubernetes (Helm)

Chart: `charts/api-simulators-lab`.

Configure before deploy: `charts/api-simulators-lab/values.yaml`

| Key | Purpose |
|---|---|
| `namespace` | Target namespace (`simulators` by default; `namespaceCreate: true`) |
| `ingresses` | Hosts, TLS secrets, annotations (one Ingress per entry) |
| `certManager` | Let's Encrypt via cert-manager (`letsencrypt-prod`) |
| `imageTag` / secrets / `postgres.persistence` | Images, keys, PVC |

Default Ingress hosts (override for real DNS before Let's Encrypt):

| Simulator | Host |
|---|---|
| Proxmox | https://proxmox.lab.local/ |
| oVirt | https://ovirt.lab.local/ |
| VMware | https://vmware.lab.local/ |
| OpenStack | https://openstack.lab.local/ |

```bash
make helm up       # warns → confirm [y/N] → helm upgrade --install
make helm down     # uninstall release
make helm-urls     # print Ingress hosts from values
make helm-template
make helm-lint
```

Skip the confirmation prompt (CI): `make helm-up HELM_YES=1`

Override namespace without editing values: `HELM_NAMESPACE=other make helm-up`

Equivalent Helm:

```bash
helm upgrade --install simulators charts/api-simulators-lab \
  --namespace simulators --create-namespace --wait
```

### How the chart starts

1. **Namespace** — created from `values.namespace` when `namespaceCreate: true`.
2. **PostgreSQL** — StatefulSet + init SQL for four simulator databases.
3. **Simulators** — Deployments with init containers:
   - `wait-postgres` → `migrate` (idempotent; no-op if schema is current).
4. **Seed** — post-install / post-upgrade Jobs per simulator.
   - Each Job waits until the app is ready, then seeds.
   - `seed.skipIfSql` skips when the DB already has lab data (no wipe/re-seed).
5. **Ingress** — TLS via cert-manager annotation `cert-manager.io/cluster-issuer`.
   - Set `certManager.createClusterIssuer: true` and `certManager.email` to create
     ClusterIssuers from the chart; otherwise an existing `letsencrypt-prod` is used.
   - Let's Encrypt HTTP-01 needs **public DNS** pointing at the Ingress controller
     (not `*.lab.local`).
   - Each Ingress sets `proxy-intercept-errors: "false"` and
     `custom-http-errors: "502,503"` so cluster-wide branded HTML (e.g. «DevOps спит»)
     does not replace simulator JSON/XML for 404/405/401. Do **not** put 404/405 in
     `custom-http-errors`. After `helm upgrade`, check with
     `curl -sH 'Accept: application/json' https://<host>/…` — expect API error body,
     not HTML. If HTML persists, fix controller-level `custom-http-errors` on
     ingress-nginx (outside this chart).

---

## Git

`origin` pushes to both remotes (same pattern as other simulators):

- `git@github.com:sergeyantropoff/simulators.git`
- `ssh://git@git.antropoff.ru:30022/DevOpsTools/Simulators.git`

```bash
make push   # stage all → multiline commit message (end with Ctrl-D) → push origin
```

Same UX as `proxmox_api_simulator`.

---

Laboratory defaults only — do not expose this stack to the public Internet without rotating secrets (`ticketSigningKey`, DB passwords, Ingress hosts).