Ejecuta el proxy de servicio extensible localmente o en otra plataforma

En esta página, se explica cómo configurar y ejecutar una instancia del proxy de servicio extensible (ESP) en una máquina local, en otro proveedor de servicios en la nube, como Amazon Web Services (AWS) o en un clúster de Kubernetes que no se ejecuta en Google Cloud.

Puedes ejecutar el ESP en una computadora Linux o macOS o en una máquina virtual (VM). Microsoft Windows no es compatible. Puedes implementar tu aplicación y el ESP en el mismo host o en hosts diferentes. Alojar una instancia local del ESP te permite hacer lo siguiente:

  • Probar el ESP antes de implementarlo en una plataforma de producción
  • Verificar que la configuración de seguridad esté configurada y funcione de forma correcta, además de que las métricas y los registros aparezcan en la página Endpoints > Servicios como se esperaba.

Requisitos previos

Como punto de partida, en esta página se da por hecho lo siguiente:

  • Que instalaste Docker, si vas a implementar el contenedor del ESP de forma local o en una VM. Consulta Cómo instalar Docker para obtener más información.

  • Has implementado una API en una máquina local o en un host al que se puede acceder con el host en el que ejecuta el ESP.

  • Que configuraste Cloud Endpoints y, además, implementaste la configuración a fin de crear un servicio administrado para tu API.

Si necesitas una API para realizar pruebas con el ESP, puedes implementar y configurar el código de muestra en la sección Opcional: usa una API de muestra. Si ya implementaste y configuraste tu API, ve a Crea una cuenta de servicio.

Opcional: usa una API de muestra

En esta sección, aprenderás a configurar y, también, implementar la versión de Python de la muestra getting-started para Endpoints de forma local. Sigue los pasos de esta sección solo si no tienes una API para realizar pruebas con el ESP.

La muestra getting-started de Cloud Endpoints está disponible en otros lenguajes. Consulta la página Muestras si quieres conocer la ubicación del GitHub para la muestra getting-started en el lenguaje que prefieras. Sigue las instrucciones del archivo README.md de la muestra para realizar la ejecución local. Luego, sigue las instrucciones de esta sección a fin de configurar Endpoints y, además, implementar la configuración.

Cómo obtener el software necesario

Si aún no configuraste un entorno de desarrollo de Python, consulta Cómo configurar un entorno de desarrollo de Python para obtener asesoramiento. Asegúrate de tener instalado lo siguiente:

Obtén el código de muestra

  1. Clona el repositorio de la aplicación de muestra en tu máquina local con el siguiente comando:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples
    
  2. Ve al directorio que contiene el código de muestra:

    cd python-docs-samples/endpoints/getting-started
    

Configura Endpoints

  1. En el directorio de código de muestra, abre el archivo de configuración openapi.yaml.

    swagger: "2.0"
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"
  2. En el campo host, reemplaza YOUR-PROJECT-ID con tu propio ID del proyecto de Google Cloud.

  3. Guarda el archivo openapi.yaml.

Implementa la configuración de Endpoints

Para implementar la configuración de Endpoints, usas el comando de gcloud endpoints services deploy. Este comando usa Service Management a fin de crear un servicio administrado.

  1. Actualiza el SDK de Cloud:

    gcloud components update
    
  2. Asegúrate de que el SDK de Cloud (gcloud) esté autorizado para acceder a tus datos y servicios en Google Cloud:

    gcloud auth login
    

    En la pestaña del navegador nueva que se abre, selecciona una cuenta.

  3. Configura el proyecto predeterminado como el ID del proyecto de la manera siguiente:

    gcloud config set project YOUR-PROJECT-ID
    

    Reemplaza YOUR-PROJECT-ID con el ID del proyecto de Google Cloud que especificaste en el archivo openapi.yaml.

  4. Implementa tu configuración:

    gcloud endpoints services deploy openapi.yaml
    

Service Management usa el texto que especificaste en el campo host del archivo openapi.yaml para crear un servicio de Endpoints nuevo con el nombre echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog (si no existe) y, luego, configura el servicio según tu archivo de configuración de OpenAPI.

A medida que se crea y configura el servicio, Service Management envía información a la terminal. Puedes ignorar las advertencias sin problemas sobre las rutas de acceso en el archivo openapi.yaml que no requieren una clave de API. Cuando completas la tarea con éxito, una línea similar a la siguiente muestra el ID de configuración del servicio y el nombre del servicio entre corchetes:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y echo-api.endpoints.example-project-12345.cloud.goog es el nombre del servicio.

Inicia tu servidor local

  1. Crea un virtualenv, actívalo y, luego, instala las dependencias de la aplicación.

    virtualenv env
    source env/bin/activate
    pip install -r requirements.txt
    
  2. Inicia el servidor. Para esto, sigue los pasos siguientes:

    python main.py
    
  3. Abre otra ventana de la terminal y usa curl para enviar una solicitud de la manera siguiente:

    curl --request POST \
        --header "content-type:application/json" \
        --data '{"message":"hello world"}' \
        http://localhost:8080/echo
    

    La API repite el mensaje que le enviaste y responde lo siguiente:

    {
      "message": "hello world"
    }
    

Crea una cuenta de servicio

A fin de proporcionar administración a tu API, el ESP y el ESPv2 Beta requieren los servicios de la infraestructura del servicio. Para llamar a estos servicios, el ESP y el ESPv2 Beta deben usar tokens de acceso. Cuando implementas el ESP o el ESPv2 Beta en entornos de Google Cloud, como GKE o Compute Engine, el ESP y el ESPv2 Beta obtienen tokens de acceso mediante el servicio de metadatos de Google Cloud.

Cuando implementas el ESP o el ESPv2 Beta en un entorno que no sea de Google Cloud, como tu computadora de escritorio local, un clúster de Kubernetes local o cualquier otro proveedor de servicios en la nube, tienes que proporcionar un archivo JSON de una cuenta de servicio que contenga una clave privada. El ESP y el ESPv2 Beta usan la cuenta de servicio con el fin de generar tokens de acceso que le permitan llamar a los servicios que necesita para administrar tu API.

Puedes usar Cloud Console o la herramienta de línea de comandos de gcloud a fin de crear la cuenta de servicio y el archivo de claves privadas, y para asignar las siguientes funciones a la cuenta de servicio:

Console

  1. En Cloud Console, abre la página Cuentas de servicio.

    Ir a la página Cuentas de servicio

  2. Haz clic en Seleccionar un proyecto.
  3. Selecciona el proyecto en el que creaste tu API y haz clic en Abrir.
  4. Haz clic en + Crear cuenta de servicio.
  5. En el campo Nombre de la cuenta de servicio, ingresa el nombre de tu cuenta de servicio.
  6. Haga clic en Crear.
  7. Haz clic en Continuar.
  8. Haga clic en Listo.
  9. Selecciona la cuenta de servicio creada recientemente, haz clic en el menú Acción en el extremo derecho y haz clic en el elemento de menú Crear clave.
  10. En el panel emergente de "Crear clave privada", selecciona el Tipo de clave y usa el tipo predeterminado, JSON.
  11. Haga clic en Crear.

Esto crea la cuenta de servicio y descarga su clave privada a un archivo JSON.

gcloud

  1. Ingresa lo siguiente para mostrar los ID de tus proyectos de Google Cloud:

    gcloud projects list
  2. Reemplaza PROJECT_ID en el comando siguiente para definir el proyecto predeterminado donde está tu API:

    gcloud config set project PROJECT_ID

  3. Asegúrate de que el SDK de Cloud (gcloud) esté autorizado para acceder a tus datos y servicios en Google Cloud:

    gcloud auth login

    Si tienes más de una cuenta, asegúrate de elegir la cuenta que está en el proyecto de Google Cloud en el que se encuentra la API. Si ejecutas gcloud auth list, la cuenta que seleccionaste se muestra como la cuenta activa para el proyecto.

  4. Para crear una cuenta de servicio, ejecuta el comando siguiente y reemplaza SERVICE_ACCOUNT_NAME y My Service Account por el nombre y el nombre comercial que quieres usar:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME 
    --display-name "My Service Account"

    Con el comando, se asigna una dirección de correo electrónico para la cuenta de servicio en este formato:

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Esta dirección de correo electrónico se requiere en los comandos posteriores.

  5. Crea un archivo de claves de la cuenta de servicio:

    gcloud iam service-accounts keys create ~/service-account-creds.json \
          --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Agrega las funciones de IAM necesarias:

Las siguientes funciones de IAM son necesarias para la cuenta de servicio que se usa en el ESP y el ESPv2 Beta.

Para agregar las funciones de controlador de servicio y IAM del agente de Cloud Trace a la cuenta de servicio, sigue estos pasos:

Console

  1. En Cloud Console, selecciona el proyecto en el que se creó tu cuenta de servicio.
  2. Abrir la página IAM/Iam

    Ir a la página IAM/Iam

    . La página debería enumerar todos los miembros de IAM, incluidas todas las cuentas de servicio.
  3. Selecciona tu cuenta de servicio y haz clic en el marcador Editar a la derecha.
  4. Se abrirá un panel de Editar permisos.
  5. Haz clic en + Agregar otra función.
  6. Haz clic en Seleccionar una función y selecciona Administración de servicio > Controlador de servicio.
  7. Haz clic en + Agregar otra función.
  8. Haz clic en Seleccionar una función y selecciona Cloud Trace > Agente de Cloud Trace.
  9. Haga clic en Save.
  10. Ahora deberías ver las funciones Control de servicio y Agente de Cloud Trace en la columna función de tu cuenta de servicio en la página de IAM.

gcloud

  1. Agrega la función de controlador de servicio:

    gcloud projects add-iam-policy-binding PROJECT_ID \
            --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
            --role roles/servicemanagement.serviceController
  2. Agrega la función de Agente de Cloud Trace para habilitar Cloud Trace:

    gcloud projects add-iam-policy-binding PROJECT_ID \
            --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
            --role roles/cloudtrace.agent

Para obtener más información, consulta ¿Qué son las funciones y los permisos?

See
[`gcloud iam service-accounts`](/sdk/gcloud/reference/iam/service-accounts/){: track-type="tutorial" track-name="internalLink" track-metadata-position="body" }
for more information about the commands.

Ejecuta ESP en un contenedor

En esta sección, se describe cómo implementar el contenedor del ESP. El procedimiento que uses dependerá de las opciones siguientes para implementar el contenedor del ESP:

En los siguientes ejemplos, la opción del ESP --http_port solo funciona si el servicio gRPC tiene configurada la transcodificación HTTP/JSON. Para obtener más información, consulta Transcodificar HTTP/JSON a gRPC.

Ejecuta el ESP en un contenedor de Docker de forma local o en otra plataforma

  1. Renombra el archivo JSON que contiene la clave privada para la cuenta de servicio a service-account-creds.json y cópialo en $HOME/Downloads/, si se descargó en un directorio diferente. De esta forma, el nombre completo de la ruta de acceso coincide con el valor para --service_account_key en el comando de docker run siguiente.

  2. En el comando siguiente de docker run, reemplaza YOUR_SERVICE_NAME por el nombre de tu servicio.

Linux

sudo docker run \
    --detach \
    --name="esp" \
    --net="host" \
    --volume=$HOME/Downloads:/esp \
    --publish=8082 \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --http2_port=8083 \
    --backend=grpc://localhost:8080 \
    --service_account_key=/esp/service-account-creds.json
  

mac OS

La opción --net="host" de Docker no funciona en macOS. En su lugar, debes realizar una asignación de puertos explícita del host al contenedor, en la que reemplaces --net="host" por --publish 8082:8082. También debes reemplazar localhost por el nombre de DNS especial docker.for.mac.localhost solo para macOS. Consulta la sección sobre casos prácticos y soluciones alternativas en la documentación de Docker para obtener más información.

sudo docker run \
    --detach \
    --name="esp" \
    --publish=8082:8082 \
    --volume=$HOME/Downloads:/esp \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --http2_port=8083 \
    --backend=grpc://docker.for.mac.localhost:8080 \
    --service_account_key=/esp/service-account-creds.json
  

Otra plataforma

sudo docker run \
    --detach \
    --name="esp" \
    --net="host" \
    --volume=$HOME/Downloads:/esp \
    --publish=8082 \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --http2_port=8083 \
    --backend=grpc://IP_Address:PORT \
    --service_account_key=/esp/service-account-creds.json
  

En la siguiente tabla, se describen las opciones de Docker utilizadas en los comandos anteriores. Para obtener más información sobre las opciones del ESP que se usaron en el ejemplo, consulta Opciones de inicio del ESP.

Opción Descripción
--detach Esta opción de Docker inicia al contenedor en modo separado, así que se ejecuta en segundo plano.
--name="esp" Esta opción de Docker brinda al contenedor un nombre de fácil acceso. Por ejemplo, para ver los registros del contenedor, puedes ejecutar docker logs esp.
--net="host" Esta opción indica que el contenedor de Docker usa la misma configuración de red que la máquina host, lo que le permite realizar llamadas al host local en la máquina host. Esta opción no funciona para ejecutar el ESP de manera local en macOS.
--publish=8082:8082 En macOS, cuando quieras ejecutar el ESP de manera local, usa esta opción de Docker, en lugar de --net="host", para hacer una asignación explícita de puertos desde el host hasta el contenedor.
--volume=
$HOME/Downloads:/esp
Con esta opción de Docker, se asigna tu directorio local $HOME/Downloads al directorio /esp en el contenedor. La opción del ESP --service_account_key usa esta asignación.

Ejecuta el ESP en un contenedor dentro de un clúster de Kubernetes

En esta sección, se describe cómo implementar el ESP en un clúster de Kubernetes que no está en Google Cloud.

Para que Endpoints administre tu API, debes implementar el contenedor del ESP en el mismo pod de Kubernetes que el del contenedor de tu API. El conjunto de pods que ejecutan el ESP y tu API se agrupan en un servicio de Kubernetes mediante un selector de etiquetas, como app: my-api. El servicio de Kubernetes especifica la política de acceso para balancear la carga de las solicitudes del cliente en el puerto del proxy.

  1. Renombra el archivo JSON que contiene la clave privada para la cuenta de servicio a service-account-creds.json y cópialo en $HOME/Downloads/, si se descargó en un directorio diferente. De este modo, el nombre completo de la ruta de acceso al directorio coincidirá con el comando en el paso siguiente.

  2. Ejecuta el comando siguiente para crear un secreto de Kubernetes y actívalo como un volumen de Kubernetes.

    kubectl create secret generic service-account-creds \
    --from-file=$HOME/Downloads/service-account-creds.json
    

    Cuando el proceso finaliza con éxito, se muestra el siguiente mensaje: secret "service-account-creds" created

  3. En tu archivo de configuración de Kubernetes, agrega lo siguiente y reemplaza YOUR_APP_NAME con el nombre de tu API y YOUR_SERVICE_NAME con el nombre de tu servicio.

    spec:
    replicas: 1
    template:
      metadata:
        labels:
          app: "YOUR_APP_NAME"
      spec:
        volumes:
          - name: service-account-creds
            secret:
              secretName: service-account-creds
              containers:
          - name: esp
            image: gcr.io/endpoints-release/endpoints-runtime:1
            args: [
              "--http_port=8082",
              "--http2_port=8083",
              "--backend=grpc://127.0.0.1:8081",
              "--service=YOUR_SERVICE_NAME",
              "--rollout_strategy=managed",
              "--service_account_key=/etc/nginx/creds/service-account-creds.json"
            ]
            ports:
              - containerPort: 8080
            volumeMounts:
              - mountPath: /etc/nginx/creds
                name: service-account-creds
                readOnly: true
    

    Para obtener más información sobre las opciones del ESP que se utilizaron en el ejemplo, consulta Opciones de inicio del ESP.

  4. Implementa el ESP en Kubernetes. Reemplaza YOUR_CONFIGURATION_FILE por el nombre de tu archivo de configuración de Kubernetes.

    kubectl apply -f YOUR_CONFIGURATION_FILE
    

Envía solicitudes

Para confirmar que el archivo de la cuenta de servicio sea correcto y que los puertos estén bien asignados, envía algunas solicitudes a tu API y asegúrate de que pasen por el ESP. Puedes ver los registros del ESP si ejecutas el comando siguiente:

sudo docker logs esp

Los ejemplos siguientes envían solicitudes a la API de muestra. Si no usas la API de muestra, te recomendamos que ejecutes pruebas similares.

Configuraste el contenedor del ESP para recibir solicitudes en el puerto 8082. Si envías una solicitud directo al servidor en http://localhost:8080, la solicitud omite el ESP. Por ejemplo:

Solicitud:

    curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      http://localhost:8080/echo

Respuesta:

    {
      "message": "hello world"
    }

Cuando envías una solicitud a http://localhost:8082, que pasa por el ESP, y no envías una clave de API, el ESP rechaza la solicitud. Por ejemplo:

Solicitud:

    curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      http://localhost:8082/echo

Respuesta:

    {
     "code": 16,
     "message": "Method doesn't allow unregistered callers (callers without
      established identity). Please use API Key or other form of API consumer
      identity to call this API.",
     "details": [
      {
       "@type": "type.googleapis.com/google.rpc.DebugInfo",
       "stackEntries": [],
       "detail": "service_control"
      }
     ]
    }

Para probar la API con una clave de API, haz lo siguiente:

  1. Crea una clave de API en la página Credenciales de API.

    Ir a la página Credenciales

  2. Haz clic en Crear credenciales y, luego, selecciona Clave de API.

  3. Copia la clave y pégala en la declaración de variable de entorno siguiente:

    export KEY=AIza...
    
  4. Envía una solicitud con la clave:

    curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      http://localhost:8082/echo?key=$KEY
    

    Verás la respuesta siguiente que indica que el proceso se completó de forma correcta:

    {
      "message": "hello world"
    }
    

Realiza una limpieza

Apaga y quita el contenedor de Docker esp con la herramienta de docker de la siguiente manera:

sudo docker stop esp
sudo docker rm esp

Si deseas limpiar la configuración del servicio implementado, consulta Borrar una API y las instancias relacionadas.

Próximos pasos