cpl 1.4.0 → 2.0.0.rc.0

data/docs/commands.md

@@ -36,7 +36,7 @@ This `-a` option is used in most of the commands and will pick all other app con
 cpl apply-template redis -a $APP_NAME
 
 # Applies several templates (practically creating full app).
-cpl apply-template gvc postgres redis rails -a $APP_NAME
+cpl apply-template app postgres redis rails -a $APP_NAME
 ```
 
 ### `build-image`
@@ -105,17 +105,22 @@ cpl copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN --ima
 
 ### `delete`
 
-- Deletes the whole app (GVC with all workloads, all volumesets and all images)
+- Deletes the whole app (GVC with all workloads, all volumesets and all images) or a specific workload
 - Will ask for explicit user confirmation
 
 ```sh
+# Deletes the whole app (GVC with all workloads, all volumesets and all images).
 cpl delete -a $APP_NAME
+
+# Deletes a specific workload.
+cpl delete -a $APP_NAME -w $WORKLOAD_NAME
 ```
 
 ### `deploy-image`
 
 - Deploys the latest image to app workloads
 - Optionally runs a release script before deploying if specified through `release_script` in the `.controlplane/controlplane.yml` file and `--run-release-phase` is provided
+- The release script is run in the context of `cpl run` with the latest image
 - The deploy will fail if the release script exits with a non-zero code or doesn't exist
 
 ```sh
@@ -177,6 +182,7 @@ cpl latest-image -a $APP_NAME
 ### `logs`
 
 - Light wrapper to display tailed raw logs for app/workload syntax
+- Defaults to showing the last 200 entries from the past 1 hour before tailing
 
 ```sh
 # Displays logs for the default workload (`one_off_workload`).
@@ -184,6 +190,15 @@ cpl logs -a $APP_NAME
 
 # Displays logs for a specific workload.
 cpl logs -a $APP_NAME -w $WORKLOAD_NAME
+
+# Displays logs for a specific replica of a workload.
+cpl logs -a $APP_NAME -w $WORKLOAD_NAME -r $REPLICA_NAME
+
+# Uses a different limit on number of entries.
+cpl logs -a $APP_NAME --limit 100
+
+# Uses a different loopback window.
+cpl logs -a $APP_NAME --since 30min
 ```
 
 ### `maintenance`
@@ -311,6 +326,9 @@ cpl ps:stop -a $APP_NAME
 
 # Stops a specific workload in app.
 cpl ps:stop -a $APP_NAME -w $WORKLOAD_NAME
+
+# Stops a specific replica of a workload.
+cpl ps:stop -a $APP_NAME -w $WORKLOAD_NAME -r $REPLICA_NAME
 ```
 
 ### `ps:wait`
@@ -327,26 +345,43 @@ cpl ps:swait -a $APP_NAME -w $WORKLOAD_NAME
 
 ### `run`
 
-- Runs one-off **_interactive_** replicas (analog of `heroku run`)
-- Uses `Standard` workload type and `cpln exec` as the execution method, with CLI streaming
-- If `fix_terminal_size` is `true` in the `.controlplane/controlplane.yml` file, the remote terminal size will be fixed to match the local terminal size (may also be overriden through `--terminal-size`)
-
-> **IMPORTANT:** Useful for development where it's needed for interaction, and where network connection drops and
-> task crashing are tolerable. For production tasks, it's better to use `cpl run:detached`.
+- Runs one-off interactive or non-interactive replicas (analog of `heroku run`)
+- Uses `Cron` workload type and either:
+- - `cpln workload exec` for interactive mode, with CLI streaming
+- - log async fetching for non-interactive mode
+- The Dockerfile entrypoint is used as the command by default, which assumes `exec "${@}"` to be present,
+  and the args ["bash", "-c", cmd_to_run] are passed
+- The entrypoint can be overriden through `--entrypoint`, which must be a single command or a script path that exists in the container,
+  and the args ["bash", "-c", cmd_to_run] are passed,
+  unless the entrypoint is `bash`, in which case the args ["-c", cmd_to_run] are passed
+- Providing `--entrypoint none` sets the entrypoint to `bash` by default
+- If `fix_terminal_size` is `true` in the `.controlplane/controlplane.yml` file,
+  the remote terminal size will be fixed to match the local terminal size (may also be overriden through `--terminal-size`)
 
 ```sh
 # Opens shell (bash by default).
 cpl run -a $APP_NAME
 
-# Need to quote COMMAND if setting ENV value or passing args.
-cpl run -a $APP_NAME -- 'LOG_LEVEL=warn rails db:migrate'
+# Runs interactive command, keeps shell open, and stops job when exiting.
+cpl run -a $APP_NAME --interactive -- rails c
 
-# Runs command, displays output, and exits shell.
-cpl run -a $APP_NAME -- ls /
-cpl run -a $APP_NAME -- rails db:migrate:status
+# Some commands are automatically detected as interactive, so no need to pass `--interactive`.
+cpl run -a $APP_NAME -- bash
+      cpl run -a $APP_NAME -- rails console
+      cpl run -a $APP_NAME -- rails c
+      cpl run -a $APP_NAME -- rails dbconsole
+      cpl run -a $APP_NAME -- rails db
 
-# Runs command and keeps shell open.
-cpl run -a $APP_NAME -- rails c
+# Runs non-interactive command, outputs logs, exits with the exit code of the command and stops job.
+cpl run -a $APP_NAME -- rails db:migrate
+
+# Runs non-iteractive command, detaches, exits with 0, and prints commands to:
+# - see logs from the job
+# - stop the job
+cpl run -a $APP_NAME --detached -- rails db:migrate
+
+# The command needs to be quoted if setting an env variable or passing args.
+cpl run -a $APP_NAME -- 'SOME_ENV_VAR=some_value rails db:migrate'
 
 # Uses a different image (which may not be promoted yet).
 cpl run -a $APP_NAME --image appimage:123 -- rails db:migrate # Exact image name
@@ -358,47 +393,12 @@ cpl run -a $APP_NAME -w other-workload -- bash
 # Overrides remote CPLN_TOKEN env variable with local token.
 # Useful when superuser rights are needed in remote container.
 cpl run -a $APP_NAME --use-local-token -- bash
-```
-
-### `run:cleanup`
-
-- 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
-cpl run:cleanup -a $APP_NAME
-```
-
-### `run:detached`
-
-- Runs one-off **_non-interactive_** replicas (close analog of `heroku run:detached`)
-- Uses `Cron` workload type with log async fetching
-- Implemented with only async execution methods, more suitable for production tasks
-- Has alternative log fetch implementation with only JSON-polling and no WebSockets
-- Less responsive but more stable, useful for CI tasks
-- Deletes the workload whenever finished with success
-- Deletes the workload whenever finished with failure by default
-- Use `--no-clean-on-failure` to disable cleanup to help with debugging failed runs
-
-```sh
-cpl run:detached rails db:prepare -a $APP_NAME
 
-# Need to quote COMMAND if setting ENV value or passing args.
-cpl run:detached -a $APP_NAME -- 'LOG_LEVEL=warn rails db:migrate'
+# Replaces the existing Dockerfile entrypoint with `bash`.
+cpl run -a $APP_NAME --entrypoint none -- rails db:migrate
 
-# Uses a different image (which may not be promoted yet).
-cpl run:detached -a $APP_NAME --image appimage:123 -- rails db:migrate # Exact image name
-cpl run:detached -a $APP_NAME --image latest -- rails db:migrate       # Latest sequential image
-
-# Uses a different workload than `one_off_workload` from `.controlplane/controlplane.yml`.
-cpl run:detached -a $APP_NAME -w other-workload -- rails db:migrate:status
-
-# Overrides remote CPLN_TOKEN env variable with local token.
-# Useful when superuser rights are needed in remote container.
-cpl run:detached -a $APP_NAME --use-local-token -- rails db:migrate:status
+# Replaces the existing Dockerfile entrypoint.
+cpl run -a $APP_NAME --entrypoint /app/alternative-entrypoint.sh -- rails db:migrate
 ```
 
 ### `setup-app`

data/docs/dns.md

@@ -1,5 +1,11 @@
 # DNS Setup Example
 
+## Docs
+
+https://shakadocs.controlplane.com/guides/configure-domain#dns-records
+
+## Example
+
 About reactrails.com DNS, steps:
 1. create CNAME or ALIAS record pointing to rails-xxxx.cpln.app
 1. go to CPLN Domains -> create

data/docs/migrating.md

@@ -36,7 +36,7 @@ key, e.g.:
 my-app-staging:
   <<: *common
   setup_app_templates:
-    - gvc
+    - app
     - redis
     - memcached
     - rails
@@ -46,8 +46,8 @@ my-app-staging:
 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).
+Ensure that env vars point to the Heroku add-ons in the template for the app (`.controlplane/templates/app.yml`). See
+[this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/templates/app.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).
@@ -61,7 +61,7 @@ app_main_folder/
     controlplane.yml
     entrypoint.sh       # App-specific - edit as needed.
     templates/
-      gvc.yml
+      app.yml
       memcached.yml
       rails.yml
       redis.yml
@@ -93,7 +93,7 @@ cpl setup-app -a my-app-staging
 cpl build-image -a my-app-staging --commit 456
 
 # Prepare database.
-cpl run:detached -a my-app-staging --image latest -- rails db:prepare
+cpl run -a my-app-staging --image latest -- rails db:prepare
 
 # Deploy latest image.
 cpl deploy-image -a my-app-staging
@@ -113,7 +113,7 @@ 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
+cpl run -a my-app-staging --image latest -- rails db:migrate
 
 # Deploy latest image.
 cpl deploy-image -a my-app-staging
@@ -192,7 +192,7 @@ configure an entry for, e.g., `my-app-review`, and then create review apps start
     <<: *common
     match_if_app_name_starts_with: true
     setup_app_templates:
-      - gvc
+      - app
       - redis
       - memcached
       - rails
@@ -215,9 +215,9 @@ 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
+  cpl run -a ${APP_NAME} --image latest -- rails db:reset
 else
-  cpl run:detached 'LOG_LEVEL=warn rails db:migrate_and_wait_replica' -a ${APP_NAME} --image latest
+  cpl run -a ${APP_NAME} --image latest -- rails db:migrate
 fi
 ```
 
@@ -226,7 +226,7 @@ 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.:
+(`.controlplane/templates/app.yml`), .e.g.:
 
 ```yaml
 - name: DATABASE_URL

data/docs/tips.md

@@ -65,7 +65,7 @@ The actual remote IP of the workload container is in the 127.0.0.x network, so t
 `REMOTE_ADDR` env var.
 
 However, Control Plane additionally sets the `x-forwarded-for` and `x-envoy-external-address` headers (and others - see:
-https://docs.controlplane.com/concepts/security#headers). On Rails, the `ActionDispatch::RemoteIp` middleware should
+https://shakadocs.controlplane.com/concepts/security#headers). On Rails, the `ActionDispatch::RemoteIp` middleware should
 pick those up and automatically populate `request.remote_ip`.
 
 So `REMOTE_ADDR` should not be used directly, only `request.remote_ip`.
@@ -87,17 +87,19 @@ level, which applies to your GVCs mapped to that org.
 
 You can do this during the initial app setup, like this:
 
-1. Add the templates for `identity`, `secrets` and `secrets-policy` to `.controlplane/templates`
-2. Ensure that the templates are listed in `setup_app_templates` for the app in `.controlplane/controlplane.yml`
-3. Run `cpl setup-app -a $APP_NAME`
-4. The identity, secrets and secrets policy will be automatically created, along with the proper binding
-5. In the upper left "Manage Org" menu, click on "Secrets"
-6. Find the created secret (it will be in the `$APP_PREFIX-secrets` format) and add the secret env vars there
-7. Use `cpln://secret/...` in the app to access the secret env vars (e.g., `cpln://secret/$APP_PREFIX-secrets.SOME_VAR`)
+1. Add the templates for `app` and `secrets` to `.controlplane/templates`
+2. Ensure that the `app` template includes the `identity`
+3. Ensure that the `app` template is listed in `setup_app_templates` for the app in `.controlplane/controlplane.yml`
+4. Run `cpl apply-template secrets -a $APP_NAME` (one-time setup)
+5. Run `cpl setup-app -a $APP_NAME`
+6. The secrets, secrets policy and identity will be automatically created, along with the proper binding
+7. In the Control Plane console, upper left "Manage Org" menu, click on "Secrets"
+8. Find the created secret (it will be in the `$APP_PREFIX-secrets` format) and add the secret env vars there
+9. Use `cpln://secret/...` in the app to access the secret env vars (e.g., `cpln://secret/$APP_PREFIX-secrets.SOME_VAR`)
 
-You can also do it manually after. Here is how you do this:
+Here are the manual steps for reference. We recommend that you follow the steps above:
 
-1. In the upper left "Manage Org" menu, click on "Secrets"
+1. In the upper left of the Control Plane console, "Manage Org" menu, click on "Secrets"
 2. Create a secret with `Secret Type: Dictionary` (e.g., `my-secrets`) and add the secret env vars there
 3. In the upper left "Manage GVC" menu, click on "Identities"
 4. Create an identity (e.g., `my-identity`)

data/examples/circleci.yml

@@ -27,7 +27,7 @@ build-staging:
         command: cpl build-image -a ${APP_NAME}
     - run:
         name: Database tasks
-        command: cpl run:detached -a ${APP_NAME} --image latest -- rails db:migrate
+        command: cpl run -a ${APP_NAME} --image latest -- rails db:migrate
     - run:
         name: Deploy image
         command: cpl deploy-image -a ${APP_NAME}
@@ -75,9 +75,9 @@ build-review-app:
         name: Database tasks
         command: |
           if [ -n "${NEW_APP}" ]; then
-            cpl run:detached -a ${APP_NAME} --image latest -- LOG_LEVEL=warn rails db:reset
+            cpl run -a ${APP_NAME} --image latest -- rails db:reset
           else
-            cpl run:detached -a ${APP_NAME} --image latest -- LOG_LEVEL=warn rails db:migrate
+            cpl run -a ${APP_NAME} --image latest -- rails db:migrate
           fi
     - run:
         name: Deploy image

data/examples/controlplane.yml

@@ -17,40 +17,53 @@ aliases:
 
     # Control Plane offers the ability to use multiple locations.
     # default_location is used for commands that require a location
-    # including `ps`, `run`, `run:detached`, `apply-template`.
+    # including `ps`, `run`, `apply-template`.
     # This can be overridden with option --location=<location> and
     # CPLN_LOCATION environment variable.
     # TODO: Allow specification of 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`.
+    # instead of `cpl apply-template app redis postgres memcached rails sidekiq`.
     #
     # Note:
     # 1. These names correspond to files in the `./controlplane/templates` directory.
     # 2. Each file can contain many objects, such as in the case of templates that create a resource, like `postgres`.
     # 3. While the naming often corresponds to a workload or other object name, the naming is arbitrary. 
     #    Naming does not need to match anything other than the file name without the `.yml` extension.
+    #
+    # If you're going to use secrets, you need to apply the `secrets.yml` template separately (one-time setup):
+    # `cpl apply-template secrets -a my-app`
     setup_app_templates:
-      - gvc
-
-      # These templates are only required if using secrets.
-      - identity
-      - secrets
-      - secrets-policy
-
+      - app
       - redis
       - postgres
       - memcached
       - rails
       - sidekiq
 
+    # Only needed if using a custom secrets name.
+    # The default is '{APP_PREFIX}-secrets'. For example:
+    # - for an app 'my-app-staging' with `match_if_app_name_starts_with` set to `false`,
+    #   it would be 'my-app-staging-secrets'
+    # - for an app 'my-app-review-1234' with `match_if_app_name_starts_with` set to `true`,
+    #   it would be 'my-app-review-secrets'
+    secrets_name: my-secrets
+
+    # Only needed if using a custom secrets policy name.
+    # The default is '{APP_SECRETS}-policy'. For example:
+    # - for an app 'my-app-staging' with `match_if_app_name_starts_with` set to `false`,
+    #   it would be 'my-app-staging-secrets-policy'
+    # - for an app 'my-app-review-1234' with `match_if_app_name_starts_with` set to `true`,
+    #   it would be 'my-app-review-secrets-policy'
+    secrets_policy_name: my-secrets-policy
+
     # Configure the workload name used as a template for one-off scripts, like a Heroku one-off dyno.
     one_off_workload: rails
 
     # Workloads that are for the application itself and are using application Docker images.
     # These are updated with the new image when running the `deploy-image` command,
-    # and are also used by the `info`, `ps:`, and `run:cleanup` commands in order to get all of the defined workloads.
+    # and are also used by the `info` and `ps:` commands in order to get all of the defined workloads.
     # On the other hand, if you have a workload for Redis, that would NOT use the application Docker image
     # and not be listed here.
     app_workloads:
@@ -58,7 +71,7 @@ aliases:
       - sidekiq
 
     # Additional "service type" workloads, using non-application Docker images.
-    # These are only used by the `info`, `ps:` and `run:cleanup` commands in order to get all of the defined workloads.
+    # These are only used by the `info` and `ps:` commands in order to get all of the defined workloads.
     additional_workloads:
       - redis
       - postgres
@@ -68,7 +81,7 @@ aliases:
     maintenance_workload: maintenance
 
     # Fixes the remote terminal size to match the local terminal size
-    # when running the commands `cpl run` or `cpl run:detached`.
+    # when running `cpl run`.
     fix_terminal_size: true
 
     # Apps with a deployed image created before this amount of days will be listed for deletion
@@ -83,10 +96,6 @@ aliases:
     # when running the command `cpl cleanup-images` (`image_retention_max_qty` takes precedence).
     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.

data/lib/command/apply_template.rb

@@ -36,7 +36,7 @@ module Command
       cpl apply-template redis -a $APP_NAME
 
       # Applies several templates (practically creating full app).
-      cpl apply-template gvc postgres redis rails -a $APP_NAME
+      cpl apply-template app postgres redis rails -a $APP_NAME
       ```
     EX
 
@@ -50,7 +50,7 @@ module Command
       @asked_for_confirmation = false
 
       pending_templates = templates.select do |template|
-        if template == "gvc"
+        if template == "app"
           confirm_app(template)
         else
           confirm_workload(template)
@@ -64,15 +64,15 @@ module Command
       pending_templates.each do |template, filename|
         step("Applying template '#{template}'", abort_on_error: false) do
           items = apply_template(filename)
-          if items
-            items.each do |item|
-              report_success(item)
-            end
-          else
+          unless items
             report_failure(template)
+            next false
           end
 
-          $CHILD_STATUS.success?
+          items.each do |item|
+            report_success(item)
+          end
+          true
         end
       end
 
@@ -82,7 +82,7 @@ module Command
       print_failed_templates
       print_skipped_templates
 
-      exit(1) if @failed_templates.any?
+      exit(ExitCode::ERROR_DEFAULT) if @failed_templates.any?
     end
 
     private