SRE文档

深浅模式

官方文档,https://kubernetes.io/zh-cn/docs/concepts/services-networking/ingress/

0. 资源规范 ​

1. Ingress资源规范 ​

yaml
apiVersion: networking.k8s.io/v1           # 资源所属的API群组和版本
kind: Ingress                              # 资源类型标识
metadata:                                  # 元数据  
  name: <string>                           # 资源名称
  annotations:                             # 资源注解
    nginx.ingress.kubernetes.io/rewrite-target: /     # URL重写
  namespace: <string>                      # 名称空间
spec:
  ingressClassName: <string>               # Ingress控制器类别
  defaultBackend:	<Object>               # 默认资源后端
    service:        <Object>               # resource 与 Service 是互斥的，只能二选一，关联后端的service对象
      name: <string> -required-            # 后端service的名称
      port:	<Object>                       # 后端service上的端口对象
        name：	<string>                  # 端口名称
        number: <integer>                  # 端口号
    resource:       <Object>               # resource 与 Service 是互斥的，只能二选一，Resource的一种常见用法是将所有入站数据导向带有静态资产的对象存储后端
      apiGroup: <string>                   # API资源组
      kind: <string> -required-            # 资源类型标识 
      name: <string> -required-            # 资源的名称
  rules:   <[]Object>                      # Ingress规则列表
  - host: <string>                         # 虚拟主机的FQDN，支持*前缀通配，不支持IP，不支持指定端口
    http: <Object>                          
      paths: <[]Object> -required-         # 虚拟主机PATH定义的列表，有pathType和backend组成
      - path: <string>                     # 流量匹配的HTTP PATH，必须以/开头
        pathType: <string> -required-      # 支持ImplementationSpecific、Exact、Prefix
        backend: <Object> -required-       # 匹配流量要转发的目标后端
          resource：	<Object>              # resource 与 Service 是互斥的，只能二选一，Resource的一种常见用法是将所有入站数据导向带有静态资产的对象存储后端
            apiGroup: <string>                   # API资源组
            kind: <string> -required-            # 资源类型标识 
            name: <string> -required-            # 资源的名称
          service:                         # resource 与 Service 是互斥的，只能二选一，关联后端的service对象
            name: <string> -required-      # 后端service的名称
            port: <string> -required-      # 后端service上的端口对象
              name：<string>               # 端口名称
              number: <integer>            # 端口号
  tls：<[]Object>                          # TLS配置，用于指定上述rules中定义的那些主机需要工作在HTTPS模式下
  - hosts：<[]string>                      # 使用同一组证书的主机名称列表
    secretName：	<string>                  # 保存数字证书和私钥信息的secret资源名称
apiVersion: networking.k8s.io/v1           # 资源所属的API群组和版本
kind: Ingress                              # 资源类型标识
metadata:                                  # 元数据  
  name: <string>                           # 资源名称
  annotations:                             # 资源注解
    nginx.ingress.kubernetes.io/rewrite-target: /     # URL重写
  namespace: <string>                      # 名称空间
spec:
  ingressClassName: <string>               # Ingress控制器类别
  defaultBackend:	<Object>               # 默认资源后端
    service:        <Object>               # resource 与 Service 是互斥的，只能二选一，关联后端的service对象
      name: <string> -required-            # 后端service的名称
      port:	<Object>                       # 后端service上的端口对象
        name：	<string>                  # 端口名称
        number: <integer>                  # 端口号
    resource:       <Object>               # resource 与 Service 是互斥的，只能二选一，Resource的一种常见用法是将所有入站数据导向带有静态资产的对象存储后端
      apiGroup: <string>                   # API资源组
      kind: <string> -required-            # 资源类型标识 
      name: <string> -required-            # 资源的名称
  rules:   <[]Object>                      # Ingress规则列表
  - host: <string>                         # 虚拟主机的FQDN，支持*前缀通配，不支持IP，不支持指定端口
    http: <Object>                          
      paths: <[]Object> -required-         # 虚拟主机PATH定义的列表，有pathType和backend组成
      - path: <string>                     # 流量匹配的HTTP PATH，必须以/开头
        pathType: <string> -required-      # 支持ImplementationSpecific、Exact、Prefix
        backend: <Object> -required-       # 匹配流量要转发的目标后端
          resource：	<Object>              # resource 与 Service 是互斥的，只能二选一，Resource的一种常见用法是将所有入站数据导向带有静态资产的对象存储后端
            apiGroup: <string>                   # API资源组
            kind: <string> -required-            # 资源类型标识 
            name: <string> -required-            # 资源的名称
          service:                         # resource 与 Service 是互斥的，只能二选一，关联后端的service对象
            name: <string> -required-      # 后端service的名称
            port: <string> -required-      # 后端service上的端口对象
              name：<string>               # 端口名称
              number: <integer>            # 端口号
  tls：<[]Object>                          # TLS配置，用于指定上述rules中定义的那些主机需要工作在HTTPS模式下
  - hosts：<[]string>                      # 使用同一组证书的主机名称列表
    secretName：	<string>                  # 保存数字证书和私钥信息的secret资源名称

2. Ingress路径类型 ​

Ingress 中的每个路径都需要有对应的路径类型（Path Type）。未明确设置 pathType 的路径无法通过合法性检查。当前支持的路径类型有三种：

ImplementationSpecific：对于这种路径类型，匹配方法取决于 IngressClass。 具体实现可以将其作为单独的 pathType 处理或者与 Prefix 或 Exact 类型作相同处理。

Exact：精确匹配 URL 路径，且区分大小写。

Prefix：基于以 / 分隔的 URL 路径前缀匹配。匹配区分大小写，并且对路径中的元素逐个完成。 路径元素指的是由 / 分隔符分隔的路径中的标签列表。 如果每个 p 都是请求路径 p 的元素前缀，则请求与路径 p 匹配。

3. IngressClass资源 ​

Ingress 可以由不同的控制器实现，通常使用不同的配置。 每个 Ingress 应当指定一个类，也就是一个对 IngressClass 资源的引用。 IngressClass 资源包含额外的配置，其中包括应当实现该类的控制器名称。

yaml
apiVersion: networking.k8s.io/v1           # 资源所属的API群组和版本
kind: IngressClass                         # 资源类型标识
metadata:
  labels：	<map[string]string>           # 标签
  name: <string>                           # 资源名称
  annotations:                             # 资源注解
    ingressclass.kubernetes.io/is-default-class: "true"    # 是否为默认
  namespace: <string>                      # 名称空间
spec:
  controller: <string>                     # 该类型所关联的ingress控制器
  parameters:  <Object>                    # 控制器相关的参数，这些参数由引用的资源定义，可选字段 
    apiGroup: <string>                     # 引用目标资源所属的API群组
    kind: <string> -required-              # 引用的资源类型
    name: <string> -required-              # 引用的资源名称
    namespace: <string>                    # 引用资源的名称空间
    scope: <string>                        # 引用资源的作用域，可选参数Cluster、Namespace
apiVersion: networking.k8s.io/v1           # 资源所属的API群组和版本
kind: IngressClass                         # 资源类型标识
metadata:
  labels：	<map[string]string>           # 标签
  name: <string>                           # 资源名称
  annotations:                             # 资源注解
    ingressclass.kubernetes.io/is-default-class: "true"    # 是否为默认
  namespace: <string>                      # 名称空间
spec:
  controller: <string>                     # 该类型所关联的ingress控制器
  parameters:  <Object>                    # 控制器相关的参数，这些参数由引用的资源定义，可选字段 
    apiGroup: <string>                     # 引用目标资源所属的API群组
    kind: <string> -required-              # 引用的资源类型
    name: <string> -required-              # 引用的资源名称
    namespace: <string>                    # 引用资源的名称空间
    scope: <string>                        # 引用资源的作用域，可选参数Cluster、Namespace

1. snippet ​

在ingress-nginx的configMap和ingress域名规则中，利用ConfigMap和Annotations进行自定义配置 snippet 并注入nginx.conf中。

  • ConfigMap: 使用ConfigMap在NGINX中设置全局配置。
  • Annotations: 如果需要特定入口规则的特定配置，请使用此选项。

1.1 annotations ​

**Annotations 用于配置特定的 Ingress Controller 行为。**以下是常见的 Nginx Ingress Controller Annotations：

1.流量管理 ​

nginx.ingress.kubernetes.io/rewrite-target: 重写 URL 路径。

nginx.ingress.kubernetes.io/force-ssl-redirect: 将 HTTP 请求重定向到 HTTPS。

nginx.ingress.kubernetes.io/use-regex: 启用正则表达式匹配路径。

2.负载均衡 ​

nginx.ingress.kubernetes.io/affinity: 配置会话保持。

值：cookie 表示基于 cookie 的会话保持。

nginx.ingress.kubernetes.io/load-balance: 配置负载均衡策略。

值：round_robin、least_conn、ip_hash。

3.安全性 ​

nginx.ingress.kubernetes.io/auth-type: 配置基础认证。

nginx.ingress.kubernetes.io/whitelist-source-range: 允许的 IP 地址列表。

4.性能优化 ​

nginx.ingress.kubernetes.io/proxy-read-timeout : 设置后端响应超时时间。

nginx.ingress.kubernetes.io/proxy-body-size: 限制请求体大小。

❌ 注意

只对指定svc的lngress生效;

若是同时配置了Annotations和configmap，一般都是annotations生效,configmap不生效，因为annotations优先级比configmap高;

nginx.ingress.kubernetes.io/configuration-snippet （用于插入 location块代码段）;

nginx.ingress.kubernetes.io/server-snippet （用于插入 server 块中的代码段）;

5.实战 ​

参数 ​
yaml
#kubectl edit  ingress ingress-domain
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      ....指令片段.....
    nginx.ingress.kubernetes.io/stream-snippet: |
      ....指令片段.....
    nginx.ingress.kubernetes.io/server-snippet: |
      ....指令片段.....
#kubectl edit  ingress ingress-domain
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      ....指令片段.....
    nginx.ingress.kubernetes.io/stream-snippet: |
      ....指令片段.....
    nginx.ingress.kubernetes.io/server-snippet: |
      ....指令片段.....
rewrite ​
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-rewrite
  annotations:
    # 这句话的是意思是将"/api(/|$)(.*)"改写为"/.*",
    # 后端在调用时会直接将"/api(/|$)"的内容取消掉.
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: java.host.com
    http:
      paths:
      - backend:
          service:
            name: svc-apple
            port:
              number: 80
        # 注意，这里用到了2个分组，小括号代表分组，共计2个小括号，
        # 上面的注解中"rewrite-target"使用到第二个小括号的参数。
        path: /api(/|$)(.*)
        pathType: ImplementationSpecific
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-rewrite
  annotations:
    # 这句话的是意思是将"/api(/|$)(.*)"改写为"/.*",
    # 后端在调用时会直接将"/api(/|$)"的内容取消掉.
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: java.host.com
    http:
      paths:
      - backend:
          service:
            name: svc-apple
            port:
              number: 80
        # 注意，这里用到了2个分组，小括号代表分组，共计2个小括号，
        # 上面的注解中"rewrite-target"使用到第二个小括号的参数。
        path: /api(/|$)(.*)
        pathType: ImplementationSpecific
案例 ​
yaml
metadata:
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      proxy_set_header X-FORWARDED-FOR $http_X_FORWARDED_FOR;
      server_tokens off; location /itwork/res/css { deny all;return 403;}      
    nginx.ingress.kubernetes.io/stream-snippet: |
      server {
        listen 8000;
        proxy_pass 127.0.0.1:80;
      }
    nginx.ingress.kubernetes.io/server-snippet: |
      add_header X-Frame-Options SAMEORIGIN;
      # set_header X-Frame-Options SAMEORIGIN;
      set $flag 0;
      set $childdomain "";
      if ($http_user_agent ~* "(Mobile)" ){
        set $flag "${flag}1";
      }
      if ( $host ~* "(.*).xxx.top") {
        set $childdomain $1;
        set $flag "${flag}2";
      }
      if ( $flag = "012")
      {
        return 301 http://m.xxx.top/$1$request_uri ;
      }
metadata:
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      proxy_set_header X-FORWARDED-FOR $http_X_FORWARDED_FOR;
      server_tokens off; location /itwork/res/css { deny all;return 403;}      
    nginx.ingress.kubernetes.io/stream-snippet: |
      server {
        listen 8000;
        proxy_pass 127.0.0.1:80;
      }
    nginx.ingress.kubernetes.io/server-snippet: |
      add_header X-Frame-Options SAMEORIGIN;
      # set_header X-Frame-Options SAMEORIGIN;
      set $flag 0;
      set $childdomain "";
      if ($http_user_agent ~* "(Mobile)" ){
        set $flag "${flag}1";
      }
      if ( $host ~* "(.*).xxx.top") {
        set $childdomain $1;
        set $flag "${flag}2";
      }
      if ( $flag = "012")
      {
        return 301 http://m.xxx.top/$1$request_uri ;
      }

1.2 configmap ​

nginx-ingress configmap 中的配置会是全局生效的

在Ingress-nginx中的ConfigMap进行配置全局生效的Nginx指令片段，其中主要位置的指令片段嵌入位置参数如下:

  • main-snippet: 将自定义配置添加到 nginx 配置的主要部分。
  • http-snippet: 将自定义配置添加到 nginx 配置的 http 部分。
  • server-snippet: 将自定义配置添加到 nginx 配置中的所有服务器。
  • location-snippet: 将自定义配置添加到 nginx 配置中的所有位置。您不能使用它来添加代理到 Kubernetes pod 的新位置，因为该片段无法访问 Go 模板函数。如果要添加自定义位置，则必须提供自己的 nginx.tmpl

编辑 ​

bash
$ kubectl edit cm  ingress-nginx-controller -n ingress-nginx
apiVersion: v1
data:
  allow-snippet-annotations: "true"
  main-snippet: |
    ....指令....
  http-snippet: |
    ....指令....
  server-snippet: | 
    ....指令....
  location-snippet: |
    ....指令....
$ kubectl edit cm  ingress-nginx-controller -n ingress-nginx
apiVersion: v1
data:
  allow-snippet-annotations: "true"
  main-snippet: |
    ....指令....
  http-snippet: |
    ....指令....
  server-snippet: | 
    ....指令....
  location-snippet: |
    ....指令....

禁用ssl跳转 ​

yaml
全局禁用
ssl-redirect: "false"
全局禁用
ssl-redirect: "false"

1.3 metadata ​

name： Ingress 资源的名称。

annotations：用于配置特定 Ingress Controller 的行为。

nginx.ingress.kubernetes.io/rewrite-target：路径重写功能。

1.4 spec ​

ingressClassName：指定使用哪个 Ingress Controller 处理此 Ingress 资源。

rules：定义域名和路径的路由规则。

host：指定域名

http.paths：定义 URL 路径的路由规则。

path：URL 路径（如 /app1）。

pathType：

Exact：精确匹配路径。

Prefix：匹配以此路径为前缀的请求。

ImplementationSpecific：由具体 Ingress Controller 决定匹配逻辑。

backend：指定后端服务。

service.name：目标服务名称。

service.port.number：目标服务的端口号。

1.5 tls ​

hosts：启用 HTTPS 的域名列表。

secretName：存储 TLS 证书和私钥的 Kubernetes Secret 名称。

2. Custom template ​