Manage static outbound API routing on Laravel Cloud
Use this runbook to release and maintain a selected static-egress integration while keeping the rest of the application unchanged. It separates configuration changes from route evidence and provider acceptance, which makes rollback and future credential rotation easier to reason about.
Record the integration boundary
Maintain a private record of the target provider and environment, selected subscription, accepted source region, assigned IPv4 pair, shared or dedicated arrangement, owner, and the code paths using the client. Include the framework and locked dependency versions.
Record the names of secret keys and where they are linked, not their values. Identify independent SDKs, queues, and scheduled tasks. This inventory is the scope for rollout and regression checks; do not treat every outbound connection as covered.
Prepare a release
- Review the provider’s acceptance of both addresses and its source-region or ownership rules.
- Add the configuration file and selected factory without replacing unrelated application files.
- Keep API authentication and request semantics unchanged.
- Run PHP lint and the application’s isolated tests on the intended runtime and dependencies.
- Exercise the missing-secret and failed-request paths. Neither should retry directly.
- Confirm the target Cloud secret linkage and any overriding custom variable.
- Retain the existing build steps and configuration-caching process.
- Choose an operator-approved harmless provider request for acceptance testing.
Avoid testing a payment, account mutation, notification, or other state-changing workflow merely to prove networking. Use the provider’s permitted read operation or dedicated diagnostic where available.
Verify after deployment
Run the deployed Artisan echo check and compare the value to the assigned pair. Then verify the actual authenticated web, queue, and scheduled paths that belong to this integration. Where the provider exposes source or request logs, correlate the request there.
Record separate outcomes for the echo and provider request. Preserve a sanitized status or request ID, not a raw response body. Mark each relevant path as passed, failed, or not exercised. Do not turn an unexercised scheduled path into an assumed pass because the controller worked.
Cloud’s one-time command behavior and worker lifecycle explain why these checks are distinct.
Rotate a proxy credential
Before changing anything, identify the active secret, all environments that share it, and the approved rollback value or process. Check whether the rotation also changes the assigned IPs; do not assume it does or does not.
Update the authorized secret location, resolve any custom-variable override, and redeploy the intended environments. Verify a fresh command, a real worker execution, and the actual provider path. Use a new timestamp and release identifier so old logs cannot be mistaken for a new pass.
Coordinate old-credential retirement with the service’s supported rotation process and the application’s deployment coverage. Never print the current or previous value to compare them. Keep the old configuration only as long as the approved rollback and credential policy permit.
Move from shared to dedicated addresses
Treat this as an address change as well as a connection change. QuotaGuard’s migration guidance describes new addresses and connection credentials.
Obtain provider approval for both new addresses before directing production calls through them. Update the expected pair used by diagnostics alongside the connection configuration. Verify the new path in each intended environment. Remove old allowlist entries only after the agreed transition and rollback window, using the provider’s change procedure.
Do not describe a dedicated arrangement as necessary for every API. The destination’s actual requirements determine that choice.
Roll back without exposing a direct route
If the new route fails, preserve the provider’s allowlist while investigating. Restore a known, approved proxy configuration and expected pair where the rollback plan allows it, then redeploy and recheck. If no valid approved route exists, pause the affected integration or use its existing controlled failure path.
Do not remove the proxy option, disable the provider allowlist, or add a direct retry as an emergency shortcut. For pending business operations, reconcile provider state before retrying work. Networking rollback and transaction reconciliation are separate responsibilities.
Keep diagnostics useful
Use ordinary application success and failure metrics for ongoing operations. Run a targeted echo check after relevant configuration, transport, or dependency changes and when diagnosing a route question. A continuous stream of echo traffic is not a substitute for observing real provider requests.
Revalidate the actual transport after major framework or client changes, secret-management changes, moving environments or regions, introducing a new SDK, and changing the assigned pair. Recheck current official instructions before changing protocol settings.
Definition of operational readiness
The selected integration has documented provider acceptance, a controlled configuration source, passing application tests, evidence from its real execution paths, safe diagnostics, and an approved failure or rollback behavior. The scope is the integration you verified, not every process in Laravel Cloud.
Download the reference examples · Integration overview