> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Migration verification
> Run DNS and TLS probes to confirm old-provider endpoints are unreachable, review the timeline, and get the safe-to-delete banner before cutting over.
# Migration verification
Before KnoxCall marks a migration complete, verification confirms that:
1. Old-provider endpoints are becoming unreachable (your applications have stopped calling them)
2. All known consumers have been seen routing through KnoxCall
3. An operator has explicitly confirmed the migration is clean
## The verification dashboard
Navigate to **Infrastructure → Secret Store Migrations → your migration → Verification tab**.
The dashboard shows:
* **Per-probe timeline** — a chronological list of DNS and TLS probe results, one row per probe
* **Consumer status** — which workloads have been seen using the KnoxCall path vs still hitting the old provider
* **Operator confirmation** — a button that unlocks once probes are green
* **Safe-to-delete banner** — appears when all three conditions above are met
## DNS and TLS probes
KnoxCall runs two probe types against each migrated secret's original provider endpoint:
| Probe type | What it checks | "Pass" condition |
| - | - | - |
| **DNS** | DNS resolution of the old provider hostname (e.g. `secretsmanager.us-east-1.amazonaws.com`) | ✅ Resolves correctly (we want it to still resolve during migration) |
| **TLS** | TLS handshake attempt to the old provider | ✅ Handshake succeeds (again — expected during migration phase) |
Probes run every 5 minutes during an active migration. The verification dashboard uses the **absence** of consumer traffic to the old endpoint (not unreachability) as the primary signal — "pass" means the endpoint is still reachable but your apps are no longer hitting it.
The probes don't check if your apps are calling the old endpoint — that tracking comes from the agent's `secret_consumers` table. Probes check reachability for operational awareness (e.g. if the cloud provider decommissions an API endpoint mid-migration).
## Operator confirmation
Once all items have been reviewed and approved, and consumer status shows all known workloads routing through KnoxCall:
1. Click **Commit migration** in the admin UI
2. Or call the API:
```bash theme={"dark"}
curl -X POST https://api.knoxcall.com/admin/migrations/mgr_01abc.../commit \
-H "Authorization: Bearer $KC_ADMIN_JWT"
```
This writes approved items as live KnoxCall secrets. The migration must be in `awaiting_review` status with at least one approved item.
One request commits up to `batch_size` items (250); a larger migration stays in `awaiting_review` with a non-zero `remaining_count`, and you repeat the call — in the admin UI, click **Commit migration** again — until it reaches `0` and the status becomes `completed`.
Response:
```json theme={"dark"}
{
"id": "mgr_01abc...",
"status": "completed",
"committed_count": 30,
"remaining_count": 0,
"batch_size": 250
}
```
## Safe-to-delete guidance
Once a migration reaches `completed` status, it is safe to clean up the source cloud store when all of the following hold:
* All tracked consumers have been seen routing through KnoxCall at least once
* Verification events show no probe errors in the last 24-hour window
* The commit has succeeded (`status: "completed"`)
At that point:
* You can revoke the IAM/read permissions KnoxCall used to discover secrets from the cloud store
* You can archive or delete the secrets from the original cloud store
* Removing intercept rules or DB proxy routes at this point is safe
## Verification timeline API
Fetch the full probe history:
```bash theme={"dark"}
curl https://api.knoxcall.com/admin/migrations/mgr_01abc.../verification-events \
-H "Authorization: Bearer $KC_ADMIN_JWT"
```
Response:
```json theme={"dark"}
{
"migration_id": "mgr_01abc...",
"safe_to_delete": false,
"verified_at": null,
"verification_window_days": 35,
"events": [
{
"id": "vev_01...",
"secret_migration_item_id": null,
"event_type": "tls_probe",
"endpoint_url": "secretsmanager.us-east-1.amazonaws.com:443",
"outcome": "still_reachable",
"details": {},
"source": "agent",
"created_at": "2026-05-25T10:25:00Z"
},
{
"id": "vev_02...",
"secret_migration_item_id": null,
"event_type": "dns_probe",
"endpoint_url": "secretsmanager.us-east-1.amazonaws.com",
"outcome": "still_reachable",
"details": {},
"source": "agent",
"created_at": "2026-05-25T10:25:00Z"
}
]
}
```
## Troubleshooting
**DNS probe shows `fail`:**
* Cloud provider may have changed the endpoint hostname — check for provider announcements
* If using a VPC endpoint, ensure the agent has DNS visibility to the VPC endpoint resolver
**TLS probe shows `fail`:**
* Certificate rotation at the cloud provider — usually transient; check if the next probe resolves
* Network policy blocking agent outbound to the cloud store — check firewall / security group rules
**Consumer still showing old provider after routing through KnoxCall:**
* Some consumers may be long-running processes that cached the old connection — restart them
* Check for consumers not covered by the intercept rules (path prefix mismatch)
**Operator confirmation button greyed out:**
* One or more consumers have not yet been seen through the KnoxCall path
* Check the consumer list for any workloads in `pending` state and verify they're running and using the updated connection string (Bucket B) or within the intercept scope (Bucket A)
HTTPS intercept setup and cutover
Database proxy setup and cutover
Verification events and confirm endpoints
Back to overview
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.