cpl 0.1.0

data/docs/commands.md

@@ -0,0 +1,219 @@
+<!-- NOTE: This file is automatically generated by running `script/generate_commands_docs`. Do NOT edit it manually. -->
+
+### 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
+
+### `build-image`
+
+- Builds and pushes the image to Control Plane
+- Automatically assigns image numbers, e.g., `app:1`, `app:2`, etc.
+- Uses `.controlplane/Dockerfile`
+
+```sh
+cpl build-image -a $APP_NAME
+```
+
+### `config`
+
+- Displays current configs (global and app-specific)
+
+```sh
+# Shows the global config.
+cpl config
+
+# Shows both global and app-specific configs.
+cpl config -a $APP_NAME
+```
+
+### `delete`
+
+- Deletes the whole app (GVC with all workloads and all images)
+- Will ask for explicit user confirmation
+
+```sh
+cpl delete -a $APP_NAME
+```
+
+### `env`
+
+- Displays app-specific environment variables
+
+```sh
+cpl env -a $APP_NAME
+```
+
+### `exists`
+
+- Shell-checks if an application (GVC) exists, useful in scripts, e.g.:
+
+```sh
+if [ cpl exists -a $APP_NAME ]; ...
+```
+
+### `latest-image`
+
+- Displays the latest image name
+
+```sh
+cpl latest-image -a $APP_NAME
+```
+
+### `logs`
+
+- Light wrapper to display tailed raw logs for app/workload syntax
+
+```sh
+# Displays logs for the default workload (`one_off_workload`).
+cpl logs -a $APP_NAME
+
+# Displays logs for a specific workload.
+cpl logs -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `open`
+
+- Opens the app endpoint URL in the default browser
+
+```sh
+# Opens the endpoint of the default workload (`one_off_workload`).
+cpl open -a $APP_NAME
+
+# Opens the endpoint of a specific workload.
+cpl open -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `promote-image`
+
+- Promotes the latest image to app workloads
+
+```sh
+cpl promote-image -a $APP_NAME
+```
+
+### `ps`
+
+- Shows running replicas in app
+
+```sh
+# Shows running replicas in app, for all workloads.
+cpl ps -a $APP_NAME
+
+# Shows running replicas in app, for a specific workload.
+cpl ps -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `ps:restart`
+
+- Forces redeploy of workloads in app
+
+```sh
+# Forces redeploy of all workloads in app.
+cpl ps:restart -a $APP_NAME
+
+# Forces redeploy of a specific workload in app.
+cpl ps:restart -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `ps:start`
+
+- Starts workloads in app
+
+```sh
+# Starts all workloads in app.
+cpl ps:start -a $APP_NAME
+
+# Starts a specific workload in app.
+cpl ps:start -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `ps:stop`
+
+- Stops workloads in app
+
+```sh
+# Stops all workloads in app.
+cpl ps:stop -a $APP_NAME
+
+# Stops a specific workload in app.
+cpl ps:stop -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
+- May not work correctly with tasks that last over 5 minutes (there's a Control Plane scaling bug at the moment)
+
+> **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`.
+
+```sh
+# Opens shell (bash by default).
+cpl run -a $APP_NAME
+
+# Runs command, displays output, and exits shell.
+cpl run ls / -a $APP_NAME
+cpl run rails db:migrate:status -a $APP_NAME
+
+# Runs command and keeps shell open.
+cpl run rails c -a $APP_NAME
+
+# 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
+```
+
+### `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
+
+```sh
+cpl run:detached rails db:prepare -a $APP_NAME
+cpl run:detached 'LOG_LEVEL=warn rails db:migrate' -a $APP_NAME
+
+# 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
+```
+
+### `setup`
+
+- 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_GVC      - basically GVC or app name
+APP_LOCATION - default location
+APP_ORG      - organization
+APP_IMAGE    - will use latest app image
+```
+
+```sh
+# Applies single template.
+cpl setup redis -a $APP_NAME
+
+# Applies several templates (practically creating full app).
+cpl setup gvc postgres redis rails -a $APP_NAME
+```

data/docs/troubleshooting.md

@@ -0,0 +1,6 @@
+# Troubleshooting
+
+
+## App Web Page Shows `upstream request timeout`
+
+If you get a blank screen showing the message `upstream request timeout` on your app after running `cpl open -a my-app-name`, check out the application logs. Your image has been promoted and your app crashing when starting.

data/examples/circleci.yml

@@ -0,0 +1,106 @@
+# Example config for staging app:
+# - triggers on push to master
+# - static app name
+# - no resource provisioning
+# - no database setup, only migration
+build-staging:
+  docker:
+    - image: cimg/ruby:3.1-node
+  resource_class: large
+  environment:
+    CPLN_ORG: myorg
+    APP_NAME: myapp-staging
+  steps:
+    - checkout
+    - setup_remote_docker:
+        docker_layer_caching: true
+    - run:
+        name: Install Control Plane tools
+        command: |
+          sudo npm install -g @controlplane/cli && cpln --version
+          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
+    - run:
+        name: Containerize and push image
+        command: cpl build-image -a ${APP_NAME}
+    - run:
+        name: Database tasks
+        command: cpl run:detached rails db:migrate -a ${APP_NAME} --image latest
+    - run:
+        name: Promote image
+        command: cpl promote-image -a ${APP_NAME}
+
+# Example config for review app:
+# - triggers manually if needed
+# - dynamic app name based on PR number
+# - resources provisioning for new apps
+# - initial database setup or migration
+build-review-app:
+  docker:
+    - image: cimg/ruby:3.1-node
+  resource_class: large
+  environment:
+    CPLN_ORG: my-org-name
+  steps:
+    - checkout
+    - setup_remote_docker:
+        docker_layer_caching: true
+    - run:
+        name: Setup environment
+        command: |
+          PR_NUM=$(echo $CIRCLE_PULL_REQUEST | grep -Eo '[0-9]+$')
+          echo "export APP_NAME=hichee-review-$PR_NUM" >> $BASH_ENV
+    - run:
+        name: Install Control Plane tools
+        command: |
+          sudo npm install -g @controlplane/cli && cpln --version
+          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
+    - run:
+        name: Provision review app if needed
+        command: |
+          if ! cpl exist -a ${APP_NAME}; then
+            cpl setup gvc postgres redis memcached rails sidekiq -a ${APP_NAME}
+            echo "export NEW_APP=true" >> $BASH_ENV
+          fi
+    - run:
+        name: Containerize and push image
+        command: |
+          cpl build-image -a ${APP_NAME} --commit ${CIRCLE_SHA1::7}
+    - run:
+        name: Database tasks
+        command: |
+          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' -a ${APP_NAME} --image latest
+          fi
+    - run:
+        name: Promote image
+        command: cpl promote-image -a ${APP_NAME}
+
+review-app:
+  jobs:
+    - start:
+        filters:
+          branches:
+            ignore: master
+        type: approval
+    - build-review-app:
+        filters:
+          branches:
+            ignore: master
+        requires:
+          - start
+staging:
+  jobs:
+    - build-staging:
+        filters:
+          branches:
+            only: master

data/examples/controlplane.yml

@@ -0,0 +1,44 @@
+aliases:
+  common: &common
+    # Org name for staging. (customize to your needs)
+    # Production apps will use a different Control Plane org, specified below, for security.
+    # keys beginning with CPLN correspond to your settings in Control Plane
+    cpln_org: my-org-staging
+
+    # Example apps use only location. CPLN offers the ability to use multiple locations.
+    # TODO -- allow specfication of multiple locations
+    default_location: aws-us-east-2
+
+    # 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 application itself and are using application docker image
+    app_workloads:
+      - rails
+      - sidekiq
+
+    # Additional "service type" workloads, using non-application docker images
+    additional_workloads:
+      - redis
+      - postgres
+      - memcached
+
+apps:
+  my-app-staging:
+    # Use the values from the common section above
+    <<: *common
+  my-app-review:
+    <<: *common
+    # if match_if_app_name_starts_with == true, then use this config for app names beginning,
+    # like my-app-review-pr123 or my-app-review-anything-goes
+    match_if_app_name_starts_with: true
+  my-app-production:
+    <<: *common
+    # Use a different org for production
+    cpln_org: my-org-production
+    # Allows running command 'cpl pipeline-promote my-app-staging' to promote the staging app to production
+    upstream: my-app-staging
+  my-app-other:
+    <<: *common
+    # you can specify different dockerfile relative to .controlplane folder, default is just 'Dockerfile'
+    dockerfile: ../some_other/Dockerfile

data/lib/command/base.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Command
+  class Base # rubocop:disable Metrics/ClassLength
+    attr_reader :config
+
+    # Used to call the command (`cpl NAME`)
+    # NAME = ""
+    # Displayed when running `cpl help` or `cpl help NAME` (defaults to `NAME`)
+    USAGE = ""
+    # Throws error if `true` and no arguments are passed to the command
+    # or if `false` and arguments are passed to the command
+    REQUIRES_ARGS = false
+    # Default arguments if none are passed to the command
+    DEFAULT_ARGS = [].freeze
+    # Options for the command (use option methods below)
+    OPTIONS = [].freeze
+    # Displayed when running `cpl help`
+    # DESCRIPTION = ""
+    # Displayed when running `cpl help NAME`
+    # LONG_DESCRIPTION = ""
+    # Displayed along with `LONG_DESCRIPTION` when running `cpl help NAME`
+    EXAMPLES = ""
+    # If `true`, hides the command from `cpl help`
+    HIDE = false
+
+    NO_IMAGE_AVAILABLE = "NO_IMAGE_AVAILABLE"
+
+    def initialize(config)
+      @config = config
+    end
+
+    def self.all_commands
+      Dir["#{__dir__}/*.rb"].each_with_object({}) do |file, result|
+        filename = File.basename(file, ".rb")
+        classname = File.read(file).match(/^\s+class (\w+) < Base($| .*$)/)&.captures&.first
+        result[filename.to_sym] = Object.const_get("::Command::#{classname}") if classname
+      end
+    end
+
+    def self.app_option(required: false)
+      {
+        name: :app,
+        params: {
+          aliases: ["-a"],
+          banner: "APP_NAME",
+          desc: "Application name",
+          type: :string,
+          required: required
+        }
+      }
+    end
+
+    def self.workload_option(required: false)
+      {
+        name: :workload,
+        params: {
+          aliases: ["-w"],
+          banner: "WORKLOAD_NAME",
+          desc: "Workload name",
+          type: :string,
+          required: required
+        }
+      }
+    end
+
+    def self.image_option(required: false)
+      {
+        name: :image,
+        params: {
+          aliases: ["-i"],
+          banner: "IMAGE_NAME",
+          desc: "Image name",
+          type: :string,
+          required: required
+        }
+      }
+    end
+
+    def self.commit_option(required: false)
+      {
+        name: :commit,
+        params: {
+          aliases: ["-c"],
+          banner: "COMMIT_HASH",
+          desc: "Commit hash",
+          type: :string,
+          required: required
+        }
+      }
+    end
+
+    def self.all_options
+      methods.grep(/_option$/).map { |method| send(method.to_s) }
+    end
+
+    def self.all_options_key_name
+      all_options.each_with_object({}) do |option, result|
+        option[:params][:aliases].each { |current_alias| result[current_alias.to_s] = option[:name] }
+        result["--#{option[:name]}"] = option[:name]
+      end
+    end
+
+    def wait_for(title)
+      progress.print "- Waiting for #{title}"
+      until yield
+        progress.print(".")
+        sleep(1)
+      end
+      progress.puts
+    end
+
+    def wait_for_workload(workload)
+      wait_for("workload to start") { cp.workload_get(workload) }
+    end
+
+    def wait_for_replica(workload, location)
+      wait_for("replica") do
+        cp.workload_get_replicas(workload, location: location)&.dig("items", 0)
+      end
+    end
+
+    def ensure_workload_deleted(workload)
+      progress.puts "- Ensure workload is deleted"
+      cp.workload_delete(workload, no_raise: true)
+    end
+
+    def latest_image # rubocop:disable Metrics/MethodLength
+      @latest_image ||=
+        begin
+          items = cp.image_query["items"]
+          matching_items = items.filter_map do |item|
+            item["name"] if item["name"].start_with?("#{config.app}:")
+          end
+
+          # Or special string to indicate no image available
+          if matching_items.empty?
+            "#{config.app}:#{NO_IMAGE_AVAILABLE}"
+          else
+            matching_items.max_by { |item| extract_image_number(item) }
+          end
+        end
+    end
+
+    def latest_image_next
+      @latest_image_next ||= begin
+        image = latest_image.split(":").first
+        image += ":#{extract_image_number(latest_image) + 1}"
+        image += "_#{config.options[:commit]}" if config.options[:commit]
+        image
+      end
+    end
+
+    # NOTE: use simplified variant atm, as shelljoin do different escaping
+    # TODO: most probably need better logic for escaping various quotes
+    def args_join(args)
+      args.join(" ")
+    end
+
+    def progress
+      $stderr
+    end
+
+    def cp
+      @cp ||= Controlplane.new(config)
+    end
+
+    private
+
+    # returns 0 if no prior image
+    def extract_image_number(image_name)
+      return 0 if image_name.end_with?(NO_IMAGE_AVAILABLE)
+
+      image_name.match(/:(\d+)/)&.captures&.first.to_i
+    end
+  end
+end

data/lib/command/build_image.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Command
+  class BuildImage < Base
+    NAME = "build-image"
+    OPTIONS = [
+      app_option(required: true),
+      commit_option
+    ].freeze
+    DESCRIPTION = "Builds and pushes the image to Control Plane"
+    LONG_DESCRIPTION = <<~HEREDOC
+      - Builds and pushes the image to Control Plane
+      - Automatically assigns image numbers, e.g., `app:1`, `app:2`, etc.
+      - Uses `.controlplane/Dockerfile`
+    HEREDOC
+
+    def call
+      dockerfile = config.current[:dockerfile] || "Dockerfile"
+      dockerfile = "#{config.app_cpln_dir}/#{dockerfile}"
+      progress.puts "- Building dockerfile: #{dockerfile}"
+
+      cp.image_build(latest_image_next, dockerfile: dockerfile)
+    end
+  end
+end

data/lib/command/config.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Command
+  class Config < Base
+    NAME = "config"
+    OPTIONS = [
+      app_option
+    ].freeze
+    DESCRIPTION = "Displays current configs (global and app-specific)"
+    LONG_DESCRIPTION = <<~HEREDOC
+      - Displays current configs (global and app-specific)
+    HEREDOC
+    EXAMPLES = <<~HEREDOC
+      ```sh
+      # Shows the global config.
+      cpl config
+
+      # Shows both global and app-specific configs.
+      cpl config -a $APP_NAME
+      ```
+    HEREDOC
+
+    def call
+      puts "-- Options"
+      puts config.options.to_hash.to_yaml[4..]
+      puts
+
+      puts "-- Current config (app: #{config.app})"
+      puts config.app ? config.current.to_yaml[4..] : "Please specify app to get app config"
+      puts
+    end
+  end
+end

data/lib/command/delete.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Command
+  class Delete < Base
+    NAME = "delete"
+    OPTIONS = [
+      app_option(required: true)
+    ].freeze
+    DESCRIPTION = "Deletes the whole app (GVC with all workloads and all images)"
+    LONG_DESCRIPTION = <<~HEREDOC
+      - Deletes the whole app (GVC with all workloads and all images)
+      - Will ask for explicit user confirmation
+    HEREDOC
+
+    def call
+      progress.puts "Type 'delete' to delete #{config.app} and images"
+      progress.print "> "
+
+      return progress.puts "Not confirmed" unless $stdin.gets.chomp == "delete"
+
+      delete_gvc
+      delete_images
+    end
+
+    private
+
+    def delete_gvc
+      progress.puts "- Deleting gvc:"
+
+      return progress.puts "none" unless cp.gvc_get
+
+      cp.gvc_delete
+      progress.puts config.app
+    end
+
+    def delete_images
+      progress.puts "- Deleting image(s):"
+
+      images = cp.image_query["items"]
+                 .filter_map { |item| item["name"] if item["name"].start_with?("#{config.app}:") }
+
+      return progress.puts "none" unless images
+
+      images.each do |image|
+        cp.image_delete(image)
+        progress.puts image
+      end
+    end
+  end
+end

data/lib/command/env.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Command
+  class Env < Base
+    NAME = "env"
+    OPTIONS = [
+      app_option(required: true)
+    ].freeze
+    DESCRIPTION = "Displays app-specific environment variables"
+    LONG_DESCRIPTION = <<~HEREDOC
+      - Displays app-specific environment variables
+    HEREDOC
+
+    def call
+      cp.gvc_get.dig("spec", "env").map do |prop|
+        # NOTE: atm no special chars handling, consider adding if needed
+        puts "#{prop['name']}=#{prop['value']}"
+      end
+    end
+  end
+end

data/lib/command/exists.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Command
+  class Exists < Base
+    NAME = "exists"
+    OPTIONS = [
+      app_option(required: true)
+    ].freeze
+    DESCRIPTION = "Shell-checks if an application (GVC) exists, useful in scripts"
+    LONG_DESCRIPTION = <<~HEREDOC
+      - Shell-checks if an application (GVC) exists, useful in scripts, e.g.:
+    HEREDOC
+    EXAMPLES = <<~HEREDOC
+      ```sh
+      if [ cpl exists -a $APP_NAME ]; ...
+      ```
+    HEREDOC
+
+    def call
+      exit(!cp.gvc_get.nil?)
+    end
+  end
+end