Estás consultando la documentación de Apigee Edge.
Consulta la
documentación de Apigee X. Información
Edge Microgateway v. 3.2.x
En este tema, se analiza cómo administrar y configurar Edge Microgateway.
Actualiza Edge Microgateway si tienes una conexión a Internet
En esta sección, se explica cómo actualizar una instalación existente de Edge Microgateway. Si operas sin conexión a Internet, consulta ¿Puedo instalar Edge Microgateway sin conexión a Internet?.
Apigee recomienda que pruebes tu configuración existente con la versión nueva antes de actualizar tu entorno de producción.
- Ejecuta el siguiente comando de
npm
para actualizar a la versión más reciente de Edge Microgateway:npm upgrade edgemicro -g
Para instalar una versión específica de Edge Microgateway, debes especificar el número de versión en el comando de instalación. Por ejemplo, para instalar la versión 3.2.3, usa el siguiente comando:
npm install edgemicro@3.2.3 -g
- Verifica el número de versión. Por ejemplo, si instalaste la versión 3.2.3:
edgemicro --version current nodejs version is v12.5.0 current edgemicro version is 3.2.3
- Por último, actualiza a la versión más reciente del proxy edgemicro-auth:
edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME
Realiza cambios en la configuración
Entre los archivos de configuración que debes conocer, se incluyen los siguientes:
- Archivo de configuración del sistema predeterminado
- Archivo de configuración predeterminado para una instancia de Edge Microgateway recién inicializada
- Archivo de configuración dinámico para instancias en ejecución
En esta sección, se analizan estos archivos y lo que debes saber para cambiarlos.
Archivo de configuración del sistema predeterminado
Cuando instalas Edge Microgateway, se coloca aquí un archivo de configuración predeterminado del sistema:
prefix/lib/node_modules/edgemicro/config/default.yaml
Donde prefix es el directorio del prefijo npm
. Consulta
Dónde está instalado Edge Microgateway si no puedes ubicar este directorio.
Si cambias el archivo de configuración del sistema, debes reiniciar, reconfigurar y reiniciar Edge Microgateway:
edgemicro initedgemicro configure [params]
edgemicro start [params]
Archivo de configuración predeterminado para las instancias de Edge Microgateway recién inicializadas
Cuando ejecutas edgemicro init
, el archivo de configuración del sistema (descrito anteriormente), default.yaml
, se coloca en el directorio ~/.edgemicro
.
Si cambias el archivo de configuración en ~/.edgemicro
, debes volver a configurar y reiniciar Edge Microgateway:
edgemicro stopedgemicro configure [params]
edgemicro start [params]
Archivo de configuración dinámico para instancias en ejecución
Cuando ejecutas edgemicro configure [params]
, se crea un archivo de configuración dinámica en ~/.edgemicro
. El nombre del archivo se basa en este patrón: org-env-config.yaml
, en el que org y env son los nombres de la organización y del entorno de Apigee Edge. Puedes usar este archivo para realizar cambios en la configuración y, luego, volver a cargarlos sin tiempo de inactividad. Por ejemplo, si agregas y configuras un complemento, puedes volver a cargar la configuración sin incurrir en tiempo de inactividad, como se explica a continuación.
Si Edge Microgateway se ejecuta (opción de tiempo de inactividad cero):
- Vuelve a cargar la configuración de Edge Microgateway:
edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET
Aquí:
- $ORG es el nombre de la organización de Edge (debes ser administrador de la organización).
- $ENV es un entorno de tu organización (como “test” o “prod”).
- $KEY es la clave que mostró antes el comando configure.
- $SECRET es la clave que mostró antes el comando configure.
Por ejemplo:
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \ -s 05c14356e42ed1...4e34ab0cc824
Si Edge Microgateway está detenido, haz lo siguiente:
- Reinicia Edge Microgateway:
edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
Aquí:
- $ORG es el nombre de la organización de Edge (debes ser administrador de la organización).
- $ENV es un entorno de tu organización (como “prueba” o “producción”).
- $KEY es la clave que mostró antes el comando configure.
- $SECRET es la clave que mostró antes el comando configure.
Por ejemplo:
edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \ -s 05c1435...e34ab0cc824
Este es un ejemplo de archivo de configuración. Para obtener detalles sobre los parámetros de configuración del archivo de configuración, consulta la Referencia de configuración de Edge Microgateway.
edge_config: bootstrap: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' vaultName: microgateway authUri: 'https://%s-%s.apigee.net/edgemicro-auth' baseUri: >- https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s bootstrapMessage: Please copy the following property to the edge micro agent config keySecretMessage: The following credentials are required to start edge micro products: 'https://docs-test.apigee.net/edgemicro-auth/products' edgemicro: port: 8000 max_connections: 1000 max_connections_hard: 5000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - oauth headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true oauth: allowNoAuthorization: false allowInvalidAuthorization: false verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey' analytics: uri: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test
Configura variables de entorno
Los comandos de la interfaz de línea de comandos que requieren valores para la organización y el entorno de Edge, así como la clave y el secreto necesarios a fin de iniciar Edge Microgateway, se pueden almacenar en las siguientes variables de entorno:
EDGEMICRO_ORG
EDGEMICRO_ENV
EDGEMICRO_KEY
EDGEMICRO_SECRET
Configurar estas variables es opcional. Si los configuraste, no es necesario que especifiques sus valores cuando usas la interfaz de línea de comandos (CLI) para configurar y, luego, iniciar Edge Microgateway.
Configura SSL en el servidor de Edge Microgateway
Mira los siguientes videos para aprender a configurar TLS en Apigee Edge Microgateway:
Video | Descripción |
---|---|
Configura la TLS unidireccional con dirección norte | Aprende a configurar TLS en Apigee Edge Microgateway. En este video, se proporciona una descripción general de TLS y su importancia, se presenta TLS en Edge Microgateway y se muestra cómo configurar la TLS unidireccional con dirección norte. |
Configura la TLS bidireccional con dirección norte | Este es el segundo video sobre la configuración de TLS en Apigee Edge Microgateway. En este video, se explica cómo configurar la TLS bidireccional con dirección norte. |
Configura la TLS de 1 y 2 vías con dirección sur | En este tercer video sobre la configuración de TLS en Apigee Edge Microgateway, se explica cómo configurar la TLS de 1 y 2 vías hacia el sur. |
Puedes configurar el servidor de Microgateway para que use SSL. Por ejemplo, con SSL configurado, puedes llamar a las API a través de Edge Microgateway con el protocolo "https", de la siguiente manera:
https://localhost:8000/myapi
Para configurar SSL en el servidor de Microgateway, sigue estos pasos:
- Obtén u obtén un certificado y una clave SSL con la utilidad openssl o el método que prefieras.
- Agrega el atributo
edgemicro:ssl
al archivo de configuración de Edge Microgateway. Para obtener una lista completa de las opciones, consulta la siguiente tabla. Por ejemplo:
edgemicro: ssl: key: <absolute path to the SSL key file> cert: <absolute path to the SSL cert file> passphrase: admin123 #option added in v2.2.2 rejectUnauthorized: true #option added in v2.2.2 requestCert: true
- Reinicia Edge Microgateway. Sigue los pasos que se describen en Realiza cambios en la configuración según el archivo de configuración que editaste: el predeterminado o el archivo de configuración del entorno de ejecución.
Este es un ejemplo de la sección edgemicro
del archivo de configuración con SSL configurada:
edgemicro: port: 8000 max_connections: 1000 max_connections_hard: 5000 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - oauth ssl: key: /MyHome/SSL/em-ssl-keys/server.key cert: /MyHome/SSL/em-ssl-keys/server.crt passphrase: admin123 #option added in v2.2.2 rejectUnauthorized: true #option added in v2.2.2
Esta es una lista de todas las opciones de servidor compatibles:
Opción | Descripción |
---|---|
key |
Es la ruta de acceso a un archivo ca.key (en formato PEM). |
cert |
Es la ruta de acceso a un archivo ca.cert (en formato PEM). |
pfx |
Ruta de acceso a un archivo pfx que contiene la clave privada, el certificado y los certificados de CA del cliente en formato PFX. |
passphrase |
Una string que contiene la frase de contraseña para la clave privada o PFX. |
ca |
Es la ruta de acceso a un archivo que contiene una lista de certificados de confianza en formato PEM. |
ciphers |
Es una string que describe los cifrados que se usarán separados por un “:”. |
rejectUnauthorized |
Si es verdadero, el certificado del servidor se verifica con la lista de CA proporcionadas. Si la verificación falla, se mostrará un error. |
secureProtocol |
Es el método SSL que se usará. Por ejemplo, SSLv3_method para forzar SSL a la versión 3. |
servername |
El nombre del servidor de la extensión TLS de SNI (indicación de nombre del servidor). |
requestCert |
Verdadero para SSL de 2 vías; falso para SSL unidireccional |
Usa opciones SSL/TLS del cliente
Puedes configurar Edge Microgateway para que sea un cliente TLS o SSL cuando te conectas a los extremos de destino. En el archivo de configuración de Microgateway, usa el elemento de destino para configurar las opciones de SSL/TLS. Ten en cuenta que puedes especificar varios objetivos específicos. A continuación, se incluye un ejemplo de varios destinos.
En este ejemplo, se proporciona la configuración que se aplicará a todos los hosts:
edgemicro: ... targets: ssl: client: key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true
En este ejemplo, la configuración solo se aplica al host especificado:
edgemicro: ... targets: - host: 'myserver.example.com' ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true
A continuación, se muestra un ejemplo de TLS:
edgemicro: ... targets: - host: 'myserver.example.com' tls: client: pfx: /Users/myname/twowayssl/ssl/client.pfx passphrase: admin123 rejectUnauthorized: true
En caso de que desees aplicar la configuración de TLS/SSL a varios destinos específicos, debes especificar el primer host de la configuración como "vacío", lo que habilita las solicitudes universales, y, luego, debes especificar hosts específicos en cualquier orden. En este ejemplo, la configuración se aplica a varios hosts específicos:
targets: - host: ## Note that this value must be "empty" ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true - host: 'myserver1.example.com' ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt rejectUnauthorized: true - host: 'myserver2.example.com' ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt rejectUnauthorized: true
A continuación, se muestra una lista de todas las opciones de cliente admitidas:
Opción | Descripción |
---|---|
pfx |
Ruta de acceso a un archivo pfx que contiene la clave privada, el certificado y los certificados de CA del cliente en formato PFX. |
key |
Es la ruta de acceso a un archivo ca.key (en formato PEM). |
passphrase |
Una string que contiene la frase de contraseña para la clave privada o PFX. |
cert |
Es la ruta de acceso a un archivo ca.cert (en formato PEM). |
ca |
Es la ruta de acceso a un archivo que contiene una lista de certificados de confianza en formato PEM. |
ciphers |
Es una string que describe los cifrados que se usarán separados por un “:”. |
rejectUnauthorized |
Si es verdadero, el certificado del servidor se verifica con la lista de CA proporcionadas. Si la verificación falla, se mostrará un error. |
secureProtocol |
Es el método SSL que se usará. Por ejemplo, SSLv3_method para forzar SSL a la versión 3. |
servername |
El nombre del servidor de la extensión TLS de SNI (indicación de nombre del servidor). |
Personaliza el proxy de Edgemicro-auth
De forma predeterminada, Edge Microgateway usa un proxy implementado en Apigee Edge para la autenticación de OAuth2.
Este proxy se implementa cuando ejecutas edgemicro configure
por primera vez. Puedes cambiar la configuración predeterminada de este proxy para agregar compatibilidad con reclamaciones personalizadas a un token web JSON (JWT), configurar el vencimiento del token y generar tokens de actualización. Para obtener más información, consulta la página edgemicro-auth en GitHub.
Usa un servicio de autenticación personalizado
De forma predeterminada, Edge Microgateway usa un proxy implementado en Apigee Edge para la autenticación de OAuth2.
Este proxy se implementa cuando ejecutas edgemicro configure
por primera vez. De forma predeterminada, la URL de este proxy se especifica en el archivo de configuración de Edge Microgateway de la siguiente manera:
authUri: https://myorg-myenv.apigee.net/edgemicro-auth
Si deseas usar tu propio servicio personalizado para manejar la autenticación, cambia el valor authUri
en el archivo de configuración para que apunte a tu servicio. Por ejemplo, puedes tener un servicio que usa LDAP para verificar la identidad.
Administra archivos de registro
Edge Microgateway registra información sobre cada solicitud y respuesta. Los archivos de registro proporcionan información útil para depurar y solucionar problemas.
Dónde se almacenan los archivos de registro
De forma predeterminada, los archivos de registro se almacenan en /var/tmp
.
Cómo cambiar el directorio de archivos de registro predeterminado
El directorio en el que se almacenan los archivos de registro se especifica en el archivo de configuración de Edge Microgateway. Consulta también Cómo realizar cambios en la configuración.
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Cambia el valor dir para especificar un directorio de archivos de registro diferente.
Envía registros a la consola
Puedes configurar el registro para que la información de registro se envíe a la salida estándar en lugar de a un archivo de registro. Configura la marca to_console
como verdadera de la siguiente manera:
edgemicro: logging: to_console: true
Con este parámetro de configuración, los registros se enviarán a la salida estándar. Por el momento, no puedes enviar registros a stdout y a un archivo de registro.
Cómo configurar el nivel de registro
Debes especificar el nivel de registro que se usará en la configuración de edgemicro
. Para obtener una lista completa de los niveles de registro y sus descripciones, consulta los atributos de Edgemicro.
Por ejemplo, con la siguiente configuración, se establece el nivel de registro en debug
:
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: debug dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Cómo cambiar los intervalos de registro
Puedes configurar estos intervalos en el archivo de configuración de Edge Microgateway. Consulta también Realizar cambios en la configuración.
Los atributos configurables son los siguientes:
- stats_log_interval: (Valor predeterminado: 60) Intervalo, en segundos, cuando el registro de estadísticas se escribe en el archivo de registro de la API.
- rotate_interval: (valor predeterminado: 24) Intervalo, en horas, cuando se rotan los archivos de registro. Por ejemplo:
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Cómo disminuir la rigurosidad de los permisos estrictos de los archivos de registro
De forma predeterminada, Edge Microgateway genera el archivo de registro de la aplicación (api-log.log
) con el nivel de permiso del archivo establecido en 0600. Este nivel de permiso no permite que las aplicaciones o los usuarios externos lean el archivo de registro. Para disminuir la rigurosidad de este nivel de permiso, establece logging:disableStrictLogFile
en true
. Cuando este atributo es true
, el archivo de registro se crea con el permiso de archivo establecido en 0755. Si es false
o si no se proporciona el atributo, el permiso predeterminado es 0600.
Se agregó en la versión 3.2.3.
Por ejemplo:
edgemicro: logging: disableStrictLogFile: true
Prácticas recomendadas para el mantenimiento de los archivos de registro
Debido a que los datos de los archivos de registro se acumulan con el tiempo, Apigee recomienda que adoptes las siguientes prácticas:
- Debido a que los archivos de registro pueden ser bastante grandes, asegúrate de que el directorio de archivos de registro tenga suficiente espacio. Consulta las siguientes secciones: Dónde se almacenan los archivos de registro y Cómo cambiar el directorio predeterminado de archivos de registro.
- Borra o mueve los archivos de registro a otro directorio de archivos al menos una vez a la semana.
- Si tu política es borrar registros, puedes usar el comando
edgemicro log -c
de la CLI para quitar (limpiar) los registros más antiguos.
Convención de nomenclatura de archivos de registro
Cada instancia de Edge Microgateway produce un archivo de registro con una extensión .log
. La convención de nombres para los archivos de registro es la siguiente:
edgemicro-HOST_NAME-INSTANCE_ID-api.log
Por ejemplo:
edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
Información acerca del contenido de los archivos de registro
Se agregó en la versión 2.3.3.
De forma predeterminada, el servicio de registro omite el JSON de los proxies y productos descargados, y el token web JSON (JWT). Si deseas generar estos objetos en la consola, configura la marca de línea de comandos DEBUG=*
cuando inicies Edge Microgateway. Por ejemplo:
DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456
Contenido del archivo de registro "api"
El archivo de registro “api” contiene información detallada sobre el flujo de solicitudes y respuestas a través de Edge Microgateway. Los archivos de registro "api" se nombran de la siguiente manera:
edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log
Para cada solicitud realizada a Edge Microgateway, se capturan cuatro eventos en el archivo de registro “API”:
- Solicitud entrante del cliente
- Solicitud saliente enviada al destino
- Respuesta entrante del destino
- Respuesta saliente al cliente
Cada una de estas entradas separadas se representa con una notación abreviada para ayudar a que los archivos de registro sean más compactos. Aquí hay cuatro entradas de ejemplo que representan cada uno de los cuatro eventos. En el archivo de registro, se ven de la siguiente manera (los números de línea son solo de referencia en el documento, no aparecen en el archivo de registro).
(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0 (2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0 (3) 1436403888672 info tres s=200, d=7, i=0 (4) 1436403888676 info res s=200, d=11, i=0
Veámoslos uno por uno:
1. Ejemplo de solicitud entrante del cliente:
1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
- 1436403888651: Marca de fecha de Unix
- info: El nivel de registro. Este valor depende del contexto de la transacción y del nivel de registro establecido en la configuración
edgemicro
. Consulta Cómo configurar el nivel de registro. Para los registros estadísticos, el nivel se establece enstats
. Los registros estadísticos se informan a un intervalo regular establecido con la configuraciónstats_log_interval
. Consulta también Cómo cambiar los intervalos de registro. - req: Identifica el evento. En este caso, se debe solicitar al cliente.
- m: El verbo HTTP que se usa en la solicitud.
- u: La parte de la URL que sigue a la ruta base.
- h: El host y el número de puerto en los que Edge Microgateway escucha.
- r: El host y el puerto remotos en los que se originó la solicitud del cliente.
- i: El ID de la solicitud. Las cuatro entradas de eventos compartirán este ID. A cada solicitud se le asigna un ID único. La correlación de registros por ID de solicitud puede proporcionar estadísticas valiosas sobre la latencia del destino.
- d: Es la duración en milisegundos desde que Edge Microgateway recibió la solicitud. En el ejemplo anterior, la respuesta del objetivo para la solicitud 0 se recibió después de 7 milisegundos (línea 3) y la respuesta se envió al cliente después de otros 4 milisegundos (línea 4). En otras palabras, la latencia total de la solicitud fue de 11 milisegundos, de los cuales 7 milisegundos la tomó el destino y 4 milisegundos por Edge Microgateway.
2. Ejemplo de solicitud saliente realizada al destino:
1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0
- 1436403888651: Marca de fecha de Unix
- info: El nivel de registro. Este valor depende del contexto de la transacción y del nivel de registro establecido en la configuración
edgemicro
. Consulta Cómo configurar el nivel de registro. Para los registros estadísticos, el nivel se establece enstats
. Los registros estadísticos se informan a un intervalo regular establecido con la configuraciónstats_log_interval
. Consulta también Cómo cambiar los intervalos de registro. - treq: Identifica el evento. En este caso, es la solicitud de destino.
- m: El verbo HTTP que se usa en la solicitud de destino.
- u: La parte de la URL que sigue a la ruta base.
- h: El host y el número de puerto del destino del backend.
- i: El ID de la entrada de registro. Las cuatro entradas de eventos compartirán este ID.
3. Muestra de la respuesta entrante del destino
1436403888672 info tres s=200, d=7, i=0
1436403888651: Marca de fecha de Unix
- info: El nivel de registro. Este valor depende del contexto de la transacción y del nivel de registro establecido en la configuración
edgemicro
. Consulta Cómo configurar el nivel de registro. Para los registros estadísticos, el nivel se establece enstats
. Los registros estadísticos se informan a un intervalo regular establecido con la configuraciónstats_log_interval
. Consulta también Cómo cambiar los intervalos de registro. - tres: Identifica el evento. En este caso, es la respuesta objetivo.
- s: Es el estado de la respuesta HTTP.
- d: Es la duración en milisegundos. Tiempo que tarda el objetivo en realizar la llamada a la API.
- i: El ID de la entrada de registro. Las cuatro entradas de eventos compartirán este ID.
4. Muestra de respuesta saliente al cliente
1436403888676 info res s=200, d=11, i=0
1436403888651: Marca de fecha de Unix
- info: El nivel de registro. Este valor depende del contexto de la transacción y del nivel de registro establecido en la configuración
edgemicro
. Consulta Cómo configurar el nivel de registro. Para los registros estadísticos, el nivel se establece enstats
. Los registros estadísticos se informan a un intervalo regular establecido con la configuraciónstats_log_interval
. Consulta también Cómo cambiar los intervalos de registro. - res: Identifica el evento. En este caso, es la respuesta al cliente.
- s: Es el estado de la respuesta HTTP.
- d: Es la duración en milisegundos. Este es el tiempo total que tarda la llamada a la API, incluido el tiempo que tarda la API de destino y el tiempo que tarda Edge Microgateway.
- i: El ID de la entrada de registro. Las cuatro entradas de eventos compartirán este ID.
Programación del archivo de registro
Los archivos de registro se rotan en el intervalo especificado por el atributo de configuración rotate_interval. Las entradas se seguirán agregando al mismo archivo de registro hasta que venza el intervalo de rotación. Sin embargo, cada vez que se reinicia Edge Microgateway, recibe un UID nuevo y crea un conjunto nuevo de archivos de registro con este UID. Consulta también Prácticas recomendadas para el mantenimiento de los archivos de registro.
Mensajes de error
Algunas entradas de registro contendrán mensajes de error. Para ayudarte a identificar dónde y por qué se producen los errores, consulta la referencia sobre errores de Edge Microgateway.
Referencia de configuración de Edge Microgateway
Ubicación del archivo de configuración
Los atributos de configuración que se describen en esta sección se encuentran en el archivo de configuración de Edge Microgateway. Consulta también Cómo realizar cambios en la configuración.
Atributos de Edge_config
Esta configuración se usa para configurar la interacción entre la instancia de Edge Microgateway y Apigee Edge.
- Boot: (predeterminado: none) Es una URL que apunta a un servicio específico de Edge Microgateway que se ejecuta en Apigee Edge. Edge Microgateway usa este servicio para
comunicarse con Apigee Edge. Esta URL se muestra cuando ejecutas el comando para generar el par de claves pública/privada:
edgemicro genkeys
. Consulta Configura y configura Edge Microgateway para obtener más detalles. - jwt_public_key: (configuración predeterminada: none) Es una URL que apunta al proxy de Edge Microgateway que se implementa en Apigee Edge. Este proxy sirve como un extremo de autenticación para emitir tokens de acceso firmados a los clientes. Se muestra esta URL cuando ejecutas el comando para implementar el proxy: edgemicro configure. Consulta Configura y configura Edge Microgateway para obtener más detalles.
- quotaUri: Configura esta propiedad de configuración si deseas administrar las cuotas a través del proxy
edgemicro-auth
que se implementa en tu organización. Si no se configura esta propiedad, el extremo de cuota se establece de forma predeterminada en el extremo interno de Edge Microgateway.edge_config: quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
atributos de Edgemicro
Con esta configuración, se configura el proceso de Edge Microgateway.
- port: (valor predeterminado: 8000) Es el número de puerto en el que escucha el proceso de Edge Microgateway.
- max_connections: Especifica la cantidad máxima de conexiones entrantes simultáneas que puede recibir Edge Microgateway (valor predeterminado: -1). Si se supera este número, se muestra el siguiente estado:
res.statusCode = 429; // Too many requests
- max_connections_hard: (valor predeterminado: -1) Es la cantidad máxima de solicitudes simultáneas que puede recibir Edge Microgateway antes de cerrar la conexión. Esta configuración está diseñada para frustrar ataques de denegación del servicio. Por lo general, establece un número mayor que max_connections.
-
logging:
-
level: (valor predeterminado: error)
- info: Registra todas las solicitudes y respuestas que fluyen a través de una instancia de Edge Microgateway (recomendado).
- warn: Registra solo los mensajes de advertencia.
- error: Registra solo los mensajes de error.
- depuración: Registra los mensajes de depuración junto con la información, las advertencias y los mensajes de error.
- trace: Registra la información de seguimiento de errores junto con la información, las advertencias y los mensajes de error.
- none: no se crea un archivo de registro.
- dir: (predeterminado: /var/tmp) Es el directorio en el que se almacenan los archivos de registro.
- stats_log_interval: (Valor predeterminado: 60) Intervalo, en segundos, cuando el registro de estadísticas se escribe en el archivo de registro de la API.
- rotate_interval: (valor predeterminado: 24) Intervalo, en horas, cuando se rotan los archivos de registro.
-
level: (valor predeterminado: error)
- plugins: Los complementos agregan funcionalidad a Edge Microgateway. Para obtener detalles sobre el desarrollo de complementos, consulta Cómo desarrollar complementos personalizados.
- dir: Una ruta de acceso relativa desde el directorio ./gateway al directorio ./plugins o una ruta absoluta.
- secuencia: Una lista de módulos de complementos para agregar a la instancia de Edge Microgateway. Los módulos se ejecutarán en el orden en el que se especifiquen aquí.
-
debug: Agrega la depuración remota al proceso de Edge Microgateway.
- port: Es el número de puerto en el que se escuchará. Por ejemplo, configura tu depurador del IDE para que escuche en este puerto.
- args: Argumentos para el proceso de depuración Por ejemplo:
args --nolazy
- config_change_poll_interval: (configuración predeterminada: 600 segundos) Edge Microgateway
carga una configuración nueva de forma periódica y ejecuta una recarga si algo cambió. El sondeo
recoge los cambios realizados en Edge (cambios en los productos, proxies compatibles con micropuertas de enlace, etc.) y en el archivo de configuración local.
- disable_config_poll_interval: (valor predeterminado: false) Configúralo en true para desactivar el sondeo de cambios automáticos.
- request_timeout: Establece un tiempo de espera para las solicitudes de destino. El tiempo de espera se establece en segundos. Si se agota el tiempo de espera, Edge Microgateway responde con un código de estado 504. (Se agregó la versión 2.4.x).
- keep_alive_timeout: Esta propiedad te permite establecer el tiempo de espera de Edge Microgateway (en milisegundos). (Opción predeterminada: 5 segundos) (agregada v3.0.6)
- headers_timeout: Este atributo limita la cantidad de tiempo (en milisegundos) que el analizador de HTTP esperará para recibir los encabezados HTTP completos.
Por ejemplo:
edgemicro: keep_alive_timeout: 6000 headers_timeout: 12000
De forma interna, el parámetro establece el atributo
Server.headersTimeout
de Node.js en las solicitudes. (Valor predeterminado: 5 segundos más que el tiempo establecido conedgemicro.keep_alive_timeout
. Esta configuración predeterminada evita que los balanceadores de cargas o los proxies pierdan la conexión por error). (Se agregó la versión 3.1.1). - noRuleMatchAction: (String): Es la acción que se realiza (permitir o rechazar el acceso) si la regla de coincidencia especificada en el complemento
accesscontrol
no se resuelve (no tiene coincidencias). Valores válidos:ALLOW
oDENY
Valor predeterminado:ALLOW
(agregado: v3.1.7) - enableAnalytics: (valor predeterminado: true) Configura el atributo en false para evitar que se cargue el complemento de estadísticas. En este caso, no se realizarán llamadas a las estadísticas de Apigee Edge. Si se configura como true o cuando no se proporciona este atributo, el complemento de Analytics funcionará como de costumbre. Consulta los atributos de Edgemicro para obtener más detalles. (Se agregó la versión 3.1.8).
Ejemplo:
edgemicro enableAnalytics=false|true
- on_target_response_abort: Este atributo te permite controlar el comportamiento de Edge Microgateway si se cierra de forma prematura la conexión entre el cliente (Edge Microgateway) y el servidor de destino.
Valor Descripción Predeterminada Si no se especifica on_target_response_abort
, el comportamiento predeterminado es truncar la respuesta sin mostrar un error. En los archivos de registro, se muestra un mensaje de advertencia contargetResponse aborted
y un código de respuesta 502.appendErrorToClientResponseBody
Se muestra el error personalizado TargetResponseAborted
al cliente. En los archivos de registro, se muestra un mensaje de advertencia contargetResponse aborted
y un código de respuesta 502. Además, el errorTargetResponseAborted
se registra con el mensajeTarget response ended prematurely.
.abortClientRequest
Edge Microgateway anula la solicitud, y se escribe una advertencia en los archivos de registro: TargetResponseAborted
con el código de estado de la solicitud 502.
Ejemplo:
edgemicro: on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest
atributos de encabezados
Esta configuración establece la manera en que se tratan ciertos encabezados HTTP.
- x-forwarded-for: (predeterminado: true) Se establece en falso para evitar que los encabezados x-forwarded-for se pasen al destino. Ten en cuenta que, si la solicitud contiene un encabezado x-forward-for, su valor se establecerá en el valor de client-ip en Edge Analytics.
- x-forwarded-host: (predeterminado: true) Se establece como falso para evitar que se pasen los encabezados x-forwarded-host al destino.
- x-request-id: (valor predeterminado: verdadero). Configúralo como falso para evitar que los encabezados x-request-id se pasen al destino.
- x-response-time: (predeterminado: true) Se establece en falso para evitar que los encabezados de x-response-time se pasen al objetivo.
- via: (valor predeterminado: true) Configúralo como falso para evitar que se pasen los encabezados al destino.
atributos de OAuth
Esta configuración configura cómo Edge Microgateway aplica la autenticación del cliente.
- allowNoAuthorization: (valor predeterminado: false). Si se configura como verdadero, las llamadas a la API pueden pasar por Edge Microgateway sin encabezado de autorización. Configúralo como falso para requerir un encabezado de autorización (predeterminado).
- allowInvalidAuthorization: (valor predeterminado: false) Si se configura como verdadero, se permite que se pasen las llamadas a la API si el token que se pasó en el encabezado de autorización no es válido o venció. Establece esto como false para requerir tokens válidos (predeterminado).
- Authorization-header: (valor predeterminado: Autorización: Bearer). Es el encabezado que se usa para enviar el token de acceso a Edge Microgateway. Es posible que desees cambiar el valor predeterminado en los casos en que el destino necesite usar el encabezado de autorización para algún otro propósito.
- api-key-header: (valor predeterminado: x-api-key) Es el nombre del encabezado o del parámetro de consulta que se usa para pasar una clave de API a Edge Microgateway. Consulta también Cómo usar una clave de API.
- keep-Authorization-header: (valor predeterminado: false). Si se configura como verdadero, el encabezado de la Autorización que se envió en la solicitud se pasa al destino (se conserva).
- allowOAuthOnly: Si se configura como verdadera, cada API debe llevar un encabezado de autorización con un token de acceso del portador. Te permite permitir solo el modelo de seguridad OAuth (y, al mismo tiempo, mantener la retrocompatibilidad). (Se agregó la versión 2.4.x)
- allowAPIKeyOnly: Si se configura como verdadera, cada API debe llevar un encabezado x-api-key (o una ubicación personalizada) con una clave de API.Te permite permitir solo el modelo de seguridad de la clave de API (y, al mismo tiempo, mantener la retrocompatibilidad). (Se agregó la versión 2.4.x)
- gracePeriod: Este parámetro ayuda a evitar errores causados por leves discrepancias entre el reloj de tu sistema y los horarios Not before (nbf) o Issued at (iat) especificados en el token de autorización JWT. Establece este parámetro en la cantidad de segundos para permitir estas discrepancias. (Agregada 2.5.7)
Atributos específicos del complemento
Consulta la sección Uso de complementos para obtener detalles sobre los atributos configurables de cada complemento.
Filtra proxies
Puedes filtrar qué proxies compatibles con micropuertas de enlace procesará una instancia de Edge Microgateway.
Cuando se inicia Edge Microgateway, se descargan todos los proxies compatibles con micropuertas de enlace de la
organización a la que está asociado. Usa la siguiente configuración para limitar los proxies que procesará la micropuerta de enlace. Por ejemplo, esta configuración limita los proxies que procesará la micropuerta de enlace a tres: edgemicro_proxy-1
, edgemicro_proxy-2
y edgemicro_proxy-3
:
edgemicro: proxies: - edgemicro_proxy-1 - edgemicro_proxy-2 - edgemicro_proxy-3
Filtrar productos por nombre
Usa la siguiente configuración para limitar la cantidad de productos de API que Edge Microgateway descarga y procesa. Para filtrar los productos descargados, agrega el parámetro de consulta productnamefilter
a la API de /products
que aparece en el archivo *.config.yaml
de Edge Microgateway. Por ejemplo:
edge_config: bootstrap: >- https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' vaultName: microgateway authUri: 'https://%s-%s.apigee.net/edgemicro-auth' baseUri: >- https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s bootstrapMessage: Please copy the following property to the edge micro agent config keySecretMessage: The following credentials are required to start edge micro products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'
Ten en cuenta que el valor del parámetro de consulta debe especificarse en formato de expresión regular y debe estar codificado para URL. Por ejemplo, la regex ^[Ee]dgemicro.*$
detecta nombres como "edgemicro-test-1" , "edgemicro_demo" y "Edgemicro_New_Demo". El valor codificado de URL, adecuado para usar en el parámetro de búsqueda, es %5E%5BEe%5Ddgemicro.%2A%24
.
En el siguiente resultado de depuración, se muestra que solo se descargaron los productos filtrados:
... 2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK ... .... .... { "apiProduct":[ { "apiResources":[ ], "approvalType":"auto", "attributes":[ { "name":"access", "value":"public" } ], "createdAt":1590549037549, "createdBy":"k***@g********m", "displayName":"test upper case in name", "environments":[ "prod", "test" ], "lastModifiedAt":1590549037549, "lastModifiedBy":"k***@g********m", "name":"Edgemicro_New_Demo", "proxies":[ "catchall" ], "quota":"null", "quotaInterval":"null", "quotaTimeUnit":"null", "scopes":[ ] }, { "apiResources":[ ], "approvalType":"auto", "attributes":[ { "name":"access", "value":"public" } ], "createdAt":1590548328998, "createdBy":"k***@g********m", "displayName":"edgemicro test 1", "environments":[ "prod", "test" ], "lastModifiedAt":1590548328998, "lastModifiedBy":"k***@g********m", "name":"edgemicro-test-1", "proxies":[ "Lets-Encrypt-Validation-DoNotDelete" ], "quota":"null", "quotaInterval":"null", "quotaTimeUnit":"null", "scopes":[ ] }, { "apiResources":[ "/", "/**" ], "approvalType":"auto", "attributes":[ { "name":"access", "value":"public" } ], "createdAt":1558182193472, "createdBy":"m*********@g********m", "displayName":"Edge microgateway demo product", "environments":[ "prod", "test" ], "lastModifiedAt":1569077897465, "lastModifiedBy":"m*********@g********m", "name":"edgemicro_demo", "proxies":[ "edgemicro-auth", "edgemicro_hello" ], "quota":"600", "quotaInterval":"1", "quotaTimeUnit":"minute", "scopes":[ ] } ] }
Cómo filtrar productos por atributos personalizados
Sigue estos pasos para filtrar productos según los atributos personalizados:
- En la IU de Edge, selecciona el proxy edgemicro_auth en la organización o el entorno en el que configuraste Edge Microgateway.
- En Develop, abre la política JavaHighlight en el editor.
- Agrega un atributo personalizado con la clave
products.filter.attributes
con una lista de nombres de atributos separados por comas. Solo los productos que contengan cualquiera de los nombres de atributos personalizados se mostrarán a Edge Microgateway. - De manera opcional, puedes inhabilitar la verificación
para ver si el producto está habilitado para el entorno actual configurando
el atributo personalizado
products.filter.env.enable
enfalse
. (El valor predeterminado es verdadero). - (Solo en la nube privada) Si estás en Edge para la nube privada, configura la propiedad
org.noncps
comotrue
a fin de extraer productos para entornos que no son de CPS.
Por ejemplo:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout"> <DisplayName>JavaCallout</DisplayName> <FaultRules/> <Properties> <Property name="products.filter.attributes">attrib.one, attrib.two</Property> <Property name="products.filter.env.enable">false</Property> <Property name="org.noncps">true</Property> </Properties> <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName> <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL> </JavaCallout>
Configura la frecuencia de envío de estadísticas
Usa estos parámetros de configuración para controlar la frecuencia con la que Edge Microgateway envía datos de estadísticas a Apigee:
- bufferSize (opcional): El número máximo de registros de estadísticas que puede contener el búfer antes de comenzar a descartar los registros más antiguos. Valor predeterminado: 10,000
- batchSize (opcional): El tamaño máximo de un lote de registros de estadísticas enviados a Apigee. Valor predeterminado: 500
- flushInterval (opcional): Es la cantidad de milisegundos entre cada limpieza de un lote de registros de estadísticas enviados a Apigee. Valor predeterminado: 5,000
Por ejemplo:
analytics: bufferSize: 15000 batchSize: 1000 flushInterval: 6000
Enmascara datos de estadísticas
La siguiente configuración evita que se muestre la información de la ruta de la solicitud en Edge Analytics. Agrega el siguiente código a la configuración de la micropuerta de enlace para enmascarar el URI de la solicitud o la ruta de la solicitud. Ten en cuenta que el URI consta de las partes del nombre de host y la ruta de acceso de la solicitud.
analytics: mask_request_uri: 'string_to_mask' mask_request_path: 'string_to_mask'
Segrega las llamadas a la API en Edge Analytics
Puedes configurar el complemento de estadísticas para segregar una ruta de acceso a la API específica, de modo que aparezca como un proxy independiente en los paneles de Edge Analytics. Por ejemplo, puedes segregar una API de verificación de estado en el panel para evitar confundirla con llamadas reales de proxy a la API. En el panel de Analytics, los proxies segregados siguen este patrón de nombres:
edgemicro_proxyname-health
En la siguiente imagen, se muestran dos proxies separados en el panel de Analytics: edgemicro_hello-health
y edgemicro_mock-health
:
Utiliza estos parámetros para segregar las rutas relativas y absolutas en el panel de Analytics como proxies independientes:
- relativePath (opcional): Especifica una ruta relativa para segregar en el panel de Analytics. Por ejemplo, si especificas
/healthcheck
, todas las llamadas a la API que contengan la ruta/healthcheck
aparecerán en el panel comoedgemicro_proxyname-health
. Ten en cuenta que esta marca ignora la ruta base del proxy. Para segregar en función de una ruta de acceso completa, incluida la ruta base, usa la marcaproxyPath
. - proxyPath (opcional): Especifica una ruta de acceso de proxy de API completa, incluida la ruta base del proxy, para segregar en el panel de estadísticas. Por ejemplo, si especificas
/mocktarget/healthcheck
, en el que/mocktarget
es la ruta base del proxy, todas las llamadas a la API con la ruta/mocktarget/healthcheck
aparecerán en el panel comoedgemicro_proxyname-health
.
Por ejemplo, en la siguiente configuración, el complemento de estadísticas segregará cualquier ruta de acceso a la API que contenga /healthcheck
. Esto significa que /foo/healthcheck
y /foo/bar/healthcheck
se segregarán como un proxy independiente llamado edgemicro_proxyname-health
en el panel de estadísticas.
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 relativePath: /healthcheck
En la siguiente configuración, cualquier API con la ruta del proxy /mocktarget/healthcheck
se
segregará como un proxy independiente llamado edgemicro_proxyname-health
en
el panel de Analytics.
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 proxyPath: /mocktarget/healthcheck
Configura Edge Microgateway detrás de un firewall de la empresa
Usa un proxy HTTP para comunicarte con Apigee Edge
Se agregó en la versión 3.1.2.
Si deseas usar un proxy HTTP para la comunicación entre Edge Microgateway y Apigee Edge, haz lo siguiente:
- Configura las variables de entorno
HTTP_PROXY
,HTTPS_PROXY
yNO_PROXY
. Estas variables controlan los hosts de cada proxy HTTP que desees usar para la comunicación con Apigee Edge o qué hosts no deben administrar la comunicación con Apigee Edge. Por ejemplo:export HTTP_PROXY='http://localhost:3786' export HTTPS_PROXY='https://localhost:3786' export NO_PROXY='localhost,localhost:8080'
Ten en cuenta que
NO_PROXY
puede ser una lista delimitada por comas de dominios a los que Edge Microgateway no debe usar como proxy.Para obtener más información sobre estas variables, consulta https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables
- Reinicia Edge Microgateway.
Usa un proxy HTTP para la comunicación con el destino
Se agregó en la versión 3.1.2.
Si deseas usar un proxy HTTP para la comunicación entre Edge Microgateway y los destinos de backend, haz lo siguiente:
- Agrega la siguiente configuración al archivo de configuración de microgateway:
edgemicro: proxy: tunnel: true | false url: proxy_url bypass: target_host # target hosts to bypass the proxy. enabled: true | false
Aquí:
- tunnel: (Opcional) Cuando es verdadero, Edge Microgateway usa el método HTTP CONNECT para hacer túneles las solicitudes HTTP en una sola conexión TCP. (Lo mismo ocurre si las variables de entorno, como se
menciona a continuación,
para configurar el proxy, están habilitadas para TLS). Predeterminada:
false
- url: La URL del proxy HTTP.
- bypass: Especifica una o más URL de host de destino separadas por comas que deben omitir el proxy HTTP (opcional). Si no se configura esta propiedad, usa la variable de entorno NO_PROXY para especificar las URLs de destino que se deben omitir.
- enabled: Si se configura como verdadero y se configura
proxy.url
, usa el valorproxy.url
para el proxy HTTP. Si es verdadero y no se configuraproxy.url
, usa los proxies especificados en las variables de entorno de proxy HTTPHTTP_PROXY
yHTTPS_PROXY
, como se describe en Usa un proxy HTTP para comunicarse con Apigee Edge.
Por ejemplo:
edgemicro: proxy: tunnel: true url: 'http://localhost:3786' bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy. enabled: true
- tunnel: (Opcional) Cuando es verdadero, Edge Microgateway usa el método HTTP CONNECT para hacer túneles las solicitudes HTTP en una sola conexión TCP. (Lo mismo ocurre si las variables de entorno, como se
menciona a continuación,
para configurar el proxy, están habilitadas para TLS). Predeterminada:
- Reinicia Edge Microgateway.
Usa comodines en proxies compatibles con Microgateway
Puedes usar uno o más comodines "*" en la ruta base de un proxy edgemicro_* (Microgateway-aware). Por ejemplo, una ruta base de /team/*/members permite a los clientes llamar a https://[host]/team/blue/members y https://[host]/team/green/members sin necesidad de crear proxies de API nuevos para brindar asistencia a equipos nuevos. Ten en cuenta que no se admite /**/
.
Importante: Apigee NO admite el uso de un comodín “*” como el primer elemento de una ruta base. Por ejemplo, NO se admite la búsqueda de /*/
.
Rota claves JWT
Poco después de generar un JWT inicialmente, es posible que debas cambiar el par de claves pública/privada almacenado en el KVM encriptado de Edge. Este proceso de generación de un nuevo par de claves se denomina rotación de claves.
Cómo Edge Microgateway usa los JWT
El token web JSON (JWT) es un estándar de token descrito en RFC7519. JWT proporciona una forma de firmar un conjunto de reclamaciones, que el destinatario del JWT puede verificar de manera confiable.
Puedes generar un JWT con la CLI y usarlo en el encabezado de autorización de las llamadas a la API en lugar de una clave de API. Por ejemplo:
curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"
Para obtener información sobre cómo generar JWT con la CLI, consulta Genera un token.
¿Qué es la rotación de claves?
Poco después de generar un JWT inicialmente, es posible que debas cambiar el par de claves pública/privada almacenado en el KVM encriptado de Edge. Este proceso de generación de un nuevo par de claves se denomina rotación de claves. Cuando rotas las claves, se genera un nuevo par de claves públicas y privadas, que se almacenan en el KVM “micropuerta de enlace” en tu organización o entorno de Apigee Edge. Además, se conserva la clave pública anterior junto con su valor de ID de clave original.
Para generar un JWT, Edge usa la información almacenada en el KVM encriptado. Cuando configuraste (configuraste) Edge Microgateway, se creó y propagó con claves un KVM llamado microgateway
. Las claves del KVM se usan para firmar y encriptar un JWT.
Las claves de KVM incluyen lo siguiente:
-
private_key: La clave privada RSA más reciente (creada más recientemente) que se usa para firmar los JWT.
-
public_key: El certificado más reciente (creado más recientemente) que se usa para verificar los JWT firmados con la clave_privada.
-
private_key_kid: El ID de clave privada más reciente (creado más recientemente). Este ID de clave está asociado con el valor de private_key y se usa para admitir la rotación de claves.
-
public_key1_kid: El ID de clave pública más reciente (creado más recientemente). Esta clave está asociada con el valor public_key1 y se usa para admitir la rotación de claves. Este valor es el mismo que el de la clave privada secundaria.
-
public_key1: La clave pública más reciente (creada más recientemente).
Cuando rotas las claves, los valores de las claves existentes se reemplazan en el mapa y se agregan claves nuevas para conservar las claves públicas antiguas. Por ejemplo:
-
public_key2_kid: Es el ID de la clave pública anterior. Esta clave está asociada con el valor public_key2 y se usa para admitir la rotación de claves.
-
public_key2: Es la clave pública anterior.
Los JWT presentados para la verificación se verificarán con la nueva clave pública. Si falla la verificación, se usará la clave pública anterior hasta que venza el JWT (después del intervalo token_expiry*, según la configuración predeterminada de 30 minutos). De esta manera, puedes “rotar” las claves sin interrumpir inmediatamente el tráfico de la API.
Cómo realizar la rotación de claves
En esta sección, se explica cómo realizar una rotación de claves.
- Para actualizar el KVM, usa el comando
edgemicro upgradekvm
. Para obtener detalles sobre cómo ejecutar este comando, consulta Actualiza el KVM. Solo debes realizar este paso una vez. - Para actualizar el proxy edgemicro-oauth, usa el comando
edgemicro upgradeauth
. Para obtener detalles sobre cómo ejecutar este comando, consulta Cómo actualizar el proxy de Edgemicro-auth. Solo debes realizar este paso una vez. - Agrega la siguiente línea al archivo
~/.edgemicro/org-env-config.yaml
, en el que debes especificar la misma organización y el mismo entorno que configuraste para que use la micropuerta de enlace:jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'
Ejecuta el comando de rotación de claves para rotar las claves. Para obtener detalles sobre este comando, consulta Rotar claves.
edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET
Por ejemplo:
edgemicro rotatekey -o docs -e test \ -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \ -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47
Después de la rotación de claves, Edge muestra varias claves a Edge Microgateway. Ten en cuenta que, en el siguiente ejemplo, cada clave tiene un valor “kid” (ID de clave) único. Luego, la micropuerta de enlace usa estas claves para validar los tokens de autorización. Si la validación del token falla, la micropuerta de enlace busca si hay una clave más antigua en el conjunto de claves y la prueba. El formato de las claves que se muestran es JSON Web Key (JWK). Puedes leer sobre este formato en RFC 7517.
{ "keys": [ { "kty": "RSA", "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ", "e": "AQAB", "kid": "2" }, { "kty": "RSA", "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw", "e": "AQAB", "kid": "1" } ] }
Configuración de un retraso de "no antes"
En el caso de las versiones 3.1.5 y anteriores, la nueva clave privada generada por el comando rotatekey
entró en vigencia de inmediato, y los tokens nuevos generados se firmaron con la nueva clave privada. Sin embargo, la nueva clave pública solo estaba disponible para las instancias de Edge Microgateway cada 10 minutos (de forma predeterminada) cuando se actualizó la configuración de la micropuerta de enlace. Debido a este retraso entre la firma del token y la actualización de la instancia de micropuerta de enlace, los tokens firmados con la clave más reciente se rechazarán hasta que todas las instancias reciban la clave pública más reciente.
En los casos en los que existen varias instancias de micropuerta de enlace, el retraso de la clave pública a veces generaba errores intermitentes en el entorno de ejecución con el estado 403, ya que la validación del token pasaba en una instancia, pero fallaba en otra hasta que se actualizaran todas las instancias.
A partir de la versión 3.1.6, una marca nueva en el comando rotatekey
te permite especificar un retraso para que la clave privada nueva entre en vigencia, lo que permite que todas las instancias de micropuerta de enlace se actualicen y reciban la clave pública nueva. La marca nueva es --nbf
, que significa "no antes".
Esta marca toma un valor de número entero, la cantidad de minutos que se retrasará.
En el siguiente ejemplo, la demora se establece en 15 minutos:
edgemicro rotatekey -o docs -e test \ -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \ -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \ --nbf 15
Ten en cuenta que se recomienda establecer un retraso mayor que el parámetro de configuración de config_change_poll_internal
, que es de 10 minutos de forma predeterminada. Consulta también los atributos de Edgemicro.
Filtra proxies descargados
De forma predeterminada, Edge Microgateway descarga todos los proxies de la organización de Edge que comienzan con el prefijo de nombre “edgemicro_”. Puedes cambiar esta configuración predeterminada para descargar proxies cuyos nombres coincidan con un patrón.
- Abre el archivo de microconfiguración de Edge:
~/.edgemicro/org-env-config.yaml
- Agrega el elemento proxyPattern en Edge_config. Por ejemplo, el siguiente patrón descargará proxies, como Edgemicro_foo, Edgemicro_fast y Edgemicro_first.
edge_config: … proxyPattern: edgemicro_f*
Especifica productos sin proxies de API
En Apigee Edge, puedes crear un producto de API que no contenga ningún proxy de API. Esta configuración del producto permite que una clave de API asociada a ese producto funcione con cualquier proxy implementado en tu organización. A partir de la versión 2.5.4, Edge Microgateway es compatible con esta configuración del producto.
Depuración y solución de problemas
Conéctate a un depurador
Puedes ejecutar Edge Microgateway con un depurador, como node-inspector. Esto es útil para solucionar problemas y depurar complementos personalizados.
- Reinicia Edge Microgateway en modo de depuración. Para ello, agrega
DEBUG=*
al comienzo del comandostart
:DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
.Para dirigir el resultado de depuración a un archivo, puedes usar este comando:
export DEBUG=* nohup edgemicro start \ -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log
- Inicia el depurador y configúralo para que detecte el número de puerto del proceso de depuración.
- Ahora puedes recorrer el código de Edge Microgateway, establecer puntos de interrupción, observar expresiones, etcétera.
Puedes especificar marcas estándar de Node.js relacionadas con el modo de depuración. Por ejemplo, --nolazy
ayuda a depurar código asíncrono.
Verifica los archivos de registro
Si tienes problemas, asegúrate de examinar los archivos de registro en busca de detalles de ejecución e información de errores. Para obtener detalles, consulta Cómo administrar archivos de registro.
Cómo usar la seguridad de la clave de API
Las claves de API proporcionan un mecanismo simple para autenticar a los clientes que realizan solicitudes a Edge Microgateway. Para obtener una clave de API, copia el valor de la clave de consumidor (también llamado ID de cliente) de un producto de Apigee Edge que incluye el proxy de autenticación de Edge Microgateway.
Almacenamiento en caché de claves
Las claves de API se intercambian por tokens del portador, que se almacenan en caché. Puedes inhabilitar el almacenamiento en caché si configuras el encabezado Cache-Control: no-cache
en las solicitudes entrantes a Edge Microgateway.
Uso de claves de API
Puedes pasar la clave de API en una solicitud a la API como un parámetro de consulta o en un encabezado. De forma predeterminada, el encabezado y el nombre del parámetro de consulta son x-api-key
.
Ejemplo de parámetro de consulta:
curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz
Ejemplo del encabezado:
curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
Configura el nombre de la clave de API
De forma predeterminada, x-api-key
es el nombre que se usa tanto para el encabezado de la clave de API como para el parámetro de consulta.
Puedes cambiar este valor predeterminado en el archivo de configuración, como se explica en Realiza cambios en la configuración. Por ejemplo, para cambiar el nombre a apiKey, haz lo siguiente:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false api-key-header: apiKey
En este ejemplo, el parámetro de consulta y el nombre del encabezado se cambian a apiKey
. El nombre x-api-key
ya no funcionará en ningún caso. Consulta también Cómo realizar cambios en la configuración.
Por ejemplo:
curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
Para obtener más información sobre el uso de claves de API con solicitudes de proxy, consulta Secure Edge Microgateway.
Habilitar códigos de respuesta upstream
De forma predeterminada, el complemento oauth
solo muestra códigos de estado de error 4xx si la respuesta no es un estado 200. Puedes cambiar este comportamiento para que siempre muestre el código exacto 4xx o 5xx, según el error.
Para habilitar esta función, agrega la propiedad oauth.useUpstreamResponse: true
a la configuración de Edge Microgateway. Por ejemplo:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false gracePeriod: 10 useUpstreamResponse: true
Usa la seguridad del token de OAuth2
En esta sección, se explica cómo obtener tokens de acceso de OAuth2 y tokens de actualización. Los tokens de acceso se usan para realizar llamadas seguras a la API a través de la micropuerta de enlace. Los tokens de actualización se usan para obtener tokens de acceso nuevos.
Cómo obtener un token de acceso
En esta sección, se explica cómo usar el proxy edgemicro-auth
para obtener un token de acceso.
También puedes obtener un token de acceso con el comando CLI edgemicro token
.
Para obtener detalles sobre la CLI, consulta Administra tokens.
API 1: Envía credenciales como parámetros del cuerpo
Sustituye los nombres de tu organización y entorno en la URL y reemplaza los valores de ID de consumidor y Secreto de consumidor obtenidos de una aplicación de desarrollador en Apigee Edge por los parámetros del cuerpo client_id y client_secret:
curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \ -d '{"grant_type": "client_credentials", "client_id": "your_client_id", \ "client_secret": "your_client_secret"}' -H "Content-Type: application/json"
API 2: Envía credenciales en un encabezado de autenticación básica
Envía las credenciales del cliente como un encabezado de autenticación básica y la grant_type
como un parámetro de formulario. Este formulario de comando también se analiza en RFC 6749: Marco de trabajo de autorización de OAuth 2.0.
http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \ -d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"
Resultado de muestra
La API muestra una respuesta JSON. Ten en cuenta que no hay diferencia entre las propiedadestoken
y access_token
. Puedes usar cualquiera de las dos. Ten en cuenta que expires_in
es un valor entero que se especifica en segundos.
{ "token": "eyJraWQiOiIxIiwidHlwIjoi", "access_token": "eyJraWQiOiIxIiwid", "token_type": "bearer", "expires_in": 1799 }
Cómo obtener un token de actualización
Para obtener un token de actualización, realiza una llamada a la API al extremo /token
del proxy edgemicro-auth
. DEBES hacer esta llamada a la API con el tipo de otorgamiento password
. En los siguientes pasos, se explica el proceso.
- Obtén un token de acceso y actualización con la API de
/token
. Ten en cuenta que el tipo de otorgamiento espassword
:curl -X POST \ https://your_organization-your_environment.apigee.net/edgemicro-auth/token \ -H 'Content-Type: application/json' \ -d '{ "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq", "client_secret":"bUdDcFgv3nXffnU", "grant_type":"password", "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq", "password":"bUdD2FvnMsXffnU" }'
La API muestra un token de acceso y un token de actualización. La respuesta es similar a la siguiente: Ten en cuenta que
expires_in
valora números enteros y se especifican en segundos.{ "token": "your-access-token", "access_token": "your-access-token", "token_type": "bearer", "expires_in": 108, "refresh_token": "your-refresh-token", "refresh_token_expires_in": 431, "refresh_token_issued_at": "1562087304302", "refresh_token_status": "approved" }
- Ahora puedes usar el token de actualización para obtener un nuevo token de acceso llamando al extremo
/refresh
de la misma API. Por ejemplo:curl -X POST \ https://willwitman-test.apigee.net/edgemicro-auth/refresh \ -H 'Content-Type: application/json' \ -d '{ "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq", "client_secret":"bUdDc2Fv3nMXffnU", "grant_type":"refresh_token", "refresh_token":"your-refresh-token" }'
La API muestra un nuevo token de acceso. La respuesta es similar a la siguiente:
{ "token": "your-new-access-token" }
Supervisión permanente
Forever es una herramienta de Node.js que reinicia automáticamente una app de Node.js en caso de que el proceso se interrumpa o tenga un error. Edge Microgateway tiene un archivo forever.json que puedes configurar para controlar cuántas veces y con qué intervalos se debe reiniciar Edge Microgateway. Este archivo configura un servicio de Forever llamado forever-monitor, que administra Forever de manera programática.
Puedes encontrar el archivo forever.json en el directorio de instalación raíz de Edge Microgateway. Consulta Dónde está instalado Edge Microgateway. Para obtener detalles sobre las opciones de configuración, consulta la documentación de Forever Monitor.
El comando edgemicro forever
incluye marcas que te permiten especificar la ubicación del archivo forever.json
(la marca -f
), además de iniciar/detener el proceso de supervisión Forever (la marca -a
). Por ejemplo:
edgemicro forever -f ~/mydir/forever.json -a start
Si deseas obtener más información, consulta Supervisión permanente en la referencia de la CLI.
Especifica un extremo del archivo de configuración
Si ejecutas varias instancias de Edge Microgateway, puedes administrar sus configuraciones desde una sola ubicación. Para ello, especifica un extremo HTTP en el que Edge Micro pueda descargar su archivo de configuración. Puedes especificar este extremo cuando inicies Edge Micro con la marca -u.
Por ejemplo:
edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key
en el que el extremo mgconfig muestra el contenido de tu archivo de configuración. Este es el archivo que, de forma predeterminada, se encuentra en ~/.edgemicro
y tiene la convención de nombres: org-env-config.yaml
.
Inhabilita el almacenamiento en búfer de datos de conexión TCP
Puedes usar el atributo de configuración nodelay
a fin de inhabilitar el almacenamiento en búfer de datos para las conexiones TCP que usa Edge Microgateway.
De forma predeterminada, las conexiones TCP usan el algoritmo de Nagle para almacenar datos en búfer antes de enviarlos. Si se configura nodelay
en true
, se inhabilita este comportamiento (los datos activan de inmediato los datos cada vez que se llama a
socket.write()
). Consulta también la documentación de Node.js para obtener más detalles.
Para habilitar nodelay
, edita el archivo de microconfiguración de Edge de la siguiente manera:
edgemicro: nodelay: true port: 8000 max_connections: 1000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Ejecuta Edge Microgateway en modo independiente
Puedes ejecutar Edge Microgateway desconectado por completo de cualquier dependencia de Apigee Edge. Esta situación, llamada modo independiente, te permite ejecutar y probar Edge Microgateway sin una conexión a Internet.
En modo independiente, las siguientes características no funcionan, ya que requieren conexión a Apigee Edge:
- OAuth y clave de API
- Cuota
- Estadísticas
Por otro lado, los complementos personalizados y la protección contra aumentos repentinos funcionan con normalidad, ya que no requieren una conexión a Apigee Edge. Además, un complemento nuevo llamado extauth
te permite autorizar llamadas a la API a la micropuerta de enlace con un JWT en modo independiente.
Configura e inicia la puerta de enlace
Para ejecutar Edge Microgateway en modo independiente, sigue estos pasos:
- Crea un archivo de configuración con el siguiente nombre:
$HOME/.edgemicro/$ORG
-
$ENV-config.yamlPor ejemplo:
vi $HOME/.edgemicro/foo-bar-config.yaml
- Pega el siguiente código en el archivo:
edgemicro: port: 8000 max_connections: 1000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - extauth - spikearrest headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true extauth: publickey_url: https://www.googleapis.com/oauth2/v1/certs spikearrest: timeUnit: second allow: 10 buffersize: 0
- Exporta la siguiente variable de entorno con el valor "1":
export EDGEMICRO_LOCAL=1
- Ejecuta el siguiente comando de
start
, en el que proporcionas valores para crear una instancia del proxy local:edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \ -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH
Aquí:
- $ORG es el nombre de la "organización" que usaste en el nombre del archivo de configuración.
- $ENV es el nombre "env" que usaste en el nombre del archivo de configuración.
- $LOCAL_PROXY_NAME es el nombre del proxy local que se creará. Puedes usar el nombre que quieras.
- $LOCAL_PROXY_VERSION es el número de versión del proxy.
- $TARGET_URL es la URL del destino del proxy. (El destino es el servicio al que llama el proxy).
- $BASE_PATH es la ruta base del proxy. Este valor debe comenzar con una barra diagonal. Para una ruta base, especifica solo una barra diagonal; por ejemplo, “/”.
Por ejemplo:
edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
- Probar la configuración
curl http://localhost:8000/echo { "error" : "missing_authorization" }
Debido a que el complemento
extauth
está en el archivofoo-bar-config.yaml
, se mostrará el error "missing_authorization". Este complemento valida un JWT que debe estar presente en el encabezado de autorización de la llamada a la API. En la siguiente sección, obtendrás un JWT que permitirá que se realicen llamadas a la API sin el error.
Ejemplo: Cómo obtener un token de autorización
En el siguiente ejemplo, se muestra cómo obtener un JWT del extremo JWT de Edge Microgateway en Apigee Edge (edgemicro-auth/jwkPublicKeys
). Este extremo se implementa cuando realizas una configuración estándar de Edge Microgateway.
Para obtener el JWT del extremo de Apigee, primero debes realizar la configuración estándar de Edge Microgateway y
estar conectado a Internet. El extremo de Apigee se usa aquí solo con fines de ejemplo y no es obligatorio. Si lo deseas, puedes usar otro extremo del token JWT. Si lo haces, deberás obtener el JWT con la API proporcionada para ese extremo.
En los siguientes pasos, se explica cómo obtener un token con el extremo edgemicro-auth/jwkPublicKeys
:
- Debes realizar una configuración estándar de Edge Microgateway para implementar el proxy
edgemicro-auth
en tu organización o entorno de Apigee Edge. Si realizaste este paso anteriormente, no es necesario que lo repitas. - Si implementaste Edge Microgateway en Apigee Cloud, debes estar conectado a Internet para obtener un JWT de este extremo.
-
Detén Edge Microgateway:
edgemicro stop
- En el archivo de configuración que creaste antes (
$HOME/.edgemicro
/org-env-config.yaml
), apunta el atributoextauth:publickey_url
al extremoedgemicro-auth/jwkPublicKeys
en tu organización o entorno de Apigee Edge. Por ejemplo:extauth: publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
. -
Reinicia Edge Microgateway como lo hiciste antes con los nombres de org/env que usaste en el nombre del archivo de configuración. Por ejemplo:
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
-
Obtén un token JWT del extremo de autorización. Debido a que estás usando el extremo
edgemicro-auth/jwkPublicKeys
, puedes usar este comando de la CLI:
Puedes generar un JWT para Edge Microgateway con el comando de edgemicro token
o una API. Por ejemplo:
edgemicro token get -o your_org -e your_env \ -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
Aquí:
- your_org es el nombre de la organización de Apigee para la que configuraste previamente Edge Microgateway.
- your_env es un entorno de la organización.
- La opción
i
especifica la clave de consumidor de una app de desarrollador que tiene un producto que incluye el proxyedgemicro-auth
. - La opción
s
especifica el Secreto de consumidor de una app de desarrollador que tiene un producto que incluye el proxyedgemicro-auth
.
Este comando le pide a Apigee Edge que genere un JWT que se pueda usar para verificar las llamadas a la API.
Consulta también Cómo generar un token.Prueba la configuración independiente
Para probar la configuración, llama a la API con el token en el encabezado Autorización, como se indica a continuación:
curl http://localhost:8000/echo -H "Authorization: Bearer your_token
Ejemplo:
curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"
Resultado de ejemplo:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }
Usa el modo de proxy local
En el modo de proxy local, Edge Microgateway no requiere que se implemente un proxy con reconocimiento de microgateway en Apigee Edge. En su lugar, para configurar un "proxy local", proporciona un nombre de proxy local, una ruta base y una URL de destino cuando inicias la micropuerta de enlace. Luego, las llamadas a la API a la micropuerta de enlace se envían a la URL de destino del proxy local. En todos los demás aspectos, el modo de proxy local funciona de la misma manera que ejecutar Edge Microgateway en modo normal. La autenticación funciona de la misma manera, al igual que la protección contra aumentos repentinos, la aplicación de cuotas, los complementos personalizados, etcétera.
Caso de uso y ejemplo
El modo de proxy local es útil cuando solo necesitas asociar un solo proxy a una instancia de Edge Microgateway. Por ejemplo, puedes incorporar Edge Microgateway en Kubernetes como un proxy de sidecar, en el que una micropuerta de enlace y un servicio se ejecutan en un solo Pod, y en el que la micropuerta de enlace administra el tráfico desde y hacia su servicio complementario. En la siguiente figura, se ilustra esta arquitectura en la que Edge Microgateway funciona como un proxy de sidecar en un clúster de Kubernetes. Cada instancia de micropuerta de enlace se comunica solo con un único extremo en su servicio complementario:
Un beneficio de este estilo de arquitectura es que Edge Microgateway proporciona administración de API para servicios individuales implementados en un entorno de contenedores, como un clúster de Kubernetes.
Configura el modo de proxy local
Si deseas configurar Edge Microgateway para que se ejecute en modo de proxy local, sigue estos pasos:
- Ejecuta
edgemicro init
para establecer el entorno de configuración local, tal como lo harías en una configuración típica de Edge Microgateway. Consulta también Configura Edge Microgateway. - Ejecuta
edgemicro configure
, como lo harías en un procedimiento de configuración típico de Edge Microgateway. Por ejemplo:edgemicro configure -o your_org -e your_env -u your_apigee_username
Este comando implementa la política edgemicro-auth en Edge y muestra una clave y un secreto que necesitarás para iniciar la micropuerta de enlace. Si necesitas ayuda, consulta Configura Edge Microgateway.
- En Apigee Edge, crea un producto de API que cumpla con los siguientes requisitos de configuración obligatorios (puedes administrar todas las demás configuraciones como desees):
- Debes agregar el proxy edgemicro-auth al producto. Este proxy
se implementó automáticamente cuando ejecutaste
edgemicro configure
. - Debes proporcionar una ruta de acceso al recurso. Apigee recomienda agregar esta ruta de acceso al producto:
/**
. Para obtener más información, consulta Configura el comportamiento de la ruta de acceso al recurso. Consulta también Cómo crear productos de API en la documentación de Edge.
- Debes agregar el proxy edgemicro-auth al producto. Este proxy
se implementó automáticamente cuando ejecutaste
En Apigee Edge, crea un desarrollador, o bien usa uno existente si lo deseas. Si deseas obtener ayuda, consulta Agrega desarrolladores mediante la IU de administración de Edge.
- En Apigee Edge, crea una app de desarrollador. Debes agregar a la app el producto de API que acabas de crear. Para obtener ayuda, consulta Registra una app en la IU de administración de Edge.
- En la máquina en la que está instalado Edge Microgateway, exporta la siguiente variable de entorno con el valor “1”.
export EDGEMICRO_LOCAL_PROXY=1
- Ejecuta el siguiente comando de
start
:edgemicro start -o your_org -e your_environment -k your_key -s your_secret \ -a local_proxy_name -v local_proxy_version -t target_url -b base_path
Aquí:
- your_org es tu organización de Apigee.
- your_environment es un entorno de tu organización.
- your_key es la clave que se mostró cuando ejecutaste
edgemicro configure
. - your_secret es el secreto que se mostró cuando ejecutaste
edgemicro configure
. - local_proxy_name es el nombre del proxy local que se creará.
- local_proxy_version es el número de versión del proxy.
- target_url es la URL de destino del proxy (el servicio al que llamará el proxy).
- base_path es la ruta base del proxy. Este valor debe comenzar con una barra diagonal. Para una ruta base, especifica solo una barra diagonal; por ejemplo, “/”.
Por ejemplo:
edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \ -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \ -t http://mocktarget.apigee.net -b /echo
Prueba la configuración
Puedes probar la configuración del proxy local llamando al extremo del proxy. Por ejemplo, si especificaste una ruta base de /echo
, puedes llamar al proxy de la siguiente manera:
curl http://localhost:8000/echo { "error" : "missing_authorization", "error_description" : "Missing Authorization header" }
Esta llamada a la API inicial produjo un error porque no proporcionaste una clave de API válida. Puedes encontrar la clave en la app de desarrollador que creaste anteriormente. Abre la app en la IU de Edge, copia la clave de consumidor y úsala de la siguiente manera:
curl http://localhost:8000/echo -H 'x-api-key:your_api_key'
Por ejemplo:
curl http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"
Resultado de ejemplo:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }
Usa el sincronizador
En esta sección, se explica cómo usar el sincronizador, una función opcional que mejora la resiliencia de Edge Microgteway, ya que le permite recuperar datos de configuración de Apigee Edge y escribirlos en una base de datos local de Redis. Con una instancia del sincronizador en ejecución, otras instancias de Edge Microgateway que se ejecutan en diferentes nodos pueden recuperar la configuración directamente desde esta base de datos.
Actualmente, la función de sincronizador es compatible con Redis 5.0.x.
¿Qué es el sincronizador?
El sincronizador proporciona un nivel de resiliencia para Edge Microgateway. Ayuda a garantizar que todas las instancias de Edge Microgateway usen la misma configuración y que, en caso de una interrupción de Internet, las instancias de Edge Microgateway puedan iniciarse y ejecutarse de forma correcta.
De forma predeterminada, las instancias de Edge Microgateway deben poder comunicarse con Apigee Edge para recuperar y actualizar los datos de configuración, como el proxy de la API y las configuraciones de los productos de la API. Si se interrumpe la conexión a Internet con Edge, las instancias de micropuerta de enlace pueden seguir funcionando porque los datos de configuración más recientes se almacenan en caché. Sin embargo, las instancias de micropuerta de enlace nuevas no pueden iniciarse sin una conexión clara. Además, es posible que una interrupción de Internet genere una o más instancias de micropuerta de enlace que se ejecuten con información de configuración que no esté sincronizada con otras instancias.
El sincronizador de Edge Microgateway proporciona un mecanismo alternativo para que las instancias de Edge Microgateway recuperen los datos de configuración que requieren a fin de iniciar y procesar el tráfico del proxy de la API.
Entre los datos de configuración recuperados de las llamadas a Apigee Edge, se incluyen las llamadas jwk_public_keys
, jwt_public_key
, de arranque y las de productos de la API.
El sincronizador permite que todas las instancias de Edge Microgateway que se ejecutan en diferentes nodos se inicien de forma correcta y se mantengan sincronizadas, incluso si se interrumpe la conexión a Internet entre Edge Microgateway y Apigee Edge.
El sincronizador es una instancia configurada de manera especial de Edge Microgateway. Su único propósito es sondear Apigee Edge (el tiempo se puede configurar), recuperar datos de configuración y escribirlos en una base de datos local de Redis. La instancia del sincronizador no puede procesar el tráfico del proxy de API. Se pueden configurar otras instancias de Edge Microgateway que se ejecutan en nodos diferentes para recuperar datos de configuración de la base de datos de Redis en lugar de Apigee Edge. Debido a que todas las instancias de micropuerta de enlace extraen sus datos de configuración de la base de datos local, pueden iniciar y procesar solicitudes a la API, incluso en caso de una interrupción de Internet.
Configura una instancia del sincronizador
Agrega la siguiente configuración al archivo org-env/config.yaml
para la instalación de Edge Microgateway que deseas usar como sincronizador:
edgemicro: redisHost: host_IP redisPort: host_port redisDb: database_index redisPassword: password edge_config: synchronizerMode: 1 redisBasedConfigCache: true
Por ejemplo:
edgemicro: redisHost: 192.168.4.77 redisPort: 6379 redisDb: 0 redisPassword: codemaster edge_config: synchronizerMode: 1 redisBasedConfigCache: true
Opción | Descripción |
---|---|
redisHost |
El host en el que se ejecuta tu instancia de Redis. Valor predeterminado: 127.0.0.1 |
redisPort |
El puerto de la instancia de Redis. Valor predeterminado: 6379 |
redisDb |
Es la base de datos de Redis que se usará. Valor predeterminado: 0 |
redisPassword |
La contraseña de la base de datos. |
Por último, guarda el archivo de configuración y, luego, inicia la instancia de Edge Microgateway. Comenzará sondear Apigee Edge y almacenar los datos de configuración descargados en la base de datos de Redis.
Configura instancias normales de Edge Microgateway
Con el sincronizador en ejecución, puedes configurar nodos adicionales de Edge Microgateway para ejecutar instancias de micropuertas de enlace normales que procesan el tráfico de proxy de la API. Sin embargo, debes configurar estas instancias para obtener los datos de configuración de la base de datos de Redis en lugar de Apigee Edge.
Agrega la siguiente configuración al archivo org-env/config.yaml
de cada nodo adicional de Edge Microgateway. Ten en cuenta que la propiedad synchronizerMode
está configurada como 0
. Esta propiedad configura la instancia para que funcione como una instancia normal de Edge Microgateway que procesa el tráfico del proxy de la API, y la instancia obtendrá los datos de configuración de la base de datos de Redis.
edgemicro: redisHost: host_IP redisPort: host_port redisDb: database_index redisPassword: password edge_config: synchronizerMode: 0 redisBasedConfigCache: true
Por ejemplo:
edgemicro: redisHost: 192.168.4.77 redisPort: 6379 redisDb: 0 redisPassword: codemaster edge_config: synchronizerMode: 0 redisBasedConfigCache: true
Propiedades de configuración
Se agregaron las siguientes propiedades de configuración para admitir el uso del sincronizador:
Atributo | Valores | Descripción |
---|---|---|
edge_config.synchronizerMode |
0 o 1 | Si es 0 (la opción predeterminada), Edge Microgateway funciona en su modo estándar. Si es 1, inicia la instancia de Edge Microgateway para que funcione como un sincronizador. En este modo, la instancia extraerá datos de configuración de Apigee Edge y los almacenará en una base de datos local de Redis. Esta instancia no puede procesar las solicitudes del proxy de API. Su único propósito es sondear los datos de configuración de Apigee Edge y escribirlos en la base de datos local. Luego, debes configurar otras instancias de micropuerta de enlace para leer desde la base de datos. |
edge_config.redisBasedConfigCache |
True o False | Si es verdadero, la instancia de Edge Microgateway recupera los datos de configuración de la
base de datos de Redis en lugar de Apigee Edge. La base de datos de Redis debe ser la misma en la que está configurado el sincronizador para escribir. Si la base de datos de Redis no está disponible o si la base de datos está vacía, la micropuerta de enlace busca un archivo cache-config.yaml existente para su configuración.
Si es falso (la opción predeterminada), la instancia de Edge Microgateway recupera los datos de configuración de Apigee Edge como de costumbre. |
edgemicro.config_change_poll_interval |
Intervalo de tiempo, en segundos | Especifica el intervalo de sondeo para que el sincronizador extraiga datos de Apigee Edge. |
Cómo configurar URLs de exclusión para los complementos
Puedes configurar la micropuerta de enlace para que omita el procesamiento de complementos en URL especificadas. Puedes configurar estas URL de “exclusión” globalmente (para todos los complementos) o para complementos específicos.
Por ejemplo:
... edgemicro: ... plugins: excludeUrls: '/hello,/proxy_one' # global exclude urls sequence: - oauth - json2xml - quota json2xml: excludeUrls: '/hello/xml' # plugin level exclude urls ...
En este ejemplo, los complementos no procesarán las llamadas entrantes del proxy de la API con las rutas de acceso /hello
o /proxy_one
. Además, se omitirá el complemento json2xml
para las APIs con /hello/xml
en su ruta de acceso.
Establece atributos de configuración con valores de variables de entorno
Puedes especificar variables de entorno mediante etiquetas en el archivo de configuración. Las etiquetas de variable de entorno especificadas se reemplazan por los valores reales de la variable de entorno. Los reemplazos se almacenan solo en la memoria y no en la configuración original ni en los archivos de caché.
En este ejemplo, el atributo key
se reemplaza por el valor de la variable de entorno TARGETS_SSL_CLIENT_KEY
, y así sucesivamente.
targets: - ssl: client: key: <E>TARGETS_SSL_CLIENT_KEY</E> cert: <E>TARGETS_SSL_CLIENT_CERT</E> passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>
En este ejemplo, la etiqueta <n>
se usa para indicar un valor de número entero. Solo se admiten números enteros positivos.
edgemicro: port: <E><n>EMG_PORT</n></E>
En este ejemplo, la etiqueta <b>
se usa para indicar un valor booleano (es decir, verdadero o falso).
quotas: useRedis: <E><b>EMG_USE_REDIS</b></E>