@ 适应worx/iac- core

核心公用事业 适应WorXTM 流 basic-as-code:秘密管理,堆栈上下文检测,区域解析,CIDR分配,和Zod验证的配置方案.

该软件包具有多提供者意识(AWS今天;Cloudflare,GitHub和Infisic作为全球供应商;Azure和GCP计划),并在Apache 2.0下获得许可,用于任何Pulumi + TypeScript项目.

安装

pnpm add @adaptiveworx/iac-core
# or
yarn add @adaptiveworx/iac-core
# or
npm install @adaptiveworx/iac-core

zod 属于对等关系:

pnpm add zod

快开始

import {
  OrganizationConfig,
  loadOrganizationOptionsFromEnv,
  SecretManager,
  detectStackContext,
} from "@adaptiveworx/iac-core";

// 1. Detect Pulumi stack context (provider, environment, region, purpose)
const ctx = detectStackContext();

// 2. Load organization options from env vars
const orgConfig = new OrganizationConfig(loadOrganizationOptionsFromEnv());

// 3. Fetch secrets via Infisical (or env-var fallback)
const sm = new SecretManager({ environment: ctx.environment });
const dbPassword = await sm.getSecret("DB_PASSWORD");

亚路径进口为对树木敏感的消费者提供支持:

import { SecretManager } from "@adaptiveworx/iac-core/config/secrets";
import { resolveRegion } from "@adaptiveworx/iac-core/utils/region-utils";

命名

一个项目是一个账户: {tenant}-{provider}-{account-purpose}-{env}一叠 实值 {target-env}-{stack-purpose}[-{concern}]-{region} (3个或4个一字) 目标环境总是优先)。 供应商: aws, (中文(简体) ), gcp, (中文(简体) ), azure (区域: use1, (中文(简体) ), usw2,(......)和 cloudflare, (中文(简体) ), github, (中文(简体) ), infisical (全球: 区域 glb) (中文(简体) ).

仅此语法解说:遗留语法中的一种名称( :{tenant}-{provider}-{env} 工程及其堆栈)被拒绝,0.6去掉别名地图和 遗留的解析器和构建器(替换表在命名文件中). 见 文档/名称.md 完全语法,地区规则 提供者、账户引用以及如何添加提供者.

每云快速启动指南

• AWS 快速启动 ——普鲁米+AWS全程部署;涵盖OrganizationConfig,AWS账户注册,CIDR,以及政策包集成
• Azure 快速开始 —— Azure- 形状的组织 Config + 区域分辨率 + 秘密; 哪些可行而哪些不可行(尚未)
• GCP 快速启动 - GCP-形状的组织Config+区域分辨率;重量比AWS轻

公共 API

config/

• SecretManager - 从非工业(生产途径中必须)获取秘密 .env.{env} 文件倒计时。 公共方法: getSecret, (中文(简体) ), getOptionalSecret, (中文(简体) ), getBooleanSecret, (中文(简体) ), getDeploymentConfiguration, (中文(简体) ), healthCheck。 。 。 .
• OrganizationConfig - 纯消费者 OrganizationOptions构造 new OrganizationConfig(opts); 通过 loadOrganizationOptionsFromEnv() (遗传)或 loadAdaptiveOrganizationDefaults() (AdaptiveWorX-内部).
• AWSAccountRegistry 发现每个环境的 AWS 账户来自 SecretManager,可选择与调用方提供的"创始账户"(主账,审计,日志存档等)合并.

utils/

• stack-utils —— 说 detectStackContext, (中文(简体) ), parseStackIdentity (单位:千美元)StackIdentity, (中文(简体) ), projectNameOf, (中文(简体) ), stackNameOf, (中文(简体) ), isAccountGrammarProject, (中文(简体) ), validateStackContext, (中文(简体) ), getEnvironmentConfig, (中文(简体) ), getComplianceRequirements, (中文(简体) ), validateCrossAccountOperation。 。 。 .
• region-utils —— 说 resolveRegion, (中文(简体) ), getRegionAliases, (中文(简体) ), isValidRegion, (中文(简体) ), validateAvailabilityZones (负载区域别名来自 @adaptiveworx/iac-schemas) (中文(简体) ).
• cidr-allocation —— 说 calculateVpcCidr, (中文(简体) ), getVpcCidr 在环境+区域之间分配非重叠的CIDR.
• stack-readme —— 说 generateStackReadme, (中文(简体) ), exportStackReadme 用于自动文档 Pulumi 堆栈.

schemas/

• SCHEMA_CONFIG, (中文(简体) ), SCHEMA_BASE_URL ——"IaC"计划命名空间的犬形元数据.
• schemas/core/core-schemas - Zod验证器(StackContextSchema, (中文(简体) ), ProjectNameSchema, (中文(简体) ), StackNameSchema, (中文(简体) ), DeploymentConfigSchema 财务报告和审定财务报表 PolicyConfigSchema (都拿一个 provider 并且以物配主者, AwsRegionSchema (来源于iac-schemas") REGIONS(a/conf.96/9,附件).
• schemas/core/tags —— 说 StandardTagsSchema (iac-schemas的标准标记键, Workload 列入, WorkloadSchema, (中文(简体) ), TagValueSchema。 。 。 .
• schemas/core/providers —— 说 ProviderSchema, (中文(简体) ), PROVIDER_DEFINITIONS,提供地区isValidProviderRegion, (中文(简体) ), resolveProviderRegion, (中文(简体) ), GLOBAL_REGION_CODE)和提供者中立账户参考文献(AccountReferenceSchema, (中文(简体) ), accountReference) (中文(简体) ).

validation/

• AgentValidationService, (中文(简体) ), ValidationPatterns ——代理驱动的IaC业务的跑道护卫.
• ConfigurationValidator 用于堆栈/环境/组件限制的配置形状验证器.

types/

• 所有共享基础设施类型: Provider, (中文(简体) ), Environment, (中文(简体) ), StackContext, (中文(简体) ), DeploymentConfig, (中文(简体) ), ComplianceRequirement, (中文(简体) ), AccountConfig, (中文(简体) ), CidrAllocation等 (中文(简体) ).

通过环境变量配置

软件包遵循"配置入,行为出"的模式. 类会消耗已验证的选项;适配器帮助源这些选项. 图书馆从来不读 process.env 从类构造者,只从显式 loadXxxFromEnv() 帮手.

需要(打电话时) loadOrganizationOptionsFromEnv()(中文(简体) )

AWS-组织具体情况

iac-core ——AWS-组织配置(org ID,主/安全账户,主/DR区域列表) @adaptiveworx/iac-aws 作为 AwsOrganizationConfig,拥有自己的 AWS_* (原始内容存档于2018-10-21). Env-var loaders. 见 AWS 快速启动 为两等的构成模式.

Schema 元数据覆盖

秘密管理者/ 虚构

当不合格时, SecretManager 倒计时 .env.{IAC_ENV} 用于本地开发的文件.

多租户覆盖模式

OrganizationConfig 纯粹是经过验证的选项的消费者。 三种装载模式涵盖常见情况:

1. 适应性WorX-内部-便利助手

用于AditiveWorX内部的部署. 使用canonial默认值,顶部有env-var的覆盖.

import {
  OrganizationConfig,
  loadAdaptiveOrganizationDefaults,
} from "@adaptiveworx/iac-core";

const orgConfig = new OrganizationConfig(loadAdaptiveOrganizationDefaults());
// orgName: "AdaptiveWorX" (or process.env.ORG_NAME)
// tenant:  "worx"          (or process.env.ORG_TENANT)
// orgDomain: "adaptiveworx.com" (or process.env.ORG_DOMAIN)

关于AWS-组织的具体情况(如ID、账户、区域),由下列单位组成: AwsOrganizationConfig 从 @adaptiveworx/iac-aws。 。 。 .

2. 外部消费者(Azure)——明确建筑

对于一个只有Azure的消费者。 无可适应WorX默认漏出.

import { OrganizationConfig } from "@adaptiveworx/iac-core";

const orgConfig = new OrganizationConfig({
  orgName: "Acme Health",
  tenant: "care",
  orgDomain: "acme.example",
});

OrganizationConfig 带有云不可知特性、环境、堆栈命名和网络策略。 云特异性组织配置(管理小组,租户,订阅)目前还没有建模——将Azure-形状的值直接应用到你的普鲁米资源上.

3. 外部消费者(AWS)——由inv-var驱动,分为两个类别

对于一个基于AWS的外部消费者. iac-core 装入 org 身份 ORG_*· ; @adaptiveworx/iac-aws 装入 AWS- org 特性 AWS_*。没有应用可适应WorX默认——每个值都来自环境.

import {
  OrganizationConfig,
  loadOrganizationOptionsFromEnv,
} from "@adaptiveworx/iac-core";
import {
  AwsOrganizationConfig,
  loadAwsOrganizationOptionsFromEnv,
} from "@adaptiveworx/iac-aws";

// Acme Co's deploy environment:
//   ORG_NAME="Acme Co"
//   ORG_TENANT="acme"
//   ORG_DOMAIN="acme.example"
//   AWS_ORG_ID="123456789012"
//   AWS_MASTER_ACCOUNT="acme-master"
//   AWS_SECURITY_ACCOUNT="acme-secops"
//   AWS_PRIMARY_REGIONS="us-east-2,us-west-1"
//   AWS_DR_REGIONS="eu-west-1"

const orgConfig = new OrganizationConfig(loadOrganizationOptionsFromEnv());
const awsConfig = new AwsOrganizationConfig(loadAwsOrganizationOptionsFromEnv());

orgConfig.orgName;                  // "Acme Co"
awsConfig.awsOrganizationId;        // "123456789012"
awsConfig.primaryRegions;           // ["us-east-2", "us-west-1"]

捡起你的装载器

同样的模式适用于 AWSAccountRegistry ——见: loadAdaptiveFoundationAccounts() 适应WorX 基础账户固定工具的助手, 或者通过您自己的 Map<string, FoundationAccount> 通过 foundationAccounts 构造器选项 .

API 参考

最重要的公共课程,有签名和极少的例子。 整个地表,看 src/index.ts。 。 。 .

SecretManager

从 Universal Auth 获取密件, 可选的倒计时到 .env.{IAC_ENV} 用于本地开发的文件.

class SecretManager {
  constructor(defaultContext?: SecretContext);

  // Required secret — throws if absent in both Infisical and env vars
  getSecret(key: string, context?: SecretContext): Promise<string>;

  // Optional secret with fallback
  getOptionalSecret(key: string, defaultValue: string, context?: SecretContext): Promise<string>;

  // Boolean parser (truthy: "true" | "1" | "yes")
  getBooleanSecret(key: string, defaultValue?: boolean, context?: SecretContext): Promise<boolean>;

  // Resolves `AWS_ACCOUNTS` JSON from Infisical
  getAwsAccountsJson(): Promise<AwsAccountsMap>;
  getAwsAccountId(purpose: string, environment: string): Promise<string | null>;
  getAwsProfile(purpose: string, environment: string, _org: string): Promise<string | null>;

  // High-level deployment config (combines org config + secrets + accounts)
  getDeploymentConfiguration(): Promise<DeploymentConfig>;

  // Connection check — useful in CI to fail fast before running pulumi
  healthCheck(): Promise<{ infisicalAvailable: boolean; missingSecrets: string[] }>;
}

interface SecretContext {
  environment?: Environment;   // dev | stg | prd | sec
  provider?: string;          // Infisical folder /{provider}; default IAC_PROVIDER, then aws
  region?: string;
  purpose?: string;
}

const sm = new SecretManager({ environment: "dev" });
await sm.getSecret("DB_PASSWORD");
await sm.getOptionalSecret("LOG_LEVEL", "info");
const useFlag = await sm.getBooleanSecret("FEATURE_X_ENABLED", false);

路线图说明数字 : SecretManager 今天被焊接到异端 A 类 SecretsBackend 可插接接口(Azure Key Vault / AWS Secrets Manager / HashiCorp Vault / 1Password Connect / in-memory test)设计于 docs/design-secrets-backend.md 但尚未执行。 形状只保留提议,直到一个具体的第二消费者对照其真实的认证+秘密布局验证接口. 现有呼叫者在降落时会继续工作——没有公共-API中断.

OrganizationConfig

纯消费 OrganizationOptions见 多租户覆盖模式 上方用于选择源.

class OrganizationConfig {
  readonly orgName: string;
  readonly tenant: string;
  readonly orgDomain: string;
  readonly environments: Record<string, EnvironmentConfig>;
  readonly stackNaming: StackNaming;
  readonly network: NetworkConfig;

  constructor(opts: OrganizationOptions);

  getEnvironmentConfig(environment: string): EnvironmentConfig | undefined;

  // Build a stack name from components — applies stackNaming.separator
  // and compresses the region per regionFormat
  formatStackName(org: string, provider: string, purpose: string, env: string, region: string): string;

  // Strategy lookup (none | single | multi-az | high-availability)
  getNatGatewayCount(environment: string): number;

  // Service feature flags — currently "monitoring", "guardduty"
  shouldEnableService(service: string, environment: string): boolean;

  // "data" | "backup" | "logs" → days
  getRetentionDays(retentionType: "data" | "backup" | "logs", environment: string): number;

  exportAsDict(): Record<string, unknown>;
}

这个 DEFAULT_ENVIRONMENTS, (中文(简体) ), DEFAULT_STACK_NAMING,以及 DEFAULT_NETWORK 常量被输出,这样消费者就可以在不重述的情况下在克恩克克布局上自作选择:

import { OrganizationConfig, DEFAULT_ENVIRONMENTS } from "@adaptiveworx/iac-core";

const orgConfig = new OrganizationConfig({
  orgName: "Acme Co", tenant: "acme", orgDomain: "acme.example",
  environments: {
    ...DEFAULT_ENVIRONMENTS,
    qa: { ...DEFAULT_ENVIRONMENTS.dev, name: "QA", shortName: "stg" }, // add a custom env
  },
});

AWSAccountRegistry

从 a 中发现每个环境的 AWS 账户 SecretManager (典型的不法分子的) AWS_ACCOUNTS JSON)并把它们与可选的"创始账户"相合并——长期账户(主账,审计账,日志存档等),这些账户都位于每个环境结构之外.

class AWSAccountRegistry {
  constructor(opts?: AwsAccountRegistryOptions);

  getFoundationAccountByName(accountName: string): FoundationAccount | undefined;
  getFoundationAccountByPurpose(purpose: string): FoundationAccount | undefined;

  getAccountsForEnvironment(environment: Environment): Promise<Map<string, AccountInfo>>;
  getAllAccounts(): Promise<Map<string, AccountInfo>>;
  getAccountById(accountId: string): Promise<AccountInfo | null>;
  getAccountByName(accountName: string): Promise<AccountInfo | null>;
  getAccountsByPurpose(purpose: string): Promise<Map<string, AccountInfo>>;

  // Returns the secops/hub account if exactly one is marked isVpcHub
  getHubAccount(): Promise<[string, AccountInfo] | [null, null]>;
  getSpokeAccounts(): Promise<Map<string, AccountInfo>>;

  clearCache(): void;
}

interface AwsAccountRegistryOptions {
  secretManager?: SecretManager;
  foundationAccounts?: Map<string, FoundationAccount>;
  accountNamingPrefix?: string;   // default "account"
}

import {
  AWSAccountRegistry,
  loadAdaptiveFoundationAccounts,
} from "@adaptiveworx/iac-core";

// AdaptiveWorX-internal — uses canonical foundation accounts + "worx" prefix
const registry = new AWSAccountRegistry({
  foundationAccounts: loadAdaptiveFoundationAccounts(),
  accountNamingPrefix: "worx",
});

const audit = registry.getFoundationAccountByName("adaptive-audit");
const dev = await registry.getAccountsForEnvironment("dev");

对于外部消费者来说,略去帮助者——登记处将从中动态地发现账户 SecretManager 仅限:

const registry = new AWSAccountRegistry();   // empty foundation map, generic prefix

水电费 - region-utils

function resolveRegion(provider: Provider, regionAlias: string): string;
function getRegionAliases(provider: Provider): Record<string, string>;
function getRegions(provider: Provider): string[];
function isValidRegion(provider: Provider, region: string): boolean;
function validateAvailabilityZones(region: string, count: number): boolean;

import { resolveRegion } from "@adaptiveworx/iac-core";

resolveRegion("aws", "use1");      // "us-east-1"
resolveRegion("azure", "eus2");    // "eastus2"
resolveRegion("aws", "us-east-1"); // "us-east-1" (already canonical)

水电费 - stack-utils

function detectStackContext(): StackContext;
function validateStackContext(ctx: StackContext): ValidationResult;

// Project "{tenant}-{provider}-{account-purpose}-{env}", stack "{target-env}-{stack-purpose}[-{concern}]-{region}"
// e.g. "worx-aws-ops-sec" with "sec-iam-github-use1", or "dev-vpc-use1" (centralized)
function parseStackIdentity(projectName: string, stackName: string): StackIdentity; // throws on any other grammar
function projectNameOf(identity: StackIdentity): string;
function stackNameOf(identity: StackIdentity): string;
function isAccountGrammarProject(projectName: string): boolean;

function getEnvironmentConfig(env: Environment): EnvironmentConfig;
function getComplianceRequirements(env: Environment): ComplianceRequirement[];
function validateCrossAccountOperation(source: string, target: string): ValidationResult;

AWS型区域分辨率resolveAwsRegion(regionCode): aws.Region(中文(简体) ) 住在这里 @adaptiveworx/iac-aws —— 说 iac-core是因为 云不可知边界禁止 @pulumi/aws 参考文献 排放类型.

水电费 - cidr-allocation

// Pure CIDR math
function calculateVpcCidr(cidrBase: string, offset: number): string;

// Looks up the cidrBase from SecretManager (`VPC_CIDR_BASE`), then
// resolves an offset from regionsConfig.aws.cidrOffsets[region]
function getVpcCidr(
  environment: string,
  region: string,
  secretManager: SecretManager
): Promise<string>;

calculateVpcCidr("10.224.0.0/11", 0);  // "10.224.0.0/16" — us-east-1
calculateVpcCidr("10.224.0.0/11", 1);  // "10.225.0.0/16" — us-east-2

史克马斯.. schemas/core

已准备好 Zod 验证器 safeParse 编号 : parse数字 :

import {
  StackContextSchema,
  DeploymentConfigSchema,
  AwsRegionSchema,
  EnvironmentSchema,
  ComplianceRequirementSchema,
} from "@adaptiveworx/iac-core";

const result = StackContextSchema.safeParse(ctx);
if (!result.success) {
  console.error(result.error.issues);
}

测试过的版本

稳定

这是一个 0.x 释放。 API 可能改变前向后兼容的方式 1.0一次 1.0 船,包裹会跟着 语义版本。 。 。 .

许可证

Apache 2.0 (英语)。见 通知 用于归属要求.

仓库+捐款

此软件包是在 适应WorX/iac-核心 单重键 : packages/iac-core/。见 捐款额 工作流程惯例和发布程序。 文件问题 https://github.com/AdaptiveWorX/iac-core/issues (中文(简体) )。 。 。 .