Validate against Azure

hulk plan answers: “Will Azure accept this Hulk project in the selected environment, and what would change?”

It adds Azure Resource Manager preflight validation to the same project preparation pipeline used by hulk check, hulk synth, and hulk transpile.

az login
hulk plan ./main.json --env dev

The resource group and subscription are read from the selected Hulk environment. No deployment is created and .hulk is not replaced.

What the command does

hulk plan performs these steps in order:

Loads and interpolates the selected Hulk environment.
Resolves modules, applies skip_envs, and validates Hulk resource identities and references.
Renders fresh Bicep into a temporary directory.
Reads the subscription and resource group from the selected environment.
Submits either ARM validation or ARM what-if using that temporary Bicep file.
Removes the temporary output after the operation unless --keep-artifacts is set.

Without --what-if, Hulk runs the equivalent of az deployment group validate. With --what-if, it runs only az deployment group what-if; ARM already includes preflight validation in what-if, so submitting both requests would duplicate work.

Validation levels

The default validation level is provider-no-rbac. Use --validation-level provider when permission validation is also required, or template for Azure-side static validation only.

hulk plan ./main.json \
  --env prod \
  --validation-level provider

Level	What Azure checks	When to use it
`provider-no-rbac`	Template and provider configuration, with read-permission checks instead of full deployment-permission checks	Default for pull requests and developer validation
`provider`	Template, providers, dependencies, and deployment permissions	Release gates using the deployment identity
`template`	Azure-side template structure and expressions only	Restricted identities or fast static validation

Provider validation is best effort. It catches many failures before deployment, including unsupported API versions, invalid provider configuration, naming conflicts, incorrect scopes, and missing provider registration, but some failures can only occur while a resource is being created.

Why use `hulk plan` instead of calling ARM directly?

A raw ARM command starts from an existing Bicep or ARM JSON file. A Hulk project starts earlier, with environment-aware JSON, modules, variables, skip rules, and references. Calling ARM directly therefore requires a manual multi-command flow:

hulk transpile ./main.json --env prod --require-bicep

az deployment group validate \
  --subscription <subscription-from-main-json> \
  --resource-group <resource-group-from-main-json> \
  --template-file .hulk/main.bicep \
  --validation-level ProviderNoRbac

hulk plan ./main.json --env prod wraps that validation boundary while adding several safeguards:

It rejects invalid Hulk configuration before making a network request.
It always generates a fresh template, eliminating accidental validation of stale .hulk output.
It takes the subscription and resource group from the selected environment instead of duplicating them in shell scripts.
It uses provider-no-rbac by default, which is better suited to developer and pull-request identities.
It does not publish partial or validation-only artifacts.
With --what-if, it avoids a redundant standalone ARM validation request.

This makes Hulk’s command safer and more convenient for Hulk projects; it does not make ARM’s underlying validation more powerful. Hulk delegates the final preflight and what-if operations to Azure Resource Manager.

What-if preview

Add --what-if to show the resource changes Azure predicts:

hulk plan ./main.json --env prod --what-if

What-if does not modify resources. Its output is a prediction and can contain noise when ARM cannot determine whether a runtime expression will change. Review the result before deploying; a successful what-if is not a guarantee that deployment-time operations will succeed.

Inspect generated Bicep

Use --keep-artifacts to retain the Bicep submitted to Azure, whether validation succeeds or fails:

hulk plan ./main.json --env prod --keep-artifacts
hulk plan ./main.json --env prod --what-if --keep-artifacts

Hulk prints the retained directory’s absolute path before rendering. The option keeps the generated template and modules without replacing .hulk/ or changing validation results. See Debugging generated Bicep for details and cleanup.

When native ARM commands are the better fit

Use az deployment group validate or az deployment group what-if directly when:

The input is already Bicep or ARM JSON rather than a Hulk project.
You need explicit parameter files or command-line parameter overrides.
You are validating subscription, management-group, tenant, deployment-stack, or template-spec workflows.
You need the complete native Azure CLI output for another automation.
You intentionally want to validate an existing generated template instead of regenerating it.

Use az deployment group create for the actual deployment. hulk plan is intentionally non-mutating.

plan requires Azure CLI authentication. For fast editor or CI feedback that does not contact Azure, use hulk check.