Ingress

简体中文

English

简体中文

English

Appearance

高级示例 ​

进阶路由、重写与健康检查等示例。

配置文件：examples/advanced/。

正则主机与路径重写 ​

yaml
version: v1
port: 8080

rules:
  - host: ^t-(\w+).example.work
    host_type: regex
    backend:
      service:
        name: task.${host.1}.svc
        port: 8080
    paths:
      - path: /api/v1/([^/]+)
        backend:
          service:
            name: ${path.1}.${host.1}.example.work
            port: 8080
            request:
              path:
                rewrites:
                  - ^/api/v1/([^/]+):/api/v1/task/$1

此示例：

  • 用正则匹配如 t-myapp.example.work 的主机
  • 在 service.name 中使用 ${host.<索引>}、${path.<索引>} 等作用域捕获
  • 对特定 API 路径做重写

通配符主机 ​

yaml
version: v1
port: 8080

rules:
  - host: '*.example.work'
    host_type: wildcard
    backend:
      service:
        name: wildcard-service
        port: 8080

匹配 example.work 的任意子域。

复杂路径重写 ​

yaml
version: v1
port: 8080

rules:
  - host: httpbin.example.work
    backend:
      service:
        mode: external
        name: httpbin.zcorky.com
        protocol: https
        request:
          path:
            rewrites:
              - ^/ip3/(.*):/$1
              - ^/ip2:/ip
    paths:
      - path: /httpbin.org
        backend:
          service:
            mode: external
            name: httpbin.org
            protocol: https
            strip_prefix: true
            # same as
            #
            # request:
            #   path:
            #     rewrites:
            #       - ^/httpbin.org/(.*):/$1

对第三方 HTTPS 上游在 backend.service 下使用 mode: external，无需再写 request.host.rewrite 即可让 Host 与各自 service.name 一致。

service.mode（internal / external）与 handler 路径示例：

yaml
# Runnable sample: internal upstreams, path routing, service.mode: external, and handler paths.
# Prefer **`backend.service.mode`** (not **`backend.mode`**) for proxy Host defaults.
# Mirrors the “simple” Docker-style demo (portainer, registry, httpbin) in a single file.
#
# Validate:
#   ingress validate -c examples/advanced/service-mode-external-mixed.yaml
#
# HTTPS upstreams: port optional (defaults to 443 when omitted).

version: v1
port: 8080

rules:
  - host: portainer.example.com
    backend:
      service:
        name: portainer
        port: 80

  - host: docker-registry.example.com
    backend:
      service:
        name: docker-registry
        port: 80
    paths:
      - path: /v2
        backend:
          service:
            name: docker-registry-v2
            port: 80

  - host: httpbin.example.work
    backend:
      service:
        mode: external
        protocol: https
        name: httpbin.zcorky.com

  - host: httpbin2.example.work
    backend:
      service:
        mode: external
        protocol: https
        name: httpbin.org

  - host: handler.example.work
    backend:
      service:
        mode: external
        protocol: https
        name: httpbin.org
    paths:
      - path: /custom/handler/string
        backend:
          type: handler
          handler:
            body: Hello World!
      - path: /custom/handler/json
        backend:
          type: handler
          handler:
            headers:
              Content-Type: application/json
            body: |
              {
                "message": "Hello, World!"
              }
      - path: /custom/handler/html
        backend:
          type: handler
          handler:
            status_code: 200
            headers:
              Content-Type: text/html
            body: |
              <html>
                <body>
                  <h1>Hello, World!</h1>
                </body>
              </html>

全部 handler 类型（file_server、templates、script）见 Handler 后端示例。

多服务与健康检查 ​

yaml
version: v1
port: 8080

healthcheck:
  outer:
    enable: true
    path: /healthz
    ok: true
  inner:
    enable: true
    interval: 30
    timeout: 5

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        healthcheck:
          enable: true
          method: GET
          path: /health
          status: [200]

HTTP 响应缓存（backend.cache） ​

按 backend 缓存 service / handler / redirect 的响应，与顶层 cache 共用 ctx.Cache()。语义、skip_vary 与 httpbin Vary 说明见缓存指南。

yaml
# Per-backend HTTP response cache (`backend.cache`): caches eligible GET/HEAD responses for
# **service** (upstream proxy), **handler** (static response), and **redirect** (final Location).
#
# This is separate from top-level `cache`, which only configures the shared Zoox `ctx.Cache()`
# engine (memory or Redis) used for matcher data *and* as the storage for HTTP cache entries.
#
# Live demo (external https://httpbin.zcorky.com + skip_vary for Vary: Origin):
#   ingress run -c examples/advanced/http-response-cache.yaml
#   curl -s -H "Host: api-cached.httpbin.work" http://127.0.0.1:8080/ip
#   curl -s -H "Host: api-cached.httpbin.work" http://127.0.0.1:8080/ip   # access log: cache_hit=1
#
# Validate:
#   ingress validate -c examples/advanced/http-response-cache.yaml

version: v1
# Listen port: use `port` here or override at runtime (`PORT=9999`). `curl` must use the same port.
port: 8080

cache:
  ttl: 300

rules:
  - host: api-cached.example.com
    backend:
      service:
        name: backend-api
        port: 8080
      cache:
        enabled: true
        ttl: 600
        max_body_bytes: 1048576
        key_hash: sha256

  - host: static-snippet.example.com
    backend:
      type: handler
      handler:
        headers:
          Content-Type: text/plain; charset=utf-8
        body: |
          Short static text — handler responses are cacheable when they meet storage rules.
      cache:
        enabled: true
        ttl: 60

  - host: redirect-cached.example.com
    backend:
      redirect:
        url: https://www.example.com/landing
      cache:
        enabled: true
        ttl: 120

  - host: mixed.example.com
    backend:
      service:
        name: default-upstream
        port: 8080
    paths:
      - path: /status
        backend:
          handler:
            status_code: 200
            headers:
              Content-Type: application/json
            body: '{"ready":true}'
          cache:
            enabled: true
            ttl: 30

  # External https://httpbin.zcorky.com — **`skip_vary: true`** so paths like `/ip` cache despite `Vary: Origin`.
  # Without `skip_vary`, Ingress does not store responses with a non-empty `Vary` header.
  # Verify: two GETs to `/ip` on this host; second request should log `cache_hit=1`.
  - host: api-cached.httpbin.work
    backend:
      service:
        mode: external
        protocol: https
        name: httpbin.zcorky.com
      cache:
        enabled: true
        ttl: 60
        skip_vary: true
    paths:
      # Handler without `Vary` — cache works even with `skip_vary: false` (contrast with `/ip` above).
      - path: /demo-cached
        backend:
          type: handler
          handler:
            headers:
              Content-Type: application/json; charset=utf-8
            body: '{"demo":"Cacheable handler (no Vary). Repeat GET to see cache_hit=1 in logs."}'
          cache:
            enabled: true
            ttl: 60

按路径 cache / bypass（default、有序 paths[]、可选 per-rule TTL）：

yaml
# Per-path HTTP response cache rules (`backend.cache.paths`).
#
# When `paths` is non-empty, rules are evaluated in order (first match wins).
# Unmatched paths follow `default` (`cache` or `bypass`; default `cache`).
#
# Validate:
#   ingress validate -c examples/advanced/http-response-cache-paths.yaml
#
# Demo (handler on /cached only — repeat GET to see cache_hit=1):
#   ingress run -c examples/advanced/http-response-cache-paths.yaml
#   curl -s -H "Host: paths-demo.example.com" http://127.0.0.1:8080/cached
#   curl -s -H "Host: paths-demo.example.com" http://127.0.0.1:8080/cached
#   curl -s -H "Host: paths-demo.example.com" http://127.0.0.1:8080/live   # never cached

version: v1
port: 8080

cache:
  ttl: 300

rules:
  - host: paths-demo.example.com
    backend:
      type: handler
      handler:
        headers:
          Content-Type: text/plain; charset=utf-8
        body: |
          Dynamic handler — path rules decide whether backend.cache applies.
      cache:
        enabled: true
        ttl: 300
        default: bypass
        paths:
          - match: /cached
            match_type: exact
            action: cache
            ttl: 60
          - match: /static/
            match_type: prefix
            action: cache
            ttl: 3600
          - match: ^/api/v[0-9]+/public/
            match_type: regex
            action: cache
          - match: /health
            action: bypass

  # Same upstream, whitelist-only caching with per-path TTL
  - host: api-selective.example.com
    backend:
      service:
        name: backend.internal
        port: 8080
      cache:
        enabled: true
        ttl: 120
        default: bypass
        paths:
          - match: /assets/
            match_type: prefix
            action: cache
            ttl: 86400
            max_body_bytes: 5242880
          - match: /api/public/
            match_type: prefix
            action: cache

应用缓存引擎（内存 / Redis） ​

顶层 cache 决定匹配器等数据用 Redis 还是内存；HTTP 响应条目在开启 backend.cache 时也写入同一后端。下例在 service 上启用 backend.cache，多实例时可共享缓存。

yaml
# Top-level `cache`: Redis-backed **application** cache (matcher, DNS hints, etc.) and the same
# `ctx.Cache()` store used for **`backend.cache`** HTTP response entries (`prefix` applies to keys).
#
# Enable **`backend.cache`** per route when you want distributed **response** caching across instances.
#
# Validate:
#   ingress validate -c examples/advanced/redis-cache.yaml

version: v1
port: 8080

cache:
  ttl: 60
  engine: redis
  host: redis.example.com
  port: 6379
  password: your-password
  db: 0
  prefix: "ingress:"

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
      cache:
        enabled: true
        ttl: 120
        max_body_bytes: 2097152
        key_hash: sha256

综合示例 ​

包含 HTTPS、缓存、健康检查、fallback、认证与路径规则的合成示例：

yaml
version: v1
port: 8080

cache:
  ttl: 30

https:
  port: 8443
  ssl:
    - domain: example.com
      cert:
        certificate: /etc/ssl/example.com/fullchain.pem
        certificate_key: /etc/ssl/example.com/privkey.pem

healthcheck:
  outer:
    enable: true
    path: /healthz
    ok: true
  inner:
    enable: true
    interval: 30
    timeout: 5

fallback:
  service:
    protocol: https
    name: httpbin.org

rules:
  - host: example.com
    backend:
      service:
        mode: external
        name: backend-service
        port: 8080
        auth:
          type: basic
          basic:
            users:
              - username: admin
                password: admin123
        healthcheck:
          enable: true
          method: GET
          path: /health
          status: [200]
        request:
          path:
            rewrites:
              - ^/api/v1/(.*):/api/v2/$1
          headers:
            X-Forwarded-Proto: https
          timeout: 30
    paths:
      - path: /api
        backend:
          service:
            name: api-service
            port: 8080
            auth:
              type: bearer
              bearer:
                tokens:
                  - api-token-123

Released under the MIT License.

Copyright © 2024 GoZoox