> ## Documentation Index > Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt > Use this file to discover all available pages before exploring further. # Connect an application to a managed service (browser session) > Requires the applications rollout flag, applications.deploy, and clusters.operate and clusters.read on the service's cluster, which is also the environment's, all intersected with live token scopes. Adds one bound application environment (POST .../consumers) to the consumers of a service Ankra runs in your cluster, so a second application uses the same service instead of getting one of its own. Nothing is deployed and the generation does not move: the environment joins the service's record of who uses it, receives the service's connection the next time the application deploys, cannot be unbound while the service uses it, and is disconnected by a retirement like every other consumer. A retirement reviewed before the change is refused when confirmed. The environment must be on the service's own cluster and in its data boundary. Refused for another generation than the one read, an environment that already uses the service, and a service that is still installing, being retired, retired, or not one Ankra runs in your cluster. One service serves at most 100 environments. ## OpenAPI ````yaml https://platform.ankra.app/openapi.json post /org/service-admission/instances/{instance_id}/consumers openapi: 3.1.0 info: title: FastAPI version: 0.1.0 servers: - url: https://platform.ankra.app security: [] tags: - name: Canvas Pages description: >- Publish a chat canvas artifact at a public pages address and take it down again. - name: Cloud Delegation description: >- Platform browser consent and organisation-bound connections for Ankra Cloud. - name: Organisation IAM description: >- Custom organisation roles and scoped role assignments for member and service-account identities. - name: Clusters description: Create, inspect and manage clusters, and the stacks deployed on them. - name: Managed Clusters description: Provider-managed control planes, driven through one common surface. - name: Imported Clusters description: Clusters that already existed and were connected to Ankra. - name: Cluster Access description: Kubeconfigs, service-account tokens and per-cluster access grants. - name: Kubernetes description: Read and act on the Kubernetes objects inside a cluster. - name: AWS Clusters description: >- Provision and manage self-managed k3s / kubeadm clusters on AWS EC2 in your own VPC. - name: Ankra Cloud Clusters description: >- Provision and manage self-managed kubeadm / k3s clusters on Ankra Cloud servers: a private network, a NAT router and a bastion per cluster. - name: DigitalOcean Clusters description: Provision and manage DigitalOcean Kubernetes clusters. - name: Hetzner Clusters description: Provision and manage Hetzner Kubernetes clusters. - name: OVH Clusters description: Provision and manage OVH Kubernetes clusters. - name: Scaleway Clusters description: Provision and manage Scaleway Kapsule clusters. - name: UpCloud Clusters description: Provision and manage UpCloud Kubernetes clusters. - name: Applications description: Deploy, configure and observe applications across the fleet. - name: Pipelines description: >- Pipeline definitions, the approval of the authority they declare, and the caches pipelines keep between runs. - name: Workspaces description: >- Personal workspaces on the organisation's CI pool where a repository's heavy commands run, and the repository profiles they are built from. - name: Deploy Targets description: >- Environments, the hosts registered to receive deployments, and the releases deployed to them. - name: Backups description: >- Backup vaults, restore points, protection posture and captures for stacks and application deployments; a completed capture is not a verified restore. - name: Stack Profiles description: Reusable stack definitions, their versions and sharing. - name: Services description: >- Versioned service packages and explicit sharing. Runtime admission is separate from publication. - name: Charts description: Browse the chart catalogue behind stacks and addons. - name: Helm description: Helm registries, credentials and the charts they expose. - name: Executions description: Long-running platform executions and their jobs. - name: Operations description: Cancel in-flight cluster operations and their jobs. - name: Chat description: Conversational sessions, plans and confirmable actions. - name: AI Management description: >- Customer agent lifecycle, authenticated identity and organisation automation controls. - name: AI Agent Runs description: Autonomous agent runs and their outcomes. - name: AI Tickets description: The AI ticket board, its sync connections and settings. - name: AI Playbooks description: Reusable playbooks the AI lanes execute. - name: AI Conditions description: Conditions that gate AI autonomy. - name: AI Remediation description: >- The organisation's auto-remediation policy: what the AI lanes may fix by themselves, and who approves the rest. - name: AI Engineering Handoffs description: Work the AI lanes escalate to a human engineer. - name: AI Environment description: The environment and base stacks AI demos deploy into. - name: MCP Servers description: >- Register the MCP servers the organisation's AI agents can call, choose their tools and grant them to roles. - name: Security description: Findings, advisories, SBOMs, compliance and posture. - name: Cost description: Cluster and fleet cost, rate cards and cost settings. - name: Decisions description: >- The decision ledger behind the Security and Cost queues: proposals a surface computed, the approve and set-aside decisions people took on them, and the receipts of running them. - name: Usage description: >- What your organisation used of Ankra - vCPU-hours, playgrounds, managed services, hosted logs and metrics, and AI - per meter and period, with how completely it was measured and whether a published rate applies. - name: Billing description: Subscription and spend caps. - name: Organisation description: Members, invitations, audit logs and organisation settings. - name: Account description: >- Your own account: the contact email Ankra mails when it differs from your sign-in address. - name: Account Tokens description: Personal access tokens for the API and CLI. - name: Credentials description: The shared credential store. - name: AWS Credentials description: >- AWS credentials: access keys or CloudFormation-onboarded STS roles for cost, EKS and self-managed provisioning. - name: Ankra Cloud Credentials description: >- Ankra Cloud API tokens, shared by the self-managed and managed Ankra Cloud lanes. - name: Azure Credentials description: Azure credentials and SSH keys. - name: DigitalOcean Credentials description: DigitalOcean credentials and SSH keys. - name: Hetzner Credentials description: Hetzner credentials and SSH keys. - name: OVH Credentials description: OVH credentials and SSH keys. - name: Scaleway Credentials description: Scaleway credentials. - name: UpCloud Credentials description: UpCloud credentials and SSH keys. - name: Data Source Credentials description: Credentials for metrics and log sources. - name: DNS Credentials description: Credentials for DNS providers. - name: Object Storage Buckets description: >- Buckets Ankra creates and manages on an organisation's own provider credentials. - name: DNS description: DNS zones and records, including custom organisation zones. - name: Cloudflare description: Cloudflare domains and the credentials behind them. - name: Avura description: >- The linked Avura organization, the domains it shares with Ankra Platform, and their DNS records. - name: Variables description: Organisation- and cluster-scoped variables. - name: Secret Slots description: >- Store secrets in Vault and reference them by ${SECRET_SLOT:} sentinel instead of by value. - name: SOPS description: Encrypt and decrypt values with the organisation SOPS config. - name: Alerts description: Alert integrations and ingest credentials. - name: Notifications description: Notification routes and their delivery targets. - name: Support description: Support tickets. - name: AI Settings description: Organisation AI provider, model catalog and per-function model settings paths: /org/service-admission/instances/{instance_id}/consumers: post: tags: - Services summary: Connect an application to a managed service (browser session) description: >- Requires the applications rollout flag, applications.deploy, and clusters.operate and clusters.read on the service's cluster, which is also the environment's, all intersected with live token scopes. Adds one bound application environment (POST .../consumers) to the consumers of a service Ankra runs in your cluster, so a second application uses the same service instead of getting one of its own. Nothing is deployed and the generation does not move: the environment joins the service's record of who uses it, receives the service's connection the next time the application deploys, cannot be unbound while the service uses it, and is disconnected by a retirement like every other consumer. A retirement reviewed before the change is refused when confirmed. The environment must be on the service's own cluster and in its data boundary. Refused for another generation than the one read, an environment that already uses the service, and a service that is still installing, being retired, retired, or not one Ankra runs in your cluster. One service serves at most 100 environments. operationId: connectServiceConsumerSession parameters: - name: instance_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ServiceInstanceConsumerRequest' responses: '200': description: The instance with the environment among its consumers. content: application/json: schema: $ref: '#/components/schemas/ServiceInstance' '400': description: Bearer token not provided or invalid authorization header '401': description: Authentication required '403': description: Insufficient permission or missing browser CSRF '404': description: >- The service or the environment's binding is not accessible or absent, or rollout disabled '409': description: >- The connection was refused: the service changed generation, is installing, being retired, retired or not run by Ankra in your cluster, or the environment already uses it, is on another cluster or in another data boundary '422': description: Invalid or ambiguous request '500': description: Internal error '503': description: Rollout availability could not be verified security: - SessionCookie: [] components: schemas: ServiceInstanceConsumerRequest: type: object additionalProperties: false required: - consumer_id - expected_generation properties: consumer_id: type: string format: uuid description: >- The binding of the application environment to connect, from POST .../consumers. expected_generation: type: integer format: int64 minimum: 1 description: >- The instance generation the person read; a request against any other generation is refused. ServiceInstance: type: object additionalProperties: false required: - id - package_version_id - cluster_id - admission_operation_id - name - region - data_boundary - generation - mode - requested_destinations - consumers - cluster_name - state - deployment_operation_id - deployment_state - readiness - readiness_check - created_at - released_at - evidence_updated_at - connection - health - retirement properties: id: type: string format: uuid package_version_id: type: string format: uuid cluster_id: type: string format: uuid cluster_name: type: string description: >- The service cluster's name as it reads now, for display; cluster_id is the identity. state: type: string enum: - deploying - deployed - serving - degraded - failed - retiring - released - unknown description: >- The instance's lifecycle in one word, folded at read time from deployment_state, health, readiness and retirement; those fields stay the evidence. released: the instance was released and its name is free. retiring: a confirmed retirement is removing it. failed: its admission or deployment operation failed. deploying: it is being installed, or its workload is rolling out. serving: the platform last observed its workload serving and no readiness check found it failing. degraded: an observation or readiness check found it not serving, or a namespace quota refuses its pods. deployed: its deployment finished and nothing observes its health (a package that is not a first-party engine, or one the health loop has not reached); not a statement that it serves. unknown: the recorded evidence establishes none of these. Precedence is released, retiring, failed, deploying, then the health-based states. admission_operation_id: type: string format: uuid name: type: string region: description: >- 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. type: string data_boundary: description: >- 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. type: string generation: type: integer format: int64 minimum: 1 mode: type: string enum: - customer - existing - hosted requested_destinations: type: array items: $ref: '#/components/schemas/ServiceReviewDestination' description: >- Requested destinations from the durable plan; not proof of a live service connection. consumers: type: array items: type: object additionalProperties: false required: - id - application_id - cluster_id - namespace - application_name - cluster_name - environment properties: id: type: string format: uuid application_id: type: string format: uuid cluster_id: type: string format: uuid namespace: type: string application_name: type: string nullable: true description: >- The application's name, for display; null when its record carries none. cluster_name: type: string description: The consumer cluster's name, for display. environment: type: object nullable: true additionalProperties: false required: - id - name - role description: >- The application environment the deployment in this namespace belongs to. Null when the application is not deployed to the namespace yet (a planned binding) or its deployment there is not assigned to an environment. properties: id: type: string format: uuid name: type: string role: type: string enum: - playground - production - staging - development - custom connection_delivery: type: object additionalProperties: false required: - state - secret_name - variables - reason description: >- How this consumer receives the service's connection: a Secret Ankra writes into its namespace inside the cluster and the environment variables it carries; values are never returned. Present on the instance detail read only, absent from lists. properties: state: type: string enum: - delivered - pending - unsupported - unknown description: >- delivered: the Secret is observed in the namespace. pending: not yet; the service is still deploying or the application has not deployed since. unsupported: Ankra does not deliver this connection (another cluster, or not an engine Ankra runs in your cluster). unknown: it could not be read. secret_name: type: string description: >- The connection Secret in the consumer's namespace; empty when unsupported or unknown. variables: type: array items: type: string description: >- Environment variable names the application receives: the conventional names when this is its first service of the engine, then the service's own prefixed names. reason: type: string description: >- Why the state is not delivered, in words a person acts on; empty when delivered. description: >- The reviewed plan's consumers with their ids: exactly the set a retirement request names in disconnect_consumer_ids. Reviewed intent, not proof of a live connection. deployment_operation_id: type: string format: uuid nullable: true description: >- Present only when current execution evidence matches the stored receipt and organisation/cluster scope. deployment_state: type: string enum: - accepted - admission_failed - deploying - deployment_failed - verification_pending - unknown - released readiness: type: string enum: - unverified - verifying - ready - degraded - stale description: >- Whether a consumer can use the service, from a scoped consumer-path canary - for PostgreSQL, a pod in the instance namespace logging in with the generated credentials by Secret reference and running SELECT 1 every five minutes; a result stands fifteen minutes. unverified: no canary covers this instance (an engine other than PostgreSQL, a hosted, released or later-generation instance, or one with no deployment receipt); a successful deployment is not readiness. verifying: covered, and no canary has established readiness yet - none has run, or the service is still deploying or inside its first start's grace window. ready: an unexpired canary passed. degraded: an unexpired canary ran and failed after the service had its chance to start. stale: readiness cannot currently be established - the canary could not run (no agent, the cluster unavailable, the canary pod refused or not finishing) or its last result expired; an expired ready is never reported. readiness_check: type: object nullable: true description: >- The canary evidence behind readiness, folded against the database clock at read time. Null when no canary has run at this generation. A canary that could not run leaves an unexpired pass or failure standing until it expires, so observed_at is when the standing result was observed, not necessarily the latest attempt. Never carries a probe log or a credential. additionalProperties: false required: - observed_at - expires_at - reason - last_passed_at properties: observed_at: type: string format: date-time expires_at: type: string format: date-time reason: type: string description: One line naming what decided the readiness. last_passed_at: type: string format: date-time nullable: true description: >- When a canary last passed at this generation; null when none has. It survives expiry. created_at: type: string format: date-time released_at: type: string format: date-time nullable: true evidence_updated_at: type: string format: date-time nullable: true connection: type: object nullable: true description: >- Where a first-party engine instance is reached inside its cluster and which Secret in its namespace holds the credentials the engine generated. Derived from the engine profile, not observed; null for any other package. additionalProperties: false required: - namespace - endpoints - secret properties: namespace: type: string endpoints: type: array items: type: object additionalProperties: false required: - name - address properties: name: type: string address: type: string secret: type: object additionalProperties: false required: - name - keys properties: name: type: string keys: type: array items: type: string health: type: object nullable: true description: >- Health as the platform last observed it from the service cluster's synced state: whether the engine's workload reports ready, its Service and credentials Secret exist, and the stack that owns it is still deployed. It is not readiness - no consumer connection is proven. Evidence past expires_at reads unknown, folded against the database clock at read time, so a stopped observer never leaves a stale serving. Null when nothing has observed this generation: a package that is not a first-party engine, an instance not deployed yet, a released instance, or one not observed yet. additionalProperties: false required: - state - observed_at - expires_at - reason - quota properties: state: type: string enum: - serving - progressing - degraded - unknown description: >- serving: every check passed on an authoritative view. progressing: a check failed while the deployment is in flight or inside the engine's grace window. degraded: a check failed after the grace window, the deployment failed, or the owning stack is gone or being removed. unknown: something could not be read - the cluster's watch of a resource type is not synced or fresh - or the evidence expired. observed_at: type: string format: date-time expires_at: type: string format: date-time reason: type: string description: >- One line naming what decided the state. While a quota refusal stands and the service is not serving, it leads with the refusal: blocked by namespace quota ( /): . quota: type: object description: >- What the same observation could see of namespace ResourceQuota refusals in the instance namespace and the namespaces of the shared operators the engine needs (cnpg-system for PostgreSQL). Read from the cluster's own events: a ReplicaSet's FailedCreate or a virtual cluster syncer's SyncError naming an exceeded quota, last seen within 30 minutes. refused: such an event stands, carried verbatim in refusal. none_observed: no such event in the namespaces listed, on an events watch that is synced and fresh - it does not cover refusals worded otherwise (a LimitRange bound, an admission webhook). unknown: no such event, and the events watch is not synced and fresh, the evidence expired, or the observation recorded no quota check. A refusal does not decide state; a serving instance can carry one it has outlived. additionalProperties: false required: - state - namespaces - refusal properties: state: type: string enum: - refused - none_observed - unknown namespaces: type: array items: type: string description: >- The namespaces read; none_observed speaks for these only. Empty when the observation recorded no quota check. refusal: type: object nullable: true description: The freshest refusal, present exactly when state is refused. additionalProperties: false required: - namespace - object_kind - object_name - message - last_seen_at properties: namespace: type: string object_kind: type: string description: >- Kind of the object the event is about: the ReplicaSet or Job that could not create a pod, or the virtual pod the syncer could not place. Empty when the event names none. object_name: type: string message: type: string description: The event's message verbatim, up to 480 characters. last_seen_at: type: string format: date-time retirement: allOf: - $ref: '#/components/schemas/ServiceInstanceRetirement' nullable: true description: >- The latest confirmed retirement, running or settled; null when none was ever confirmed. A settled outcome other than retired left the service and its name in place. ServiceReviewDestination: type: object additionalProperties: false required: - application_id - cluster_id - namespace properties: application_id: type: string format: uuid cluster_id: type: string format: uuid namespace: type: string ServiceInstanceRetirement: type: object additionalProperties: false description: >- The latest confirmed retirement of an instance: recorded progress, not an observation of the cluster. required: - id - state - phase - execution_id - requested_at - settled_at - outcome - reason properties: id: type: string format: uuid state: type: string enum: - in_progress - settled phase: type: string enum: - retire_stack - await_teardown - dispose_data nullable: true description: The phase the retirement is in, or was in when it settled. execution_id: type: string format: uuid requested_at: type: string format: date-time settled_at: type: string format: date-time nullable: true outcome: type: string enum: - retired - removal_failed - disposal_unknown - refused - interrupted nullable: true reason: type: string nullable: true securitySchemes: SessionCookie: description: Browser session. Mutations also require X-Ankra-CSRF. in: cookie name: ankra_session type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.