Add available space memory to /v3/spaces/:guid/usage_summary response

[anailieva]

After redesigning one of the pages in SAP BTP Cockpit, we would like to include a key metric - the available memory of a space.
Currently, the endpoint /v3/spaces/:guid/usage_summary provides information about used memory, but to calculate the available memory we need additional logic on the client side:

• Detect whether the space uses a space quota or defaults to the org quota.
• Apply different calculations based on this.
• Perform extra API calls to retrieve quota details.

Since the page already aggregates multiple metrics, every additional call affects the performance.

Our proposal is to enhance the response of /v3/spaces/:guid/usage_summary to include a new field available_memory_in_mb, which should represent the remaining memory capacity available for allocations within the space, respecting both space and org quotas:

• If the space has a space quota assigned: available_memory = space_quota_memory_limit - used_memory
• If the space has no space quota: available_memory = org_quota_memory_limit - used_memory
• If the space quota is greater than the org’s remaining available memory, the available memory must be capped by the org: available_memory = min(space_quota_memory_limit, org_available_memory) - used_memory

[johha]

Showing the remaining / available memory for a given org or space would be a simple addition as there is already some calculation in place: https://github.com/cloudfoundry/cloud_controller_ng/blob/main/app/models/runtime/space.rb#L354-L356
Not sure if it's possible to directly access the org quota within the space model.

@Gerg @sethboyles Do you have any concerns about adding a remaining_memory (or available_memory) field to the usage_summary endpoints for spaces and orgs?

[Gerg]

It does feel a little different to me than what we've currently done so far with the usage endpoints. These endpoints are currently showing resource usage, rather than remaining quotas. That's not to say that we couldn't extend them to start also do something different.

As a thought experiment, what would this look like for the /v3/info/usage_summary endpoint? A global roll-up or all the available quota on the environment? Maybe that could be also useful.

Alternatively, this info could be on a similar, new endpoint e.g.GET /v3/spaces/:space_guid/remaining_quota. Or maybe there are also some other designs to consider.

[johha]

Tried out a few things with copilot and I'd propose to add two new endpoints GET /v3/spaces/:space_guid/quota_summary and GET /v3/organizations/:org_guid/quota_summary which would return the following information:

{
  "quota_summary": {
    "apps": {
      "total_memory_in_mb": {
        "limit": 5120,
        "used": 2048,
        "available": 3072
      },
      "per_process_memory_in_mb": {
        "limit": 1024
      },
      "total_instances": {
        "limit": 20,
        "used": 8,
        "available": 12
      },
      "per_app_tasks": {
        "limit": 5
      }
    },
    "services": {
      "paid_services_allowed": {
        "limit": true
      },
      "total_service_instances": {
        "limit": 10,
        "used": 3,
        "available": 7
      },
      "total_service_keys": {
        "limit": 20,
        "used": 5,
        "available": 15
      }
    },
    "routes": {
      "total_routes": {
        "limit": 25,
        "used": 10,
        "available": 15
      },
      "total_reserved_ports": {
        "limit": 5,
        "used": 1,
        "available": 4
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/space-guid-1/quota_summary"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/space-guid-1"
    }
  }
}

The format is based on the space/organization quota object. For spaces there would be a calculation in place which considers the org quota so that the correct value is shown
I'm not sure if we should include attributes where we cannot show a usage - e.g. per_process_memory_in_mb, per_app_tasks and paid_services_allowed. Also the available field is not really necessary as clients could subtract the limit and used themselves but adding this field is basically zero effort.

Feedback highly appreciated!

[johha]

Alternatively we could implement a GET /v3/spaces/:guid/effective_quota endpoint which returns a temporary, computed quota object (the merge of the current org and space quotas). It reuses the existing quota object structure, just without attributes like guid, name, created_at, etc.
Example response:

{
  "apps": {
    "total_memory_in_mb": 5120,
    "per_process_memory_in_mb": 1024,
    ...
  },
  "services": {
    "paid_services_allowed": true,
    "total_service_instances": 10,
    ...
  },
...
}

With an include (e.g. GET /v3/spaces/:guid/usage_summary?include=effective_quota) this data can be attached to the existing usage summary so clients can compute remaining resources themselves.
This approach stays close to existing CF API v3 patterns: it provides a dedicated, well-scoped endpoint, keeps usage and limits separate, and cleanly reuses established resource shapes.

[Gerg]

I have a mild preference for GET /v3/.../effective_quota.

• It doesn't duplicate data that is already available via the GET /v3/.../usage_summary endpoints.
• Doing the available math seems like marginal value, so I'm fine losing that.
• It's also cleaner for the "usage-less" quotas.

The ?include=effective_quota may be a bit wonky since, under the current spec, includes are for relationships. Not to say that the spec can't be modified to solve a problem.

A deluxe edition for GET /v3/spaces/:guid/effective_quota could look something like:

{
  "apps": {
    "total_memory_in_mb": {
      "org_limit": 5120,
      "space_limit": 9001,
      "effective_limit": 5120 
    },
    "...": "..."
  },
  "...": "..."
}