Entrada

NCP creará un equilibrador de carga de capa 7 para las entradas con especificación TLS y otro equilibrador de carga de capa 7 para las entradas sin especificación TLS. También puede crear objetos CRD (CustomResourceDefinitions) para controlar el ajuste de escala de la entrada.

Tenga en cuenta lo siguiente:

• Todas las entradas obtendrán una sola dirección IP.
• Al recurso de entrada se le asigna una dirección IP del grupo de direcciones IP externas que la opción external_ip_pools especifica en la sección [nsx_v3] de ncp.ini. El equilibrador de carga se expone en esta dirección IP y los puertos HTTP y HTTPS (80 y 443).
• Al recurso de entrada se le asigna una dirección IP del grupo de direcciones IP externas que la opción external_ip_pools_lb especifica en la sección [nsx_v3] de ncp.ini. Si la opción external_ip_pools_lb no existe, se utiliza el grupo que external_ip_pools especifica. El equilibrador de carga se expone en esta dirección IP y los puertos HTTP y HTTPS (80 y 443).
• Puede utilizar otro grupo de direcciones IP cambiando la configuración y reiniciando NCP.
• Puede especificar un certificado predeterminado para TLS. A continuación podrá obtener información sobre la generación de un certificado y el montaje de este en el pod de NCP.
• Las entradas sin especificación TLS se alojarán en el servidor virtual HTTP (puerto 80).
• Las entradas con especificación TLS se alojarán en el servidor virtual HTTPS (puerto 443). El equilibrador de carga actuará como servidor SSL y finalizará la conexión SSL de cliente.
• Se admite la modificación de una entrada agregando o quitando la sección TLS. Cuando la clave tls se quita de la especificación de entrada, las reglas de entrada se transferirán del servidor virtual HTTPS (puerto 443) al servidor virtual HTTP (puerto 80). De igual modo, cuando la clave tls se agrega a la especificación de entrada, las reglas de entrada se transferirán del servidor virtual HTTP (puerto 80) al servidor virtual HTTPS (puerto 443).
• Si hay reglas duplicadas en las definiciones de entrada de un solo clúster, solo se aplicará la primera regla. El resto de entradas con reglas duplicadas se anotarán con un error. Por ejemplo, si crea dos entradas con el mismo host y la misma path; una entrada tiene especificación TLS y la otra no, y kubernetes.io/ingress.allow-http se establece como false, las dos reglas se crearán en servidores virtuales diferentes y no entrarán en conflicto entre sí. Sin embargo, si true se establece como kubernetes.io/ingress.allow-http, la entrada que se aplique posteriormente se anotará con un error. Consulte la sección "Errores" que se incluye más abajo para obtener más información.
• Solo se admite una entrada con un back-end predeterminado en cada clúster. El tráfico que no coincida con ninguna regla de entrada se reenviará al back-end predeterminado.
• Si hay varias entradas con back-end predeterminados, solo se configurará la primera. Las demás se anotarán con un error. Consulte la sección "Errores" que se incluye más abajo para obtener más información.
• Las reglas se aplican en el siguiente orden:
  1. Reglas con host y path especificado.
     1. Rules con Exact pathType.
     2. Rules con Prefix pathType.
     3. Rules con Regex pathType.
  2. Reglas con host o path especificado.
     1. Rules con Exact pathType.
     2. Rules con Prefix pathType.
     3. Rules con Regex pathType.

  Nota: Si hay varias rutas que coinciden con una solicitud, se proporcionará la prioridad a la ruta más larga.

  Acerca de pathType:

  • A partir de Kubernetes 1.19, pathType es obligatorio.
  • Si se establece use-regex, solo surtirá efecto si pathType es ImplementationSpecific.
  • Si no se establece use-regex, ImplementationSpecific se tratará igual que Exact. pathType tiene prioridad sobre otras anotaciones de NCP.
  • Dos rutas de acceso que coinciden con pathType diferentes pueden coexistir.
  • Para el tipo Prefix, /foo coincidirá con /foo/, /foo/bar pero no con /foo ni /foobar. Para buscar coincidencias de /foo, agregue la ruta Exact /foo a la regla de entrada.
• Comodines de nombre de host
  Al especificar el nombre de host, puede especificar el nombre exacto, como abc.ejemplo.com, o utilizar un comodín, como *.ejemplo.com. Tenga en cuenta que el comodín coincidirá con una o varias etiquetas de DNS. La siguiente tabla muestra los resultados de la coincidencia si especifica *.ejemplo.com.

  Encabezado del host	Resultado de coincidencia
  abc.ejemplo.com	Coincide con
  abc.def.ejemplo.com	Coincide con
  example.com	No hay coincidencias

• (Esto es aplicable si utiliza el modo Directiva). Si se crea una entrada TLS con un back-end predeterminado, se recomienda configurar el back-end predeterminado para responder a las solicitudes HTTP y HTTPS debido a lo siguiente:
  • El equilibrador de carga finalizará TLS y enviará solicitudes HTTP al servidor back-end predeterminado si hay una entrada TLS (en el clúster para el caso práctico de Kubernetes/TKGI o en el mismo espacio de nombres para el caso práctico de Project Pacific) con el host que coincida con el host de la solicitud.
  • El equilibrador de carga volverá a cifrar y a enviar solicitudes HTTPS al servidor back-end si no hay ninguna entrada TLS (en el clúster para el caso práctico de Kubernetes/TKGI o en el mismo espacio de nombres para el caso práctico de Project Pacific) con el host que coincida con el host de la solicitud.
• El recurso IngressClass no está admitido.
• Se admite el atributo pathType.
• Se admite la autenticación de cliente JWT (JSON Web Token). Esta función requiere NSX 3.0.0 o versiones posteriores.

A partir de Kubernetes 1.18, la anotación kubernetes.io/ingress.class de entrada queda obsoleta y se reemplaza por el recurso IngressClass. Para especificar NSX como el controlador de entrada en el recurso IngressClass, establezca el parámetro del controlador en k8s.io/nsx. Por ejemplo:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nsx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: true
spec:
  controller: k8s.io/nsx

Para especificar un controlador de entrada de terceros, establezca el parámetro del controlador en k8s.io/<controller name>. Por ejemplo:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: false
spec:
  controller: k8s.io/ingress-nginx

Para establecer IngressClass como el valor predeterminado para el clúster, establezca la anotación ingressclass.kubernetes.io/is-default-class en true. Consulte el ejemplo anterior.

No debe utilizar ni la anotación kubernetes.io/ingress.class ni el recurso IngressClass.

Si configura manualmente un objeto de Endpoints, asegúrese de establecer el parámetro targetRef. El valor debe ser el UID del pod back-end. Por ejemplo:

apiVersion: networking.k8s.io/v1
kind: Endpoints
metadata:
  name: tea-svc
subsets:
  - addresses:
    - ip: 172.26.0.2
      targetRef:
        uid: 4378e0ae-5837-49c6-a0b2-178dced8eb1e
...

Anotaciones de funciones

En la siguiente tabla, se incluyen las anotaciones compatibles con NCP:

Anotación	Descripción	Valores compatibles	Valor predeterminado
kubernetes.io/ingress.allow-http	Habilita las solicitudes HTTP además de HTTPS.	true, false	true
ncp/use-regex	Habilita la coincidencia de patrones de ruta.	true, false	false
ingress.kubernetes.io/rewrite-target	Vuelve a escribir la ruta de la solicitud entrante.	Rutas que empiezan por ‘/’ Rutas con un marcador de posición numerado para un grupo capturado en una expresión regular, por ejemplo, /$1	Sin valor predeterminado
ncp/http-redirect	Redirecciona las solicitudes HTTP a HTTPS.	true, false	false
kubernetes.io/ingress.class	Indica qué controlador de entrada es responsable de una entrada determinada.	nsx, nginx, etc.	nsx
nsx/loadbalancer	Coloca una entrada en un equilibrador de carga específico.	Nombre de un objeto CRD de equilibrador de carga	Sin valor predeterminado
ncp/allowed-source-range	Limita el acceso de entrada por la IP de origen de la solicitud	Lista separada por comas de CIDR, direcciones IP o rangos de IP.	Sin valor predeterminado
ncp/ssl-mode	Selecciona el modo SSL para todas las reglas de una entrada.	offload, reencrypt, passthrough	offload
ncp/jwt-alg	Determina el algoritmo que se utilizará para validar la firma de JWT. Habilita la autenticación del cliente de JWT cuando se establece con ncp/jwt-secret.	HS256, RS256	Sin valor predeterminado
ncp/jwt-secret	Especifica el nombre del secreto de Kubernetes que contiene el secreto de JWT o la clave pública que se utiliza para la validación de la firma. Habilita la autenticación del cliente de JWT cuando se establece con ncp/jwt-alg.	Nombre de un secreto de Kubernetes	Sin valor predeterminado
ncp/jwt-token	Ubicación adicional para buscar JWT en la solicitud HTTP.	_arg_<nombre_parámetro>, _cookie_<nombre_cookie>	Sin valor predeterminado
ncp/jwt-realm	Especifica el encabezado de territorio devuelto con 401 cuando falla la autenticación.	Cadena que indica el dominio Kerberos	Nombre de host de la regla de entrada
ncp/jwt-preserve	Opción para mantener JWT y pasar al back-end después de una autenticación correcta.	true, false	true
ncp/connection_multiplexing_enabled	Habilita la multiplexación de TCP.	true, false	false
ncp/connection_multiplexing_number	Si la multiplexación de TCP está habilitada, esto especifica el número de conexiones TCP inactivas que están disponibles.	0 - 2147483647	6

Información sobre las anotaciones:

• Coincidencia REGEX (expresión regular) de la ruta
  • Puede habilitar o deshabilitar la coincidencia de expresiones regulares del parámetro path de entrada (pero no host) mediante la anotación ncp/use-regex. Si se establece como false, la coincidencia exacta de la ruta se realiza mediante la coincidencia equals. Si se establece como true, la coincidencia de expresión regular se realiza agregando el inicio del carácter de cadena (^) y el final del carácter de cadena ($) a la ruta para que todo el URI de solicitud coincida con el patrón. Tenga en cuenta que cuando se utiliza el operador OR (|), siempre se debe especificar el ámbito con paréntesis para que ^ y $ se apliquen a todos los operandos. Por ejemplo, path: /(tea|coffee|milk). Un ejemplo de especificación de entrada:

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: cafe-ingress
      annotations:
        kubernetes.io/ingress.class: "nsx"
        #/tea/cup will be served by tea-svc:80
        ncp/use-regex: "True"
    spec:
      rules:
      - host: cafe.example.com
        http:
          paths:
          # for this tea and coffee NCP will configure regex rule
          - path: /tea/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: tea-svc
                port:
                  number: 80
          - path: /coffee/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: coffee-svc
                port:
                  number: 80
          # for juice and alcohol NCP will configure Exact and Prefix rules
          - path: /juice
            pathType: Exact
            backend:
              service:
                name: juice-svc
                port:
                  number: 80
          - path: /alcohol
            pathType: Prefix
            backend:
              service:
                name: bar
                  number: 80

  • Actualizar las entradas antes de actualizar NCP
    Este proceso solo es necesario en caso de que haya entradas que requieran la coincidencia de todas las rutas secundarias mediante el uso de los caracteres "." y "*".

    1. Actualice las entradas para que incluyan la anotación ncp/use-regex: true.
    2. Para la coincidencia de todas las rutas secundarias, si tiene rutas como /coffee/* o /*, cámbielas a /coffee/.* y /.*.

       /coffee/.* coincidirá con /coffee/, /coffee/a, /coffee/b, /coffee/a/b, etc. /.* coincidirá con /coffee, /tea, /coffee/a, etc. Si omite la ruta, el comportamiento será igual que path: /.*.

• En el siguiente ejemplo de la anotación ingress.kubernetes.io/rewrite-target, las rutas /tea y /coffee se cambiarán a / antes de enviar la URL al servicio back-end.

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: cafe-ingress
    annotations:
      ingress.kubernetes.io/rewrite-target: /
  spec:
    rules:
    - host: cafe.example.com
      http:
        paths:
        - path: /tea
          pathType: ImplementationSpecific
          backend:
            service:
              name: tea-svc
              port:
                number: 80
        - path: /coffee
          pathType: ImplementationSpecific
          backend:
            service:
              name: coffee-svc
              port:
                number: 80

  Si path se especifica mediante una expresión regular, los grupos capturados se guardarán en marcadores de posición numerados con el formato $1, $2, etc. Estos marcadores de posición se pueden utilizar como parámetros en la anotación ingress.kubernetes.io/rewrite-target. No se admiten marcadores de posición con nombre ni grupos capturados con nombre. Por ejemplo,

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: cafe-ingress
    annotations:
      kubernetes.io/ingress.class: "nsx"
      ncp/use-regex: "true"
      #/tea/cup will be rewritten to /cup before sending request to endpoint
      ingress.kubernetes.io/rewrite-target: /$1
  spec:
    rules:
    - host: cafe.example.com
      http:
        paths:
        - path: /tea/(.*)
          pathType: ImplementationSpecific
          backend:
            service:
              name: tea-svc
              port:
                number: 80
        - path: /coffee/(.*)
          pathType: ImplementationSpecific
          backend:
            service:
              name: coffee-svc
              port:
                number: 80

• Información sobre la anotación kubernetes.io/ingress.allow-http:
  • Si la anotación se establece como false, se crearán reglas para el servidor virtual HTTPS.
  • Si se establece como true o no se incluye, se crearán reglas para los servidores virtuales HTTP y HTTPS. Tenga en cuenta que se crearán reglas HTTPS si la sección TLS está presente en la especificación de entrada.
• Información sobre la anotación ncp/http-redirect:
  • Si la anotación se establece como false, el tráfico HTTP que entra (puerto 80) hacia el servidor virtual HTTP no se redirigirá al servidor virtual HTTPS.
  • Si la anotación se establece como true, el tráfico HTTP que entra (puerto 80) hacia el servidor virtual HTTP se redirigirá al servidor virtual HTTPS (puerto 443).

  Esta anotación solo es válida si está presente la sección TLS. Esta anotación tiene prioridad sobre kubernetes.io/ingress.allow-http. Cuando se establece como true, dirigirá el tráfico HTTP que coincida hacia HTTPS con independencia del valor que establezca para kubernetes.io/ingress.allow-http.

• Información sobre la anotación kubernetes.io/ingress.class:
  • Si el valor es nsx, NCP gestionará la entrada. Si se especifica otro valor, NCP ignorará la entrada. Para obtener más información, consulte Controladores de entrada de terceros.
• Para obtener más información sobre la anotación nsx/loadbalancer, consulte Objetos CRD LoadBalancer para ajustar la escala de entrada.
• Información sobre la anotación ncp/allowed-source-range:
  • Solo se admite en el modo Directiva.
  • Cuando se establece, solo se aceptará una solicitud entrante si su IP de origen se incluye en esta anotación. De lo contrario, se descartará el tráfico.
  • Puede especificar una combinación de CIDR, direcciones IP y rangos de IP. Por ejemplo, 1.1.1.1/24, 2.2.2.2, 3.3.3.3-4.4.4.4.
  • Ejemplo de YAML:

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: cafe-ingress
      annotations:
        kubernetes.io/ingress.class: "nsx"
        #Source IP addresses allowed to access ingress URL
        ncp/allowed-source-range: "192.168.128.0/17, 192.168.64.0-192.168.64.255, 192.168.16.32"
    spec:
      tls:
      - hosts:
        - cafe.example.com
      rules:
      - host: cafe.example.com
        http:
          paths:
          - path: /tea
            pathType: ImplementationSpecific
            backend:
              service:
                name: tea-svc
                port:
                  number: 80
          - path: /coffee
            pathType: ImplementationSpecific
            backend:
              service:
                name: coffee-svc
                port:
                  number: 80

• Información sobre la anotación ncp/ssl-mode:
  • Solo se admite en el modo Directiva.
  • Esta anotación se aplica a todas las reglas de una entrada y el equilibrador de carga funcionará en el modo SSL seleccionado para estas reglas.

    Si ncp/ssl-mode está establecido en reencrypt o passthrough, kubernetes.io/ingress.allow-http debe establecerse en False. Esta anotación no se puede establecer en passthrough si está establecida la anotación ingress.kubernetes.io/rewrite-target, ncp/use-regex o ncp/allowed-source-range.

    Si ncp/ssl-mode se establece en passthrough, no se admite el atributo path en la especificación de rules.

• Acerca de la autenticación de cliente de JWT:
  • Para habilitar la autenticación del cliente de JWT para todas las reglas bajo una entrada, tanto ncp/jwt-alg como ncp/jwt-secret deben tener un valor válido. Cuando se habilita, el tráfico HTTP entrante, solo se transfiere al back-end si se proporciona un token web JSON válido. De lo contrario, el tráfico se rechazará con el estado 401.
  • Esta función no es compatible con las siguientes anotaciones:
    • kubernetes.io/ingress.allow-http: true
    • ncp/http-redirect: true
    • ncp/ssl-mode: passthrough
  • ncp/jwt-alg:
    • Algoritmos simétricos compatibles: HS256
    • Algoritmos asimétricos compatibles: RS256
  • ncp/jwt-secret:
    • Debe configurarse una clave simétrica o un certificado público en un secreto de Kubernetes con el nombre especificado en esta anotación en el mismo espacio de nombres que la entrada.
    • Para los algoritmos simétricos, el secreto debe estar almacenado en el campo jwt.key.
    • Para los algoritmos asimétricos, el certificado público debe estar almacenado en el campo tls.crt.
    • La autenticación del cliente de JWT se deshabilitará si el secreto simétrico o el certificado público no se almacenan en las ubicaciones mencionadas anteriormente, o si los datos almacenados en el secreto no son válidos.
  • ncp/jwt-token:
    • Solo se puede configurar un elemento en esta anotación.
    • _arg_<param_name>: para los JWT pasados como un parámetro de URI. Especifique el nombre del parámetro que contiene JWT.
    • _cookie_<cookie_name>: para los JWT pasados como una cookie. Especifique el nombre de la cookie que contiene JWT.
• Acerca de las anotaciones ncp/connection_multiplxing_enabled y ncp/connection_multiplxing_number:
  • La multiplexación de TCP no puede coexistir con HTTP NTLM. En NSX, si un grupo de equilibradores de carga con multiplexación de TCP habilitada está vinculado a un servidor de capa 7 habilitado para NTLM, la configuración de NTLM tendrá prioridad sobre la multiplexación de TCP.
  • Ejemplo de YAML:

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: cafe-ingress
      annotations:
        ncp/connection_multiplexing_enabled: "true"
        ncp/connection_multiplexing_number: 100
    spec:
      tls:
      - hosts:
        - cafe.example.com
      rules:
      - host: cafe.example.com
        http:
          paths:
          - path: /tea
            backend:
              service:
                name: tea-svc
                port:
                  number: 80
          - path: /coffee
            backend:
              service:
                name: coffee-svc
                port:
                  number: 80

Errores

Los errores se anotan en el recurso de entrada. La clave de error es ncp/error.loadbalancer y la clave de advertencia es ncp/warning.loadbalancer. El error y la advertencia posibles son:

• ncp/error.loadbalancer: DEFAULT_BACKEND_IN_USE

  Este error indica que ya existe una entrada con un back-end predeterminado. La entrada estará inactiva. Este error se produce si 1) la entrada es para HTTP y existe otra entrada para HTTP con un back-end predeterminado; 2) la entrada es para HTTPS y existe otra entrada para HTTPS con un back-end predeterminado, o 3) la entrada es para HTTP y HTTPS y existe otra entrada para HTTP y HTTPS con un back-end predeterminado. Para solucionar el error, elimine y vuelva a crear la entrada con una especificación correcta.

• ncp/warning.loadbalancer: SECRET_NOT_FOUND

  Este error indica que el secreto especificado en la especificación de entrada no existe, o si ncp/jwt-alg y ncp/jwt-secret están anotados, pero el secreto no se puede encontrar en el mismo espacio de nombres que la entrada. La entrada se activará parcialmente. Para solucionar el error, cree el secreto que falta. Tenga en cuenta que las advertencias incluidas en la anotación no se borrarán durante el ciclo de vida del recurso de entrada.

• ncp/warning.loadbalancer: INVALID_INGRESS
  Este error indica que se cumple una de las siguientes condiciones. La entrada estará inactiva. Para solucionar el error, elimine y vuelva a crear la entrada con una especificación correcta.

  • Una regla de entrada entra en conflicto con otra regla de entrada en el mismo clúster de Kubernetes. Solo se producen conflictos entre entradas que tengan la misma estrategia de coincidencia, es decir, con el mismo valor de la anotación ncp/use-regex.
  • La anotación kubernetes.io/ingress.allow-http se establece como false y la entrada no tiene una sección TLS.
  • La anotación ncp/http-redirect se establece como true y la entrada no tiene una sección TLS.
  • Una regla de entrada no tiene host ni path especificados. Una regla de entrada de este tipo tiene la misma funcionalidad que el back-end predeterminado de entrada. Utilice el back-end predeterminado de entrada en su lugar.
  • La entrada tiene anotaciones de JWL que no se pueden procesar correctamente. Por ejemplo:
    • Falta ncp/jwt-alg o ncp/jwt-secret.
    • ncp/jwt-alg está configurado con un algoritmo no admitido.
    • ncp/jwt-alg y ncp/jwt-secret están configurados con otras anotaciones de habilitación de HTTP, o con acceso directo a SSL.