cpl 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da0cd8b4b3f57a141b2a148a35555069f4ff4135803e4ae95932cd3887e3a567
-  data.tar.gz: dab258fecce6a5948374057418959d736915ab69f84593e1b189c148f62f00be
+  metadata.gz: 9d187c354ac6a9a75c0aea498f8fbc060f741809d075439ee22663fdf06f265d
+  data.tar.gz: ffde2f0f3be4663ba85baadf599c6a12882c2ba11734f9220d26366bacc5368d
 SHA512:
-  metadata.gz: 31c5cfe13e647abf6f34f6b021c808c220db07a48cd223d0d277ad7814ab0942961a7b75c63d89c3c109e7ca670d478285e5289fdb9fe64ccd828917b7fccf22
-  data.tar.gz: 926431c8d7fb4c5f8ba7930a3a156d70718dcce6eb1c717e9859f5a8546900266e4267cee7c755ca4c99612fb1b574a7cbfdd6ca23a2fd5483c1eb3c743a83db
+  metadata.gz: 70941d48b8ccc5bb3fb46b6c96c91fd0d3c2f13f2a702822ee6541231d90957df5a3b3c9d60d2091afad9f6e76be8870953f69085a97315c2a865d534d0c1ce7
+  data.tar.gz: 3a109996c812ec2b2e9dc76c189bd5d3518835e5b221ff8f12416982f3542f1753dcba441dbb3ec32224e807d0c83db54fe78e21cad43da0d829b8d65593a6d5

data/CHANGELOG.md

@@ -1,9 +1,38 @@
 # Changelog
 
-## 0.1.1 - 2023-03-09
+All notable changes to this project's source code will be documented in this file. Items under `Unreleased` are upcoming features that will be out in the next version.
 
-- Fixed issue with default gems for older Ruby versions (#14)
+## Contributors
 
-## 0.1.0 - 2023-02-19
+Please follow the recommendations outlined at [keepachangelog.com](https://keepachangelog.com). Please use the existing headings and styling as a guide, and add a link for the version diff at the bottom of the file. Also, please update the `Unreleased` link to compare it to the latest release version.
+
+## Versions
+
+## [Unreleased]
+
+Changes since the last non-beta release.
+
+_Please add entries here for your pull requests that are not yet released._
+
+### Added
+
+- Added steps to migrate to docs. [PR 57](https://github.com/shakacode/heroku-to-control-plane/pull/57) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Added `ps:wait` command. [PR 58](https://github.com/shakacode/heroku-to-control-plane/pull/58) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
+## [1.0.1] - 2023-06-28
+
+### Fixed
+
+- Fixed `cleanup-stale-apps` command when app does not have image. [PR 55](https://github.com/shakacode/heroku-to-control-plane/pull/55) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
+### Changed
+
+- Improved docs. [PR 50](https://github.com/shakacode/heroku-to-control-plane/pull/50) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
+## [1.0.0] - 2023-05-29
 
 - Initial release
+
+[Unreleased]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/shakacode/heroku-to-control-plane/releases/tag/v1.0.0

data/CONTRIBUTING.md

@@ -1,13 +1,15 @@
 # Contributing
 
 ## Installation
-Rather than installing `cpl` as a Ruby gem, install this repo locally and alias `cpl` command globally for easier access, e.g.:
+
+Rather than installing `cpl` as a Ruby gem, install this repo locally and alias the `cpl` command globally for easier
+access, e.g.:
 
 ```sh
 git clone https://github.com/shakacode/heroku-to-control-plane
 
 # Create an alias in some local shell startup script, e.g., `.profile`, `.bashrc`, etc.
-alias cpl="~/projects/heroku-to-control-plane/cpl"
+alias cpl="~/projects/heroku-to-control-plane/bin/cpl"
 ```
 
 Or set the path of the Ruby gem in your Gemfile.
@@ -16,13 +18,30 @@ Or set the path of the Ruby gem in your Gemfile.
 gem 'cpl', path: '~/projects/heroku-to-control-plane'
 ```
 
-## Linting
-Be sure to run `rubocop -a` before committing code.
+## Linting/Testing
+
+Before committing or pushing code, be sure to:
+
+- Run `bundle exec rake update_command_docs` to sync any doc changes made in the source code to the docs
+- Run `bundle exec rubocop -a` to fix any linting errors
+- Run `bundle exec rspec` to run the test suite
+
+You can also install [overcommit](https://github.com/sds/overcommit) and let it automatically check for you:
+
+```sh
+gem install overcommit
+
+overcommit --install
+```
 
 ## Debugging
 
-1. Install gem: `gem install debug`
-2. Require: Add a `require "debug"` statement to the file you want to debug.
-3. Add breakpoint: Add a `debugger` statement to the line you want to debug.
-4. Modify the `lib/command/test.rb` file to triggger the code that you want to run.
-5. Run the test in your test app with a `.controlplane` directory. `cpl test -a my-app-name`
+1. Add a breakpoint (`debugger`) to any line of code you want to debug.
+2. Modify the `lib/command/test.rb` file to trigger the code you want to test. To simulate a command, you can use
+   `Cpl::Cli.start` (e.g., `Cpl::Cli.start(["deploy-image", "-a", "my-app-name"])` would be the same as running
+   `cpl deploy-image -a my-app-name`).
+3. Run the `test` command in your test app with a `.controlplane` directory.
+
+```sh
+cpl test
+```

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpl (1.0.1)
+    cpl (1.0.3)
       debug (~> 1.7.1)
       dotenv (~> 2.8.1)
       psych (~> 5.1.0)
@@ -25,7 +25,7 @@ GEM
     hashdiff (1.0.1)
     iniparse (1.5.0)
     io-console (0.6.0)
-    irb (1.7.0)
+    irb (1.7.1)
       reline (>= 0.3.0)
     json (2.6.3)
     overcommit (0.60.0)

data/README.md

@@ -28,10 +28,8 @@ a **helper CLI** based on templates to save lots of day-to-day typing (and human
 1. [Key Features](#key-features)
 2. [Concept Mapping](#concept-mapping)
 3. [Installation](#installation)
-4. [Example CLI Flow for Application Build/Deployment](#example-cli-flow-for-application-builddeployment)
-   - [Initial Setup and Deployment](#initial-setup-and-deployment)
-   - [Promoting Code Upgrades](#promoting-code-upgrades)
-5. [Example Project Modifications for Control Plane](#example-project-modifications-for-control-plane)
+4. [Steps to Migrate](#steps-to-migrate)
+5. [Config](#config)
 6. [Environment](#environment)
 7. [Database](#database)
 8. [In-memory Databases](#in-memory-databases)
@@ -110,104 +108,13 @@ gem install cpl
 **Note:** Do not confuse the `cpl` CLI with the `cpln` CLI. The `cpl` CLI is the Heroku to Control Plane playbook CLI.
 The `cpln` CLI is the Control Plane CLI.
 
-## Example CLI Flow for Application Build/Deployment
+## Steps to Migrate
 
-**Notes:**
+Click [here](/docs/migrating.md) to see the steps to migrate.
 
-- `my-app` is an app name defined in the `.controlplane/controlplane.yml` file, such as `ror-tutorial` in
-  [this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
-- Other files in the `.controlplane/templates/` directory are used by the `cpl setup-app` and `cpl apply-template`
-  commands.
+## Config
 
-### Initial Setup and Deployment
-
-For each Git project that you want to deploy to Control Plane, copy project-specific configs to a `.controlplane/`
-directory at the top of your project. `cpl` will pick those up depending on which project folder tree it runs. Thus,
-this automates running several projects with different configs without explicitly switching configs.
-
-Before the initial setup, add the templates for the app to `.controlplane/controlplane.yml`, using the `setup` key, e.g.:
-
-```yaml
-my-app:
-  setup:
-    - gvc
-    - postgres
-    - redis
-    - memcached
-    - rails
-    - sidekiq
-```
-
-Note how the templates correspond to files in the `.controlplane/templates/` directory.
-
-Then create a `Dockerfile` for your deployment. See
-[this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/Dockerfile).
-
-```sh
-# Provision infrastructure (one-time-only for new apps) using templates.
-cpl setup-app -a my-app
-
-# Build and push image with auto-tagging, e.g., "my-app:1_456".
-cpl build-image -a my-app --commit 456
-
-# Prepare database.
-cpl run:detached -a my-app --image latest -- rails db:prepare
-
-# Deploy latest image.
-cpl deploy-image -a my-app
-
-# Open app in browser.
-cpl open -a my-app
-```
-
-### Promoting Code Upgrades
-
-```sh
-# Build and push new image with sequential tagging, e.g., "my-app:2".
-cpl build-image -a my-app
-
-# Or build and push new image with sequential tagging and commit SHA, e.g., "my-app:2_ABC".
-cpl build-image -a my-app --commit ABC
-
-# Run database migrations (or other release tasks) with latest image, while app is still running on previous image.
-# This is analogous to the release phase.
-cpl run:detached -a my-app --image latest -- rails db:migrate
-
-# Deploy latest image.
-cpl deploy-image -a my-app
-```
-
-## Example Project Modifications for Control Plane
-
-_See this for a complete example._
-
-To learn how to migrate an app, we recommend following along with
-[this example project](https://github.com/shakacode/react-webpack-rails-tutorial).
-
-1. Create the `.controlplane/` directory at the top of your project and copy files from the `templates/` directory of
-   this repository to something as follows:
-
-```sh
-app_main_folder/
-  .controlplane/
-    Dockerfile          # Your app's Dockerfile, with some Control Plane changes.
-    controlplane.yml
-    entrypoint.sh       # App-specific - edit as needed.
-    templates/
-      gvc.yml
-      memcached.yml
-      postgres.yml
-      rails.yml
-      redis.yml
-      sidekiq.yml
-```
-
-The example
-[`.controlplane/` directory](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)
-already contains these files.
-
-2. Edit your `controlplane.yml` file as needed. For example, see
-   [this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
+Here's a complete example of all supported config keys explained:
 
 ```yaml
 # Keys beginning with "cpln_" correspond to your settings in Control Plane.
@@ -221,6 +128,16 @@ aliases:
     # Example apps use only one location. Control Plane offers the ability to use multiple locations.
     default_location: aws-us-east-2
 
+    # Allows running the command `cpl setup-app`
+    # instead of `cpl apply-template gvc redis postgres memcached rails sidekiq`.
+    setup:
+      - gvc
+      - redis
+      - postgres
+      - memcached
+      - rails
+      - sidekiq
+
     # Configure the workload name used as a template for one-off scripts, like a Heroku one-off dyno.
     one_off_workload: rails
 
@@ -235,40 +152,58 @@ aliases:
       - postgres
       - memcached
 
-    # Configure the workload name used when maintenance mode is on (defaults to "maintenance")
+    # Configure the workload name used when maintenance mode is on (defaults to "maintenance").
     maintenance_workload: maintenance
 
+    # Fixes the remote terminal size to match the local terminal size
+    # when running the commands `cpl run` or `cpl run:detached`.
+    fix_terminal_size: true
+
+    # Apps with a deployed image created before this amount of days will be listed for deletion
+    # when running the command `cpl cleanup-stale-apps`.
+    stale_app_image_deployed_days: 5
+
+    # Images created before this amount of days will be listed for deletion
+    # when running the command `cpl cleanup-old-images`.
+    old_image_retention_days: 5
+
+    # Run workloads created before this amount of days will be listed for deletion
+    # when running the command `cpl run:cleanup`.
+    stale_run_workload_created_days: 2
+
 apps:
   my-app-staging:
     # Use the values from the common section above.
     <<: *common
+
   my-app-review:
     <<: *common
+
     # If `match_if_app_name_starts_with` is `true`, then use this config for app names starting with this name,
     # e.g., "my-app-review-pr123", "my-app-review-anything-goes", etc.
     match_if_app_name_starts_with: true
+
   my-app-production:
     <<: *common
+
     # Use a different organization for production.
     cpln_org: my-org-production
+
     # Allows running the command `cpl promote-app-from-upstream -a my-app-production`
     # to promote the staging app to production.
     upstream: my-app-staging
+
+    # Used by the command `cpl promote-app-from-upstream` to run a release script before deploying.
+    # This is relative to the `.controlplane/` directory.
+    release_script: release_script
+
   my-app-other:
     <<: *common
+
     # You can specify a different `Dockerfile` relative to the `.controlplane/` directory (defaults to "Dockerfile").
     dockerfile: ../some_other/Dockerfile
 ```
 
-3. We recommend that you try out the commands listed in
-   [the example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/readme.md).
-   These steps will guide you to the following:
-
-   1. Provision the GVC and workloads.
-   2. Build the Docker image.
-   3. Run Rails migrations, like in the Heroku release phase.
-   4. Promote the latest Docker image.
-
 ## Environment
 
 There are two main places where we can set up environment variables in Control Plane:

data/bin/cpl

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "cpl"
+require_relative "../lib/cpl"
 
 Cpl::Cli.start

data/cpl

@@ -1,15 +1,6 @@
-#!/bin/sh
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-SCRIPT_DIR=$(dirname $(realpath $0))
+require_relative "lib/cpl"
 
-# exports .env to vars
-#
-# Example .env:
-# CPLN_TOKEN=xxx
-#
-if [ -f "$SCRIPT_DIR/.env" ]; then
-  export $(grep -v '^#' $SCRIPT_DIR/.env | xargs -0)
-fi
-
-# exec $SCRIPT_DIR/old_commands/main.sh "$@"
-exec ruby $SCRIPT_DIR/lib/main.rb "$@"
+Cpl::Cli.start

data/docs/commands.md

@@ -285,6 +285,18 @@ cpl ps:stop -a $APP_NAME
 cpl ps:stop -a $APP_NAME -w $WORKLOAD_NAME
 ```
 
+### `ps:wait`
+
+- Waits for workloads in app to be ready after re-deployment
+
+```sh
+# Waits for all workloads in app.
+cpl ps:wait -a $APP_NAME
+
+# Waits for a specific workload in app.
+cpl ps:swait -a $APP_NAME -w $WORKLOAD_NAME
+```
+
 ### `run`
 
 - Runs one-off **_interactive_** replicas (analog of `heroku run`)
@@ -329,6 +341,7 @@ cpl run bash -a $APP_NAME --use-local-token
 - Deletes stale run workloads for an app
 - Workloads are considered stale based on how many days since created
 - `stale_run_workload_created_days` in the `.controlplane/controlplane.yml` file specifies the number of days after created that the workload is considered stale
+- Works for both interactive workloads (created with `cpl run`) and non-interactive workloads (created with `cpl run:detached`)
 - Will ask for explicit user confirmation of deletion
 
 ```sh
@@ -352,18 +365,16 @@ cpl run:detached 'LOG_LEVEL=warn rails db:migrate' -a $APP_NAME
 # COMMAND may also be passed at the end (in this case, no need to quote).
 cpl run:detached -a $APP_NAME -- rails db:migrate
 
-# Uses some other image.
-cpl run:detached rails db:migrate -a $APP_NAME --image /some/full/image/path
-
-# Uses latest app image (which may not be promoted yet).
-cpl run:detached rails db:migrate -a $APP_NAME --image latest
-
 # Uses a different image (which may not be promoted yet).
 cpl run:detached rails db:migrate -a $APP_NAME --image appimage:123 # Exact image name
 cpl run:detached rails db:migrate -a $APP_NAME --image latest       # Latest sequential image
 
 # Uses a different workload than `one_off_workload` from `.controlplane/controlplane.yml`.
 cpl run:detached rails db:migrate:status -a $APP_NAME -w other-workload
+
+# Overrides remote CPLN_TOKEN env variable with local token.
+# Useful when superuser rights are needed in remote container.
+cpl run:detached rails db:migrate:status -a $APP_NAME --use-local-token
 ```
 
 ### `setup-app`

data/docs/migrating.md

@@ -0,0 +1,262 @@
+# Steps to Migrate from Heroku to Control Plane
+
+We recommend following along with
+[this example project](https://github.com/shakacode/react-webpack-rails-tutorial).
+
+1. [Clone the Staging Environment](#clone-the-staging-environment)
+   - [Review Special Gems](#review-special-gems)
+   - [Create a Minimum Bootable Config](#create-a-minimum-bootable-config)
+2. [Create the Review App Process](#create-the-review-app-process)
+   - [Database for Review Apps](#database-for-review-apps)
+   - [Redis and Memcached for Review Apps](#redis-and-memcached-for-review-apps)
+3. [Deploy to Production](#deploy-to-production)
+
+## Clone the Staging Environment
+
+By cloning the staging environment on Heroku, you can speed up the initial provisioning of the app on Control Plane
+without compromising your current environment.
+
+Consider migrating just the web dyno first, and get other types of dynos working afterward. You can also move the
+add-ons to Control Plane later once the app works as expected.
+
+First, create a new Heroku app with all the add-ons, copying the data from the current staging app.
+
+Then, copy project-specific configs to a `.controlplane/` directory at the top of your project. `cpl` will pick those up
+depending on which project folder tree it runs. Thus, this automates running several projects with different configs
+without explicitly switching configs.
+
+Edit the `.controlplane/controlplane.yml` file as needed. Note that the `my-app-staging` name used in the examples below
+is defined in this file. See
+[this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
+
+Before the initial setup, add the templates for the app to the `.controlplane/controlplane.yml` file, using the `setup`
+key, e.g.:
+
+```yaml
+my-app-staging:
+  <<: *common
+  setup:
+    - gvc
+    - redis
+    - memcached
+    - rails
+    - sidekiq
+```
+
+Note how the templates correspond to files in the `.controlplane/templates/` directory. These files will be used by the
+`cpl setup-app` and `cpl apply-template` commands.
+
+Ensure that env vars point to the Heroku add-ons in the template for the app (`.controlplane/templates/gvc.yml`). See
+[this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/templates/gvc.yml).
+
+After that, create a Dockerfile in `.controlplane/Dockerfile` for your deployment. See
+[this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/Dockerfile).
+
+You should have a folder structure similar to the following:
+
+```sh
+app_main_folder/
+  .controlplane/
+    Dockerfile          # Your app's Dockerfile, with some Control Plane changes.
+    controlplane.yml
+    entrypoint.sh       # App-specific - edit as needed.
+    templates/
+      gvc.yml
+      memcached.yml
+      rails.yml
+      redis.yml
+      sidekiq.yml
+```
+
+The example
+[`.controlplane/` directory](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)
+already contains these files.
+
+Finally, check the app for any Heroku-specific code and update it, such as the `HEROKU_SLUG_COMMIT` env var and other
+env vars beginning with `HEROKU_`. You should add some logic to check for the Control Plane equivalents - it might be
+worth adding a `CONTROLPLANE` env var to act as a feature flag and help run different code for Heroku and Control Plane
+until the migration is complete.
+
+You might want to [review special gems](#review-special-gems) and
+[create a minimum bootable config](#create-a-minimum-bootable-config).
+
+At first, do the deployments from the command line. Then set up CI scripts to trigger the deployment upon merges to
+master/main.
+
+Use these commands for the initial setup and deployment:
+
+```sh
+# Provision infrastructure (one-time-only for new apps) using templates.
+cpl setup-app -a my-app-staging
+
+# Build and push image with auto-tagging, e.g., "my-app-staging:1_456".
+cpl build-image -a my-app-staging --commit 456
+
+# Prepare database.
+cpl run:detached -a my-app-staging --image latest -- rails db:prepare
+
+# Deploy latest image.
+cpl deploy-image -a my-app-staging
+
+# Open app in browser.
+cpl open -a my-app-staging
+```
+
+Then for promoting code upgrades:
+
+```sh
+# Build and push new image with sequential tagging, e.g., "my-app-staging:2".
+cpl build-image -a my-app-staging
+
+# Or build and push new image with sequential tagging and commit SHA, e.g., "my-app-staging:2_ABC".
+cpl build-image -a my-app-staging --commit ABC
+
+# Run database migrations (or other release tasks) with latest image, while app is still running on previous image.
+# This is analogous to the release phase.
+cpl run:detached -a my-app-staging --image latest -- rails db:migrate
+
+# Deploy latest image.
+cpl deploy-image -a my-app-staging
+```
+
+### Review Special Gems
+
+Make sure to review "special" gems which might be related to Heroku, e.g.:
+
+- `rails_autoscale_agent`. It's specific to Heroku, so it must be removed.
+- `puma_worker_killer`. In general, it's unnecessary on Control Plane, as Kubernetes containers will restart on their
+  own logic and may not restart at all if everything is ok.
+- `rack-timeout`. It could possibly be replaced with Control Plane's `timeout` option.
+
+You can use the `CONTROLPLANE` env var to separate the gems, e.g.:
+
+```ruby
+# Gemfile
+group :staging, :production do
+	gem "rack-timeout"
+
+  unless ENV.key?("CONTROLPLANE")
+	  gem "rails_autoscale_agent"
+    gem "puma_worker_killer"
+  end
+end
+```
+
+### Create a Minimum Bootable Config
+
+You can try to create a minimum bootable config to migrate parts of your app gradually. To do that, follow these steps:
+
+1. Rename the existing `application.yml` file to some other name (e.g., `application.old.yml`)
+2. Create a new **minimal** `application.yml` file, e.g.:
+
+```yaml
+SECRET_KEY_BASE: "123"
+# This should be enabled for `rails s`, not `rails assets:precompile`.
+# DATABASE_URL: postgres://localhost:5432/dbname
+# RAILS_SERVE_STATIC_FILES: "true"
+
+# You will add whatever env vars are required here later.
+```
+
+3. Try running `RAILS_ENV=production CONTROLPLANE=true rails assets:precompile`
+   (theoretically, this should work without any additional env vars)
+4. Fix whatever code needs to be fixed and add missing env vars
+   (the fewer env vars are needed, the cleaner the `Dockerfile` will be)
+5. Enable `DATABASE_URL` and `RAILS_SERVE_STATIC_FILES` env vars
+6. Try running `RAILS_ENV=production CONTROLPLANE=true rails s`
+7. Fix whatever code needs to be fixed and add required env vars to `application.yml`
+8. Try running your **production** entrypoint command, e.g.,
+   `RAILS_ENV=production RACK_ENV=production CONTROLPLANE=true puma -C config/puma.rb`
+9. Fix whatever code needs to be fixed and add required env vars to `application.yml`
+
+Now you should have a minimal bootable config.
+
+Then you can temporarily set the `LOG_LEVEL=debug` env var and disable unnecessary services to help with the process,
+e.g.:
+
+```yaml
+DISABLE_SPRING: "true"
+SCOUT_MONITOR: "false"
+RACK_TIMEOUT_SERVICE_TIMEOUT: "0"
+```
+
+## Create the Review App Process
+
+Add an entry for review apps to the `.controlplane/controlplane.yml` file. By adding a `match_if_app_name_starts_with`
+key with the value `true`, any app that starts with the entry's name will use this config. Doing this allows you to
+configure an entry for, e.g., `my-app-review`, and then create review apps starting with that name (e.g.,
+`my-app-review-1234`, `my-app-review-5678`, etc.). Here's an example:
+
+```yaml
+  my-app-review:
+    <<: *common
+    match_if_app_name_starts_with: true
+    setup:
+      - gvc
+      - redis
+      - memcached
+      - rails
+      - sidekiq
+```
+
+In your CI scripts, you can create a review app using some identifier (e.g., the number of the PR on GitHub).
+
+```yaml
+# On CircleCI, you can use `echo $CIRCLE_PULL_REQUEST | grep -Eo '[0-9]+$'` to extract the number of the PR.
+PR_NUM=$(... extract the number of the PR here ...)
+echo "export APP_NAME=my-app-review-$PR_NUM" >> $BASH_ENV
+
+# Only create the app if it doesn't exist yet, as we may have multiple triggers for the review app
+# (such as when a PR gets updated).
+if ! cpl exists -a ${APP_NAME}; then
+  cpl setup-app -a ${APP_NAME}
+  echo "export NEW_APP=true" >> $BASH_ENV
+fi
+
+# The `NEW_APP` env var that we exported above can be used to either reset or migrate the database before deploying.
+if [ -n "${NEW_APP}" ]; then
+  cpl run:detached 'LOG_LEVEL=warn rails db:reset' -a ${APP_NAME} --image latest
+else
+  cpl run:detached 'LOG_LEVEL=warn rails db:migrate_and_wait_replica' -a ${APP_NAME} --image latest
+fi
+```
+
+Then follow the same steps for the initial deployment or code upgrades.
+
+### Database for Review Apps
+
+For the review app resources, these should be handled as env vars in the template for the app
+(`.controlplane/templates/gvc.yml`), .e.g.:
+
+```yaml
+- name: DATABASE_URL
+  value: postgres://postgres:XXXXXXXX@cpln-XXXX-staging.XXXXXX.us-east-1.rds.amazonaws.com:5432/APP_GVC
+```
+
+Notice that `APP_GVC` is the app name, which is used as the database name on RDS, so that each review app gets its own
+database on the one RDS instance used for all review apps, which would be, e.g., `my-app-review-1234`.
+
+### Redis and Memcached for Review Apps
+
+So long as no persistence is needed for Redis and Memcached, we have templates for workloads that should be sufficient
+for review apps in the `templates/` directory of this repository. Using these templates results in considerable cost
+savings compared to paying for the resources on Heroku.
+
+```yaml
+- name: MEMCACHE_SERVERS
+  value: memcached.APP_GVC.cpln.local
+- name: REDIS_URL
+  value: redis://redis.APP_GVC.cpln.local:6379
+```
+
+## Deploy to Production
+
+Only try deploying to production once staging and review apps are working well.
+
+For simplicity, keep add-ons running on Heroku initially. You could move over the database to RDS first. However, it's a
+bit simpler to isolate any differences in cost and performance by first moving over your compute to Control Plane.
+
+Ensure that your Control Plane compute is in the AWS region `US-EAST-1`; otherwise, you'll have noticeable extra latency
+with your calls to resources. You might also have egress charges from Control Plane.
+
+Use the `cpl promote-app-from-upstream` command to promote the staging app to production.

data/examples/circleci.yml

@@ -59,8 +59,7 @@ build-review-app:
           cpln profile create default --token ${CPLN_TOKEN} --org ${CPLN_ORG} --gvc ${APP_NAME}
           cpln image docker-login
 
-          git clone https://github.com/shakacode/heroku-to-control-plane ~/heroku-to-control-plane
-          sudo ln -s ~/heroku-to-control-plane/cpl /usr/local/bin/cpl
+          gem install cpl
     - run:
         name: Provision review app if needed
         command: |

data/lib/command/cleanup_old_images.rb

@@ -31,6 +31,18 @@ module Command
 
     private
 
+    def app_prefix
+      config.should_app_start_with?(config.app) ? "#{config.app}-" : "#{config.app}:"
+    end
+
+    def remove_deployed_image(app, app_images)
+      return app_images unless cp.fetch_gvc(app)
+
+      # If app exists, remove latest image, because we don't want to delete the image that is currently deployed
+      latest_image_name = latest_image_from(app_images, app_name: app)
+      app_images.filter { |item| item["name"] != latest_image_name }
+    end
+
     def old_images # rubocop:disable Metrics/MethodLength
       @old_images ||=
         begin
@@ -39,21 +51,20 @@ module Command
           now = DateTime.now
           old_image_retention_days = config[:old_image_retention_days]
 
-          images = cp.image_query["items"].filter { |item| item["name"].start_with?("#{config.app}:")	}
-
-          # Remove latest image, because we don't want to delete the image that is currently deployed
-          latest_image_name = latest_image_from(images)
-          images = images.filter { |item| item["name"] != latest_image_name }
-
-          images.each do |image|
-            created_date = DateTime.parse(image["created"])
-            diff_in_days = (now - created_date).to_i
-            next unless diff_in_days >= old_image_retention_days
-
-            result_images.push({
-                                 name: image["name"],
-                                 date: created_date
-                               })
+          images = cp.image_query["items"].filter { |item| item["name"].start_with?(app_prefix)	}
+          images_by_app = images.group_by { |item| item["repository"] }
+          images_by_app.each do |app, app_images|
+            app_images = remove_deployed_image(app, app_images)
+            app_images.each do |image|
+              created_date = DateTime.parse(image["created"])
+              diff_in_days = (now - created_date).to_i
+              next unless diff_in_days >= old_image_retention_days
+
+              result_images.push({
+                                   name: image["name"],
+                                   date: created_date
+                                 })
+            end
           end
 
           result_images

data/lib/command/info.rb

@@ -112,10 +112,6 @@ module Command
       result.uniq.sort
     end
 
-    def should_app_start_with?(app)
-      config.apps[app.to_sym]&.dig(:match_if_app_name_starts_with)
-    end
-
     def any_app_starts_with?(app)
       @app_workloads.keys.find { |app_name| app_matches?(app_name, app, config.apps[app.to_sym]) }
     end
@@ -132,7 +128,7 @@ module Command
     end
 
     def add_to_missing_workloads(app, workload)
-      if should_app_start_with?(app)
+      if config.should_app_start_with?(app)
         @missing_apps_starting_with[app] ||= []
         @missing_apps_starting_with[app].push(workload)
       else
@@ -142,7 +138,7 @@ module Command
     end
 
     def print_app(app, org)
-      if should_app_start_with?(app)
+      if config.should_app_start_with?(app)
         check_any_app_starts_with(app)
       elsif cp.fetch_gvc(app, org).nil?
         @missing_apps_workloads[app] = ["gvc"]

data/lib/command/ps_start.rb

@@ -42,9 +42,7 @@ module Command
 
       @workloads.reverse_each do |workload|
         step("Waiting for workload '#{workload}' to be ready", retry_on_failure: true) do
-          cp.fetch_workload_deployments(workload)&.dig("items")&.any? do |item|
-            item.dig("status", "ready")
-          end
+          cp.workload_deployments_ready?(workload, expected_status: true)
         end
       end
     end

data/lib/command/ps_stop.rb

@@ -6,7 +6,7 @@ module Command
     OPTIONS = [
       app_option(required: true),
       workload_option,
-      wait_option("workload to be not ready")
+      wait_option("workload to not be ready")
     ].freeze
     DESCRIPTION = "Stops workloads in app"
     LONG_DESCRIPTION = <<~DESC
@@ -41,10 +41,8 @@ module Command
       progress.puts
 
       @workloads.each do |workload|
-        step("Waiting for workload '#{workload}' to be not ready", retry_on_failure: true) do
-          cp.fetch_workload_deployments(workload)&.dig("items")&.all? do |item|
-            !item.dig("status", "ready")
-          end
+        step("Waiting for workload '#{workload}' to not be ready", retry_on_failure: true) do
+          cp.workload_deployments_ready?(workload, expected_status: false)
         end
       end
     end

data/lib/command/ps_wait.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Command
+  class PsWait < Base
+    NAME = "ps:wait"
+    OPTIONS = [
+      app_option(required: true),
+      workload_option
+    ].freeze
+    DESCRIPTION = "Waits for workloads in app to be ready after re-deployment"
+    LONG_DESCRIPTION = <<~DESC
+      - Waits for workloads in app to be ready after re-deployment
+    DESC
+    EXAMPLES = <<~EX
+      ```sh
+      # Waits for all workloads in app.
+      cpl ps:wait -a $APP_NAME
+
+      # Waits for a specific workload in app.
+      cpl ps:swait -a $APP_NAME -w $WORKLOAD_NAME
+      ```
+    EX
+
+    def call
+      @workloads = [config.options[:workload]] if config.options[:workload]
+      @workloads ||= config[:app_workloads] + config[:additional_workloads]
+
+      @workloads.reverse_each do |workload|
+        step("Waiting for workload '#{workload}' to be ready", retry_on_failure: true) do
+          cp.workload_deployments_ready?(workload, expected_status: true)
+        end
+      end
+    end
+  end
+end

data/lib/command/run.rb

@@ -99,8 +99,8 @@ module Command
 
       # Override image if specified
       image = config.options[:image]
-      image = "/org/#{config.org}/image/#{latest_image}" if image == "latest"
-      container_spec["image"] = image if image
+      image = latest_image if image == "latest"
+      container_spec["image"] = "/org/#{config.org}/image/#{image}"
 
       # Set runner
       container_spec["env"] ||= []

data/lib/command/run_cleanup.rb

@@ -12,6 +12,7 @@ module Command
       - Deletes stale run workloads for an app
       - Workloads are considered stale based on how many days since created
       - `stale_run_workload_created_days` in the `.controlplane/controlplane.yml` file specifies the number of days after created that the workload is considered stale
+      - Works for both interactive workloads (created with `cpl run`) and non-interactive workloads (created with `cpl run:detached`)
       - Will ask for explicit user confirmation of deletion
     DESC
 
@@ -20,8 +21,14 @@ module Command
 
       progress.puts("Stale run workloads:")
       stale_run_workloads.each do |workload|
-        progress.puts("  #{workload[:name]} " \
-                      "(#{Shell.color("#{workload[:date]} - #{workload[:days]} days ago", :red)})")
+        output = ""
+        output += if config.should_app_start_with?(config.app)
+                    "  #{workload[:app]} - #{workload[:name]}"
+                  else
+                    "  #{workload[:name]}"
+                  end
+        output += " (#{Shell.color("#{workload[:date]} - #{workload[:days]} days ago", :red)})"
+        progress.puts(output)
       end
 
       return unless confirm_delete
@@ -62,11 +69,19 @@ module Command
           now = DateTime.now
           stale_run_workload_created_days = config[:stale_run_workload_created_days]
 
-          workloads = cp.query_workloads("-run-", partial_match: true)["items"]
+          interactive_workloads = cp.query_workloads(
+            "-run-", partial_gvc_match: config.should_app_start_with?(config.app), partial_workload_match: true
+          )["items"]
+          non_interactive_workloads = cp.query_workloads(
+            "-runner-", partial_gvc_match: config.should_app_start_with?(config.app), partial_workload_match: true
+          )["items"]
+          workloads = interactive_workloads + non_interactive_workloads
+
           workloads.each do |workload|
+            app_name = workload["links"].find { |link| link["rel"] == "gvc" }["href"].split("/").last
             workload_name = workload["name"]
 
-            original_workload_name, workload_number = workload_name.split("-run-")
+            original_workload_name, workload_number = workload_name.split(/-run-|-runner-/)
             next unless defined_workloads.include?(original_workload_name) && workload_number.match?(/^\d{4}$/)
 
             created_date = DateTime.parse(workload["created"])
@@ -74,6 +89,7 @@ module Command
             next unless diff_in_days >= stale_run_workload_created_days
 
             run_workloads.push({
+                                 app: app_name,
                                  name: workload_name,
                                  date: created_date,
                                  days: diff_in_days
@@ -91,8 +107,13 @@ module Command
     end
 
     def delete_workload(workload)
-      step("Deleting run workload '#{workload[:name]}'") do
-        cp.delete_workload(workload[:name])
+      message = if config.should_app_start_with?(config.app)
+                  "Deleting run workload '#{workload[:app]} - #{workload[:name]}'"
+                else
+                  "Deleting run workload '#{workload[:name]}'"
+                end
+      step(message) do
+        cp.delete_workload(workload[:name], workload[:app])
       end
     end
   end

data/lib/command/run_detached.rb

@@ -8,7 +8,8 @@ module Command
     OPTIONS = [
       app_option(required: true),
       image_option,
-      workload_option
+      workload_option,
+      use_local_token_option
     ].freeze
     DESCRIPTION = "Runs one-off **_non-interactive_** replicas (close analog of `heroku run:detached`)"
     LONG_DESCRIPTION = <<~DESC
@@ -28,18 +29,16 @@ module Command
       # COMMAND may also be passed at the end (in this case, no need to quote).
       cpl run:detached -a $APP_NAME -- rails db:migrate
 
-      # Uses some other image.
-      cpl run:detached rails db:migrate -a $APP_NAME --image /some/full/image/path
-
-      # Uses latest app image (which may not be promoted yet).
-      cpl run:detached rails db:migrate -a $APP_NAME --image latest
-
       # Uses a different image (which may not be promoted yet).
       cpl run:detached rails db:migrate -a $APP_NAME --image appimage:123 # Exact image name
       cpl run:detached rails db:migrate -a $APP_NAME --image latest       # Latest sequential image
 
       # Uses a different workload than `one_off_workload` from `.controlplane/controlplane.yml`.
       cpl run:detached rails db:migrate:status -a $APP_NAME -w other-workload
+
+      # Overrides remote CPLN_TOKEN env variable with local token.
+      # Useful when superuser rights are needed in remote container.
+      cpl run:detached rails db:migrate:status -a $APP_NAME --use-local-token
       ```
     EX
 
@@ -91,8 +90,8 @@ module Command
 
       # Override image if specified
       image = config.options[:image]
-      image = "/org/#{config.org}/image/#{latest_image}" if image == "latest"
-      container_spec["image"] = image if image
+      image = latest_image if image == "latest"
+      container_spec["image"] = "/org/#{config.org}/image/#{image}"
 
       # Set cron job props
       spec["type"] = "cron"
@@ -108,10 +107,16 @@ module Command
       cp.apply("kind" => "workload", "name" => one_off, "spec" => spec)
     end
 
-    def runner_script
+    def runner_script # rubocop:disable Metrics/MethodLength
       script = "echo '-- STARTED RUNNER SCRIPT --'\n"
       script += Scripts.helpers_cleanup
 
+      if config.options["use_local_token"]
+        script += <<~SHELL
+          CPLN_TOKEN=$CONTROLPLANE_TOKEN
+        SHELL
+      end
+
       script += <<~SHELL
         if ! eval "#{args_join(config.args)}"; then echo "----- CRASHED -----"; fi
 

data/lib/command/test.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# Be sure to have run: gem install debug
 require "debug"
 
 module Command
@@ -14,13 +13,10 @@ module Command
     HIDE = true
 
     def call
-      # Change code here to test.
+      # Modify this method to trigger the code you want to test.
       # You can use `debugger` to debug.
-      # debugger
-      # Or print values
-      # rubocop:disable Lint/Debugger
-      pp latest_image_next
-      # rubocop:enable Lint/Debugger
+      # You can use `Cpl::Cli.start` to simulate a command
+      # (e.g., `Cpl::Cli.start(["deploy-image", "-a", "my-app-name"])`).
     end
   end
 end

data/lib/core/config.rb

@@ -34,6 +34,10 @@ class Config
     "#{app_dir}/.controlplane"
   end
 
+  def should_app_start_with?(app)
+    apps[app.to_sym]&.dig(:match_if_app_name_starts_with) || false
+  end
+
   private
 
   def ensure_current_config!

data/lib/core/controlplane.rb

@@ -45,7 +45,11 @@ class Controlplane # rubocop:disable Metrics/ClassLength
   end
 
   def image_query(app_name = config.app, org_name = config.org)
-    cmd = "cpln image query --org #{org_name} -o yaml --max -1 --prop repository=#{app_name}"
+    # When `match_if_app_name_starts_with` is `true`, we query for images from any gvc containing the name,
+    # otherwise we query for images from a gvc with the exact name.
+    op = config.should_app_start_with?(app_name) ? "~" : "="
+
+    cmd = "cpln image query --org #{org_name} -o yaml --max -1 --prop repository#{op}#{app_name}"
     perform_yaml(cmd)
   end
 
@@ -86,7 +90,7 @@ class Controlplane # rubocop:disable Metrics/ClassLength
   def gvc_query(app_name = config.app)
     # When `match_if_app_name_starts_with` is `true`, we query for any gvc containing the name,
     # otherwise we query for a gvc with the exact name.
-    op = config.current[:match_if_app_name_starts_with] ? "~" : "="
+    op = config.should_app_start_with?(app_name) ? "~" : "="
 
     cmd = "cpln gvc query --org #{org} -o yaml --prop name#{op}#{app_name}"
     perform_yaml(cmd)
@@ -128,10 +132,11 @@ class Controlplane # rubocop:disable Metrics/ClassLength
     raise "Can't find workload '#{workload}', please create it with 'cpl apply-template #{workload} -a #{config.app}'."
   end
 
-  def query_workloads(workload, partial_match: false)
-    op = partial_match ? "~" : "="
+  def query_workloads(workload, partial_gvc_match: false, partial_workload_match: false)
+    gvc_op = partial_gvc_match ? "~" : "="
+    workload_op = partial_workload_match ? "~" : "="
 
-    api.query_workloads(org: org, gvc: gvc, workload: workload, op_type: op)
+    api.query_workloads(org: org, gvc: gvc, workload: workload, gvc_op_type: gvc_op, workload_op_type: workload_op)
   end
 
   def workload_get_replicas(workload, location:)
@@ -149,6 +154,26 @@ class Controlplane # rubocop:disable Metrics/ClassLength
     api.workload_deployments(workload: workload, gvc: gvc, org: org)
   end
 
+  def workload_deployment_version_ready?(version, next_version, expected_status:)
+    return false unless version["workload"] == next_version
+
+    version["containers"]&.all? do |_, container|
+      ready = container.dig("resources", "replicas") == container.dig("resources", "replicasReady")
+      expected_status == true ? ready : !ready
+    end
+  end
+
+  def workload_deployments_ready?(workload, expected_status:)
+    deployments = fetch_workload_deployments(workload)["items"]
+    deployments.all? do |deployment|
+      next_version = deployment.dig("status", "expectedDeploymentVersion")
+
+      deployment.dig("status", "versions")&.all? do |version|
+        workload_deployment_version_ready?(version, next_version, expected_status: expected_status)
+      end
+    end
+  end
+
   def workload_set_image_ref(workload, container:, image:)
     cmd = "cpln workload update #{workload} #{gvc_org}"
     cmd += " --set spec.containers.#{container}.image=/org/#{config.org}/image/#{image}"
@@ -184,8 +209,8 @@ class Controlplane # rubocop:disable Metrics/ClassLength
     perform!(cmd)
   end
 
-  def delete_workload(workload)
-    api.delete_workload(org: org, gvc: gvc, workload: workload)
+  def delete_workload(workload, a_gvc = gvc)
+    api.delete_workload(org: org, gvc: a_gvc, workload: workload)
   end
 
   def workload_connect(workload, location:, container: nil, shell: nil)

data/lib/core/controlplane_api.rb

@@ -33,7 +33,7 @@ class ControlplaneApi
     api_json_direct("/logs/org/#{org}/loki/api/v1/query_range?#{params}", method: :get, host: :logs)
   end
 
-  def query_workloads(org:, gvc:, workload:, op_type:) # rubocop:disable Metrics/MethodLength
+  def query_workloads(org:, gvc:, workload:, gvc_op_type:, workload_op_type:) # rubocop:disable Metrics/MethodLength
     body = {
       kind: "string",
       spec: {
@@ -41,12 +41,12 @@ class ControlplaneApi
         terms: [
           {
             rel: "gvc",
-            op: "=",
+            op: gvc_op_type,
             value: gvc
           },
           {
             property: "name",
-            op: op_type,
+            op: workload_op_type,
             value: workload
           }
         ]

data/lib/cpl/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Cpl
-  VERSION = "1.0.1"
+  VERSION = "1.0.3"
   MIN_CPLN_VERSION = "0.0.71"
 end

data/lib/cpl.rb

@@ -13,7 +13,7 @@ require "yaml"
 require_relative "command/base"
 
 modules = Dir["#{__dir__}/**/*.rb"].reject do |file|
-  file == __FILE__ || file.end_with?("main.rb") || file.end_with?("base.rb")
+  file == __FILE__ || file.end_with?("base.rb")
 end
 modules.sort.each { require(_1) }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cpl
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - Justin Gordon
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-28 00:00:00.000000000 Z
+date: 2023-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: debug
@@ -223,6 +223,7 @@ files:
 - docs/assets/memcached.png
 - docs/assets/sidekiq-pre-stop-hook.png
 - docs/commands.md
+- docs/migrating.md
 - docs/postgres.md
 - docs/redis.md
 - docs/tips.md
@@ -255,6 +256,7 @@ files:
 - lib/command/ps_restart.rb
 - lib/command/ps_start.rb
 - lib/command/ps_stop.rb
+- lib/command/ps_wait.rb
 - lib/command/run.rb
 - lib/command/run_cleanup.rb
 - lib/command/run_detached.rb
@@ -271,7 +273,6 @@ files:
 - lib/cpl.rb
 - lib/cpl/version.rb
 - lib/deprecated_commands.json
-- lib/main.rb
 - rakelib/create_release.rake
 - script/add_command
 - script/check_command_docs

data/lib/main.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "cpl"
-
-Cpl::Cli.start