cpl 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 711286ef49686f6c51df2a94c533b3df94f4d71d3fb6018b6ed61c210593dd47
-  data.tar.gz: '085357faac6b5b27e493049b34c27debab21fa19950af21548fe11889140b557'
+  metadata.gz: 0e67b960593def42983c0f333119e9edffe55434751769cb1ca25dd8333c1489
+  data.tar.gz: 3f201ff14fe51d451c5ab1fd8705e5e544d5e99c87b83e53c54464841a835a1d
 SHA512:
-  metadata.gz: ac229234f4919d8e1b3485095476ef0fddac04573d8dd03aba6a3737fd5e90b319538e04c51d98e5f33f244fe304c519d949a624a377bbc9ee9067754a0c71dd
-  data.tar.gz: 0ba5203d4f8539dde89a2eb5a52dc92c2098d11bb1914002cd57628081465d08e9842f47546da563bc18edda17fbf12101bfefca8fdcee4088825c0e56ee0fa0
+  metadata.gz: cb075c69a7fa151bdd800186594ef481999075c8377eabf7dcb886c0b30e246fcb5e3ccd6396ff0e8487ac5a8b50c24d01b3dade658cd7c2b4ebfa82cb6546c9
+  data.tar.gz: 2a7c0782f57fd543f79fdeb985221dc72bfdba830bbfda81dc966e432007ad314ccd28ba299d0084d446993201f05cabaec40a133c0a2edf7b16af70f3e38348

data/.github/workflows/check_cpln_links.yml

@@ -0,0 +1,19 @@
+name: Check Links
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  check_cpln_links:
+    runs-on: ubuntu-latest
+    name: Check Links
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Validate outgoing links to Control Plane
+        run: |
+          TERM=xterm-color ./script/check_cpln_links
+        shell: bash

data/.overcommit.yml

@@ -1,4 +1,7 @@
 PreCommit:
+  ValidateLinks:
+    enabled: true
+    command: ["bash", "./script/check_cpln_links"]
   CommandDocs:
     enabled: true
     command: ["bundle", "exec", "rake", "check_command_docs"]

data/CHANGELOG.md

@@ -14,6 +14,45 @@ Changes since the last non-beta release.
 
 _Please add entries here for your pull requests that are not yet released._
 
+## [1.4.0] - 2024-03-20
+
+### Added
+
+- Added new template substitution variables (used by `apply-template` and `setup-app` commands): `{{APP_LOCATION_LINK}}`, `{{APP_IMAGE_LINK}}`, `{{APP_IDENTITY}}`, `{{APP_IDENTITY_LINK}}`, `{{APP_SECRETS}}` and `{{APP_SECRETS_POLICY}}`. [PR 146](https://github.com/shakacode/heroku-to-control-plane/pull/146) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Added `--run-release-phase` option to `deploy-image` command to run release script before deploying (same step as in `promote-app-from-upstream` command). [PR 146](https://github.com/shakacode/heroku-to-control-plane/pull/146) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
+### Changed
+
+- Template substitution (used by `apply-template` and `setup-app` commands) now uses double braces (e.g., `APP_ORG` -> `{{APP_ORG}}`). This change is backwards compatible. [PR 146](https://github.com/shakacode/heroku-to-control-plane/pull/146) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Renamed template substitution variable `APP_GVC` to `{{APP_NAME}}` (used by `apply-template` and `setup-app` commands). This change is backwards compatible. [PR 146](https://github.com/shakacode/heroku-to-control-plane/pull/146) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- `setup-app` command now automatically binds the app to the secrets policy, as long as both the identity and the policy exist. Added `--skip-secret-access-binding` option to prevent this behavior. [PR 146](https://github.com/shakacode/heroku-to-control-plane/pull/146) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Local API token is now refreshed when it is about to expire. [PR 146](https://github.com/shakacode/heroku-to-control-plane/pull/146) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- `apply-template` command now exits with non-zero code if failed to apply any templates. [PR 146](https://github.com/shakacode/heroku-to-control-plane/pull/146) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
+## [1.3.0] - 2024-03-19
+
+### Fixed
+
+- Fixed issue where cpln profile was not switched back to `default` if an error happened while running `copy-image-from-upstream` command. [PR 135](https://github.com/shakacode/heroku-to-control-plane/pull/135) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Fixed issue that didn't allow using upstream with `match_if_app_name_starts_with` set to `true` in `copy-image-from-upstream` command. [PR 136](https://github.com/shakacode/heroku-to-control-plane/pull/136) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
+### Added
+
+- Added `--no-clean-on-failure` option to `run:detached` command to skip deletion of failed workload run. [PR 133](https://github.com/shakacode/heroku-to-control-plane/pull/133) by [Justin Gordon](https://github.com/justin808) and [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Added `--domain` option to `maintenance`, `maintenance:on` and `maintenance:off` commands. [PR 131](https://github.com/shakacode/heroku-to-control-plane/pull/131) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Added `default_domain` config to specify domain for `maintenance`, `maintenance:on` and `maintenance:off` commands. [PR 131](https://github.com/shakacode/heroku-to-control-plane/pull/131) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Added option to specify upstream for `copy-image-from-upstream` command through `CPLN_UPSTREAM` env var. [PR 138](https://github.com/shakacode/heroku-to-control-plane/pull/138) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
+### Changed
+
+- `build-image` command now accepts extra options and passes them to `docker build`. [PR 126](https://github.com/shakacode/heroku-to-control-plane/pull/126) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- `CPLN_ORG_UPSTREAM` env var now takes precedence over config from `controlplane.yml` in `copy-image-from-upstream` command. [PR 137](https://github.com/shakacode/heroku-to-control-plane/pull/137) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- `info` command now works properly for apps with `match_if_app_name_starts_with` set to `true`.[PR 139](https://github.com/shakacode/heroku-to-control-plane/pull/139) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- `info` command now lists workloads in the same order as `controlplane.yml`. [PR 139](https://github.com/shakacode/heroku-to-control-plane/pull/139) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Improved domain workload matching for `maintenance`, `maintenance:on` and `maintenance:off` commands (instead of matching only by workload, it now matches by org + app + workload, which is more accurate). [PR 140](https://github.com/shakacode/heroku-to-control-plane/pull/140) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
+## [1.2.0] - 2024-01-03
+
 ### Fixed
 
 - Fixed issue where `info` command does not respect `CPLN_ORG` env var. [PR 88](https://github.com/shakacode/heroku-to-control-plane/pull/88) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
@@ -117,7 +156,10 @@ _Please add entries here for your pull requests that are not yet released._
 
 - Initial release
 
-[Unreleased]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.1.2...HEAD
+[Unreleased]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.1.2...v1.2.0
 [1.1.2]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.1.1...v1.1.2
 [1.1.1]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.0.4...v1.1.0

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    cpl (1.2.0)
+    cpl (1.4.0)
       debug (~> 1.7.1)
       dotenv (~> 2.8.1)
+      jwt (~> 2.8.1)
       psych (~> 5.1.0)
       thor (~> 1.2.1)
 
@@ -13,6 +14,7 @@ GEM
     addressable (2.8.4)
       public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
+    base64 (0.2.0)
     childprocess (4.1.0)
     crack (0.4.5)
       rexml
@@ -24,11 +26,13 @@ GEM
     dotenv (2.8.1)
     hashdiff (1.0.1)
     iniparse (1.5.0)
-    io-console (0.7.1)
-    irb (1.11.0)
+    io-console (0.7.2)
+    irb (1.12.0)
       rdoc
-      reline (>= 0.3.8)
+      reline (>= 0.4.2)
     json (2.6.3)
+    jwt (2.8.1)
+      base64
     overcommit (0.60.0)
       childprocess (>= 0.6.3, < 5)
       iniparse (~> 1.4)
@@ -44,7 +48,7 @@ GEM
     rdoc (6.6.2)
       psych (>= 4.0.0)
     regexp_parser (2.6.2)
-    reline (0.4.1)
+    reline (0.4.3)
       io-console (~> 0.5)
     rexml (3.2.5)
     rspec (3.12.0)

data/README.md

@@ -1,4 +1,4 @@
-# Heroku to Control Plane `cpl` CLI
+# The power of Kubernetes with the ease of Heroku!
 
 <meta name="author" content="Justin Gordon and Sergey Tarasov">
 <meta name="description" content="Instructions on how to migrate from Heroku to Control Plane and a CLI called cpl to make it easier.">
@@ -6,16 +6,24 @@
 <meta name="keywords" content="Control Plane, Heroku, Kubernetes, K8, Infrastructure">
 <meta name="google-site-verification" content="dIV4nMplcYl6YOKOaZMqgvdKXhLJ4cdYY6pS6e_YrPU" />
 
-_A gem that provides **Heroku Flow** functionality on Control Plane, including docs for migrating from [Heroku](https://heroku.com) to [Control Plane](https://shakacode.controlplane.com/)._
-
 [![RSpec](https://github.com/shakacode/heroku-to-control-plane/actions/workflows/rspec.yml/badge.svg)](https://github.com/shakacode/heroku-to-control-plane/actions/workflows/rspec.yml)
 [![Rubocop](https://github.com/shakacode/heroku-to-control-plane/actions/workflows/rubocop.yml/badge.svg)](https://github.com/shakacode/heroku-to-control-plane/actions/workflows/rubocop.yml)
 
 [![Gem](https://badge.fury.io/rb/cpl.svg)](https://badge.fury.io/rb/cpl)
 
+
+Here's a playbook for migrating from [Heroku Flow](https://www.heroku.com/flow) to [Control Plane](https://shakacode.controlplane.com) with our `cpl` gem source code.
+
+----
+
+_If you need a free demo account for Control Plane (no CC required), you can contact [Justin Gordon, CEO of ShakaCode](mailto:justin@shakacode.com)._
+
 ---
 
-_If you need a free demo account for Control Plane (no CC required), you can contact [controlplane@shakacode.com](mailto:controlplane@shakacode.com)._
+Be sure to see the [demo app](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)
+If you would like to see the simple YAML configuration and setup,
+Also, check [how the `cpl` gem (this project) is used in the Github actions](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.github/actions/deploy-to-control-plane/action.yml).
+Here is a brief [video overview](https://www.youtube.com/watch?v=llaQoAV_6Iw).
 
 ---
 
@@ -117,7 +125,7 @@ npm update -g @controlplane/cli
 
 5. Run `cpln image docker-login --org <your-org>` to ensure that you have access to the Control Plane Docker registry.
 
-6. Install Heroku to Control Plane `cpl` CLI as a [Ruby gem](https://rubygems.org/gems/cpl): `gem install cpl`. If you want to hack on the source code, see [CONTRIBUTING.md](CONTRIBUTING.md). 
+6. Install Heroku to Control Plane `cpl` CLI as a [Ruby gem](https://rubygems.org/gems/cpl): `gem install cpl`. If you want to hack on the source code, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 7. You can use [this Dockerfile](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/Dockerfile) as an example for your project. Ensure that you have Docker running.
 
@@ -182,8 +190,20 @@ aliases:
 
     # Allows running the command `cpl setup-app`
     # instead of `cpl apply-template gvc 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.
     setup_app_templates:
       - gvc
+
+      # These templates are only required if using secrets.
+      - identity
+      - secrets
+      - secrets-policy
+
       - redis
       - postgres
       - memcached
@@ -194,11 +214,16 @@ aliases:
     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.
+    # 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:
       - rails
       - 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.
     additional_workloads:
       - redis
       - postgres
@@ -258,6 +283,10 @@ apps:
     # This is relative to the `.controlplane/` directory.
     release_script: release_script
 
+    # default_domain is used for commands that require a domain
+    # including `maintenance`, `maintenance:on`, `maintenance:off`.
+    default_domain: domain.com
+
   my-app-other:
     <<: *common
 
@@ -475,6 +504,13 @@ cpl --help
 
 ## Examples
 
-- See the `examples/` and `templates/` directories of this repository.
+- See this repository's `examples/` and `templates/` directories.
 - See the `.controlplane/` directory of this live example:
-  [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)
+  [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane).
+- See [how the `cpl` gem is used in the Github actions](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.github/actions/deploy-to-control-plane/action.yml).
+- Here is a brief [video overview](https://www.youtube.com/watch?v=llaQoAV_6Iw).
+
+## Resources
+* If you need a free demo account for Control Plane (no CC required), you can contact [Justin Gordon, CEO of ShakaCode](mailto:justin@shakacode.com).
+* [Control Plane Site](https://shakacode.controlplane.com)
+* [Join our Slack to Discuss Heroku to Control Plane](https://reactrails.slack.com/join/shared_invite/enQtNjY3NTczMjczNzYxLTlmYjdiZmY3MTVlMzU2YWE0OWM0MzNiZDI0MzdkZGFiZTFkYTFkOGVjODBmOWEyYWQ3MzA2NGE1YWJjNmVlMGE)

data/cpl.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "debug",    "~> 1.7.1"
   spec.add_dependency "dotenv",   "~> 2.8.1"
+  spec.add_dependency "jwt",      "~> 2.8.1"
   spec.add_dependency "psych",    "~> 5.1.0"
   spec.add_dependency "thor",     "~> 1.2.1"
 

data/docs/commands.md

@@ -21,10 +21,14 @@ This `-a` option is used in most of the commands and will pick all other app con
 **Preprocessed template variables:**
 
 ```
-APP_GVC      - basically GVC or app name
-APP_LOCATION - default location
-APP_ORG      - organization
-APP_IMAGE    - will use latest app image
+{{APP_ORG}}           - organization name
+{{APP_NAME}}          - GVC/app name
+{{APP_LOCATION}}      - location, per YML file, ENV, or command line arg
+{{APP_LOCATION_LINK}} - full link for location, ready to be used for the value of `staticPlacement.locationLinks` in the templates
+{{APP_IMAGE}}         - latest app image
+{{APP_IMAGE_LINK}}    - full link for latest app image, ready to be used for the value of `containers[].image` in the templates
+{{APP_IDENTITY}}      - default identity
+{{APP_IDENTITY_LINK}} - full link for identity, ready to be used for the value of `identityLink` in the templates
 ```
 
 ```sh
@@ -41,6 +45,7 @@ cpl apply-template gvc postgres redis rails -a $APP_NAME
 - Automatically assigns image numbers, e.g., `app:1`, `app:2`, etc.
 - Uses `.controlplane/Dockerfile` or a different Dockerfile specified through `dockerfile` in the `.controlplane/controlplane.yml` file
 - If a commit is provided through `--commit` or `-c`, it will be set as the runtime env var `GIT_COMMIT`
+- Accepts extra options that are passed to `docker build`
 
 ```sh
 cpl build-image -a $APP_NAME
@@ -86,7 +91,7 @@ cpl config -a $APP_NAME
 ### `copy-image-from-upstream`
 
 - Copies an image (by default the latest) from a source org to the current org
-- The source org must be specified through `upstream` in the `.controlplane/controlplane.yml` file
+- The source app must be specified either through the `CPLN_UPSTREAM` env var or `upstream` in the `.controlplane/controlplane.yml` file
 - Additionally, the token for the source org must be provided through `--upstream-token` or `-t`
 - A `cpln` profile will be temporarily created to pull the image from the source org
 
@@ -110,6 +115,8 @@ cpl delete -a $APP_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 deploy will fail if the release script exits with a non-zero code or doesn't exist
 
 ```sh
 cpl deploy-image -a $APP_NAME
@@ -250,8 +257,9 @@ cpl open-console -a $APP_NAME
 - Copies the latest image from upstream, runs a release script (optional), and deploys the image
 - It performs the following steps:
   - Runs `cpl copy-image-from-upstream` to copy the latest image from upstream
-  - Runs a release script if specified through `release_script` in the `.controlplane/controlplane.yml` file
   - Runs `cpl deploy-image` to deploy the image
+  - If `.controlplane/controlplane.yml` includes the `release_script`, `cpl deploy-image` will use the `--run-release-phase` option
+  - The deploy will fail if the release script exits with a non-zero code
 
 ```sh
 cpl promote-app-from-upstream -a $APP_NAME -t $UPSTREAM_TOKEN
@@ -331,28 +339,25 @@ cpl ps:swait -a $APP_NAME -w $WORKLOAD_NAME
 cpl run -a $APP_NAME
 
 # Need to quote COMMAND if setting ENV value or passing args.
-cpl run 'LOG_LEVEL=warn rails db:migrate' -a $APP_NAME
-
-# COMMAND may also be passed at the end.
 cpl run -a $APP_NAME -- 'LOG_LEVEL=warn rails db:migrate'
 
 # Runs command, displays output, and exits shell.
-cpl run ls / -a $APP_NAME
-cpl run rails db:migrate:status -a $APP_NAME
+cpl run -a $APP_NAME -- ls /
+cpl run -a $APP_NAME -- rails db:migrate:status
 
 # Runs command and keeps shell open.
-cpl run rails c -a $APP_NAME
+cpl run -a $APP_NAME -- rails c
 
 # Uses a different image (which may not be promoted yet).
-cpl run rails db:migrate -a $APP_NAME --image appimage:123 # Exact image name
-cpl run rails db:migrate -a $APP_NAME --image latest       # Latest sequential image
+cpl run -a $APP_NAME --image appimage:123 -- rails db:migrate # Exact image name
+cpl run -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 bash -a $APP_NAME -w other-workload
+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 bash -a $APP_NAME --use-local-token
+cpl run -a $APP_NAME --use-local-token -- bash
 ```
 
 ### `run:cleanup`
@@ -374,26 +379,26 @@ cpl run:cleanup -a $APP_NAME
 - 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 'LOG_LEVEL=warn rails db:migrate' -a $APP_NAME
-
-# COMMAND may also be passed at the end.
 cpl run:detached -a $APP_NAME -- 'LOG_LEVEL=warn rails db:migrate'
 
 # 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
+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 rails db:migrate:status -a $APP_NAME -w other-workload
+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 rails db:migrate:status -a $APP_NAME --use-local-token
+cpl run:detached -a $APP_NAME --use-local-token -- rails db:migrate:status
 ```
 
 ### `setup-app`
@@ -401,6 +406,8 @@ cpl run:detached rails db:migrate:status -a $APP_NAME --use-local-token
 - Creates an app and all its workloads
 - Specify the templates for the app and workloads through `setup_app_templates` in the `.controlplane/controlplane.yml` file
 - This should only be used for temporary apps like review apps, never for persistent apps like production (to update workloads for those, use 'cpl apply-template' instead)
+- Automatically binds the app to the secrets policy, as long as both the identity and the policy exist
+- Use `--skip-secret-access-binding` to prevent the automatic bind
 
 ```sh
 cpl setup-app -a $APP_NAME

data/docs/dns.md

@@ -0,0 +1,9 @@
+# DNS Setup Example
+
+About reactrails.com DNS, steps:
+1. create CNAME or ALIAS record pointing to rails-xxxx.cpln.app
+1. go to CPLN Domains -> create
+1. add reactrails.com copy code from there
+1. add TXT record with code as _cpln.reactrails.com
+1. hit ok on CPLN, route to rails workload when asked
+1. wait domain check and certificates created

data/docs/tips.md

@@ -85,7 +85,17 @@ For storing ENVs in the source code, we can use a level of indirection so that y
 code like `cpln://secret/my-app-review-env-secrets.SECRET_KEY_BASE` and then have the secret value stored at the org
 level, which applies to your GVCs mapped to that org.
 
-Here is how you do this:
+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`)
+
+You can also do it manually after. Here is how you do this:
 
 1. In the upper left "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

data/examples/controlplane.yml

@@ -25,8 +25,20 @@ aliases:
 
     # Allows running the command `cpl setup-app`
     # instead of `cpl apply-template gvc redis postgres memcached rails sidekiq`.
-    setup:
+    #
+    # 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.
+    setup_app_templates:
       - gvc
+
+      # These templates are only required if using secrets.
+      - identity
+      - secrets
+      - secrets-policy
+
       - redis
       - postgres
       - memcached
@@ -37,11 +49,16 @@ aliases:
     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.
+    # 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:
       - rails
       - 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.
     additional_workloads:
       - redis
       - postgres
@@ -101,6 +118,10 @@ apps:
     # This is relative to the `.controlplane/` directory.
     release_script: release_script
 
+    # default_domain is used for commands that require a domain
+    # including `maintenance`, `maintenance:on`, `maintenance:off`.
+    default_domain: domain.com
+
   my-app-other:
     <<: *common
 

data/lib/command/apply_template.rb

@@ -20,10 +20,14 @@ module Command
       **Preprocessed template variables:**
 
       ```
-      APP_GVC      - basically GVC or app name
-      APP_LOCATION - default location
-      APP_ORG      - organization
-      APP_IMAGE    - will use latest app image
+      {{APP_ORG}}           - organization name
+      {{APP_NAME}}          - GVC/app name
+      {{APP_LOCATION}}      - location, per YML file, ENV, or command line arg
+      {{APP_LOCATION_LINK}} - full link for location, ready to be used for the value of `staticPlacement.locationLinks` in the templates
+      {{APP_IMAGE}}         - latest app image
+      {{APP_IMAGE_LINK}}    - full link for latest app image, ready to be used for the value of `containers[].image` in the templates
+      {{APP_IDENTITY}}      - default identity
+      {{APP_IDENTITY_LINK}} - full link for identity, ready to be used for the value of `identityLink` in the templates
       ```
     DESC
     EXAMPLES = <<~EX
@@ -36,7 +40,7 @@ module Command
       ```
     EX
 
-    def call # rubocop:disable Metrics/MethodLength, Metrics/PerceivedComplexity
+    def call # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       ensure_templates!
 
       @created_items = []
@@ -55,6 +59,8 @@ module Command
 
       progress.puts if @asked_for_confirmation
 
+      @deprecated_variables = []
+
       pending_templates.each do |template, filename|
         step("Applying template '#{template}'", abort_on_error: false) do
           items = apply_template(filename)
@@ -70,9 +76,13 @@ module Command
         end
       end
 
+      warn_deprecated_variables
+
       print_created_items
       print_failed_templates
       print_skipped_templates
+
+      exit(1) if @failed_templates.any?
     end
 
     private
@@ -124,17 +134,55 @@ module Command
       false
     end
 
-    def apply_template(filename)
+    def apply_template(filename) # rubocop:disable Metrics/MethodLength
       data = File.read(filename)
-                 .gsub("APP_GVC", config.app)
-                 .gsub("APP_LOCATION", config.location)
-                 .gsub("APP_ORG", config.org)
-                 .gsub("APP_IMAGE", latest_image)
+                 .gsub("{{APP_ORG}}", config.org)
+                 .gsub("{{APP_NAME}}", config.app)
+                 .gsub("{{APP_LOCATION}}", config.location)
+                 .gsub("{{APP_LOCATION_LINK}}", app_location_link)
+                 .gsub("{{APP_IMAGE}}", latest_image)
+                 .gsub("{{APP_IMAGE_LINK}}", app_image_link)
+                 .gsub("{{APP_IDENTITY}}", app_identity)
+                 .gsub("{{APP_IDENTITY_LINK}}", app_identity_link)
+                 .gsub("{{APP_SECRETS}}", app_secrets)
+                 .gsub("{{APP_SECRETS_POLICY}}", app_secrets_policy)
+
+      find_deprecated_variables(data)
+
+      # Kept for backwards compatibility
+      data = data
+             .gsub("APP_ORG", config.org)
+             .gsub("APP_GVC", config.app)
+             .gsub("APP_LOCATION", config.location)
+             .gsub("APP_IMAGE", latest_image)
 
       # Don't read in YAML.safe_load as that doesn't handle multiple documents
       cp.apply_template(data)
     end
 
+    def new_variables
+      {
+        "APP_ORG" => "{{APP_ORG}}",
+        "APP_GVC" => "{{APP_NAME}}",
+        "APP_LOCATION" => "{{APP_LOCATION}}",
+        "APP_IMAGE" => "{{APP_IMAGE}}"
+      }
+    end
+
+    def find_deprecated_variables(data)
+      @deprecated_variables.push(*new_variables.keys.select { |old_key| data.include?(old_key) })
+      @deprecated_variables = @deprecated_variables.uniq.sort
+    end
+
+    def warn_deprecated_variables
+      return unless @deprecated_variables.any?
+
+      message = "Please replace these variables in the templates, " \
+                "as support for them will be removed in a future major version bump:"
+      deprecated = @deprecated_variables.map { |old_key| "  - #{old_key} -> #{new_variables[old_key]}" }.join("\n")
+      progress.puts("\n#{Shell.color("DEPRECATED: #{message}", :yellow)}\n#{deprecated}")
+    end
+
     def report_success(item)
       @created_items.push(item)
     end