cpl 1.0.0 → 1.0.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.gitignore +1 -0
- data/CHANGELOG.md +32 -3
- data/Gemfile.lock +4 -4
- data/README.md +140 -178
- 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 +14 -2
- data/docs/migrating.md +262 -0
- data/docs/tips.md +177 -0
- data/examples/circleci.yml +8 -9
- data/examples/controlplane.yml +16 -14
- data/lib/command/base.rb +1 -1
- data/lib/command/cleanup_stale_apps.rb +1 -0
- data/lib/command/ps_start.rb +1 -3
- data/lib/command/ps_stop.rb +3 -5
- data/lib/command/ps_wait.rb +35 -0
- data/lib/core/controlplane.rb +20 -0
- data/lib/cpl/version.rb +2 -1
- data/lib/cpl.rb +42 -1
- data/script/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 +8 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 97534e7ffeb4c0b6c7db70851d6cbac5f86ca0329a76af9975dc4a164eeb08b3
|
|
4
|
+
data.tar.gz: 3e8a4e9a60af5859bf157464a164f3b7b430a335a33815d65d9bbc54415d43b5
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 41f11336b2c8a741693e5acc415225bf64d19b4fd0f2240da6ee3de884a517abdb23a37b1ebe166b5b8fd0ccf4d0ae0b95cb7fb3cce0c8f770bfd7c7bc5c6e3e
|
|
7
|
+
data.tar.gz: e3367bea0aeca04add5823d7129f0ffa3f276709e967d5fe6e533241c8fbace80dd1811b54cb2ee7fd71ce500d54535e4bbe4aea76a1c58114ecf324a3fee763
|
data/.gitignore
CHANGED
data/CHANGELOG.md
CHANGED
|
@@ -1,9 +1,38 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
All notable changes to this project's source code will be documented in this file. Items under `Unreleased` are upcoming features that will be out in the next version.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Contributors
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Please follow the recommendations outlined at [keepachangelog.com](https://keepachangelog.com). Please use the existing headings and styling as a guide, and add a link for the version diff at the bottom of the file. Also, please update the `Unreleased` link to compare it to the latest release version.
|
|
8
|
+
|
|
9
|
+
## Versions
|
|
10
|
+
|
|
11
|
+
## [Unreleased]
|
|
12
|
+
|
|
13
|
+
Changes since the last non-beta release.
|
|
14
|
+
|
|
15
|
+
_Please add entries here for your pull requests that are not yet released._
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- Added steps to migrate to docs. [PR 57](https://github.com/shakacode/heroku-to-control-plane/pull/57) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
|
|
20
|
+
- Added `ps:wait` command. [PR 58](https://github.com/shakacode/heroku-to-control-plane/pull/58) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
|
|
21
|
+
|
|
22
|
+
## [1.0.1] - 2023-06-28
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
|
|
26
|
+
- Fixed `cleanup-stale-apps` command when app does not have image. [PR 55](https://github.com/shakacode/heroku-to-control-plane/pull/55) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
|
|
30
|
+
- Improved docs. [PR 50](https://github.com/shakacode/heroku-to-control-plane/pull/50) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
|
|
31
|
+
|
|
32
|
+
## [1.0.0] - 2023-05-29
|
|
8
33
|
|
|
9
34
|
- Initial release
|
|
35
|
+
|
|
36
|
+
[Unreleased]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.0.1...HEAD
|
|
37
|
+
[1.0.1]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.0.0...v1.0.1
|
|
38
|
+
[1.0.0]: https://github.com/shakacode/heroku-to-control-plane/releases/tag/v1.0.0
|
data/Gemfile.lock
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
PATH
|
|
2
2
|
remote: .
|
|
3
3
|
specs:
|
|
4
|
-
cpl (1.0.
|
|
4
|
+
cpl (1.0.2)
|
|
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.1)
|
|
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,55 @@ _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. [
|
|
27
|
-
5. [
|
|
31
|
+
4. [Steps to Migrate](#steps-to-migrate)
|
|
32
|
+
5. [Config](#config)
|
|
28
33
|
6. [Environment](#environment)
|
|
29
34
|
7. [Database](#database)
|
|
30
|
-
8. [In-memory
|
|
31
|
-
9. [Scheduled
|
|
32
|
-
10. [CLI
|
|
35
|
+
8. [In-memory Databases](#in-memory-databases)
|
|
36
|
+
9. [Scheduled Jobs](#scheduled-jobs)
|
|
37
|
+
10. [CLI Commands Reference](#cli-commands-reference)
|
|
33
38
|
11. [Mapping of Heroku Commands to `cpl` and `cpln`](#mapping-of-heroku-commands-to-cpl-and-cpln)
|
|
34
39
|
12. [Examples](#examples)
|
|
35
|
-
13. [Migrating Postgres
|
|
36
|
-
14. [Migrating Redis
|
|
40
|
+
13. [Migrating Postgres Database from Heroku Infrastructure](/docs/postgres.md)
|
|
41
|
+
14. [Migrating Redis Database from Heroku Infrastructure](/docs/redis.md)
|
|
42
|
+
15. [Tips](/docs/tips.md)
|
|
37
43
|
|
|
38
|
-
## Key
|
|
44
|
+
## Key Features
|
|
39
45
|
|
|
40
|
-
- A `cpl` command to complement the default Control Plane `cpln` command with "Heroku style scripting." The Ruby source
|
|
46
|
+
- A `cpl` command to complement the default Control Plane `cpln` command with "Heroku style scripting." The Ruby source
|
|
47
|
+
can serve as inspiration for your own scripts.
|
|
41
48
|
- Easy to understand Heroku to Control Plane conventions in setup and naming.
|
|
42
49
|
- **Safe, production-ready** equivalents of `heroku run` and `heroku run:detached` for Control Plane.
|
|
43
50
|
- Automatic sequential release tagging for Docker images.
|
|
44
|
-
- A project-aware CLI
|
|
51
|
+
- A project-aware CLI that enables working on multiple projects.
|
|
45
52
|
|
|
46
|
-
## Concept
|
|
53
|
+
## Concept Mapping
|
|
47
54
|
|
|
48
55
|
On Heroku, everything runs as an app, which means an entity that:
|
|
49
56
|
|
|
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.
|
|
57
|
+
- runs code from a Git repository.
|
|
58
|
+
- runs several process types, as defined in the `Procfile`.
|
|
59
|
+
- has dynos, which are Linux containers that run these process types.
|
|
60
|
+
- has add-ons, including the database and other services.
|
|
61
|
+
- has common environment variables.
|
|
57
62
|
|
|
58
|
-
|
|
63
|
+
On Control Plane, we can map a Heroku app to a GVC (Global Virtual Cloud). Such a cloud consists of workloads, which can
|
|
64
|
+
be anything that can run as a container.
|
|
59
65
|
|
|
60
66
|
| Heroku | Control Plane |
|
|
61
67
|
| ---------------- | ------------------------------------------- |
|
|
@@ -66,128 +72,49 @@ On Control Plane, we can map a Heroku app to a GVC (Global Virtual Cloud). Such
|
|
|
66
72
|
| _staging env_ | _GVC (app)_ in staging _organization_ |
|
|
67
73
|
| _production env_ | _GVC (app)_ in production _organization_ |
|
|
68
74
|
|
|
69
|
-
On Heroku, dyno types are specified in the `Procfile` and configured via the CLI/UI; add-ons are configured only via the
|
|
75
|
+
On Heroku, dyno types are specified in the `Procfile` and configured via the CLI/UI; add-ons are configured only via the
|
|
76
|
+
CLI/UI.
|
|
77
|
+
|
|
70
78
|
On Control Plane, workloads are created either by _templates_ (preferred way) or via the CLI/UI.
|
|
71
79
|
|
|
72
80
|
For the typical Rails app, this means:
|
|
73
81
|
|
|
74
|
-
| Function
|
|
75
|
-
|
|
|
76
|
-
| web traffic
|
|
77
|
-
| background jobs
|
|
78
|
-
| db
|
|
79
|
-
| in-memory db
|
|
80
|
-
|
|
|
82
|
+
| Function | Examples | On Heroku | On Control Plane |
|
|
83
|
+
| --------------- | -------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
84
|
+
| web traffic | `rails`, `sinatra` | `web` dyno | workload with app image |
|
|
85
|
+
| background jobs | `sidekiq`, `resque` | `worker` dyno | workload with app image |
|
|
86
|
+
| db | `postgres`, `mysql` | add-on | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
|
|
87
|
+
| in-memory db | `redis`, `memcached` | add-on | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
|
|
88
|
+
| others | `mailtrap` | add-on | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
|
|
81
89
|
|
|
82
90
|
## Installation
|
|
83
91
|
|
|
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`.
|
|
92
|
+
1. Install [Node.js](https://nodejs.org/en) (required for Control Plane CLI).
|
|
93
|
+
2. Install [Ruby](https://www.ruby-lang.org/en/) (required for these helpers).
|
|
94
|
+
3. Install Control Plane CLI (adds `cpln` command) and configure credentials.
|
|
89
95
|
|
|
90
96
|
```sh
|
|
91
97
|
npm install -g @controlplane/cli
|
|
92
98
|
cpln login
|
|
93
99
|
```
|
|
94
100
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
Do not confuse the `cpl` CLI with the `cpln` CLI. The `cpl` CLI is the Heroku to Control Plane playbook CLI. The `cpln` CLI is the Control Plane CLI.
|
|
98
|
-
|
|
99
|
-
- For each Git project that you want to deploy to Control Plane, copy project-specific configs to a `.controlplane` directory at the top of your project. `cpl` will pick those up depending on which project
|
|
100
|
-
folder tree it runs. Thus, this automates running several projects with different configs without explicitly switching configs.
|
|
101
|
-
|
|
102
|
-
5. Create a `Dockerfile` for your production deployment. See [this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/Dockerfile).
|
|
103
|
-
|
|
104
|
-
## Example CLI flow for application build/deployment
|
|
105
|
-
|
|
106
|
-
**Notes:**
|
|
107
|
-
|
|
108
|
-
1. `myapp` is an app name defined in the `.controlplane/controlplane.yml` file, such as `ror-tutorial` in [this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
|
|
109
|
-
2. Other files in the `.controlplane/templates` directory are used by the `cpl setup-app` and `cpl apply-template` commands.
|
|
110
|
-
|
|
111
|
-
### Initial Setup and Deployment
|
|
112
|
-
|
|
113
|
-
Before the initial setup, add the templates for the app to `.controlplane/controlplane.yml`, using the `setup` key:
|
|
114
|
-
|
|
115
|
-
```yaml
|
|
116
|
-
myapp:
|
|
117
|
-
setup:
|
|
118
|
-
- gvc
|
|
119
|
-
- postgres
|
|
120
|
-
- redis
|
|
121
|
-
- memcached
|
|
122
|
-
- rails
|
|
123
|
-
- sidekiq
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
Note how the templates correspond to files in the `.controlplane/templates` directory.
|
|
101
|
+
4. Install Heroku to Control Plane `cpl` CLI, either as a [Ruby gem](https://rubygems.org/gems/cpl) or a local clone.
|
|
102
|
+
For information on the latter, see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
127
103
|
|
|
128
104
|
```sh
|
|
129
|
-
|
|
130
|
-
cpl setup-app -a myapp
|
|
131
|
-
|
|
132
|
-
# Build and push image with auto-tagging "myapp:1_456".
|
|
133
|
-
cpl build-image -a myapp --commit 456
|
|
134
|
-
|
|
135
|
-
# Prepare database.
|
|
136
|
-
cpl run:detached rails db:prepare -a myapp --image latest
|
|
137
|
-
|
|
138
|
-
# Deploy latest image.
|
|
139
|
-
cpl deploy-image -a myapp
|
|
140
|
-
|
|
141
|
-
# Open app in browser.
|
|
142
|
-
cpl open -a myapp
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
### Promoting code upgrades
|
|
146
|
-
|
|
147
|
-
```sh
|
|
148
|
-
# Build and push new image with sequential image tagging, e.g. 'ror-tutorial_123'
|
|
149
|
-
cpl build-image -a ror-tutorial
|
|
150
|
-
|
|
151
|
-
# OR
|
|
152
|
-
# Build and push with sequential image tagging and commit SHA, e.g. 'ror-tutorial_123_ABCD'
|
|
153
|
-
cpl build-image -a ror-tutorial --commit ABCD
|
|
154
|
-
|
|
155
|
-
# Run database migrations (or other release tasks) with latest image,
|
|
156
|
-
# while app is still running on previous image.
|
|
157
|
-
# This is analogous to the release phase.
|
|
158
|
-
cpl run:detached rails db:migrate -a ror-tutorial --image latest
|
|
159
|
-
|
|
160
|
-
# Deploy latest image to app
|
|
161
|
-
cpl deploy-image -a ror-tutorial
|
|
105
|
+
gem install cpl
|
|
162
106
|
```
|
|
163
107
|
|
|
164
|
-
|
|
108
|
+
**Note:** Do not confuse the `cpl` CLI with the `cpln` CLI. The `cpl` CLI is the Heroku to Control Plane playbook CLI.
|
|
109
|
+
The `cpln` CLI is the Control Plane CLI.
|
|
165
110
|
|
|
166
|
-
|
|
111
|
+
## Steps to Migrate
|
|
167
112
|
|
|
168
|
-
|
|
113
|
+
Click [here](/docs/migrating.md) to see the steps to migrate.
|
|
169
114
|
|
|
170
|
-
|
|
171
|
-
something as follows:
|
|
115
|
+
## Config
|
|
172
116
|
|
|
173
|
-
|
|
174
|
-
app_main_folder/
|
|
175
|
-
.controlplane/
|
|
176
|
-
Dockerfile # Your app's Dockerfile, with some Control Plane changes.
|
|
177
|
-
controlplane.yml
|
|
178
|
-
entrypoint.sh # App-specific, edit as needed.
|
|
179
|
-
templates/
|
|
180
|
-
gvc.yml
|
|
181
|
-
memcached.yml
|
|
182
|
-
postgres.yml
|
|
183
|
-
rails.yml
|
|
184
|
-
redis.yml
|
|
185
|
-
sidekiq.yml
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
The example [`.controlplane` directory](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane) already contains these files.
|
|
189
|
-
|
|
190
|
-
2. Edit your `controlplane.yml` file as needed. For example, see [this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
|
|
117
|
+
Here's a complete example of all supported config keys explained:
|
|
191
118
|
|
|
192
119
|
```yaml
|
|
193
120
|
# Keys beginning with "cpln_" correspond to your settings in Control Plane.
|
|
@@ -195,13 +122,22 @@ The example [`.controlplane` directory](https://github.com/shakacode/react-webpa
|
|
|
195
122
|
aliases:
|
|
196
123
|
common: &common
|
|
197
124
|
# Organization name for staging (customize to your needs).
|
|
198
|
-
# Production apps will use a different
|
|
125
|
+
# Production apps will use a different organization, specified below, for security.
|
|
199
126
|
cpln_org: my-org-staging
|
|
200
127
|
|
|
201
128
|
# Example apps use only one location. Control Plane offers the ability to use multiple locations.
|
|
202
|
-
# TODO -- allow specification of multiple locations
|
|
203
129
|
default_location: aws-us-east-2
|
|
204
130
|
|
|
131
|
+
# Allows running the command `cpl setup-app`
|
|
132
|
+
# instead of `cpl apply-template gvc redis postgres memcached rails sidekiq`.
|
|
133
|
+
setup:
|
|
134
|
+
- gvc
|
|
135
|
+
- redis
|
|
136
|
+
- postgres
|
|
137
|
+
- memcached
|
|
138
|
+
- rails
|
|
139
|
+
- sidekiq
|
|
140
|
+
|
|
205
141
|
# Configure the workload name used as a template for one-off scripts, like a Heroku one-off dyno.
|
|
206
142
|
one_off_workload: rails
|
|
207
143
|
|
|
@@ -216,52 +152,76 @@ aliases:
|
|
|
216
152
|
- postgres
|
|
217
153
|
- memcached
|
|
218
154
|
|
|
155
|
+
# Configure the workload name used when maintenance mode is on (defaults to "maintenance").
|
|
156
|
+
maintenance_workload: maintenance
|
|
157
|
+
|
|
158
|
+
# Fixes the remote terminal size to match the local terminal size
|
|
159
|
+
# when running the commands `cpl run` or `cpl run:detached`.
|
|
160
|
+
fix_terminal_size: true
|
|
161
|
+
|
|
162
|
+
# Apps with a deployed image created before this amount of days will be listed for deletion
|
|
163
|
+
# when running the command `cpl cleanup-stale-apps`.
|
|
164
|
+
stale_app_image_deployed_days: 5
|
|
165
|
+
|
|
166
|
+
# Images created before this amount of days will be listed for deletion
|
|
167
|
+
# when running the command `cpl cleanup-old-images`.
|
|
168
|
+
old_image_retention_days: 5
|
|
169
|
+
|
|
170
|
+
# Run workloads created before this amount of days will be listed for deletion
|
|
171
|
+
# when running the command `cpl run:cleanup`.
|
|
172
|
+
stale_run_workload_created_days: 2
|
|
173
|
+
|
|
219
174
|
apps:
|
|
220
175
|
my-app-staging:
|
|
221
176
|
# Use the values from the common section above.
|
|
222
177
|
<<: *common
|
|
178
|
+
|
|
223
179
|
my-app-review:
|
|
224
180
|
<<: *common
|
|
225
|
-
|
|
181
|
+
|
|
182
|
+
# If `match_if_app_name_starts_with` is `true`, then use this config for app names starting with this name,
|
|
226
183
|
# e.g., "my-app-review-pr123", "my-app-review-anything-goes", etc.
|
|
227
184
|
match_if_app_name_starts_with: true
|
|
185
|
+
|
|
228
186
|
my-app-production:
|
|
229
187
|
<<: *common
|
|
188
|
+
|
|
230
189
|
# Use a different organization for production.
|
|
231
190
|
cpln_org: my-org-production
|
|
232
|
-
|
|
191
|
+
|
|
192
|
+
# Allows running the command `cpl promote-app-from-upstream -a my-app-production`
|
|
193
|
+
# to promote the staging app to production.
|
|
233
194
|
upstream: my-app-staging
|
|
195
|
+
|
|
196
|
+
# Used by the command `cpl promote-app-from-upstream` to run a release script before deploying.
|
|
197
|
+
# This is relative to the `.controlplane/` directory.
|
|
198
|
+
release_script: release_script
|
|
199
|
+
|
|
234
200
|
my-app-other:
|
|
235
201
|
<<: *common
|
|
236
|
-
|
|
202
|
+
|
|
203
|
+
# You can specify a different `Dockerfile` relative to the `.controlplane/` directory (defaults to "Dockerfile").
|
|
237
204
|
dockerfile: ../some_other/Dockerfile
|
|
238
205
|
```
|
|
239
206
|
|
|
240
|
-
3. We recommend that you try out the commands listed in [the example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/readme.md). These steps will guide you through:
|
|
241
|
-
1. Provision the GVC and workloads
|
|
242
|
-
2. Build the Docker image
|
|
243
|
-
3. Run Rails migrations, like in the Heroku release phase
|
|
244
|
-
4. Promote the lastest Docker image
|
|
245
|
-
|
|
246
207
|
## Environment
|
|
247
208
|
|
|
248
209
|
There are two main places where we can set up environment variables in Control Plane:
|
|
249
210
|
|
|
250
|
-
- **In `workload/container/env`** - those are container-specific and
|
|
211
|
+
- **In `workload/container/env`** - those are container-specific and must be set up individually for each container.
|
|
251
212
|
|
|
252
|
-
- **In `gvc/env`** - this is a "common" place to keep env vars which we can share among different workloads.
|
|
253
|
-
|
|
213
|
+
- **In `gvc/env`** - this is a "common" place to keep env vars which we can share among different workloads. Those
|
|
214
|
+
common variables are not visible by default, and we should explicitly enable them via the `inheritEnv` property.
|
|
254
215
|
|
|
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`.
|
|
216
|
+
Generally, `gvc/env` vars are useful for "app" types of workloads, e.g., `rails`, `sidekiq`, as they can easily share
|
|
217
|
+
common configs (the same way as on a Heroku app). They are not needed for non-app workloads, e.g., `redis`, `memcached`.
|
|
258
218
|
|
|
259
219
|
It is ok to keep most of the environment variables for non-production environments in the app templates as, in general,
|
|
260
220
|
they are not secret and can be committed to the repository.
|
|
261
221
|
|
|
262
|
-
It is also possible to set up a Secret store (of type Dictionary), which we can reference as,
|
|
263
|
-
|
|
264
|
-
|
|
222
|
+
It is also possible to set up a Secret store (of type `Dictionary`), which we can reference as, e.g.,
|
|
223
|
+
`cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_VAR_NAME`. In such a case, we must set up an app Identity and proper
|
|
224
|
+
Policy to access the secret.
|
|
265
225
|
|
|
266
226
|
```yaml
|
|
267
227
|
# In `templates/gvc.yml`:
|
|
@@ -281,31 +241,32 @@ spec:
|
|
|
281
241
|
value: 'value'
|
|
282
242
|
- name: MY_SECRET_LOCAL_VAR
|
|
283
243
|
value: 'cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_LOCAL_VAR'
|
|
284
|
-
inheritEnv: true # To enable global env inheritance
|
|
244
|
+
inheritEnv: true # To enable global env inheritance.
|
|
285
245
|
```
|
|
286
246
|
|
|
287
247
|
## Database
|
|
288
248
|
|
|
289
249
|
There are several options for a database setup on Control Plane:
|
|
290
250
|
|
|
291
|
-
|
|
292
|
-
|
|
251
|
+
- **Heroku Postgres**. It is the least recommended but simplest. We only need to provision the Postgres add-on on Heroku
|
|
252
|
+
and copy its `XXXXXX_URL` connection string. This is good for quick testing but unsuitable for the long term.
|
|
293
253
|
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
254
|
+
- **Control Plane container**. We can set it up as a workload using one of the default
|
|
255
|
+
[Docker Hub](https://hub.docker.com/) images. However, such a setup lacks persistence between container restarts. We
|
|
256
|
+
can use this only for an example or test app where the database doesn't keep any serious data and where such data is
|
|
257
|
+
restorable.
|
|
298
258
|
|
|
299
|
-
|
|
259
|
+
- Any other cloud provider for Postgres, e.g., Amazon's RDS can be a quick go-to. Here are
|
|
260
|
+
[instructions for setting up a free tier of RDS](https://aws.amazon.com/premiumsupport/knowledge-center/free-tier-rds-launch/).
|
|
300
261
|
|
|
301
262
|
**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.
|
|
263
|
+
accessible (Heroku actually does that for all of its Postgres databases unless they are within private spaces). Then we
|
|
264
|
+
can connect to such a database from everywhere with only the correct username/password.
|
|
304
265
|
|
|
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:
|
|
266
|
+
By default, we have structured our templates to accomplish this with only a single free tier or low tier AWS RDS
|
|
267
|
+
instance that can serve all your development/testing needs for small/medium applications, e.g., as follows:
|
|
307
268
|
|
|
308
|
-
```
|
|
269
|
+
```sh
|
|
309
270
|
aws-rds-single-pg-instance
|
|
310
271
|
mydb-staging
|
|
311
272
|
mydb-review-111
|
|
@@ -313,22 +274,22 @@ aws-rds-single-pg-instance
|
|
|
313
274
|
mydb-review-333
|
|
314
275
|
```
|
|
315
276
|
|
|
316
|
-
Additionally, we provide a default `postgres` template in this
|
|
317
|
-
|
|
277
|
+
Additionally, we provide a default `postgres` template in this repository optimized for Control Plane and suitable for
|
|
278
|
+
development purposes.
|
|
318
279
|
|
|
319
|
-
## In-memory
|
|
280
|
+
## In-memory Databases
|
|
320
281
|
|
|
321
|
-
E.g
|
|
282
|
+
E.g., Redis, Memcached.
|
|
322
283
|
|
|
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
|
|
284
|
+
For development purposes, it's useful to set those up as Control Plane workloads, as in most cases, they don't keep any
|
|
285
|
+
valuable data and can be safely restarted, which doesn't affect application performance.
|
|
325
286
|
|
|
326
287
|
For production purposes or where restarts are not an option, you should use external cloud services.
|
|
327
288
|
|
|
328
|
-
We provide default `redis` and `memcached` templates in this
|
|
329
|
-
|
|
289
|
+
We provide default `redis` and `memcached` templates in this repository optimized for Control Plane and suitable for
|
|
290
|
+
development purposes.
|
|
330
291
|
|
|
331
|
-
## Scheduled
|
|
292
|
+
## Scheduled Jobs
|
|
332
293
|
|
|
333
294
|
Control Plane supports scheduled jobs via [cron workloads](https://docs.controlplane.com/reference/workload#cron).
|
|
334
295
|
|
|
@@ -340,9 +301,9 @@ name: daily-task
|
|
|
340
301
|
spec:
|
|
341
302
|
type: cron
|
|
342
303
|
job:
|
|
343
|
-
# Run daily job at 2am
|
|
304
|
+
# Run daily job at 2am.
|
|
344
305
|
schedule: 0 2 * * *
|
|
345
|
-
# Never or OnFailure
|
|
306
|
+
# "Never" or "OnFailure"
|
|
346
307
|
restartPolicy: Never
|
|
347
308
|
containers:
|
|
348
309
|
- name: daily-task
|
|
@@ -354,17 +315,19 @@ spec:
|
|
|
354
315
|
image: "/org/APP_ORG/image/APP_IMAGE"
|
|
355
316
|
```
|
|
356
317
|
|
|
357
|
-
A complete example can be found at [templates/daily-task.yml](templates/daily-task.yml), optimized for Control Plane and
|
|
318
|
+
A complete example can be found at [templates/daily-task.yml](templates/daily-task.yml), optimized for Control Plane and
|
|
319
|
+
suitable for development purposes.
|
|
358
320
|
|
|
359
|
-
You can create the cron workload by adding the template for it to the `.controlplane/templates
|
|
321
|
+
You can create the cron workload by adding the template for it to the `.controlplane/templates/` directory and running
|
|
322
|
+
`cpl apply-template my-template -a my-app`, where `my-template` is the name of the template file (e.g., `my-template.yml`).
|
|
360
323
|
|
|
361
324
|
Then to view the logs of the cron workload, you can run `cpl logs -a my-app -w my-template`.
|
|
362
325
|
|
|
363
|
-
## CLI
|
|
326
|
+
## CLI Commands Reference
|
|
364
327
|
|
|
365
328
|
Click [here](/docs/commands.md) to see the commands.
|
|
366
329
|
|
|
367
|
-
You can also run:
|
|
330
|
+
You can also run the following command:
|
|
368
331
|
|
|
369
332
|
```sh
|
|
370
333
|
cpl --help
|
|
@@ -372,8 +335,6 @@ cpl --help
|
|
|
372
335
|
|
|
373
336
|
## Mapping of Heroku Commands to `cpl` and `cpln`
|
|
374
337
|
|
|
375
|
-
**`[WIP]`**
|
|
376
|
-
|
|
377
338
|
| Heroku Command | `cpl` or `cpln` |
|
|
378
339
|
| -------------------------------------------------------------------------------------------------------------- | ------------------------------- |
|
|
379
340
|
| [heroku ps](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-ps-type-type) | `cpl ps` |
|
|
@@ -388,5 +349,6 @@ cpl --help
|
|
|
388
349
|
|
|
389
350
|
## Examples
|
|
390
351
|
|
|
391
|
-
|
|
392
|
-
|
|
352
|
+
- See the `examples/` and `templates/` directories of this repository.
|
|
353
|
+
- See the `.controlplane/` directory of this live example:
|
|
354
|
+
[react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
data/docs/commands.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
<!-- NOTE: This file is automatically generated by running `script/generate_commands_docs`. Do NOT edit it manually. -->
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Common Options
|
|
4
4
|
|
|
5
5
|
```
|
|
6
6
|
-a XXX, --app XXX app ref on Control Plane (GVC)
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
This `-a` option is used in most of the commands and will pick all other app configurations from the project-specific
|
|
10
10
|
`.controlplane/controlplane.yml` file.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
## Commands
|
|
13
13
|
|
|
14
14
|
### `apply-template`
|
|
15
15
|
|
|
@@ -285,6 +285,18 @@ cpl ps:stop -a $APP_NAME
|
|
|
285
285
|
cpl ps:stop -a $APP_NAME -w $WORKLOAD_NAME
|
|
286
286
|
```
|
|
287
287
|
|
|
288
|
+
### `ps:wait`
|
|
289
|
+
|
|
290
|
+
- Waits for workloads in app to be ready after re-deployment
|
|
291
|
+
|
|
292
|
+
```sh
|
|
293
|
+
# Waits for all workloads in app.
|
|
294
|
+
cpl ps:wait -a $APP_NAME
|
|
295
|
+
|
|
296
|
+
# Waits for a specific workload in app.
|
|
297
|
+
cpl ps:swait -a $APP_NAME -w $WORKLOAD_NAME
|
|
298
|
+
```
|
|
299
|
+
|
|
288
300
|
### `run`
|
|
289
301
|
|
|
290
302
|
- Runs one-off **_interactive_** replicas (analog of `heroku run`)
|