platform-deploy-runtime

Runtime components for the platform application deployment control plane.

This repo owns the deploy API service and Flink-side preparation jobs. Directus schema and app registry collections stay in k8s-cms; the NiFi orchestration flow stays in dataflow-platform-deploy-app.

Components

• platform-deploy-service/ - internal API used by the Organization Management UI and Hasura/Gravitee actions to queue app deploy/destroy operations and update deploy-time Vault secrets.
• platform-deploy-flink-job/ - Flink batch job that validates/enriches a queued operation and publishes the prepared NiFi request.
• manifests/ - Kubernetes resources for the runtime service and Flink jar upload hook.
• .github/workflows/ - image build/publish workflows for runtime images.
• docs/platform-deploy-service-openapi.yaml - static OpenAPI copy for the deploy service contract.

Image Publishing

The GitHub Actions image workflows publish to GHCR using the repository GITHUB_TOKEN by default. If GHCR rejects the push with write_package, add a repository secret named GHCR_PAT with write:packages access and, when the PAT owner is not the workflow actor, a GHCR_USER secret containing that username. For existing org packages, the package must also grant this repository write access under the package's Actions access settings.

Deployment Flow

1. Internal Organization Management creates or updates a platform_apps row in Directus.
2. The UI calls platform-deploy-service.
3. platform-deploy-service creates a platform_app_operations row and submits platform-deploy-flink-job through Flink REST.
4. The Flink job validates the payload, publishes to batch.platform.deploy.prepared.v1, and calls the service callback.
5. dataflow-platform-deploy-app consumes the prepared Kafka request and runs the NiFi orchestration flow.

Detailed non-secret operation progress is stored in platform_app_operation_steps. Pipeline components can call POST /internal/operations/{operation_id}/steps/{step_key} to upsert current step status, message, timing, and sanitized result metadata. The Organization Management UI can read the same rows through the Directus/Hasura platform_app_operation_steps collection or via GET /internal/operations/{operation_id}/steps.

When the UI supplies notification_context, platform-deploy-service preserves that context on the operation payload and emits a notification request after each step status update. Deployment operation notifications are internal operational messages even when the managed target is an external customer app. The service therefore resolves the single active internal/internal app from Directus and uses its current ID for notification templates and browser-subscription routing. The lookup is validated and briefly cached; no environment-specific app UUID is stored in the service or manifest. The target app ID remains in notification parameters and metadata for context. Notification tests do not use the deploy service and may still explicitly select internal or external app settings. Deployment operation notifications are browser-push-only until user notification preferences exist. If the context includes a browser subscription id, user id, or user email, the notification service is asked to resolve browser push targets. The optional notification_preferences.browser_push_device_target value selects current_device (the default), favorite_device, or all_devices. If no browser push target can be resolved, the notification is skipped/logged instead of falling back to email or SMS. Notification failures are logged but do not fail or block the deployment operation.

Validation

cd platform-deploy-service
npm run build

cd ../platform-deploy-flink-job
mvn -B -ntp package

Secrets are resolved at runtime from Vault/Kubernetes. Do not commit secret values to this repo.

platform-deploy-service accepts either its service-internal token from secret/data/platform-deploy-service#token or the configured Directus platform management service token. In Kubernetes, that Directus token is resolved from secret/data/directus/gravitee/clients/<graphql-api-client-id>#token, matching the token forwarded by Gravitee after it exchanges the user bearer token through directus-auth-bridge.

GET /internal/secrets/platform-deploy loads the operator-managed Terraform Cloud, Cloudflare, and GitHub source credentials for the Organization Management dialog. GitHub source access can use either github_token or GitHub App fields github_app_id, github_app_installation_id, and github_app_private_key. POST /internal/secrets/platform-deploy writes those same fields to Vault paths secret/data/platform-deploy-service and secret/data/platform-deploy-service/github; github_token is also kept on the main path for backwards compatibility. The auth gateway admin token is resolved from the existing internal secret/data/auth-gateway-admin-api#value secret, not from this UI/API. The service merges submitted keys with existing KV data so internal tokens remain intact.

Set RETURN_PLATFORM_DEPLOY_SECRET_VALUES=false on platform-deploy-service to keep GET /internal/secrets/platform-deploy from returning raw secret values. When disabled, the endpoint still reports which secret fields are configured and returns empty strings for the value fields.

Set PLATFORM_DEPLOY_NOTIFICATIONS_ENABLED=false to disable deployment status notification requests. PLATFORM_NOTIFICATION_SERVICE_URL defaults to the in-cluster platform-notification-service endpoint.