Configuración del controlador de entrada nativo de OCI

Enrutar solicitudes según el host

Puede configurar el controlador de entrada nativo de OCI para enrutar una solicitud entrante según el nombre de dominio en la cabecera Host de la solicitud (el host al que se envió originalmente la solicitud).

Para enrutar una solicitud a un puerto y servicio de backend concreto según el host, cree una regla de ruta en el manifiesto Ingress. Si el host coincide con la regla de ruta, el controlador de entrada nativo de OCI enruta la solicitud al puerto y servicio de backend asociados.

Por ejemplo, puede definir la siguiente regla para direccionar las solicitudes enviadas originalmente a http://foo.bar.com a un servicio de backend denominado ServiceA en el puerto 80. Todo el tráfico entrante enviado originalmente a http://foo.bar.com se direcciona a ServiceA en el puerto 80.

kind: Ingress
...
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
        - pathType: Prefix
          path: /
          backend:
            serviceName: ServiceA
            servicePort: 80

Enrutar solicitudes a diferentes servicios de backend según la ruta de acceso

Puede configurar el controlador de entrada nativo de OCI para enrutar las solicitudes entrantes a diferentes servicios de backend, en función de los elementos de la ruta a la que se enviaron originalmente las solicitudes.

Para enrutar una solicitud a un puerto y servicio de backend concreto según la ruta de acceso, cree una regla de ruta en el manifiesto Ingress. Si la ruta coincide con la regla de ruta, el controlador de entrada nativo de OCI enruta la solicitud al puerto y servicio de backend asociados. Puede especificar varias rutas en la misma regla para enrutar solicitudes a backends diferentes.

Por ejemplo, puede definir la siguiente regla para enrutar solicitudes en función de la ruta a la que se envió originalmente la solicitud:

• Si la ruta empieza por /app1, el controlador de entrada nativo de OCI enruta la solicitud a un servicio de backend denominado ServiceA en el puerto 80.
• Si la ruta empieza por /app2, el controlador de entrada nativo de OCI enruta la solicitud a un servicio de backend denominado ServiceB en el puerto 443.

Puesto que la regla no especifica un host, la regla se aplica a todo el tráfico entrante.

kind: Ingress
...
spec:
  rules:
    - http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: ServiceA
            servicePort: 80
        - pathType: Prefix
          path: /app2
          backend:
            serviceName: ServiceB
            servicePort: 443

Enrutar solicitudes según el host y la ruta

Puede configurar el controlador de entrada nativo de OCI para enrutar una solicitud entrante según el nombre de dominio de la cabecera Host de la solicitud (el host al que se envió originalmente la solicitud) y los elementos de la ruta a la que se envió la solicitud original.

Para enrutar una solicitud a un puerto y servicio de backend concreto según el host y la ruta de acceso, cree una regla de ruta en el manifiesto Ingress. Si el host y la ruta coinciden con la regla de ruta, el controlador de entrada nativo de OCI enruta la solicitud al puerto y servicio de backend asociados.

Por ejemplo, puede definir la siguiente regla para direccionar las solicitudes enviadas originalmente a http://foo.bar.com/app1 a un servicio de backend denominado foo en el puerto 80:

kind: Ingress
...
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: foo
            servicePort: 80

Enrutar solicitudes a un backend por defecto

Puede configurar el controlador de entrada nativo de OCI para enrutar las solicitudes entrantes a un backend por defecto. Puede configurar un backend por defecto para gestionar solicitudes que no coincidan con ninguna regla de ruta.

Por ejemplo, puede definir el siguiente defaultBackend para direccionar solicitudes que no coincidan con otras reglas del manifiesto Ingress a un servicio de backend denominado ServiceC en el puerto 8080.

Tenga en cuenta que si no especifica ninguna otra regla en un manifiesto Ingress, debe especificar un defaultBackend.

kind: Ingress
...
spec:
  rules:
    - http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: ServiceA
            servicePort: 80
        - pathType: Prefix
          path: /app2
          backend:
            serviceName: ServiceB
            servicePort: 443
  defaultBackend:
    service:
      name: ServiceC
      port:
        number: 8080

Personalización del comportamiento general mediante anotaciones

Puede agregar anotaciones a los manifiestos de recursos IngressClass o Ingress para personalizar el comportamiento general del controlador de entrada nativo de OCI.

Personalización del comportamiento de las comprobaciones del sistema mediante anotaciones

Puede agregar anotaciones al manifiesto de recurso Ingress para personalizar las comprobaciones del sistema realizadas por el equilibrador de carga creado por el controlador de entrada nativo de OCI. Para obtener más información sobre las comprobaciones del sistema del equilibrador de carga, consulte Comprobaciones del sistema para equilibradores de carga.

Opción 1: el controlador de entrada nativo de OCI obtiene el certificado del servicio Certificates mediante un secreto de Kubernetes

Para configurar el controlador de entrada nativo de OCI para obtener un certificado del servicio OCI Certificates:

1. Obtenga un par de claves pública y privada TLS y un certificado.

   En entornos de producción, obtiene un certificado TLS de la autoridad de certificación seleccionada enviando una solicitud de firma de certificado. Durante el proceso de solicitud de certificado, se generan una clave pública y la clave privada correspondiente.

   En entornos de desarrollo y prueba, puede crear un certificado autofirmado y generar una clave privada usted mismo mediante una herramienta como OpenSSL. Por ejemplo (mediante OpenSSL 3.0 o posterior):

   1. Genere un par de claves públicas y privadas introduciendo los siguientes comandos:

      openssl genrsa -out rootCA.key 4096

      openssl req -x509 -addext basicConstraints=critical,CA:TRUE -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt -subj /CN=RootCA

   2. Genere un certificado introduciendo los siguientes comandos:

      openssl genrsa -out server.key 4096

      openssl req -new -sha256 -key server.key -subj /C=US/ST=CA/O=MyOrg,Inc./CN=my.example.com -out server.csr

      openssl x509 -req -in server.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out server.crt -days 500 -sha256

   En este ejemplo:

   • rootCA.key contiene el par de claves para la CA raíz.
   • rootCA.crt contiene el certificado de CA raíz.
   • server.key contiene el par de claves para generar el certificado de servidor.
   • server.csr contiene la solicitud de firma de certificado para el certificado de servidor.
   • server.crt contiene el certificado de servidor generado.
2. Cree un recurso secreto de Kubernetes de una de las siguientes formas:

   • Mediante el comando kubectl create secret generic, introduzca:

     kubectl create secret generic <k8s-secret-name> --type=kubernetes.io/tls --from-file=ca.crt=<path-and-filename>.crt --from-file=tls.crt=<path-and-filename>.crt --from-file=tls.key=<path-and-filename>.key

     donde:

     • <k8s-secret-name> es el nombre que ha elegido para el secreto de Kubernetes
     • --from-file=ca.crt=<path-and-filename>.crt especifica la ruta de acceso al archivo que contiene el certificado de CA raíz. Por ejemplo, --from-file=ca.crt=rootCA.crt
     • --from-file=tls.crt=<path-and-filename>.crt especifica la ruta al archivo que contiene el certificado de servidor generado. Por ejemplo, --from-file=tls.crt=server.crt
     • --from-file=tls.key=<path-and-filename>.key especifica la ruta de acceso al archivo que contiene la clave privada generada. Por ejemplo, --from-file=tls.key=server.key

     Por ejemplo:

     kubectl create secret generic example-tls-secret --type=kubernetes.io/tls --from-file=ca.crt=rootCA.crt --from-file=tls.crt=server.crt --from-file=tls.key=server.key

   • Mediante un archivo de manifiesto de recurso Secret:

     1. Defina el secreto de Kubernetes en un archivo .yaml con el siguiente formato:

        apiVersion: v1
        kind: Secret
        metadata:
          name: <k8s-secret-name>
        type: kubernetes.io/tls
        data:
          ca.crt: <base64-encoded-certificate-chain>
          tls.crt: <base64-encoded-server-certificate>
          tls.key: <base64-encoded-private-key>

        donde:

        • name: <k8s-secret-name> es el nombre que ha elegido para el recurso secreto de Kubernetes.
        • ca.crt: <base64-encoded-certificate-chain> es el contenido del archivo (o archivos) que contiene certificados intermedios que forman una cadena de certificados desde el certificado de hoja hasta la autoridad de certificación. Tenga en cuenta que puede omitir ca.cert, siempre que incluya toda la cadena de certificados como el valor de tls.cert (en cuyo caso, inicie la cadena de certificados con el contenido del archivo que contiene el certificado de servidor generado, seguido de los certificados restantes).
        • tls.crt: <base64-encoded-server-certificate> es el contenido del archivo que contiene el certificado de servidor generado.
        • tls.key: <base64-encoded-private-key> es el contenido del archivo que contiene la clave privada generada.

        Por ejemplo:

        apiVersion: v1
        kind: Secret
        metadata:
          name: example-tls-secret
        type: kubernetes.io/tls
        data:
          ca.crt : MIIFGERTegcDFRTuSDGfghREdE______Jre
          tls.crt: MIIC2DCCAcCgAwIBAgIBATANBg______kqh
          tls.key: MIIEpgIBAAKCAQEA7yn3bRHQ5F______HMQ

     2. Cree el recurso secreto introduciendo kubectl create -f <filename>.yaml

3. Agregue el secreto de Kubernetes a un manifiesto de recurso Ingress:
   1. Defina un nuevo recurso de entrada en un archivo .yaml. Consulte Creación de recurso de entrada.
   2. En la sección spec: del manifiesto, agregue un elemento tls: que especifique tanto el host que va a recibir tráfico HTTPS como el nombre del secreto de Kubernetes, en el formato:

      kind: Ingress
      ...
      spec:
        tls:
        - hosts:
            - <host-name>
          secretName: <k8s-secret-name>

      Por ejemplo:

      kind: Ingress
      ...
      spec:
        tls:
        - hosts:
            - my.example.com
          secretName: example-tls-secret

   3. En la sección rules: del manifiesto, agregue una regla para el host que va a recibir tráfico HTTPS y especifique 443 como puerto en el que desea recibir tráfico HTTPS.

      Por ejemplo:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: acme-tls-secret-ingress
      spec:
        tls:
        - hosts:
            - my.example.com
          secretName: example-tls-secret
        rules:
        - host: "my.example.com"
          http:
            paths:
            - pathType: Prefix
              path: "/TLSPath"
              backend:
                service:
                  name: tls-test
                  port:
                    number: 443

   4. Cree el recurso introduciendo kubectl create -f <filename>.yaml

Al crear el recurso de entrada, el controlador de entrada nativo de OCI utiliza el secreto de Kubernetes para obtener un certificado de tipo Importado y un grupo de autoridades de certificación (grupo de autoridades de certificación) del servicio OCI Certificates. El controlador de entrada nativo de OCI asocia el certificado al listener y el grupo de autoridades de certificación al juego de backends.

Cuando el listener que recibe en el puerto 443 recibe una solicitud HTTPS en el host especificado, el listener utiliza el certificado para la terminación TLS. A continuación, el listener utiliza la regla de direccionamiento para reenviar la solicitud al juego de backends. El juego de backends crea una nueva conexión TLS con los backends que se ejecutan en el cluster (mediante el grupo de autoridades de certificación como autoridad de confianza para la nueva conexión).

Opción 2: obtiene el certificado del servicio Certificates

Para configurar el controlador de entrada nativo de OCI para que utilice un certificado que haya obtenido del servicio OCI Certificates:

1. Cree un certificado en el servicio OCI Certificates de una de las siguientes formas:
   • mediante la importación de un certificado emitido por una CA de terceros (el certificado será del tipo Importado)
   • emitiendo el certificado internamente desde una CA de servicio de certificados (el certificado será de tipo emitido por la CA interna)

   No cree un certificado para gestionar externamente (de tipo Emitido por CA interna, gestionado externamente). Para obtener más información, consulte Creación de un certificado.

2. Anote el OCID del certificado.
3. Agregue el OCID del certificado a un manifiesto de recurso Ingress:
   1. Defina un nuevo recurso de entrada en un archivo .yaml. Consulte Crear recurso de entrada.
   2. En la sección metadata:, agregue un elemento annotations: que especifique el OCID del certificado que ha creado en el servicio OCI Certificates, con el formato:

      kind: Ingress
      metadata:
        name: <i-name>
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid>
      spec:
      ...

      donde:

      • name: <i-name> es el nombre que elija para el recurso de entrada.
      • oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid> es el OCID del certificado que ha creado en el servicio OCI Certificates

      Por ejemplo:

      kind: Ingress
      metadata:
        name: acme-tls-certificate-ingress
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: ocid1.certificate.oc1.iad.amaaaaaa______gabc
      spec:
      ...

   3. En la sección rules: del manifiesto de recurso Ingress, agregue una regla para el host que va a recibir tráfico HTTPS y especifique 443 como puerto en el que desea recibir tráfico HTTPS.

      Por ejemplo:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: acme-tls-certificate-ingress
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: ocid1.certificate.oc1.iad.amaaaaaa______gabc
      spec:
        rules:
        - host: "my.example.com"
          http:
            paths:
            - pathType: Prefix
              path: "/TLSPath"
              backend:
                service:
                  name: tls-test
                  port:
                    number: 443

   4. Cree el recurso introduciendo kubectl create -f <filename>.yaml

Lo que sucede al crear el recurso de entrada depende de cómo haya creado el certificado en el servicio OCI Certificates:

• Si ha creado el certificado mediante la importación de un certificado emitido por una CA de terceros, el certificado es del tipo Importado. El controlador de entrada nativo de OCI asocia el certificado al listener, crea un grupo de autoridades de certificación a partir de la cadena de certificados y asocia el grupo de autoridades de certificación al juego de backends. Tenga en cuenta que no puede configurar certificados de tipo Importados para que se roten automáticamente.
• Si creó el certificado emitiendo el certificado internamente desde una CA de servicio de certificados, el certificado es del tipo Emitido por la CA interna. El controlador de entrada nativo de OCI asocia el certificado al listener, obtiene el OCID de la CA y asocia ese OCID al juego de backends. Tenga en cuenta que puede configurar certificados de tipo Emitidos por CA interna para que se roten automáticamente.

Cuando el listener que recibe en el puerto 443 recibe una solicitud HTTPS en el host especificado, el listener utiliza el certificado para la terminación TLS. A continuación, el listener utiliza la regla de direccionamiento para reenviar la solicitud al juego de backends. El juego de backends crea una nueva conexión TLS con los backends que se ejecutan en el cluster (mediante el grupo de autoridades de certificación o la autoridad de certificación identificada por su OCID, como autoridad de confianza para la nueva conexión).

Aplicación de etiquetas definidas al equilibrador de carga

Un administrador de etiquetas configura y gestiona las etiquetas definidas. Una etiqueta definida consta de un espacio de nombres de etiqueta, una clave y un valor. El espacio de nombres de la etiqueta y la definición de la clave de la etiqueta deben estar configurados en un arrendamiento para poder aplicar una etiqueta definida a un recurso.

Para especificar que el controlador de entrada nativo de OCI debe aplicar etiquetas definidas al equilibrador de carga, utilice la anotación oci-native-ingress.oraclecloud.com/defined-tags en el manifiesto IngressClass, con el siguiente formato:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: <ic-name>
  annotations:
    oci-native-ingress.oraclecloud.com/defined-tags: '{"<tag-namespace>": {"<tag-key>": "<tag-value>"}}'
spec:
  ...

donde:

• <tag-namespace> es el espacio de nombres de la etiqueta al que pertenece la etiqueta.
• <tag-key> es el nombre de una etiqueta definida que se va a aplicar al equilibrador de carga.
• <tag-value> es un valor para la etiqueta de una lista de valores predefinida, o un nuevo valor, o está en blanco (en función de cómo se haya configurado la etiqueta definida).

El valor de la anotación oci-native-ingress.oraclecloud.com/defined-tags es una cadena JSON, que permite especificar varios espacios de nombres de etiqueta, claves de etiqueta y valores de etiqueta en formato JSON.

Por ejemplo:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: my-ingress-class
  annotations:
    oci-native-ingress.oraclecloud.com/defined-tags: '{"Operations": {"CostCenter": "42", "Department": "001"}, "Sales": {"Region": "US"}}'
spec:
  ...

Al cambiar una de las etiquetas de la anotación oci-native-ingress.oraclecloud.com/defined-tags del manifiesto IngressClass, el controlador de entrada nativo de OCI vuelve a aplicar al equilibrador de carga todas las etiquetas definidas especificadas por la anotación. Sin embargo, si una etiqueta definida contiene una variable de etiqueta, el controlador de entrada nativo de OCI solo vuelve a aplicar la etiqueta definida al equilibrador de carga si la etiqueta aún no está presente.

Tenga en cuenta que para permitir que el controlador de entrada nativo de OCI aplique etiquetas definidas a un equilibrador de carga, debe existir una política de IAM adecuada para permitir que el controlador de entrada nativo de OCI utilice el espacio de nombres de etiqueta adecuado. Para obtener más información, consulte:

• Asignación de permisos al controlador de entrada nativo de OCI como programa independiente
• Asignación de permisos al complemento de cluster de controlador de entrada nativo de OCI

Aplicación de etiquetas de formato libre al equilibrador de carga

Un administrador de etiquetas no gestiona las etiquetas de formato libre. Una etiqueta de formato libre consta de una clave y un valor. A diferencia de las etiquetas definidas, las etiquetas de formato libre no pertenecen a un espacio de nombres de etiqueta.

Para especificar que el controlador de entrada nativo de OCI debe aplicar etiquetas de formato libre al equilibrador de carga, utilice la anotación oci-native-ingress.oraclecloud.com/freeform-tags en el manifiesto IngressClass, con el siguiente formato:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: <ic-name>
  annotations:
    oci-native-ingress.oraclecloud.com/freeform-tags: '{"<tag-key>": "<tag-value>"}'
spec:
  ...

donde:

• <tag-key> es un nombre para la etiqueta de formato libre que se va a aplicar al equilibrador de carga.
• <tag-value> es un valor para que la etiqueta de formato libre se aplique al equilibrador de carga.

El valor de la anotación oci-native-ingress.oraclecloud.com/freeform-tags es una cadena JSON, que permite especificar varias claves de etiqueta y valores de etiqueta en formato JSON.

Por ejemplo:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: my-ingress-class
  annotations:
    oci-native-ingress.oraclecloud.com/freeform-tags: '{"Project": "Red", "Version": "Alpha"}'
spec:
  ...

Al cambiar una de las etiquetas de la anotación oci-native-ingress.oraclecloud.com/freeform-tags del manifiesto IngressClass, el controlador de entrada nativo de OCI vuelve a aplicar al equilibrador de carga todas las etiquetas de formato libre especificadas por la anotación.

Aplicación de valores por defecto de etiqueta al equilibrador de carga

Los valores por defecto de las etiquetas se configuran para un compartimento específico. Los valores por defecto de etiqueta son específicos del compartimento. Los valores por defecto de etiqueta especifican etiquetas definidas que se aplican automáticamente a todos los recursos creados en un compartimento específico en el momento de la creación.

Al utilizar el controlador de entrada nativo de OCI versión 1.4.0 (o posterior), los valores por defecto de etiqueta se aplican automáticamente a los equilibradores de carga que crea el controlador de entrada nativo de OCI. Posteriormente, el controlador de entrada nativo de OCI conserva un valor por defecto de etiqueta aplicado a un equilibrador de carga a menos que se cumpla una de las siguientes condiciones:

• Elimine manualmente un valor por defecto de etiqueta que se haya aplicado automáticamente a un equilibrador de carga.
• Puede especificar un valor por defecto de etiqueta como una etiqueta definida mediante la anotación oci-native-ingress.oraclecloud.com/defined-tags (en cuyo caso, el controlador de entrada nativo de OCI trata el valor por defecto de etiqueta como cualquier otra etiqueta definida).

Tenga en cuenta que los valores por defecto de etiqueta con valores aplicados por el usuario no están soportados. Si se ha configurado un valor por defecto de etiqueta con un valor aplicado por el usuario para un compartimento en el que el controlador de entrada nativo de OCI va a crear o gestionar un equilibrador de carga, debe utilizar la anotación oci-native-ingress.oraclecloud.com/defined-tags para especificar el valor por defecto de etiqueta como etiqueta definida.

Para los equilibradores de carga creados mediante una versión del controlador de entrada nativo de OCI anterior a la versión 1.4.0, o al utilizar la anotación oci-native-ingress.oraclecloud.com/id para especificar que el controlador de entrada nativo de OCI gestione un equilibrador de carga existente, tenga en cuenta que los valores por defecto de etiqueta no están soportados. En ambos casos, para aplicar o retener un valor por defecto de etiqueta, utilice la anotación oci-native-ingress.oraclecloud.com/defined-tags para especificar el valor por defecto de etiqueta como una etiqueta definida en su lugar.