Usa paquetes del sistema

---

En este instructivo, se muestra cómo compilar un servicio personalizado de Knative serving que transforma un parámetro de entrada de descripción de grafo en un diagrama en el formato de imagen PNG. Usa Graphviz, que 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 Knative serving
• 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:

• Cloud Build
• Container Registry
• Knative serving

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 califiquen para obtener una prueba gratuita.

Precaución: Container Registry está obsoleto y se programó para el cierre. Las organizaciones que no usaron Container Registry antes del 8 de enero de 2024 tendrán nuevos repositorios de gcr.io alojados en Artifact Registry de forma predeterminada. A partir del 15 de mayo de 2024, los proyectos de Google Cloud sin uso anterior de Container Registry solo admitirán el hosting y la administración de imágenes para el dominio gcr.io en Artifact Registry.

Container Registry está programado para cerrarse el 18 de marzo de 2025. Para obtener detalles sobre la baja, consulta Baja de Container Registry.

Antes de comenzar

• En este instructivo, se supone que tienes Knative serving instalado y configurado en tu clúster.
• Asegúrate de que el entorno de la línea de comandos esté configurado y que las herramientas estén actualizadas:
  • Clústeres de GKE en Google Cloud.
  • Clústeres de GKE fuera de Google Cloud

Recupera la muestra de código

A fin de recuperar la muestra de código para su uso, haz lo siguiente:

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

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

   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:

Para obtener la fuente del diagrama, consulta la Descripción DOT

.

El usuario realiza una solicitud HTTP al servicio de Knative serving 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

Punto clave: Usa tu Dockerfile para personalizar tu entorno con bibliotecas, utilidades, variables de entorno, archivos de configuración y procesos de inicio. Este es el enfoque basado en contenedores para la “configuración del servidor”.

Tu Dockerfile es específico al lenguaje y al entorno operativo base, como Ubuntu, que usará el servicio.

Nota: La guía de inicio rápido, aunque es para Knative serving, muestra varios Dockerfiles que se pueden usar como punto de partida para compilar un Dockerfile para otros servicios.

Este servicio requiere uno o más paquetes del sistema adicionales que no están disponibles de forma predeterminada.

1. Abre Dockerfile en un editor.

2. Busca una declaración Dockerfile RUN. Esta instrucción permite ejecutar comandos de shell arbitrarios para modificar el entorno. Si el Dockerfile tiene varias etapas, identificadas mediante la búsqueda de varias declaraciones FROM, 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

   RUN apt-get update -y && apt-get install -y \
     graphviz \
     && apt-get clean

   Alpine

   Alpine requiere un segundo paquete para la compatibilidad de fuentes.

   RUN apk --no-cache add graphviz ttf-ubuntu-font-family

   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 desde node, puedes encontrar documentación y el Dockerfile superior en Docker Hub.

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

app.get('/diagram.png', (req, res) => {
  try {
    const image = createDiagram(req.query.dot);
    res.setHeader('Content-Type', 'image/png');
    res.setHeader('Content-Length', image.length);
    res.setHeader('Cache-Control', 'public, max-age=86400');
    res.send(image);
  } catch (err) {
    console.error(`error: ${err.message}`);
    const errDetails = (err.stderr || err.message).toString();
    if (errDetails.includes('syntax')) {
      res.status(400).send(`Bad Request: ${err.message}`);
    } else {
      res.status(500).send('Internal Server Error');
    }
  }
});

Python

@app.route("/diagram.png", methods=["GET"])
def index():
    """Takes an HTTP GET request with query param dot and
    returns a png with the rendered DOT diagram in a HTTP response.
    """
    try:
        image = create_diagram(request.args.get("dot"))
        response = make_response(image)
        response.headers.set("Content-Type", "image/png")
        return response

    except Exception as e:
        print(f"error: {e}")

        # If no graphviz definition or bad graphviz def, return 400
        if "syntax" in str(e):
            return f"Bad Request: {e}", 400

        return "Internal Server Error", 500

Go

// diagramHandler renders a diagram using HTTP request parameters and the dot command.
func diagramHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodGet {
		log.Printf("method not allowed: %s", r.Method)
		http.Error(w, fmt.Sprintf("HTTP Method %s Not Allowed", r.Method), http.StatusMethodNotAllowed)
		return
	}

	q := r.URL.Query()
	dot := q.Get("dot")
	if dot == "" {
		log.Print("no graphviz definition provided")
		http.Error(w, "Bad Request", http.StatusBadRequest)
		return
	}

	// Cache header must be set before writing a response.
	w.Header().Set("Cache-Control", "public, max-age=86400")

	input := strings.NewReader(dot)
	if err := createDiagram(w, input); err != nil {
		log.Printf("createDiagram: %v", err)
		// Do not cache error responses.
		w.Header().Del("Cache-Control")
		if strings.Contains(err.Error(), "syntax") {
			http.Error(w, "Bad Request: DOT syntax error", http.StatusBadRequest)
		} else {
			http.Error(w, "Internal Server Error", http.StatusInternalServerError)
		}
	}
}

Java

get(
    "/diagram.png",
    (req, res) -> {
      InputStream image = null;
      try {
        String dot = req.queryParams("dot");
        image = createDiagram(dot);
        res.header("Content-Type", "image/png");
        res.header("Content-Length", Integer.toString(image.available()));
        res.header("Cache-Control", "public, max-age=86400");
      } catch (Exception e) {
        if (e.getMessage().contains("syntax")) {
          res.status(400);
          return String.format("Bad Request: %s", e.getMessage());
        } else {
          res.status(500);
          return "Internal Server Error";
        }
      }
      return image;
    });

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

// Generate a diagram based on a graphviz DOT diagram description.
const createDiagram = dot => {
  if (!dot) {
    throw new Error('syntax: no graphviz definition provided');
  }

  // Adds a watermark to the dot graphic.
  const dotFlags = [
    '-Glabel="Made on Cloud Run"',
    '-Gfontsize=10',
    '-Glabeljust=right',
    '-Glabelloc=bottom',
    '-Gfontcolor=gray',
  ].join(' ');

  const image = execSync(`/usr/bin/dot ${dotFlags} -Tpng`, {
    input: dot,
  });
  return image;
};

Python

def create_diagram(dot):
    """Generates a diagram based on a graphviz DOT diagram description.

    Args:
        dot: diagram description in graphviz DOT syntax

    Returns:
        A diagram in the PNG image format.
    """
    if not dot:
        raise Exception("syntax: no graphviz definition provided")

    dot_args = [  # These args add a watermark to the dot graphic.
        "-Glabel=Made on Cloud Run",
        "-Gfontsize=10",
        "-Glabeljust=right",
        "-Glabelloc=bottom",
        "-Gfontcolor=gray",
        "-Tpng",
    ]

    # Uses local `dot` binary from Graphviz:
    # https://graphviz.gitlab.io
    image = subprocess.run(
        ["dot"] + dot_args, input=dot.encode("utf-8"), stdout=subprocess.PIPE
    ).stdout

    if not image:
        raise Exception("syntax: bad graphviz definition provided")
    return image

Go

// createDiagram generates a diagram image from the provided io.Reader written to the io.Writer.
func createDiagram(w io.Writer, r io.Reader) error {
	stderr := new(bytes.Buffer)
	args := []string{
		"-Glabel=Made on Cloud Run",
		"-Gfontsize=10",
		"-Glabeljust=right",
		"-Glabelloc=bottom",
		"-Gfontcolor=gray",
		"-Tpng",
	}
	cmd := exec.Command("/usr/bin/dot", args...)
	cmd.Stdin = r
	cmd.Stdout = w
	cmd.Stderr = stderr

	if err := cmd.Run(); err != nil {
		return fmt.Errorf("exec(%s) failed (%w): %s", cmd.Path, err, stderr.String())
	}

	return nil
}

Java

// Generate a diagram based on a graphviz DOT diagram description.
public static InputStream createDiagram(String dot) {
  if (dot == null || dot.isEmpty()) {
    throw new NullPointerException("syntax: no graphviz definition provided");
  }
  // Adds a watermark to the dot graphic.
  List<String> args = new ArrayList<>();
  args.add("/usr/bin/dot");
  args.add("-Glabel=\"Made on Cloud Run\"");
  args.add("-Gfontsize=10");
  args.add("-Glabeljust=right");
  args.add("-Glabelloc=bottom");
  args.add("-Gfontcolor=gray");
  args.add("-Tpng");

  StringBuilder output = new StringBuilder();
  InputStream stdout = null;
  try {
    ProcessBuilder pb = new ProcessBuilder(args);
    Process process = pb.start();
    OutputStream stdin = process.getOutputStream();
    stdout = process.getInputStream();
    // The Graphviz dot program reads from stdin.
    Writer writer = new OutputStreamWriter(stdin, "UTF-8");
    writer.write(dot);
    writer.close();
    process.waitFor();
  } catch (Exception e) {
    System.out.println(e);
  }
  return stdout;
}

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.

Envía el código

Para enviar tu código, compílalo con Cloud Build, súbelo a Container Registry y realiza la implementación en Knative serving:

1. Ejecuta el siguiente comando para compilar el contenedor y publicar en Container Registry.

   Node.js

   gcloud builds submit --tag gcr.io/PROJECT_ID/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 Container Registry y puede volver a usarse si así se desea.

   Python

   gcloud builds submit --tag gcr.io/PROJECT_ID/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 Container Registry y puede volver a usarse si así se desea.

   Go

   gcloud builds submit --tag gcr.io/PROJECT_ID/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 Container 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.

   1. Mediante Dockerfile, configura y compila una imagen base con los paquetes de sistema instalados a fin de anular la imagen base predeterminada de Jib:

      # Use the Official eclipse-temurin image for a lean production stage of our multi-stage build.
      # https://hub.docker.com/_/eclipse-temurin/
      FROM eclipse-temurin:17.0.12_7-jre
      
      RUN apt-get update -y && apt-get install -y \
        graphviz \
        && apt-get clean

      gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz-base

      En el ejemplo anterior, PROJECT_ID es el ID del proyecto de Google Cloud.

   2. Compila el contenedor final con Jib y publica en Container Registry:

      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>jib-maven-plugin</artifactId>
        <version>3.4.0</version>
        <configuration>
          <from>
            <image>gcr.io/PROJECT_ID/graphviz-base</image>
          </from>
          <to>
            <image>gcr.io/PROJECT_ID/graphviz</image>
          </to>
        </configuration>
      </plugin>

      mvn compile jib:build \
       -Dimage=gcr.io/PROJECT_ID/graphviz \
       -Djib.from.image=gcr.io/PROJECT_ID/graphviz-base

      En el ejemplo anterior, PROJECT_ID es el ID del proyecto de Google Cloud.

2. Realiza la implementación con el siguiente comando:

   gcloud run deploy graphviz-web --create-if-missing --image gcr.io/PROJECT_ID/graphviz

   En el ejemplo anterior, PROJECT_ID es el ID de tu proyecto de Google Cloud, graphviz es el nombre del contenedor anterior y graphviz-web es el nombre del servicio.

   Espera hasta que finalice la implementación; esto puede tomar alrededor de medio minuto.

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

1. Envía una solicitud HTTP al servicio.

   Puedes incorporar el diagrama en una página web:

   1. A fin de obtener la IP externa para el balanceador de cargas, ejecuta el siguiente comando:

      kubectl get svc istio-ingressgateway -n ASM-INGRESS-NAMESPACE
      

      Reemplaza ASM-INGRESS-NAMESPACE por el espacio de nombres en el que se encuentra tu entrada de Cloud Service Mesh. Especifica istio-system si instalaste Cloud Service Mesh usando su configuración predeterminada.

      El resultado es similar al siguiente:

      NAME                   TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
      istio-ingressgateway   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP
      

      El valor EXTERNAL-IP es la dirección IP externa del balanceador de cargas.

   2. Ejecuta un comando curl mediante esta dirección EXTERNAL-IP en la URL. No incluyas el protocolo (p. ej.: http://) en SERVICE_DOMAIN.

      curl -G -H "Host: SERVICE_DOMAIN" http://EXTERNAL-IP/diagram.png \
         --data-urlencode "dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" \
         > diagram.png

2. Abre el archivo diagram.png resultante en cualquier aplicación que admita archivos PNG, como Chrome.

   Se verá de la siguiente manera:

   

   Fuente: Descripción DOT

Puedes explorar una pequeña colección de descripciones de diagramas listas para usar.

1. Copia el contenido del archivo .dot seleccionado.

2. Pégalo en un comando curl:

   curl -G -H "Host: SERVICE_DOMAIN" http://EXTERNAL-IP/diagram.png \
   --data-urlencode "dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" \
   > diagram.png

Limpia

Puedes borrar los recursos que creaste para este instructivo a fin de evitar que se generen costos.

Borra los recursos del instructivo

1. Borra el servicio de Knative serving 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 Knative serving desde la consola de Google Cloud:

   Ir a Knative serving

2. Quita las opciones de configuración predeterminadas de gcloud que agregaste durante la configuración del instructivo.

    gcloud config unset run/platform
    gcloud config unset run/cluster
    gcloud config unset run/cluster_location
   

3. Quita la configuración del proyecto:

    gcloud config unset project
   

4. Borra otros recursos de Google Cloud que creaste en este instructivo:

   • Borra la imagen del contenedor llamada gcr.io/<var>PROJECT_ID</var>/graphviz de Container Registry.
   • Si creaste un clúster para este instructivo, bórralo.

¿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.
• Explora arquitecturas de referencia, diagramas y prácticas recomendadas sobre Google Cloud. Consulta nuestro Cloud Architecture Center.