Comienza a usar Cloud Endpoints para Kubernetes con el ESPv2

OpenAPI  |  gRPC

En este instructivo, se muestra cómo configurar y también implementar una API de muestra y el proxy de servicio extensible V2 (ESPv2) en un clúster de Kubernetes que no está en Google Cloud. Si quieres usar Google Kubernetes Engine (GKE), consulta Comienza a usar Endpoints en GKE.

La API de ejemplo se describe con la especificación de OpenAPI. En este instructivo, también se muestra cómo crear una clave de API para enviar solicitudes a la API.

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

• Implementa una aplicación web en contenedor
• Imágenes de contenedor de Kubernetes

Para obtener una descripción general de Cloud Endpoints, consulta Acerca de Endpoints y la descripción de la arquitectura de Cloud Endpoints.

Objetivos

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

Parte 1

1. Configurar un proyecto de Google Cloud Consulta Antes de comenzar.
2. Instala y configura el software que se usa en el instructivo. Consulta Cómo instalar y configurar el software obligatorio.
3. Si lo deseas, puedes descargar el código de muestra. Consulta Cómo obtener el código de muestra.
4. Descarga el archivo de configuración de Kubernetes. Consulta Cómo obtener el archivo de configuración de Kubernetes.
5. Configura el archivo openapi.yaml, que se usa para configurar Endpoints. Consulta Cómo configurar Endpoints.
6. Implementa la configuración de Endpoints a fin de crear un servicio de Cloud Endpoints. Consulta Implementa la configuración de Endpoints.
7. Crea credenciales para tu servicio de Endpoints. Consulta Cómo crear credenciales para tu servicio.
8. Implementa la API y el ESP en el clúster. Consulta Cómo implementar el backend de la API.
9. Obtén la dirección IP externa del servicio. Consulta Obtén la dirección IP externa.
10. Envía una solicitud a la API mediante una dirección IP. Consulta Cómo enviar una solicitud mediante la dirección IP.
11. Realiza un seguimiento de la actividad de la API. Consulta Cómo realizar un seguimiento de la actividad de la API.

Parte 2

1. Configura un registro DNS para la API de muestra. Consulta Cómo configurar el DNS para Endpoints.
2. Envía una solicitud a la API con el nombre de dominio. Consulta Cómo enviar una solicitud mediante el FQDN.

Limpieza

Cuando termines, consulta Realizar una limpieza para evitar incurrir en cargos con tu cuenta de Google Cloud .

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• Endpoints

Para obtener una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios de Google Cloud nuevos cumplan con los requisitos para acceder a una prueba gratuita.

Cuando completes las tareas que se describen en este documento, podrás borrar los recursos que creaste para evitar que se te siga facturando. Para obtener más información, consulta Realiza una limpieza.

Antes de comenzar

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.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Toma nota del Google Cloud ID del proyecto, ya que lo necesitarás más adelante.

Instala y configura el software obligatorio

En este instructivo, instalarás Google Cloud CLI para usar la CLI de gcloud y administrar tu proyecto. Usarás kubectl, una interfaz de línea de comandos para ejecutar comandos con clústeres de Kubernetes. También necesitarás una forma de probar la API.

En el procedimiento siguiente, si ya tienes el software necesario instalado, continúa hasta el último paso.

Para instalar y configurar el software necesario, completa los pasos siguientes:

1. Necesitas una aplicación para enviar solicitudes a la API de muestra.

   • Usuarios de Linux y macOS: En este instructivo se proporciona un ejemplo del uso de curl, que suele venir preinstalado en el sistema operativo. Si no tienen curl, pueden descargarlo de la curl página de actualizaciones y descargas.
   • Usuarios de Windows: En este instructivo se proporciona un ejemplo del uso de Invoke-WebRequest, que es compatible con PowerShell 3.0 y versiones posteriores.
2. Instala e inicializa la CLI de gcloud.
3. Actualiza la gcloud CLI y, luego, instala los componentes de Endpoints:

   gcloud components update

4. Asegúrate de que Google Cloud CLI (gcloud) esté autorizada para acceder a tus datos y servicios en Google Cloud:

   gcloud auth login

   En la pestaña nueva que se abre, selecciona una cuenta.
5. Configura el proyecto predeterminado como el ID del proyecto:

   gcloud config set project YOUR_PROJECT_ID

   Reemplaza YOUR_PROJECT_ID con el ID del proyecto. Si tienes otros proyectos de Google Cloud y deseas usar gcloud para administrarlos, consulta Cómo gcloud CLI de gcloud.

6. Instala kubectl:

   gcloud components install kubectl

7. 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

8. Elige una cuenta en la pestaña nueva que se abre.
9. Ejecuta el comando siguiente para asegurarte de que el cliente de Kubernetes esté configurado de forma correcta:

   kubectl version

   Deberías ver un resultado similar al siguiente:

      Client Version: version.Info{Major:"1", Minor:"8", GitVersion:"v1.8.4",
        GitCommit:"9befc2b8928a9426501d3bf62f72849d5cbcd5a3", GitTreeState:"clean",
        BuildDate:"2017-11-20T05:28:34Z", GoVersion:"go1.8.3", Compiler:"gc",
        Platform:"linux/amd64"}
      Server Version: version.Info{Major:"1", Minor:"7+",
        GitVersion:"v1.7.8-gke.0",
        GitCommit:"a7061d4b09b53ab4099e3b5ca3e80fb172e1b018", GitTreeState:"clean",
        BuildDate:"2017-10-10T18:48:45Z", GoVersion:"go1.8.3", Compiler:"gc",
        Platform:"linux/amd64"}
      

Cómo descargar el código de muestra

Si lo deseas, puedes descargar el código de muestra. En este instructivo, implementarás una imagen de contenedor prediseñada para que no tengas que compilar un contenedor a partir del código de muestra. Sin embargo, tal vez necesites descargar el código de muestra, que está disponible en varios lenguajes para ayudarte a comprender cómo funciona la API de muestra.

Para descargar el código de muestra, sigue estos pasos:

Java

Para clonar o descargar la API de muestra, haz lo siguiente:

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

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

   Como alternativa, descarga la muestra como un archivo zip y extráelo.

2. Ve al directorio que contiene el código de muestra:

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

Python

Para clonar o descargar la API de muestra, haz lo siguiente:

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

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

   Como alternativa, descarga la muestra como un archivo zip y extráelo.

2. Ve al directorio que contiene el código de muestra:

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

Go

Para clonar o descargar la API de muestra, haz lo siguiente:

1. Asegúrate de que esté configurada tu variable de entorno de GOPATH.
2. Clona el repositorio de la aplicación de muestra en tu máquina local de la siguiente forma:

   go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

3. Ve al directorio que contiene el código de muestra:

   cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

PHP

Para clonar o descargar la API de muestra, haz lo siguiente:

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

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

   Como alternativa, descarga la muestra como un archivo zip y extráelo.

2. Ve al directorio que contiene el código de muestra:

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

Ruby

Para clonar o descargar la API de muestra, haz lo siguiente:

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

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

   Como alternativa, descarga la muestra como un archivo zip y extráelo.

2. Ve al directorio que contiene el código de muestra:

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

NodeJS

Para clonar o descargar la API de muestra, haz lo siguiente:

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

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

   Como alternativa, descarga la muestra como un archivo zip y extráelo.

2. Ve al directorio que contiene el código de muestra:

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

Obtén el archivo de configuración de Kubernetes

1. Clona el repositorio de GitHub que contiene los archivos yaml que se usaron en este instructivo en tu máquina local:

    git clone https://github.com/googlecloudplatform/endpoints-samples

   Como alternativa, descarga el ejemplo como un archivo ZIP y extráelo.

2. Ve al directorio que contiene los archivos de configuración:

    cd endpoints-samples/kubernetes

Configura Endpoints

Debes tener un documento de OpenAPI basado en OpenAPI 2.0 o OpenAPI 3.x que describa la superficie de tus apps y cualquier requisito de autenticación. Para obtener más información, consulta Versiones compatibles de OpenAPI.

También debes agregar un campo específico de Google que contenga la URL de cada app para que ESPv2 tenga la información necesaria para invocar una app. Si es la primera vez que usas OpenAPI, consulta la descripción general de OpenAPI para obtener más información.

Para configurar Endpoints, haz lo siguiente:

1. Crea un archivo de texto nuevo llamado openapi.yaml. Para mayor comodidad, esta página hace referencia al documento de OpenAPI con ese nombre, pero puedes darle otro nombre si así lo prefieres.
2. Copia el contenido de uno de los siguientes archivos en tu nuevo archivo openapi.yaml. Puedes usar OpenAPI 2.0 o OpenAPI 3.x.

   OpenAPI 2.0

   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"
   
   consumes:
     - "application/json"
   produces:
     - "application/json"
   
   schemes:
   # Uncomment the next line if you configure SSL for this API.
   # - "https"
     - "http"
   
   paths:
     /echo:
       post:
         description: "Echo back a given message."
         operationId: "echo"
         produces:
           - "application/json"
         responses:
           200:
             description: "Echo"
             schema:
               $ref: "#/definitions/echoMessage"
         parameters:
           -
             description: "Message to echo"
             in: body
             name: message
             required: true
             schema:
               $ref: "#/definitions/echoMessage"
         security:
           - api_key: []
     /auth/info/googlejwt:
       get:
         description: "Returns the requests' authentication information."
         operationId: "auth_info_google_jwt"
         produces:
           - "application/json"
         responses:
           200:
             description: "Authenication info."
             schema:
               $ref: "#/definitions/authInfoResponse"
         security:
           - api_key: []
             google_jwt: []
     /auth/info/googleidtoken:
       get:
         description: "Returns the requests' authentication information."
         operationId: "authInfoGoogleIdToken"
         produces:
           - "application/json"
         responses:
           200:
             description: "Authentication info."
             schema:
               $ref: "#/definitions/authInfoResponse"
         security:
           - api_key: []
             google_id_token: []
   
   definitions:
     echoMessage:
       type: "object"
       properties:
         message:
           type: "string"
     authInfoResponse:
       properties:
         id:
           type: "string"
         email:
           type: "string"
   
   securityDefinitions:
     # This section configures basic authentication with an API key.
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"
   
     # This section configures authentication using Google API Service Accounts
     # to sign a json web token. This is mostly used for server-to-server
     # communication.
     google_jwt:
       authorizationUrl: ""
       flow: "implicit"
       type: "oauth2"
       # This must match the 'iss' field in the JWT.
       x-google-issuer: "jwt-client.endpoints.sample.google.com"
       # Update this with your service account's email address.
       x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
       # This must match the "aud" field in the JWT. You can add multiple
       # audiences to accept JWTs from multiple clients.
       x-google-audiences: "echo.endpoints.sample.google.com"
     # This section configures authentication using Google OAuth2 ID Tokens.
     # ID Tokens can be obtained using OAuth2 clients, and can be used to access
     # your API on behalf of a particular user.
   
     google_id_token:
       authorizationUrl: ""
       flow: "implicit"
       type: "oauth2"
       x-google-issuer: "https://accounts.google.com"
       x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
       # Your OAuth2 client's Client ID must be added here. You can add
       # multiple client IDs to accept tokens from multiple clients.
       x-google-audiences: "YOUR_CLIENT_ID"

   OpenAPI 3.x

   openapi: 3.0.4
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   servers:
     - url: "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
       x-google-endpoint: {}
   
   paths:
     "/echo":
       post:
         description: "Echo back a given message."
         operationId: "echo"
         requestBody:
           description: "Message to echo"
           required: true
           content:
             "application/json":
               schema:
                 $ref: "#/components/schemas/echoMessage"
         responses:
           '200':
             description: "Echo"
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/echoMessage"
         security:
           - api_key: []
   
     "/auth/info/googlejwt":
       get:
         description: "Returns the requests' authentication information."
         operationId: "auth_info_google_jwt"
         responses:
           '200':
             description: "Authentication info."
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/authInfoResponse"
         security:
           - api_key: []
             google_jwt: []
   
     "/auth/info/googleidtoken":
       get:
         description: "Returns the requests' authentication information."
         operationId: "authInfoGoogleIdToken"
         responses:
           '200':
             description: "Authentication info."
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/authInfoResponse"
         security:
           - api_key: []
             google_id_token: []
   
   components:
     schemas:
       echoMessage:
         type: "object"
         properties:
           message:
             type: "string"
       authInfoResponse:
         properties:
           id:
             type: "string"
           email:
             type: "string"
   
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"
   
       google_jwt:
         type: "oauth2"
         flows:
           implicit:
             authorizationUrl: ""
             scopes: {}
         x-google-auth:
           issuer: "jwt-client.endpoints.sample.google.com"
           jwksUri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
           audiences: "echo.endpoints.sample.google.com"
   
       google_id_token:
         type: "oauth2"
         flows:
           implicit:
             authorizationUrl: ""
             scopes: {}
         x-google-auth:
           issuer: "https://accounts.google.com"
           jwksUri: "https://www.googleapis.com/oauth2/v3/certs"
           audiences:
             - "YOUR_CLIENT_ID"

En este instructivo, se usa una extensión específica de Google para la especificación de OpenAPI que te permite configurar el nombre del servicio. El método para especificar el nombre del servicio depende de la versión de la especificación de OpenAPI que uses.

OpenAPI 2.0

Usa el campo host para especificar el nombre del servicio:

host: echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog

Para configurar Endpoints, haz lo siguiente:

1. Abre el archivo openapi.yaml.
2. En el campo host, reemplaza YOUR_PROJECT_ID por el ID de tu proyecto Google Cloud .
3. Guarda el archivo openapi.yaml.

OpenAPI 3.x

Usa el campo url en el objeto servers para especificar el nombre del servicio:

servers:
- url: https://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
    x-google-endpoint: {}

Para configurar Endpoints, haz lo siguiente:

1. Abre el archivo openapi.yaml.
2. Si tu archivo openapi.yaml tiene un campo host, quítalo.
3. Agrega un objeto servers como se muestra.
4. En el campo url, reemplaza YOUR_PROJECT_ID por el ID de tu proyecto Google Cloud .
5. Guarda el archivo openapi.yaml.

Después de completar todos los pasos de configuración de modo que puedas enviar con éxito solicitudes a la API de muestra mediante una dirección IP, consulta Configurar DNS para Endpoints si quieres obtener información sobre cómo configurar echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog para que sea el nombre de dominio calificado por completo (FQDN).

Implementa la configuración de Endpoints

Para implementar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa la Administración de servicios para crear un servicio administrado.

Para implementar la configuración de Endpoints, haz lo siguiente:

1. Asegúrate de estar en el directorio en el que se encuentra tu archivo de configuración openapi.yaml.
2. Sube la configuración y crea un servicio administrado.

   gcloud endpoints services deploy openapi.yaml
   

Entonces, el comando gcloud llama a la API de Service Management para crear un servicio administrado con el nombre que especificaste en el campo host o servers.url del archivo openapi.yaml. La Administración de servicios configura el servicio de acuerdo con la configuración del archivo openapi.yaml. Cuando realizas cambios en openapi.yaml, debes volver a implementar el archivo para actualizar el servicio de Endpoints.

Mientras se crea y configura el servicio, la Administración de servicios exporta la información a la terminal. Puedes ignorar sin riesgo las advertencias que indican que las rutas de acceso en el archivo openapi.yaml no requieren una clave de API. Cuando termina de configurarse el servicio, la Administración de servicios muestra un mensaje con el ID de configuración del servicio y el nombre del servicio, de manera similar a este ejemplo:

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 servicio de Endpoints. El ID de configuración de servicio consiste en una marca de fecha seguida de un número de revisión. Si implementas el archivo openapi.yaml otra vez el mismo día, el número de revisión aumenta en el ID de configuración del servicio. Puedes ver la configuración del servicio de Endpoints en la página Endpoints > Servicios de la Google Cloud consola.

Si recibes un mensaje de error, consulta Cómo solucionar problemas en la implementación de la configuración de Endpoints.

Verifica los servicios requeridos

Como mínimo, Endpoints y ESP requieren que se habiliten los siguientes servicios de Google:

Name	Título
servicemanagement.googleapis.com	API de Administración de servicios
servicecontrol.googleapis.com	Service Control API

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.

• Implementaste la configuración de Endpoints en un proyecto deGoogle Cloud existente en el que estos servicios se inhabilitaron de forma explícita.

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

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 la consola de Cloud. 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 proporcionar administración a tu API, el ESP y el ESPv2 requieren los servicios de la infraestructura del servicio. 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, Compute Engine o el entorno flexible de App Engine, el ESP y el ESPv2 obtienen tokens de acceso a través delGoogle Cloud servicio de metadatos.

Cuando implementas el ESP o el ESPv2 en un entorno que no es deGoogle 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 necesita para administrar tu API.

Puedes usar la consola de Google Cloud o Google Cloud CLI para crear la cuenta de servicio y el archivo de claves privadas:

Console

1. En la consola de Google Cloud , 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. Haz clic en Listo.
9. Haz clic en la dirección de correo electrónico de la cuenta de servicio recién creada.
10. Haz clic en Claves.
11. Haz clic en Agregar clave. Luego, haz clic en Crear clave nueva.

12. Haz clic en Crear. Se descargará un archivo de claves JSON en tu computadora.

    Asegúrate de almacenar el archivo de claves de forma segura, ya que se puede usar para autenticarse como tu cuenta de servicio. Puedes mover este archivo y cambiarle el nombre como desees.

13. Haz clic en Cerrar.

gcloud

1. Ingresa lo siguiente para mostrar los IDs de tus proyectos deGoogle 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

   Importante: Debes crear la cuenta de servicio en el mismo proyecto en el que se encuentra tu API.

3. Asegúrate de que Google Cloud CLI (gcloud) esté autorizada 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 que está en el proyecto 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:

En esta sección, se describen los recursos de IAM que usan el ESP y el ESPv2 y las funciones de IAM necesarias para que la cuenta de servicio conectada acceda a estos recursos.

Configuración del servicio de extremo

El ESP y el ESPv2 llaman al Control de servicios que usa la configuración del servicio de extremo. La configuración del servicio de extremo es un recurso de IAM, por lo que el ESP y el ESPv2 necesitan la función de Controlador de servicio para acceder a él.

La función de IAM se encuentra en la configuración del servicio de extremo, no en el proyecto. Un proyecto puede tener múltiples opciones de configuración de servicio de extremo.

Usa el siguiente comando de gcloud a fin de agregar la función a la cuenta de servicio conectada para la configuración del servicio de extremo.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

En el ejemplo anterior
* SERVICE_NAME es el nombre del servicio de extremo
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com es la cuenta de servicio conectada

Cloud Trace

El ESP y el ESPv2 llaman al servicio de Cloud Trace para exportar Trace a un proyecto. Este proyecto se llama proyecto de seguimiento. En el ESP, el proyecto de seguimiento y el proyecto que posee la configuración del servicio de extremo son los mismos. En el ESPv2, el proyecto de seguimiento se puede especificar con la marca --tracing_project_id y, de forma predeterminada, se establece el proyecto de implementación.

El ESP y el ESPv2 requieren el rol de Agente de Cloud Trace para habilitar Cloud Trace.

Usa el siguiente comando de gcloud para agregar la función a la cuenta de servicio conectada:

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

En el ejemplo anterior
* TRACING_PROJECT_ID es el ID del proyecto de seguimiento
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.comes la cuenta de servicio conectada Para obtener más información, consulta ¿Qué son las funciones y los permisos?

Consulta gcloud iam service-accounts para obtener más información sobre los comandos.

Implementa el backend de la API

Hasta ahora, implementaste el documento de OpenAPI en Service Management, pero aún no implementaste el código que entrega 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.

Verifica los permisos necesarios

Otorga los permisos necesarios a la cuenta de servicio asociada con tu clúster:

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
    --member "serviceAccount:SERVICE_ACCOUNT" \
    --role roles/servicemanagement.serviceController

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

Cómo proporcionar las credenciales de servicio al ESPv2

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 secreto de Kubernetes y activarlo como un volumen de Kubernetes.

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

1. Asegúrate de renombrar el archivo JSON a service-account-creds.json y copiarlo en endpoints-samples/kubernetes si se descargó en un directorio diferente. De esta forma, el nombre coincidirá con las opciones especificadas en el archivo de manifiesto de implementación echo.yaml.
2. Asegúrate de estar en el directorio endpoints-samples/kubernetes.

3. Crea un secreto de Kubernetes con las credenciales de la cuenta de servicio mediante el siguiente comando:

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

   Si se realiza de forma correcta, verás 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. Abre el archivo de manifiesto de implementación, echo.yaml, y reemplaza SERVICE_NAME en las opciones de inicio del ESP por el nombre de tu servicio. Este es el mismo nombre que configuraste en el campo host o server.url de tu documento de OpenAPI. Por ejemplo:

   "--service=echo-api.endpoints.example-project-12345.cloud.goog"

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port=8080",
       "--backend=127.0.0.1:8081",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed",
       "--non_gcp",
       "--service_account_key=/etc/esp/creds/service-account-creds.json"
     ]
     ports:
       - containerPort: 8080
     volumeMounts:
       - mountPath: /etc/esp/creds
         name: service-account-creds
         readOnly: true
   - name: echo
     image: gcr.io/endpoints-release/echo:latest
     ports:
       - containerPort: 8081
   

   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 deseas obtener información acerca de las otras opciones del ESPv2 que se usan, consulta Opciones de inicio del ESPv2.

   Nota: Si usas MiniKube, debes cambiar el campo type del servicio de LoadBalancer a NodePort en el archivo de configuración.
   Nota: Te recomendamos que configures imagePullPolicy en la especificación del contenedor como Always. Esto permitirá que los pods recién creados siempre extraigan la versión más reciente del ESPv2. Lee sobre las prácticas recomendadas de configuración para obtener más detalles. Cuando se lanza una versión nueva del ESPv2, puedes realizar un reinicio progresivo de todos los pods para garantizar que se use la versión más reciente.

2. Inicia el servicio para implementar el servicio de Endpoints en Kubernetes mediante el siguiente comando:

   kubectl create -f echo.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 la sección sobre cómo configurar kubectl si quieres obtener más información. Para obtener más información, consulta cómo implementar Endpoints en Kubernetes.

Obtén la dirección IP externa del servicio

Si usas Minikube, ve a Cómo enviar una solicitud mediante la dirección IP. Es posible que la dirección IP externa tarde unos minutos en estar lista después de que inicies tu servicio en el contenedor.

Para visualizar la dirección IP externa del servicio, sigue estos pasos:

1. Ejecuta el comando siguiente:

   kubectl get service

2. Toma nota del valor de EXTERNAL-IP. Usa esta dirección IP cuando envíes una solicitud a la API de muestra.

Envía una solicitud mediante una dirección IP

Después de que la API de muestra comience a ejecutarse en el clúster del contenedor, puedes enviar solicitudes a la API.

Cómo crear una clave de API y configurar una variable de entorno

El código de muestra requiere una clave de API. La solicitud es más simple si configuras una variable de entorno para la clave de API.

1. En el mismo proyecto Google Cloud que usaste para tu API, crea una clave de API en la página de credenciales de la API. Si quieres crear una clave de API en otro proyecto de Google Cloud , consulta Cómo habilitar una API en tu proyecto de Google Cloud .

   Ir a la página Credenciales

2. Haz clic en Crear credenciales y selecciona Clave de API.
3. Copia la clave al portapapeles.
4. Haz clic en Cerrar.
5. En tu computadora local, pega la clave de API para asignarla a una variable de entorno:
   • En Linux o macOS: export ENDPOINTS_KEY=AIza...
   • En Windows PowerShell, haz lo siguiente: $Env:ENDPOINTS_KEY="AIza..."

Enviar la solicitud a minikube

Los comandos siguientes usan la variable del entorno ENDPOINTS_KEY que configuraste antes.

Linux o macOS

NODE_PORT=`kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}'`
MINIKUBE_IP=`minikube ip`
curl --request POST \
    --header "content-type:application/json" \
    --data '{"message":"hello world"}' \
    ${MINIKUBE_IP}:${NODE_PORT}/echo?key=${ENDPOINTS_KEY}

PowerShell

$Env:NODE_PORT=$(kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}')
$Env:MINIKUBE_IP=$(minikube ip)
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://$Env:MINIKUBE_IP:$Env:NODE_PORT/echo?key=$Env:ENDPOINTS_KEY").Content

Envía la solicitud a otros clústeres de Kubernetes

Linux o macOS

Usa curl para enviar una solicitud HTTP con la variable de entorno ENDPOINTS_KEY que configuraste antes. Reemplaza IP_ADDRESS por la dirección IP externa de la instancia.

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

En el curl anterior, sucede lo siguiente:

• La opción --data especifica los datos que se publicarán en la API.
• La opción --header especifica que los datos están en formato JSON.

PowerShell

Usa Invoke-WebRequest para enviar una solicitud HTTP con la variable de entorno ENDPOINTS_KEY que configuraste antes. Reemplaza IP_ADDRESS por la dirección IP externa de la instancia.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

En el ejemplo anterior, las dos primeras líneas terminan en un acento grave. Cuando pegues el ejemplo en PowerShell, asegúrate de que no quede un espacio después de los acentos graves. Para obtener más información sobre las opciones usadas en la solicitud de ejemplo, consulta Invoke-WebRequest en la documentación de Microsoft.

App de terceros

Puedes usar una aplicación de terceros, como la extensión del navegador Chrome Postman, para enviar la solicitud:

• Selecciona POST como el verbo HTTP.
• Para el encabezado, selecciona la clave content-type y el valor application/json.
• Para el cuerpo, ingresa lo siguiente:
  {"message":"hello world"}
• En la URL, usa la clave de API real en lugar de la variable de entorno. Por ejemplo:
  http://192.0.2.0:80/echo?key=AIza...

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

{
  "message": "hello world"
}

Si no obtuviste una respuesta correcta, consulta Soluciona errores de respuesta.

¡Acabas de implementar y probar una API en Endpoints!

Nota: Si quieres contarnos qué te gustó de este instructivo, envíanos tus comentarios al final de esta página. Tus comentarios nos ayudarán a mejorar estos instructivos.
Si recibiste un error, únete al grupo de Google google-cloud-endpoints y cuéntanos cuál fue el problema. En este grupo encontrarás respuestas de otros usuarios de Endpoints y de los ingenieros de Google, quienes supervisan el grupo.

Cómo realizar un seguimiento de la actividad de la API

Para realizar un seguimiento de la actividad de la API, sigue estos pasos:

1. Para ver los grafos de actividad de tu API, ve a la página Endpoints > Servicios.
   

   Ir a la página Servicios de Endpoints

   
   La solicitud puede tardar unos momentos en reflejarse en los grafos.

2. Revisa los registros de solicitud de tu API en la página del visor de registros.
   

   Ir a la página Explorador de registros

Cómo configurar el DNS para Endpoints

Debido a que el nombre del servicio de Endpoints para la API se encuentra en el dominio .endpoints.YOUR_PROJECT_ID.cloud.goog, puedes usarlo como el nombre de dominio calificado por completo (FQDN) mediante un pequeño cambio de configuración en el archivo openapi.yaml. De este modo, puedes enviar solicitudes a la API de muestra si usas echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog en lugar de la dirección IP.

Para configurar DNS de Endpoints, sigue estos pasos:

OpenAPI 2.0

1. Abre tu archivo de configuración de OpenAPI, openapi.yaml, y agrega la propiedad x-google-endpoints en el nivel superior del archivo (sin sangría ni anidado) como se muestra en el siguiente fragmento:

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
   x-google-endpoints:
   - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
     target: "IP_ADDRESS"

2. En la propiedad name, reemplaza YOUR_PROJECT_ID por el ID del proyecto.
3. En la propiedad target, reemplaza IP_ADDRESS por la dirección IP que usaste cuando enviaste una solicitud a la API de muestra.
4. Implementa tu archivo de configuración de OpenAPI actualizado en la Administración de servicios:

   gcloud endpoints services deploy openapi.yaml
   

OpenAPI 3.x

1. Abre tu archivo de configuración de OpenAPI, openapi.yaml, y agrega la propiedad servers.url en el nivel superior del archivo (sin sangría ni anidado) como se muestra en el siguiente fragmento:

   servers:
     - url: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
       x-google-endpoint:
         target: "IP_ADDRESS"

2. En la propiedad name, reemplaza YOUR_PROJECT_ID por el ID del proyecto.
3. En la propiedad target, reemplaza IP_ADDRESS por la dirección IP que usaste cuando enviaste una solicitud a la API de muestra.
4. Implementa tu archivo de configuración de OpenAPI actualizado en la Administración de servicios:

   gcloud endpoints services deploy openapi.yaml
   

Por ejemplo, supongamos que el archivo openapi.yaml está configurado de esta manera:

OpenAPI 2.0

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

OpenAPI 3.x

servers:
  - url: "echo-api.endpoints.example-project-12345.cloud.goog"
    x-google-endpoint:
      target: "192.0.2.1"

Cuando implementas el archivo openapi.yaml con el comando gcloud anterior, la Administración de servicios crea un registro A de DNS, echo-api.endpoints.my-project-id.cloud.goog, que se resuelve en la dirección IP de destino, 192.0.2.1. Es posible que la nueva configuración de DNS tarde algunos minutos en propagarse.

Configura SSL

Para obtener más detalles sobre cómo configurar DNS y SSL, consulta Cómo habilitar SSL para Endpoints.

Envía una solicitud al FQDN

Ahora que tienes el registro DNS configurado para la API de muestra, envíale una solicitud con el FQDN (reemplaza YOUR_PROJECT_ID por el ID de tu proyecto) y la variable de entorno ENDPOINTS_KEY que configuraste antes:

• En Linux o macOS:

  curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"

• En Windows PowerShell:

  (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

Realiza 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.

Realiza una limpieza

• Borra el servicio y la implementación de Kubernetes:

  kubectl delete -f echo.yaml

Consulta Borrar una API y las instancias relacionadas para obtener información acerca de cómo detener los servicios que se usan en este instructivo.

¿Qué sigue?

• Aprende a implementar Endpoints en Google Kubernetes Engine.
• Aprende a compilar una imagen de Docker.
• Comparte tu API con otro desarrollador.
• Obtén más información sobre la autenticación.
• Aprende sobre las opciones del servicio de asistencia de la comunidad.
• Cómo solucionar problemas de implementación en GKE.