使用CDKTF与TypeScript存储tfstate到Azure存储账户时遇错误

错误原因分析 #

1. 后端初始化时机冲突：Terraform的后端配置必须在terraform init阶段确定所有参数值，你代码中直接使用tfStateResourceGroup.name和tfStateStorageAccount.name（属于未创建资源的动态属性），初始化阶段Terraform无法解析这些值，导致传递了占位符字符串（如${azurerm_resource_group.xxxxx-rg (xxxx-rg).name}）到Azure API，触发校验失败。
2. 资源名称格式违规：错误信息显示资源组名称包含空格（xxxx-rg (xxxx-rg)），不符合Azure资源组名称的正则规则^[-\w\._\(\)]+$（不允许空格），这是env.CreateTfStateId生成的名称不符合要求导致的。

解决方案步骤 #

1. 修正资源命名规则 #

先确保CreateTfStateId生成的名称符合Azure强制要求：

• 资源组名称：长度1-90，仅允许字母、数字、连字符、下划线、点、括号，不能以连字符结尾
• 存储账户名称：长度3-24，仅允许小写字母和数字，无其他字符

修改CreateTfStateId方法，示例如下：

class Environment {
  CreateTfStateId(suffix: string): string {
    // 替换空格为连字符，转小写，移除违规字符
    const baseName = this.name.replace(/\s+/g, '-').toLowerCase();
    return `${baseName}-${suffix}`.replace(/[^a-z0-9\-_\.\(\)]/g, '');
  }
}

2. 拆分Stack实现后端资源预创建 #

由于Terraform后端初始化不能依赖未创建的资源，必须先单独创建存储tfstate的资源组和存储账户，再用已存在的资源配置主Stack的后端：

步骤1：创建后端引导Stack（BackendBootstrapStack）

这个Stack仅负责创建存储tfstate所需的资源，使用本地临时状态：

class BackendBootstrapStack extends TerraformStack {
  public readonly resourceGroupName: string;
  public readonly storageAccountName: string;
  public readonly containerName = 'tfstate';

  constructor(scope: Construct, id: string, env: Environment) {
    super(scope, id);

    new AzurermProvider(this, 'AzureRm', { features: {} });

    this.resourceGroupName = env.CreateTfStateId('rg');
    this.storageAccountName = env.CreateTfStateId('sa').toLowerCase(); // 存储账户名必须小写

    const resourceGroup = new ResourceGroup(this, this.resourceGroupName, {
      name: this.resourceGroupName,
      location: 'xxxxx',
    });

    const storageAccount = new StorageAccount(this, this.storageAccountName, {
      name: this.storageAccountName,
      resourceGroupName: resourceGroup.name,
      location: 'xxxxx',
      accountTier: 'Standard',
      accountReplicationType: 'LRS',
      accountKind: 'StorageV2',
      enableHttpsTrafficOnly: true,
    });

    // 创建存储容器
    new StorageContainer(this, 'tfstate-container', {
      name: this.containerName,
      storageAccountName: storageAccount.name,
      containerAccessType: 'Private',
    });

    // 输出资源信息，方便后续获取
    new TerraformOutput(this, 'resource-group-name', { value: resourceGroup.name });
    new TerraformOutput(this, 'storage-account-name', { value: storageAccount.name });
  }
}

步骤2：部署引导Stack并获取资源信息

先部署这个引导Stack：

cdktf deploy BackendBootstrapStack

部署完成后，记录输出的resource-group-name和storage-account-name，或通过环境变量传递。

步骤3：配置主Stack的Azure后端

在主Stack中，使用已创建的资源静态值配置后端，而非动态依赖：

class MainStack extends TerraformStack {
  constructor(scope: Construct, id: string, env: Environment, backendConfig: {
    resourceGroupName: string;
    storageAccountName: string;
    containerName: string;
  }) {
    super(scope, id);

    new AzurermProvider(this, 'AzureRm', { features: {} });

    // 配置Azure后端，使用预创建的资源信息
    new AzurermBackend(this, 'TerraformBackend', {
      resourceGroupName: backendConfig.resourceGroupName,
      storageAccountName: backendConfig.storageAccountName,
      containerName: backendConfig.containerName,
      key: `${env.name}/infrastructure-terraform.tfstate`,
    });

    // 此处添加你的其他基础设施资源
    // ...
  }
}

步骤4：初始化并部署主Stack

从环境变量或配置文件读取引导Stack的输出值：

// 示例：从环境变量读取后端配置
const backendConfig = {
  resourceGroupName: process.env.BACKEND_RG_NAME!,
  storageAccountName: process.env.BACKEND_SA_NAME!,
  containerName: 'tfstate',
};

const app = new App();
new MainStack(app, 'MainStack', env, backendConfig);
app.synth();

执行初始化和部署：

cdktf init
cdktf deploy MainStack

关键注意事项 #

• 后端引导Stack的状态可暂时存于本地，后续更新时需注意不要破坏已有的tfstate文件。
• 存储账户名称必须为小写字母和数字的组合，这是Azure的强制要求，代码中必须确保转换为小写。

内容的提问来源于stack exchange，提问作者ZunX