README.md in cpl-1.4.0 vs README.md in cpl-2.2.0

- old
+ new

@@ -4,12 +4,12 @@ <meta name="description" content="Instructions on how to migrate from Heroku to Control Plane and a CLI called cpl to make it easier."> <meta name="copyright" content="ShakaCode, 2023"> <meta name="keywords" content="Control Plane, Heroku, Kubernetes, K8, Infrastructure"> <meta name="google-site-verification" content="dIV4nMplcYl6YOKOaZMqgvdKXhLJ4cdYY6pS6e_YrPU" /> -[![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) +[![RSpec](https://github.com/shakacode/control-plane-flow/actions/workflows/rspec.yml/badge.svg)](https://github.com/shakacode/control-plane-flow/actions/workflows/rspec.yml) +[![Rubocop](https://github.com/shakacode/control-plane-flow/actions/workflows/rubocop.yml/badge.svg)](https://github.com/shakacode/control-plane-flow/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. @@ -108,11 +108,11 @@ 2. Install [Node.js](https://nodejs.org/en) (required for Control Plane CLI). 3. Install [Ruby](https://www.ruby-lang.org/en/) (required for these helpers). -4. Install Control Plane CLI, and configure access ([docs here](https://docs.controlplane.com/quickstart/quick-start-3-cli#getting-started-with-the-cli)). +4. Install Control Plane CLI, and configure access ([docs here](https://shakadocs.controlplane.com/quickstart/quick-start-3-cli#getting-started-with-the-cli)). ```sh # Install CLI npm install -g @controlplane/cli @@ -123,11 +123,11 @@ 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 use `cpl` from Rake tasks in a Rails project, use `Bundler.with_unbundled_env { `cpl help` } or else you'll get an error that `cpl` cannot be found. While you can add `cpl` to your Gemfile, it's not recommended because it might trigger conflicts with other gems. 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. **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. @@ -141,23 +141,23 @@ The `cpl` gem is based on several configuration files within a `/.controlplane` top-level directory in your project. ``` .controlplane/ ├─ templates/ -│ ├─ gvc.yml +│ ├─ app.yml │ ├─ postgres.yml │ ├─ rails.yml ├─ controlplane.yml ├─ Dockerfile ├─ entrypoint.sh ``` 1. `controlplane.yml` describes the overall application. Be sure to have `<your-org>` as the value for `aliases.common.cpln_org`, or set it with the `CPLN_ORG` environment variable. 2. `Dockerfile` builds the production application. `entrypoint.sh` is an _example_ entrypoint script for the production application, referenced in your Dockerfile. 3. `templates` directory contains the templates for the various workloads, such as `rails.yml` and `postgres.yml`. -4. `templates/gvc.yml` defines your project's GVC (like a Heroku app). More importantly, it contains ENV values for the app. -5. `templates/rails.yml` defines your Rails workload. It may inherit ENV values from the parent GVC, which is populated from the `templates/gvc.yml`. This file also configures scaling, sizing, firewalls, and other workload-specific values. +4. `templates/app.yml` defines your project's GVC (like a Heroku app). More importantly, it contains ENV values for the app. +5. `templates/rails.yml` defines your Rails workload. It may inherit ENV values from the parent GVC, which is populated from the `templates/app.yml`. This file also configures scaling, sizing, firewalls, and other workload-specific values. 6. For other workloads (like lines in a Heroku `Procfile`), you create additional template files. For example, you can base a `templates/sidekiq.yml` on the `templates/rails.yml` file. 7. You can have other files in the `templates` directory, such as `redis.yml` and `postgres.yml`, which could setup Redis and Postgres for a testing application. Here's a complete example of all supported config keys explained for the `controlplane.yml` file: @@ -181,63 +181,88 @@ # (provided that `allow_org_override_by_env` is set to `true`). cpln_org: my-org-staging # 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. 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. setup_app_templates: - - gvc - - # These templates are only required if using secrets. - - identity - - secrets - - secrets-policy - + - app - redis - postgres - memcached - rails - sidekiq + # Skips secrets setup when running `cpl setup-app`. + skip_secrets_setup: true + + # 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: - 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. + # These are only used by the `info` and `ps:` commands in order to get all of the defined workloads. additional_workloads: - redis - postgres - memcached # 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`. + # when running `cpl run`. fix_terminal_size: true + # Sets a default CPU size for `cpl run` jobs (can be overridden per job through `--cpu`). + # If not specified, defaults to "1" (1 core). + runner_job_default_cpu: "2" + + # Sets a default memory size for `cpl run` jobs (can be overridden per job through `--memory`). + # If not specified, defaults to "2Gi" (2 gibibytes). + runner_job_default_memory: "4Gi" + + # Sets the maximum number of seconds that `cpl run` jobs can execute before being stopped. + # If not specified, defaults to 21600 (6 hours). + runner_job_timeout: 1000 + # 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 that exceed this quantity will be listed for deletion @@ -246,14 +271,10 @@ # Images created before this amount of days will be listed for deletion # 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. <<: *common @@ -262,10 +283,19 @@ # 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 + # Hooks can be either a script path that exists in the app image or a command. + # They're run in the context of `cpl run` with the latest image. + hooks: + # Used by the command `cpl setup-app` to run a hook after creating the app. + post_creation: bundle exec rake db:prepare + + # Used by the command `cpl delete` to run a hook before deleting the app. + pre_deletion: bundle exec rake db:drop + my-app-production: <<: *common # You can also opt out of allowing the use of CPLN_ORG and CPLN_APP env vars per app. # It's recommended to leave this off for production, to avoid any accidents. @@ -305,11 +335,11 @@ ### Setup Commands ```sh # Provision all infrastructure on Control Plane. # `tutorial-app` will be created per definition in .controlplane/controlplane.yml. -cpl apply-template gvc postgres redis rails daily-task -a tutorial-app +cpl apply-template app postgres redis rails daily-task -a tutorial-app # Build and push the Docker image to the Control Plane repository. # Note, it may take many minutes. Be patient. # Check for error messages, such as forgetting to run `cpln image docker-login --org <your-org>`. cpl build-image -a tutorial-app @@ -334,11 +364,11 @@ cpl build-image -a tutorial-app # Run database migrations (or other release tasks) with the latest image, # while the app is still running on the previous image. # This is analogous to the release phase. -cpl run:detached rails db:migrate -a tutorial-app --image latest +cpl run -a tutorial-app --image latest -- rails db:migrate # Pomote the latest image to the app. cpl deploy-image -a tutorial-app ``` @@ -372,11 +402,11 @@ It is also possible to set up a Secret store (of type `Dictionary`), which we can reference as, e.g., `cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_VAR_NAME`. In such a case, we must set up an app Identity and proper Policy to access the secret. -In `templates/gvc.yml`: +In `templates/app.yml`: ```yaml spec: env: - name: MY_GLOBAL_VAR @@ -444,10 +474,10 @@ We provide default `redis` and `memcached` templates in this repository optimized for Control Plane and suitable for development purposes. ## Scheduled Jobs -Control Plane supports scheduled jobs via [cron workloads](https://docs.controlplane.com/reference/workload#cron). +Control Plane supports scheduled jobs via [cron workloads](https://shakadocs.controlplane.com/reference/workload#cron). Here's a partial example of a template for a cron workload, using the app image: ```yaml kind: workload