cpl 0.7.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/workflows/command_docs.yml +24 -0
- data/.github/workflows/rspec.yml +8 -5
- data/.github/workflows/rubocop.yml +5 -2
- data/.gitignore +1 -0
- data/.overcommit.yml +3 -0
- data/Gemfile.lock +4 -4
- data/README.md +152 -125
- data/Rakefile +7 -2
- data/docs/assets/grafana-alert.png +0 -0
- data/docs/assets/memcached.png +0 -0
- data/docs/assets/sidekiq-pre-stop-hook.png +0 -0
- data/docs/commands.md +2 -2
- data/docs/tips.md +177 -0
- data/examples/circleci.yml +8 -9
- data/examples/controlplane.yml +16 -14
- data/lib/command/base.rb +8 -14
- data/lib/command/cleanup_stale_apps.rb +1 -0
- data/lib/command/run.rb +8 -6
- data/lib/command/run_detached.rb +12 -8
- data/lib/core/scripts.rb +2 -2
- data/lib/cpl/version.rb +2 -1
- data/lib/cpl.rb +42 -1
- data/script/check_command_docs +3 -0
- data/script/{generate_commands_docs → update_command_docs} +2 -2
- data/templates/daily-task.yml +5 -4
- data/templates/maintenance.yml +4 -3
- data/templates/memcached.yml +3 -2
- data/templates/postgres.yml +3 -2
- data/templates/rails.yml +3 -2
- data/templates/redis.yml +2 -1
- data/templates/sidekiq.yml +13 -4
- metadata +9 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: da0cd8b4b3f57a141b2a148a35555069f4ff4135803e4ae95932cd3887e3a567
|
|
4
|
+
data.tar.gz: dab258fecce6a5948374057418959d736915ab69f84593e1b189c148f62f00be
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 31c5cfe13e647abf6f34f6b021c808c220db07a48cd223d0d277ad7814ab0942961a7b75c63d89c3c109e7ca670d478285e5289fdb9fe64ccd828917b7fccf22
|
|
7
|
+
data.tar.gz: 926431c8d7fb4c5f8ba7930a3a156d70718dcce6eb1c717e9859f5a8546900266e4267cee7c755ca4c99612fb1b574a7cbfdd6ca23a2fd5483c1eb3c743a83db
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
name: Command Docs
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches:
|
|
6
|
+
- main
|
|
7
|
+
pull_request:
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
rspec:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
name: Command Docs
|
|
13
|
+
steps:
|
|
14
|
+
- name: Checkout code
|
|
15
|
+
uses: actions/checkout@v3
|
|
16
|
+
- name: Set up Ruby
|
|
17
|
+
uses: ruby/setup-ruby@v1
|
|
18
|
+
with:
|
|
19
|
+
ruby-version: "3.0"
|
|
20
|
+
bundler-cache: true
|
|
21
|
+
- name: Install dependencies
|
|
22
|
+
run: bundle install
|
|
23
|
+
- name: Check if command docs are up to date
|
|
24
|
+
run: bundle exec rake check_command_docs
|
data/.github/workflows/rspec.yml
CHANGED
|
@@ -8,15 +8,18 @@ on:
|
|
|
8
8
|
|
|
9
9
|
jobs:
|
|
10
10
|
rspec:
|
|
11
|
-
runs-on: ubuntu-latest
|
|
12
|
-
name: RSpec
|
|
13
|
-
env:
|
|
14
|
-
RAILS_ENV: test
|
|
15
11
|
strategy:
|
|
16
12
|
matrix:
|
|
13
|
+
os:
|
|
14
|
+
- ubuntu-latest
|
|
15
|
+
- macos-latest
|
|
17
16
|
ruby:
|
|
18
17
|
- "2.7"
|
|
19
18
|
- "3.0"
|
|
19
|
+
runs-on: ${{ matrix.os }}
|
|
20
|
+
name: RSpec
|
|
21
|
+
env:
|
|
22
|
+
RAILS_ENV: test
|
|
20
23
|
steps:
|
|
21
24
|
- name: Checkout code
|
|
22
25
|
uses: actions/checkout@v3
|
|
@@ -28,7 +31,7 @@ jobs:
|
|
|
28
31
|
- name: Install dependencies
|
|
29
32
|
run: bundle install
|
|
30
33
|
- name: Run tests
|
|
31
|
-
run: bundle exec rspec
|
|
34
|
+
run: bundle exec rspec
|
|
32
35
|
- name: Upload coverage results
|
|
33
36
|
uses: actions/upload-artifact@master
|
|
34
37
|
if: always()
|
|
@@ -8,13 +8,16 @@ on:
|
|
|
8
8
|
|
|
9
9
|
jobs:
|
|
10
10
|
rubocop:
|
|
11
|
-
runs-on: ubuntu-latest
|
|
12
|
-
name: Rubocop
|
|
13
11
|
strategy:
|
|
14
12
|
matrix:
|
|
13
|
+
os:
|
|
14
|
+
- ubuntu-latest
|
|
15
|
+
- macos-latest
|
|
15
16
|
ruby:
|
|
16
17
|
- "2.7"
|
|
17
18
|
- "3.0"
|
|
19
|
+
runs-on: ${{ matrix.os }}
|
|
20
|
+
name: Rubocop
|
|
18
21
|
steps:
|
|
19
22
|
- name: Checkout code
|
|
20
23
|
uses: actions/checkout@v3
|
data/.gitignore
CHANGED
data/.overcommit.yml
CHANGED
data/Gemfile.lock
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
PATH
|
|
2
2
|
remote: .
|
|
3
3
|
specs:
|
|
4
|
-
cpl (0.
|
|
4
|
+
cpl (1.0.1)
|
|
5
5
|
debug (~> 1.7.1)
|
|
6
6
|
dotenv (~> 2.8.1)
|
|
7
7
|
psych (~> 5.1.0)
|
|
@@ -25,7 +25,7 @@ GEM
|
|
|
25
25
|
hashdiff (1.0.1)
|
|
26
26
|
iniparse (1.5.0)
|
|
27
27
|
io-console (0.6.0)
|
|
28
|
-
irb (1.
|
|
28
|
+
irb (1.7.0)
|
|
29
29
|
reline (>= 0.3.0)
|
|
30
30
|
json (2.6.3)
|
|
31
31
|
overcommit (0.60.0)
|
|
@@ -41,7 +41,7 @@ GEM
|
|
|
41
41
|
rainbow (3.1.1)
|
|
42
42
|
rake (13.0.6)
|
|
43
43
|
regexp_parser (2.6.2)
|
|
44
|
-
reline (0.3.
|
|
44
|
+
reline (0.3.5)
|
|
45
45
|
io-console (~> 0.5)
|
|
46
46
|
rexml (3.2.5)
|
|
47
47
|
rspec (3.12.0)
|
|
@@ -83,7 +83,7 @@ GEM
|
|
|
83
83
|
simplecov_json_formatter (~> 0.1)
|
|
84
84
|
simplecov-html (0.12.3)
|
|
85
85
|
simplecov_json_formatter (0.1.4)
|
|
86
|
-
stringio (3.0.
|
|
86
|
+
stringio (3.0.7)
|
|
87
87
|
thor (1.2.2)
|
|
88
88
|
timecop (0.9.6)
|
|
89
89
|
unicode-display_width (2.4.2)
|
data/README.md
CHANGED
|
@@ -13,49 +13,57 @@ _A playbook for migrating from [Heroku](https://heroku.com) to [Control Plane](h
|
|
|
13
13
|
|
|
14
14
|
[](https://badge.fury.io/rb/cpl)
|
|
15
15
|
|
|
16
|
-
This playbook shows how to move "Heroku apps" to "Control Plane workloads" via an open-source `cpl` CLI on top of
|
|
16
|
+
This playbook shows how to move "Heroku apps" to "Control Plane workloads" via an open-source `cpl` CLI on top of
|
|
17
|
+
Control Plane's `cpln` CLI.
|
|
17
18
|
|
|
18
|
-
Heroku provides a UX and CLI that enables easy publishing of Ruby on Rails and other apps. This ease of use comes via
|
|
19
|
-
|
|
19
|
+
Heroku provides a UX and CLI that enables easy publishing of Ruby on Rails and other apps. This ease of use comes via
|
|
20
|
+
many "Heroku" abstractions and naming conventions.
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
Control Plane, on the other hand, gives you access to raw cloud computing power. However, you need to know precisely how
|
|
23
|
+
to use it.
|
|
22
24
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
+
To simplify migration to and usage of Control Plane for Heroku users, this repository provides a **concept mapping** and
|
|
26
|
+
a **helper CLI** based on templates to save lots of day-to-day typing (and human errors).
|
|
27
|
+
|
|
28
|
+
1. [Key Features](#key-features)
|
|
29
|
+
2. [Concept Mapping](#concept-mapping)
|
|
25
30
|
3. [Installation](#installation)
|
|
26
|
-
4. [Example CLI
|
|
27
|
-
|
|
31
|
+
4. [Example CLI Flow for Application Build/Deployment](#example-cli-flow-for-application-builddeployment)
|
|
32
|
+
- [Initial Setup and Deployment](#initial-setup-and-deployment)
|
|
33
|
+
- [Promoting Code Upgrades](#promoting-code-upgrades)
|
|
34
|
+
5. [Example Project Modifications for Control Plane](#example-project-modifications-for-control-plane)
|
|
28
35
|
6. [Environment](#environment)
|
|
29
36
|
7. [Database](#database)
|
|
30
|
-
8. [In-memory
|
|
31
|
-
9. [Scheduled
|
|
32
|
-
10. [CLI
|
|
37
|
+
8. [In-memory Databases](#in-memory-databases)
|
|
38
|
+
9. [Scheduled Jobs](#scheduled-jobs)
|
|
39
|
+
10. [CLI Commands Reference](#cli-commands-reference)
|
|
33
40
|
11. [Mapping of Heroku Commands to `cpl` and `cpln`](#mapping-of-heroku-commands-to-cpl-and-cpln)
|
|
34
41
|
12. [Examples](#examples)
|
|
35
|
-
13. [Migrating Postgres
|
|
36
|
-
14. [Migrating Redis
|
|
42
|
+
13. [Migrating Postgres Database from Heroku Infrastructure](/docs/postgres.md)
|
|
43
|
+
14. [Migrating Redis Database from Heroku Infrastructure](/docs/redis.md)
|
|
44
|
+
15. [Tips](/docs/tips.md)
|
|
37
45
|
|
|
38
|
-
## Key
|
|
46
|
+
## Key Features
|
|
39
47
|
|
|
40
|
-
- A `cpl` command to complement the default Control Plane `cpln` command with "Heroku style scripting." The Ruby source
|
|
48
|
+
- A `cpl` command to complement the default Control Plane `cpln` command with "Heroku style scripting." The Ruby source
|
|
49
|
+
can serve as inspiration for your own scripts.
|
|
41
50
|
- Easy to understand Heroku to Control Plane conventions in setup and naming.
|
|
42
51
|
- **Safe, production-ready** equivalents of `heroku run` and `heroku run:detached` for Control Plane.
|
|
43
52
|
- Automatic sequential release tagging for Docker images.
|
|
44
|
-
- A project-aware CLI
|
|
53
|
+
- A project-aware CLI that enables working on multiple projects.
|
|
45
54
|
|
|
46
|
-
## Concept
|
|
55
|
+
## Concept Mapping
|
|
47
56
|
|
|
48
57
|
On Heroku, everything runs as an app, which means an entity that:
|
|
49
58
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
On Control Plane, we can map a Heroku app to a GVC (Global Virtual Cloud). Such a cloud consists of workloads, which can be anything that can run as a container.
|
|
59
|
+
- runs code from a Git repository.
|
|
60
|
+
- runs several process types, as defined in the `Procfile`.
|
|
61
|
+
- has dynos, which are Linux containers that run these process types.
|
|
62
|
+
- has add-ons, including the database and other services.
|
|
63
|
+
- has common environment variables.
|
|
57
64
|
|
|
58
|
-
|
|
65
|
+
On Control Plane, we can map a Heroku app to a GVC (Global Virtual Cloud). Such a cloud consists of workloads, which can
|
|
66
|
+
be anything that can run as a container.
|
|
59
67
|
|
|
60
68
|
| Heroku | Control Plane |
|
|
61
69
|
| ---------------- | ------------------------------------------- |
|
|
@@ -66,54 +74,61 @@ On Control Plane, we can map a Heroku app to a GVC (Global Virtual Cloud). Such
|
|
|
66
74
|
| _staging env_ | _GVC (app)_ in staging _organization_ |
|
|
67
75
|
| _production env_ | _GVC (app)_ in production _organization_ |
|
|
68
76
|
|
|
69
|
-
On Heroku, dyno types are specified in the `Procfile` and configured via the CLI/UI; add-ons are configured only via the
|
|
77
|
+
On Heroku, dyno types are specified in the `Procfile` and configured via the CLI/UI; add-ons are configured only via the
|
|
78
|
+
CLI/UI.
|
|
79
|
+
|
|
70
80
|
On Control Plane, workloads are created either by _templates_ (preferred way) or via the CLI/UI.
|
|
71
81
|
|
|
72
82
|
For the typical Rails app, this means:
|
|
73
83
|
|
|
74
|
-
| Function
|
|
75
|
-
|
|
|
76
|
-
| web traffic
|
|
77
|
-
| background jobs
|
|
78
|
-
| db
|
|
79
|
-
| in-memory db
|
|
80
|
-
|
|
|
84
|
+
| Function | Examples | On Heroku | On Control Plane |
|
|
85
|
+
| --------------- | -------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
86
|
+
| web traffic | `rails`, `sinatra` | `web` dyno | workload with app image |
|
|
87
|
+
| background jobs | `sidekiq`, `resque` | `worker` dyno | workload with app image |
|
|
88
|
+
| db | `postgres`, `mysql` | add-on | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
|
|
89
|
+
| in-memory db | `redis`, `memcached` | add-on | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
|
|
90
|
+
| others | `mailtrap` | add-on | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
|
|
81
91
|
|
|
82
92
|
## Installation
|
|
83
93
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
2. Install `ruby` (required for these helpers).
|
|
88
|
-
3. Install Control Plane CLI (adds `cpln` command) and configure credentials by running command `cpln login`.
|
|
94
|
+
1. Install [Node.js](https://nodejs.org/en) (required for Control Plane CLI).
|
|
95
|
+
2. Install [Ruby](https://www.ruby-lang.org/en/) (required for these helpers).
|
|
96
|
+
3. Install Control Plane CLI (adds `cpln` command) and configure credentials.
|
|
89
97
|
|
|
90
98
|
```sh
|
|
91
99
|
npm install -g @controlplane/cli
|
|
92
100
|
cpln login
|
|
93
101
|
```
|
|
94
102
|
|
|
95
|
-
|
|
103
|
+
4. Install Heroku to Control Plane `cpl` CLI, either as a [Ruby gem](https://rubygems.org/gems/cpl) or a local clone.
|
|
104
|
+
For information on the latter, see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
96
105
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
folder tree it runs. Thus, this automates running several projects with different configs without explicitly switching configs.
|
|
106
|
+
```sh
|
|
107
|
+
gem install cpl
|
|
108
|
+
```
|
|
101
109
|
|
|
102
|
-
|
|
110
|
+
**Note:** Do not confuse the `cpl` CLI with the `cpln` CLI. The `cpl` CLI is the Heroku to Control Plane playbook CLI.
|
|
111
|
+
The `cpln` CLI is the Control Plane CLI.
|
|
103
112
|
|
|
104
|
-
## Example CLI
|
|
113
|
+
## Example CLI Flow for Application Build/Deployment
|
|
105
114
|
|
|
106
115
|
**Notes:**
|
|
107
116
|
|
|
108
|
-
|
|
109
|
-
|
|
117
|
+
- `my-app` is an app name defined in the `.controlplane/controlplane.yml` file, such as `ror-tutorial` in
|
|
118
|
+
[this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
|
|
119
|
+
- Other files in the `.controlplane/templates/` directory are used by the `cpl setup-app` and `cpl apply-template`
|
|
120
|
+
commands.
|
|
110
121
|
|
|
111
122
|
### Initial Setup and Deployment
|
|
112
123
|
|
|
113
|
-
|
|
124
|
+
For each Git project that you want to deploy to Control Plane, copy project-specific configs to a `.controlplane/`
|
|
125
|
+
directory at the top of your project. `cpl` will pick those up depending on which project folder tree it runs. Thus,
|
|
126
|
+
this automates running several projects with different configs without explicitly switching configs.
|
|
127
|
+
|
|
128
|
+
Before the initial setup, add the templates for the app to `.controlplane/controlplane.yml`, using the `setup` key, e.g.:
|
|
114
129
|
|
|
115
130
|
```yaml
|
|
116
|
-
|
|
131
|
+
my-app:
|
|
117
132
|
setup:
|
|
118
133
|
- gvc
|
|
119
134
|
- postgres
|
|
@@ -123,59 +138,61 @@ myapp:
|
|
|
123
138
|
- sidekiq
|
|
124
139
|
```
|
|
125
140
|
|
|
126
|
-
Note how the templates correspond to files in the `.controlplane/templates
|
|
141
|
+
Note how the templates correspond to files in the `.controlplane/templates/` directory.
|
|
142
|
+
|
|
143
|
+
Then create a `Dockerfile` for your deployment. See
|
|
144
|
+
[this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/Dockerfile).
|
|
127
145
|
|
|
128
146
|
```sh
|
|
129
147
|
# Provision infrastructure (one-time-only for new apps) using templates.
|
|
130
|
-
cpl setup-app -a
|
|
148
|
+
cpl setup-app -a my-app
|
|
131
149
|
|
|
132
|
-
# Build and push image with auto-tagging "
|
|
133
|
-
cpl build-image -a
|
|
150
|
+
# Build and push image with auto-tagging, e.g., "my-app:1_456".
|
|
151
|
+
cpl build-image -a my-app --commit 456
|
|
134
152
|
|
|
135
153
|
# Prepare database.
|
|
136
|
-
cpl run:detached
|
|
154
|
+
cpl run:detached -a my-app --image latest -- rails db:prepare
|
|
137
155
|
|
|
138
156
|
# Deploy latest image.
|
|
139
|
-
cpl deploy-image -a
|
|
157
|
+
cpl deploy-image -a my-app
|
|
140
158
|
|
|
141
159
|
# Open app in browser.
|
|
142
|
-
cpl open -a
|
|
160
|
+
cpl open -a my-app
|
|
143
161
|
```
|
|
144
162
|
|
|
145
|
-
### Promoting
|
|
163
|
+
### Promoting Code Upgrades
|
|
146
164
|
|
|
147
165
|
```sh
|
|
148
|
-
# Build and push new image with sequential
|
|
149
|
-
cpl build-image -a
|
|
166
|
+
# Build and push new image with sequential tagging, e.g., "my-app:2".
|
|
167
|
+
cpl build-image -a my-app
|
|
150
168
|
|
|
151
|
-
#
|
|
152
|
-
|
|
153
|
-
cpl build-image -a ror-tutorial --commit ABCD
|
|
169
|
+
# Or build and push new image with sequential tagging and commit SHA, e.g., "my-app:2_ABC".
|
|
170
|
+
cpl build-image -a my-app --commit ABC
|
|
154
171
|
|
|
155
|
-
# Run database migrations (or other release tasks) with latest image,
|
|
156
|
-
# while app is still running on previous image.
|
|
172
|
+
# Run database migrations (or other release tasks) with latest image, while app is still running on previous image.
|
|
157
173
|
# This is analogous to the release phase.
|
|
158
|
-
cpl run:detached
|
|
174
|
+
cpl run:detached -a my-app --image latest -- rails db:migrate
|
|
159
175
|
|
|
160
|
-
# Deploy latest image
|
|
161
|
-
cpl deploy-image -a
|
|
176
|
+
# Deploy latest image.
|
|
177
|
+
cpl deploy-image -a my-app
|
|
162
178
|
```
|
|
163
179
|
|
|
164
|
-
## Example
|
|
180
|
+
## Example Project Modifications for Control Plane
|
|
165
181
|
|
|
166
182
|
_See this for a complete example._
|
|
167
183
|
|
|
168
|
-
To learn how to migrate an app, we recommend
|
|
184
|
+
To learn how to migrate an app, we recommend following along with
|
|
185
|
+
[this example project](https://github.com/shakacode/react-webpack-rails-tutorial).
|
|
169
186
|
|
|
170
|
-
1. Create the `.controlplane
|
|
171
|
-
something as follows:
|
|
187
|
+
1. Create the `.controlplane/` directory at the top of your project and copy files from the `templates/` directory of
|
|
188
|
+
this repository to something as follows:
|
|
172
189
|
|
|
173
190
|
```sh
|
|
174
191
|
app_main_folder/
|
|
175
192
|
.controlplane/
|
|
176
193
|
Dockerfile # Your app's Dockerfile, with some Control Plane changes.
|
|
177
194
|
controlplane.yml
|
|
178
|
-
entrypoint.sh # App-specific
|
|
195
|
+
entrypoint.sh # App-specific - edit as needed.
|
|
179
196
|
templates/
|
|
180
197
|
gvc.yml
|
|
181
198
|
memcached.yml
|
|
@@ -185,9 +202,12 @@ app_main_folder/
|
|
|
185
202
|
sidekiq.yml
|
|
186
203
|
```
|
|
187
204
|
|
|
188
|
-
The example
|
|
205
|
+
The example
|
|
206
|
+
[`.controlplane/` directory](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)
|
|
207
|
+
already contains these files.
|
|
189
208
|
|
|
190
|
-
2. Edit your `controlplane.yml` file as needed. For example, see
|
|
209
|
+
2. Edit your `controlplane.yml` file as needed. For example, see
|
|
210
|
+
[this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
|
|
191
211
|
|
|
192
212
|
```yaml
|
|
193
213
|
# Keys beginning with "cpln_" correspond to your settings in Control Plane.
|
|
@@ -195,11 +215,10 @@ The example [`.controlplane` directory](https://github.com/shakacode/react-webpa
|
|
|
195
215
|
aliases:
|
|
196
216
|
common: &common
|
|
197
217
|
# Organization name for staging (customize to your needs).
|
|
198
|
-
# Production apps will use a different
|
|
218
|
+
# Production apps will use a different organization, specified below, for security.
|
|
199
219
|
cpln_org: my-org-staging
|
|
200
220
|
|
|
201
221
|
# Example apps use only one location. Control Plane offers the ability to use multiple locations.
|
|
202
|
-
# TODO -- allow specification of multiple locations
|
|
203
222
|
default_location: aws-us-east-2
|
|
204
223
|
|
|
205
224
|
# Configure the workload name used as a template for one-off scripts, like a Heroku one-off dyno.
|
|
@@ -216,52 +235,58 @@ aliases:
|
|
|
216
235
|
- postgres
|
|
217
236
|
- memcached
|
|
218
237
|
|
|
238
|
+
# Configure the workload name used when maintenance mode is on (defaults to "maintenance")
|
|
239
|
+
maintenance_workload: maintenance
|
|
240
|
+
|
|
219
241
|
apps:
|
|
220
242
|
my-app-staging:
|
|
221
243
|
# Use the values from the common section above.
|
|
222
244
|
<<: *common
|
|
223
245
|
my-app-review:
|
|
224
246
|
<<: *common
|
|
225
|
-
# If `match_if_app_name_starts_with`
|
|
247
|
+
# If `match_if_app_name_starts_with` is `true`, then use this config for app names starting with this name,
|
|
226
248
|
# e.g., "my-app-review-pr123", "my-app-review-anything-goes", etc.
|
|
227
249
|
match_if_app_name_starts_with: true
|
|
228
250
|
my-app-production:
|
|
229
251
|
<<: *common
|
|
230
252
|
# Use a different organization for production.
|
|
231
253
|
cpln_org: my-org-production
|
|
232
|
-
# Allows running the command `cpl promote-app-from-upstream -a my-app-production`
|
|
254
|
+
# Allows running the command `cpl promote-app-from-upstream -a my-app-production`
|
|
255
|
+
# to promote the staging app to production.
|
|
233
256
|
upstream: my-app-staging
|
|
234
257
|
my-app-other:
|
|
235
258
|
<<: *common
|
|
236
|
-
# You can specify a different `Dockerfile` relative to the `.controlplane
|
|
259
|
+
# You can specify a different `Dockerfile` relative to the `.controlplane/` directory (defaults to "Dockerfile").
|
|
237
260
|
dockerfile: ../some_other/Dockerfile
|
|
238
261
|
```
|
|
239
262
|
|
|
240
|
-
3. We recommend that you try out the commands listed in
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
263
|
+
3. We recommend that you try out the commands listed in
|
|
264
|
+
[the example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/readme.md).
|
|
265
|
+
These steps will guide you to the following:
|
|
266
|
+
|
|
267
|
+
1. Provision the GVC and workloads.
|
|
268
|
+
2. Build the Docker image.
|
|
269
|
+
3. Run Rails migrations, like in the Heroku release phase.
|
|
270
|
+
4. Promote the latest Docker image.
|
|
245
271
|
|
|
246
272
|
## Environment
|
|
247
273
|
|
|
248
274
|
There are two main places where we can set up environment variables in Control Plane:
|
|
249
275
|
|
|
250
|
-
- **In `workload/container/env`** - those are container-specific and
|
|
276
|
+
- **In `workload/container/env`** - those are container-specific and must be set up individually for each container.
|
|
251
277
|
|
|
252
|
-
- **In `gvc/env`** - this is a "common" place to keep env vars which we can share among different workloads.
|
|
253
|
-
|
|
278
|
+
- **In `gvc/env`** - this is a "common" place to keep env vars which we can share among different workloads. Those
|
|
279
|
+
common variables are not visible by default, and we should explicitly enable them via the `inheritEnv` property.
|
|
254
280
|
|
|
255
|
-
|
|
256
|
-
common configs (the same way as on a Heroku app). They are not needed for non-app workloads,
|
|
257
|
-
e.g., `redis`, `memcached`.
|
|
281
|
+
Generally, `gvc/env` vars are useful for "app" types of workloads, e.g., `rails`, `sidekiq`, as they can easily share
|
|
282
|
+
common configs (the same way as on a Heroku app). They are not needed for non-app workloads, e.g., `redis`, `memcached`.
|
|
258
283
|
|
|
259
284
|
It is ok to keep most of the environment variables for non-production environments in the app templates as, in general,
|
|
260
285
|
they are not secret and can be committed to the repository.
|
|
261
286
|
|
|
262
|
-
It is also possible to set up a Secret store (of type Dictionary), which we can reference as,
|
|
263
|
-
|
|
264
|
-
|
|
287
|
+
It is also possible to set up a Secret store (of type `Dictionary`), which we can reference as, e.g.,
|
|
288
|
+
`cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_VAR_NAME`. In such a case, we must set up an app Identity and proper
|
|
289
|
+
Policy to access the secret.
|
|
265
290
|
|
|
266
291
|
```yaml
|
|
267
292
|
# In `templates/gvc.yml`:
|
|
@@ -281,31 +306,32 @@ spec:
|
|
|
281
306
|
value: 'value'
|
|
282
307
|
- name: MY_SECRET_LOCAL_VAR
|
|
283
308
|
value: 'cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_LOCAL_VAR'
|
|
284
|
-
inheritEnv: true # To enable global env inheritance
|
|
309
|
+
inheritEnv: true # To enable global env inheritance.
|
|
285
310
|
```
|
|
286
311
|
|
|
287
312
|
## Database
|
|
288
313
|
|
|
289
314
|
There are several options for a database setup on Control Plane:
|
|
290
315
|
|
|
291
|
-
|
|
292
|
-
|
|
316
|
+
- **Heroku Postgres**. It is the least recommended but simplest. We only need to provision the Postgres add-on on Heroku
|
|
317
|
+
and copy its `XXXXXX_URL` connection string. This is good for quick testing but unsuitable for the long term.
|
|
293
318
|
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
319
|
+
- **Control Plane container**. We can set it up as a workload using one of the default
|
|
320
|
+
[Docker Hub](https://hub.docker.com/) images. However, such a setup lacks persistence between container restarts. We
|
|
321
|
+
can use this only for an example or test app where the database doesn't keep any serious data and where such data is
|
|
322
|
+
restorable.
|
|
298
323
|
|
|
299
|
-
|
|
324
|
+
- Any other cloud provider for Postgres, e.g., Amazon's RDS can be a quick go-to. Here are
|
|
325
|
+
[instructions for setting up a free tier of RDS](https://aws.amazon.com/premiumsupport/knowledge-center/free-tier-rds-launch/).
|
|
300
326
|
|
|
301
327
|
**Tip:** If you are using RDS for development/testing purposes, you might consider running such a database publicly
|
|
302
|
-
accessible (Heroku actually does that for all of its Postgres databases unless they are within private spaces). Then we
|
|
303
|
-
such a database from everywhere with only the correct username/password.
|
|
328
|
+
accessible (Heroku actually does that for all of its Postgres databases unless they are within private spaces). Then we
|
|
329
|
+
can connect to such a database from everywhere with only the correct username/password.
|
|
304
330
|
|
|
305
|
-
By default, we have structured our templates to accomplish this with only a single free tier or low tier AWS RDS
|
|
306
|
-
that can serve all your development/testing needs for small/medium applications, e.g., as follows:
|
|
331
|
+
By default, we have structured our templates to accomplish this with only a single free tier or low tier AWS RDS
|
|
332
|
+
instance that can serve all your development/testing needs for small/medium applications, e.g., as follows:
|
|
307
333
|
|
|
308
|
-
```
|
|
334
|
+
```sh
|
|
309
335
|
aws-rds-single-pg-instance
|
|
310
336
|
mydb-staging
|
|
311
337
|
mydb-review-111
|
|
@@ -313,22 +339,22 @@ aws-rds-single-pg-instance
|
|
|
313
339
|
mydb-review-333
|
|
314
340
|
```
|
|
315
341
|
|
|
316
|
-
Additionally, we provide a default `postgres` template in this
|
|
317
|
-
|
|
342
|
+
Additionally, we provide a default `postgres` template in this repository optimized for Control Plane and suitable for
|
|
343
|
+
development purposes.
|
|
318
344
|
|
|
319
|
-
## In-memory
|
|
345
|
+
## In-memory Databases
|
|
320
346
|
|
|
321
|
-
E.g
|
|
347
|
+
E.g., Redis, Memcached.
|
|
322
348
|
|
|
323
|
-
For development purposes, it's useful to set those up as Control Plane workloads, as in most cases they don't keep any
|
|
324
|
-
valuable data and can be safely restarted
|
|
349
|
+
For development purposes, it's useful to set those up as Control Plane workloads, as in most cases, they don't keep any
|
|
350
|
+
valuable data and can be safely restarted, which doesn't affect application performance.
|
|
325
351
|
|
|
326
352
|
For production purposes or where restarts are not an option, you should use external cloud services.
|
|
327
353
|
|
|
328
|
-
We provide default `redis` and `memcached` templates in this
|
|
329
|
-
|
|
354
|
+
We provide default `redis` and `memcached` templates in this repository optimized for Control Plane and suitable for
|
|
355
|
+
development purposes.
|
|
330
356
|
|
|
331
|
-
## Scheduled
|
|
357
|
+
## Scheduled Jobs
|
|
332
358
|
|
|
333
359
|
Control Plane supports scheduled jobs via [cron workloads](https://docs.controlplane.com/reference/workload#cron).
|
|
334
360
|
|
|
@@ -340,9 +366,9 @@ name: daily-task
|
|
|
340
366
|
spec:
|
|
341
367
|
type: cron
|
|
342
368
|
job:
|
|
343
|
-
# Run daily job at 2am
|
|
369
|
+
# Run daily job at 2am.
|
|
344
370
|
schedule: 0 2 * * *
|
|
345
|
-
# Never or OnFailure
|
|
371
|
+
# "Never" or "OnFailure"
|
|
346
372
|
restartPolicy: Never
|
|
347
373
|
containers:
|
|
348
374
|
- name: daily-task
|
|
@@ -354,17 +380,19 @@ spec:
|
|
|
354
380
|
image: "/org/APP_ORG/image/APP_IMAGE"
|
|
355
381
|
```
|
|
356
382
|
|
|
357
|
-
A complete example can be found at [templates/daily-task.yml](templates/daily-task.yml), optimized for Control Plane and
|
|
383
|
+
A complete example can be found at [templates/daily-task.yml](templates/daily-task.yml), optimized for Control Plane and
|
|
384
|
+
suitable for development purposes.
|
|
358
385
|
|
|
359
|
-
You can create the cron workload by adding the template for it to the `.controlplane/templates
|
|
386
|
+
You can create the cron workload by adding the template for it to the `.controlplane/templates/` directory and running
|
|
387
|
+
`cpl apply-template my-template -a my-app`, where `my-template` is the name of the template file (e.g., `my-template.yml`).
|
|
360
388
|
|
|
361
389
|
Then to view the logs of the cron workload, you can run `cpl logs -a my-app -w my-template`.
|
|
362
390
|
|
|
363
|
-
## CLI
|
|
391
|
+
## CLI Commands Reference
|
|
364
392
|
|
|
365
393
|
Click [here](/docs/commands.md) to see the commands.
|
|
366
394
|
|
|
367
|
-
You can also run:
|
|
395
|
+
You can also run the following command:
|
|
368
396
|
|
|
369
397
|
```sh
|
|
370
398
|
cpl --help
|
|
@@ -372,8 +400,6 @@ cpl --help
|
|
|
372
400
|
|
|
373
401
|
## Mapping of Heroku Commands to `cpl` and `cpln`
|
|
374
402
|
|
|
375
|
-
**`[WIP]`**
|
|
376
|
-
|
|
377
403
|
| Heroku Command | `cpl` or `cpln` |
|
|
378
404
|
| -------------------------------------------------------------------------------------------------------------- | ------------------------------- |
|
|
379
405
|
| [heroku ps](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-ps-type-type) | `cpl ps` |
|
|
@@ -388,5 +414,6 @@ cpl --help
|
|
|
388
414
|
|
|
389
415
|
## Examples
|
|
390
416
|
|
|
391
|
-
|
|
392
|
-
|
|
417
|
+
- See the `examples/` and `templates/` directories of this repository.
|
|
418
|
+
- See the `.controlplane/` directory of this live example:
|
|
419
|
+
[react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)
|
data/Rakefile
CHANGED
|
@@ -10,7 +10,12 @@ RuboCop::RakeTask.new
|
|
|
10
10
|
|
|
11
11
|
task default: %i[rspec rubocop]
|
|
12
12
|
|
|
13
|
+
desc "Checks if commands.md file is up to date"
|
|
14
|
+
task :check_command_docs do
|
|
15
|
+
sh "./script/check_command_docs"
|
|
16
|
+
end
|
|
17
|
+
|
|
13
18
|
desc "Updates commands.md file"
|
|
14
|
-
task :
|
|
15
|
-
sh "./script/
|
|
19
|
+
task :update_command_docs do
|
|
20
|
+
sh "./script/update_command_docs"
|
|
16
21
|
end
|