第一阶段 — 构建

第一阶段使用 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 和 Provider 版本。Provider 约束为 >= 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

Provider 在代码中不接受任何参数——它从环境变量中进行认证，因此不会将密钥提交到代码库。

# 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 变量——Provider 根据 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
}

该模块创建区域（命名空间被省略——Provider 默认将其设置为 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 Provider 认证	仓库密钥	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"

然后导出密钥以供本地运行使用，并将其（连同 Provider 凭据）设置为 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

成功应用后，将创建 DNS 区域并将状态写入 Azure 容器。继续前往第二阶段 — 验证以确认解析是否正常。

持续集成

.github/workflows/terraform.yml 工作流在每次 Pull Request 时执行 plan，在合并到 main 时执行 apply。它从仓库变量中读取后端参数和输入值，从密钥中读取凭据，仅将每项内容注入到需要它的步骤中，并通过并发组对运行进行串行化，确保两次 apply 不会在共享状态 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 步骤，而非整个作业。