Skip to content

Commit

Permalink
remove support for PUT on quota
Browse files Browse the repository at this point in the history 
This includes:

- removing the LowPrivilegeRaiseLimit configuration that is obsoleted by this
- replacing the `raise` and `lower` policies with `edit_privileged` for PUT on max-quota
  • Loading branch information
@majewsky
majewsky committed May 3, 2024
1 parent 5ba5cde commit 58c485e
Show file tree
Hide file tree
Showing 19 changed files with 101 additions and 3,137 deletions.
9 changes: 1 addition & 8 deletions docs/example-policy.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,21 +10,14 @@ project_viewer: rule:domain_viewer or (rule:project_scope and role:member) or ru
project:list: rule:domain_viewer
project:show: rule:project_viewer
project:edit: rule:project_editor
project:edit_max_quota: rule:domain_editor
project:sync: rule:project_editor
project:raise: rule:domain_editor
project:raise_lowpriv: rule:project_editor
project:lower: rule:project_editor
domain:lower_lowpriv: rule:project_editor
project:set_rate_limit: rule:domain_editor
project:discover: rule:domain_editor
project:uncommit: rule:cluster_admin

domain:list: rule:cluster_admin
domain:show: rule:domain_viewer
domain:raise: rule:cluster_admin
domain:raise_lowpriv: rule:domain_editor
domain:lower: rule:domain_editor
domain:lower_lowpriv: rule:domain_editor
domain:discover: rule:cluster_admin

cluster:list: rule:cluster_admin
Expand Down
39 changes: 1 addition & 38 deletions docs/operators/config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ on the top left corner of this document to get to a specific section of this gui
| Variable | Default | Description |
| --- | --- | --- |
| `LIMES_API_LISTEN_ADDRESS` | `:80` | Bind address for the HTTP API exposed by this service, e.g. `127.0.0.1:80` to bind only on one IP, or `:80` to bind on all interfaces and addresses. |
| `LIMES_API_POLICY_PATH` | `/etc/limes/policy.yaml` | Path to the oslo.policy file that describes authorization behavior for this service. Please refer to the [OpenStack documentation on policies][policy] for syntax reference. This repository includes an [example policy][ex-pol] that can be used for development setups, or as a basis for writing your own policy. For `:raise`, `:raise_lowpriv`, `:lower` and `:set_rate_limit` policies, the object attribute `%(service_type)s` is available to restrict editing to certain service types. |
| `LIMES_API_POLICY_PATH` | `/etc/limes/policy.yaml` | Path to the oslo.policy file that describes authorization behavior for this service. Please refer to the [OpenStack documentation on policies][policy] for syntax reference. This repository includes an [example policy][ex-pol] that can be used for development setups, or as a basis for writing your own policy. For `:set_rate_limit` policies, the object attribute `%(service_type)s` is available to restrict editing to certain service types. |

### Audit trail

Expand Down Expand Up @@ -114,47 +114,10 @@ The following fields and sections are supported:
| `discovery.params` | yes/no | A subsection containing additional parameters for the specific discovery method. Whether this is required depends on the discovery method; see [*Supported discovery methods*](#supported-discovery-methods) for details. |
| `services` | yes | List of backend services for which to scrape quota/usage data. Service types for which Limes does not include a suitable *quota plugin* will be ignored. See below for supported service types. |
| `capacitors` | no | List of capacity plugins to use for scraping capacity data. See below for supported capacity plugins. |
| `lowpriv_raise` | no | Configuration options for low-privilege quota raising. See [*low-privilege quota raising*](#low-privilege-quota-raising) for details. |
| `resource_behavior` | no | Configuration options for special resource behaviors. See [*resource behavior*](#resource-behavior) for details. |
| `bursting.max_multiplier` | no | If given, permits quota bursting in this cluster. When projects enable quota bursting, the backend quota is set to `quota * (1 + max_multiplier)`. In the future, Limes may autonomously adjust the multiplier between 0 and the configured maximum based on cluster-wide resource utilization. |
| `quota_distribution_configs` | no | Configuration options for selecting resource-specific quota distribution models. See [*quota distribution models*](#quota-distribution-models) for details. |

### Low-privilege quota raising

The Oslo policy for Limes (see [example policy][ex-pol]) is structured such that raising quotas requires
a different (usually higher) permission level than lowering quotas. However, through the `*:raise_lowpriv` rules,
low-privilege users can be permitted to raise quotas within certain boundaries.

| Field | Required | Description |
| --- | --- | --- |
| `lowpriv_raise.limits.projects` | no | Limits up to which project quotas can be raised by a low-privilege user. |
| `lowpriv_raise.limits.domains` | no | Limits up to which domain quotas can be raised by a low-privilege user. |
| `lowpriv_raise.except_projects_in_domains` | no | May contain a regex. If given, low-privilege quota raising will not be allowed for projects in domains whose names match the regex. |
| `lowpriv_raise.only_projects_in_domains` | no | May contain a regex. If given, low-privilege quota raising will only be possible for projects in domains whose names match the regex. If `except_projects_in_domains` is also given, it takes precedence over `only_projects_in_domains`. |

Both `limits.projects` and `limits.domains` contain two-level maps, first by service type, then by resource name.

- Values may also be specified relative to the cluster capacity with the special syntax `<number>% of cluster capacity`.
- For `limits.domains` only, the alternative special syntax `until <number>% of cluster capacity is assigned` will cause
quota requests to be approved as long as the sum of all domain quotas is below the given value.

For example:

```yaml
lowpriv_raise:
limits:
projects:
compute:
cores: 10
instances: 0.5% of cluster capacity
ram: 10 GiB
domains:
compute:
cores: 1000
instances: until 80% of cluster capacity is assigned
ram: 1 TiB
```

### Resource behavior

Some special behaviors for resources can be configured in the `resource_behavior[]` section. Each entry in this section can match multiple resources.
Expand Down
146 changes: 4 additions & 142 deletions docs/users/api-spec-resources.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -357,99 +357,11 @@ substructure will be returned in the top-level field `domain`.

### PUT /v1/domains/:domain\_id

Set quotas for the given domain. Requires at least a domain-admin token, and a request body that is a JSON document
like:

```json
{
"domain": {
"services": [
{
"type": "compute",
"resources": [
{
"name": "instances",
"quota": 30
},
{
"name": "ram",
"quota": 150,
"unit": "GiB"
},
...
]
},
...
]
}
}
```

The following fields can appear in the request body:

| Field | Type | Description |
| ----- | ---- | ----------- |
| `domain` | object | Top-level grouping to match the response structure in the respective GET endpoint. |
| `domain.services` | list of objects | List of services where quotas shall be updated. |
| `domain.services[].type` | string | The type name of this service. |
| `domain.services[].resources` | list of objects | List of resources in this service where quotas shall be updated. |

The objects at `domain.services[].resources[]` may contain the following fields:

| Field | Type | Description |
| ----- | ---- | ----------- |
| `name` | string | The name of this resource. |
| `quota` | unsigned integer | The requested quota for this resource. |
| `unit` | string | The unit for the value in the `quota` field (must be omitted if this resource is counted instead of measured, can be omitted to imply the resource's default unit). |

On success, returns 202 (Accepted) and no response body. On error, 4xx responses may be returned. The exact response
status is determined in the same way as described for the respective `simulate-put` endpoint below.
**Deprecated.** Always returns 405 (Method Not Allowed) because support for setting quotas manually has been removed from Limes.

### POST /v1/domains/:domain\_id/simulate-put

Requires a similar token and request body like `PUT /v1/domains/:domain_id`, but does not attempt to actually change any
quotas.

Returns 200 (OK) on success, or 4xx otherwise (see below). Result is a JSON document like:

```json
{
"success": false,
"unacceptable_resources": [
{
"service_type": "compute",
"name": "cores",
"status": 403,
"message": "user is not allowed to set compute quotas"
}
]
}
```

If `success` is true, the corresponding PUT request would have been accepted (i.e., produced a 202 response). If
`success` is false, `unacceptable_resources` contains one entry for each resource whose requested quota was not
accepted, with the following fields:

| Field | Type | Description |
| ----- | ---- | ----------- |
| `service_type` | string | The service wherein the resource with the unacceptable quota is located. |
| `name` | string | The name of the resource with the unacceptable quota. |
| `status` | unsigned integer | An HTTP status code providing a broad classification of why the quota is not acceptable. |
| `message` | string | A human-readable message describing why the quota is not acceptable. |
| `min_acceptable_quota`<br>`max_acceptable_quota` | unsigned integer | If the specific requested quota value is the problem, one or both of these fields may be shown to indicate which quota values would be acceptable with the current level of permissions. |
| `unit` | string | The unit for this resource (only shown for measured resources if `min_acceptable_quota` or `max_acceptable_quota` is also shown). |

The response status will be either 422 (Unprocessable Entity) if multiple unacceptable resources have different status
codes, or equal to the status code of the unacceptable resources if they all agree on one. For example, if all resources are
rejected with status 403, the entire request will have response status 403.

The following status codes are possible for unacceptable resources:

- 403 (Forbidden) indicates that a higher permission level (e.g. a cloud-admin token instead of a domain-admin token) is
needed to set the requested quota value.
- 409 (Conflict) indicates that the requested quota value contradicts values set on other levels of the quota hierarchy.
- 422 (Unprocessable Entity) indicates that the quota request itself was malformed (e.g. when a quota of 200 MiB is
requested for a countable resource like `compute/cores`).
**Deprecated.** Always returns 405 (Method Not Allowed) because support for setting quotas manually has been removed from Limes.

### POST /v1/domains/discover

Expand Down Expand Up @@ -578,61 +490,11 @@ such object with identical substructure will be returned in the top-level field

### PUT /v1/domains/:domain\_id/projects/:project\_id

Set quotas for the given project. Requires at least a project-admin token, and a request body that is a JSON document
like:

```json
{
"project": {
"services": [
{
"type": "compute",
"resources": [
{
"name": "instances",
"quota": 30
},
{
"name": "ram",
"quota": 150,
"unit": "GiB"
},
...
]
},
...
]
}
}
```

The following fields can appear in the request body:

| Field | Type | Description |
| ----- | ---- | ----------- |
| `project` | object | Top-level grouping to match the response structure in the respective GET endpoint. |
| `project.services` | list of objects | List of services where quotas shall be updated. |
| `project.services[].type` | string | The type name of this service. |
| `project.services[].resources` | list of objects | List of resources in this service where quotas shall be updated. |

The objects at `project.services[].resources[]` may contain the following fields:

| Field | Type | Description |
| ----- | ---- | ----------- |
| `name` | string | The name of this resource. |
| `quota` | unsigned integer | The requested quota for this resource. |
| `unit` | string | The unit for the value in the `quota` field (must be omitted if this resource is counted instead of measured, can be omitted to imply the resource's default unit). |

On success, returns 202 (Accepted) and no response body. On error, 4xx responses may be returned. The exact response
status is determined in the same way as described for the respective `simulate-put` endpoint below.
**Deprecated.** Always returns 405 (Method Not Allowed) because support for setting quotas manually has been removed from Limes.

### POST /v1/domains/:domain\_id/projects/:project\_id/simulate-put

Requires a similar token and request body like `PUT /v1/domains/:domain_id`, but does not attempt to actually change any
quotas.

Returns 200 (OK) on success, or 4xx otherwise (see below). Result is a JSON document with the same structure as for
`POST /v1/domains/:domain_id/simulate-put`.
**Deprecated.** Always returns 405 (Method Not Allowed) because support for setting quotas manually has been removed from Limes.

### POST /v1/domains/:domain\_id/projects/discover

Expand Down
Loading

0 comments on commit 58c485e

Please sign in to comment.