Tutorial sobre el uso de paquetes del sistema

En este tutorial se muestra cómo crear un servicio Cloud Run personalizado que transforma un parámetro de entrada de descripción de un gráfico en un diagrama en formato de imagen PNG. Usa Graphviz y se instala como paquete del sistema en el entorno de contenedor del servicio. Graphviz se usa a través de utilidades de línea de comandos para atender solicitudes.

Configurar los valores predeterminados de gcloud

Para configurar gcloud con los valores predeterminados de tu servicio de Cloud Run, sigue estos pasos:

  1. Configura tu proyecto predeterminado:

    gcloud config set project PROJECT_ID

    Sustituye PROJECT_ID por el nombre del proyecto que has creado para este tutorial.

  2. Configura gcloud para la región que hayas elegido:

    gcloud config set run/region REGION

    Sustituye REGION por la región de Cloud Run compatible que quieras.

Ubicaciones de Cloud Run

Cloud Run es regional, lo que significa que la infraestructura que ejecuta tus servicios de Cloud Run se encuentra en una región específica y Google la gestiona para que esté disponible de forma redundante en todas las zonas de esa región.

Cumplir tus requisitos de latencia, disponibilidad o durabilidad son factores primordiales para seleccionar la región en la que se ejecutan tus servicios de Cloud Run. Por lo general, puedes seleccionar la región más cercana a tus usuarios, pero debes tener en cuenta la ubicación de los otros Google Cloudproductos que utiliza tu servicio de Cloud Run. Usar Google Cloud productos juntos en varias ubicaciones puede afectar a la latencia y al coste de tu servicio.

Cloud Run está disponible en las siguientes regiones:

Con sujeción a los precios del nivel 1

  • asia-east1 (Taiwán)
  • asia-northeast1 (Tokio)
  • asia-northeast2 (Osaka)
  • asia-south1 (Bombay, la India)
  • europe-north1 (Finlandia) icono de una hoja CO2 bajo
  • europe-north2 (Estocolmo) icono de una hoja CO2 bajo
  • europe-southwest1 (Madrid) icono de una hoja CO2 bajo
  • europe-west1 (Bélgica) icono de una hoja CO2 bajo
  • europe-west4 (Países Bajos) icono de una hoja CO2 bajo
  • europe-west8 (Milán)
  • europe-west9 (París) icono de una hoja CO2 bajo
  • me-west1 (Tel Aviv)
  • northamerica-south1 (México)
  • us-central1 (Iowa) icono de una hoja CO2 bajo
  • us-east1 (Carolina del Sur)
  • us-east4 (Norte de Virginia)
  • us-east5 (Columbus)
  • us-south1 (Dallas) icono de una hoja CO2 bajo
  • us-west1 (Oregón) icono de una hoja CO2 bajo

Con sujeción 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-south2 (Delhi, la India)
  • australia-southeast1 (Sídney)
  • australia-southeast2 (Melbourne)
  • europe-central2 Varsovia (Polonia)
  • europe-west10 (Berlín)
  • europe-west12 (Turín)
  • europe-west2 (Londres, Reino Unido) icono de una hoja CO2 bajo
  • europe-west3 (Fráncfort, Alemania)
  • europe-west6 (Zúrich, Suiza) icono de una hoja Bajas emisiones de CO2
  • me-central1 (Doha)
  • me-central2 (Dammam)
  • northamerica-northeast1 (Montreal) icono de una hoja CO2 bajo
  • northamerica-northeast2 (Toronto) icono de una hoja CO2 bajo
  • southamerica-east1 (São Paulo, Brasil) icono de una hoja CO2 bajo
  • southamerica-west1 (Santiago, Chile) icono de una hoja CO2 bajo
  • us-west2 (Los Ángeles)
  • us-west3 (Salt Lake City)
  • us-west4 (Las Vegas)

Si ya has creado un servicio de Cloud Run, puedes ver la región en el panel de control de Cloud Run de la Google Cloud consola.

Obtener el código de ejemplo

Para obtener el código de muestra que vas a usar, sigue estos pasos:

  1. Clona el repositorio de aplicaciones de muestra en la máquina local:

    Node.js 

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

    También puedes descargar el ejemplo como un archivo ZIP y extraerlo.

    Python 

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

    También puedes descargar el ejemplo como un archivo ZIP y extraerlo.

    Go 

    git clone https://github.com/GoogleCloudPlatform/golang-samples.git

    También puedes descargar el ejemplo como un archivo ZIP y extraerlo.

    Java 

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

    También puedes descargar el ejemplo como un archivo ZIP y extraerlo.

  2. Cambia al directorio que contiene el código de ejemplo 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/

Visualizar la arquitectura

La arquitectura básica es la siguiente:

Diagrama que muestra el flujo de solicitudes desde el usuario hasta el servicio web y la utilidad DOT de Graphviz.
Para ver la fuente del diagrama, consulta la descripción de DOT

El usuario envía una solicitud HTTP al servicio de Cloud Run, que ejecuta una utilidad de Graphviz para transformar la solicitud en una imagen. Esa imagen se envía al usuario como respuesta HTTP.

Información sobre el código

Definir la configuración del entorno con Dockerfile

Tu Dockerfile es específico del idioma y del entorno operativo base, como Ubuntu, que usará tu servicio.

En la guía de inicio rápido de compilación e implementación se muestran varios Dockerfiles que se pueden usar como punto de partida para crear un Dockerfile para otros servicios.

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

  1. Abre el Dockerfile en un editor.

  2. Busca un extracto de Dockerfile RUN. Esta instrucción permite ejecutar comandos de shell arbitrarios para modificar el entorno. Si el Dockerfile tiene varias fases, identificadas por varias instrucciones FROM, se encontrará en la última fase.

    Los paquetes específicos necesarios y el mecanismo para instalarlos varían en función del sistema operativo declarado en el contenedor.

    Para obtener instrucciones sobre tu sistema operativo o imagen base, haz clic en la pestaña correspondiente.

    Debian/Ubuntu
    RUN apt-get update -y && apt-get install -y \
  graphviz \
  && apt-get clean
    Alpine
    Alpine requiere un segundo paquete para admitir fuentes. 
    RUN apk --no-cache add graphviz

    Para determinar el sistema operativo de tu imagen de contenedor, consulta el nombre en la instrucción FROM o en un archivo README asociado a tu imagen base. Por ejemplo, si amplías desde node, puedes encontrar documentación y el elemento principal Dockerfile en Docker Hub.

  3. Para probar la personalización, compila la imagen con docker build localmente o con Cloud Build.

Gestionar solicitudes entrantes

El servicio de ejemplo usa parámetros de la solicitud HTTP entrante para invocar una llamada al sistema que ejecuta el comando de utilidad dot adecuado.

En el controlador HTTP que se muestra a continuación, se extrae un parámetro de entrada de descripción de gráfico de la variable de cadena de consulta dot.

Las descripciones de los gráficos pueden incluir caracteres que deben codificarse como URL para usarse en una cadena 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 entre los errores de servidor internos y las entradas de usuario no válidas. Este servicio de ejemplo devuelve un error de servidor interno para todos los errores de línea de comandos de punto, a menos que el mensaje de error contenga la cadena syntax, que indica un problema de entrada del usuario.

Generar un diagrama

La lógica principal de la generación de diagramas usa la herramienta de línea de comandos dot para procesar el parámetro de entrada de descripción del gráfico y convertirlo en un diagrama en 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ñar un servicio seguro

Las vulnerabilidades de la herramienta dot son vulnerabilidades potenciales del servicio web. Para mitigar este problema, puedes usar versiones actualizadas del paquete graphviz recompilando la imagen del contenedor de forma periódica.

Si amplías la muestra actual para que acepte datos introducidos por el 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:

  • Asignar entradas a un diccionario de parámetros admitidos
  • Validar que las entradas coincidan con un intervalo de valores seguros conocidos, quizás mediante expresiones regulares
  • Escapar las entradas para asegurarse de que no se evalúe la sintaxis de shell

Puedes reducir aún más las posibles vulnerabilidades implementando el servicio con una cuenta de servicio a la que no se le hayan concedido permisos para usar los servicios de Google Cloud, en lugar de usar la cuenta predeterminada, que tiene permisos de uso común. Por este motivo, en los pasos de este tutorial se crea y se usa una cuenta de servicio.

Envío del código

Para enviar tu código, compílalo con Cloud Build, súbelo a Artifact Registry y despliégalo en Cloud Run:

  1. Crea un Artifact Registry:

    gcloud artifacts repositories create REPOSITORY \
    --repository-format docker \
    --location REGION

    Sustituye:

    • REPOSITORY: un nombre único para el repositorio. Los nombres de los repositorios deben ser únicos en cada ubicación de repositorio de un proyecto.
    • REGION: la Google Cloud región que se va a usar en el repositorio de Artifact Registry.

  2. Ejecuta el siguiente comando para compilar el contenedor y publicarlo en Artifact Registry.

    Node.js 

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz

    Donde PROJECT_ID es el ID de tu proyecto Google Cloud y graphviz es el nombre que quieres dar a tu servicio.

    Si la operación se realiza correctamente, verás un mensaje de ÉXITO que contiene el ID, la hora de creación y el nombre de la imagen. La imagen se almacena en Artifact Registry y se puede volver a usar si quieres.

    Python 

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz

    Donde PROJECT_ID es el ID de tu proyecto Google Cloud y graphviz es el nombre que quieres dar a tu servicio.

    Si la operación se realiza correctamente, verás un mensaje de ÉXITO que contiene el ID, la hora de creación y el nombre de la imagen. La imagen se almacena en Artifact Registry y se puede reutilizar si se quiere.

    Go 

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz

    Donde PROJECT_ID es el ID de tu proyecto Google Cloud y graphviz es el nombre que quieres dar a tu servicio.

    Si la operación se realiza correctamente, verás un mensaje de ÉXITO que contiene el ID, la hora de creación y el nombre de la imagen. La imagen se almacena en Artifact Registry y se puede reutilizar si se quiere.

    Java

    En este ejemplo se usa Jib para crear imágenes de Docker con herramientas comunes de Java. Jib optimiza las compilaciones de contenedores sin necesidad de usar un Dockerfile ni de tener Docker instalado. Más información sobre cómo crear contenedores Java con Jib

    1. Con el Dockerfile, configura y compila una imagen base con los paquetes del sistema instalados para 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.16_8-jre

RUN apt-get update -y && apt-get install -y \
  graphviz \
  && apt-get clean
       
      gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz-base

      Donde PROJECT_ID es el ID de tu proyecto Google Cloud .

    2. Usa el asistente de credenciales de gcloud para autorizar a Docker a enviar contenido a tu Artifact Registry. 

      gcloud auth configure-docker

    3. Crea el contenedor final con Jib y publícalo en Artifact 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=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz \
 -Djib.from.image=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz-base

      Donde PROJECT_ID es el ID de tu proyecto Google Cloud .

  3. Implementa con lo siguiente:

    gcloud

    1. Crear una nueva cuenta de servicio. Tu código, incluidos los paquetes del sistema que utilice, solo puede usar losGoogle Cloud servicios a los que se haya concedido acceso a esta cuenta de servicio. 
      gcloud iam service-accounts create SA_NAME
       Donde SA_NAME es el nombre que le das a esta cuenta de servicio. Si hay un error o una vulnerabilidad en tu código, este no podrá acceder a ninguno de los recursos de tus otros proyectos. Google Cloud
    2. Implementa el código y especifica la cuenta de servicio. 
      gcloud run deploy graphviz-web --service-account SA_NAME@PROJECT_ID.iam.gserviceaccount.com  --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz
       Donde PROJECT_ID es el ID de tu proyecto, SA_NAME es el nombre de la cuenta de servicio que has creado, graphviz es el nombre del contenedor de arriba y graphviz-web es el nombre del servicio. Google Cloud Responde Y a la petición "allow unauthenticated" (permitir sin autenticar). Consulta Gestionar el acceso para obtener más información sobre la autenticación basada en IAM.
    3. Espera a que finalice la implementación. Este proceso puede tardar aproximadamente medio minuto. Si la acción se realiza correctamente, la línea de comandos mostrará la URL del servicio.

    Terraform

    Para saber cómo aplicar o quitar una configuración de Terraform, consulta Comandos básicos de Terraform.

    El siguiente código de Terraform crea un servicio de Cloud Run.

    resource "google_service_account" "graphviz" {
  account_id   = "graphviz"
  display_name = "GraphViz Tutorial Service Account"
}

resource "google_cloud_run_v2_service" "default" {
  name     = "graphviz-example"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # Replace with the URL of your graphviz image
      #   gcr.io/<YOUR_GCP_PROJECT_ID>/graphviz
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }

    service_account = google_service_account.graphviz.email
  }
}

    Sustituye IMAGE_URL por una referencia a la imagen de contenedor. Por ejemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME ya debe estar creado. La URL sigue el formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

    El siguiente código de Terraform hace que tu servicio de Cloud Run sea público.

    # Make Cloud Run service publicly accessible
resource "google_cloud_run_service_iam_member" "allow_unauthenticated" {
  service  = google_cloud_run_v2_service.default.name
  location = google_cloud_run_v2_service.default.location
  role     = "roles/run.invoker"
  member   = "allUsers"
}

  4. Si quieres implementar una actualización de código en el servicio, repite los pasos anteriores. Cada despliegue en un servicio crea una nueva revisión y empieza a servir tráfico automáticamente cuando está listo.

Pruébalo

Prueba tu servicio enviando solicitudes HTTP POST con descripciones de sintaxis DOT en la carga útil de la solicitud.

  1. Envía una solicitud HTTP a tu servicio.

    Copia la URL en la barra de direcciones del navegador y actualiza [SERVICE_DOMAIN]:

    https://SERVICE_DOMAIN/diagram.png?dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }

    Puedes insertar el diagrama en una página web:

    <img src="https://SERVICE_DOMAIN/diagram.png?dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" />

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

    Debería tener este aspecto:

    Diagrama que muestra el flujo de fases de &quot;Codificar&quot;, &quot;Compilar&quot;, &quot;Implementar&quot; y &quot;Ejecutar&quot;.
    Fuente: Descripción de DoT

Puedes consultar una pequeña colección de descripciones de diagramas prediseñadas.

  1. Copia el contenido del archivo .dot seleccionado.

  2. Envía una solicitud HTTP a tu servicio.

    Copia la URL en la barra de direcciones del navegador.

    https://SERVICE_DOMAIN/diagram.png?dot=SELECTED DOTFILE CONTENTS