cpl 0.7.0 → 1.0.1
Sign up to get free protection for your applications and to get access to all the features.
- 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
|