cpflow 5.1.1 → 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/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/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/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.1"
+  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

data/lib/github_flow_templates/.github/cpflow-help.md

@@ -40,6 +40,16 @@ review-app secret dictionaries limited to disposable databases, review-only
 renderer credentials, and license values that are acceptable for review-app
 exposure.
 
+For public demos, starter staging apps, and long-lived review apps, keep the app
+workload `type: standard` with one warm replica, set its autoscaling metric to
+`disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and
+memory allocation at that fixed replica count. Shared Postgres and other
+stateful workloads are the usual exceptions and should stay manually sized;
+Capacity AI is for supported stateless app/service workloads. If true idle
+scale-to-zero is explicitly required, create a separate `serverless` workload
+before the first deploy or plan a delete/recreate migration because Control
+Plane will not change an existing `standard` workload to `serverless` in place.
+
 Optional overrides exist for forks, clones, and unusual apps:
 
 | Name | Notes |

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cpflow
 version: !ruby/object:Gem::Version
-  version: 5.1.1
+  version: 5.2.0
 platform: ruby
 authors:
 - Justin Gordon
@@ -75,7 +75,16 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".agents/agent-workflow.yml"
+- ".agents/bin/README.md"
+- ".agents/bin/docs"
+- ".agents/bin/lint"
+- ".agents/bin/setup"
+- ".agents/bin/test"
+- ".agents/bin/validate"
+- ".agents/trusted-github-actors.yml"
 - ".agents/workflows/address-review.md"
+- ".agents/workflows/ai-rollout-e2e-test.md"
 - ".claude/commands/address-review.md"
 - ".claude/commands/update-changelog.md"
 - ".github/actions/cpflow-build-docker-image/action.yml"
@@ -106,7 +115,9 @@ files:
 - ".overcommit.yml"
 - ".rubocop.yml"
 - ".simplecov_spawn.rb"
+- AGENTS.md
 - CHANGELOG.md
+- CLAUDE.md
 - COMM-LICENSE.txt
 - CONTRIBUTING.md
 - Gemfile
@@ -137,12 +148,20 @@ files:
 - docs/ci-automation.md
 - docs/commands.md
 - docs/dns.md
+- docs/grafana-opentelemetry.md
 - docs/migrating-heroku-to-control-plane.md
 - docs/postgres.md
 - docs/rds-private-networking.md
 - docs/redis.md
 - docs/releasing.md
 - docs/secrets-and-env-values.md
+- docs/sidebars.ts
+- docs/telemetry/application-instrumentation.md
+- docs/telemetry/collector.md
+- docs/telemetry/index.md
+- docs/telemetry/pipelines.md
+- docs/telemetry/review-apps.md
+- docs/telemetry/troubleshooting.md
 - docs/terraform/details.md
 - docs/terraform/example/.controlplane/controlplane.yml
 - docs/terraform/example/.controlplane/templates/app.yml
@@ -284,7 +303,7 @@ licenses:
 metadata:
   rubygems_mfa_required: 'true'
 post_install_message: |
-  cpflow 5.1.1 installed.
+  cpflow 5.2.0 installed.
 
   If this repository already uses generated cpflow GitHub Actions, update the
   checked-in wrappers so GitHub loads the matching control-plane-flow release tag: