Deep Dive
Connector lifecycle
Install, observe, pause, resume, restart, and safely remove connectors
A connector is a tenant-owned data flow between one SQIP topic and an external system. SQIP manages its configuration, desired state, and operational status.
Installation stages
The connector installer has four stages:
- Placement — choose the tenant, installation name, cluster, namespace, and topic.
- Configure — enter connector-specific settings, parallelism, and credentials.
- Review — confirm the connector version, direction, placement, and runtime settings.
- Install — queue the request and follow its status on the Connectors page.
Sources use an Output topic because they bring records into SQIP. Sinks use an Input topic because they deliver existing topic records elsewhere.
Installation names
An installation name must:
- Contain 3–63 characters.
- Start with a letter.
- Use only letters, numbers, dots, underscores, or dashes.
- Be unique for its tenant.
Example: orders-to-warehouse.
Credentials
SQIP supports two credential approaches:
| Approach | When to use it |
|---|---|
| One-time credentials | Enter the token, username, or password directly in the installer. SQIP does not display it again. |
| Existing secret reference | Select Use an existing secret reference instead when your administrator has already prepared a compatible secret. |
Do not enter both. When you type a one-time credential, SQIP clears the existing reference; when you enter a reference, it clears the one-time values.
Desired state and observed phase
The desired state is what you asked SQIP to do. The phase is what SQIP currently observes.
| Value | Meaning |
|---|---|
RUNNING | The connector should actively process records |
PAUSED | The connector should remain stopped without being deleted |
PENDING or PROVISIONING | Installation or a requested change is still being applied |
RUNNING phase | The connector is available and matches the requested state |
DEGRADED | The connector is available but needs investigation |
FAILED | SQIP could not complete the requested state |
It is normal for the observed phase to lag briefly behind the requested action.
Day-two actions
| Action | Use it when |
|---|---|
| Pause | You need to stop data movement temporarily without losing the installation |
| Resume | You are ready to continue a paused connector |
| Restart | The configuration is correct but the running process needs to be refreshed |
| Connector logs | You need status details or the reason an operation failed |
| Delete | The data flow is permanently retired |
Tenant administrators can install and delete connectors. Cluster administrators and delegated operators can perform lifecycle actions only when their permissions allow it.
Delivery behavior
Connectors are designed for reliable, at-least-once delivery. After a timeout or interruption, an item may be processed again.
- Use stable record identifiers.
- Prefer upsert or deduplication at destinations.
- Avoid making a destination action unsafe to repeat.
- Confirm both the source and destination after recovering from an incident.
Troubleshooting sequence
- Read the connector's message and phase on the Connectors page.
- Open Connector logs and review the most recent warning or error.
- Confirm that the endpoint, database, or file server is available.
- Confirm that credentials are current and authorized.
- Confirm that the selected topic and namespace still exist.
- Use Restart after resolving an external issue.
- Ask a tenant administrator to update configuration or credentials when required.