Ingress使用

1.Nginx Ingress简介

　　Kubernetes 通过 kube-proxy 服务实现了 Service 的对外发布及负载均衡，它的各种方式都是基于传输层实现的。在实际的互联网应用场景中，不仅要实现单纯的转发，还有更加细致的策略需求，如果使用真正的负载均衡器更会增加操作的灵活性和转发性能。

　　基于以上需求，Kubernetes 引入了资源对象 Ingress，Ingress 为 Service 提供了可直接被集群外部访问的虚拟主机、负载均衡、SSL 代理、HTTP 路由等应用层转发功能。

　　Kubernetes 官方发布了基于 GCE 和 Nginx 的 Ingress 控制器，Nginx Ingress 控制器能根据 Service 中 Pod 的变化动态地调整配置，结合 Nginx 的高稳定性、高性能、高并发处理能力等特点，使 Kubernetes 对集群中运行于容器的应用程序具有了更加灵活的应用层管理能力。

　　Nginx Ingress 因使用 Nginx 的不同版本，分为 Nginx 官方版本和 Kubernetes 社区版。Nginx 官方版本提供其基于Go语言开发的 Ingress 控制器，并与 Nginx 集成分为 Nginx 开源版和 Nginx Plus 版；开源版仅基于 Nginx 的原始功能，提供了 Nginx 原生配置指令的支持，相较于 Nginx Plus 版功能简单且不支持 Pod 变化的动态变更。

　　Nginx Plus 版则提供了诸多完善的商业功能，其支持 Nginx 原生配置指令、JWT 验证、Pod 变化的动态配置及主动健康检查等功能。Kubernetes 社区版是基于 Nginx 的扩展版 OpenResty 及诸多第三方模块构建的，其基于 OpenResty 的 Lua 嵌入式编程能力，扩展了 Nginx 的功能，并基于 balancer_by_lua 模块实现了 Pod 变化的动态变更功能。本节介绍的是基于 Kubernetes 社区版的 Nginx Ingress。

 

1.1 Nginx Ingress原理

　　Nginx Ingress 由资源对象 Ingress、Ingress 控制器、Nginx 三部分组成，Ingress 控制器用以将 Ingress 资源实例组装成 Nginx 配置文件（nginx.conf），并重新加载 Nginx 使变更的配置生效。当它监听到 Service 中 Pod 变化时通过动态变更的方式实现 Nginx 上游服务器组配置的变更，无须重新加载 Nginx 进程。工作原理如下图所示。

• Ingress，一组基于域名或 URL 把请求转发到指定 Service 实例的访问规则，是 Kubernetes 的一种资源对象，Ingress 实例被存储在对象存储服务 etcd 中，通过接口服务被实现增、删、改、查的操作。
• Ingress 控制器（Ingress controller），用以实时监控资源对象 Ingress、Service、End-point、Secret（主要是 TLS 证书和 Key）、Node、ConfigMap 的变化，自动对 Nginx 进行相应的操作。
• Nginx，实现具体的应用层负载均衡及访问控制。

　　　　　　　　　　　　　　图：Nginx Ingress工作原理

　　Ingress 控制器通过同步循环机制实时监控接口服务 Ingress 等资源对象的变化，当相关 Service 对应的端点列表有变化时，会通过 HTTP POST 请求将变化信息发送到 Nginx 内部运行的 Lua 程序进行处理，实现对 Nginx Upstream 中后端 Pod IP 变化的动态修改。

　　每个后端 Pod 的 IP 及 targetPort 信息都存储在 Nginx 的共享内存区域，Nginx 对每个获取的请求将使用配置的负载均衡算法进行转发，Nginx 的配置中应用 Lua 模块的 balancer_by_lua 功能实现 upstream 指令域的动态操作，Pod IP 变化及资源对象 Ingress 对 upstream 指令域相关注解（annotation）的变化无须执行 Nginx 的 reload 操作。

　　当 Ingress 控制器监控的其他资源对象变化时，会对当前变化的内容创建 Nginx 配置模型，如果新的配置模型与当前运行的 Nginx 配置模型不一致，则将新的配置模型按照模板生成新的 Nginx 配置，并对 Nginx 执行 reload 操作。

　　Nginx 配置模型避免了 Nginx 的无效 reload 操作。为避免因 Nginx 配置语法错误导致意外中断，Ingress 控制器为 Nginx 的配置内容提供了冲突检测及合并机制，Ingress 控制器使用了准入控制插件（Validating Admission Webhook）做验证 Ingress 配置语法的准入控制，验证通过的 Ingress 资源对象才会被保存在存储服务 etcd 中，并被 Ingress 控制器生成确保没有语法错误的 Nginx 配置文件。

 

1.2 集成的第三方模块

　　Kubernetes 的 Nginx Ingress 当前版本是 0.25.1，其集成了 Nginx 的扩展版本 Open-Resty 的 1.15.8.1 版本，OpenResty 的最大特点是集成了 Lua 脚本的嵌入式编程功能，基于 Nginx 的优化，使 Nginx 具有更强的扩展能力。

　　Nginx Ingress 通过 Lua 脚本编程，利用 OpenResty 的 balancer_by_lua 模块，可通过 nginx-ingress 控制器动态地修改 Nginx 上游服务器组的配置，无须 Nginx 进程的热加载，有效地解决了因 Pod 调度带来的 Pod IP 变化的问题。

　　Kubernetes 的 Nginx Ingress 在 OpenResty 基础上还集成了诸多的第三方模块，模块功能介绍如下。

　　1) Ajp协议模块（nginx_ajp_module）

　　Ajp 协议模块是一个使 Nginx 实现 Ajp 协议代理的模块，该模块可以使 Nginx 通过 Ajp 协议连接到被代理的 Tomcat 服务。

　　模块网址：https://github.com/nginx-modules/nginx_ajp_module

　　2) InfluxDB输出模块（nginx-influxdb-module）

　　InfluxDB 输出模块可以使 Nginx 的每次请求记录以 InfluxDB 作为后端进行存储，其以非阻塞的方式对每个请求进行过滤，并使用 UDP 协议将处理后的数据发送到 InfluxDB 服务器。可以通过该模块实时监控 Nginx 的所有请求，获得每个请求的连接类型、请求状态，并通过 InfluxDB 实现相关故障状态的报警。

　　模块网址：https://github.com/influxdata/nginx-influxdb-module

　　3) GeoIP2数据库模块（ngx_http_geoip2）

　　MaxMind 的 GeoIP 数据库已经升级到第二代，GeoIP2 数据库提供了准确的 IP 信息，包括 IP 地址的位置（国家、城市、经纬度）等数据。该模块增加了 GeoIP2 数据的支持。

　　模块网址：https://github.com/nginx-modules/ngx_http_geoip2_module

　　4) 摘要认证模块（nginx-http-auth-digest）

　　摘要认证模块使 Nginx 的基本认证功能增加了摘要认证（Digest Authentication）的支持，这是一种简单的身份验证机制，是对基本认证的一种安全改进，仅通过服务端及客户端根据用户名和密码计算的摘要信息进行验证，避免了密码的明文传递，增加了认证过程的安全性。

　　模块网址：https://github.com/nginx-modules/nginx-http-auth-digest

 

　　5) 内容过滤模块（ngx_http_substitutions_filter_module）

　　内容过滤模块是一个内容过滤功能的模块，其相对于 Nginx 自带的内容过滤模块（ngx_http_sub_module）增加了正则匹配的替换方式。

　　模块网址：https://github.com/nginx-modules/ngx_http_substitutions_filter_module

　　6) 分布式跟踪模块（nginx-opentracing）

　　OpenTracing 由 API 规范、实现该规范的框架和库以及项目文档组成，是一个轻量级的标准化规范，其位于应用程序和跟踪分析程序之间，解决了不同分布式追踪系统API不兼容的问题。OpenTracing 允许开发人员使用 API 向应用程序代码中添加工具，实现业务应用中的分布式请求跟踪。　　

　　分布式请求跟踪，也称分布式跟踪，是一种用于分析和监视应用程序的方法，特别是那些使用微服务体系结构构建的应用程序。分布式跟踪有助于查明故障发生的位置以及导致性能低下的原因。该模块是将 Nginx 的请求提供给 OpenTracing 项目的分布式跟踪系统用于应用的请求分析和监控。

　　Nginx Ingress 中集成了 jaeger 和 zipkin 两种分布式跟踪系统的 OpenTracing 项目插件，用户可根据实际情况进行选择使用。

　　模块网址：https://github.com/opentracing-contrib/nginx-opentracing

　　7) Brotli压缩模块（ngx_brotli）

　　Brotli 是 Google 推出的侧重于 HTTP 压缩的一种开源压缩算法，它使用 lz77 算法的现代变体、Huffman 编码和基于上下文的二阶建模的组合来压缩数据。在与 Deflate 相似的压缩与解压缩速度下，增加了 20% 的压缩密度。在与 gzip 的测试下，因压缩密度高其消耗的压缩时间要比 gzip 多，但在客户端解压的时间则相当。

　　模块网址：https://github.com/google/ngx_brotli

　　8) ModSecurity连接器模块（ModSecurity-nginx）

　　ModSecurity 是一个开源的 Web 应用防火墙，其主要作用是增强 Web 应用的安全性并保护 Web 应用免受攻击。模块 ModSecurity-nginx 是一个 Nginx 的 ModSecurity 连接器，其提供了 Nginx 和 libmodsecurity（ModSecurity v3）之间的通信通道。Nignx Ingress 中已经集成了 ModSecurity 和 　　OWASP 规则集，在 Nginx 配置文件目录可以查看相关配置。

　　模块网址：https://github.com/nginx-modules/ModSecurity-nginx

　　9) lua-resty-waf模块

　　lua-resty-waf 是一个基于 OpenResty 的高性能 Web 应用防火墙，它使用 Nginx Lua API 及灵活的规则架构分析和处理 HTTP 请求信息，并不断开发和测试一些自定义的规则补丁来应对不断出现的新的安全威胁。lua-resty-waf 提供了 ModSecurity 兼容的规则语法，支持 ModSecurity 现有规则的自动转换，用户无须学习新的语法规则就可以扩展 lua-resty-waf 的规则。

　　模块网址：https://github.com/p0pr0ck5/lua-resty-waf。

 

2.Nginx Ingress安装部署

2.1 HELM方式安装部署

　　Helm 是一个非常方便的 Kubernetes 应用部署工具，支持 Nginx Ingress 的快速部署和卸载。通过 Helm 可快速将 Nginx Ingress 部署在 Kubernetes 集群中，Helm 中 Nginx Ingress 的 1.19.1 版本 Chart 部分参数如下表所示。

参数	参数值选项	默认值	功能说明
controller.service.type	ClusterIP 或 NodePort 或 LoadBalancer	LoadBalancer	设置资源对象 Service 的服务类型
controller.hostNetwork	true 或 false	false	设置资源对象 Pod 是否以 hostNet-work方式运行
controller.service.externalIPs	--	--	设置资源对象 Service externalIPs 的 IP 地址
controller.kind	Deployment 或 Daemon-Set	Deployment	设置部署方式
controller.service.external-TrafficPolicy	Local 或 Cluster	Cluster	设置 Pod 流量调度方式
rbac.create	true 或 false	false	是否为 nginx-ingress 创建 RBAC 资源
controller.autoscaling.enabled	true 或 false	false	是否启用多副本支持，启用后最小副本数为 1，最大值为 11
controller.autoscaling.min-Replicas	--	1	设置创建的最小副本数
controller.metrics.enabled	true 或 false	false	是否启用 Prometheus Exporter
controller.containerPort.http	--	80	Nginx Ingress 的默认 HTTP 端口
controller.containerPort.https	--	443	Nginx Ingress 的默认 HTTP 端口

helm install --name nginx-ingress stable/nginx-ingress --set rbac.create=true

　　具体说明如下：

• • Helm 安装的应用名称为 nginx-ingress；
  • rbac.create 参数用以为 nginx-ingress 创建 RBAC 资源，获取与接口服务的访问授权。

 

　　Nginx Ingress 以 Pod 形式运行在 Kubernetes 集群中，用户可根据 Kubernetes 的网络通信特点以及实际场景选择灵活的部署方式进行 Nginx Ingress 的部署，此处分别以基于资源对象 Service 的 NodePort 方式和 Pod 的 hostNetwork 方式举例介绍。

　　1) Service的NodePort方式

　　以 NodePort 类型部署 Nginx Ingress，需要使用参数进行指定 controller.service.type 为 NodePort。为便于管理，可以为 Nginx Ingress 创建单独使用的命名空间 nginx-ingress，部署拓扑如下图所示。

　　　　　　　　　　　　　　　　图：NodePort方式

　　部署命令如下：

# 安装nginx-ingress
helm install --name nginx-ingress \
             --namespace nginx-ingress \
             stable/nginx-ingress \
             --set "rbac.create=true,controller.autoscaling.enabled=true,controller. autoscaling.minReplicas=2,controller.service.type=NodePort,con-troller.service.externalTrafficPolicy=Local"

# 也可以在创建后调整副本数
kubectl scale --replicas=3 deployment/nginx-ingress

　　具体说明如下：

• • Helm 安装的应用名称为 nginx-ingress，命名空间为 nginx-ingress；
  • 以默认的 Deployment 方式部署，设置 Pod 副本数为 2，并以 Service 的 NodePort 方式对外发布服务，设置流量调度策略为 Local；
  • Kubernetes 将为 nginx-ingress Service 随机创建范围在 30000～32767 之间的 Node-Port 端口；
  • 用户将 Kubernetes 中节点 IP 和 NodePort 手动添加到传输层负载均衡中的虚拟服务器集群中；
  • 外部请求发送到传输层负载均衡虚拟服务器，传输层负载将请求数据转发到 Kubernetes 集群节点的 NodePort；
  • NodePort 类型的 Service 将请求负载到对应的 Nginx Pod；
  • Nginx 将用户请求进行应用层负载转发到配置的应用 Pod；
  • 在该部署方式下，Nginx Pod 需要使用 Local 的流量调度策略，获取客户端的真实 IP。

 

　　2) Pod的hostNetwork方式

　　主机网络（hostNetwork）方式可以使 Pod 与宿主机共享网络命名空间，外网传输效率最高。因 Pod 直接暴露外网，虽然存在一定的安全问题，但不存在客户端源 IP 隐藏的问题，部署拓扑如下图所示。

　　　　　　　　　　　　　　　　　　图：hostNetwork方式

　　部署命令如下：

# 以Deployment方式部署

helm install --name nginx-ingress \

             --namespace nginx-ingress \

             stable/nginx-ingress \

             --set "rbac.create=true,controller.service.type=ClusterIP,controller. hostNetwork=true"

　　具体说明如下：

• • Deployment 方式部署时，Nginx Ingress 的 Service 设置类型为 ClusterIP，仅提供内部服务端口；
  • 用户将 Kubernetes 中节点 IP 及 80、443 端口手动添加到传输层负载均衡中的虚拟服务器集群中；
  • 用户请求经传输层负载均衡设备转发到 Nginx，Nginx 将用户请求负载到 Kubernetes 集群内的 Pod 应用。

　　也可以使用 DaemonSet 部署方式，在集群中的每个节点自动创建并运行一个 Nginx Ingress Pod，实现 Nginx Ingress 的自动扩展。

# 以DaemonSet方式部署nginx-ingress并成为集群唯一入口
helm install --name nginx-ingress \
             --namespace nginx-ingress \
             stable/nginx-ingress \
             --set "rbac.create=true,controller.kind=DaemonSet,controller.service.type=ClusterIP,controller.hostNetwork=true"

 

　　3) SSL终止（SSL Termination）和SSL透传（SSL Passthrough）

　　SSL 终止模式下，客户端的 TLS 数据会在代理服务器 Nginx 中解密，解密的数据由代理服务器直接或再次 TLS 加密后传递给被代理服务器，这种模式下，相对增加代理服务器的计算负担，但方便了 SSL 证书的统一管理。

　　SSL 透传模式下，Nginx 不会对客户端的 HTTPS 请求进行解密，加密的请求会被直接转发到后端的被代理服务器，这种方式常被应用到后端的 HTTPS 服务器需要对客户端进行客户端证书验证的场景，相对也会降低 Nginx 对 TLS 证书加解密的负担。由于请求数据是保持加密传输的，HTTP 消息头将无法修改，所以消息头字段 X-forwarded-* 的客户端 IP 无法被添加。Nginx Ingress 默认部署方式没有开启 SSL 透传的支持，需要在部署时使用参数 --enable-ssl-passthrough 进行开启。

# 修改部署资源对象nginx-ingress-controller
kubectl edit Deployment/nginx-ingress-controller -n nginx-ingress

# 在规范部分添加容器启动参数--enable-ssl-passthrough
    spec:
        containers:
        - args:
          - /nginx-ingress-controller
          - --default-backend-service=nginx-ingress/nginx-ingress-default-backend
          - --election-id=ingress-controller-leader
          - --ingress-class=nginx
          - --configmap=nginx-ingress/nginx-ingress-controller
          - --enable-ssl-passthrough

 

　　4) 卸载Nginx Ingress

　　Nginx 的配置是以资源对象 ConfigMap 和 Ingress 方式存储在 etcd 服务中的，所以即便删除或重新部署 Nginx Ingress 也不会影响之前的配置。

helm delete --purge nginx-ingress

 

2.2 手动方式安装部署

　　手动方式不做过多解释，简单来说找到想要安装的版本，直接应用其中的mandatory.yaml即可，当然，也可以根据自己的需求更改yaml文件

　　Git地址为以下: https://github.com/kubernetes/ingress-nginx/blob/nginx-0.30.0/deploy/static/mandatory.yaml

 

3.Nginx Ingress配置映射ConfigMap

　　通过 Helm 安装 Nginx Ingress 的默认关联配置映射实例名称为 nginx-ingress-controller，用户可以通过修改资源对象 Deployment/DaemonSet 实例 nginx-ingress-controller 中的参数 --configmap 自定义关联配置映射实例的名称。

　　当然，手动增加configmap，只要写上对应的ingress的labels也可以。

　　Nginx Ingress 控制器约定 Nginx Ingress 配置映射实例中的键值只能是字符串，即便是数字或布尔值时也要以字符串的形式书写，比如 "true"、"false"、"100"，"[]string" 或 "[]int" 的 Slice 类型则表示内部数据是以 "," 分隔的字符串。根据配置涉及的功能可以有如下分类。

 

3.1 Nginx原生配置指令

　　用以提供向 Nginx 配置中添加 Nginx 原生配置指令，功能说明如下表所示。

名称	类型	默认值	功能描述
main-snippet	string	""	在 main 指令域添加 Nginx 配置指令
http-snippet	string	""	在 http 指令域添加 Nginx 配置指令
server-snippet	string	""	在 server 指令域添加 Nginx 配置指令
location-snippet	string	""	在 location 指令域添加 Nginx 配置指令

　　配置样例如下：

echo '
apiVersion: v1
kind: ConfigMap
data:
    http-snippet: |
        ancient_browser "UCWEB";
        ancient_browser_value oldweb;
        server {
            listen 8080;
            if ($ancient_browser) {
                rewrite ^ /${ancient_browser}.html; # 重定向到oldweb.html
            }
        }
metadata:
    name: nginx-ingress-controller
    namespace: nginx-ingress
' | kubectl create -f -

 

3.2 通用配置

　　提供 Nginx 核心配置相关配置指令的配置，功能说明如下表所示。

名称	类型	默认值	Nginx 指令	功能描述
worker-processes	string	auto	worker_processes	参见《Nginx进程配置指令》一节
worker-cpu-affinity	string	""	worker_cpu_affinity	参见《Nginx进程配置指令》一节
worker-shutdown-timeout	string	10s	worker_shutdown_timeout	参见《Nginx进程配置指令》一节
max-worker-connections	string	--	worker_connections	参见《Nginx进程配置指令》一节
max-worker-open-files	string	--	worker_rlimit_nofile	参见《Nginx进程配置指令》一节
enable-multi-accept	bool	true	multi_accept	参见《Nginx进程配置指令》一节
keep-alive	int	75	keepalive_timeout	--
keep-alive-requests	int	100	keepalive_requests	--
variables-hash-bucket-size	int	128	variables_hash_bucket_size	--
variables-hash-max-size	int	2048	variables_hash_max_size	--
server-name-hash-max-size	int	1024	server_names_hash_max_size	--
server-name-hash-bucket-size	int	CPU 缓存行的大小	server_names_hash_bucket_size	--
map-hash-bucket-size	int	64	map_hash_bucket_size	--
bind-address	[]string	""	listen	设置虚拟主机绑定的 IP 地址
reuse-port	bool	true	listen	设置监听端口启用 reuseport 参数，由 Linux 内核以套接字分片方式实现进程调度
disable-ipv6	bool	false	listen	--
disable-ipv6-dns	bool	false	resolver	设置是否关闭域名解析的 IPv6 地址查找
enable-underscores-in-headers	bool	false	underscores_in_headers	参见《Nginx处理HTTP请求》一节
ignore-invalid-headers	bool	true	ignore_invalid_headers	参见《Nginx处理HTTP请求》一节
client-header-buffer-size	string	1k	client_header_buffer_size	参见《Nginx处理HTTP请求》一节
client-header-timeout	int	60	client_header_timeout	参见《Nginx处理HTTP请求》一节
client-body-buffer-size	string	8k	client_body_buffer_size	参见《Nginx处理HTTP请求》一节
client-body-timeout	int	69	client_body_timeout	参见《Nginx处理HTTP请求》一节
large-client-header-buffers	string	4 8k	large_client_header_buffers	参见《Nginx处理HTTP请求》一节
http-redirect-code	int	308	return	设置 URL 跳转时的响应码，可选项为 301，302，307 和 308
use-geoip	bool	true	--	启用 geoip 功能
use-geoip2	bool	false	--	启用 geoip2 功能，由第三方模块实现
nginx-status-ipv4-whitelist	[]string	127.0.0.1	--	设置允许访问路径 /nginx_status 的 IPv4 地址
nginx-status-ipv6-whitelist	[]string	::1	--	设置允许访问路径 /nginx_status 的 IPv6 地址
server-tokens	bool	true	server_tokens	参见《Nginx处理HTTP请求》一节
lua-shared-dicts	string	""	--	设置 Lua 共享内存字典，Oper_Resty 扩展指令

　　配置样例如下：

cat>test.yaml<<EOF
apiVersion: v1
kind: ConfigMap
data:
    keep-alive:   "60"
    disable-ipv6: "true"
metadata:
    name: nginx-ingress-controller
    namespace: nginx-ingress
EOF

kubectl create -f test.yaml

 

3.3 响应数据配置

　　提供响应信息头修改及响应数据压缩相关功能的配置，功能说明如下表所示。

名称	类型	默认值	Nginx指令	功能描述
add-headers	string	""	add_header	--
use-gzip	bool	true	gzip	启用 gzip
gzip-level	int	5	gzip_comp_level	参见《Nginx开启gzip》一节
gzip-types	string	application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/java-script text/plain text/x-component	gzip_types	参见《Nginx开启gzip》一节
enable-brotli	bool	false	--	设置是否加载 brotli 模块
brotli-level	int	4	--	设置 brotli 的压缩级别
brotli-types	string	application/xml+rss application/atom+xml application/javascript application/x-javascript application/json applica-tion/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/javascript text/plain text/x-com-ponent	--	设置 brotli 的压缩类型

 

3.4 访问控制

　　提供限制连接数、访问速度、访问连接及防火墙的配置，功能说明如下表所示。

名称	类型	默认值	Nginx 指令	功能描述
limit-conn-zone-variable	string	$binary_remote_addr	limit_conn_zone	参见《Nginx并发连接数限制模块》一节
limit-conn-status-code	int	503	limit_conn_status	参见《Nginx并发连接数限制模块》一节
limit-rate	int	0	limit_rate	--
limit-rate-after	int	0	limit_rate_after	--
limit-req-status-code	int	503	limit_req_status	参见《Nginx并发连接数限制模块》一节
whitelist-source-range	[]string []string{}	--	allow	设置允许访问的源 IP 地址
block-cidrs	[]string	""	deny	禁止设置 IP 地址的访问
block-user-agents	[]string	""	map	禁止设置信息头字段 User-Agent 匹配值的访问
block-referers	[]string	""	map	禁止设置信息头字段 Referer 匹配值的访问
enable-modsecurity	bool	false	--	设置是否加载 Mod-Security 连接模块
enable-owasp-modsecurity-crs	bool	false	--	设置是否加载 OWASP ModSecurity 核心规则库

 

3.5 HTTPS配置

　　提供与 HTTPS 相关的配置，功能说明如下表所示。

名称	类型	默认值	Nginx指令	功能描述
ssl-ciphers	string	ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384: ECDHE-ECDSA-CHACHA20-POLY-1305:ECDHE-RSA-CHACHA20-POLY1305: ECDHE-ECDSA-AES128-GCM-SHA256：ECDHE-RSA-AES128-GCM-SHA256: ECDHE-ECDSA-AES256-SHA-384：ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA -AES-128-SHA256:ECDHE-RSA-AES-128-SHA256	ssl-ciphers	参见《Nginx HTTPS服务器搭建》一节
ssl-ecdh-curve	string	auto	ssl_ecdh_curve	参见《Nginx HTTPS服务器搭建》一节
ssl-dhparam	string	""	ssl_dhparam	参见《Nginx HTTPS服务器搭建》一节
ssl-protocols	string	TLSv1.2	ssl_protocols	参见《Nginx HTTPS服务器搭建》一节
ssl-early-data	bool	true	ssl_early_data	参见《Nginx HTTPS服务器搭建》一节
ssl-session-cache	bool	true	ssl_session_cache	参见《Nginx HTTPS服务器搭建》一节
ssl-session-cache-size	string	10m	ssl_session_cache	参见《Nginx HTTPS服务器搭建》一节
ssl-session-tickets	bool	true	ssl_session_tickets	参见《Nginx HTTPS服务器搭建》一节
ssl-session-ticket-key	string	--	ssl_session_tickets	参见《Nginx HTTPS服务器搭建》一节
ssl-session-timeout	string	10m	ssl_session_timeout	参见《Nginx HTTPS服务器搭建》一节
ssl-buffer-size	string	4k	ssl_buffer_size	参见《Nginx HTTPS服务器搭建》一节
ssl-redirect	bool	true	--	当被配置的虚拟主机启用了 TLS 支持，则将虚拟主机的 HTTP 请求跳转到 HTTPS 请求
no-tls-redirect-locations	string	/.well-known/acme-challenge	--	一个以“,”分隔的 location 列表，对列表中 location 的 HTTP 请求永远不会跳转到 HTTPS 请求

 

3.6 HSTS配置

　　HSTS（HTTP Strict Transport Security）是一种新的 Web 安全协议，HSTS 配置启用后，将强制客户端使用 HTTPS 协议与服务器建立连接，配置映射提供的 HSTS 功能配置功能说明如下表所示。

名称	类型	默认值	Nginx指令	功能描述
hsts	bool	true	add_header	是否运行 SSL 时在消息头中添加 HSTS 属性字段
hsts-include-subdomains	bool	true	add_header	是否在当前域名的所有子域中启用 HSTS
hsts-max-age	string	15724800	add_header	设置 HSTS Header 的过期时间
hsts-preload	bool	false	add_header	设置是否启用 HSTS 的预加载支持

 

3.7 认证转发配置

　　提供认证转发功能的全局配置，功能说明如下表所示。

名称	类型	默认值	Nginx指令	功能描述
global-auth-url	string	""	auth_request	设置外部身份验证的 URL
global-auth-method	string	""	proxy_method	外部认证 URL 的 HTTP 方法
global-auth-signin	string	""	--	当外部认证返回 401 时跳转的 URL，通常为提示输人用户名和密码的 URL
global-auth-response-headers	string	""	--	设置认证请求完成后传递到真实后端的头信息
global-auth-request-redirect	string	""	--	设置发送给认证服务器请求头中 X-Auth-Request-Redirect 的值
global-auth-snippet	string	""	--	可以自定义在外部认证指令区域添加 Nginx 配置指令
global-auth-cache-key	string	""	--	启用认证缓存，并设置认证缓存的关键字
global-auth-cache-duration	string	200 202 401 5m	--	基于响应码设置认证缓存的有效时间
no-auth-locations	string	/.well-known/acme-challenge	--	一个以“,”分隔的 location 列表，列表中被记录的请求将不进行身份认证

 

3.8 代理配置

　　设置 Nginx 的代理功能配置，相关配置说明如下表所示。

名称	类型	默认值	Nginx指令	功能描述
retry-non-idempotent	bool	false	proxy_next_upstream	参见《Nginx HTTP代理服务器》一节
proxy-set-header	string	""	proxy_set_header	参见《Nginx HTTP代理服务器》一节
proxy-headers-hash-max-size	int	512	proxy_headers_hash_max_size	参见《Nginx HTTP代理服务器》一节
proxy-headers-hash-bucket-size	int	64	proxy_headers_hash_bucket_size	参见《Nginx HTTP代理服务器》一节
hide-headers	string array	empty	proxy_hide_header	参见《Nginx HTTP代理服务器》一节
proxy-body-size	string	1m	client_max_body_size	--
allow-backend-server-header	bool	false	proxy_pass_header	设置是否允许将被代理服务器的消息头字段 Server 的值代替 Nginx 的默认值返回给客户端
proxy-connect-timeout	int	5	proxy_connect_timeout	参见《Nginx HTTP代理服务器》一节
proxy-read-timeout	int	60	proxy_read_timeout	参见《Nginx HTTP代理服务器》一节
proxy-send-timeout	int	60	proxy_send_timeout	参见《Nginx HTTP代理服务器》一节
proxy-buffers-number	int	4	proxy_buffers	参见《Nginx HTTP代理服务器》一节
proxy-buffer-size	string	4k	proxy_buffer_size	参见《Nginx HTTP代理服务器》一节
proxy-cookie-path	string	off	proxy_cookie_path	参见《Nginx HTTP代理服务器》一节
proxy-cookie-domain	string	off	proxy_cookie_domain	参见《Nginx HTTP代理服务器》一节
proxy-next-upstream	string	error timeout	proxy_next_upstream	参见《Nginx HTTP代理服务器》一节
proxy-next-upstream-timeout	int	0	proxy_next_upstream_timeout	参见《Nginx HTTP代理服务器》一节
proxy-next-upstream-tries	int	3	proxy_next_upstream_tries	参见《Nginx HTTP代理服务器》一节
proxy-redirect-from	string	off	proxy_redirect	此处为添加要替换的源文本
proxy-redirect-to	string	off	proxy_redirect	此处为添加要替换的目标文本
proxy-request-buffering	string	on	proxy_request_buffering	参见《Nginx HTTP代理服务器》一节
proxy-buffering	string	off	proxy_buffering	参见《Nginx HTTP代理服务器》一节
proxy-add-original-uri-header	bool	true	proxy_set_header	为发送到后端的请求头添加一个头属性字段 X-Original-Uri，记录原始请求
use-forwarded-headers	bool	false	proxy_set_header	设置是否使用传入的头属性字段 X-Forwarded
forwarded-for-header	string	X-Forwarded-For	proxy_set_header	设置用于标识客户端源 IP 的头属性字段名称 X-For-warded
compute-full-forwarded-for	bool	false	proxy_set_header	设置是否将远程地址附加到头属性字段 X-For-warded-For 中，而不是替换它
custom-http-errors	[]int	off	error_page	该配置会自动启用 Nginx 配置指令 proxy_intercept_errors，默认是关闭的
proxy-stream-timeout	string	600s	proxy_timeout	参见《Nginx TCP/UDP代理》一节
proxy-stream-responses	int	1	proxy_responses	参见《Nginx TCP/UDP代理》一节
use-proxy-protocol	bool	false	listen	启用 proxy_protocol 支持
proxy-protocol-header-timeout	string	5d	proxy_protocol_timeout	设置接收 proxy-protocol 头的超时时间，可防止 TLS 传递处理程序无限期地等待已断开的连接
proxy-real-ip-cidr	[]string	0.0.0.0/0	set_real_ip_from	当启用 proxy-protocol 时设置授信 IP，用于后端获得真实客户端 IP
use-http2	bool	true	listen	启用 HTTP2 监听
http2-max-field-size	string	4k	http2_max_field_size	参见《Nginx HTTP2模块配置》一节
http2-max-header-size	string	16k	http2_max_header_size	参见《Nginx HTTP2模块配置》一节
http2-max-requests	int	1000	http2_max_requests	参见《Nginx HTTP2模块配置》一节

 

3.9 负载均衡配置

　　Nginx Ingress 为方便上游服务器组的动态管理，其基于 Lua 实现了轮询调度及峰值指数加权移动平均（Peak Exponentially Weighted Moving-Average，Peak EWMA）负载均衡算法。配置映射的配置为全局负载均衡的配置，详见本节的注解负载均衡说明。配置映射还提供了被代理服务器长连接的配置支持，配置说明如下表所示。

名称	类型	默认值	Nginx指令	功能描述
load-balance	string	round_robin	--	设置负载均衡算法，支持轮询 round_robin 和 Peak EWMA 两种模式， 基于 OpenResty 的 balancer_by_lua 模块实现
upstream-keepalive-connections	int	32	keepalive	参见《Nginx负载均衡模块》一节
upstream-keepalive-timeout	int	60	keepalive_timeout	参见《Nginx负载均衡模块》一节
upstream-keepalive-requests	int	100	keepalive_requests	参见《Nginx负载均衡模块》一节

 

3.10 日志配置

　　设置 Nginx 的日志功能配置，相关配置说明如下表所示。

名称	类型	默认值	Nginx指令	功能描述
disable-access-log	bool	false	access-log	设置 HTTP 指令域 access-log 的指令值为 off
access-log-params	string	""	access-log	设置访问日志的参数
access-log-path	string	/var/log/nginx/access.log	access-log	设置访问日志路径
log-format-escape-json	bool	false	log_format	设置日志格式为 JSON
log-format-upstream	string	%v-[$the_real_ip]-$remote_user[$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_up-stream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id	log_format	HTTP 日志模板
skip-access-log-urls	[]string	[]string{}	access-log	设置不进行访问日志记录的 URL，access-log 的 if 参数
enable-access-log-for-default-backend	bool	false	access-log	是否开启默认后端的访问日志记录
log-format-stream	string	[$time_local] $protocol $status $bytes_sent $bytes_received $session_time	log_format	TCP/UDP 日志模板
error-log-path	string	/var/log/nginx/error.log	error_log	错误日志路径
error-log-level	string	notice	error_log	错误日志级别

 

3.11 分布式跟踪配置

　　设置分布式跟踪功能的配置，配置键及功能描述如下表所示。

名称	类型	默认值	功能描述
generate-request-id	bool	true	如果请求头中没有属性字段 X-Request-ID，则为该请求随机创建一个，用于分布式链路跟踪
enable-opentracing	bool	false	设置是否加载 opentracing 模块，启用分布式跟踪支持
zipkin-collector-host	string	""	设置用于上传跟踪信息的 zipkin 主机地址
zipkin-collector-port	int	9411	设置用于上传跟踪信息的 zipkin 主机端口
zipkin-service-name	string	nginx	设置用于在 zipkin 中创建跟踪的服务名称
zipkin-sample-rate	float	1.0	设置 zipkin 跟踪的采样率
jaeger-collector-host	string	""	设置用于上传跟踪信息的 jaeger 主机地址
jaeger-collector-port	int	6831	设置用于上传跟踪信息的 jaeger 主机端口
jaeger-service-name	string	nginx	设置用于在 jaeger 中创建跟踪的服务名称
jaeger-sampler-type	string	const	设置 jaeger 的采样器名称，可选项为 const、probabilistic、ratelimiting、remote
jaeger-sampler-param	string	1	设置 jaeger 采样器的参数
jaeger-sampler-host	string	http://127.0.0.1	设置 jaeger 采样器为 remote 时的主机地址
jaeger-sampler-port	int	5778	设置 jaeger 采样器为 remote 时的主机端口

 

4.Nginx Ingress注解Annotations

　　Nginx Ingress 注解使用在 Ingress 资源实例中，用以设置当前 Ingress 资源实例中 Nginx 虚拟主机的相关配置，对应配置的是 Nginx 当前虚拟主机的 server 指令域内容。在与 Nginx Ingress 配置映射具有相同功能配置时，将按照所在指令域层级遵循 Nginx 配置规则覆盖。

　　Nginx Ingress注解按照配置功能有如下分类。

 

4.1 Nginx原生配置指令

　　支持在注解中添加 Nginx 原生配置指令。配置说明如下表所示。

注解	类型	功能描述
nginx.ingress.kubernetes.io/server-snippet	string	在 server 指令域添加 Nginx 配置指令
nginx.ingress.kubernetes.io/configuration-snippet	string	在 location 指令域添加 Nginx 配置指令

　　配置样例如下：

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    annotations:
        nginx.ingress.kubernetes.io/server-snippet: |
            location / {
                return 302 /coffee;
            }
spec:
    rules:
    - host: web.nginxbar.org
      http:
            paths:
            - path: /tea
              backend:
                  serviceName: tea-svc
                  servicePort: 80
            - path: /coffee
            backend:
                serviceName: coffee-svc
                servicePort: 80

 

4.2 通用配置

　　Nginx 虚拟主机中的通用配置。通用配置说明如下表所示。

注解	类型	功能描述
nginx.ingress.kubernetes.io/enable-access-log	true 或 false	对当前虚拟主机设置是否启用访问日志，默认为真
nginx.ingress.kubernetes.io/server-alias	string	为 Nginx 添加更多的主机名，同 Nginx 配置指令 server name
nginx.ingress.kubernetes.io/app-root	string	将当前虚拟主机根目录的访问 302 跳转到当前指定的路径
nginx.ingress.kubernetes.io/client-body-buffer-size	string	同 Nginx 配置指令 client_body_buffer_size
nginx.ingress.kubernetes.io/use-regex	true 或 false	是否对当前虚拟主机的 Nginx 指令 location 使用正则方式进行路径匹配，默认值为 false
nginx.ingress.kubernetes.io/custom-http-errors	[]int	根据响应码状态定义为错误状态并跳转到设置的默认后端
nginx.ingress.kubernetes.io/default-backend	string	自定义默认后端的资源对象 Service 名称，当客户端的请求没有匹配的 Nginx 规则或响应错误时，将被转发到默认后端
nginx.ingress.kubernetes.io/whitelist-source-range	CIDR	功能同 ConfigMap 配置键 whitelist-source-range
nginx.ingress.kubernetes.io/permanent-redirect	string	设置永久重定向的目标地址
nginx.ingress.kubernetes.io/permanent-redirect-code	number	自定义永久重定向的响应码，默认为 301
nginx.ingress.kubernetes.io/temporal-redirect	string	设置临时重定向的目标地址
nginx.ingress.kubernetes.io/from-to-www-redirect	true 或 false	设置是否将当前虚拟主机子域名为 www 的请求跳转到当前主机域名
nginx.ingress.kubernetes.io/rewrite-target	URI	同 Nginx 配置指令 rewrite
nginx.ingress.kubernetes.io/enable-rewrite-log	true 或 false	同 Nginx 配置指令 rewrite log，默认为 false
nginx.ingress.kubernetes.io/mirror-uri	string	同 Nginx 配置指令 mirro
nginx.ingress.kubernetes.io/mirror-request-body	true 或 false	同 Nginx 配置指令 mirror_request_body，默认为 true

　　配置样例如下：

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    namespace: default
    annotations:
        nginx.ingress.kubernetes.io/rewrite-target: /tea/$1
        nginx.ingress.kubernetes.io/enable-rewrite-log: "true"
spec:
    rules:
    - host: web.nginxbar.org   # 此service的访问域名
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080
        path: /coffee/(.+)

 

4.3 访问控制

　　用以设置基于流量、请求连接数、请求频率的访问控制。访问控制配置说明如下表所示。

注解	类型/选项	功能描述
nginx.ingress.kubernetes.io/limit-rate	number	访问流量速度限制，同 Nginx 配置指令 limit_rate
nginx.ingress.kubernetes.io/limit-rate-after	number	启用访问流量速度限制的最大值，同 Nginx 配置指令 limit_rate_after
nginx.ingress.kubernetes.io/limit-connections	number	节并发连接数限制，同 Nginx 配置指令 limit_conn
nginx.ingress.kubernetes.io/limit-rps	number	每秒请求频率限制，burst 参数为给定值的 5 倍，响应状态码由 ConfigMap 的 limit-req-status-code 设定
nginx.ingress.kubernetes.io/limit-rpm	number	每分钟请求频率限制，burst 参数为给定值的 5 倍，响应状态码由 ConfigMap 的 limit-req-status-code 设定
nginx.ingress.kubernetes.io/limit-whitelist	CIDR	对以上限制设置基于 IP 的白名单

 

4.4 认证管理

　　Nginx Ingress 提供了基本认证、摘要认证和外部认证 3 种方式，为被代理服务器提供认证支持。认证管理配置说明如下表所示。

注解	类型	功能描述
nginx.ingress.kubernetes.io/enable-global-auth	true 或 false	如果 ConfigMap 的 global-auth-url 被设置，Nginx 会将所有的请求重定向到提供身份验证的 URL，默认为 true
nginx.ingress.kubernetes.io/satisfy	string	同 Nginx 配置指令 satisfy
nginx.ingress.kubernetes.io/auth-type	basic 或 digest	设置 HTTP 认证类型，支持基本和摘要两种类型
nginx.ingress.kubernetes.io/auth-secret	string	指定关联资源对象 secret 的名称
nginx.ingress.kubernetes.io/auth-realm	string	设置基本认证的提示信息 auth_basic
nginx.ingress.kubernetes.io/auth-url	string	设置提供外部身份认证的 URL，由 Nginx 配置指令 auth_request 提供该功能
nginx.ingress.kubernetes.io/auth-signin	string	设置当外部认证返回 401 时跳转的 URL，通常为提示输入用户名和密码的 URL
nginx.ingress.kubernetes.io/auth-method	string	指定访问外部认证 URL 的 HTTP 方法，由 Nginx 配置指令 proxy_method 提供该功能
nginx.ingress.kubernetes.io/auth-request-redirect	string	设置发送给认证服务器请求头中 X-Auth-Request-Redirect 的值
nginx.ingress.kubernetes.io/auth-cache-key	string	启用认证缓存，并设置认证缓存的关键字
nginx.ingress.kubernetes.io/auth-cache-duration	string	基于响应码设置认证缓存的有效时间
nginx.ingress.kubernetes.io/auth-response-headers	string	设置认证请求完成后传递到真实后端的头信息
nginx.ingress.kubernetes.io/auth-snippet	string	可以自定义在外部认证指令区域添加 Nginx 配置指令

　　基本认证配置如下：

# 创建基本认证用户名nginxbar、密码123456，输出文件名必须是auth
htpasswd -bc auth nginxbar 123456

# 创建资源对象secret保存账号和密码
kubectl create secret generic basic-auth --from-file=auth

# 查看创建的basic-auth
kubectl get secret basic-auth -o yaml

# 创建基本认证的Ingress实例
cat>auth-nginxbar-org.yaml<<EOF
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: auth-nginxbar-org
    namespace: default
    annotations:
        # 设置认证类型
        nginx.ingress.kubernetes.io/auth-type: basic
        # 关联账号和密码
        nginx.ingress.kubernetes.io/auth-secret: basic-auth
        # 显示认证提示信息
        nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required for web.nginxbar.org'
spec:
    rules:
    - host: auth.nginxbar.org   # 此service的访问域名
      http:
          paths:
          - backend:
              serviceName: nginx-web
              servicePort: 8080
EOF

kubectl create -f auth-nginxbar-org.yaml

　　认证转发配置样例如下：

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: auth-nginxbar-org
    namespace: default
    annotations:
        nginx.ingress.kubernetes.io/auth-url: "http://$host/auth2"
        nginx.ingress.kubernetes.io/auth-signin: "http://$host/auth/start"
        nginx.ingress.kubernetes.io/auth-method: "POST"
        nginx.ingress.kubernetes.io/auth-cache-key: "foo",
        nginx.ingress.kubernetes.io/auth-cache-duration": "200 202 401 30m"
        nginx.ingress.kubernetes.io/auth-snippet: |
            proxy_set_header Foo-Header 42;
spec:
    rules:
    - host: auth.nginxbar.org   # 此service的访问域名
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080

 

4.5 跨域访问

　　跨域访问功能配置说明如下表所示。

注解	类型	功能描述
nginx.ingress.kubernetes.io/enable-cors	true 或 false	是否启用跨域访问支持，默认为 false
nginx.ingress.kubernetes.io/cors-allow-origin	string	允许跨域访问的域名，默认为 *，表示接受任意域名的访问
nginx.ingress.kubernetes.io/cors-allow-methods	string	允许跨域访问方法，默认为 GET、PUT、POST、DELETE、PATCH、OPTIONS
nginx.ingress.kubernetes.io/cors-allow-headers	string	允许跨域访问的请求头，默认为 DNT，X-CustomHeader、Keep-Alive、User-Agent、X-Requested-With、 If-Modified-Since、Cache-Control、Content-Type、Authorization
nginx.ingress.kubernetes.io/cors-allow-credentials	true 或 false	设置在响应头中 Access-Control-Allow-Credentials 的值，设置是否允许客户端携带验证信息，如 cookie 等，默认为 true
nginx.ingress.kubernetes.io/cors-max-age	number	设置响应头中 Access-Control-Max-Age 的值，设置返回结果可以用于缓存的最长时间，默认为 1728000 秒

　　配置样例如下：

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    namespace: default
    annotations:
        nginx.ingress.kubernetes.io/cors-allow-headers: >-
            DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,
            If-Modified-Since,Cache-Control,Content-Type,Authorization
        nginx.ingress.kubernetes.io/cors-allow-methods: 'PUT, GET, POST, OPTIONS'
        nginx.ingress.kubernetes.io/cors-allow-origin: '*'
        nginx.ingress.kubernetes.io/enable-cors: "true"
        nginx.ingress.kubernetes.io/cors-max-age: 600
spec:
    rules:
    - host: web.nginxbar.org
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080
          path: /

 

4.6 代理配置

　　Nginx 代理相关功能配置说明如下表所示。

注解	类型/选项	功能描述
nginx.ingress.kubernetes.io/service-upstream	true 或 false	默认 Nginx 以 Service 中 Pod 的 IP 和端口为 Upstream 中的成员列表，该参数为 true 时，将以 Service 的 ClusterIP 和端口为被代理入口， 该功能避免了因 Pod 漂移带来的 Upstream 的配置变化
nginx.ingress.kubernetes.io/backend-protocol	http 或 HTTPS 或 GRPC 或 GRPCS 或 AJP 或 FCGI	设置代理后端服务器的代理协议类型，默认为 HTTP
nginx.ingress.kubernetes.io/proxy-body-size	string	同 Nginx 配置指令 client_max_body-size，默认为 1m
nginx.ingress.kubernetes.io/proxy-cookie-do-main	string	同 Nginx 配置指令 proxy_cookie_domain
nginx.ingress.kubernetes.io/proxy-cookie-path	string	同 Nginx 配置指令 proxy_cookie_path
nginx.ingress.kubernetes.io/proxy-connect-timeout	number	同 Nginx 配置指令 proxy_connect_timeout
nginx.ingress.kubernetes.io/proxy-send-time-out	number	同 Nginx 配置指令 proxy_send_timeout
nginx.ingress.kubernetes.io/proxy-read-time-out	number	同 Nginx 配置指令 proxy_read_timeout
nginx.ingress.kubernetes.io/proxy-next-up-stream	string	同 Nginx 配置指令 proxy_next_upstream
nginx.ingress.kubernetes.io/proxy-next-up-stream-timeout	number	同 Nginx 配置指令 proxy_next_upstream_timeout
nginx.ingress.kubernetes.io/proxy-next-up-stream-tries	number	同 Nginx 配置指令 proxy_next_upstream_tries
nginx.ingress.kubernetes.io/proxy-buffering	string	同 Nginx 配置指令 proxy_buffering
nginx.ingress.kubernetes.io/proxy-buffers-number	number	同 Nginx 配置指令 proxy_buffers
nginx.ingress.kubernetes.io/proxy-buffer-size	string	同 Nginx 配置指令 proxy_buffer_size
nginx.ingress.kubernetes.io/proxy-request-buffering	string	同 Nginx 配置指令 proxy_request_buffering
nginx.ingress.kubernetes.io/proxy-http-ver-sion	1.0 或 1.1	同 Nginx 配置指令 proxy_http_version，默认为 1.1
nginx.ingress.kubernetes.io/upstream-vhost	string	自定义发送到上游服务器的信息头字段中 Host 的内容，相当于 Nginx 配置指令 proxy_set_header Host $host 的设置
nginx.ingress.kubernetes.io/proxy-redirect-from	string	设置要替换的源文本，同 Nginx 配置指令 proxy_redirect
nginx.ingress.kubernetes.io/proxy-redirect-to	string	设置要替换的目标文本，同 Nginx 配置指 proxy redirect
nginx.ingress.kubernetes.io/connection-proxy-header	string	设置发送到被代理服务器请求头中字段属性 connection 的值，相当于 Nginx 配置指令 proxy_set_header Connection 的状态为 Keep-Alive
nginx.ingress.kubernetes.io/x-forwarded-prefix	string	创建并设置代理请求头属性字段 X-Forwarded-Prefix 属性，用以向后端传递请求路径
nginx.ingress.kubernetes.io/http2-push-pre-load	true 或 false	同 Nginx 配置指令 http2-push-preload，默认值为 false

 

4.7 负载均衡

　　为方便上游服务器组的动态管理，Nginx Ingress 基于 Lua 实现了一致性哈希、基于子集的一致性哈希、轮询调度及峰值指数加权移动平均（Peak Exponentially Weighted Moving-Average，Peak EWMA）负载均衡算法。负载均衡配置说明如下表所示。

注解	类型/选项	功能描述
nginx.ingress.kubernetes.io/upstream-hash-by	string	同 Nginx 配置指令 hash，此处默认为一致性哈希负载算法， 允许除了客户端 IP 或 cookie 之外的会话粘连
nginx.ingress.kubernetes.io/upstream-hash-by-subset	true 或 false	设置是否使用子集模式的一致性哈希负载算法，默认为 false
nginx.ingress.kubernetes.io/upstream-hash-by-subset-size	int	设置子集模式中上游服务器分组的大小，默认为 3
nginx.ingress.kubernetes.io/load-balance	round_robin 或 ewma	设置负载均衡算法，基于 balancer_by_lua 模块实现， 支持轮询和 Peak EWMA 两种负载算法

　　子集模式的一致性哈希负载算法是将上游服务器组中的被代理服务器分成固定数量的分组，然后把每个分组当作一致性哈希计算的虚拟节点。默认一致性哈希是按照每个被代理服务器为虚拟节点进行计算的。

　　Peak EWMA 负载均衡算法，是对每个 Pod 请求的往返延时（Round-Trip Time，RTT）计算移动平均值，并用该 Pod 的未完成请求数对这个平均值加权计算，计算值最小的 Pod 端点将被分配新的请求。

4.8 会话保持配置

　　设置基于 cookie 的会话亲缘关系，也就是会话保持功能。启用基于 cookie 的会话保持功能时，可以使同一客户端的请求始终转发给同一后端服务器。Nginx Ingress 对启用会话保持功能的 Service 集群使用一致性哈希负载算法，即使后端 Pod 数量变化，也不会对会话保持功能产生太大的影响。会话保持配置说明如下表所示。

注解	类型	功能描述
nginx.ingress.kubernetes.io/affinity	cookie	设置会话保持类型，目前只有 cookie 类型
nginx.ingress.kubernetes.io/session-cookie-name	string	设置 cookie 名称，默认为 INGRESSCOOKIE
nginx.ingress.kubernetes.io/session-cookie-path	string	设置 cookie 字段 path 的值，默认值为当前资源实例 path 的设置。如果启用 use-regex 功能， 使用正则匹配时，必须单独指定，不能使用默认值
nginx.ingress.kubernetes.io/session-cookie-max-age	--	设置 cookie 字段 max-age 的值，表示 cookie 过期时间
nginx.ingress.kubernetes.io/session-cookie-expires	--	为兼容旧的浏览器，设置 cookie 字段 expires 的值，表示 cookie 过期时间
nginx.ingress.kubernetes.io/session-cookie-change-on-failure	true 或 false	当会话保持的被代理服务器请求失败时，如果设置值为 true，则将下次请求更改为向另一台被代理服务器转发， 否则继续向当前被代理服务器转发请求

　　配置样例如下：

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    annotations:
        nginx.ingress.kubernetes.io/affinity: "cookie"
        nginx.ingress.kubernetes.io/session-cookie-name: "route"
        nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
        nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"

spec:
    rules:
    - host: web.nginxbar.org
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080
        path: /

 

4.9 HTTPS配置

　　HTTPS 功能的配置说明如下表所示。

注解	类型	功能描述
nginx.ingress.kubernetes.io/force-ssl-redirect	true 或 false	当客户端的 HTTPS 被外部集群进行 SSL 卸载（SSL offloading）时，仍将 HTTP 的请求强制跳转到 HTTPS 端口
nginx.ingress.kubernetes.io/ssl-redirect	true 或 false	设置当前虚拟主机支持 HTTPS 请求时，是否将 HTTP 的请求强制跳转到 HTTPS 端口，全局默认为 true
nginx.ingress.kubernetes.io/ssl-passthrough	true 或 false	设置是否启用 SSL 透传
nginx.ingress.kubernetes.io/auth-tls-secret	string	设置客户端证书的资源对象名称
nginx.ingress.kubernetes.io/ssl-ciphers	string	设置 TLS 用于协商使用的加密算法组合，同 Nginx 配置指令 ssl_ciphers
nginx.ingress.kubernetes.io/auth-tls-verify-client	string	是否启用客户端证书验证，同 Nginx 配置指令 ssl_verify_client
nginx.ingress.kubernetes.io/auth-tls-verify-depth	number	客户端证书链的验证深度同 Nginx 配置指令 ssl_verify_depth
nginx.ingress.kubernetes.io/auth-tls-error-page	string	设置客户端证书验证错误时的跳转页面
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream	true 或 false	指定证书是否传递到上游服务器
nginx.ingress.kubernetes.io/secure-verify-ca-secret	string	设置是否启用对被代理服务器的 SSL 证书验证功能

　　HTTPS 配置样例如下：

# 创建TLS证书
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /data/apps/certs/dashboard.key -out /data/apps/certs/dashboard.crt -subj "/CN=dashboard.nginxbar.org/O=dashboard.nginxbar.org"
kubectl -n kube-system  create secret tls ingress-secret --key /data/apps/certs/dashboard.key --cert /data/apps/certs/dashboard.crt

# 创建HTTPS服务
cat>dashboard-ingress.yaml<<EOF
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: dashboard-ingress
    namespace: kube-system
    annotations:
        nginx.ingress.kubernetes.io/ingress.class: nginx
        # 使用HTTPS协议代理后端服务器
        nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
        # 启用SSL透传
        nginx.ingress.kubernetes.io/ssl-passthrough: "true"
spec:
    tls:
    - hosts:
        - dashboard.nginxbar.org
        secretName: ingress-secret
    rules:
        - host: dashboard.nginxbar.org
          http:
            paths:
            - path: /
              backend:
                serviceName: kubernetes-dashboard
                servicePort: 443
EOF

kubectl create -f dashboard-ingress.yaml

curl -k -H "Host:dashboard.nginxbar.org" https://10.103.196.209

　　Nginx-ingress 在用户没有提供证书的情况下会提供一个内置的默认 TLS 证书，如果 secretName 参数没有配置或配置错误，Nginx 会使用系统默认的证书，所以配置后仍需检查确认。

　　HTTPS 客户端证书身份认证配置样例如下：

# 创建客户端证书资源对象default/ca-secret

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    annotations:
        # 启用客户端证书验证
        nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
        # 绑定客户端证书的资源对象名称，是命名空间default的ca-secret
        nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
        # 客户端证书链的验证深度为1
        nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
        # 设置客户端证书验证错误时的跳转页面
        nginx.ingress.kubernetes.io/auth-tls-error-page: "http://www.mysite.com/error-cert.html"
        # 指定证书传递到上游服务器
        nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
    name: nginx-test
    namespace: default
spec:
    rules:
    - host: mydomain.com
        http:
            paths:
            - backend:
                serviceName: http-svc
                servicePort: 80
            path: /
    tls:
    - hosts:
        - mydomain.com
        secretName: tls-secret

 

4.10 “金丝雀”发布

　　“金丝雀”发布又称为灰度发布，灰度发布功能可以将用户请求按照指定的策略进行分割，并转发到不同的代理服务器组，通过不同的代理服务器部署应用不同版本可进行对照比较，因该方式对于新版本而言类似于使用“金丝雀”的方式进行测试，所以也叫“金丝雀”发布。

　　Nginx Ingress 支持 Header、cookie 和权重 3 种方式，可单独使用，也可以组合使用。“金丝雀”发布配置说明如下表所示。

注解	类型	功能描述
nginx.ingress.kubernetes.io/canary	true 或 false	启用“金丝雀”发布功能
nginx.ingress.kubernetes.io/canary-by-header	string	设置请求头属性字段的名称，用于根据该字段的值判断是否将请求路由到“金丝雀”服务器组，该字段值为 always 时则该请求被路由到“金丝雀”服务器组； 该字段值为 never 时则不路由到“金丝雀”服务器组
nginx.ingress.kubernetes.io/canary-by-header-value	string	自定义用于判断是否路由到“金丝雀”服务器组的请求头字段值，默认为 always，必须与 canary-by-header同时使用
nginx.ingress.kubernetes.io/canary-by-cookie	string	设置 cookie 的字段名称，用于根据该字段的值判断是否将请求路由到“金丝雀”服务器组。always 则路由到“金丝雀”服务器组； never 则永远不路由到“金丝雀”服务器组
nginx.ingress.kubernetes.io/canary-weight	number	将请求基于整数（0~100）的请求百分比随机路由到“金丝雀”服务器组；100 表示所有请求都路由到“金丝雀”服务器组； 0 表示不路由任何请求到“金丝雀”服务器组

　　“金丝雀”路由规则同时存在时的优先顺序是 canary-by-header、canary-by-cookie、canary-weight。

　　配置样例如下：

# 创建主机web.nginxbar.org的Ingress资源配置
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    namespace: default
    annotations:
        nginx.ingress.kubernetes.io/ingress.class: "nginx"
spec:
    rules:
    - host: web.nginxbar.org   # 此service的访问域名
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080

# 创建主机web.nginxbar.org金丝雀组的Ingress资源配置
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org-canary
    namespace: default
    annotations:
        nginx.ingress.kubernetes.io/ingress.class: "nginx"
        nginx.ingress.kubernetes.io/canary: "true",
        # 根据请求头字段CanaryByHeader的值进行判断
        nginx.ingress.kubernetes.io/canary-by-header: "CanaryByHeader",
        # 请求头字段CanaryByHeader的值为DoCanary时，路由到“金丝雀”服务器组
        nginx.ingress.kubernetes.io/canary-by-header-value: "DoCanary",
        # 根据Cookie字段CanaryByCookie的值进行判断
        nginx.ingress.kubernetes.io/canary-by-cookie: "CanaryByCookie",
        # 随机10%的请求路由到“金丝雀”服务器组
        nginx.ingress.kubernetes.io/canary-weight: "10",
spec:
    rules:
    - host: web.nginxbar.org   # 此service的访问域名
      http:
        paths:
        - backend:
            serviceName: nginx-web-canary
            servicePort: 8080

 

4.11 lua-resty-waf模块

　　lua-resty-waf 是一个基于 OpenResty 的高性能 Web 应用防火墙，对当前虚拟主机的访问可以按照相关防火墙规则进行访问过滤。模块配置说明如下表所示。

注解	类型	功能描述
nginx.ingress.kubernetes.io/lua-resty-waf	string	设置 WAF 防火墙的工作模式，inactive 表示不执行任何操作；active 表示启用：simulate 模式下， 如果给定请求有匹配的规则，它将记录一条警告消息而不进行处理。这有助于在完全部署规则之前调试规则并消除可能的误报
nginx.ingress.kubernetes.io/lua-resty-waf-debug	true 或 false	设置是否启用调试功能，默认值为 false
nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets	string	设置忽略规则集的名称，当某些规则集（如 sqli 或 xss crs 规则集）太容易误报或不适用时，可通过该设置进行忽略处理
nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules	string	设置自定义的规则
nginx.ingress.kubernetes.io/lua-resty-waf-allow-unknown-content-types	true 或 false	设置在发送了不在允许内容类型表中的内容类型头时是否继续处理请求。默认允许的为 text/html、text/json、 application/json 的文档类型，默认值为 false
nginx.ingress.kubernetes.io/lua-resty-waf-score-threshold	number	设置请求异常评分的阈值，如果超过这个阈值，则拒绝该请求，默认值为 5
nginx.ingress.kubernetes.io/lua-resty-waf-process-multipart-body	true 或 false	设置是否使用 lua-resty-upload 模块对 multipart/form-data 类型请求体的处理，默认为 true

 

4.12 ModSecurity模块配置

　　ModSecurity 是一个开源的 Web 应用防火墙。必须首先通过在 ConfigMap 中启用 Mod-Security 来加载 ModSecurity 模块。这将为所有路径启用 ModSecurity 过滤，可以手动在 Ingress 资源实例中禁用此功能。ModSecurity 模块配置说明如下表所示。

注解	类型	功能描述
nginx.ingress.kubernetes.io/enable-mod-security	bool	设置是否启用 ModSecurity 过滤，启用时应用推荐的规则以仅检测（Detection-Only）模式运行
nginx.ingress.kubernetes.io/enable-owasp-core-rules	bool	设置是否使用 OWASP 核心规则进行请求检测
nginx.ingress.kubernetes.io/modsecurity-transaction-id	string	设置从 Nginx 传递事务 ID，而不是在库中自动生成，有利于在 ModSecurity 中跟踪查看检测的请求， 对应模块配置指令为 modsecurity_transaction_id
nginx.ingress.kubernetes.io/modsecurity-snippet	string	添加模块配置指令 modsecurity_rules 的内容

　　配置样例如下：

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    annotations:
        nginx.ingress.kubernetes.io/enable-modsecurity: "true"
        nginx.ingress.kubernetes.io/enable-owasp-core-rules: "true"
        nginx.ingress.kubernetes.io/modsecurity-transaction-id: "$request_id"
        nginx.ingress.kubernetes.io/modsecurity-snippet: |
        SecRuleEngine On
        SecDebugLog /tmp/modsec_debug.log
spec:
    rules:
    - host: web.nginxbar.org
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080
            path: /

 

4.13 Influxdb模块配置

　　通过使用 Nginx Influxdb 模块，可以用 UDP 协议将请求记录实时发送到后端的 Influxdb 服务器。Influxdb 模块配置说明如下表所示。

注解	类型	功能描述
nginx.ingress.kubernetes.io/enable-influxdb	true 或 false	是否启用 Influxdb 输出功能
nginx.ingress.kubernetes.io/influxdb-measurement	string	指定 Influxdb 中的 measurement 名称
nginx.ingress.kubernetes.io/influxdb-port	string	指定 Influxdb 的端口
nginx.ingress.kubernetes.io/influxdb-host	string	指定 Influxdb 的 IP 地址
nginx.ingress.kubernetes.io/influxdb-server-name	string	设置自己的应用标识

　　配置样例如下：

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    annotations:
        nginx.ingress.kubernetes.io/enable-influxdb: "true"
        nginx.ingress.kubernetes.io/influxdb-measurement: "nginxbar-reqs"
        nginx.ingress.kubernetes.io/influxdb-port: "8089"
        nginx.ingress.kubernetes.io/influxdb-host: "192.168.2.110"
        nginx.ingress.kubernetes.io/influxdb-server-name: "nginxbar-com"
spec:
    rules:
    - host: web.nginxbar.org
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080
        path: /

 

5.参考

　Ingress配置参考：https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md

　Ingress注释参考https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/annotations.md