Bake 中的變數

目錄

您可以在 Bake 檔案中定義和使用變數來設定屬性值、將其插入到其他值中以及執行算術運算。變數可以定義預設值，也可以使用環境變數覆蓋。

將變數用作屬性值

使用 variable 塊定義變數。

docker-bake.hcl
variable "TAG" {
  default = "docker.io/username/webapp:latest"
}

以下示例展示瞭如何在目標中使用 TAG 變數。

docker-bake.hcl
target "webapp" {
  context = "."
  dockerfile = "Dockerfile"
  tags = [ TAG ]
}

將變數插入到值中

Bake 支援將變數字串插值到值中。您可以使用 ${} 語法將變數插入到值中。以下示例定義了一個 TAG 變數，其值為 latest。

docker-bake.hcl
variable "TAG" {
  default = "latest"
}

要將 TAG 變數插入到屬性的值中，請使用 ${TAG} 語法。

docker-bake.hcl
group "default" {
  targets = [ "webapp" ]
}

variable "TAG" {
  default = "latest"
}

target "webapp" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["docker.io/username/webapp:${TAG}"]
}

使用 --print 標誌列印 Bake 檔案會顯示已解析構建配置中的插值值。

$ docker buildx bake --print

{
  "group": {
    "default": {
      "targets": ["webapp"]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": ["docker.io/username/webapp:latest"]
    }
  }
}

驗證變數

要驗證變數的值是否符合預期型別、值範圍或其他條件，您可以使用 validation 塊定義自定義驗證規則。

在以下示例中，驗證用於對變數值強制執行數字約束；PORT 變數必須大於或等於 1024。

docker-bake.hcl
# Define a variable `PORT` with a default value and a validation rule
variable "PORT" {
  default = 3000  # Default value assigned to `PORT`

  # Validation block to ensure `PORT` is a valid number within the acceptable range
  validation {
    condition = PORT >= 1024  # Ensure `PORT` is at least 1024
    error_message = "The variable 'PORT' must be 1024 or greater."  # Error message for invalid values
  }
}

如果 condition 表示式計算結果為 false，則變數值被視為無效，從而導致構建呼叫失敗併發出 error_message。例如，如果 PORT=443，則條件計算結果為 false，並引發錯誤。

在設定驗證之前，值會被強制轉換為預期型別。這可確保使用環境變數設定的任何覆蓋都按預期工作。

驗證多個條件

要評估多個條件，請為變數定義多個 validation 塊。所有條件都必須為 true。

這是一個示例

docker-bake.hcl
# Define a variable `VAR` with multiple validation rules
variable "VAR" {
  # First validation block: Ensure the variable is not empty
  validation {
    condition = VAR != ""
    error_message = "The variable 'VAR' must not be empty."
  }

  # Second validation block: Ensure the value contains only alphanumeric characters
  validation {
    # VAR and the regex match must be identical:
    condition = VAR == regex("[a-zA-Z0-9]+", VAR)
    error_message = "The variable 'VAR' can only contain letters and numbers."
  }
}

此示例強制執行

  • 變數不能為空。
  • 變數必須匹配特定的字元集。

對於 VAR="hello@world" 等無效輸入，驗證將失敗。

驗證變數依賴項

您可以在條件表示式中引用其他 Bake 變數，從而啟用強制執行變數之間依賴關係的驗證。這可確保在繼續之前正確設定依賴變數。

這是一個示例

docker-bake.hcl
# Define a variable `FOO`
variable "FOO" {}

# Define a variable `BAR` with a validation rule that references `FOO`
variable "BAR" {
  # Validation block to ensure `FOO` is set if `BAR` is used
  validation {
    condition = FOO != ""  # Check if `FOO` is not an empty string
    error_message = "The variable 'BAR' requires 'FOO' to be set."
  }
}

此配置確保僅當 FOO 已分配非空值時才能使用 BAR 變數。嘗試在不設定 FOO 的情況下進行構建將觸發驗證錯誤。

轉義變數插值

如果您想在解析 Bake 定義時繞過變數插值，請使用雙美元符號 ($${VARIABLE})。

docker-bake.hcl
target "webapp" {
  dockerfile-inline = <<EOF
  FROM alpine
  ARG TARGETARCH
  RUN echo "Building for $${TARGETARCH/amd64/x64}"
  EOF
  platforms = ["linux/amd64", "linux/arm64"]
}
$ docker buildx bake --progress=plain
...
#8 [linux/arm64 2/2] RUN echo "Building for arm64"
#8 0.036 Building for arm64
#8 DONE 0.0s

#9 [linux/amd64 2/2] RUN echo "Building for x64"
#9 0.046 Building for x64
#9 DONE 0.1s
...

跨檔案使用變數中的變數

當指定多個檔案時，一個檔案可以使用另一個檔案中定義的變數。在以下示例中，vars.hcl 檔案定義了一個 BASE_IMAGE 變數，其預設值為 docker.io/library/alpine。

vars.hcl
variable "BASE_IMAGE" {
  default = "docker.io/library/alpine"
}

以下 docker-bake.hcl 檔案定義了一個引用 BASE_IMAGE 變數的 BASE_LATEST 變數。

docker-bake.hcl
variable "BASE_LATEST" {
  default = "${BASE_IMAGE}:latest"
}

target "webapp" {
  contexts = {
    base = BASE_LATEST
  }
}

當您使用 -f 標誌指定 vars.hcl 和 docker-bake.hcl 檔案並列印已解析的構建配置時，您會看到 BASE_LATEST 變數已解析為 docker.io/library/alpine:latest。

$ docker buildx bake -f vars.hcl -f docker-bake.hcl --print app

{
  "target": {
    "webapp": {
      "context": ".",
      "contexts": {
        "base": "docker.io/library/alpine:latest"
      },
      "dockerfile": "Dockerfile"
    }
  }
}

其他資源

以下是一些其他資源，展示瞭如何在 Bake 中使用變數

  • 您可以使用環境變數覆蓋 variable 值。有關更多資訊，請參閱覆蓋配置。
  • 您可以在函式中引用和使用全域性變數。請參閱HCL 函式
  • 您可以在評估表示式時使用變數值。請參閱表示式評估