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 ejemplo siguiente, se explica cómo obtener una clave de API que puedes usar a fin de validar las llamadas a la API a un servicio de destino que se envían mediante Apigee Adapter for Envoy.

1. Accede a Apigee

  1. Accede a la IU de Apigee.
  2. Selecciona la misma organización que usaste para aprovisionar Apigee Adapter for Envoy.

2. Crear un desarrollador

Puedes usar un desarrollador existente para realizar pruebas o crear uno nuevo de la siguiente manera:

  1. Selecciona Publicar > Desarrolladores en el menú de navegación lateral.
  2. Haz clic en + Desarrollador.
  3. Completa el diálogo para crear un nuevo desarrollador. Puedes usar cualquier nombre de desarrollador o correo electrónico que desees.

3. Crear un producto de API

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

  1. Selecciona Publicar > Productos de API en el menú de navegación lateral.
  2. Haz clic en +CREAR.
  3. Completa la página Detalles del producto como se indica a continuación. Solo los campos obligatorios se mencionan en la siguiente tabla:
    Campo Valor Descripción
    Nombre httpbin-product El nombre único del producto de API.
    Nombre visible httpbin product Es el nombre descriptivo que deseas ver en la IU o en otros contextos de visualización.
    Acceso Public Para los fines de este ejemplo, Pública es una buena opción.
  4. En la sección Operaciones, haz clic en AGREGAR UNA OPERACIÓN.
  5. En la sección Fuente, selecciona Servicio remoto.
  6. Cambia el interruptor de Fuente (Source) para permitirte escribir de forma manual el nombre de un servicio remoto en el campo del servicio remoto.
  7. En el campo Servicio remoto, ingresa el nombre de un servicio remoto. Este es un servicio de destino al que el adaptador envía solicitudes HTTP entrantes. Para fines de prueba, usa httpbin.org o httpbin.default.svc.cluster.local con Kubernetes.

    Se selecciona el botón de selección Servicio remoto, se selecciona el botón para activar o desactivar la entrada de texto manual y se ingresa el servicio remoto httpbin.org en el campo Servicio remoto.

  8. En la sección Operación, ingresa / para la ruta de acceso. Para obtener más información sobre las opciones de ruta, consulta Configura rutas de recursos.
  9. Haz clic en Guardar para guardar la operación.
  10. Haz clic en Save para guardar el producto de API.

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

4. Crear una app de desarrollador

La app para desarrolladores contiene la clave de API que se requiere para realizar llamadas al proxy de API a través del adaptador.

  1. Selecciona Publicar Apps en el menú de navegación lateral.
  2. Haga clic en + App.
  3. Completa la sección Detalles de la app de la siguiente manera. Solo los campos obligatorios se mencionan en la siguiente tabla:
    4. Nombre httpbin-app
    Desarrollador Selecciona el desarrollador que creaste anteriormente o elige cualquier desarrollador que desees de la lista.
  4. En la sección Credenciales, haz clic en + Agregar producto y selecciona el producto que acabas 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 generada. Este valor es la clave de API que usarás para realizar llamadas a la API al servicio httpbin a través de Apigee Adapter for Envoy.

Usa la autenticación basada en JWT

Puedes usar un token JWT para realizar llamadas autenticadas al 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 a fin de crear el secreto de Kubernetes para contener los JWT.

Descripción general

Envoy administra la verificación y autenticación de JWT con su Filtro de autenticación de JWT.

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

Crea 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

También puedes usar el extremo del 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"

Usa el token JWT

Una vez que tengas el token, solo debes pasarlo a Envoy en el encabezado de Autorización. Ejemplo:

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

Falla del token JWT

Rechazo de Envoy

Si Envoy rechaza el token, es posible que veas un mensaje como el siguiente:

Jwks remote fetch has failed

Si es así, asegúrate de que la configuración de Envoy contenga un URI válido en la sección remote_jwks, que pueda acceder a Envoy y que hayas configurado los certificados de forma correcta cuando instalaste el proxy de Apigee. Deberías poder llamar a la 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 verse así:

  • "No se permite público en Jwt"
  • "La entidad emisora de Jwt no está configurada"

Son requisitos de tu configuración de Envoy que posiblemente debas modificar.

Inspecciona 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 Falla la clave de API válida.

Usa tu propio proveedor de identidad

De forma predeterminada, el adaptador de Apigee para Envoy usa el proxy de API remote-token como servicio de proveedor de identidad a fin de autenticar aplicaciones cliente y entregar tokens JWT según el tipo de otorgamiento 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 identidad que no sea el que proporciona Apigee, puedes configurar el adaptador para usar otro proveedor de identidad. Para obtener detalles sobre este caso de uso de proveedor de identidad que no es de Apigee y la configuración necesaria, consulta este artículo en la comunidad de Apigee: Usa tu propio proveedor de identidad con el adaptador de Envoy de Apigee.

Logging

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: depuración, información, advertencia, error. Ajusta el nivel de registro. Predeterminado: información
-j, --json-log Emite el resultado del registro como registros JSON.

Envoy proporciona registros. Para obtener más información, consulta los siguientes vínculos de documentación de Envoy:

Cambia el nombre del secreto de la política

Un secreto de Kubernetes implementado en el clúster contiene credenciales que el adaptador necesita para autenticar la comunicación con el proxy de servicio remoto. Este secreto requiere un punto de activación de volumen, que se puede configurar. De forma predeterminada, el punto de activación es /policy-secret. Para cambiar el punto de activación, 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 activación por el nombre 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

Usa un proxy de red

Se puede insertar un proxy HTTP con las variables de entorno HTTP_PROXY y HTTPS_PROXY en el entorno del objeto binario apigee-remote-service-envoy. Cuando se usan, la variable de entorno NO_PROXY también se puede usar para evitar que se envíen hosts específicos 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.

Información acerca de las métricas y las estadísticas

Un extremo de las métricas de Prometheus está disponible en :5001/metrics. Puedes configurar este número de puerto. Consulta Archivo de configuración.

Estadísticas de Envoy

En los vínculos siguientes, se proporciona información sobre cómo obtener datos de estadísticas del proxy de Envoy:

Estadísticas de Istio

En los vínculos siguientes, se proporciona información sobre cómo obtener datos de estadísticas del proxy de Envoy:

Estadísticas de Apigee

El servicio remoto de Apigee para Envoy envía estadísticas de solicitudes a Apigee para el procesamiento de estadísticas. Apigee informa estas solicitudes en el nombre del producto de API asociado.

Para obtener más información sobre las estadísticas de Apigee, consulta la descripción general de los servicios de estadísticas.

Compatibilidad con el entorno de multiusuario

Ahora puedes habilitar el adaptador para atender varios entornos en una organización de Apigee. Esta función te permite usar un adaptador de Apigee para Envoy asociado a una organización de Apigee para trabajar con 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 siguiente archivo: 
    kubectl apply -f $CLI_HOME/config.yaml

Cuando configuras el modo de varios entornos, también debes configurar Envoy para enviar un valor de entorno apropiado al adaptador. Para ello, agrega los siguientes metadatos en la sección virtual_hosts:routes del archivo envoy-config.yaml. Por ejemplo:

  1. Genera el archivo envoy-config.yaml mediante 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 (llamado envoy-config.yaml).
  3. Agrega 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 ilustra la configuración de un virtual_host con varias rutas definidas, en las que 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 agregar entornos adicionales según sea necesario.
  5. Guarda el archivo y aplícalo.

Captura datos para informes personalizados

El adaptador admite pasar metadatos de Envoy a la función de captura de datos de Apigee, que envía datos capturados en variables que especificas en Analytics para su uso en informes personalizados. Esta función proporciona una capacidad similar a la política de captura de datos de Apigee.

Para usar esta función, sigue estos pasos:

  1. Crea un recurso de REST de recopilación de datos.
  2. Define las variables de captura de datos con la API de recopilación de datos de Apigee.
  3. Si no lo hiciste, genera el archivo envoy-config.yaml mediante 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 (llamado envoy-config.yaml).
  5. Usa un filtro Envoy a fin de establecer valores para tus variables personalizadas en el espacio de nombres envoy.filters.http.apigee.datacapture. Por ejemplo, puedes usar un filtro de encabezado a metadatos o un filtro Lua. Para obtener más información sobre estos filtros, consulta Encabezado a metadatos y Lua.

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

    Ejemplo del 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 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. Agrega el filtro deseado al archivo. Consulta los ejemplos que se mencionan a continuación.
  7. Guarda el archivo y aplícalo.

Configura mTLS entre el adaptador y el entorno de ejecución de Apigee

Puedes 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 entorno de ejecución de Apigee. Este cambio se aplica a todas las plataformas de Apigee compatibles. También habilita mTLS para estadísticas de la plataforma Apigee Edge for la nube privada. Por ejemplo: 

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