Apolo Applications

Use Apps for long-running deployments and managed services, including databases, APIs, and web UIs. Use jobs only for bounded R&D, builds, migrations, batch work, and tests; never keep a job alive to emulate a deployment.

1. Resolve the exact context and call list_app_templates before selecting a template. Compare the available templates against the user's requested outcome using titles, descriptions, tags, current versions, and known operational tradeoffs. Do not assume a template before discovery or narrow the initial search.

2. Present the best matching candidate and meaningful alternatives, including why each fits, important limitations, and user-facing consequences. Ask the user to confirm the template when that choice determines or changes the user-facing deployment. Do not plan or install until confirmed. A user who already named an exact template and version has confirmed that choice unless discovery shows it is missing or unsuitable.

3. Call list_app_template_versions and retrieve the selected version's current input schema with get_app_template. Never hard-code a remembered schema. For Validate only fields defined by that schema and report unsupported requested fields.

4. Create an install or configure plan. Seed configure input from the app's current input before applying a requested patch. Do not mutate the app while planning.

5. Review the stable plans/apps/<target>/<timestamp>/inputs.yaml, plan.json, and PLAN.md. Show exact template version, context, app/current revision, dependencies, resources, endpoints, validation, destructive effects, expiry, and SHA-256. Permit secret references only; never resolve secret values.

6. Describe the exact reviewed operation, then invoke it so the MCP host can apply its approval UI. Require managed or full server policy and the exact unexpired single-use plan. Recheck checksum, parsed YAML, context, template, and current revision. Reject edits or drift and create a fresh plan.

7. Wait with a bound, then verify app state, rollout logs, events, output, and endpoints. For a service, verify public authenticated access when possible and a same-project in-cluster endpoint. If public exposure is unavailable, record the exact platform/schema reason and the in-cluster evidence instead. Record bounded failure evidence.

8. Create rollback and uninstall as fresh no-payload plans bound to exact app and revision state. Require stricter destructive approval/policy and never invent YAML for an operation whose SDK/CLI has no file input.

9. Record created app IDs in the ledger and automatically clean up only exact ledger-owned IDs. Preserve reviewed inputs and the sanitized execution result.

When an App needs a custom image, use the Flow-first image-build workflow. Prefer dedicated content-addressed component images in an existing Flow project and fall back to the documented apolo-extras image build command only without Flow context. The remote builder is a bounded job; the resulting service still belongs in an App. Record the exact builder job, build-context path, and image tag, then clean only those created targets.

For the Service Deployment template, preserve Apolo image URI semantics in the template input. Use an image: repository reference and pass its tag separately:

image:
  repository: image:my-service
  tag: release-2026-07-30
  pull_policy: IfNotPresent

Do not replace it with the resolved registry.<cluster>... hostname. The image: reference lets the platform resolve the current context and inject the required image pull credentials. Discover the current template schema first because the repository and tag field shape remains template-version-specific.

Never reuse a consumed or failed plan, accept approval for a changed file, or declare rollout success from submission alone.