Am Driver Laravel Package

Product Decisions This Supports

• Multi-Tenant SaaS Orchestration:

  • Enhanced Tenant Context Tracking: Leverage the new integrationInstanceId in callbacks to correlate tenant actions across distributed systems (e.g., link CREATE_INSTANCE in AM to specific integration instances like captain-learning:dev). Example: Use integrationInstanceId to route tenant events to dedicated microservices (e.g., tenant-provisioner@captain-learning-dev).
  • Debugging & Auditing: Append integrationInstanceId to logs in AmDriverEventListener for granular traceability of orchestration commands (e.g., CREATE_INSTANCE for tenant:123 in integration:captain-learning:dev).

• Usage-Based Billing & Compliance:

  • Fine-Grained Consumption Tracking: Use integrationInstanceId to scope usage metrics (e.g., proof_storage_mo) to specific product/environment pairs. Example: Charge captain-learning:prod separately from captain-learning:staging based on integrationInstanceId.
  • SLA Isolation: Apply per-integration SLAs (e.g., 99.9% uptime for captain-learning:prod vs. 99% for staging) by filtering OperationalStateStoreInterface queries with integrationInstanceId.

• Self-Healing Infrastructure:

  • Context-Aware Remediation: Extend StopInstanceHandler to validate integrationInstanceId before shutdown (e.g., block STOP for captain-learning:prod during business hours). Example:

    if ($command->getIntegrationInstanceId() === 'captain-learning:prod' && $this->isBusinessHours()) {
        throw new \RuntimeException('Cannot stop prod instance during business hours');
    }
    

• Developer Experience:

  • Local Testing: Use integrationInstanceId in orchestration:simulate CLI to mimic multi-integration environments locally. Example:

    vendor/bin/am-driver orchestration:simulate create --integration-instance-id captain-learning:dev
    

  • Documentation: Update Swagger UI (/am/swagger) to highlight integrationInstanceId in callback payloads for API consumers.

• Security & Compliance:

  • Token Scoping: Align consumption_webhook_token with integrationInstanceId to restrict usage data pushes to specific integrations (e.g., captain-learning:prod token only accepts metrics for that instance).
  • Audit Trails: Log integrationInstanceId in SIEM events to track cross-integration command flows (e.g., CREATE_INSTANCE in captain-learning:dev triggers a DB provision in database-manager:shared).

When to Consider This Package

Adopt if:

• You need to differentiate tenant actions by integration context (e.g., captain-learning:prod vs. captain-learning:staging) and:
  • Track per-integration usage (billing/compliance).
  • Enforce context-specific SLAs (e.g., stricter uptime for prod).
  • Debug cross-system orchestration flows (e.g., CREATE_INSTANCE → DB provision → notification).
• Your AM integrations span multiple environments (e.g., dev, staging, prod) and require granular control over lifecycle events.
• You’re using AM’s callback system and need to correlate responses with the originating integration instance.

Look elsewhere if:

• Your tenant model is flat (no need to distinguish between integrationInstanceId contexts).
• You’re not using AM callbacks (this feature is callback-specific).
• Your security model requires full isolation between integrations (e.g., separate tokens per integrationInstanceId may complicate key management).
• You’re not leveraging AM’s orchestration protocol (e.g., using custom webhooks or direct API calls).

How to Pitch It (Stakeholders)

For Executives: *"This update adds integrationInstanceId to AM callbacks, letting us track and control tenant actions at the integration level (e.g., captain-learning:prod vs. staging). This enables:

• Precision Billing: Charge captain-learning:prod separately from staging based on per-integration usage.
• SLA Granularity: Enforce stricter SLAs for production while allowing flexibility for dev environments.
• Debugging: Correlate cross-system events (e.g., CREATE_INSTANCE → DB provision) with their originating context.

Example: If captain-learning:prod hits a storage limit, we can auto-scale only that instance while leaving staging unaffected.

Risk: Minimal—this is a non-breaking addition to existing callbacks. We’ll validate in a 1-hour spike by testing integrationInstanceId in our CreateInstanceHandler."*

For Engineering: *"The new integrationInstanceId in callbacks lets us:

• Scope handlers to specific integrations. Example:

  public function handle(OrchestrationCommand $command): void {
      if ($command->getIntegrationInstanceId() === 'captain-learning:prod') {
          $this->prodProvisioner->provision($command->getTenantId());
      }
  }
  

• Log context in AmDriverEventListener:

  public function onCommandProcessed(CommandEvent $event): void {
      $this->logger->info(
          'Processed command for tenant: ' . $event->getTenantId() .
          ' in integration: ' . $event->getIntegrationInstanceId()
      );
  }
  

• Test locally with the CLI:

  vendor/bin/am-driver orchestration:simulate create \
    --integration-instance-id captain-learning:dev
  

Tradeoffs:

• Callback-Only: integrationInstanceId is only available in AM callbacks (not orchestration commands).
• Token Alignment: Ensure your consumption_webhook_token is scoped to the correct integration in AM’s UI.
• Backward Compatibility: Existing code ignores integrationInstanceId if not used (no breaking changes).

Next Steps:

1. Spike: Test integrationInstanceId in CreateInstanceHandler for captain-learning:prod.
2. Update Docs: Add integrationInstanceId to Swagger UI and internal runbooks.
3. Log Correlation: Extend AmDriverEventListener to include integrationInstanceId in SIEM events."*

For Security/Compliance: *"The integrationInstanceId adds context to audit trails, but we must:

• Validate Tokens: Ensure consumption_webhook_token is tied to a specific integration (e.g., captain-learning:prod) to prevent cross-integration metric leaks.
• Log Context: Include integrationInstanceId in all orchestration events sent to SIEM for forensic traceability.
• Access Control: If using role-based tokens, scope permissions to integrationInstanceId (e.g., STOP allowed only for captain-learning:staging).

Risk: Misconfigured tokens could allow cross-integration commands. Mitigate by:

• Whitelisting integrationInstanceId in AM’s ManagedAppIntegration UI.
• Monitoring for commands with mismatched integrationInstanceId/token scopes."