使用系统软件包

---

本教程介绍如何构建自定义 Cloud Run 服务，以将图表说明输入参数转换为 PNG 图片格式的图表。本教程使用已作为系统软件包安装在服务容器环境中的 Graphviz。您可以通过命令行实用程序使用 Graphviz 来处理请求。

目标

• 使用 Dockerfile 编写并构建一个自定义容器
• 编写、构建和部署 Cloud Run for Anthos 服务
• 使用 Graphviz dot 实用程序生成图表
• 通过使用 DOT 语法发布集合中的图表或您自己创建的图表来测试服务

费用

在本文档中，您将使用 Google Cloud 的以下收费组件：

• Cloud Build
• Container Registry
• Cloud Run for Anthos

您可使用价格计算器根据您的预计使用情况来估算费用。 Google Cloud 新用户可能有资格申请免费试用。

准备工作

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

   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

2. Make sure that billing is enabled for your Google Cloud project.

3. 启用 Cloud Run for Anthos API
4. 安装并初始化 gcloud CLI。
5. 安装 kubectl 组件：

   gcloud components install kubectl

6. 更新组件：

   gcloud components update

7. 安装 curl 以试用该服务
8. 按照设置 Cloud Run for Anthos 中的说明创建一个新集群。

设置 gcloud 默认值

如需为您的 Cloud Run for Anthos 服务配置 gcloud 默认值，请执行以下操作：

1. 设置默认项目：

   gcloud config set project PROJECT_ID

   将 PROJECT_ID 替换为您在本教程中使用的项目名称。

2. 为您的集群配置 gcloud：

   gcloud config set run/platform gke
   gcloud config set run/cluster CLUSTER-NAME
   gcloud config set run/cluster_location REGION

   您需要将其中的：

   • 将 CLUSTER-NAME 替换为您使用的集群名称。
   • 将 REGION 替换为您选择的受支持的集群位置。

检索代码示例

如需检索可用的代码示例，请执行以下操作：

1. 将示例应用代码库克隆到本地机器：

   Node.js

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

   或者，您也可以下载该示例的 zip 文件并将其解压缩。

   Python

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

   或者，您也可以下载该示例的 zip 文件并将其解压缩。

   Go

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

   或者，您也可以下载该示例的 zip 文件并将其解压缩。

   Java

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

   或者，您也可以下载该示例的 zip 文件并将其解压缩。

2. 切换到包含 Cloud Run for Anthos 示例代码的目录：

   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/

直观呈现架构

基本架构如下所示：

如需了解图表来源，请参阅 DOT 说明

用户向 Cloud Run for Anthos 服务发出 HTTP 请求，然后该服务执行 Graphviz 实用程序来将请求转换为图片，并将得到的图片以 HTTP 响应形式传递给用户。

了解代码

使用 Dockerfile 定义您的环境配置

要点：在 Dockerfile 中，利用库、实用程序、环境变量、配置文件和启动流程自定义您的环境。这是一种容器化方法，适用于“服务器配置”。

您的 Dockerfile 取决于服务将使用的语言和基础运营环境，例如 Ubuntu。

注意：尽管该快速入门适用于 Cloud Run for Anthos，但确实显示了各种 Dockerfiles，您可以此为起点为其他服务构建 Dockerfile。

此服务还需要一个或多个其他系统软件包，但这些软件包不会默认提供。

1. 在编辑器中打开 Dockerfile。

2. 查找 Dockerfile RUN 语句。该语句允许运行任意 shell 命令来修改环境。如果 Dockerfile 包含多个阶段（可通过找到多条 FROM 语句来确定），则您将会在最后一个阶段找到这条语句。

   所需的特定软件包及其安装机制因容器内声明的操作系统而异。

   如需获取有关所用操作系统或基础映像的说明，请点击相应的标签页。

   Debian/Ubuntu

   run/system_package/Dockerfile

   在 GitHub 上查看 反馈

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

   Alpine

   Alpine 还需要一个用于支持字体的软件包。

   run/system-package/Dockerfile

   在 GitHub 上查看 反馈

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

   要确定容器映像的操作系统，请检查 FROM 语句中的名称或与基础映像关联的 README 文件。例如，如果您的 Dockerfile 从 node 扩展而来，则可以在 Docker Hub 上找到文档和父级 Dockerfile。

3. 使用 docker build（本地）或 Cloud Build 构建映像，以对您的自定义内容进行测试。

处理传入请求

示例服务使用来自传入 HTTP 请求的参数进行系统调用，以此执行相应的 dot 实用程序命令。

以下 HTTP 处理程序从 dot 查询字符串变量中提取图表说明输入参数。

图表说明包含的字符必须采用网址编码，以便用于查询字符串。

Node.js

run/system-package/app.js

在 GitHub 上查看 反馈

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

run/system-package/main.py

在 GitHub 上查看 反馈

@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

run/system_package/graphviz.go

在 GitHub 上查看 反馈

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

run/system-package/src/main/java/com/example/cloudrun/App.java

在 GitHub 上查看 反馈

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;
    });

您需要区分内部服务器错误和无效用户输入。此示例服务会为所有 dot 命令行错误都返回一个内部服务器错误，除非错误消息包含指示用户输入问题的 syntax 字符串。

生成图表

图表生成的核心逻辑是使用 dot 命令行工具将图表说明输入参数处理为 PNG 图片格式的图表。

Node.js

run/system-package/app.js

在 GitHub 上查看 反馈

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

run/system-package/main.py

在 GitHub 上查看 反馈

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

run/system_package/graphviz.go

在 GitHub 上查看 反馈

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

run/system-package/src/main/java/com/example/cloudrun/App.java

在 GitHub 上查看 反馈

// 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;
}

设计安全的服务

dot 工具中的任何漏洞都会成为 Web 服务的潜在漏洞。通过定期重新构建容器映像，您可以使用 graphviz 软件包的最新版本来缓解这种情况。

如果您将当前示例扩展为接受用户输入作为命令行参数，则应防范命令注入攻击。以下是可以防范此类注入攻击的一些方法：

• 将输入映射到由受支持参数组成的字典
• 验证输入是否匹配一系列已知安全的值（可能使用正则表达式）
• 对输入进行转义，以确保不对 shell 语法进行评估

交付代码

要交付代码，请先使用 Cloud Build 进行构建，然后上传到 Container Registry，最后再部署到 Cloud Run for Anthos：

1. 运行以下命令来构建容器并将其发布到 Container Registry 上。

   Node.js

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

   其中 PROJECT_ID 是您的 GCP 项目 ID，graphviz 是您要为服务指定的名称。

   成功完成后，您将看到一条包含 ID、创建时间和映像名称的 SUCCESS 消息。映像存储在 Container Registry 中，并可根据需要重复使用。

   Python

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

   其中 PROJECT_ID 是您的 GCP 项目 ID，graphviz 是您要为服务指定的名称。

   成功完成后，您将看到一条包含 ID、创建时间和映像名称的 SUCCESS 消息。映像存储在 Container Registry 中，并可根据需要重复使用。

   Go

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

   其中 PROJECT_ID 是您的 GCP 项目 ID，graphviz 是您要为服务指定的名称。

   成功完成后，您将看到一条包含 ID、创建时间和映像名称的 SUCCESS 消息。映像存储在 Container Registry 中，并可根据需要重复使用。

   Java

   此示例使用 Jib 利用常见 Java 工具构建 Docker 映像。无需编写 Dockerfile 或安装 Docker，Jib 便可以优化容器构建。详细了解如何使用 Jib 构建 Java 容器。

   1. 使用 Dockerfile，配置并构建已安装系统软件包的基本映像，以覆盖 Jib 的默认基本映像：

      run/system-package/Dockerfile

      在 GitHub 上查看 反馈
      # 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.8_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

      其中 PROJECT_ID 是您的 GCP 项目 ID。

   2. 使用 Jib 构建最终容器并在 Container Registry 上发布：

      run/system-package/pom.xml

      在 GitHub 上查看 反馈
      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>jib-maven-plugin</artifactId>
        <version>3.3.2</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

      其中 PROJECT_ID 是您的 GCP 项目 ID。

2. 使用以下命令进行部署：

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

   其中 PROJECT_ID 是您的 GCP 项目 ID，graphviz 是上述容器的名称，graphviz-web 是服务的名称。

   等待部署完成，这可能需要半分钟左右的时间。

3. 如果要将代码更新部署到该服务，请重复执行上述步骤。向服务执行的每次部署都会创建一个新的修订版本，该修订版本准备就绪后会自动开始处理流量。

试试看

要试用您的服务，您可以发送 HTTP POST 请求，并使用 DOT 语法在请求负载中添加说明。

1. 向您的服务发送 HTTP 请求。

   您可以将图表嵌入到网页中：

   1. 如需获取 Istio 入站网关的外部 IP，请执行以下操作：

      kubectl get svc istio-ingress -n gke-system

      生成的输出类似如下所示：

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

      负载平衡器的 EXTERNAL-IP 是您必须使用的 IP 地址。

   2. 通过在网址中使用此 EXTERNAL-IP 地址，运行 curl 命令。 请不要将协议（例如：http://）添加到 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. 在任何支持 PNG 文件的应用（如 Chrome）中，打开生成的 diagram.png 文件。

   该属性应如下所示：

   

   来源：DOT 说明

您可以浏览一小部分现成的图表说明。

1. 复制所选 .dot 文件的内容

2. 将其粘贴到 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

清除数据

如果您为本教程创建了一个新项目，请删除项目。 如果您使用的是现有项目，希望保留此项目且不保留本教程中添加的任何更改，请删除为教程创建的资源。

删除项目

为了避免产生费用，最简单的方法是删除您为本教程创建的项目。

如需删除项目，请执行以下操作：

注意：删除项目会产生以下影响：

• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

如果您打算探索多个架构、教程或快速入门，则重复使用项目可以帮助您避免超出项目配额限制。

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

删除教程资源

1. 删除您在本教程中部署的 Cloud Run for Anthos 服务：

   gcloud run services delete SERVICE-NAME

   其中，SERVICE-NAME 是您选择的服务名称。

   您还可以在 Google Cloud 控制台中删除 Cloud Run for Anthos 服务。

   转到 Cloud Run for Anthos

2. 移除您在教程设置过程中添加的 gcloud 默认配置：

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

3. 移除项目配置：

    gcloud config unset project
   

4. 删除在本教程中创建的其他 Google Cloud 资源：

   • 从 Container Registry 中删除名为 gcr.io/<var>PROJECT_ID</var>/graphviz 的容器映像。
   • 如果您为本教程创建了一个集群，请删除集群

后续步骤

• 对您的 graphviz 应用进行实验：
  • 添加对其他 graphviz 实用程序的支持，以便运用不同算法来生成图表。
  • 将图表保存到 Cloud Storage。要保存该图片或 DOT 语法吗？
  • 使用 Cloud Natural Language API 实现内容滥用防护。
  • 参阅图片处理中的另一个系统软件包示例。
• 探索有关 Google Cloud 的参考架构、图表和最佳实践。查看我们的 Cloud Architecture Center。