cpflow 5.1.0 → 5.2.0

data/lib/command/deploy_image.rb

@@ -3,42 +3,110 @@
 require "resolv"
 
 module Command
-  class DeployImage < Base
+  class DeployImage < Base # rubocop:disable Metrics/ClassLength
     NAME = "deploy-image"
     OPTIONS = [
       app_option(required: true),
+      workload_option(repeatable: true),
       run_release_phase_option,
       use_digest_image_ref_option
     ].freeze
     DESCRIPTION = "Deploys the latest image to app workloads, and runs a release script (optional)"
     LONG_DESCRIPTION = <<~DESC
       - Deploys the latest image to app workloads
+      - Use `--workload`/`-w` one or more times to deploy only selected app workloads
+      - If `deploy_order` is configured and no `--workload` is provided, deploys ordered workload groups one at a time and waits for each group to be ready before continuing
+      - Workloads listed in `app_workloads` but omitted from `deploy_order` deploy last as an implicit final group
       - Runs a release script before deploying if `release_script` is specified in the `.controlplane/controlplane.yml` file and `--run-release-phase` is provided
       - The release script is run in the context of `cpflow run` with the latest image
       - If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code
       - If `use_digest_image_ref` is `true` in the `.controlplane/controlplane.yml` file or `--use-digest-image-ref` option is provided, deployed image's reference will include its digest
       - Repairs missing `shared_secret_grants` policy bindings before running a release phase or updating workloads
     DESC
+    EXAMPLES = <<~EX
+      ```sh
+      # Deploys the latest image to all app workloads.
+      cpflow deploy-image -a $APP_NAME
+
+      # Deploys only one app workload.
+      cpflow deploy-image -a $APP_NAME -w node-renderer
+
+      # Deploys only selected app workloads.
+      cpflow deploy-image -a $APP_NAME -w node-renderer -w sidekiq
+      ```
+    EX
 
     def call
       release_script = release_script_to_run
       image = resolve_image_to_deploy
       shared_secret_policy_grant_pairs = resolve_shared_secret_policy_grants
-      workload_data_by_name = app_workload_data
+      workload_data_by_name = app_workload_data(workload_names_to_deploy)
 
       bind_shared_secret_policy_grants(shared_secret_policy_grant_pairs)
       run_release_script(release_script) if release_script
-      deploy_image_to_workloads(image, workload_data_by_name)
+      deploy_image(image, workload_data_by_name)
     end
 
     private
 
-    def app_workload_data
-      config[:app_workloads].to_h do |workload|
+    def workload_names_to_deploy
+      app_workloads = config[:app_workloads]
+      requested_workloads = requested_workload_names
+      return app_workloads if requested_workloads.empty?
+
+      ensure_workloads_configured!(requested_workloads, app_workloads)
+      requested_workloads
+    end
+
+    def ensure_workloads_configured!(requested_workloads, app_workloads)
+      requested_workloads.each do |workload|
+        next if app_workloads.include?(workload)
+
+        raise "Workload '#{workload}' must be listed in app_workloads for app '#{config.app}'."
+      end
+    end
+
+    def app_workload_data(workloads)
+      workloads.to_h do |workload|
         [workload, cp.fetch_workload!(workload)]
       end
     end
 
+    def deploy_image(image, workload_data_by_name)
+      deployed_endpoints = {}
+
+      if deploy_in_order?
+        deploy_image_to_ordered_workloads(image, workload_data_by_name, deployed_endpoints)
+      else
+        deployed_endpoints.merge!(deploy_image_to_workloads(image, workload_data_by_name))
+      end
+    ensure
+      print_deployed_endpoints(deployed_endpoints)
+    end
+
+    def deploy_in_order?
+      requested_workload_names.empty? && config.deploy_order
+    end
+
+    def deployment_groups(workload_data_by_name)
+      ordered_groups = config.deploy_order
+      ordered_workloads = ordered_groups.flatten
+      unordered_workloads = workload_data_by_name.keys - ordered_workloads
+
+      [*ordered_groups, unordered_workloads].reject(&:empty?)
+    end
+
+    def deploy_image_to_ordered_workloads(image, workload_data_by_name, deployed_endpoints)
+      deployment_groups(workload_data_by_name).each do |group|
+        deployed_endpoints.merge!(deploy_image_to_workloads(image, workload_data_by_name.slice(*group)))
+        wait_for_workloads_ready(group)
+      end
+    end
+
+    def requested_workload_names
+      @requested_workload_names ||= Array(config.options[:workload]).map(&:to_s).uniq
+    end
+
     def deploy_image_to_workloads(image, workload_data_by_name) # rubocop:disable Metrics/MethodLength
       deployed_endpoints = {}
 
@@ -57,6 +125,10 @@ module Command
         end
       end
 
+      deployed_endpoints
+    end
+
+    def print_deployed_endpoints(deployed_endpoints)
       progress.puts("\nDeployed endpoints:")
       deployed_endpoints.each do |workload, endpoint|
         progress.puts("  - #{workload}: #{endpoint}")

data/lib/command/maintenance_off.rb

@@ -10,6 +10,7 @@ module Command
     DESCRIPTION = "Disables maintenance mode for an app"
     LONG_DESCRIPTION = <<~DESC
       - Disables maintenance mode for an app
+      - Safe to re-run: if a previous run timed out after switching the domain but before stopping the maintenance workload, re-running while maintenance mode is already disabled stops the maintenance workload to finish it (so it is not a pure no-op)
       - Specify the one-off workload through `one_off_workload` in the `.controlplane/controlplane.yml` file
       - Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance')
       - Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443

data/lib/command/maintenance_on.rb

@@ -10,6 +10,7 @@ module Command
     DESCRIPTION = "Enables maintenance mode for an app"
     LONG_DESCRIPTION = <<~DESC
       - Enables maintenance mode for an app
+      - Safe to re-run: if a previous run timed out after switching the domain but before stopping the app workloads, re-running while maintenance mode is already enabled stops the app workloads to finish it (so it is not a pure no-op)
       - Specify the one-off workload through `one_off_workload` in the `.controlplane/controlplane.yml` file
       - Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance')
       - Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443

data/lib/command/promote_app_from_upstream.rb

@@ -14,6 +14,7 @@ module Command
       - It performs the following steps:
         - Runs `cpflow copy-image-from-upstream` to copy the latest image from upstream
         - Runs `cpflow deploy-image` to deploy the image
+        - Honors `deploy_order` from `.controlplane/controlplane.yml` through `cpflow deploy-image`
         - If `.controlplane/controlplane.yml` includes the `release_script`, `cpflow deploy-image` will use the `--run-release-phase` option
         - If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code
         - If `use_digest_image_ref` is `true` in the `.controlplane/controlplane.yml` file or `--use-digest-image-ref` option is provided, deployed image's reference will include its digest

data/lib/command/ps_wait.rb

@@ -26,19 +26,11 @@ module Command
       ```
     EX
 
-    def call # rubocop:disable Metrics/MethodLength
+    def call
       @workloads = [config.options[:workload]] if config.options[:workload]
       @workloads ||= config[:app_workloads] + config[:additional_workloads]
 
-      @workloads.reverse_each do |workload|
-        if cp.workload_suspended?(workload)
-          progress.puts("Workload '#{workload}' is suspended. Skipping...")
-        else
-          step("Waiting for workload '#{workload}' to be ready", retry_on_failure: true) do
-            cp.workload_deployments_ready?(workload, location: config.location, expected_status: true)
-          end
-        end
-      end
+      wait_for_workloads_ready(@workloads, reverse: true)
     end
   end
 end

data/lib/command/run.rb

@@ -47,6 +47,8 @@ module Command
         and also overridden per job through `--cpu` and `--memory`)
       - By default, the job is stopped if it takes longer than 6 hours to finish
         (can be configured though `runner_job_timeout` in `controlplane.yml`)
+      - Non-interactive jobs return the Control Plane cron job status even when the job finishes before
+        Control Plane exposes a runner replica to attach logs to
     DESC
     EXAMPLES = <<~EX.freeze
       ```sh
@@ -97,7 +99,7 @@ module Command
 
     attr_reader :interactive, :detached, :location, :original_workload, :runner_workload,
                 :default_image, :default_cpu, :default_memory, :job_timeout, :job_history_limit,
-                :container, :job, :replica, :command
+                :container, :job, :replica, :command, :job_completed_before_replica_exit_status
 
     def call # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       @interactive = config.options[:interactive] || interactive_command?
@@ -129,6 +131,7 @@ module Command
       update_runner_workload
       start_job
       wait_for_replica_for_job
+      exit(job_completed_before_replica_exit_status) if job_completed_before_replica_exit_status
 
       progress.puts
       if interactive
@@ -269,7 +272,20 @@ module Command
         result = cp.fetch_workload_replicas(runner_workload, location: location)
         @replica = result&.dig("items")&.find { |item| item.include?(job) }
 
-        replica || false
+        replica || completed_job_before_replica? || false
+      end
+    end
+
+    def completed_job_before_replica?
+      case current_job_status
+      when "successful"
+        @job_completed_before_replica_exit_status = ExitCode::SUCCESS
+        true
+      when nil, "active", "pending"
+        false
+      else
+        @job_completed_before_replica_exit_status = ExitCode::ERROR_DEFAULT
+        true
       end
     end
 
@@ -505,9 +521,7 @@ module Command
 
     def resolve_job_status # rubocop:disable Metrics/MethodLength
       loop do
-        result = cp.fetch_cron_workload(runner_workload, location: location)
-        job_details = result&.dig("items")&.find { |item| item["id"] == job }
-        status = job_details&.dig("status")
+        status = current_job_status
 
         Shell.debug("JOB STATUS", status)
 
@@ -522,6 +536,12 @@ module Command
       end
     end
 
+    def current_job_status
+      result = cp.fetch_cron_workload(runner_workload, location: location)
+      job_details = result&.dig("items")&.find { |item| item["id"] == job }
+      job_details&.dig("status")
+    end
+
     ###########################################
     ### temporary extaction from run:detached
     ###########################################

data/lib/core/config.rb

@@ -166,6 +166,28 @@ class Config # rubocop:disable Metrics/ClassLength
     current&.dig(:use_digest_image_ref) == true
   end
 
+  def deploy_order
+    return nil unless current&.key?(:deploy_order)
+
+    @deploy_order ||= normalize_deploy_order(
+      current.fetch(:deploy_order),
+      app_workloads_for_deploy_order!(current, app),
+      app
+    )
+  end
+
+  def validate_deploy_orders!
+    apps.each do |app_name, app_options|
+      next unless app_options.key?(:deploy_order)
+
+      normalize_deploy_order(
+        app_options.fetch(:deploy_order),
+        app_workloads_for_deploy_order!(app_options, app_name),
+        app_name
+      )
+    end
+  end
+
   private
 
   def ensure_current_config!
@@ -252,6 +274,78 @@ class Config # rubocop:disable Metrics/ClassLength
     end
   end
 
+  def app_workloads_for_deploy_order!(app_options, app_name)
+    app_workloads = app_options[:app_workloads]
+    return app_workloads if app_workloads.is_a?(Array)
+
+    raise "deploy_order for app '#{app_name}' requires app_workloads to be an array."
+  end
+
+  def normalize_deploy_order(raw_deploy_order, app_workloads, app_name)
+    ensure_deploy_order_array!(raw_deploy_order, app_name)
+    context = {
+      app_workload_names: app_workloads.map(&:to_s),
+      seen_workloads: {},
+      app_name: app_name
+    }
+
+    raw_deploy_order.map.with_index do |group, index|
+      normalize_deploy_order_group(group, index, context)
+    end
+  end
+
+  def ensure_deploy_order_array!(raw_deploy_order, app_name)
+    raise "deploy_order for app '#{app_name}' must be an array of workload groups." unless raw_deploy_order.is_a?(Array)
+    return unless raw_deploy_order.empty?
+
+    raise "deploy_order for app '#{app_name}' must include at least one workload group."
+  end
+
+  def normalize_deploy_order_group(group, index, context)
+    group_number = index + 1
+    ensure_deploy_order_group_array!(group, group_number, context.fetch(:app_name))
+
+    group.map.with_index do |workload, workload_index|
+      normalize_deploy_order_workload(workload, group_number, workload_index, context)
+    end
+  end
+
+  def ensure_deploy_order_group_array!(group, group_number, app_name)
+    unless group.is_a?(Array)
+      raise "deploy_order group ##{group_number} for app '#{app_name}' must be an array of workload names."
+    end
+    return unless group.empty?
+
+    raise "deploy_order group ##{group_number} for app '#{app_name}' must include at least one workload."
+  end
+
+  def normalize_deploy_order_workload(workload, group_number, workload_index, context)
+    app_name = context.fetch(:app_name)
+    unless workload.is_a?(String) && !workload.strip.empty?
+      raise "deploy_order group ##{group_number} entry ##{workload_index + 1} " \
+            "for app '#{app_name}' must be a workload name."
+    end
+
+    workload_name = workload.strip
+    ensure_deploy_order_workload_configured!(workload_name, context.fetch(:app_workload_names), app_name)
+    ensure_deploy_order_workload_unique!(workload_name, context.fetch(:seen_workloads), app_name)
+    workload_name
+  end
+
+  def ensure_deploy_order_workload_configured!(workload_name, app_workload_names, app_name)
+    return if app_workload_names.include?(workload_name)
+
+    raise "deploy_order workload '#{workload_name}' must be listed in app_workloads for app '#{app_name}'."
+  end
+
+  def ensure_deploy_order_workload_unique!(workload_name, seen_workloads, app_name)
+    if seen_workloads[workload_name]
+      raise "deploy_order workload '#{workload_name}' must appear only once for app '#{app_name}'."
+    end
+
+    seen_workloads[workload_name] = true
+  end
+
   def ensure_app!
     return if app
 

data/lib/core/doctor_service.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class DoctorService
+class DoctorService # rubocop:disable Metrics/ClassLength
   class ValidationError < StandardError; end
 
   extend Forwardable
@@ -36,12 +36,12 @@ class DoctorService
 
   def validate_config
     check_for_app_names_contained_in_others
+    check_deploy_orders
   end
 
   def validate_templates
     @template_parser = TemplateParser.new(@command)
-    filenames = Dir.glob("#{@template_parser.template_dir}/*.yml")
-    templates = @template_parser.parse(filenames)
+    templates = @template_parser.parse(template_filenames)
 
     check_for_duplicate_templates(templates)
     warn_deprecated_template_variables
@@ -60,6 +60,12 @@ class DoctorService
     raise ValidationError, "#{Shell.color("ERROR: #{message}", :red)}\n#{list}"
   end
 
+  def check_deploy_orders
+    config.validate_deploy_orders!
+  rescue RuntimeError => e
+    raise ValidationError, Shell.color("ERROR: #{e.message}", :red)
+  end
+
   def find_app_names_contained_in_others # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
     app_names = config.apps.keys.map(&:to_s).sort
     app_prefixes = config.apps
@@ -88,6 +94,41 @@ class DoctorService
     raise ValidationError, "#{Shell.color("ERROR: #{message}", :red)}\n#{list}"
   end
 
+  def template_filenames
+    return existing_arg_template_filenames if config.args.any?
+
+    message = "ERROR: Can't find current config, please specify an app."
+    raise ValidationError, Shell.color(message, :red) if config.current.nil?
+
+    template_names = config.current[:setup_app_templates]
+    # Fall back to every template in the directory when setup_app_templates is unconfigured.
+    return Dir.glob("#{@template_parser.template_dir}/*.yml") if template_names.nil? || template_names.empty?
+
+    # When setup_app_templates is configured, validate only that selected subset,
+    # including the deprecation scan.
+    resolve_template_filenames(template_names)
+  end
+
+  def existing_arg_template_filenames = resolve_template_filenames(config.args)
+
+  def resolve_template_filenames(template_names)
+    unique_template_names = template_names.uniq
+    filenames = unique_template_names.map { |name| @template_parser.template_filename(name) }
+    ensure_templates_exist!(unique_template_names, filenames)
+    filenames
+  end
+
+  def ensure_templates_exist!(template_names, filenames)
+    missing_templates = template_names.zip(filenames).reject { |_, filename| File.exist?(filename) }
+    return if missing_templates.empty?
+
+    missing_templates_str = missing_templates.map do |name, filename|
+      "  - #{name} (#{filename})"
+    end.join("\n")
+    message = "#{Shell.color('Missing templates:', :red)}\n#{missing_templates_str}"
+    raise ValidationError, message
+  end
+
   def warn_deprecated_template_variables
     deprecated_variables = @template_parser.deprecated_variables
     return if deprecated_variables.empty?

data/lib/core/maintenance_mode.rb

@@ -1,8 +1,19 @@
 # frozen_string_literal: true
 
-class MaintenanceMode
+class MaintenanceMode # rubocop:disable Metrics/ClassLength
   extend Forwardable
 
+  DOMAIN_WORKLOAD_UPDATE_MAX_POLL_ATTEMPTS = 30
+  DOMAIN_WORKLOAD_UPDATE_RETRY_WAIT_SECONDS = 1
+  DOMAIN_WORKLOAD_UPDATE_STEP_OPTIONS = {
+    retry_on_failure: true,
+    # `with_retry` loops while `retry_count <= max_retry_count` starting from 0, so
+    # total attempts == max_retry_count + 1. Subtract 1 so the bounded poll runs
+    # exactly DOMAIN_WORKLOAD_UPDATE_MAX_POLL_ATTEMPTS times.
+    max_retry_count: DOMAIN_WORKLOAD_UPDATE_MAX_POLL_ATTEMPTS - 1,
+    wait: DOMAIN_WORKLOAD_UPDATE_RETRY_WAIT_SECONDS
+  }.freeze
+
   def_delegators :@command, :config, :progress, :cp, :step, :run_cpflow_command
 
   def initialize(command)
@@ -22,6 +33,7 @@ class MaintenanceMode
   def enable!
     if enabled?
       progress.puts("Maintenance mode is already enabled for app '#{config.app}'.")
+      ensure_app_workloads_stopped
     else
       enable_maintenance_mode
     end
@@ -30,6 +42,7 @@ class MaintenanceMode
   def disable!
     if disabled?
       progress.puts("Maintenance mode is already disabled for app '#{config.app}'.")
+      ensure_maintenance_workload_stopped
     else
       disable_maintenance_mode
     end
@@ -69,6 +82,28 @@ class MaintenanceMode
     cp.fetch_workload!(maintenance_workload)
   end
 
+  # A run that already switched the route but hit the poll timeout aborts before
+  # its final workload-stop step runs. The next `enable!`/`disable!` short-circuits
+  # on the route check, so do the matching stop here — once the route is on the
+  # target, this brings the workloads into the state that route implies. `ps:stop`
+  # is idempotent, so each is a no-op once the target workload is already stopped.
+  #
+  # The stop target differs by direction. `ps:stop -a` covers only
+  # `app_workloads` + `additional_workloads`, never the maintenance workload:
+  #   - enable!: the route now points at the maintenance workload, so the *app*
+  #     workloads are the ones left running and `ps:stop -a` is correct.
+  #   - disable!: the route now points at the app workloads (and a short-circuit
+  #     `disable!` can run on an app whose app workloads are serving live traffic),
+  #     so stopping all workloads would cause an outage. The workload a timed-out
+  #     `disable!` leaves running is the maintenance workload, so stop only that.
+  def ensure_app_workloads_stopped
+    start_or_stop_all_workloads(:stop)
+  end
+
+  def ensure_maintenance_workload_stopped
+    start_or_stop_maintenance_workload(:stop)
+  end
+
   def start_or_stop_all_workloads(action)
     run_cpflow_command("ps:#{action}", "-a", config.app, "--wait")
 
@@ -82,16 +117,68 @@ class MaintenanceMode
   end
 
   def switch_domain_workload(to:)
-    step("Switching workload for domain '#{domain_data['name']}' to '#{to}'") do
-      cp.set_domain_workload(domain_data, to)
-
-      # Give it a bit of time for the domain to update
-      Kernel.sleep(30)
+    domain_name = domain_data["name"]
+
+    # Unlike the polling step below, the switch request is intentionally not
+    # retried: if it fails, nothing has changed yet, so aborting and letting the
+    # user re-run is the safe outcome. (Retrying would not help here anyway —
+    # `with_retry` retries on a falsy return, and `set_domain_workload` raises
+    # rather than returning false.)
+    step("Requesting workload switch for domain '#{domain_name}' to '#{to}'") do
+      # `set_domain_workload` mutates the route in place, so send a deep copy
+      # (round-tripped through JSON, since the domain is plain parsed-API data
+      # with string keys and JSON-native values) to keep the cached
+      # `@domain_data` reflecting the real server route. The poll re-fetches and
+      # matches on that fresh data, but if every poll times out without a routable
+      # fetch, `@domain_data` is what a re-run's `enabled?`/`disabled?` check reads
+      # — mutating it here would make that check report the requested route, not
+      # the actual one.
+      domain_data_for_update = JSON.parse(JSON.generate(domain_data))
+      cp.set_domain_workload(domain_data_for_update, to)
     end
 
+    wait_for_domain_workload_switch(domain_name, to)
+
     progress.puts
   end
 
+  # If the route never switches within the bounded poll window, this step aborts
+  # (abort_on_error) before any workloads are stopped, so traffic stays on the
+  # current workload. The label tells the user how to recover, since an exhausted
+  # poll has no error message of its own to print.
+  def wait_for_domain_workload_switch(domain_name, to)
+    @last_poll_error = nil # reset the poll-error dedup state for this poll window
+    step("Waiting for domain '#{domain_name}' workload to switch to '#{to}' " \
+         "(re-run this command if it times out)", **DOMAIN_WORKLOAD_UPDATE_STEP_OPTIONS) do
+      domain_workload_update_confirmed?(domain_name, to)
+    end
+  end
+
+  # Refetches the domain, refreshes the cached `@domain_data` when the fetch
+  # returns a routable domain, and reports whether the route now points at
+  # `workload`. Any error — a 5xx mid-propagation, a transient 403
+  # (`ForbiddenError < StandardError`, not a `RuntimeError`), or a network blip —
+  # is treated as "not switched yet" so the poll keeps retrying. The broad rescue
+  # logs the error to the step's stderr, so a latent bug (e.g. `NoMethodError`)
+  # surfaces in the "failed!" output on timeout instead of being swallowed.
+  def domain_workload_update_confirmed?(domain_name, workload)
+    refreshed_domain_data = cp.fetch_domain(domain_name)
+    @domain_data = refreshed_domain_data if refreshed_domain_data
+    refreshed_domain_data && cp.domain_workload_matches?(refreshed_domain_data, workload)
+  rescue StandardError => e
+    # A persistent failure (bad domain name, network outage, a latent bug) repeats
+    # the same error on every poll attempt, so only log when the message changes —
+    # otherwise the timeout output would carry up to MAX_POLL_ATTEMPTS identical
+    # lines. Guard on `tmp_stderr` so this stays safe if ever called outside a
+    # `step` block, where no tmp stderr is set up.
+    message = "#{e.class}: #{e.message} (#{e.backtrace&.first})\n"
+    if message != @last_poll_error && Shell.tmp_stderr
+      Shell.write_to_tmp_stderr(message)
+      @last_poll_error = message
+    end
+    false
+  end
+
   def domain_data
     @domain_data ||=
       if config.domain

data/lib/core/template_parser.rb

@@ -37,38 +37,72 @@ class TemplateParser
   private
 
   def replace_variables(yaml_file) # rubocop:disable Metrics/MethodLength
+    original_yaml_file = yaml_file
+    yaml_file = replace_legacy_variables(yaml_file)
+
     yaml_file = yaml_file
                 .gsub("{{APP_ORG}}", config.org)
                 .gsub("{{APP_NAME}}", config.app)
                 .gsub("{{APP_LOCATION}}", config.location)
                 .gsub("{{APP_LOCATION_LINK}}", config.location_link)
-                .gsub("{{APP_IMAGE}}", cp.latest_image)
-                .gsub("{{APP_IMAGE_LINK}}", config.image_link(cp.latest_image))
                 .gsub("{{APP_IDENTITY}}", config.identity)
                 .gsub("{{APP_IDENTITY_LINK}}", config.identity_link)
                 .gsub("{{APP_SECRETS}}", config.secrets)
                 .gsub("{{APP_SECRETS_POLICY}}", config.secrets_policy)
+    yaml_file = replace_image_variables(yaml_file)
 
     config.shared_secret_placeholders.each do |placeholder, secret_name|
       yaml_file = yaml_file.gsub(placeholder, secret_name)
     end
 
-    find_deprecated_variables(yaml_file)
+    find_deprecated_variables(original_yaml_file)
+    yaml_file
+  end
+
+  def replace_image_variables(yaml_file)
+    has_image = yaml_file.include?("{{APP_IMAGE}}")
+    has_image_link = yaml_file.include?("{{APP_IMAGE_LINK}}")
+    return yaml_file unless has_image || has_image_link
 
-    # Kept for backwards compatibility
+    yaml_file = yaml_file.gsub("{{APP_IMAGE}}", latest_image) if has_image
+    yaml_file = yaml_file.gsub("{{APP_IMAGE_LINK}}", config.image_link(latest_image)) if has_image_link
     yaml_file
-      .gsub("APP_ORG", config.org)
-      .gsub("APP_GVC", config.app)
-      .gsub("APP_LOCATION", config.location)
-      .gsub("APP_IMAGE", cp.latest_image)
+  end
+
+  # Kept for backwards compatibility.
+  def replace_legacy_variables(yaml_file)
+    yaml_file
+      .gsub(deprecated_variable_pattern("APP_ORG"), config.org)
+      .gsub(deprecated_variable_pattern("APP_GVC"), config.app)
+      .gsub(deprecated_variable_pattern("APP_LOCATION"), config.location)
+      .then { |updated_yaml| replace_legacy_image_variable(updated_yaml) }
+  end
+
+  def replace_legacy_image_variable(yaml_file)
+    return yaml_file unless deprecated_variable_used?(yaml_file, "APP_IMAGE")
+
+    yaml_file.gsub(deprecated_variable_pattern("APP_IMAGE"), latest_image)
+  end
+
+  def latest_image
+    # Share one image value across modern and legacy image replacements in this parser instance.
+    @latest_image ||= cp.latest_image
   end
 
   def find_deprecated_variables(yaml_file)
     new_variables.each do |old_key, new_key|
-      @deprecated_variables[old_key] = new_key if yaml_file.include?(old_key)
+      @deprecated_variables[old_key] = new_key if deprecated_variable_used?(yaml_file, old_key)
     end
   end
 
+  def deprecated_variable_used?(yaml_file, old_key)
+    yaml_file.match?(deprecated_variable_pattern(old_key))
+  end
+
+  def deprecated_variable_pattern(old_key)
+    /(?<!\{\{)\b#{Regexp.escape(old_key)}\b(?!\}\})/
+  end
+
   def new_variables
     {
       "APP_ORG" => "{{APP_ORG}}",

data/lib/cpflow/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Cpflow
-  VERSION = "5.1.0"
+  VERSION = "5.2.0"
   MIN_CPLN_VERSION = "3.1.0"
 end

data/lib/generator_templates/controlplane.yml

@@ -48,10 +48,9 @@ apps:
     #   - name: database
     #     secret_name: __APP_PREFIX__-review-database-secrets
     #     policy_name: __APP_PREFIX__-review-database-secrets-policy
-    # Uncomment to automatically initialize and tear down review-app databases:
+    # Uncomment to automatically initialize review-app databases:
     # hooks:
     #   post_creation: bundle exec rails db:prepare
-    #   pre_deletion: bundle exec rails db:drop
 
   __APP_PREFIX__-production:
     <<: *production