Миграция с Ingress-NGINX Controller на ANIC#

Для миграции ANIC должен быть установлен на том же хосте, где уже работает Ingress-NGINX Controller.

Перенос конфигурации#

  1. Настройте ConfigMap для ANIC, добавив общие параметры для всех Ingress. Эти параметры будут дефолтными для всех Ingress, если конкретный манифест их не переопределяет.

  2. В манифестах для сервисов измените аннотации Ingress-NGINX Controller на соответствующие аннотации ANIC, где это необходимо.

    Для аннотаций, которые не поддерживаются в ANIC, используйте другие варианты настройки конфигурации (см. примеры ниже).

  3. По очереди перенесите манифесты для сервисов, проверяя, что каждый манифест работает корректно.

Примечание

Не рекомендуется изменять поле spec в ресурсе Ingress. Реализации Ingress-NGINX Controller и ANIC отличаются, что может привести к проблемам совместимости.

Соответствия для аннотаций#

В таблице ниже приведены аннотации Ingress-NGINX Controller с эквивалентными аннотациями ANIC.

Ingress-NGINX Controller

ANIC

nginx.ingress.kubernetes.io/configuration-snippet

angie.software/location-snippets

nginx.ingress.kubernetes.io/load-balance

angie.software/lb-method

nginx.ingress.kubernetes.io/proxy-buffering

angie.software/proxy-buffering

nginx.ingress.kubernetes.io/proxy-buffers-number

angie.software/proxy-buffers

nginx.ingress.kubernetes.io/proxy-buffer-size

angie.software/proxy-buffer-size

nginx.ingress.kubernetes.io/proxy-connect-timeout

angie.software/proxy-connect-timeout

nginx.ingress.kubernetes.io/proxy-read-timeout

angie.software/proxy-read-timeout

nginx.ingress.kubernetes.io/proxy-send-timeout

angie.software/proxy-send-timeout

nginx.ingress.kubernetes.io/rewrite-target

angie.software/rewrites

nginx.ingress.kubernetes.io/server-snippet

angie.software/server-snippets

nginx.ingress.kubernetes.io/ssl-redirect

ingress.kubernetes.io/ssl-redirect

Полный список аннотаций ANIC см. в разделе Расширенная конфигурация с помощью аннотаций.

Глобальная конфигурация с помощью ConfigMap#

В таблице ниже приведено ключи ConfigMap в Ingress-NGINX Controller и их эквиваленты в ANIC.

Ingress-NGINX Controller

ANIC

disable-access-log

access-log-off

hsts

hsts

hsts-include-subdomains

hsts-include-subdomains

hsts-max-age

hsts-max-age

http-snippet

http-snippets

keep-alive

keepalive-timeout

keep-alive-requests

keepalive-requests

load-balance

lb-method

location-snippet

location-snippets

log-format-escape-json

log-format-escaping: “json”

log-format-stream

stream-log-format

log-format-upstream

log-format

main-snippet

main-snippets

max-worker-connections

worker-connections

max-worker-open-files

worker-rlimit-nofile

proxy-body-size

client-max-body-size

proxy-buffering

proxy-buffering

proxy-buffers-number

proxy-buffers: number size

proxy-buffer-size

proxy-buffers: number size

proxy-connect-timeout

proxy-connect-timeout

proxy-read-timeout

proxy-read-timeout

proxy-send-timeout

proxy-send-timeout

server-name-hash-bucket-size

server-names-hash-bucket-size

proxy-headers-hash-max-size

server-names-hash-max-size

server-snippet

server-snippets

server-tokens

server-tokens

upstream-keepalive-connections

keepalive

use-http2

http2

use-proxy-protocol

proxy-protocol

variables-hash-bucket-size

variables-hash-bucket-size

worker-cpu-affinity

worker-cpu-affinity

worker-processes

worker-processes

worker-shutdown-timeout

worker-shutdown-timeout

Примеры#

Настройка терминации SSL и маршрутизации на основе HTTP-путей#

Ingress-NGINX Controller:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-test
spec:
  tls:
    - hosts:
      - foo.bar.com
      secretName: tls-secret
  rules:
    - host: foo.bar.com
      http:
        paths:
        - path: /login
          backend:
            serviceName: login-svc
            servicePort: 80
        - path: /billing
            serviceName: billing-svc
            servicePort: 80

ANIC:

apiVersion: networking.k8s.io/v1
kind: VirtualServer
metadata:
  name: anic-test
spec:
  host: foo.bar.com
  tls:
    secret: tls-secret
  upstreams:
    - name: login
      service: login-svc
      port: 80
    - name: billing
      service: billing-svc
      port: 80
  routes:
  - path: /login
    action:
      pass: login
  - path: /billing
    action:
      pass: billing

Настройка балансировки нагрузки TCP/UDP и TLS Passthrough#

ANIC предоставляет доступ к TCP- и UDP-сервисам с помощью ресурсов TransportServer и GlobalConfiguration. Ingress-NGINX Controller использует для этой цели ConfigMap.

Канареечные развертывания#

Канареечные и сине-зеленые развертывания (сanary deployment и blue-green deployment) позволяют внедрять изменения в код в продакшн-среде, не прерывая работу пользователей. ANIC выполняет развертывания на уровне передачи данных: чтобы перейти с Ingress-NGINX Controller на ANIC, необходимо сопоставить аннотации Ingress-NGINX Controller с ресурсами VirtualServer и VirtualServerRoute в ANIC.

Ingress-NGINX Controller обрабатывает канареечные аннотации в следующем порядке:

  1. nginx.ingress.kubernetes.io/canary-by-header

  2. nginx.ingress.kubernetes.io/canary-by-cookie

  3. nginx.ingress.kubernetes.io/canary-by-weight

Примечание

Чтобы канареечные аннотации интерпретировались в ANIC аналогично, они должны располагаться в манифесте VirtualServer или VirtualServerRoute в том же порядке.

nginx.ingress.kubernetes.io/canary-by-header

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-header: "httpHeader"

ANIC:

matches:
- conditions:
  - header: httpHeader
      value: never
  action:
    pass: echo
  - header: httpHeader
      value: always
  action:
    pass: echo-canary
action:
  pass: echo

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-header: "httpHeader"
nginx.ingress.kubernetes.io/canary-by-header-value: "my-value"

ANIC:

matches:
- conditions:
  - header: httpHeader
      value: my-value
  action:
    pass: echo-canary
action:
  pass: echo

nginx.ingress.kubernetes.io/canary-by-cookie

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-cookie: "cookieName"

ANIC:

matches:
- conditions:
  - cookie: cookieName
      value: never
  action:
    pass: echo
  - cookie: cookieName
      value: always
  action:
    pass: echo-canary
action:
  pass: echo

Управление трафиком#

Аннотации Ingress-NGINX Controller, для которых пока нет соответствующих полей в ресурсах ANIC, необходимо обрабатывать с помощью фрагментов (сниппетов).

Примечание

Для работы в чарте необходимо установить controller.enableSnippets в true.

В примерах ниже аннотации Ingress-NGINX Controller сопоставлены с ресурсами VirtualServer и VirtualServerRoute в ANIC.

custom-http-errors

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/custom-http-errors: "code"
nginx.ingress.kubernetes.io/default-backend: "default-svc"

ANIC:

errorPages:
- codes: [code]
    redirect:
      code: 301
      url: default-svc

limit-connections

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/limit-connections: "number"

ANIC:

http-snippets: |
    limit_conn_zone $binary_remote_addr zone=zone_name:size;
routes:
- path: /path
    location-snippets: |
      limit_conn zone_name number;

limit-rate

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/limit-rate: "number"
nginx.ingress.kubernetes.io/limit-rate-after: "number"

ANIC:

location-snippets: |
    limit_rate number;

    limit_rate_after number;

limit-rpm

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/limit-rpm: "number"
nginx.ingress.kubernetes.io/limit-burst-multiplier: "multiplier"

ANIC:

rateLimit:
    rate: numberr/m

    burst: number * multiplier
    key: ${binary_remote_addr}
    zoneSize: size

limit-rps

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/limit-rps: "number"
nginx.ingress.kubernetes.io/limit-burst-multiplier: "multiplier"

ANIC:

rateLimit:
    rate: numberr/s

    burst: number * multiplier
    key: ${binary_remote_addr}
    zoneSize: size

limit-whitelist

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/limit-whitelist: "CIDR"

ANIC:

http-snippets: |
server-snippets: |

rewrite-target

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/rewrite-target: "URI"

ANIC:

rewritePath: "URI"

Манипуляция заголовками#

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/enable-cors: "true"
nginx.ingress.kubernetes.io/cors-allow-credentials: "true"

nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For"

nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"

nginx.ingress.kubernetes.io/cors-allow-origin: "*"

nginx.ingress.kubernetes.io/cors-max-age: "seconds"

ANIC:

Установка для Ingress возможна с помощью аннотации angie.software/location-snippets. Для работы в чарте необходимо установить controller.enableSnippets в true.

Ingress:
annotations:
    angie.software/location-snippets |
        add_header 'Access-Control-Allow-Origin' '*' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range' always;
        add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;

VirtualServer
responseHeaders:
  add:
    - name: Access-Control-Allow-Credentials
      value: "true"
    - name: Access-Control-Allow-Headers
      value: "X-Forwarded-For"
    - name: Access-Control-Allow-Methods
      value: "PUT, GET, POST, OPTIONS"
    - name: Access-Control-Allow-Origin
      value: "*"
    - name: Access-Control-Max-Age
      value: "seconds"

Проксирование и балансировка нагрузки#

В таблице ниже приведены аннотации Ingress-NGINX Controller и параметры в поле upstream для ресурсов VirtualServer и VirtualServerRoute.

Ingress-NGINX Controller

ANIC

nginx.ingress.kubernetes.io/load-balance

lb-method

nginx.ingress.kubernetes.io/proxy-buffering

buffering

nnginx.ingress.kubernetes.io/proxy-buffers-number

buffers

nginx.ingress.kubernetes.io/proxy-next-upstream

next-upstream

nginx.ingress.kubernetes.io/proxy-next-upstream-timeout

next-upstream-timeout

nginx.ingress.kubernetes.io/proxy-read-timeout

read-timeout

nginx.ingress.kubernetes.io/proxy-send-timeout

send-timeout

nginx.ingress.kubernetes.io/service-upstream

use-cluster-ip

Аутентификация mTLS#

ANIC может обрабатывать аутентификацию mTLS на уровне входного трафика, требуя предоставления действительных сертификатов для внешних соединений. Настройка реализуется с помощью ресурсов Policy, соответствующих аннотациям Ingress-NGINX Controller.

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/auth-tls-secret: secretName
nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"

ANIC:

ingressMTLS:
   clientCertSecret: secretName
   verifyClient: "on"

   verifyDepth: 1

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/proxy-ssl-secret: "secretName"
nginx.ingress.kubernetes.io/proxy-ssl-verify: "on|off"
nginx.ingress.kubernetes.io/proxy-ssl-verify-depth: "1"
nginx.ingress.kubernetes.io/proxy-ssl-protocols: "TLSv1.2"
nginx.ingress.kubernetes.io/proxy-ssl-ciphers: "DEFAULT"
nginx.ingress.kubernetes.io/proxy-ssl-name: "server-name"
nginx.ingress.kubernetes.io/proxy-ssl-server-name: "on|off"

ANIC:

egressMTLS:
   tlsSecret: secretName

   verifyServer: true|false

   verifyDepth: 1

   protocols: TLSv1.2

   ciphers: DEFAULT

   sslName: server-name

   serverName: true|false

Сохранение сессий#

Для сохранения сессий в ANIC используются ресурсы Policy. В Ingress-NGINX Controller используются соответствующие аннотации.

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "cookieName"
nginx.ingress.kubernetes.io/session-cookie-expires: "x"
nginx.ingress.kubernetes.io/session-cookie-path: "/route"
nginx.ingress.kubernetes.io/session-cookie-secure: "true"

ANIC:

sessionCookie:
  enable: true

  name: cookieName

  expires: xh

  path: /route

  secure: true

Аутентификация через внешний сервис#

Ingress-NGINX Controller:

nginx.ingress.kubernetes.io/auth-url

ANIC:

Используется собственная реализация (применима только для VirtualServer): настройка OIDC.