En este instructivo, se muestra cómo compilar un servicio personalizado de Cloud Run que transforma un parámetro de entrada de descripción de grafo en un diagrama en el formato de imagen PNG
. Usa Graphviz y se instala como un paquete del sistema en el entorno del contenedor del servicio.
Graphviz se usa a través de utilidades de línea de comandos para entregar solicitudes.
Objetivos
- Escribir y compilar un contenedor personalizado con un Dockerfile
- Escribir, compilar e implementar un servicio de Cloud Run
- Usar la utilidad Graphviz dot para generar diagramas
- Probar el servicio mediante la publicación de un diagrama de sintaxis DOT de la colección o de tu propia creación
Costos
En este documento, usarás 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.
Antes de comenzar
- Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
- Habilita la API de Administrador de Cloud Run
- Instala e inicializa la CLI de gcloud.
- Actualiza los componentes, como se indica a continuación:
gcloud components update
Roles obligatorios
Si quieres obtener los permisos que necesitas para completar el instructivo, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:
-
Editor de Cloud Build (
roles/cloudbuild.builds.editor
) -
Administrador de Cloud Run (
roles/run.admin
) -
Crea cuentas de servicio (
roles/iam.serviceAccountCreator
) -
Usuario de cuenta de servicio (
roles/iam.serviceAccountUser
) -
Consumidor de Service Usage (
roles/serviceusage.serviceUsageConsumer
) -
Administrador de almacenamiento (
roles/storage.admin
)
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.
Configura los valores predeterminados de gcloud
A fin de configurar gcloud con los valores predeterminados para el servicio de Cloud Run, sigue estos pasos:
Configura el proyecto predeterminado:
gcloud config set project PROJECT_ID
Reemplaza PROJECT_ID por el nombre del proyecto que creaste para este instructivo.
Configura gcloud en la región que elegiste:
gcloud config set run/region REGION
Reemplaza REGION por la región de Cloud Run compatible que prefieras.
Ubicaciones de Cloud Run
Cloud Run es regional, lo que significa que la infraestructura que ejecuta los servicios se ubica en una región específica, y Google la administra para que esté disponible de manera redundante en todas las zonas de esa región.
El cumplimiento de los requisitos de latencia, disponibilidad o durabilidad es el factor principal para seleccionar la región en la que se ejecutan los servicios de Cloud Run.
Por lo general, puedes seleccionar la región más cercana a los usuarios, pero debes considerar la ubicación de los otros productos de Google Cloud que usa el servicio de Cloud Run.
Si usas productos de Google Cloud en varias ubicaciones, la latencia y el costo del servicio pueden verse afectados.
Cloud Run está disponible en las siguientes regiones:
Sujetas a los Precios del nivel 1
asia-east1
(Taiwán)asia-northeast1
(Tokio)asia-northeast2
(Osaka)europe-north1
(Finlandia) Bajo nivel de CO2europe-southwest1
(Madrid) Bajo nivel de CO2europe-west1
(Bélgica) Bajo nivel de CO2europe-west4
(Países Bajos) Bajo nivel de CO2europe-west8
(Milán)europe-west9
(París) Bajo nivel de CO2me-west1
(Tel Aviv)us-central1
(Iowa) Bajo nivel de CO2us-east1
(Carolina del Sur)us-east4
(Virginia del Norte)us-east5
(Columbus)us-south1
(Dallas) Bajo nivel de CO2us-west1
(Oregón) Bajo nivel de CO2
Sujetas a los Precios del nivel 2
africa-south1
(Johannesburgo)asia-east2
(Hong Kong)asia-northeast3
(Seúl, Corea del Sur)asia-southeast1
(Singapur)asia-southeast2
(Yakarta)asia-south1
(Bombay, India)asia-south2
Delhi (India)australia-southeast1
(Sídney)australia-southeast2
(Melbourne)europe-central2
(Varsovia, Polonia)europe-west10
(Berlín) Bajo nivel de CO2europe-west12
(Turín)europe-west2
(Londres, Reino Unido) Bajo nivel de CO2europe-west3
(Fráncfort, Alemania) Bajo nivel de CO2europe-west6
(Zúrich, Suiza) Bajo nivel de CO2me-central1
(Doha)me-central2
(Dammam)northamerica-northeast1
(Montreal) Bajo nivel de CO2northamerica-northeast2
(Toronto) Bajo nivel de CO2southamerica-east1
(São Paulo, Brasil) Bajo nivel de CO2southamerica-west1
(Santiago, Chile) Bajo nivel de CO2us-west2
(Los Ángeles)us-west3
(Salt Lake City)us-west4
(Las Vegas)
Si ya creaste un servicio de Cloud Run, puedes ver la región en el panel de Cloud Run en la consola de Google Cloud.
Recupera la muestra de código
A fin de recuperar la muestra de código para su uso, haz lo siguiente:
Clona el repositorio de la app de muestra en tu máquina local:
Node.js
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
De manera opcional, puedes descargar la muestra como un archivo zip y extraerla.
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
De manera opcional, puedes descargar la muestra como un archivo zip y extraerla.
Go
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
De manera opcional, puedes descargar la muestra como un archivo ZIP y extraerla.
Java
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
De manera opcional, puedes descargar la muestra como un archivo ZIP y extraerla.
Ve al directorio que contiene el código de muestra de Cloud Run:
Node.js
cd nodejs-docs-samples/run/system-package/
Python
cd python-docs-samples/run/system-package/
Go
cd golang-samples/run/system_package/
Java
cd java-docs-samples/run/system-package/
Visualiza la arquitectura
La arquitectura básica se ve de la siguiente manera:
.El usuario realiza una solicitud HTTP al servicio de Cloud Run que ejecuta una utilidad de Graphviz para transformar la solicitud en una imagen. Esa imagen se entrega al usuario como la respuesta HTTP.
Comprende el código
Define la configuración del entorno con el Dockerfile
Tu Dockerfile
es específico al lenguaje y al entorno operativo base, como Ubuntu, que usará el servicio.
La guía de inicio rápido de implementación y compilación muestra varios Dockerfiles
que se pueden usar como punto de partida a fin de compilar un Dockerfile
para otros servicios.
Este servicio requiere uno o más paquetes de sistema adicionales que no están disponibles de forma predeterminada.
Abre
Dockerfile
en un editor.Busca una declaración
Dockerfile
RUN
. Esta instrucción permite ejecutar comandos de shell arbitrarios para modificar el entorno. Si elDockerfile
tiene varias etapas, identificadas mediante la búsqueda de varias declaracionesFROM
, se encontrará en la última etapa.Los paquetes específicos necesarios y el mecanismo para instalarlos varían según el sistema operativo que se declare dentro del contenedor.
Para obtener instrucciones sobre el sistema operativo o la imagen base, haz clic en la pestaña correspondiente.
Debian y Ubuntu Alpine Alpine requiere un segundo paquete para la compatibilidad de fuentes.Para determinar el sistema operativo de la imagen de contenedor, verifica el nombre en la declaración
FROM
o en un README asociado con la imagen base. Por ejemplo, si extiendes desdenode
, puedes encontrar documentación y elDockerfile
superior en Docker Hub.Compila la imagen mediante
docker build
de forma local o Cloud Build para probar la personalización.
Administra las solicitudes entrantes
El servicio de muestra usa parámetros de la solicitud HTTP entrante para invocar una llamada del sistema que ejecuta el comando de utilidad dot
apropiado.
En el controlador HTTP que se muestra a continuación, se extrae un parámetro de entrada de descripción de grafo de la variable de la string de consulta dot
.
Las descripciones del grafo pueden incluir caracteres que deben estar codificados como URL para usarlos en una string de consulta.
Node.js
Python
Go
Java
Deberás diferenciar los errores internos del servidor y las entradas de usuario no válidas. En este servicio de ejemplo, se muestra un error interno del servidor para todos los errores de la línea de comandos de dot, a menos que el mensaje de error contenga la string syntax
, que indica un problema de entrada del usuario.
Genera un diagrama
La lógica central de la generación de diagramas usa la herramienta de línea de comandos de dot para procesar el parámetro de entrada de descripción de grafo en un diagrama en el formato de imagen PNG.
Node.js
Python
Go
Java
Diseña un servicio seguro
Las vulnerabilidades de la herramienta de dot
son vulnerabilidades potenciales del servicio web. Puedes mitigar esto mediante el uso de versiones actualizadas del paquete de graphviz
. Para ello, debes compilar la imagen del contenedor con regularidad.
Si extiendes la muestra actual para aceptar las entradas del usuario como parámetros de línea de comandos, debes protegerte contra los ataques de inyección de comandos. Estas son algunas de las formas de evitar los ataques de inyección:
- Asigna entradas a un diccionario de parámetros compatibles.
- Valida entradas coincidentes con un rango de valores seguros conocidos, quizás mediante expresiones regulares.
- Escapa entradas para garantizar que no se evalúe la sintaxis de shell.
Puedes mitigar aún más las posibles vulnerabilidades si implementas el servicio con una cuenta de servicio a la que no se le otorgaron permisos para usar los servicios de Google Cloud, en lugar de usar la cuenta predeterminada, que utiliza los permisos más comunes de usar. Por esta razón, en los pasos de este instructivo, se crea y se utiliza una cuenta de servicio nueva.
Envía el código
Para enviar tu código, compílalo con Cloud Build, súbelo a Artifact Registry y realiza la implementación en Cloud Run:
Crea un Artifact Registry:
gcloud artifacts repositories create REPOSITORY \ --repository-format docker \ --location REGION
Reemplaza lo siguiente:
- REPOSITORY por un nombre único para el repositorio. Para la ubicación de cada repositorio en un proyecto, los nombres de los repositorios deben ser únicos.
- REGION por la región de Google Cloud que se usará para el repositorio de Artifact Registry.
Ejecuta el siguiente comando para compilar el contenedor y publicar en Artifact Registry.
Node.js
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz
En el que PROJECT_ID es el ID del proyecto de Google Cloud y
graphviz
es el nombre que deseas darle a tu servicio.Si la operación se completa de manera correcta, verás un mensaje de ÉXITO con el ID, la hora de creación y el nombre de la imagen. La imagen se almacena en Artifact Registry y puede volver a usarse si así se desea.
Python
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz
En el que PROJECT_ID es el ID del proyecto de Google Cloud y
graphviz
es el nombre que deseas darle a tu servicio.Si la operación se completa de manera correcta, verás un mensaje de ÉXITO con el ID, la hora de creación y el nombre de la imagen. La imagen se almacena en Artifact Registry y puede volver a usarse si así se desea.
Go
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz
En el que PROJECT_ID es el ID del proyecto de Google Cloud y
graphviz
es el nombre que deseas darle a tu servicio.Si la operación se completa de manera correcta, verás un mensaje de ÉXITO con el ID, la hora de creación y el nombre de la imagen. La imagen se almacena en Artifact Registry y puede volver a usarse si así se desea.
Java
En esta muestra, se usa Jib para compilar imágenes de Docker mediante herramientas de Java comunes. Jib optimiza las compilaciones de contenedores sin la necesidad de tener un Dockerfile o tener Docker instalado. Obtén más información sobre la compilación de contenedores de Java con Jib.Mediante Dockerfile, configura y compila una imagen base con los paquetes de sistema instalados a fin de anular la imagen base predeterminada de Jib:
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz-base
En el ejemplo anterior, PROJECT_ID es el ID del proyecto de Google Cloud.
Usa el auxiliar de credenciales de gcloud para autorizar a Docker a que envíe contenido a tu Artefact Registry.
gcloud auth configure-docker
Compila el contenedor final con Jib y publica en Artifact Registry:
mvn compile jib:build \ -Dimage=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz \ -Djib.from.image=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz-base
En el ejemplo anterior, PROJECT_ID es el ID del proyecto de Google Cloud.
Realiza la implementación con lo siguiente:
gcloud
- Crea una cuenta de servicio nueva El código, incluidos los paquetes del sistema que usa, solo puede utilizar los servicios de Google Cloud que se otorgaron a esta cuenta de servicio.
En el ejemplo anterior, SA_NAME es un nombre que le asignas a esta cuenta de servicio. Si hay un error o una vulnerabilidad en tu código, este no podrá acceder a ninguno de los demás recursos de tu proyecto de Google Cloud.gcloud iam service-accounts create SA_NAME
- Implementa el código y especifica la cuenta de servicio.
En el ejemplo anterior, PROJECT_ID es el ID del proyecto de Google Cloud, SA_NAME es el nombre de la cuenta de servicio que creaste,gcloud run deploy graphviz-web --service-account SA_NAME@PROJECT_ID.iam.gserviceaccount.com --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz
graphviz
es el nombre del contenedor anterior ygraphviz-web
es el nombre del servicio. RespondeY
para la solicitud “allow unauthenticated”. Consulta Administra el acceso para obtener más detalles sobre la autenticación basada en IAM. - Espera a que finalice la implementación. Esto puede tomar alrededor de medio minuto. Si la operación se completa de forma correcta, la línea de comandos mostrará la URL de servicio.
Terraform
Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform.
El siguiente código de Terraform crea un servicio de Cloud Run.
Reemplaza IMAGE_URL por una referencia a la imagen de contenedor, como
us-docker.pkg.dev/cloudrun/container/hello:latest
. Si usas Artifact Registry, el repositorio REPO_NAME debe estar creado. La URL tiene el formatoLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
.El siguiente código de Terraform hace que el servicio de Cloud Run sea público.
- Crea una cuenta de servicio nueva El código, incluidos los paquetes del sistema que usa, solo puede utilizar los servicios de Google Cloud que se otorgaron a esta cuenta de servicio.
Si deseas implementar una actualización de código en el servicio, repite los pasos anteriores. Cada implementación en un servicio crea una revisión nueva y comienza a entregar tráfico de forma automática cuando está lista.
Realiza una prueba
Para probar el servicio, envía solicitudes HTTP POST
con descripciones de sintaxis DOT en la carga útil de la solicitud.
Envía una solicitud HTTP al servicio.
Copia la URL en la barra de URL de tu navegador y actualiza
[SERVICE_DOMAIN]
:https://SERVICE_DOMAIN/diagram.png?dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }
Puedes incorporar el diagrama en una página web:
<img src="https://SERVICE_DOMAIN/diagram.png?dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" />
Abre el archivo
diagram.png
resultante en cualquier aplicación que admita archivosPNG
, como Chrome.Se verá de la siguiente manera:
Puedes explorar una pequeña colección de descripciones de diagramas listas para usar.
- Copia el contenido del archivo
.dot
seleccionado. Envía una solicitud HTTP al servicio.
Copia la URL en la barra de URL de tu navegador
https://SERVICE_DOMAIN/diagram.png?dot=SELECTED DOTFILE CONTENTS
Realiza una limpieza
Si creaste un proyecto nuevo para este instructivo, bórralo. Si usaste un proyecto existente y deseas conservarlo sin los cambios que se agregaron en este instructivo, borra los recursos creados para el instructivo.
Borra el proyecto
La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.
Para borrar el proyecto, sigue estos pasos:
- En la consola de Google Cloud, ve a la página Administrar recursos.
- En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
- En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.
Borra los recursos del instructivo
Usa este comando para borrar el servicio de Cloud Run que implementaste en este instructivo:
gcloud run services delete SERVICE-NAME
En el ejemplo anterior, SERVICE-NAME es el nombre del servicio que elegiste.
También puedes borrar los servicios de Cloud Run desde la consola de Google Cloud.
Quita la configuración de región predeterminada de gcloud que agregaste durante la configuración en el instructivo:
gcloud config unset run/region
Quita la configuración del proyecto:
gcloud config unset project
Borra otros recursos de Google Cloud que creaste en este instructivo:
Borra la imagen del contenedor llamada
REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz
de Artifact Registry.Borra la cuenta de servicio SA_NAME.
gcloud iam service-accounts delete SA_NAME@PROJECT_ID.iam.gserviceaccount.com
¿Qué sigue?
- Experimenta con tu app de graphviz:
- Agrega compatibilidad con otras utilidades de graphviz que aplican diferentes algoritmos a la generación de diagramas.
- Guarda diagramas en Cloud Storage. ¿Deseas guardar la imagen o la sintaxis de DOT?
- Implementa la protección contra el abuso de contenido con la API de Cloud Natural Language.
- Consulta otro ejemplo de un paquete de sistema en Instructivo: Procesamiento de imágenes con Cloud Run.
- Explora arquitecturas de referencia, diagramas y prácticas recomendadas sobre Google Cloud. Consulta nuestro Cloud Architecture Center.