Enhance address space handling to accept numeric CIDR masks

[JC-wk]

Resolves #4733

What is being addressed

Describe the current behavior you are modifying. Please also remember to update any impacted documentation.

How is this addressed

• Accepts cidr values as strings from "16" to "29" for subnet creation
• Updates documentation
• Updates CHANGELOG.md
• Updates API version
• Adds Tests

[github-actions]

Unit Test Results

735 tests   735 ✅  8s ⏱️
  1 suites    0 💤
  1 files      0 ❌

Results for commit 8280ea2.

♻️ This comment has been updated with latest results.

[JC-wk]

I've tested allocating a /27 and that worked in my environment

[Copilot]

Pull request overview

Adds support in the API for requesting auto-assigned address spaces using numeric CIDR prefix lengths (as strings), extending beyond the existing small/medium/large presets while keeping backwards compatibility.

Changes:

• Extend address space allocation logic to accept numeric CIDR masks (string values) and validate allowed ranges.
• Add repository tests for numeric CIDR prefix requests.
• Update workspace authoring documentation and the project changelog to describe the new behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/tre-workspace-authors/authoring-workspace-templates.md	Documents numeric CIDR mask support for address_space_size when requesting additional address spaces.
CHANGELOG.md	Records the enhancement in the unreleased changelog.
api_app/tests_ma/test_db/test_repositories/test_workpaces_repository.py	Adds tests covering successful numeric CIDR prefix requests.
api_app/models/schemas/workspace_template.py	Updates sample schema description text to mention numeric CIDR masks.
api_app/db/repositories/workspaces.py	Implements numeric CIDR prefix parsing/validation and routes it into new CIDR allocation.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (6)

templates/workspaces/airlock-import-review/template_schema.json:53

• The address_space_size description is ambiguous: it reads like an IP CIDR (e.g. 10.2.1.0/25) could be provided as the value, but the schema expects either a preset/numeric mask or the literal custom (with the CIDR provided separately via the address_space property). Rewording this to match the enum and the custom behavior would prevent user confusion.

        "medium",
        "large",
        "custom"
      ]
    },

api_app/models/schemas/workspace_template.py:77

• The schema_extra example for address_space_size is ambiguous about where the explicit CIDR should be supplied for custom. Aligning this wording with the address_space property (defined just below) would make the API docs less confusing.

                        "address_space_size": {
                            "type": "string",
                            "title": "Address space size",
                            "description": "Network address size as a CIDR value or (small /24, medium /22, large /16 or custom with an IP range e.g. 10.2.1.0/25) to be used by the workspace."
                        },

templates/workspaces/base/template_schema.json:53

• The address_space_size description is ambiguous: it reads like an IP CIDR (e.g. 10.2.1.0/25) could be provided as the value, but the schema expects either a preset/numeric mask or the literal custom (with the CIDR provided separately via the address_space property). Rewording this to match the enum and the custom behavior would prevent user confusion.

    "address_space_size": {
      "type": "string",
      "title": "Address space size",
      "description": "Network address size as a CIDR value or (small /24, medium /22, large /16 or custom with an IP range e.g. 10.2.1.0/25) to be used by the workspace.",
      "default": "small",

templates/workspaces/unrestricted/template_schema.json:45

• The address_space_size description is ambiguous: it reads like an IP CIDR (e.g. 10.2.1.0/25) could be provided as the value, but the schema expects either a preset/numeric mask or the literal custom (with the CIDR provided separately via the address_space property). Rewording this to match the enum and the custom behavior would prevent user confusion.

    "address_space_size": {
      "type": "string",
      "title": "Address space size",
      "description": "Network address size as a CIDR value or (small /24, medium /22, large /16 or custom with an IP range e.g. 10.2.1.0/25) to be used by the workspace.",
      "default": "small",

api_app/models/schemas/workspace_template.py:25

• This sample address_space_size description is ambiguous about where the explicit CIDR (e.g. 10.2.1.0/24) should be provided. Since custom relies on the separate address_space property, clarifying the wording here would better match the API behavior and the schema examples below.

            "address_space_size": Property(
                type="string",
                default="small",
                description="Network address size as a CIDR value or (small /24, medium /22, large /16 or custom with an IP range e.g. 10.2.1.0/25) to be used by the workspace.")
        },

api_app/tests_ma/test_db/test_repositories/test_workpaces_repository.py:442

• These new numeric-CIDR tests use basic_workspace_request (a workspace create model), which implies sizes like /29 are valid for workspaces even though the bundled workspace template schemas only allow numeric masks down to /24. Since get_address_space_based_on_size is also used for workspace-service address space allocation, consider making these tests pass a plain properties dict so they clearly exercise the shared allocation logic without implying workspace-template support for /29.

async def test_get_address_space_based_on_size_with_string_19(workspace_repo, basic_workspace_request):
    workspace_to_create = basic_workspace_request
    # request a /19
    workspace_to_create.properties["address_space_size"] = "19"
    address_space = await workspace_repo.get_address_space_based_on_size(workspace_to_create.properties)

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (6)

templates/workspaces/base/template_schema.json:52

• The schema enum values are CIDR prefix lengths (e.g. "23"), but the description says "CIDR value", which can be misread as requiring a full CIDR (like 10.0.0.0/23). Consider clarifying that the numeric options are prefix lengths, and that "custom" uses the separate address_space field.

      "description": "Network address size as a CIDR value or (small /24, medium /22, large /16 or custom with an IP range e.g. 10.2.1.0/25) to be used by the workspace.",

templates/workspaces/unrestricted/template_schema.json:44

• The schema enum values are CIDR prefix lengths (e.g. "23"), but the description says "CIDR value", which can be misread as requiring a full CIDR (like 10.0.0.0/23). Consider clarifying that the numeric options are prefix lengths, and that "custom" uses the separate address_space field.

      "description": "Network address size as a CIDR value or (small /24, medium /22, large /16 or custom with an IP range e.g. 10.2.1.0/25) to be used by the workspace.",

templates/workspaces/airlock-import-review/template_schema.json:36

• The schema enum values are CIDR prefix lengths (e.g. "23"), but the description says "CIDR value", which can be misread as requiring a full CIDR (like 10.0.0.0/23). Consider clarifying that the numeric options are prefix lengths, and that "custom" uses the separate address_space field.

      "description": "Network address size as a CIDR value or (small /24, medium /22, large /16 or custom with an IP range e.g. 10.2.1.0/25) to be used by the workspace.",

api_app/models/schemas/workspace_template.py:26

• This description is used in the sample workspace template schema, but it’s ambiguous about what the numeric values represent and doesn’t explicitly tie the "custom" case to the separate address_space field. Clarifying it as a CIDR prefix length (e.g. "23") and explicitly referencing address_space would make the API example clearer.

            "address_space_size": Property(
                type="string",
                default="small",
                description="Network address size as a CIDR value or (small /24, medium /22, large /16 or custom with an IP range e.g. 10.2.1.0/25) to be used by the workspace.")
        },

api_app/models/schemas/workspace_template.py:77

• The example JSON schema description says "CIDR value", which can be misread as requiring a full CIDR range rather than a prefix length string ("23"). Consider clarifying this text to match how address_space_size is actually supplied (prefix length) and to explicitly reference address_space for the custom case.

                        "address_space_size": {
                            "type": "string",
                            "title": "Address space size",
                            "description": "Network address size as a CIDR value or (small /24, medium /22, large /16 or custom with an IP range e.g. 10.2.1.0/25) to be used by the workspace."
                        },

docs/tre-workspace-authors/authoring-workspace-templates.md:113

• This sentence mentions a "numeric CIDR mask"; the numeric value here is actually a CIDR prefix length (e.g. "25"). Also, the final sentence refers specifically to "Workspace templates" even though this section is about workspace services—consider making it generic to "template JSON Schemas" to avoid confusion.

This parameter accepts the presets `small` (/24), `medium` (/22), `large` (/16), the literal value `custom` together with an explicit `address_space` CIDR (e.g. `10.2.1.0/25`), or (for workspace services) a numeric CIDR mask as a string from "16" to "29" (e.g. `"25"`) to ask the system to auto-select an available `/25`. Workspace templates may further restrict the allowed values via their JSON Schema.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (4)

templates/workspaces/base/porter.yaml:4

• Allowing additional address_space_size values is new bundle functionality, so this should be a minor version bump rather than a patch bump. Please use 2.11.0; patch versions are reserved for backward-compatible fixes.

version: 2.10.1

api_app/_version.py:1

• This API change adds a new supported input capability, so it requires a minor version bump under semantic versioning rather than a patch bump. Please use 0.27.0; patch versions are reserved for backward-compatible fixes.

__version__ = "0.26.1"

templates/workspaces/unrestricted/porter.yaml:4

• Allowing additional address_space_size values is new bundle functionality, so this should be a minor version bump rather than a patch bump. Please use 0.15.0; patch versions are reserved for backward-compatible fixes.

version: 0.14.1

templates/workspaces/airlock-import-review/porter.yaml:4

• Allowing additional address_space_size values is new bundle functionality, so this should be a minor version bump rather than a patch bump. Please use 0.17.0; patch versions are reserved for backward-compatible fixes.

version: 0.16.1

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/tre-workspace-authors/authoring-workspace-templates.md:113

• The parenthetical says numeric masks are only for workspace services, but this PR also adds numeric values to all three bundled workspace schemas (there they are limited to 16–24). Please distinguish the two ranges so template authors do not conclude that workspaces cannot use numeric masks.

This parameter accepts the presets `small` (/24), `medium` (/22), `large` (/16), the literal value `custom` together with an explicit `address_space` CIDR (e.g. `10.2.1.0/25`), or (for workspace services) a numeric CIDR mask as a string from "16" to "29" (e.g. `"25"`) to ask the system to auto-select an available `/25`. Workspace templates may further restrict the allowed values via their JSON Schema.

api_app/db/repositories/workspaces.py:181

• These new InvalidInput branches are also reached from workspace-service creation, but create_workspace_service calls this method outside its exception-handling block (api_app/api/routes/workspaces.py:265). Consequently, an out-of-range numeric mask (or the new unknown-preset branch below) returns HTTP 500 for workspace services instead of a client error; workspace creation already maps the same exception to 422. Catch and translate InvalidInput in the workspace-service route, and add a route-level regression test.

            if cidr_netmask < 16 or cidr_netmask > 29:
                raise InvalidInput("'address_space_size' numeric value must be between 16 and 29")

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/tre-workspace-authors/authoring-workspace-templates.md:115

• A /29 contains six conventional host addresses, but Azure reserves the first four and last address of every subnet, leaving only three addresses assignable to resources. Stating six usable addresses can cause workspace-service authors to under-size Azure subnets.

Depending on the workspace service you are deploying you may configure a template with a CIDR up to "29" which only has 6 usable IP addresses.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/tre-workspace-authors/authoring-workspace-templates.md:115

• Remove the duplicated “only” in this sentence.

Depending on the workspace service you are deploying you may configure a template with a CIDR up to "29" which only has only 3 usable IP addresses as Azure reserves the first four and last address of every subnet.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

[maxmartin-cgi]

/test-extended

[github-actions]

🤖 pr-bot 🤖

🏃 Running extended tests: https://github.com/microsoft/AzureTRE/actions/runs/31003421731 (with refid c0294657)

(in response to this comment from @maxmartin-cgi)