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

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

Results for commit 3a1ca5f.

♻️ 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.

[JC-wk]

@JC-wk still getting:

The backend accepts 16–29 and the docs advertise up to /29, but the schema enum tops out at /24. Values like "25"–"29" will be rejected by JSON-schema validation before ever reaching the backend — directly defeating the "smaller than /24" goal from issue #4733. The Copilot reviewer flagged this on all three schemas and it remains unresolved.

Also, the new schema description text says "custom with an IP", but custom requires a CIDR (e.g. 10.2.1.0/25), not a plain IP. Minor wording fix worth making for consistency with the more accurate description in workspace_template.py / the docs.

Thanks @marrobi

1. is by design, workspaces need /24 as a minimum but workspace_service templates can request an IP Subnet smaller than /24. Have now changed the description to be /24 instead of /25

2. wording was already like that prior to this change, but now updated to
   "Network address size cidr 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."

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

api_app/models/schemas/workspace_template.py:26

• The address_space_size description mentions numeric CIDR masks but doesn't state the accepted mask range (16–29), while WorkspaceRepository.get_address_space_based_on_size enforces that range. Including the range here would make the generated schema clearer and avoid mismatched expectations.

            "address_space_size": Property(
                type="string",
                default="small",
                description="This can have a value of small, medium, large, a numeric CIDR mask (e.g. \"24\") or custom. If you specify custom, then you need to specify a VNet address space in 'address_space' (e.g. 10.2.1.0/24)")
        },

api_app/models/schemas/workspace_template.py:77

• This example JSON schema description also mentions numeric CIDR masks but doesn't specify the accepted range (16–29), even though the API enforces it. Clarifying the valid range here would make the published schema example more accurate.

                        "address_space_size": {
                            "type": "string",
                            "title": "Address space size",
                            "description": "This can have a value of small, medium, large, a numeric CIDR mask (e.g. \"24\") or custom. If you specify custom, then you need to specify a VNet address space in 'address_space' (e.g. 10.2.1.0/24)"
                        },

[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 (4)

templates/workspaces/base/template_schema.json:52

• The address_space_size description is ambiguous: it suggests passing a CIDR (e.g. "/24") or an IP range, but the schema actually expects either presets (small/medium/large), a numeric mask length as a string (e.g. "24"), or "custom" with a separate address_space CIDR. Clarifying this helps prevent users providing values that will be rejected by schema validation.

      "description": "Network address size cidr 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 address_space_size description is ambiguous: it suggests passing a CIDR (e.g. "/24") or an IP range, but the schema actually expects either presets (small/medium/large), a numeric mask length as a string (e.g. "24"), or "custom" with a separate address_space CIDR. Clarifying this helps prevent users providing values that will be rejected by schema validation.

      "description": "Network address size cidr 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 address_space_size description is ambiguous: it suggests passing a CIDR (e.g. "/24") or an IP range, but the schema actually expects either presets (small/medium/large), a numeric mask length as a string (e.g. "24"), or "custom" with a separate address_space CIDR. Clarifying this helps prevent users providing values that will be rejected by schema validation.

      "description": "Network address size cidr 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/db/repositories/workspaces.py:188

• This error message echoes raw_size without normalization, so inputs with leading/trailing whitespace (e.g. " huge ") will produce a confusing message that includes that whitespace. Using a stripped value makes the error clearer without changing behavior.

        raise InvalidInput(f"Invalid 'address_space_size': {raw_size}")

[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 (1)

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

• The new address_space_size documentation is inaccurate in two ways: (1) it says a numeric mask "16"–"29" asks the system to auto-select an available /25 (should be /{mask}), and (2) it says "Workspace templates" may restrict allowed values, but this section is about workspace service templates (and their JSON Schemas).

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.

Comments suppressed due to low confidence (5)

templates/workspaces/base/template_schema.json:52

• The description says "CIDR value", which can be read as allowing a full CIDR (e.g. "10.2.1.0/25") directly in address_space_size. In this template schema, address_space_size is a prefix length (e.g. "24") or a preset, while full CIDRs are provided via address_space when address_space_size is "custom". Rewording avoids user confusion.

      "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 description says "CIDR value", which can be read as allowing a full CIDR (e.g. "10.2.1.0/25") directly in address_space_size. In this template schema, address_space_size is a prefix length (e.g. "24") or a preset, while full CIDRs are provided via address_space when address_space_size is "custom". Rewording avoids user confusion.

      "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 description says "CIDR value", which can be read as allowing a full CIDR (e.g. "10.2.1.0/25") directly in address_space_size. In this template schema, address_space_size is a prefix length (e.g. "24") or a preset, while full CIDRs are provided via address_space when address_space_size is "custom". Rewording avoids user confusion.

      "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:25

• This description mentions numeric CIDR masks but doesn't state the enforced range. Since WorkspaceRepository.get_address_space_based_on_size rejects values outside 16–29, consider documenting the accepted range here to avoid misleading API consumers.

                description="This can have a value of small, medium, large, a numeric CIDR mask (e.g. \"24\") or custom. If you specify custom, then you need to specify a VNet address space in 'address_space' (e.g. 10.2.1.0/24)")

api_app/models/schemas/workspace_template.py:76

• This example JSON schema description mentions numeric CIDR masks but doesn't state the enforced range. Since WorkspaceRepository.get_address_space_based_on_size rejects values outside 16–29, consider documenting the accepted range here to avoid misleading API consumers.

                            "description": "This can have a value of small, medium, large, a numeric CIDR mask (e.g. \"24\") or custom. If you specify custom, then you need to specify a VNet address space in 'address_space' (e.g. 10.2.1.0/24)"

[marrobi]

LGTM if it works!

[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 (5)

templates/workspaces/base/template_schema.json:52

• The address_space_size description says "CIDR value" and includes a full CIDR example (10.2.1.0/25), but this property is validated as an enum of CIDR mask strings ("16"–"24") plus presets/custom. This wording can mislead users into providing a full CIDR for address_space_size or expecting /25 to be allowed via the enum.

      "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 address_space_size description says "CIDR value" and includes a full CIDR example (10.2.1.0/25), but this property is validated as an enum of CIDR mask strings ("16"–"24") plus presets/custom. This wording can mislead users into providing a full CIDR for address_space_size or expecting /25 to be allowed via the enum.

      "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 address_space_size description says "CIDR value" and includes a full CIDR example (10.2.1.0/25), but this property is validated as an enum of CIDR mask strings ("16"–"24") plus presets/custom. This wording can mislead users into providing a full CIDR for address_space_size or expecting /25 to be allowed via the enum.

      "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:25

• The sample address_space_size description mentions numeric CIDR masks but doesn't state the accepted range or that the API expects the mask as a string (e.g. "19"), which can lead to inconsistent client implementations.

                description="This can have a value of small, medium, large, a numeric CIDR mask (e.g. \"24\") or custom. If you specify custom, then you need to specify a VNet address space in 'address_space' (e.g. 10.2.1.0/24)")

api_app/models/schemas/workspace_template.py:76

• The OpenAPI example schema for address_space_size mentions numeric CIDR masks but doesn't state the accepted range or that the API expects the mask as a string, which can lead to inconsistent client implementations.

                            "description": "This can have a value of small, medium, large, a numeric CIDR mask (e.g. \"24\") or custom. If you specify custom, then you need to specify a VNet address space in 'address_space' (e.g. 10.2.1.0/24)"

[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 (3)

templates/workspaces/base/template_schema.json:52

• The description says "CIDR value", but the enum values are numeric CIDR masks (e.g. "24"), while full CIDR ranges are only valid when using the "custom" option. Tweaking the wording here would avoid confusing users into thinking they can enter "10.0.0.0/24" directly into 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/unrestricted/template_schema.json:44

• Same wording issue as other workspace templates: address_space_size accepts numeric CIDR masks (e.g. "24"), not a full CIDR range. Clarifying this in the description will prevent users from trying to enter an IP range into 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/airlock-import-review/template_schema.json:36

• The schema description currently says "CIDR value", but address_space_size is a numeric CIDR mask (e.g. "24"). Full CIDR ranges belong in address_space when address_space_size is "custom". Updating the description will make that distinction clear.

      "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.",

[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 (5)

templates/workspaces/base/template_schema.json:52

• The description says "CIDR value" but this schema's enum only allows numeric masks "16"–"24" (plus presets). To avoid implying that any CIDR (or "25"–"29") is valid for this workspace template, tighten the wording to match the actual allowed values.

      "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 description implies any "CIDR value" is accepted, but the enum only allows numeric masks "16"–"24" (plus presets). Clarify the description so users aren’t misled into thinking "25"–"29" are valid for this workspace template.

      "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 description suggests a generic "CIDR value", but the enum only permits numeric masks "16"–"24" (plus presets). Update the description to reflect the actual allowed numeric range for this workspace template.

      "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 OpenAPI sample description says "CIDR value" without indicating that numeric masks are expected as strings (and that actual allowed values are template-specific). Consider rewording to avoid implying arbitrary CIDR input is valid.

            "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 schema example description uses the ambiguous phrase "CIDR value" even though the feature expects a numeric CIDR mask string (e.g. "23") or presets/custom. Updating this text makes the API docs consistent with the implemented behavior.

                        "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."
                        },