第一階段 — 建置

第一階段使用 Terraform 在 F5 Distributed Cloud 上部署具有權威性的主要 DNS 區域，並以 Azure Blob Storage 作為遠端狀態儲存後端。本頁說明計畫中的每個檔案、解釋必要的變數與密鑰，並涵蓋本機執行與 GitHub Actions 管線兩種方式。

部署內容

• 在 system 命名空間中為您委派的網域建立一個 xcsh_dns_zone，並包含一個 demo-records 群組的 A 記錄（www、app、api）。
• Terraform 狀態儲存於 Azure Blob Storage 容器中，讓您的本機與 CI 環境共享相同的狀態。

注意

DNS 物件必須建立在 system 命名空間中 — F5 XC API 會拒絕其他命名空間。區域名稱必須是您帳號所擁有的網域，且記錄的 TTL 必須至少為 60 秒。

計畫結構

計畫位於 terraform/ 目錄下：一個精簡的根模組，負責將輸入傳入 dns-zone 模組。

versions.tf

固定 Terraform 及提供者的版本。提供者版本限制為 >= 3.62.0 — 此版本開始，僅限系統使用的 DNS 資源會自動預設其命名空間。

terraform {
  required_version = ">= 1.5"

  required_providers {
    xcsh = {
      source = "f5-sales-demo/xcsh"
      # >= 3.62.0: the namespace attribute for system-only DNS resources defaults
      # to "system" (spec-driven), so it can be omitted. Locally the provider is
      # consumed via dev_overrides, which ignores this constraint.
      version = ">= 3.62.0"
    }
  }
}

providers.tf

提供者在程式碼中不帶任何參數 — 它從環境變數進行驗證，因此不會有密鑰被提交至版本庫。

# The xcsh provider authenticates from the environment — no secrets in code.
# Export one of the following credential sets before running Terraform:
#
#   Token auth:  XCSH_API_URL + XCSH_API_TOKEN
#   P12 auth:    XCSH_API_URL + XCSH_P12_FILE + XCSH_P12_PASSWORD
#   PEM auth:    XCSH_API_URL + XCSH_CERT + XCSH_KEY
#
# See terraform/README.md for local dev setup (dev_overrides + env).
provider "xcsh" {}

backend.tf

一個部分的 azurerm 後端設定：不在此處寫死任何環境特定的值。座標資訊在 init 時提供（來自本機檔案，或在 CI 中來自 GitHub Actions 變數）。

terraform {
  # Azure Blob Storage remote state, configured as a PARTIAL backend:
  # no environment-specific values are hardcoded here. Supply them at init time.
  #
  #   CI:    terraform init -backend-config="resource_group_name=$RG" ...
  #          (values from GitHub Actions repository variables)
  #   Local: terraform init -backend-config=backend.hcl   (copy backend.hcl.example; gitignored)
  #
  # Auth is the storage account access key via the ARM_ACCESS_KEY environment
  # variable (never committed). Keyless auth (use_oidc / use_azuread_auth) is not
  # used: our Contributor-only RBAC cannot assign the "Storage Blob Data
  # Contributor" role those methods require.
  backend "azurerm" {}
}

variables.tf

domain 為必填項目（在執行時提供，不寫死）；a_records 將每個記錄名稱對應至其 IPv4 位址。此處沒有 namespace 變數 — 提供者依據 API 規格的限制，將 DNS 物件固定至 system 命名空間，因此無需在此設定。

variable "domain" {
  description = "DNS zone FQDN (required; supplied via TF_VAR_domain / a GitHub variable / tfvars)."
  type        = string
}

variable "labels" {
  description = "Labels applied to managed DNS objects."
  type        = map(string)
  default = {
    managed_by = "terraform"
    use_case   = "dns"
  }
}

variable "a_records" {
  description = "A records: record name (\"\" = apex) to list of IPv4 addresses."
  type        = map(list(string))
  default = {
    www = ["203.0.113.10"]
    app = ["203.0.113.20"]
    api = ["203.0.113.30"]
  }
}

提示

預設的 A 記錄使用 RFC 5737 文件位址（203.0.113.0/24），這些位址無法路由。如需用於實際示範，請將其替換為真實的目標位址。

main.tf 與 dns-zone 模組

根模組將輸入傳入 ./modules/dns-zone：

module "dns_zone" {
  source = "./modules/dns-zone"

  domain    = var.domain
  labels    = var.labels
  a_records = var.a_records
}

該模組負責建立區域（命名空間已省略 — 提供者預設為 system）。一個 dynamic "rr_set" 區塊將 a_records 對應表轉換為每個項目一組記錄集：

resource "xcsh_dns_zone" "this" {
  name   = var.domain
  labels = var.labels

  primary {
    default_soa_parameters {}

    rr_set_group {
      metadata {
        name = "demo-records"
      }

      dynamic "rr_set" {
        for_each = var.a_records
        content {
          ttl = var.record_ttl
          a_record {
            name   = rr_set.key
            values = rr_set.value
          }
        }
      }
    }
  }
}

根目錄的 outputs.tf 從模組重新匯出區域名稱與 F5 XC 識別碼。

必要的變數與密鑰

.tf 檔案中不內嵌任何環境特定的資訊。所有內容均在執行時提供 — 在 CI 中來自 GitHub Actions 的變數與密鑰，或在本機來自本機檔案及環境變數。

值	用途	CI 來源	本機來源
resource_group_name、storage_account_name、container_name、key	azurerm 後端座標	儲存庫變數 TFSTATE_RESOURCE_GROUP、TFSTATE_STORAGE_ACCOUNT、TFSTATE_CONTAINER、TFSTATE_KEY（透過 -backend-config 傳入）	backend.hcl（複製自 backend.hcl.example；已加入 gitignore）
domain	Terraform 輸入值	儲存庫變數 DNS_DOMAIN（作為 TF_VAR_domain）	terraform.tfvars（複製範例檔案）或 TF_VAR_domain
ARM_ACCESS_KEY	azurerm 後端驗證（儲存帳戶金鑰）	儲存庫密鑰	export ARM_ACCESS_KEY=...
XCSH_API_URL、XCSH_API_TOKEN	xcsh 提供者驗證	儲存庫密鑰	export XCSH_API_URL=... XCSH_API_TOKEN=...

儲存庫中附帶的兩個範例檔案：

backend.hcl.example

resource_group_name  = "f5-sales-demo-tfstate"
storage_account_name = "f5salesdemotfstate"
container_name       = "tfstate"
key                  = "dns.tfstate"

terraform.tfvars.example

domain = "f5-sales-demo.com"

labels = {
  managed_by = "terraform"
  use_case   = "dns"
}

a_records = {
  www = ["203.0.113.10"]
  app = ["203.0.113.20"]
  api = ["203.0.113.30"]
}

警告

後端驗證使用儲存帳戶存取金鑰（ARM_ACCESS_KEY），而非無金鑰的 OIDC / Azure AD 方式。無金鑰的資料平面存取需要 Storage Blob Data Contributor 角色，而僅具備 Contributor 角色的訂閱無法指派此角色。存取金鑰僅存在於環境變數或 GitHub 密鑰中 — 絕不會被提交至版本庫。

啟動 Azure 狀態後端

後端儲存無法儲存其自身的啟動設定，因此需透過已驗證的 Azure CLI 工作階段，在帶外一次性建立。儲存庫附帶 scripts/bootstrap-azure-state.sh：

az group create --name f5-sales-demo-tfstate --location eastus2 \
  --tags managed_by=terraform use_case=dns purpose=tfstate

az storage account create --name f5salesdemotfstate --resource-group f5-sales-demo-tfstate \
  --location eastus2 --sku Standard_LRS --kind StorageV2 \
  --min-tls-version TLS1_2 --allow-blob-public-access false

# State safety: keep prior versions and allow recovery of deleted state blobs.
az storage account blob-service-properties update \
  --account-name f5salesdemotfstate --resource-group f5-sales-demo-tfstate \
  --enable-versioning true \
  --enable-delete-retention true --delete-retention-days 7 \
  --enable-container-delete-retention true --container-delete-retention-days 7

KEY="$(az storage account keys list \
  --account-name f5salesdemotfstate --resource-group f5-sales-demo-tfstate \
  --query '[0].value' -o tsv)"

az storage container create --name tfstate \
  --account-name f5salesdemotfstate --auth-mode key --account-key "$KEY"

接著匯出金鑰供本機執行使用，並將其（連同提供者憑證）設定為 GitHub 密鑰：

export ARM_ACCESS_KEY="$KEY"
gh secret set ARM_ACCESS_KEY -R f5-sales-demo/dns
gh secret set XCSH_API_URL   -R f5-sales-demo/dns
gh secret set XCSH_API_TOKEN -R f5-sales-demo/dns

本機部署

1. 設定輸入值。 複製範例檔案並填入您的值：

   cp terraform/backend.hcl.example terraform/backend.hcl
   cp terraform/terraform.tfvars.example terraform/terraform.tfvars

2. 匯出憑證：

   export XCSH_API_URL="https://<tenant>.console.ves.volterra.io"
   export XCSH_API_TOKEN="<api-token>"
   export ARM_ACCESS_KEY="<storage-account-key>"

3. 使用部分設定初始化後端：

   cd terraform
   terraform init -backend-config=backend.hcl

4. 檢查格式並驗證：

   terraform fmt -check -recursive
   terraform validate

5. 計畫並套用：

   terraform plan
   terraform apply

成功套用後，系統會建立區域並將狀態寫入 Azure 容器。請繼續前往第二階段 — 驗證以確認解析是否正常運作。

持續整合

.github/workflows/terraform.yml 工作流程會在每次拉取請求時執行計畫，並在合併至 main 時執行套用。它從儲存庫變數讀取後端座標與輸入值，從密鑰讀取憑證，並僅將每個值注入至需要它的步驟中，同時透過並行群組序列化執行，確保兩個套用操作不會同時競爭共享的狀態 blob。

name: Terraform

on:
  pull_request:
    branches: [main]
    paths: ['terraform/**', '.github/workflows/terraform.yml']
  push:
    branches: [main]
    paths: ['terraform/**']

permissions:
  contents: read

concurrency:
  group: terraform-state
  cancel-in-progress: false

env:
  TF_IN_AUTOMATION: 'true'

jobs:
  terraform:
    name: ${{ github.event_name == 'push' && 'apply' || 'plan' }}
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: terraform
    steps:
      - name: Checkout
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@dfe3c3f87815947d99a8997f908cb6525fc44e9e # v4.0.1

      - name: Init
        env:
          ARM_ACCESS_KEY: ${{ secrets.ARM_ACCESS_KEY }}
          RESOURCE_GROUP: ${{ vars.TFSTATE_RESOURCE_GROUP }}
          STORAGE_ACCOUNT: ${{ vars.TFSTATE_STORAGE_ACCOUNT }}
          CONTAINER: ${{ vars.TFSTATE_CONTAINER }}
          STATE_KEY: ${{ vars.TFSTATE_KEY }}
        run: |
          terraform init -input=false \
            -backend-config="resource_group_name=${RESOURCE_GROUP}" \
            -backend-config="storage_account_name=${STORAGE_ACCOUNT}" \
            -backend-config="container_name=${CONTAINER}" \
            -backend-config="key=${STATE_KEY}"

      - name: Format check
        run: terraform fmt -check -recursive

      - name: Validate
        run: terraform validate -no-color

      - name: Plan
        if: github.event_name == 'pull_request'
        env:
          ARM_ACCESS_KEY: ${{ secrets.ARM_ACCESS_KEY }}
          XCSH_API_URL: ${{ secrets.XCSH_API_URL }}
          XCSH_API_TOKEN: ${{ secrets.XCSH_API_TOKEN }}
          TF_VAR_domain: ${{ vars.DNS_DOMAIN }}
        run: terraform plan -input=false -no-color

      - name: Apply
        if: github.event_name == 'push'
        env:
          ARM_ACCESS_KEY: ${{ secrets.ARM_ACCESS_KEY }}
          XCSH_API_URL: ${{ secrets.XCSH_API_URL }}
          XCSH_API_TOKEN: ${{ secrets.XCSH_API_TOKEN }}
          TF_VAR_domain: ${{ vars.DNS_DOMAIN }}
        run: terraform apply -input=false -auto-approve -no-color

Actions 已固定至提交 SHA（並附有版本註解），密鑰的作用域限定於 init、plan 和 apply 步驟，而非整個工作。