Skip to main content
Version: main 🚧

Manage connectors and tenant grants

Use the Connector management API to configure integrations and grant tenants access to admin-managed connectors.

Prerequisites​

  • A kubeconfig pointing to the Platform management API.
  • Platform admin permissions for the grant examples.
  • The license feature for the connector type you create or update.
  • A Tenant for the grant examples.

Tenants can use granted connectors, but can't create, update, patch, or delete connectors in this release. They also need a role granting get and list, such as loft-connectors-viewer.

Create and inspect a connector​

Create a database connector using the database guide, or choose another connector type.

The schema's required fields don't describe every admission rule. A type's credentials are required on create, even though the schema marks them optional, unless the connector authenticates another way, such as AWS IAM database authentication. Updates follow different rules. See Update credentials.

List the connectors visible to your current identity:

kubectl get connectors.management.loft.sh

The table shows names, types, display names, and ages. Inspect conditions as a connector admin:

Modify the following with your specific values to generate a copyable command:
kubectl get connectors.management.loft.sh prod-db -o jsonpath='{.status.conditions}'

Configured=True means the stored payload passes validation. It doesn't prove that the external service is reachable. Additional conditions depend on the connector type.

Update credentials​

Update connectors as a connector admin, and include the complete configuration in the update. Users with only view access see a reduced copy that leaves out some fields. Don't save that copy as a backup or send it back as an update.

Any API update, including a patch or a label change, rewrites the backing Secret from the fields the API models. Unmodeled Secret data keys and withheld annotations, such as the last-applied annotation, are dropped. This matters most for connectors created as Secrets by hand or by other automation.

TypeEmpty credential on update
DatabaseKeeps password. Selecting identityProvider: aws removes the password. Switching back requires a new password.
Argo CDKeeps existing credentials within the current authentication method. Switching between token and username/password requires credentials for the new method.
AkuityKeeps apiKeySecret while remaining on Akuity. Switching from self-hosted Argo CD requires an Akuity API key secret.
NetBoxKeeps apiToken when a stored token exists.
OS image storeKeeps s3.secretKey. An empty s3.sessionToken removes that token.
ObservabilityReferences TLS Secrets instead of embedding these credentials. Manage the referenced Secrets separately.

An empty credential keeps the stored value, as the table shows. Other fields generally don't, so an empty value replaces the stored one. To change one field, send only that field in a merge patch. Don't edit the reduced copy a viewer sees and send it back as an update:

Modify the following with your specific values to generate a copyable command:
kubectl patch connectors.management.loft.sh netbox-main --type=merge -p '{"spec":{"displayName":"Primary NetBox"}}'

The API validates every update in full, including credentials already required by the selected authentication method. An incomplete legacy Secret, such as an Argo CD Secret with no usable credential or a MySQL Secret with no port, refuses any update until you supply the missing fields.

Use the API from automation​

The API supports create, get, list, update, patch, and delete. It doesn't support watch or collection deletion, so poll lists instead.

Create and update validate the payload and the license features it needs. A patch is validated as the object that results from it. Status is read-only, so a write that includes status doesn't change it. A delete can return successfully while a finalizer still holds the backing Secret for cleanup.

Use server-side apply, imperative commands, or read-modify-write replacement. Client-side apply can't reliably track its previous configuration because the API withholds the last-applied annotation.

spec.displayName and spec.description map to the backing Secret's Platform annotations, and the payload section sets its loft.sh/connector-type label. To manage backing Secrets directly, use a kubeconfig for the control plane cluster instead of the management API.

Grant use to a tenant​

Adding a label to a connector updates it through the API, the same as any other change. For a connector created directly as a Secret, the label change removes Secret data keys the API doesn't model, and it fails until any missing required fields are supplied. Review Update credentials before you label a connector that existing automation also writes. A name grant doesn't require a label and leaves the connector's Secret data untouched, so it suits those connectors.

First enable connector use on the Tenant. Every grant method requires it:

Modify the following with your specific values to generate a copyable command:
kubectl patch tenants.management.loft.sh acme --type=merge -p '{"spec":{"connectors":{"enabled":true}}}'

Choose one of these grant methods.

Assign one connector​

Assign the connector exclusively to the tenant:

Modify the following with your specific values to generate a copyable command:
kubectl label connectors.management.loft.sh prod-db tenant.vcluster.com/exclusive-to=acme --overwrite

An assigned connector is visible only to that tenant, so other tenants' name and label grants don't match it.

Grant connectors by name​

Grant specific connectors to the Tenant by name:

Modify the following with your specific values to generate a copyable command:
kubectl patch tenants.management.loft.sh acme --type=merge -p '{"spec":{"connectors":{"enabled":true,"allow":{"byName":["prod-db"],"byLabels":null}}}}'

Names must match exactly. Wildcards, empty names, and duplicates are refused. A merge patch replaces the whole byName list, so include every connector the tenant should keep.

Platform applies a name grant asynchronously, so the connector can take a moment to appear in the tenant's list.

You can't combine byName with a non-empty byLabels selector. Tenant admission refuses that with byName and byLabels cannot both be set. To grant a labeled set plus one more connector, label that connector and widen the byLabels selector instead.

The patch clears byLabels because a merge patch keeps an existing selector. A leftover non-empty selector fails validation, and a leftover byLabels: {} grants every eligible admin-managed connector.

Share matching connectors​

Label a connector and grant matching connectors to the Tenant:

Modify the following with your specific values to generate a copyable command:
kubectl label connectors.management.loft.sh prod-db tier=shared --overwrite
kubectl patch tenants.management.loft.sh acme --type=merge -p '{"spec":{"connectors":{"enabled":true,"allow":{"byLabels":{"tier":"shared"},"byName":null}}}}'

The patch clears any existing byName grant, since the two selectors can't both be set.

Use labels that the Connector API passes through. Tenant admission refuses a byLabels selector on the projected connector-type or fleet-observability labels, with this label is not served on connectors, so it cannot select one.

An empty selector (byLabels: {}) grants every eligible admin-managed connector, and Platform then ignores byName. An absent or null selector grants none by label. To replace an existing selector with an empty map through a merge patch, clear it with null first.

Verify the grant​

Create an access key for a user in the tenant with the loft-connectors-viewer role. Use a separate CLI configuration and kubeconfig for tenant checks. Keep the existing admin session for grant changes.

Log in with that user's key. Then use vcluster platform connect management --print to write the tenant kubeconfig:

Modify the following with your specific values to generate a copyable command:
vcluster platform login https://platform.example.com --access-key tenant-access-key --config tenant-vcluster.json --docker-login=false
vcluster platform connect management --config tenant-vcluster.json --print > tenant-kubeconfig.yaml
kubectl --kubeconfig tenant-kubeconfig.yaml get connectors.management.loft.sh

The granted connector appears with a reduced configuration. A connector assigned elsewhere stays hidden.

Validate connector use​

The grant and the caller's resource permissions both matter. Naming a connector in a template doesn't grant the tenant access to it.

For database, Argo CD, and observability cluster configuration, writes introducing a literal connector reference check the owning tenant's usable connectors. Missing, hidden, and wrong-type connectors receive the same refusal, a validation error that reads does not name a usable connector. The error is reported on the cluster's template reference or Helm values, not on the connector field itself.

For example, adding this configuration to a granted cluster template doesn't let an ungranted tenant use prod-db:

vcluster.yaml
controlPlane:
backingStore:
database:
external:
# The owning tenant also needs a grant for this connector.
connector: prod-db

Create a cluster from that template as the tenant. Without the connector grant, the literal reference is rejected. Restore the grant in the admin session, then retry the cluster creation as the tenant.

Checks run at different points, so some edits succeed after a grant is lost. A connector name supplied through a template parameter is checked when the cluster reconciles, and the cluster's connector condition reports a failure. See A cluster reports an unusable connector. An edit that keeps or removes a reference already in effect isn't checked again, so it succeeds even after the grant is revoked.

A cluster that uses a versioned template is checked on every write. If its template version names a connector the tenant can't use, writes fail until the grant returns or the template changes.

OSImage create, upload, and finalize requests fail if the tenant can't use the spec.connectorRef image store.

NodeProvider creation checks spec.metal3.netBox.secretRef, and so does an update that changes it. The reference must name a NetBox connector in the Platform namespace that the owning tenant can use. The NetBox sync also checks the grant again before it calls NetBox. See Reference it from a node provider.

These checks cover database, Argo CD, observability, OSImage, and NetBox references.

Revoke a grant and clean up​

In the admin session, remove an exclusive assignment:

Modify the following with your specific values to generate a copyable command:
kubectl label connectors.management.loft.sh prod-db tenant.vcluster.com/exclusive-to-

If the tenant must lose all access, also remove the connector's name from byName and any matching label grant. To remove a name, patch the byName list without it. Disabling spec.connectors.enabled blocks all connector access for that tenant.

Verify the revocation with the tenant kubeconfig created in Verify the grant:

kubectl --kubeconfig tenant-kubeconfig.yaml get connectors.management.loft.sh

The connector no longer appears.

Losing a grant blocks new use of the connector. Resources already provisioned through it aren't removed right away.

ConsumerBehavior after grant loss
Database, not yet provisionedOn reconciliation, DBConnectorSynced=False with reason ConnectorUnusable. No database is provisioned.
Database, already provisionedThe cluster keeps its database and existing database condition.
Argo CDNew use fails. An ArgoCDApplication can report InvalidConnector. Existing registration remains until integration removal or cluster deletion.
ObservabilityNew writer credential requests fail, and the cluster reports ObservabilityConnectorUnresolved=False with reason ObservabilityConnectorUnusable. A writer key issued before the grant loss keeps working.
OS image storeNew upload and finalize requests refuse an unusable connector.
NetBoxThe NodeProvider stops syncing from NetBox and reports ConnectorUsable=False with reason ConnectorUnusable. Machines already imported are kept.

Changing a Tenant's grants doesn't immediately enqueue every dependent object. Checks run when the object next reconciles. Don't use a condition's unchanged value as proof that a revoked grant still works.

When offboarding the tenant, use the admin session to delete its clusters through their normal lifecycle:

Modify the following with your specific values to generate a copyable command:
kubectl delete virtualclusterinstances.management.loft.sh app-dev -n p-team-a

Database and Argo CD cleanup use the recorded connector identity even after grant loss. Database deletion still respects the configured reclaim policy. Keep the connector and its credentials available until cleanup finishes.

Don't edit Platform-recorded connector annotations to repair a grant. Platform owns loft.sh/argocd-connector and the connector identity recorded on per-cluster database Secrets. VirtualClusterInstance writes can't set or change the Argo CD annotation.

Before deleting a connector, complete tenant offboarding and verify that no cluster or integration still depends on it.

Migrate database discovery​

Replace calls to the deprecated, list-only databaseconnectors.management.loft.sh resource with a filtered Connector list:

kubectl get connectors.management.loft.sh -l loft.sh/connector-type=shared-database

Keep connector names unchanged. Map DatabaseConnector.spec.displayName to Connector.spec.displayName, and DatabaseConnector.spec.type to Connector.spec.sharedDatabase.dialect.

Grant the reader loft-connectors-viewer. Unlike the old database list, Connector discovery isn't granted to every authenticated user.

No data migration or Secret deletion is needed. Existing raw-Secret consumers remain compatible. Reverting discovery to the old resource doesn't undo API configuration changes, restore discarded data keys, or make new Connector fields available on an older Platform version.

Troubleshoot connector access​

A connector is missing or listing returns Forbidden​

Check the user's management role, the Tenant's enabled capability, and whether the connector is assigned, named in byName, or matched by labels. Confirm that the requested connector has the expected type.

A cluster reports an unusable connector​

For a database connector, inspect the cluster's DBConnectorSynced condition. For an observability connector, inspect its ObservabilityConnectorUnresolved condition. For a NetBox connector, inspect the NodeProvider's ConnectorUsable condition. Then check the owning Tenant's grants. Restore the grant or choose an allowed connector. Don't repoint an existing database connector at a different database server.

A connector stays pending deletion​

Check the backing Secret's finalizers. An observability connector can remain pending when its cleanup controller isn't running after a license expires. The controller runs only when the license includes fleet-observability, and never on a Platform running embedded Kubernetes. Restore the license. Platform restarts itself when a licensed feature's status changes. If cleanup still doesn't run, restart Platform. Don't remove the finalizer by hand while the controller can still run. See Delete a connector.