维护模式示例
源码位于 examples/maintenance/。
全局常开维护（状态探测）
maintenance.hosts 中未配置 window 的条目在 Host 匹配时始终生效。可用 GET /_/ingress/status 探测该 Host 是否处于维护（返回 {"status":"ok"} 或 {"status":"maintenance",...}）。
yaml
version: v1
port: 8080
# Global maintenance for listed hosts within maintenance.hosts[].window.
# Probe: curl -sS -D - http://app.example.com/_/ingress/status
maintenance:
hosts:
- host: app.example.com
window:
start: "2026-01-01T00:00:00Z"
end: "2026-12-31T23:59:59Z"
- host: staging-*.example.com
window:
start: "2026-01-01T00:00:00Z"
end: "2026-12-31T23:59:59Z"
title: Site maintenance
subtitle: We will be back shortly.
retry_after: 3600
rules:
- host: app.example.com
backend:
service:
name: httpbin.org
port: 443
protocol: https
- host: staging-api.example.com
backend:
service:
name: httpbin.org
port: 443
protocol: httpsbash
curl -sS http://app.example.com/_/ingress/status
curl -sS -D - http://app.example.com/api # 维护中时 503 + X-Ingress-Maintenance: 1全局维护 + 放行（bypass）
yaml
version: v1
port: 8080
# Global maintenance with bypass: /healthz still reaches the handler; other paths get 503.
maintenance:
hosts:
- host: app.example.com
window:
start: "2026-01-01T00:00:00Z"
end: "2026-12-31T23:59:59Z"
title: Planned maintenance
retry_after: 600
bypass:
paths:
- /healthz
- /metrics/*
header:
name: X-Maintenance-Bypass
value: secret-token
rules:
- host: app.example.com
backend:
service:
name: httpbin.org
port: 443
protocol: https
paths:
- path: /healthz
backend:
type: handler
handler:
status_code: 200
headers:
Content-Type: application/json
body: '{"ok":true}'维护生效期间，/healthz（handler）及带 X-Maintenance-Bypass: secret-token 的请求仍可访问；其余路径返回 503。
路由 scope: all
yaml
version: v1
port: 8080
# Route-level maintenance: scope all blocks every host matched by the rule.
rules:
- host: app.example.com
backend:
type: service
service:
name: httpbin.org
port: 443
protocol: https
maintenance:
enabled: true
scope: all
window:
start: "2026-01-01T00:00:00Z"
end: "2026-12-31T23:59:59Z"
title: Application maintenance
subtitle: Upgrading the app stack.
retry_after: 1800路由 scope: listed + 分 host 时间窗
yaml
version: v1
port: 8080
# Route-level maintenance: scope listed applies only to maintenance.hosts on the rule.
rules:
- host: "*.example.com"
backend:
type: service
service:
name: httpbin.org
port: 443
protocol: https
maintenance:
enabled: true
scope: listed
hosts:
- host: legacy.example.com
window:
start: "2026-12-01T00:00:00Z"
end: "2026-12-01T06:00:00Z"
- host: beta.example.com
window:
start: "2026-12-01T00:00:00Z"
end: "2026-12-01T06:00:00Z"
title: Legacy stack maintenance自定义维护响应头
yaml
version: v1
port: 8080
# Custom maintenance response header (default is X-Ingress-Maintenance: 1).
maintenance:
hosts:
- host: app.example.com
window:
start: "2026-01-01T00:00:00Z"
end: "2026-12-31T23:59:59Z"
title: Planned maintenance
response_header:
name: X-Custom-Maintenance
value: "yes"
rules:
- host: app.example.com
backend:
type: service
service:
name: httpbin.org
port: 443
protocol: https自定义状态 API 路径
yaml
version: v1
port: 8080
# Custom JSON status probe path (default is /_/ingress/status).
maintenance:
status_path: /internal/ingress-status
hosts:
- host: app.example.com
window:
start: "2026-01-01T00:00:00Z"
end: "2026-12-31T23:59:59Z"
title: Planned maintenance
rules:
- host: app.example.com
backend:
type: service
service:
name: httpbin.org
port: 443
protocol: https自定义状态 API 响应体
yaml
version: v1
port: 8080
# Custom JSON body for the maintenance status probe (default is built-in status/title fields).
maintenance:
hosts:
- host: app.example.com
window:
start: "2026-01-01T00:00:00Z"
end: "2026-12-31T23:59:59Z"
title: Planned maintenance
retry_after: 300
status_response:
ok: '{"ready":true,"host":"${host}"}'
maintenance: '{"ready":false,"message":"${title}","retry_after":${retry_after}}'
content_type: application/json; charset=utf-8
rules:
- host: app.example.com
backend:
type: service
service:
name: httpbin.org
port: 443
protocol: https全局 + 路由级组合
yaml
version: v1
port: 8080
# Combined global + route-level maintenance with per-host time windows and bypass.
maintenance:
hosts:
- host: app.example.com
window:
start: "2026-05-30T02:00:00+08:00"
end: "2026-05-30T06:00:00+08:00"
- host: staging-*.example.com
window:
start: "2026-05-30T02:00:00+08:00"
end: "2026-05-30T18:00:00+08:00"
title: Planned maintenance
subtitle: We will be back shortly.
retry_after: 3600
bypass:
paths:
- /healthz
header:
name: X-Maintenance-Bypass
value: secret-token
rules:
- host: "*.example.com"
backend:
type: service
service:
name: httpbin.org
port: 443
protocol: https
maintenance:
enabled: true
scope: listed
hosts:
- host: legacy.example.com
window:
start: "2026-05-31T00:00:00+08:00"
end: "2026-05-31T01:00:00+08:00"
title: Legacy stack maintenance校验
bash
ingress validate -c examples/maintenance/global-always-on.yaml
ingress validate -c examples/maintenance/global-bypass.yaml
ingress validate -c examples/maintenance/route-scope-all.yaml
ingress validate -c examples/maintenance/route-scope-listed.yaml
ingress validate -c examples/maintenance/custom-response-header.yaml
ingress validate -c examples/maintenance/custom-status-path.yaml
ingress validate -c examples/maintenance/custom-status-response.yaml
ingress validate -c examples/maintenance/ingress.yaml详解见 维护模式指南（响应头、访问日志字段等）。