# 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](https://bluebricks.co/docs/core-concepts/packages/artifacts-overview/bicep): artifact overview, parameter mapping, and CLI workflow
* [Packages](https://bluebricks.co/docs/core-concepts/packages): artifact types and packaging concepts