Control Plane connectivity and targeting
The hosted Control Plane manages desired state. A customer-hosted Manager connects outbound, reports environment inventory, receives authorized operations, and returns acknowledgements. The Control Plane is not in the MongoDB request path.
Management connection
The supported connection is authenticated and environment-bound. Current Manager heartbeats report Manager version, configured Proxy image, managed Proxy inventory, cluster metadata, and Manager protocol capabilities. Heartbeats do not yet provide a complete bundle identity, CRD kind set, accepted pipeline references, or schema fingerprint in every released Manager.
The operational sequence is:
- Register an environment and obtain its protected connect-token workflow.
- Install the version-pinned Nexo Edge command supplied by the console.
- Manager authenticates and reports heartbeat inventory.
- The Control Plane returns authorized commands for that environment.
- Manager applies the command and acknowledges
appliedorfailed. - Later inventory and Operator status provide runtime evidence.
Reconnect, retry, and heartbeat intervals are implementation details. Do not depend on the legacy 30-second interval or a specific gRPC method shape as a public contract.
Connect tokens
- Tokens identify a registered environment, not a reusable fleet-wide credential.
- Store them in the supported Kubernetes Secret path.
- Ordinary environment responses do not reveal the Manager credential.
- Regeneration uses a protected operation and a rotation grace path; 0.2.0 does not support the later rotation behavior.
- Never place a token in documentation, shell history, source control, or a pipeline definition.
What the console controls
- project pipeline revisions and change previews;
- environment registration and health;
- release and deployment operations;
- project-to-environment selectors;
- namespace targeting within an allowed environment;
- authorization, audit history, and licensed entitlement checks.
The console does not replace Kubernetes authorization, network policy, database authorization, or release-specific compatibility checks.
Environment targeting
Projects and environments belong to the same top-level tenant. Projects define stage-specific label selectors; environments expose administrator-controlled labels. The Control Plane evaluates those labels to determine eligible deployment targets. Namespace selectors are a separate label space and limit which administrator-defined namespace targets a project can use.
project production selector: env=production, team=payments
environment labels: env=production, team=payments, region=eu-west
result: eligible environment
Use exact labels supported by the console and API. The legacy Boolean expression examples
(AND, OR, and NOT) are not the current selector contract.
Isolation and authorization
- Tenant and project access are enforced by server-side authorization.
- Environment credentials are scoped to their environment.
- Project managers, editors, viewers, and tenant administrators have different capabilities.
- Deployment is additionally constrained by environment and namespace targeting.
- A visible target is not permission to deploy; authorization and entitlement checks still apply.
Unavailable or contract-dependent modes
Self-hosted Control Plane
Legacy pages described an Enterprise Helm chart for a customer-operated management plane. No public chart, support boundary, upgrade process, or availability contract is published. Treat self-hosting as unavailable unless a signed customer agreement and release-specific procedure provide it.
Air-gapped management
Legacy pages described local JSON configuration and signed offline license files. Public air-gapped installation and management are not currently supported. Offline license implementation details do not create a customer-available distribution path.
Service hostnames and protocol examples
api.nexo.io, app.nexo.io, charts.nexo.io, the legacy ControlPlane protobuf, and
sample settings such as controlPlaneUrl, clusterName, or heartbeatInterval are
historical examples, not stable public endpoints or API contracts. Use the URL and values
generated by the authenticated console for the selected environment.
Failure behavior
Loss of management connectivity prevents new commands and fresh acknowledgements but must be evaluated separately from database traffic. Confirm the active graph revision, monitor the age of the last heartbeat, avoid bypass edits, and follow the incident runbooks before publishing more change.