Se usó la API de Cloud Translation para traducir esta página.
Switch to English

Comienza a usar Endpoints para Kubernetes con ESPv2

En este instructivo, se muestra cómo implementar un ejemplo simple del servicio de gRPC con el proxy de servicio extensible V2 (ESPv2) en un clúster de Kubernetes que no se ejecuta en Google Cloud. En este instructivo, se usa la versión de Python de la muestra de bookstore-grpc. Consulta la sección Próximos pasos para ver muestras de gRPC en otros lenguajes.

Además, se usan imágenes de contenedor compiladas con anterioridad del código de muestra y el ESPv2, que se almacenan en Container Registry. Si no estás familiarizado con los contenedores, consulta las páginas siguientes para obtener más información:

Si quieres obtener una descripción general de Cloud Endpoints, consulta Acerca de Endpoints y Arquitectura de Endpoints.

Objetivos

Usa la siguiente lista de tareas de alto nivel a medida que avanzas en el instructivo. Todas las tareas son necesarias para enviar solicitudes a la API con éxito.

  1. Configura un proyecto de Google Cloud y descarga el software necesario. Consulta Antes de comenzar.
  2. Copia y configura los archivos del bookstore-grpc de muestra. Consulta Configura Cloud Endpoints.
  3. Implementa la configuración de Endpoints para crear un servicio de Endpoints. Consulta Cómo configurar Endpoints.
  4. Crea credenciales para tu servicio de Endpoints. Consulta Crear credenciales para tu servicio.
  5. Crea un backend para entregar la API y, luego, implementarla. Consulta Implementa el backend de la API.
  6. Obtén la dirección IP externa del servicio. Consulta Cómo obtener la dirección IP externa del servicio.
  7. Envía una solicitud a la API. Consulta Enviar una solicitud a la API.
  8. Evita que se generen cargos en tu cuenta de Google Cloud. Consulta Limpiar.

Costos

En este instructivo, se usan los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud sean aptos para obtener una prueba gratuita.

Cuando finalices este instructivo, podrás borrar los recursos creados para evitar que se te siga facturando. Para obtener más información, consulta cómo hacer una limpieza.

Antes de comenzar

En este instructivo, se supone que ya configuraste un clúster de Kubernetes o Minikube. Para obtener más información, consulta la documentación de Kubernetes.

  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

    Ir a la página del selector de proyectos

  3. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Descubre cómo confirmar que tienes habilitada la facturación en un proyecto.

  4. Anota el ID del proyecto de Google Cloud porque se necesita más tarde.
  5. Instala e inicializa el SDK de Cloud.
  6. Actualiza el SDK de Cloud y, luego, instala los componentes de Endpoints.
    gcloud components update
  7. 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 nueva que se abre, selecciona una cuenta.
  8. Configura el proyecto predeterminado como el ID del proyecto:
    gcloud config set project
        YOUR_PROJECT_ID

    Reemplaza YOUR_PROJECT_ID con tu ID del proyecto de Google Cloud.

    Si tienes otros proyectos de Google Cloud y quieres usar gcloud para administrarlos, consulta la sección sobre cómo administrar los parámetros de configuración del SDK de Cloud.

  9. Instala kubectl:
    gcloud components install kubectl
  10. Adquiere credenciales de usuario nuevo para usar como credenciales predeterminadas de la aplicación. Se necesitan las credenciales de usuario para autorizar a kubectl.
    gcloud auth application-default login
  11. Se abrirá una nueva pestaña del navegador donde debes elegir una cuenta.
  12. Sigue los pasos en la Guía de inicio rápido de Python de gRPC para instalar gRPC y sus herramientas.

Configura Endpoints

El bookstore-grpc de muestra contiene los archivos que necesitas copiar y configurar de forma local.

  1. Crea un archivo descriptor protobuf autónomo desde tu archivo de servicio .proto:
    1. Guarda una copia de bookstore.proto del repositorio de ejemplo. Este archivo define la API del servicio de Bookstore.
    2. Crea el directorio siguiente: mkdir generated_pb2
    3. Crea api_descriptor.pb, el archivo descriptor, mediante el compilador de búferes de protocolo protoc. Ejecuta el comando siguiente en el directorio donde guardaste bookstore.proto:
      python -m grpc_tools.protoc \
          --include_imports \
          --include_source_info \
          --proto_path=. \
          --descriptor_set_out=api_descriptor.pb \
          --python_out=generated_pb2 \
          --grpc_python_out=generated_pb2 \
          bookstore.proto
      

      En el comando anterior, --proto_path se configura como el directorio de trabajo actual. En tu entorno de compilación de gRPC, si usas un directorio diferente para los archivos de entrada .proto, cambia --proto_path a fin de que el compilador busque el directorio donde guardaste bookstore.proto.

  2. Crea un archivo de configuración YAML para la API de gRPC:
    1. Guarda una copia del archivo api_config.yaml. Este archivo define la configuración de la API de gRPC para el servicio de Bookstore.
    2. Reemplaza MY_PROJECT_ID en tu archivo api_config.yaml con el ID de tu proyecto de Google Cloud. Por ejemplo:
      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      Ten en cuenta que el valor del campo apis.name en este archivo coincide con exactitud con el nombre de API calificado por completo del archivo .proto; de lo contrario, la implementación no funcionará. El servicio de Bookstore se define en bookstore.proto dentro del paquete endpoints.examples.bookstore. Su nombre de API calificado por completo es endpoints.examples.bookstore.Bookstore, tal como aparece en el archivo api_config.yaml.

      apis:
        - name: endpoints.examples.bookstore.Bookstore
      

Consulta Cómo configurar Endpoints para obtener más información.

Implemente la configuración de Endpoints

Para implementar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa Service Infrastructure, la plataforma básica de servicios de Google, que Endpoints y otros servicios usan para crear y administrar las API y los servicios.

  1. Asegúrate de estar en el directorio en el que se encuentran los archivos api_descriptor.pb y api_config.yaml.
  2. Confirma que el proyecto predeterminado que se usa actualmente en la herramienta de línea de comandos de gcloud sea el proyecto de Google Cloud en el que deseas implementar la configuración de Endpoints. Valida el ID del proyecto que se muestra en el comando siguiente para asegurarte de que el servicio no se cree en el proyecto equivocado.
    gcloud config list project
    

    Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando:

    gcloud config set project YOUR_PROJECT_ID
    
  3. Implementa el archivo proto descriptor y el archivo de configuración mediante la herramienta de línea de comandos de gcloud:
    gcloud endpoints services deploy api_descriptor.pb api_config.yaml
    

    Mientras se crea y configura el servicio, Service Management exporta la información a la terminal. Cuando se completa la implementación, aparece un mensaje similar al siguiente:

    Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

    CONFIG_ID es el ID de configuración único del servicio de Endpoints que creó la implementación. Por ejemplo:

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

    En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y bookstore.endpoints.example-project.cloud.goog es el nombre del servicio. El ID de configuración del servicio consiste en una marca de fecha seguida de un número de revisión. Si implementas la configuración de Endpoints otra vez el mismo día, el número de revisión aumenta en el ID de configuración del servicio.

Si recibes un mensaje de error, consulta Solucionar problemas con la implementación de la configuración de Cloud Endpoints.

Consulta Implementar la configuración de Endpoints para obtener información adicional.

Verifica los servicios requeridos

Como mínimo, Endpoints y ESP requieren que se habiliten los siguientes servicios de Google:
Name Cargo
servicemanagement.googleapis.com API de Administración de servicios
servicecontrol.googleapis.com API de Control de servicios
endpoints.googleapis.com Google Cloud Endpoints

En la mayoría de los casos, el comando de gcloud endpoints services deploy habilita estos servicios obligatorios. Sin embargo, el comando gcloud se completa de manera correcta sin habilitar los servicios requeridos en las circunstancias siguientes:

  • Usaste una aplicación de terceros, como Terraform, y no incluiste estos servicios.

  • Si implementaste la configuración de Endpoints en un proyecto existente de Google Cloud en el que se inhabilitaron explícitamente estos servicios

Usa el siguiente comando para confirmar que los servicios requeridos están habilitados:

gcloud services list

Si no ves los servicios necesarios que se incluyeron en la lista, habilítalos:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

También habilita el servicio de Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar la variable ENDPOINTS_SERVICE_NAME, puedes hacer lo siguiente:

  • Después de implementar la configuración de Endpoints, ve a la página Endpoints en Cloud Console. La lista de posibles ENDPOINTS_SERVICE_NAME se muestra en la columna Nombre del servicio.

  • Para OpenAPI, el ENDPOINTS_SERVICE_NAME es lo que especificaste en el campo host de tu especificación de OpenAPI. Para gRPC, el ENDPOINTS_SERVICE_NAME es lo que especificaste en el campo name de tu configuración de Endpoints de gRPC.

Para obtener más información sobre los comandos gcloud, consulta servicios de gcloud.

Crear credenciales para tu servicio

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

Cuando implementas el ESP o el ESPv2 en un entorno que no es 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 la cuenta de servicio que contenga una clave privada. El ESP y el ESPv2 usan la cuenta de servicio con el objetivo de generar tokens de acceso que le permitan llamar a los servicios que necesitan 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 "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 requeridas de IAM:

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

Para agregar las funciones de IAM de controlador de servicio y de 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. Abre 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.

Implemente el backend de la API

Hasta ahora, implementaste la configuración del servicio en Service Management, pero aún no implementaste el código que entregará el backend de la API. En esta sección, aprenderás a implementar contenedores compilados con anterioridad para el ESPv2 y la API de muestra en Kubernetes.

Proporciona el ESPv2 con las credenciales del servicio

El ESPv2, que se ejecuta dentro de un contenedor, necesita acceso a las credenciales almacenadas de forma local en el archivo service-account-creds.json. Para proporcionar al ESPv2 acceso a las credenciales, debes crear un Secret de Kubernetes y activarlo como un volumen de Kubernetes.

Para crear el secreto de Kubernetes y activar el volumen, sigue estos pasos:

  1. Si usaste Cloud Console para crear la cuenta de servicio, cambia el nombre del archivo JSON a service-account-creds.json. Muévelo al mismo directorio en el que se encuentran los archivos api_descriptor.pb y api_config.yaml.
  2. Crea un secreto de Kubernetes con las credenciales de la cuenta de servicio:

    kubectl create secret generic service-account-creds \
        --from-file=service-account-creds.json
    

    Cuando el proceso finaliza con éxito, se muestra el mensaje siguiente:

    secret "service-account-creds" created
    

El archivo de manifiesto de implementación que usas para implementar la API y el ESPv2 en Kubernetes ya contiene el volumen de Secret, como se muestra en las dos secciones siguientes del archivo:

volumes:
- name: service-account-creds
  secret:
    secretName: service-account-creds
volumeMounts:
- mountPath: /etc/esp/creds
  name: service-account-creds
  readOnly: true

Cómo configurar el nombre de servicio y cómo iniciar el servicio

El ESPv2 necesita saber el nombre de tu servicio para buscar la configuración que implementaste con anterioridad (con el comando gcloud endpoints services deploy).

Para configurar el nombre del servicio y luego iniciar el servicio, sigue estos pasos:

  1. Guarda una copia del archivo de manifiesto de implementación, grpc-bookstore.yaml, en el mismo directorio que service-account-creds.json.
  2. Abre grpc-bookstore.yaml y reemplaza SERVICE_NAME por el nombre de tu servicio de Endpoints. Este es el mismo nombre que configuraste en el campo name del archivo api_config.yaml.

    containers:
    - name: esp
      image: gcr.io/endpoints-release/endpoints-runtime:2
      args: [
        "--listener_port=9000",
        "--service=SERVICE_NAME",
        "--rollout_strategy=managed",
        "--backend=grpc://127.0.0.1:8000",
        "--service_account_key=/etc/esp/creds/service-account-creds.json",
      ]

    La opción --rollout_strategy=managed configura el ESPv2 para que use la configuración del servicio implementado más reciente. Cuando especificas esta opción, el ESPv2 detecta el cambio y comienza a aplicarlo de forma automática dentro del minuto siguiente a la implementación de una configuración de servicio nueva. Te recomendamos que especifiques esta opción en lugar de proporcionar un ID de configuración específico para que use el ESPv2. Si quieres obtener más detalles sobre los argumentos del ESPv2, consulta las opciones de inicio del ESPv2.

  3. Inicia el servicio para implementar el servicio en Kubernetes:

    kubectl create -f grpc-bookstore.yaml

    Podría aparecer un mensaje de error similar a este:

    The connection to the server localhost:8080 was refused - did you specify the right host or port?

    Esto indica que kubectl no está configurado de forma correcta. Consulta Configurar kubectl para obtener más información.

Obtén la dirección IP externa de la API

Necesitas la dirección IP externa del servicio para enviar solicitudes a la API de muestra. Es posible que la dirección IP externa tarde unos minutos en estar lista después de que inicies tu servicio en el contenedor.

  1. Para ver la dirección IP externa, sigue estos pasos:

    kubectl get service
  2. Toma nota del valor de EXTERNAL-IP y guárdalo en una variable de entorno SERVER_IP como se usaba al momento de enviar solicitudes a la API de muestra.

    export SERVER_IP=YOUR_EXTERNAL_IP
    

Envía una solicitud a la API

Para enviar solicitudes a la API de muestra, puedes usar un cliente gRPC de muestra escrito en Python.

  1. Clona el repositorio de Git donde se aloja el código del cliente gRPC:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
       

  2. Cambia tu directorio de trabajo:

    cd python-docs-samples/endpoints/bookstore-grpc/
      

  3. Instala las dependencias:

    pip install virtualenv
    virtualenv env
    source env/bin/activate
    python -m pip install -r requirements.txt
    

  4. Envía una solicitud a la API de muestra:

    python bookstore_client.py --host SERVER_IP --port 80
    

Si no obtienes una respuesta correcta, consulta Solucionar errores en las respuestas.

¡Acabas de implementar y probar una API en Endpoints!

Realice una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

  1. Borra la API:

    gcloud endpoints services delete SERVICE_NAME
    

    Reemplaza SERVICE_NAME por el nombre de tu API.

  2. Borra el clúster de GKE:

    gcloud container clusters delete NAME --zone ZONE
    

¿Qué sigue?