Ikanos — Guide - Reverse Tunnel for Private APIs¶

Table of Contents¶

• Overview
• When to use this guide
• Path A — Embedded OpenZiti (built-in, recommended)
  • How the embedded tunnel works
  • Capability YAML
  • Adding the tunnel module to your deployment
  • Identity provisioning and rotation
  • Fallback behaviour
  • Observability — what surfaces in Ikanos
• Path B — Sidecar pattern (for non-Ziti tunnels)
  • How the sidecar pattern works
  • Recipe 1 — FRP (Fast Reverse Proxy)
  • Recipe 2 — Cloudflare Tunnel
  • Recipe 3 — Standalone OpenZiti tunneler
  • Capability YAML for the sidecar pattern
  • Health checks and startup ordering
• Choosing a path
• Security trade-offs
• Troubleshooting

Overview¶

Many real-world integrations need an Ikanos capability to call an HTTP API that lives inside a corporate network — a CRM, an ERP, an internal database — while the engine itself runs in a public environment (cloud, SaaS, customer's edge). Three options are tempting but each has a serious drawback:

The correct answer is a reverse tunnel: a process on the private side dials outbound to a relay (or directly to Ikanos), then accepts traffic back through the established connection. No inbound firewall rules. No public exposure of the private API. No public DNS.

Ikanos 1.0.0-alpha3 ships two supported ways to do this:

Both paths preserve the no-inbound-firewall-rule property. Path A makes the tunnel a first-class part of the capability contract; Path B keeps it as deployment infrastructure.

When to use this guide¶

Use a reverse tunnel when all of the following are true:

• The upstream API lives behind a firewall that denies inbound traffic.
• You cannot (or do not want to) move Ikanos into that network.
• You can run one matching process on the private side (a Ziti edge router for Path A, or the matching tunnel client for Path B).

If even one of those is not true, prefer the simpler path: a public API plus an authentication layer declared with the standard authentication: block.

Path A — Embedded OpenZiti (built-in, recommended)¶

New in Ikanos 1.0.0-alpha3. The engine dials the consumed API directly through an OpenZiti overlay using the Java SDK — no sidecar, no 127.0.0.1 indirection, no port mapping. The capability YAML declares the tunnel; the engine handles the rest.

At a glance — drop the ikanos-tunnel-ziti jar on the classpath, add a tunnel: block to consumes.http, mount a Ziti identity through binds, and that's it. baseUri keeps its real hostname.

How the embedded tunnel works¶

   PUBLIC NETWORK                                  │           PRIVATE NETWORK
                                                   │
   ┌──────────────────────────────────┐            │     ┌─────────────────────────┐
   │ Ikanos engine                    │            │     │ Internal API            │
   │   consumes.http:                 │            │     │ (CRM, ERP, DB, …)       │
   │     baseUri: https://crm.internal│            │     └────────────▲────────────┘
   │     tunnel: { type: ziti, … }    │            │                  │ HTTP(S)
   │                                  │            │                  │
   │   ┌──────────────────────────┐   │            │     ┌────────────┴────────────┐
   │   │ OpenZiti Java SDK        │ ──┼─ overlay ──┼─────│ Ziti edge router        │
   │   │ (ikanos-tunnel-ziti)     │   │ (mTLS,     │     │ + private "host" ident. │
   │   └──────────────────────────┘   │  outbound) │     └─────────────────────────┘
   └──────────────────────────────────┘            │
                                                   │
                                Ziti controller    │
                              (self-hosted, OSS)   │

Key invariants:

1. The engine dials the overlay — no extra container, no loopback hop. The Tunnel SPI (io.ikanos.engine.consumes.tunnel.Tunnel) replaces the default HttpClient socket factory when a tunnel: block is declared.
2. The private side dials out — the Ziti edge router on the private network establishes an outbound mTLS connection to the controller. The firewall only needs to permit outbound to the controller / edge router endpoints.
3. baseUri is the real hostname. https://crm.internal resolves through the Ziti intercept.v1 config, not DNS. No 127.0.0.1 placeholder, no synthetic hosts file.
4. Authentication still runs end-to-end on top of the tunnel. Bearer tokens, OAuth2, API keys declared via authentication: are unaffected — the tunnel is transport.

Capability YAML¶

ikanos: "1.0.0-alpha3"

info:
  display: "CRM reverse-tunnel example"
  description: "Reach an internal CRM API over an OpenZiti reverse tunnel."

binds:
  - namespace: "secrets"
    description: "Credentials for the private CRM and the Ziti identity bundle."
    location: "file:///./shared/secrets.yaml"
    keys:
      ZITI_IDENTITY: "ziti-identity-path"
      CRM_TOKEN: "crm-bearer-token"

capability:
  consumes:
    - type: "http"
      namespace: "crm"
      description: "Customer Relationship Management API on the private network."
      baseUri: "https://crm.internal"
      authentication:
        type: "bearer"
        token: "{{secrets.CRM_TOKEN}}"
      tunnel:
        type: "ziti"
        service: "crm-api"
        identity: "{{secrets.ZITI_IDENTITY}}"
        fallback: "fail"
      resources:
        customers:
          description: "Customer records."
          path: "/customers"
          operations:
            list-customers:
              method: "GET"
              description: "List all customers."

Field reference for tunnel::

Adding the tunnel module to your deployment¶

The embedded path is an opt-in jar so the OpenZiti SDK is not pulled into deployments that do not need it.

Maven dependency:

<dependency>
    <groupId>io.ikanos</groupId>
    <artifactId>ikanos-tunnel-ziti</artifactId>
    <version>1.0.0-alpha3</version>
</dependency>

Container image:

FROM ghcr.io/naftiko/ikanos:1.0.0-alpha3
# Drop the tunnel module on the classpath — discovered via ServiceLoader.
ADD https://repo.maven.apache.org/maven2/io/ikanos/ikanos-tunnel-ziti/1.0.0-alpha3/ikanos-tunnel-ziti-1.0.0-alpha3.jar \
    /app/lib/

The module registers an implementation of io.ikanos.engine.consumes.tunnel.Tunnel through META-INF/services. At startup the engine discovers it by ServiceLoader, reads the Mustache-resolved tunnel.identity from the matching consumes.http, and installs the tunnel socket factory on the HttpClient used for that endpoint.

Validation works without the jar. Parsing, schema validation, and the Polychro linter rules all run from the spec alone. You only need the ikanos-tunnel-ziti jar at runtime when the engine actually dials.

Identity provisioning and rotation¶

Each capability gets its own Ziti identity. The standard flow:

1. Enroll the identity on the Ziti controller — produces a one-time JWT enrollment token.
2. Exchange the JWT for a long-lived identity bundle (JSON / PFX). The exchange happens once, on the machine that will hold the identity.
3. Mount the bundle into the Ikanos deployment through the same binds mechanism Ikanos already uses for secrets — e.g. a Kubernetes Secret mounted as a file, or location: file:// against a sealed-secret-managed path.

The Ziti controller can revoke an identity at any time; the engine surfaces the next failed dial through isReady() == false on the Tunnel and a 503-equivalent on the consumed operation. Rotation is therefore atomic from Ikanos's point of view: drop the new identity into the bound location, restart the capability, and the next dial uses the new bundle.

One identity per capability is the canonical shape in Alpha 3. Multi-identity per capability is a future enhancement tracked in the Reverse Tunnel blueprint.

Fallback behaviour¶

tunnel.fallback controls what happens when the overlay is unavailable at dial time:

The fail-closed default exists because a leaked direct fallback would silently exfiltrate a request that the developer thought was being tunnelled. Lint catches the obvious cases; the schema description documents the rest.

Observability — what surfaces in Ikanos¶

Unlike the sidecar pattern (where the tunnel is opaque to the engine), the embedded path surfaces tunnel state in the same places Ikanos already exposes its own health:

• /health/ready — gated on Tunnel.isReady(). A capability is not ready until the Ziti context is Active.
• /metrics — dial attempts, dial latency, and tunnel session state, tagged by capability and consumed namespace.
• Traces — the Ziti dial is a child span of the consumed-operation span, so trace context propagates end-to-end through the overlay.

This is the single biggest operational advantage over the sidecar pattern: tunnel state is inside the engine's observability story, not next to it.

Path B — Sidecar pattern (for non-Ziti tunnels)¶

The sidecar pattern keeps working and is still the right choice in two cases:

• You want FRP or Cloudflare Tunnel specifically (e.g. you already operate a Cloudflare Access tenant).
• You cannot extend the JVM classpath in the Ikanos deployment — e.g. you ship a tightly-locked image and need the tunnel as pure infrastructure.

For an OpenZiti overlay you have a choice: use Path A (recommended) or run the standalone ziti-edge-tunnel as a sidecar. Path A removes one container, one identity-management surface, and the loopback indirection.

How the sidecar pattern works¶

The deployment topology has three pieces:

   PUBLIC NETWORK                                 │           PRIVATE NETWORK
                                                  │
   ┌─────────────────────────────┐                │     ┌─────────────────────────┐
   │ Ikanos engine               │                │     │ Internal API            │
   │  baseUri: http://127.0.0.1: │                │     │ (CRM, ERP, DB, …)       │
   │           8443              │                │     └────────────▲────────────┘
   └─────────────┬───────────────┘                │                  │ HTTP
                 │ HTTP (loopback)                │                  │
   ┌─────────────▼───────────────┐                │     ┌────────────┴────────────┐
   │ Tunnel sidecar (frpc /      │                │     │ Tunnel server / agent   │
   │ cloudflared / ziti-tunneler)│ ◄── tunnel ────│─────│ (frps / cloudflared /   │
   └─────────────────────────────┘   (outbound    │     │ ziti-edge-tunnel)       │
                                     from private)     └─────────────────────────┘

Key invariants:

1. The private-side process always dials out. The firewall only needs to permit outbound traffic to a known relay or controller.
2. The capability YAML points at a loopback endpoint. consumes.baseUri is http://127.0.0.1:<port> — the sidecar owns the mapping to the real private host.
3. Authentication still runs end-to-end on top of the tunnel, same as Path A.

Recipe 1 — FRP (Fast Reverse Proxy)¶

FRP is an Apache 2.0 reverse proxy with a self-hostable control plane (frps) and a small client (frpc). Recommended sidecar default when you need a non-Ziti tunnel.

Components¶

docker-compose.yml¶

version: "3.9"
services:
  ikanos:
    image: ghcr.io/naftiko/ikanos:1.0.0-alpha3
    ports:
      - "8081:8081"     # REST/MCP exposure
    volumes:
      - ./capability.yaml:/app/capability.yaml:ro
    depends_on:
      frpc:
        condition: service_healthy

  frpc:
    image: snowdreamtech/frpc:latest
    network_mode: "service:ikanos"   # share Ikanos' loopback
    volumes:
      - ./frpc.toml:/etc/frp/frpc.toml:ro
    healthcheck:
      test: ["CMD", "wget", "-q", "-O-", "http://127.0.0.1:7400/healthz"]
      interval: 5s
      timeout: 2s
      retries: 12

network_mode: "service:ikanos" puts frpc and Ikanos on the same loopback, so baseUri: http://127.0.0.1:8443 resolves to the sidecar's local listener.

frpc.toml (public side)¶

serverAddr = "frps.example.com"
serverPort = 7000
auth.method = "token"
auth.token = "{{REPLACE_WITH_TOKEN}}"

# Expose a local listener that maps to the private CRM
[[visitors]]
name = "crm"
type = "stcp"
serverName = "crm-private"
secretKey = "{{REPLACE_WITH_SECRET}}"
bindAddr = "127.0.0.1"
bindPort = 8443

The private-side frpc mirrors this with type = "stcp", name = "crm-private", the matching secretKey, and localIP / localPort pointing at the internal API. See the FRP documentation for the full server + private-side config.

Security profile¶

• Authentication: shared token between every frpc and frps; per-tunnel secretKey for stcp visitors.
• Encryption: optional mTLS on frpc ↔ frps. For HTTPS upstream, the application-layer TLS handshake still runs end-to-end inside the tunnel — frpc only sees ciphertext.
• Granularity: per-tunnel keys. A leaked secretKey only exposes the matching stcp mapping, not the whole network.

Recipe 2 — Cloudflare Tunnel¶

Cloudflare Tunnel (cloudflared) is the lowest-setup option if you accept a SaaS control plane. Cloudflare brokers the connection; you do not run a relay server.

Components¶

docker-compose.yml¶

version: "3.9"
services:
  ikanos:
    image: ghcr.io/naftiko/ikanos:1.0.0-alpha3
    ports:
      - "8081:8081"
    volumes:
      - ./capability.yaml:/app/capability.yaml:ro
    depends_on:
      cloudflared:
        condition: service_started

  cloudflared:
    image: cloudflare/cloudflared:latest
    network_mode: "service:ikanos"
    command:
      - access
      - tcp
      - --hostname
      - crm.internal.example.com
      - --url
      - 127.0.0.1:8443
    environment:
      TUNNEL_SERVICE_TOKEN_ID:     "${CF_SERVICE_TOKEN_ID}"
      TUNNEL_SERVICE_TOKEN_SECRET: "${CF_SERVICE_TOKEN_SECRET}"

The private-side cloudflared tunnel run <UUID> is configured separately and points at the internal API. Authorization between the public sidecar and the tunnel is enforced by Cloudflare Access Service Tokens.

Security profile¶

• Authentication: Cloudflare Access Service Tokens (or SSO / mTLS) on the public side; tunnel credentials on the private side. Both are issued and revocable from the Cloudflare dashboard.
• Encryption: end-to-end TLS to Cloudflare's edge; mTLS optional on both legs.
• Granularity: per-hostname. Service Tokens can be revoked individually.
• Trade-off: the control plane is not self-hostable — you depend on Cloudflare. If air-gap or sovereignty is a requirement, prefer Path A or FRP.

Recipe 3 — Standalone OpenZiti tunneler¶

This recipe runs the standalone ziti-edge-tunnel as a sidecar instead of the embedded Path A. Use it only when you cannot extend the JVM classpath; otherwise prefer Path A, which uses the same overlay without the extra container.

Components¶

docker-compose.yml¶

version: "3.9"
services:
  ikanos:
    image: ghcr.io/naftiko/ikanos:1.0.0-alpha3
    ports:
      - "8081:8081"
    volumes:
      - ./capability.yaml:/app/capability.yaml:ro
    depends_on:
      ziti-tunnel:
        condition: service_started

  ziti-tunnel:
    image: openziti/ziti-edge-tunnel:latest
    network_mode: "service:ikanos"
    cap_add: ["NET_ADMIN"]
    devices: ["/dev/net/tun"]
    volumes:
      - ./ikanos-identity.json:/ziti-edge-tunnel/identity.json:ro
    command: ["run", "--identity", "/ziti-edge-tunnel/identity.json"]

Because ziti-edge-tunnel requires NET_ADMIN and /dev/net/tun, this recipe is the most container-runtime-sensitive of the three. Path A avoids both — the Ikanos JVM dials through the overlay using only socket-level integration.

Security profile¶

• Authentication: x509-based identity enrollment per side; short-lived session credentials issued by the controller.
• Encryption: end-to-end mTLS through every hop of the Ziti fabric. Application-layer TLS still runs end-to-end on top.
• Granularity: per-service authorization in the controller.

Capability YAML for the sidecar pattern¶

Whichever sidecar you choose, the capability YAML looks the same — note the baseUri is 127.0.0.1, and there is no tunnel: block:

ikanos: "1.0.0-alpha3"

binds:
  - namespace: secrets
    location: env://
    keys:
      CRM_TOKEN: CRM_TOKEN

capability:
  consumes:
    - type: http
      namespace: crm
      description: |
        Internal CRM API, reached through a reverse-tunnel sidecar.
        The sidecar (frpc / cloudflared / ziti-edge-tunnel) is responsible for
        routing 127.0.0.1:8443 to the private CRM. From Ikanos' point of view
        this is a regular HTTP endpoint.
      baseUri: "http://127.0.0.1:8443"
      authentication:
        type: bearer
        token: "{{secrets.CRM_TOKEN}}"
      resources:
        customers:
          path: "/v1/customers/{id}"
          operations:
            get-customer:
              method: GET
              inputParameters:
                - { name: id, in: path, required: true }

Two things to notice:

• baseUri uses http://127.0.0.1:<port> rather than the real internal hostname. The sidecar owns the mapping.
• authentication: is unchanged. The bearer token authenticates the capability to the upstream API, end-to-end inside the tunnel.

Health checks and startup ordering¶

The sidecar must be ready before Ikanos starts polling consumed endpoints, otherwise the first health check on /health/ready may fail. Use one of the following:

• Docker Compose — depends_on: { sidecar: { condition: service_healthy } } plus a healthcheck: block on the sidecar (FRP example above).
• Kubernetes — model the sidecar as a regular sidecar container with a readinessProbe. The pod is not considered ready until both containers report ready.
• systemd — put Requires= and After= on the Ikanos unit pointing at the tunnel unit.

In the sidecar pattern, the Ikanos Control Port reflects readiness of the consumed endpoint, not the tunnel itself — there is no Ikanos-side visibility into the sidecar's health. If you need tunnel state to surface in /health/ready and /metrics, use Path A.

Choosing a path¶

When in doubt: Path A. The sidecar pattern is a supported escape hatch, not the default.

Security trade-offs¶

All paths preserve the no-inbound-firewall-rule property — that is the whole point. They differ on credential lifecycle, blast radius of a leak, and where tunnel state shows up operationally.

Troubleshooting¶