Bicep decorator - Azure Glossary

Understand the concept

In plain English

A Bicep decorator is an annotation that you place above a declaration to add rules, descriptions, or behavior. Decorators start with the at sign, such as description, allowed, secure, minLength, or batchSize. They make Bicep files easier to understand and safer to use because parameters can be constrained, sensitive values can be marked, and looped resources can deploy in batches. They are small pieces of syntax, but they often explain how a template should be operated.

Why it matters

Bicep decorator matters because good infrastructure code needs more than resource declarations. Operators need to know which values are allowed, which parameters are sensitive, why a module exists, and whether many resources should deploy in parallel or sequentially. Decorators make those expectations visible in the template itself. They reduce tribal knowledge, improve documentation, and help CI catch invalid input earlier. The risk is careless decoration: a misleading description, overly broad allowed list, or missing secure marker can make a template look governed while leaving reviewers without real protection. This keeps architecture decisions visible for reviewers, helps support teams understand intended behavior, and gives release managers evidence before approving changes.

Official wording and source

A Bicep decorator adds metadata, validation, constraints, or deployment behavior to a declaration such as a parameter, resource, module, output, type, variable, or function. Microsoft Learn places it in Bicep file structure and syntax; operators confirm scope, configuration, dependencies, and production impact.

Open Microsoft Learn

Technical context

Technically, decorators are written as @expression above supported Bicep elements, including parameters, variables, resources, modules, outputs, functions, and user-defined types. Available decorators depend on the element and data type. Examples include @description for documentation, @allowed for accepted parameter values, @secure for sensitive parameters or outputs, and @batchSize for serializing looped resource or module deployments. Decorators compile into ARM template metadata or deployment behavior where supported, while also improving editor validation and review context. Reviewers should confirm scope, generated ARM JSON, permissions, and deployment results before approving production use.

Exam context

Compare with

ARM template Deployment stack

Where it is used

Where you see it

You see Bicep decorators as at-sign lines above parameters, resources, modules, outputs, variables, functions, or user-defined types in shared templates. Operators use this evidence during release review.
You see their effects in editor validation, generated ARM metadata, deployment input restrictions, secure parameter handling, and batched loop deployment behavior. Operators use this evidence during release review.
You see decorator mistakes during reviews when descriptions are stale, secure markers are missing, or allowed SKU lists no longer match platform standards. Operators use this evidence during release review.

Common situations

Standardize Azure infrastructure as code across teams and environments.
Reduce manual portal configuration by making deployment behavior reviewable and repeatable.
Support CI checks that catch template problems before production changes.
Create clearer handoffs between platform modules, application teams, and operations runbooks.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Scenario 01 Energy platform parameter guardrails Scenario, objectives, solution, measured impact, and takeaway.

Scenario

SolaraGrid Energy let project teams deploy storage and analytics resources, but wrong SKU and region values repeatedly caused failures.

Goals

Constrain allowed deployment inputs.
Improve self-service module documentation.
Reduce failed deployments caused by invalid parameters.
Keep region and SKU choices aligned with architecture standards.

Approach using Bicep decorator

The platform team added Bicep decorators to shared modules, including allowed values for supported SKUs, minLength and maxLength for names, and descriptions for every public parameter. Secure decorators were added to sensitive parameters. CI ran lint and build to verify syntax, while a sample deployment what-if validated the constrained values. The team paired decorators with Azure Policy so local guidance and cloud enforcement pointed to the same standard. The team documented ownership, rollback steps, and approval evidence so operators could distinguish intentional template behavior from configuration drift. Pipeline checks compared expected deployment output with actual Azure inventory before the release was marked complete. Runbooks were updated with validation commands, known failure modes, and the escalation path for production changes.

Potential outcomes

Reduced invalid-parameter deployment failures by 76 percent.
Cut onboarding questions for self-service modules by half.
Improved policy compliance for storage deployments to 98 percent.
Reduced pull request comments about missing parameter context by 61 percent.

What to learn

Bicep decorators make module expectations visible at the exact point where users provide deployment input.

Scenario 02 Hospital secure output handling Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Morningside Medical Center used Bicep modules that returned generated connection details, creating concern about sensitive values in deployment history.

Goals

Prevent sensitive module outputs from appearing in logs.
Preserve automation that needed nonsecret resource identifiers.
Document safe and unsafe output patterns.
Pass internal security review for infrastructure pipelines.

Approach using Bicep decorator

The cloud team reviewed every module output and separated secret material from operational identifiers. Bicep secure decorators were applied where supported for sensitive outputs, while secrets were moved to Key Vault access flows. Description decorators explained each remaining output consumer. Build and lint ran in CI, and deployment logs were sampled to verify that sensitive values were no longer visible. Security reviewers approved a new checklist for future modules. The team documented ownership, rollback steps, and approval evidence so operators could distinguish intentional template behavior from configuration drift. Pipeline checks compared expected deployment output with actual Azure inventory before the release was marked complete. Runbooks were updated with validation commands, known failure modes, and the escalation path for production changes.

Potential outcomes

Removed seven sensitive plaintext outputs from deployment history.
Kept 14 nonsecret outputs available for downstream automation.
Passed pipeline security review without delaying the release.
Reduced manual secret handling steps by 80 percent.

What to learn

Decorators are most valuable when they express security intent and are backed by secret-management design.

Scenario 03 Food distributor batched rollout Scenario, objectives, solution, measured impact, and takeaway.

Scenario

HarborFoods Distribution deployed hundreds of similar warehouse network rules, but parallel deployment caused throttling during monthly expansion releases.

Goals

Reduce provider throttling during looped deployments.
Keep warehouse rule templates reusable.
Give operations predictable rollout timing.
Avoid manual staging scripts outside Bicep.

Approach using Bicep decorator

Engineers added a batchSize decorator to the looped Bicep resource that created warehouse firewall and routing rules. The same module kept descriptions on parameters and allowed values for supported warehouse tiers. CI built the template and what-if showed the full planned change set before release. Operations accepted the slightly longer deployment because each batch was predictable, logged, and tied to the same Bicep module rather than external scripts. The team documented ownership, rollback steps, and approval evidence so operators could distinguish intentional template behavior from configuration drift. Pipeline checks compared expected deployment output with actual Azure inventory before the release was marked complete. Runbooks were updated with validation commands, known failure modes, and the escalation path for production changes.

Potential outcomes

Reduced throttling-related deployment failures from 23 percent to 3 percent.
Kept monthly expansion releases within the approved maintenance window.
Removed two custom retry scripts from the release process.
Improved operator confidence through clear batch progress in deployment logs.

What to learn

Bicep decorators can affect both human understanding and deployment behavior when used deliberately.

Azure CLI

CLI validation proves decorator syntax and compiled behavior before a small annotation creates a failed or misleading production deployment.

Useful for

Build and lint templates to confirm decorators are valid for the declaration where they are used.
Run what-if after decorator changes that affect deployment behavior, such as batchSize on looped resources.
Capture generated ARM JSON when reviewers need to see how decorators become metadata or constraints.

Before you run a command

Confirm the active tenant, subscription, resource group, deployment scope, and parameter file before running Bicep commands.
Check the installed Bicep CLI version and whether external modules must be restored from a registry.
Run commands from the repository folder that should control bicepconfig.json resolution and relative module paths.
Make sure the pipeline or user identity has only the permissions needed for restore, what-if, and deployment.

What the output tells you

Build output shows whether the Bicep source compiles into valid ARM JSON and whether module restore succeeded.
Lint output identifies syntax, rule, naming, cleanup, or maintainability issues before a deployment touches Azure.
What-if output shows which Azure resources would be created, modified, skipped, or deleted for the current parameters.
Deployment output or query results show the resource IDs, endpoints, or module values returned after a completed deployment.

Mapped commands

Bicep decorator validation and operations

direct

az bicep version

az bicepdiscoverManagement and Governance

az bicep build --file main.bicep

az bicepprovisionManagement and Governance

az bicep lint --file main.bicep

az bicepdiscoverManagement and Governance

az deployment group what-if --resource-group <resource-group> --template-file main.bicep

az deployment groupdiscoverManagement and Governance

Architecture context

Technically, decorators are written as @expression above supported Bicep elements, including parameters, variables, resources, modules, outputs, functions, and user-defined types. Available decorators depend on the element and data type. Examples include @description for documentation, @allowed for accepted parameter values, @secure for sensitive parameters or outputs, and @batchSize for serializing looped resource or module deployments. Decorators compile into ARM template metadata or deployment behavior where supported, while also improving editor validation and review context. Reviewers should confirm scope, generated ARM JSON, permissions, and deployment results before approving production use.

Security: Security value comes from using decorators to label and constrain sensitive infrastructure inputs. Secure decorators should protect passwords, tokens, connection strings, and sensitive outputs from exposure in logs or deployment history where supported. Allowed values, min and max length rules, and descriptions can steer users away from insecure SKUs or naming patterns. Reviewers should confirm decorators match actual policy requirements. Do not rely only on decorators for enforcement; combine them with Azure Policy, Key Vault integration, least privilege pipeline identities, and secret scanning. Security teams should pair the pattern with least privilege, policy checks, repository review, and controlled parameters in shared pipelines.
Cost: Cost impact appears when decorators constrain expensive choices and document financial intent. Allowed SKU lists can prevent accidental use of premium resources in development. Description text can explain when high availability, replicas, or diagnostics are required. Batch controls may reduce throttling-related retries and failed deployments, saving engineering time. Decorators do not replace budgets or policy, but they make cost-aware defaults easier to enforce at template entry points. Review allowed values after pricing, region, or service tier changes so old constraints do not mislead teams. Cost owners should review defaults, environment parameters, and what-if output because small template changes can multiply across many deployments.
Reliability: Reliability improves when decorators prevent invalid or risky deployment input before Azure Resource Manager receives the template. Parameter constraints reduce failed deployments caused by wrong names, unsupported regions, bad SKUs, or empty values. Batch-size decorators can make large looped deployments safer by limiting parallel changes. Descriptions help operators understand dependencies during incidents. Reliability suffers when decorators are copied without checking resource-specific limits. Keep decorators aligned with current service capabilities, and test boundary values during module updates. Reliable teams also rehearse rollback, check generated resources after deployment, and document how downstream modules behave when the pattern changes. Reliable teams also rehearse rollback, check generated resources after deployment, and document how downstream modules behave when the pattern changes.
Performance: Performance depends on how decorators shape deployment behavior and template usability. Batch-size decorators can slow a deployment by making looped resources deploy serially, but they may prevent throttling and increase successful completion. Parameter constraints and descriptions improve authoring performance by catching bad input before a pipeline runs. Secure and metadata decorators have little runtime impact, but they improve review speed. For large modules, use decorators selectively: enough to guide users and reduce mistakes, not so many that the file becomes hard to scan. Performance reviewers should compare pipeline duration, provider throttling, generated template size, and runtime impact before scaling the pattern broadly.
Operations: Operationally, decorators act as built-in guidance for anyone reading or running a Bicep file. They support code review, self-service platform modules, template documentation, and pipeline validation. Teams should require useful descriptions on shared modules and clear constraints on public parameters. When a production incident traces back to bad input, update decorators and tests so the failure cannot recur. For looped resources, document why batch size is chosen. Keep decorators concise so they inform operators instead of becoming ignored boilerplate. Operators should keep examples, expected outputs, owner contacts, and troubleshooting steps near the repository that deploys the template. Operators should keep examples, expected outputs, owner contacts, and troubleshooting steps near the repository that deploys the template.

Common mistakes

Adding descriptions that sound helpful but no longer match what the resource or module does.
Forgetting secure decorators on sensitive parameters or outputs that may appear in deployment records.
Using allowed lists that block valid current SKUs or allow outdated unsafe choices.