Skip to content

Forge v1 to v2

This guide outlines the changes required to migrate from v1 to v2 for APIs and Web Applications.

Overview

The v2 templates introduce significant improvements including:

  • Updated Terraform module versions with blue-green deployment support
  • Simplified Azure DevOps pipeline parameters
  • Removal of application code deployed with infrastructure in favor of deployment slots

API Applications Migration

1. Azure DevOps Pipeline Changes

Main Pipeline (azure-pipelines-api.yml)

Template Reference:

# v1
extends:
  template: azure-dotnet-api.yml@templates

# v2
extends:
  template: azure-dotnet-api-v2.yml@templates

Parameters - Removed:

  • DeploymentEnvironments
  • BusinessDomain
  • ApiType

Parameters - Renamed:

# v1 → v2
ApplicationName → applicationName
ProjectId → projectId
OpenAPIFileName → openAPIFileName

Parameters - Added:

dotNetVersion: '9.x' # Specifies .NET 9 runtime

PR Pipeline (azure-pipelines-api-pr.yml)

Template Reference:

# v1
extends:
  template: azure-dotnet-api-pr.yml@templates

# v2
extends:
  template: azure-dotnet-api-pr-v2.yml@templates

Parameters - Same changes as main pipeline, plus:

# (when hasFrontEnd: true)
nodeVersion: '20.x' # Added for projects with frontend components

2. Terraform Infrastructure Changes

Module Version Update (app.generated.tf)

# v1
module "saif-appservices" {
  source  = "app.terraform.io/SAIFCorp/saif-apiservice/azure"
  version = ">=1.0.0, <2.0.0"

# v2
module "saif-appservices" {
  source  = "app.terraform.io/SAIFCorp/saif-apiservice/azure"
  version = ">=2.0.0, <3.0.0"

Variable Changes

Removed Variables:

# Remove this variable - no longer needed
variable "DockerImageTag" {
  type        = string
  description = "The tag of the Docker image to deploy"
  default     = ""
}

Added Variables:

# Add this variable for blue-green deployments
variable "createStagingSlot" {
  type        = bool
  description = "Whether to create a secondary slot for the application"
  default     = false
}

Module Parameter Changes:

# v1
module "saif-appservices" {
  # ... other parameters
  DockerImageTag = var.DockerImageTag  # Remove this line
  SystemAPIType  = local.Variables.SystemAPIType # Remove this line, if it exists
}

# v2
module "saif-appservices" {
  # ... other parameters
  createStagingSlot = var.createStagingSlot  # Add this line
}

3. NuGet Package Updates

Project File Changes

  • v2 Package List:
  • SAIF.Platform.Azure
<!-- v1 -->
<PackageReference Include="SAIF.Platform.Azure" Version="1.0.*" />

<!-- v2 -->
<PackageReference Include="SAIF.Platform.Azure" Version="2.0.3" />

Web Applications Migration

1. Azure DevOps Pipeline Changes

Main Pipeline (azure-pipelines-web.yml)

Template Reference:

# v1
extends:
  template: azure-react-web.yml@templates

# v2
extends:
  template: azure-react-web-v2.yml@templates

Parameters - Removed:

  • DeploymentEnvironments
  • WorkingDirectory

Parameters - Renamed:

# v1 → v2
ApplicationName → applicationName
ProjectId → projectId
FrontendProjectId → frontendProjectId

Parameters - Added:

nodeVersion: '20.x' # Specifies Node.js 20 runtime

PR Pipeline (azure-pipelines-web-pr.yml)

Template Reference:

# v1
extends:
  template: azure-react-web-pr.yml@templates

# v2
extends:
  template: azure-react-web-pr-v2.yml@templates

Parameters - Removed:

  • WorkingDirectory
  • ArtifactName

Parameters - Added:

dotNetVersion: '9.x' # Added for backend components
nodeVersion: '20.x' # Specifies Node.js 20 runtime

2. Terraform Infrastructure Changes

Module Version Update (web.generated.tf)

# v1
module "saif-webapp" {
  source  = "app.terraform.io/SAIFCorp/saif-webapp/azure"
  version = ">=1.0.0, <2.0.0"

# v2
module "saif-webapp" {
  source  = "app.terraform.io/SAIFCorp/saif-webapp/azure"
  version = ">=2.0.0, <3.0.0"

Variable Changes

Removed Variables:

# Remove this variable - no longer needed
variable "DockerImageTag" {
  type        = string
  description = "The tag of the Docker image to deploy"
  default     = ""
}

Added Variables:

# Add this variable for blue-green deployments
variable "createStagingSlot" {
  type        = bool
  description = "Whether to create a secondary slot for the application"
  default     = false
}

Module Parameter Changes:

# v1
module "saif-webapp" {
  # ... other parameters
  DockerImageTag = var.DockerImageTag  # Remove this line
}

# v2
module "saif-webapp" {
  # ... other parameters
  createStagingSlot = var.createStagingSlot  # Add this line
}

Migration Checklist

For API Projects

  • Update pipeline template references to -v2 versions
  • Rename pipeline parameters to camelCase
  • Remove deprecated parameters (DeploymentEnvironments, BusinessDomain, ApiType)
  • Add dotNetVersion: '9.x' parameter
  • Add nodeVersion: '20.x' for projects with frontend (when hasFrontEnd: true)
  • Update Terraform module version to >=2.0.0, <3.0.0
  • Remove DockerImageTag variable and parameter
  • Add createStagingSlot variable and parameter
  • Update SAIF.Platform.Azure package to version 2.0.0

For Web Projects

  • Update pipeline template references to -v2 versions
  • Rename pipeline parameters to camelCase
  • Remove deprecated parameters (DeploymentEnvironments, WorkingDirectory, ArtifactName)
  • Add dotNetVersion: '9.x' and nodeVersion: '20.x' parameters
  • Update Terraform module version to >=2.0.0, <3.0.0
  • Remove DockerImageTag variable and parameter
  • Add createStagingSlot variable and parameter