# Nextgen Metering Auto Region Design ## Goal Add automatic new-region support for `nextgen-metering-server` in `app-delivery`. The workflow should match existing next-gen regional-control-plane components: a GitHub Actions workflow receives region metadata and `additionalArgs`, calls a component-local `deploy-new-region.sh`, generates a new kustomize overlay, registers the overlay in `app-registry/nextgen-metering-server.yaml`, and opens an automated pull request. ## Scope In scope: - `dev/nextgen-regional-control-plane/nextgen-metering-server` - `staging/nextgen-regional-control-plane/nextgen-metering-server` - `nextgen-regional-control-plane/nextgen-metering-server` - AWS, Alicloud, and Azure providers - A new GitHub Actions workflow for automatic PR creation - Local tests that exercise all three provider paths Out of scope: - Changing nextgen metering runtime behavior - Migrating existing manually-created overlays to generated output - Deriving cloud credentials, storage buckets, or IAM roles from existing regions - Changing the current bump-version workflow ## Architecture Each `nextgen-metering-server` tree gets provider templates under: ```text nextgen-metering-server/variants/-/ ``` The new script runs from the selected work directory: ```bash deploy-new-region.sh ``` The GitHub workflow selects the work directory from `env`: - `dev` uses `dev/nextgen-regional-control-plane` - `staging` uses `staging/nextgen-regional-control-plane` - `prod` uses `nextgen-regional-control-plane` The script copies templates into the generated env directory and replaces placeholders with explicitly supplied values from `additionalArgs`. ## Generated Names The generated overlay name follows existing nextgen metering conventions: - `prod` and `staging`: `--` - `dev` AWS: `dev-` - `dev` Azure: `dev-azure-` - `dev` Alicloud: `alicloud-dev-` Provider aliases: - `aws` -> `aws` - `alicloud` -> `ali` - `azure` -> `azure` Examples: - `prod`, `aws`, `us-west-2-ng` -> `prod-aws-us-west-2-ng` - `staging`, `alicloud`, `ap-southeast-1-ng` -> `staging-ali-ap-southeast-1-ng` - `dev`, `aws`, `us-east-1-ng` -> `dev-us-east-1-ng` ## Inputs Common `additionalArgs` fields: - `imageRegistry`: container registry prefix - `imageTag`: nextgen-metering-server image tag - `bucket`: storage bucket/container used by metering - `startTime`: Unix timestamp for metering start Optional common fields: - `taskInterval`, default `15` - `delayMinutes`, default `5` - `reporterInterval`, default `30` in prod and `60` outside prod - `enablePprof`, default `true` outside prod and `false` in prod - `featureGateFilter`, default omitted - `plan`, default omitted; used for BYOC when set to `byoc` AWS fields: - `irsaRoleArn`: ServiceAccount role annotation - `meteringRoleArn`, optional; when set, the script adds `nextGenMetering.roleArn` and `storageOptions.AWS_IAM_ROLE_ARN` Alicloud fields: - `awsReporterRoleArn`: AWS role used by the reporter through web identity - `bucketEndpoint`, optional; default `https://oss-.aliyuncs.com` - `ramSecretKey`, optional; default `metering-ram-key` Azure fields: - `azureWorkloadIdentityClientID`: ServiceAccount workload identity client ID - `azureStorageAccountName`: Azure storage account name - `bucketEndpoint`: Azure Blob endpoint - `awsReporterRoleArn`: AWS role used by the reporter through web identity ## Generated Files All providers generate: - `kustomization.yaml` - `service-account.yaml` - `service.yaml` - `serviceconfig.yaml` - `statefulset.yaml` Alicloud also generates: - `externalsecret.yaml` AWS uses EKS IRSA on the ServiceAccount and AWS region env vars in the StatefulSet. Alicloud mounts a projected AWS web identity token, references RAM credentials from the external secret, uses Alicloud OSS endpoint configuration, and stores Delta Lake paths with the existing `s3://` format. Azure uses workload identity labels and annotations, Azure storage account env/config fields, a projected AWS web identity token for reporter access, and Delta Lake paths with the existing `azure://` format. ## Workflow Add `.github/workflows/deploy-new-region-next-gen-metering-server.yaml`. Workflow inputs: - `cloud` - `env` - `region` - `logicalRegionName` - `cluster` - `jobId` - `additionalArgs` - `author` Workflow steps: 1. Check out the repository. 2. Install `yq` and `jq`. 3. Select the work directory from `env`. 4. Use `.github/scripts/check-deployed.sh` to ensure the target cluster is not already registered for nextgen metering. 5. Write `additionalArgs` to a temporary JSON file. 6. Run `nextgen-metering-server/deploy-new-region.sh`. 7. Register the generated env and target cluster in `app-registry/nextgen-metering-server.yaml`. 8. Create an automated pull request. 9. Mark the PR approved in FAD, trigger check runs, enable automerge, and approve the PR using the same pattern as other next-gen deploy workflows. ## Error Handling The script uses `set -euo pipefail`. The script fails before writing manifests when: - Required positional arguments are missing. - `jq` is unavailable. - `yq` is unavailable. - `cloud` is not one of `aws`, `alicloud`, or `azure`. - The expected variant directory does not exist. - The target env directory already exists. - A provider-required `additionalArgs` field is missing or empty. Template replacement must fail if unreplaced `TMPL_` placeholders remain in generated files. ## Testing Add shell-based tests for the deploy script. The tests create temporary copies of the component tree, run the deploy script for one AWS, one Alicloud, and one Azure example, then assert: - The generated env directory name is correct. - Provider-specific files are present or absent correctly. - Key YAML fields match supplied arguments. - No `TMPL_` placeholders remain. - `kustomize build` succeeds for each generated overlay. The implementation should also run `kustomize build` against generated sample overlays during verification. ## Rollback Rollback is a git revert of the generated overlay and app-registry entry. The workflow and templates are inert until invoked, so reverting a bad generated region does not require changing running regions.