使用系統套件教學課程

設定 gcloud 預設值

如要針對 Cloud Run 服務設定 gcloud 的預設值：

1. 設定您的預設專案：

   gcloud config set project PROJECT_ID

   將 PROJECT_ID 改為您為本教學課程建立的專案名稱。

2. 為所選地區設定 gcloud：

   gcloud config set run/region REGION

   將 REGION 改為您所選擇的支援 Cloud Run 地區。

擷取程式碼範例

如要擷取要使用的程式碼範例：

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 範例程式碼的目錄：

   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/

將架構視覺化

基本架構如下所示：

使用者將 HTTP 要求傳送至 Cloud Run 服務，這個服務會執行 Graphviz 公用程式，將要求轉換成圖片，再將該圖片做為 HTTP 回應傳送給使用者。

瞭解程式碼

使用 Dockerfile 定義環境設定

您的 Dockerfile 僅適用於您的服務使用的語言和基本作業環境 (例如 Ubuntu)。

《建構及部署》快速入門導覽課程提供各種不同的 Dockerfiles，您可據此建構用於其他服務的 Dockerfile。

這項服務需要一或多個額外系統套件 (預設不提供)。

1. 在編輯器中開啟 Dockerfile。

2. 尋找 Dockerfile RUN 陳述式。這個陳述式允許執行任意殼層指令來修改環境。如果 Dockerfile 有多個階段，可藉由尋找多個 FROM 陳述式加以識別，您會在最後的階段中找到它。

   需要的特定套件和安裝機制，會因容器內部宣告的作業系統而異。

   如要取得作業系統或基本映像檔適用的操作說明，請按一下相關的分頁標籤。

   Debian/Ubuntu

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

   Alpine

   Alpine 需要第二套件才能取得字型支援。

   RUN apk --no-cache add graphviz

   如果要判斷容器映像檔的作業系統，請查看 FROM 陳述式中的名稱或與基本映像檔相關聯的 README。例如，如果您從 node 進行擴充，可以在 Docker Hub 尋找說明文件和父項 Dockerfile。

3. 使用 docker build 本機或 Cloud Build 建構映像檔，測試自訂項目。

處理傳入要求

範例服務使用傳入 HTTP 要求中的參數來叫用系統呼叫，以執行適當的 dot 公用程式指令。

在下面的 HTTP 處理常式中，圖表說明輸入參數是從 dot 查詢字串變數中擷取出的。

圖表說明所包含的字元必須使用網址編碼，以便在查詢字串中使用。

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

@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

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

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

您需要分清楚內部伺服器錯誤與無效的使用者輸入。除非錯誤訊息含有 syntax 字串來表示使用者輸入問題，否則對於所有 dot 指令列錯誤，這個範例服務都會傳回內部伺服器錯誤。

產生圖表

產生圖表的核心邏輯使用 dot 指令列工具，將圖表說明輸入參數處理為 PNG 圖片格式的圖表。

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

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

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

// 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 工具的任何安全漏洞都是網路服務的潛在安全漏洞。您可以透過定期重新建構容器映像檔，使用最新版 graphviz 套件來減緩這種情況。

如果您將目前的範例擴充為接受使用者輸入做為指令列參數，則應防範指令植入 (command-injection) 攻擊。防範植入攻擊的幾個方法包括：

• 將輸入內容對應至支援參數的字典
• 驗證輸入內容是否與範圍廣泛的已知安全值相符 (可使用規則運算式)
• 逸出輸入內容以確保不會評估殼層語法

您可以使用未授予任何 Google Cloud服務權限的服務帳戶部署服務，進一步降低潛在的安全漏洞，而非使用已普遍使用權限的預設帳戶。因此，本教學課程的步驟會建立及使用新的服務帳戶。

推送程式碼

如要推送您的程式碼，您可使用 Cloud Build 建構程式碼，並上傳至 Artifact Registry，然後部署到 Cloud Run：

1. 建立 Artifact Registry：

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

   取代：

   • REPOSITORY 與存放區的專屬名稱。專案中的每個存放區位置，存放區名稱都必須是唯一的。
   • REGION 與要用於 Artifact Registry 存放區的 Google Cloud 區域。

2. 執行下列指令以建構您的容器，然後發布到 Artifact Registry。

   Node.js

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

   其中 PROJECT_ID 是您的 Google Cloud 專案 ID，graphviz 則是您要給予服務的名稱。

   若成功執行，您會看到包含 ID、建立時間和映像檔名稱的「SUCCESS」(成功) 訊息。映像檔會儲存在 Artifact Registry 中，日後如有需要，可以重複使用。

   Python

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

   其中 PROJECT_ID 是您的 Google Cloud 專案 ID，graphviz 則是您要給予服務的名稱。

   若成功執行，您會看到包含 ID、建立時間和映像檔名稱的「SUCCESS」(成功) 訊息。映像檔會儲存在 Artifact Registry 中，日後如有需要，可以重複使用。

   Go

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

   其中 PROJECT_ID 是您的 Google Cloud 專案 ID，graphviz 則是您要給予服務的名稱。

   若成功執行，您會看到包含 ID、建立時間和映像檔名稱的「SUCCESS」(成功) 訊息。映像檔會儲存在 Artifact Registry 中，日後如有需要，可以重複使用。

   Java

   這個範例使用 Jib 建構 Docker 映像檔，並使用常見的 Java 工具。Jib 可在不需要 Dockerfile 或安裝 Docker 的情況下，最佳化容器建構作業。進一步瞭解如何使用 Jib 建構 Java 容器。

   1. 使用 Dockerfile 設定並建構基本映像檔，並安裝系統套件來覆寫 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.15_6-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

      其中 PROJECT_ID 是您的 Google Cloud 專案 ID。

   2. 使用 gcloud 憑證輔助程式授權 Docker 推送至 Artifact Registry。

      gcloud auth configure-docker

   3. 使用 Jib 建構最終容器，並發布至 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

      其中 PROJECT_ID 是您的 Google Cloud 專案 ID。

3. 使用下列指令進行部署：

   gcloud

   1. 建立新的服務帳戶。您的程式碼 (包括所使用的任何系統套件) 只能使用已授予此服務帳戶的Google Cloud 服務。

      gcloud iam service-accounts create SA_NAME

      ，其中 SA_NAME 是您為此服務帳戶指定的名稱。如果程式碼有錯誤或漏洞，就無法存取任何其他 Google Cloud 專案資源。
   2. 部署程式碼，並指定服務帳戶。

      gcloud run deploy graphviz-web --service-account SA_NAME@PROJECT_ID.iam.gserviceaccount.com  --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/graphviz

      其中 PROJECT_ID 是您的 Google Cloud 專案 ID，SA_NAME 是您建立的服務帳戶名稱，graphviz 是上述容器的名稱，graphviz-web 則是服務名稱。出現「allow unauthenticated」(允許未經驗證) 提示時，請回覆 Y。如要進一步瞭解以 IAM 為基礎的驗證，請參閱「管理存取權」一文。
   3. 等待部署作業完成。這項作業可能需要半分鐘的時間。成功完成後，指令列會顯示服務網址。

   Terraform

   如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。

   下列 Terraform 程式碼會建立 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
     }
   }

   將 IMAGE_URL 替換為容器映像檔的參照，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。如果您使用的是 Artifact Registry，則必須先建立存放區 REPO_NAME。網址的形狀為 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。

   下列 Terraform 程式碼會公開 Cloud Run 服務。

   # 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. 如果您要將程式碼更新部署到服務，請重複上述步驟。每次部署到服務都會建立一個新的修訂版本，並會在就緒時自動開始處理流量。

立即體驗

如要開始試用您的服務，請在要求酬載中搭配 DOT 語法說明來傳送 HTTP POST 要求。

1. 將 HTTP 要求傳送到您的服務。

   將網址複製到瀏覽器網址列，並更新 [SERVICE_DOMAIN]：

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

   您可以在網頁中嵌入圖表：

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

2. 使用任何支援 PNG 檔案的應用程式 (例如 Chrome) 開啟產生的 diagram.png 檔案。

   內容應該會類似這樣：

   

您可以探索現成圖表說明的小型集合。

1. 複製所選 .dot 檔案的內容

2. 將 HTTP 要求傳送到您的服務。

   將網址複製到瀏覽器網址列

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