# Deployment Modes

When deploying Bicep templates through Bluebricks, you can choose between two deployment modes: **Complete** and **Incremental**. Each mode has different behavior for resource lifecycle management.

## Complete mode (default)

### How it works

* Creates or updates resources defined in the template
* **Deletes any resources in the resource group that are not in the template**
* Provides full lifecycle management (create, update, destroy)

### When to use Complete mode

**Standard Bluebricks deployments:**

* Bluebricks auto-generates a unique resource group per deployment (e.g., `rg-myapp-a1b2c`)
* The blueprint owns the entire resource group
* Safe cleanup on destroy operations
* Full control over all resources in the scope

**Benefits:**

* Clean destroy behavior removes all resources when the blueprint is uninstalled
* Prevents orphaned resources
* Simplifies cost management

### Example configuration

```json
{
  "name": "azure-vm",
  "native": {
    "type": "bicep",
    "path": ".",
    "mode": "Complete"
  },
  "props": {
    "location": {"type": "string"}
  }
}
```

Bluebricks creates a dedicated resource group, deploys resources, and can safely clean up everything on uninstall.

## Incremental mode

### How it works

* Creates or updates resources defined in the template
* **Never deletes resources** (even if removed from template)
* Resources remain in Azure when removed from the Bicep template
* Requires manual cleanup for decommissioned resources

### When to use Incremental mode

**Shared resource group scenarios:**

* Multiple teams or blueprints deploy to the same resource group
* Need to preserve existing resources not managed by this blueprint
* Adding resources to existing infrastructure

**User-provided resource groups:**

* User specifies an existing resource group name
* Resource group contains resources from other sources
* Cannot take full ownership of the resource group

### Example configuration

```json
{
  "name": "add-vm-to-existing-rg",
  "native": {
    "type": "bicep",
    "path": ".",
    "mode": "Incremental"
  },
  "props": {
    "resourceGroup": {"type": "string", "required": true},
    "location": {"type": "string"}
  }
}
```

Deploys to an existing resource group without affecting other resources. Manual cleanup required on uninstall.

## Decision matrix

Choose the right deployment mode based on your scenario:

| Scenario                       | Mode        | Resource group strategy          |
| ------------------------------ | ----------- | -------------------------------- |
| Standard Bluebricks deployment | Complete    | Auto-generated                   |
| User-provided shared RG        | Incremental | User-provided                    |
| User-provided RG (sole owner)  | Complete    | User-provided (use with caution) |
| Multiple teams, same RG        | Incremental | User-provided                    |

## Resource group management

### Complete mode with auto-generated resource groups

**Configuration:**

* Do not provide a `resourceGroup` parameter
* Bluebricks generates a unique RG name based on the deployment
* Full lifecycle management enabled

**Workflow:**

1. User deploys blueprint
2. Bluebricks creates `rg-<blueprint>-<hash>`
3. Resources deployed to the dedicated RG
4. On uninstall: all resources cleaned up automatically

### Incremental mode with user-provided resource groups

**Configuration:**

* Provide `resourceGroup` parameter as a required property
* User specifies an existing RG name during deployment
* Manual cleanup process required

**Workflow:**

1. User deploys blueprint and specifies an existing RG
2. Resources added to the specified RG
3. Other resources in the RG remain untouched
4. On uninstall: resources remain, manual cleanup needed

## Important considerations

### Complete mode risks

When a user provides an existing resource group name and Complete mode is active:

* All resources in that RG not defined in the template will be deleted
* This includes resources from other teams, manual deployments, or other blueprints

{% hint style="danger" %}
Use Incremental mode when deploying to user-provided resource groups. Reserve Complete mode for Bluebricks-managed (auto-generated) resource groups.
{% endhint %}

### Incremental mode trade-offs

**Orphaned resources:**

* Resources removed from the template remain in Azure
* Increases cost over time if not manually cleaned
* Requires a decommission process

**Cost management:**

* Bluebricks calculates cost based on blueprint definitions
* Orphaned resources are not reflected in Bluebricks cost tracking
* Manual reconciliation required

## Referencing external resources

Both modes support referencing resources from other resource groups without managing them.

### Example: VM with existing VNet

```bicep
param virtualNetworkResourceGroup string
param virtualNetworkName string
param subnetName string

var subnetRef = resourceId(
  virtualNetworkResourceGroup,
  'Microsoft.Network/virtualNetworks/subnets',
  virtualNetworkName,
  subnetName
)

resource nic 'Microsoft.Network/networkInterfaces@2023-06-01' = {
  name: 'myNic'
  properties: {
    ipConfigurations: [{
      properties: {
        subnet: { id: subnetRef }
      }
    }]
  }
}
```

The VNet exists in `virtualNetworkResourceGroup`, but the NIC is created in the deployment's resource group. Complete mode only affects resources in the deployment's resource group.

## Cost management

### Complete mode

* Bluebricks tracks all resources in the deployment
* Cost calculation accurate
* Uninstall frees up environment budget immediately

### Incremental mode

* Bluebricks tracks resources at deployment time
* Orphaned resources not reflected in cost tracking
* Manual reconciliation required for accurate costs
* Budget freed only after manual resource cleanup

## See also

* [Bicep](/docs/orchestration/packages/artifacts-overview/bicep.md): artifact overview, parameter mapping, and CLI workflow
* [Packages](/docs/orchestration/packages.md): artifact types and packaging concepts


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/orchestration/packages/artifacts-overview/bicep/bicep-deployment-modes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.