Guía de operaciones

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Cómo obtener una clave de API

En el siguiente ejemplo se explica cómo obtener una clave de API que puedes usar para validar las llamadas a la API a un servicio de destino proxy a través de Apigee Adapter for Envoy.

1. Iniciar sesión en Apigee

  1. Inicia sesión en la interfaz de usuario de Apigee.
  2. Selecciona la misma organización que usaste para aprovisionar el adaptador de Apigee para Envoy.

2. Crear un desarrollador

Puedes usar un desarrollador que ya tengas para hacer pruebas o crear uno nuevo siguiendo estos pasos:

  1. En el menú de navegación lateral, selecciona Publicar > Desarrolladores.
  2. Haz clic en + Desarrollador.
  3. Rellena el cuadro de diálogo para crear un desarrollador. Puedes usar el nombre o el correo del desarrollador que quieras.

3. Crear un producto de API

Sigue el ejemplo de creación de productos que se indica a continuación.

  1. En el menú de navegación lateral, seleccione Publicar > Productos de API.
  2. Haz clic en + CREAR.
  3. Rellene la sección Detalles del producto de la siguiente manera. En la siguiente tabla solo se mencionan los campos obligatorios:
    Campo Valor Descripción
    Nombre httpbin-product Nombre único del producto de la API.
    Nombre visible httpbin product El nombre descriptivo que quieres que se muestre en la interfaz de usuario u otros contextos de visualización.
    Acceso Public En este ejemplo, Público es una buena opción.
  4. En la sección Operaciones, haz clic en +AÑADIR UNA OPERACIÓN.
  5. En la sección Fuente, selecciona Servicio remoto.
  6. Activa el interruptor Origen para poder escribir manualmente el nombre de un servicio remoto en el campo Servicio remoto.
  7. En el campo Servicio remoto, introduce el nombre de un servicio remoto. Es un servicio de destino al que el adaptador envía solicitudes HTTP entrantes. Para hacer pruebas, usa httpbin.org o httpbin.default.svc.cluster.local con Kubernetes.

    Se selecciona el botón de radio Servicio remoto, se habilita el interruptor para habilitar la introducción de texto manual y se introduce el servicio remoto httpbin.org en el campo Servicio remoto.

  8. En la sección Operation (Operación), introduzca / en la ruta. Para obtener información sobre las opciones de ruta, consulta el artículo Configurar rutas de recursos.
  9. Haz clic en GUARDAR para guardar la operación.
  10. Haz clic en GUARDAR para guardar el producto de la API.

Para obtener más información, consulta Gestionar productos de API.

4. Crear una aplicación de desarrollador

La aplicación para desarrolladores contiene la clave de API necesaria para hacer llamadas a proxies de API a través del adaptador.

  1. Seleccione Publicar aplicaciones en el menú de navegación lateral.
  2. Haz clic en + Aplicación.
  3. Rellena la sección Detalles de la aplicación de la siguiente manera. En la siguiente tabla solo se mencionan los campos obligatorios:
    4. Nombre httpbin-app
    Desarrolladores Seleccione el desarrollador que haya creado anteriormente o elija el que quiera de la lista.
  4. En la sección Credenciales, haga clic en + Añadir producto y seleccione el producto que acaba de configurar: httpbin-product.
  5. Haz clic en Crear.
  6. En Credenciales, haz clic en Mostrar junto a Clave.
  7. Copia el valor de la clave de consumidor. Este valor es la clave de API que usarás para hacer llamadas a la API del servicio httpbin a través del adaptador de Apigee para Envoy.

Usar la autenticación basada en JWT

Puedes usar un token JWT para hacer llamadas autenticadas a un proxy de API en lugar de usar una clave de API. En esta sección se explica cómo usar el comando apigee-remote-service-cli token para crear, inspeccionar y rotar tokens JWT. En un entorno híbrido de Apigee, puedes usar este comando para crear un secreto de Kubernetes que contenga los JWTs.

Información general

Envoy se encarga de la verificación y la autenticación de JWT mediante su filtro de autenticación JWT.

Una vez autenticado, el filtro ext-authz de Envoy envía los encabezados de solicitud y el JWT a apigee-remote-service-envoy. Compara las reclamaciones api_product_list y scope del JWT con los productos de API de Apigee para autorizarlo en el destino de la solicitud.

Crear tokens JWT de Apigee

Los tokens JWT de Apigee se pueden crear con la CLI:

apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

O bien, mediante el endpoint de token de OAuth estándar. Ejemplo de curl:

curl https://org-env.apigee.net/remote-token/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

Usar el token JWT

Una vez que tengas el token, solo tienes que enviarlo a Envoy en el encabezado Authorization. Ejemplo:

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

Error de token JWT

Rechazo de Envoy

Si Envoy rechaza el token, puede que veas un mensaje como este:

Jwks remote fetch has failed

Si es así, asegúrate de que tu configuración de Envoy contenga un URI válido en la sección remote_jwks, de que Envoy pueda acceder a él y de que hayas configurado correctamente los certificados al instalar el proxy de Apigee. Deberías poder llamar al URI directamente con una llamada GET y recibir una respuesta JSON válida.

Ejemplo:

curl https://myorg-eval-test.apigee.net/remote-service/certs

Otros mensajes de Envoy pueden ser los siguientes:

  • "No se permiten audiencias en Jwt"
  • "Jwt issuer is not configured" ("No se ha configurado el emisor de JWT")

Se trata de requisitos de la configuración de Envoy que puede que tengas que modificar.

Inspeccionar un token

Puedes usar la CLI para inspeccionar tu token. Ejemplo

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

o 

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

Depuración

Consulta La clave de API válida falla.

Usar tu propio proveedor de identidades

De forma predeterminada, Apigee Adapter for Envoy usa el proxy de API remote-token como servicio de proveedor de identidades para autenticar aplicaciones cliente y entregar tokens JWT basados en el tipo de autorización de credenciales de cliente de OAuth 2.0. Sin embargo, en algunos casos, es posible que no puedas usar el proxy remote-token. Si debes usar un proveedor de identidades que no sea el que proporciona Apigee, puedes configurar el adaptador para que use otro proveedor de identidades. Para obtener información sobre este caso práctico de proveedor de identidades que no es de Apigee y la configuración necesaria, consulta este artículo de la comunidad de Apigee: Using your own Identity Provider with the Apigee Envoy Adapter (Usar tu propio proveedor de identidades con el adaptador Envoy de Apigee).

Almacenamiento de registros

Puedes ajustar el nivel de registro en el servicio $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. Todos los registros se envían a stderr.

Elemento Obligatorio Descripción
-l, --log-level Niveles válidos: debug, info, warn y error. Ajusta el nivel de registro. Valor predeterminado: info
-j, --json-log Emite la salida de registro como registros JSON.

Envoy proporciona registros. Para obtener más información, consulta los siguientes enlaces de la documentación de Envoy:

Cambiar el nombre del secreto de la política

Un secreto de Kubernetes desplegado en el clúster contiene las credenciales que necesita el adaptador para autenticar la comunicación con el proxy del servicio remoto. Este secreto requiere un punto de montaje de volumen, que se puede configurar. De forma predeterminada, el punto de montaje es /policy-secret. Para cambiar el punto de montaje, sigue estos pasos:

  1. Ejecuta este comando: 
    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

    Por ejemplo: 

    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point
  2. Abre $CLI_HOME/samples/apigee-envoy-adapter.yaml en un editor.
  3. Cambia el nombre del punto de montaje por el nuevo: 
    volumeMounts:
  - mountPath: /config
    name: apigee-remote-service-envoy
    readOnly: true
  - mountPath: /opt/apigee/tls
    name: tls-volume
    readOnly: true
  - mountPath: /my-mount-point
    name: policy-secret
    readOnly: true
  4. Guarda el archivo y aplícalo a la malla de servicios: 
    kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

Usar un proxy de red

Se puede insertar un proxy HTTP mediante las variables de entorno HTTP_PROXY y HTTPS_PROXY en el entorno del archivo binario apigee-remote-service-envoy. Cuando se usan estas variables, también se puede usar la variable de entorno NO_PROXY para excluir hosts específicos de que se envíen a través del proxy.

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

Recuerda que se debe poder acceder al proxy desde apigee-remote-service-envoy.

Acerca de las métricas y las analíticas

Hay un endpoint de métricas de Prometheus disponible en :5001/metrics. Puedes configurar este número de puerto. Consulta el artículo Archivo de configuración.

Analíticas de Envoy

En los siguientes enlaces se proporciona información sobre cómo obtener datos analíticos del proxy Envoy:

Analíticas de Istio

En los siguientes enlaces se proporciona información sobre cómo obtener datos analíticos del proxy Envoy:

Analíticas de Apigee

Apigee Remote Service for Envoy envía estadísticas de solicitudes a Apigee para que se procesen las analíticas. Apigee informa de estas solicitudes con el nombre del producto de API asociado.

Para obtener información sobre las analíticas de Apigee, consulta el resumen de los servicios de analíticas.

Compatibilidad con entornos multicliente

Ahora puede habilitar el adaptador para que dé servicio a varios entornos de una organización de Apigee. Esta función le permite usar un adaptador de Apigee para Envoy asociado a una organización de Apigee para dar servicio a varios entornos. Antes de este cambio, un adaptador siempre estaba vinculado a un entorno de Apigee.

Para configurar la compatibilidad con varios entornos, cambia el valor de tenant:env_name a "*" en el archivo config.yaml. Por ejemplo:

  1. Abre el archivo config.yaml en un editor.
  2. Cambia el valor de tenant.env_name a "*". Por ejemplo: 
    apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://apitest.mydomain.net/remote-service
      org_name: my-org
      env_name: "*""
      allow_unverified_ssl_cert: true
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://apitest.mydomain.net/remote-token/token
  3. Guarda el archivo.
  4. Aplica el archivo: 
    kubectl apply -f $CLI_HOME/config.yaml

Cuando configures el modo multientorno, también debes configurar Envoy para que envíe un valor de entorno adecuado al adaptador. Para ello, añade los siguientes metadatos en la sección virtual_hosts:routes del archivo envoy-config.yaml. Por ejemplo:

  1. Genera el archivo envoy-config.yaml con la CLI. Por ejemplo: 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  2. Abre el archivo generado (se llama envoy-config.yaml).
  3. Añada los siguientes metadatos en la sección virtual_host o routes del archivo: 
    typed_per_filter_config:
  envoy.filters.http.ext_authz:
    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
    check_settings:
      context_extensions:
        apigee_environment: test

    En el siguiente ejemplo se muestra la configuración de un virtual_host con varias rutas definidas, donde cada ruta envía tráfico a un entorno específico: 

    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          route_config:
            virtual_hosts:
            - name: default
              domains: "*"
              routes:
              - match: { prefix: /test }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: test
              - match: { prefix: /prod }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: prod
  4. Repite el último paso para añadir más entornos según sea necesario.
  5. Guarda el archivo y aplícalo.

Recoger datos para informes personalizados

El adaptador permite transferir metadatos de Envoy a la función de captura de datos de Apigee, que envía los datos capturados en las variables que especifiques a las analíticas de Apigee para usarlos en informes personalizados. Esta función ofrece una función similar a la política de captura de datos de Apigee.

Para usar esta función:

  1. Crea un recurso REST de recopilador de datos.
  2. Define variables de captura de datos con la API datacollectors de Apigee.
  3. Si aún no lo has hecho, genera el archivo envoy-config.yaml con la CLI. Por ejemplo: 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  4. Abre el archivo generado (se llama envoy-config.yaml).
  5. Usa un filtro de Envoy para definir los valores de tus variables personalizadas en el espacio de nombres envoy.filters.http.apigee.datacapture. Por ejemplo, puede usar un filtro Encabezado a metadatos o un filtro Lua. Para obtener más información sobre estos filtros, consulta Header-To-Metadata y Lua.

    Los nombres de las variables personalizadas deben tener el formato dc.XXXXX.

    Ejemplo de filtro de encabezado a metadatos: 

     - name: envoy.filters.http.header_to_metadata
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
    request_rules:
      - header: "Host"
        on_header_present:
          metadata_namespace: envoy.filters.http.apigee.datacapture
          key: dc.host  # host (without the prefix) also works
          type: STRING
        remove: false

    Ejemplo de filtro de Lua: 

    - name: envoy.filters.http.lua
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
    inline_code: |
      function envoy_on_request(request_handle)
        metadata = request_handle:streamInfo():dynamicMetadata()
        metadata:set("envoy.filters.http.apigee.datacapture", "dc.test", "A test string.")
      end
  6. Añade el filtro que quieras al archivo. Echa un vistazo a estos ejemplos.
  7. Guarda el archivo y aplícalo.

Configurar mTLS entre el adaptador y el tiempo de ejecución de Apigee

Puede proporcionar certificados TLS del lado del cliente en la sección tenant del archivo config.yaml del adaptador para usar mTLS entre el adaptador y el tiempo de ejecución de Apigee. Este cambio se aplica a todas las plataformas de Apigee compatibles. También habilita mTLS para las analíticas de la plataforma Apigee Edge para nubes privadas. Por ejemplo: 

tenant:
  tls:
    ca_file: path/ca.pem
    cert_file: path/cert.pem
    key_file: path/key.pem
    allow_unverified_ssl_cert: false