cpl 1.0.0 → 1.0.2
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/.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`)
|