## Common Options ``` -a XXX, --app XXX app ref on Control Plane (GVC) ``` This `-a` option is used in most of the commands and will pick all other app configurations from the project-specific `.controlplane/controlplane.yml` file. ## Commands ### `apply-template` - Applies application-specific configs from templates (e.g., for every review-app) - Publishes (creates or updates) those at Control Plane infrastructure - Picks templates from the `.controlplane/templates` directory - Templates are ordinary Control Plane templates but with variable preprocessing **Preprocessed template variables:** ``` {{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 # Applies single template. cpflow apply-template redis -a $APP_NAME # Applies several templates (practically creating full app). cpflow apply-template app postgres redis rails -a $APP_NAME ``` ### `build-image` - Builds and pushes the image to Control Plane - 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 cpflow build-image -a $APP_NAME ``` ### `cleanup-images` - Deletes all images for an app that either exceed the max quantity or are older than the specified amount of days - Specify the max quantity through `image_retention_max_qty` in the `.controlplane/controlplane.yml` file - Specify the amount of days through `image_retention_days` in the `.controlplane/controlplane.yml` file - If `image_retention_max_qty` is specified, any images that exceed it will be deleted, regardless of `image_retention_days` - Will ask for explicit user confirmation - Never deletes the latest image ```sh cpflow cleanup-images -a $APP_NAME ``` ### `cleanup-stale-apps` - Deletes the whole app (GVC with all workloads, all volumesets and all images) for all stale apps - Also unbinds the app from the secrets policy, as long as both the identity and the policy exist (and are bound) - Stale apps are identified based on the creation date of the latest image - Specify the amount of days after an app should be considered stale through `stale_app_image_deployed_days` in the `.controlplane/controlplane.yml` file - If `match_if_app_name_starts_with` is `true` in the `.controlplane/controlplane.yml` file, it will delete all stale apps that start with the name - Will ask for explicit user confirmation ```sh cpflow cleanup-stale-apps -a $APP_NAME ``` ### `config` - Displays config for each app or a specific app ```sh # Shows the config for each app. cpflow config # Shows the config for a specific app. cpflow 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 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 ```sh # Copies the latest image from the source org to the current org. cpflow copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN # Copies a specific image from the source org to the current org. cpflow copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN --image appimage:123 ``` ### `delete` - Deletes the whole app (GVC with all workloads, all volumesets and all images) or a specific workload - Also unbinds the app from the secrets policy, as long as both the identity and the policy exist (and are bound) - Will ask for explicit user confirmation - Runs a pre-deletion hook before the app is deleted if `hooks.pre_deletion` is specified in the `.controlplane/controlplane.yml` file - If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code - Use `--skip-pre-deletion-hook` to skip the hook if specified in `controlplane.yml` ```sh # Deletes the whole app (GVC with all workloads, all volumesets and all images). cpflow delete -a $APP_NAME # Deletes a specific workload. cpflow delete -a $APP_NAME -w $WORKLOAD_NAME ``` ### `deploy-image` - Deploys the latest image to app workloads - Runs a release script before deploying if `release_script` is specified in the `.controlplane/controlplane.yml` file and `--run-release-phase` is provided - The release script is run in the context of `cpflow run` with the latest image - If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code ```sh cpflow deploy-image -a $APP_NAME ``` ### `doctor` - Runs validations ```sh # Runs all validations that don't require additional options by default. cpflow doctor # Runs config validation. cpflow doctor --validations config # Runs templates validation (requires app). cpflow doctor --validations templates -a $APP_NAME ``` ### `env` - Displays app-specific environment variables ```sh cpflow env -a $APP_NAME ``` ### `exists` - Shell-checks if an application (GVC) exists, useful in scripts, e.g.: ```sh if [ cpflow exists -a $APP_NAME ]; ... ``` ### `generate` Creates base Control Plane config and template files ```sh # Creates .controlplane directory with Control Plane config and other templates cpflow generate ``` ### `info` - Displays the diff between defined/available apps/workloads (apps equal GVCs) - Apps that are defined but not available are displayed in red - Apps that are available but not defined are displayed in green - Apps that are both defined and available are displayed in white - The diff is based on what's defined in the `.controlplane/controlplane.yml` file ```sh # Shows diff for all apps in all orgs (based on `.controlplane/controlplane.yml`). cpflow info # Shows diff for all apps in a specific org. cpflow info -o $ORG_NAME # Shows diff for a specific app. cpflow info -a $APP_NAME ``` ### `latest-image` - Displays the latest image name ```sh cpflow 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`). cpflow logs -a $APP_NAME # Displays logs for a specific workload. cpflow logs -a $APP_NAME -w $WORKLOAD_NAME # Displays logs for a specific replica of a workload. cpflow logs -a $APP_NAME -w $WORKLOAD_NAME -r $REPLICA_NAME # Uses a different limit on number of entries. cpflow logs -a $APP_NAME --limit 100 # Uses a different loopback window. cpflow logs -a $APP_NAME --since 30min ``` ### `maintenance` - Checks if maintenance mode is on or off for an app - Outputs 'on' or 'off' - Specify the one-off workload through `one_off_workload` in the `.controlplane/controlplane.yml` file - Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance') - Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443 ```sh cpflow maintenance -a $APP_NAME ``` ### `maintenance:off` - Disables maintenance mode for an app - Specify the one-off workload through `one_off_workload` in the `.controlplane/controlplane.yml` file - Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance') - Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443 ```sh cpflow maintenance:off -a $APP_NAME ``` ### `maintenance:on` - Enables maintenance mode for an app - Specify the one-off workload through `one_off_workload` in the `.controlplane/controlplane.yml` file - Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance') - Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443 ```sh cpflow maintenance:on -a $APP_NAME ``` ### `maintenance:set-page` - Sets the page for maintenance mode - Only works if the maintenance workload uses the `shakacode/maintenance-mode` image - Will set the URL as an env var `PAGE_URL` on the maintenance workload - Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance') ```sh cpflow maintenance:set-page PAGE_URL -a $APP_NAME ``` ### `open` - Opens the app endpoint URL in the default browser ```sh # Opens the endpoint of the default workload (`one_off_workload`). cpflow open -a $APP_NAME # Opens the endpoint of a specific workload. cpflow open -a $APP_NAME -w $WORKLOAD_NAME ``` ### `open-console` - Opens the app console on Control Plane in the default browser - Can also go directly to a workload page if `--workload` is provided ```sh cpflow open-console -a $APP_NAME ``` ### `promote-app-from-upstream` - Copies the latest image from upstream, runs a release script (optional), and deploys the image - It performs the following steps: - Runs `cpflow copy-image-from-upstream` to copy the latest image from upstream - Runs `cpflow deploy-image` to deploy the image - If `.controlplane/controlplane.yml` includes the `release_script`, `cpflow deploy-image` will use the `--run-release-phase` option - If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code ```sh cpflow promote-app-from-upstream -a $APP_NAME -t $UPSTREAM_TOKEN ``` ### `ps` - Shows running replicas in app ```sh # Shows running replicas in app, for all workloads. cpflow ps -a $APP_NAME # Shows running replicas in app, for a specific workload. cpflow ps -a $APP_NAME -w $WORKLOAD_NAME ``` ### `ps:restart` - Forces redeploy of workloads in app ```sh # Forces redeploy of all workloads in app. cpflow ps:restart -a $APP_NAME # Forces redeploy of a specific workload in app. cpflow ps:restart -a $APP_NAME -w $WORKLOAD_NAME ``` ### `ps:start` - Starts workloads in app ```sh # Starts all workloads in app. cpflow ps:start -a $APP_NAME # Starts a specific workload in app. cpflow ps:start -a $APP_NAME -w $WORKLOAD_NAME ``` ### `ps:stop` - Stops workloads in app ```sh # Stops all workloads in app. cpflow ps:stop -a $APP_NAME # Stops a specific workload in app. cpflow ps:stop -a $APP_NAME -w $WORKLOAD_NAME # Stops a specific replica of a workload. cpflow ps:stop -a $APP_NAME -w $WORKLOAD_NAME -r $REPLICA_NAME ``` ### `ps:wait` - Waits for workloads in app to be ready after re-deployment ```sh # Waits for all workloads in app. cpflow ps:wait -a $APP_NAME # Waits for a specific workload in app. cpflow ps:swait -a $APP_NAME -w $WORKLOAD_NAME ``` ### `run` - 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 overridden 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 overridden through `--terminal-size`) - By default, all jobs use a CPU size of 1 (1 core) and a memory size of 2Gi (2 gibibytes) (can be configured through `runner_job_default_cpu` and `runner_job_default_memory` in `controlplane.yml`, and also overridden per job through `--cpu` and `--memory`) - By default, the job is stopped if it takes longer than 6 hours to finish (can be configured though `runner_job_timeout` in `controlplane.yml`) ```sh # Opens shell (bash by default). cpflow run -a $APP_NAME # Runs interactive command, keeps shell open, and stops job when exiting. cpflow run -a $APP_NAME --interactive -- rails c # Some commands are automatically detected as interactive, so no need to pass `--interactive`. cpflow run -a $APP_NAME -- bash cpflow run -a $APP_NAME -- rails console cpflow run -a $APP_NAME -- rails c cpflow run -a $APP_NAME -- rails dbconsole cpflow run -a $APP_NAME -- rails db # Runs non-interactive command, outputs logs, exits with the exit code of the command and stops job. cpflow 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 cpflow run -a $APP_NAME --detached -- rails db:migrate # The command needs to be quoted if setting an env variable or passing args. cpflow run -a $APP_NAME -- 'SOME_ENV_VAR=some_value rails db:migrate' # Uses a different image (which may not be promoted yet). cpflow run -a $APP_NAME --image appimage:123 -- rails db:migrate # Exact image name cpflow run -a $APP_NAME --image latest -- rails db:migrate # Latest sequential image # Uses a different workload than `one_off_workload` from `.controlplane/controlplane.yml`. cpflow 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. cpflow run -a $APP_NAME --use-local-token -- bash # Replaces the existing Dockerfile entrypoint with `bash`. cpflow run -a $APP_NAME --entrypoint none -- rails db:migrate # Replaces the existing Dockerfile entrypoint. cpflow run -a $APP_NAME --entrypoint /app/alternative-entrypoint.sh -- rails db:migrate ``` ### `setup-app` - 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 or staging (to update workloads for those, use 'cpflow apply-template' instead) - Configures app to have org-level secrets with default name "{APP_PREFIX}-secrets" using org-level policy with default name "{APP_PREFIX}-secrets-policy" (names can be customized, see docs) - Creates identity for secrets if it does not exist - Use `--skip-secrets-setup` to prevent the automatic setup of secrets, or set it through `skip_secrets_setup` in the `.controlplane/controlplane.yml` file - Runs a post-creation hook after the app is created if `hooks.post_creation` is specified in the `.controlplane/controlplane.yml` file - If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code - Use `--skip-post-creation-hook` to skip the hook if specified in `controlplane.yml` ```sh cpflow setup-app -a $APP_NAME ``` ### `version` - Displays the current version of the CLI - Can also be done with `cpflow --version` or `cpflow -v` ```sh cpflow version ```