Prepare an actor-bound managed-service plan review

Requires the applications rollout flag and live membership intersected with token scopes; reviews require applications.deploy, profiles.read and clusters.read. Preparing a review resolves the immutable package, the declared cluster policy, every explicitly bound consumer and every secret grant on the primary database, and stores an actor-bound plan with a digest and a ten-minute expiry. Confirming accepts only the stored review id and the reviewed digest, revalidates the same authority under row locks, and enqueues one cluster-scoped execution for a customer or existing-service plan; a retry returns the same receipt after current access checks. Hosted plans are refused at preparation: hosted operator-to-customer binding and cell dispatch are not wired, so nothing hosted can be reviewed or confirmed. A name an unreleased service instance already holds on the service cluster is refused with 409 Service name is already in use when the review is prepared, and again when it is confirmed: the reservation made at confirmation decides between concurrent reviews of one name. Service review has changed means only that the digest or the stored review changed. The request body is bounded at 16 KiB, which fits the maximum of 100 consumer_ids, 32 parameters and 16 secret_references. An actor may hold at most 20 open reviews and an organisation 100; a review that was never confirmed is deleted seven days after it expires. Plans never carry credential values. The execution receipt is not proof of service readiness. On a playground, prepare and confirm also check the plan’s quota against what the tenant commits now: a shortfall is refused with 409 naming it, and a capacity the platform cannot establish is returned as capacity.state unknown without blocking.

POST /api/v1/org/service-admission/reviews

Prepare an actor-bound managed-service plan review

Python

import requests

url = "https://platform.ankra.app/api/v1/org/service-admission/reviews"

payload = {
    "package_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "region": "<string>",
    "data_boundary": "<string>",
    "cluster_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "consumer_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "parameters": {},
    "secret_references": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "package_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "plan": {},
  "digest": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "confirmed_at": "2023-11-07T05:31:56Z",
  "capacity": {
    "state": "fits",
    "reason": "<string>",
    "plan_id": "<string>",
    "quota": {
      "limits_cpu_millicores": 123,
      "limits_memory_mib": 123,
      "requests_cpu_millicores": 123,
      "requests_memory_mib": 123
    },
    "committed": {
      "limits_cpu_millicores": 123,
      "limits_memory_mib": 123,
      "requests_cpu_millicores": 123,
      "requests_memory_mib": 123
    },
    "transient": {
      "limits_cpu_millicores": 123,
      "limits_memory_mib": 123,
      "requests_cpu_millicores": 123,
      "requests_memory_mib": 123
    },
    "required": {
      "limits_cpu_millicores": 123,
      "limits_memory_mib": 123,
      "requests_cpu_millicores": 123,
      "requests_memory_mib": 123
    }
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

package_version_id · string<uuid> · required

name · string · required

Required string length: 1 - 63

Pattern: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$

mode · enum<string> · required

Available options: hosted, customer, existing

region · string · required

Physical cloud region of the placement, for example eu-north-1. It locates infrastructure; it is not the data-location promise, which is data_boundary.

Required string length: 1 - 63

Pattern: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$

data_boundary · string · required

Boundary the data is permitted to stay within, for example eu. Sharing a service across clusters is decided by this boundary, never by the physical region.

Required string length: 1 - 63

Pattern: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$

cluster_id · string<uuid> · required

The service cluster for customer and existing modes. Hosted plans cannot be confirmed.

consumer_ids · string<uuid>[] · required

Customer-mode services can be deployed before connecting an application. Other modes require at least one consumer.

Maximum array length: 100

parameters · object · required

Show child attributes

secret_references · object · required

Package secret input name to credential grant id. Values are never accepted.

Show child attributes

Response

200

application/json

The stored review, its plan and digest; confirmation adds the execution receipt.

id · string<uuid> · required

package_version_id · string<uuid> · required

plan · object · required

The server-resolved plan (schema version 2): package digest, mode, location, service cluster, consumers with their policy and binding revisions, bounded parameters and opaque secret references. Never credential values. It is exactly the document the digest is taken over, so a planned consumer inside it keeps the stored nil UUID as installation_id; binding_kind says which case applies, and the consumer read reports the same absence as null.

digest · string · required

Pattern: ^sha256:[a-f0-9]{64}$

created_at · string<date-time> · required

execution_id · string<uuid> | null · required

confirmed_at · string<date-time> | null · required

capacity · object | null · required

Whether the service cluster can admit the service, as this prepare or confirm assessed it. It describes the cluster at that moment and is not part of the plan or its digest. Only playgrounds are checked, because the platform sets their quota. The service's footprint (for PostgreSQL, its instances and the CloudNativePG operator when the cluster does not run one) is compared with the plan's quota less what the tenant's pods commit now, with the playground LimitRange's defaults applied and the virtual control plane added. Job pods are reported as transient and left out of the decision. A playground that cannot admit the service is refused with 409, and the detail names the shortfall, the namespaces and stacks holding the quota, and what to do. Null when the response assessed nothing: a confirm that returned an existing receipt.

Show child attributes