1 | # Kumori Platform CLI
|
2 |
|
3 | This is a command line interface to boost the process of developing elements for Kumori Platform.
|
4 |
|
5 | ## Description
|
6 |
|
7 | This application can be used to boost the process of developing deployments services for Kumori Platform. This application helps with:
|
8 |
|
9 | * Managing a workspace creating initial versions of elements under development by using templates.
|
10 | * Interacting with Kumori Platform.
|
11 |
|
12 | More information can be found in (Kumori PaaS Documentation)[https://github.com/kumori-systems/documentation].
|
13 |
|
14 | ## Table of Contents
|
15 |
|
16 | * [Installation](#installation)
|
17 | * [The Kumori Platform Service Model](#the-kumori-platform-service-model)
|
18 | * [Usage](#usage)
|
19 | * [`init`](#init-command)
|
20 | * [`component`](#component-command)
|
21 | * [`deployment`](#deployment-command)
|
22 | * [`project`](#project-command)
|
23 | * [`resource`](#resource-command)
|
24 | * [`runtime`](#runtime-command)
|
25 | * [`service`](#service-command)
|
26 | * [`set`](#set-command)
|
27 | * [`stamp`](#stamp-command)
|
28 | * [License](#license)
|
29 |
|
30 | ## Installation
|
31 |
|
32 | Install it as a npm package
|
33 |
|
34 | npm install -g @kumori/cli
|
35 |
|
36 | ## The Kumori Platform Service Model
|
37 |
|
38 | The services deployed in Kumori Platform must follow a very specific service model known as the `Kumori Platform Service Model`. This model is based in the following main concepts:
|
39 |
|
40 | * Component: it is a runnable piece of code which must implement a given API. A component can interact with other components by using channels. A component can also have some configuration parameters and require some resources to work (CPU, RAM, persitent volumes, ...)
|
41 | * Service: defines a specific topology of components connecting their channels.
|
42 | * Deployment: it is an instance of a service and it is composed by several instance of each of its components. The number of instances might variate in time.
|
43 | * Stamp: is an instance of the Kumori Platform. Only one stamp is considered THE Kumori Platform. However, in some cases specific stamps can be created by the Kumori team for specific purposes.
|
44 |
|
45 | ## Usage
|
46 |
|
47 | To use `kumori` CLI first create an initial workspace
|
48 |
|
49 | ```
|
50 | $ mkdir workspace
|
51 | $ cd workspace
|
52 | $ kumori init
|
53 | create kumoriConfig.json
|
54 | create builts/README.md
|
55 | create components/README.md
|
56 | create dependencies/README.md
|
57 | create deployments/README.md
|
58 | create resources/README.md
|
59 | create runtimes/README.md
|
60 | create services/README.md
|
61 | ```
|
62 | The workspace structure is described in the [init command](#init-command) section.
|
63 |
|
64 | Once created, you can start developing services. This application currently supports the following commands:
|
65 |
|
66 | ```
|
67 | Usage: kumori [options] [command]
|
68 |
|
69 | Options:
|
70 |
|
71 | -V, --version output the version number
|
72 | -h, --help output usage information
|
73 |
|
74 | Commands:
|
75 |
|
76 | component Manages components
|
77 | deployment Manages deployments
|
78 | project Manages projects
|
79 | resource Manages resources
|
80 | runtime Manages runtimes
|
81 | service Manages services
|
82 | set Manages workspace configuration parameters
|
83 | stamp Manages stamps
|
84 | init [options] Populates the current folder with the worspace folders structure
|
85 | help [cmd] display help for [cmd]
|
86 | ```
|
87 |
|
88 | Each one of those commands have several subcommands.
|
89 |
|
90 | ### Init Command
|
91 |
|
92 | Created a brand new workspace. A workspace is a folder with the following structure:
|
93 |
|
94 | ```
|
95 | .
|
96 | ├── builts
|
97 | ├── components
|
98 | ├── dependencies
|
99 | ├── deployments
|
100 | ├── kumoriConfig.json
|
101 | ├── resources
|
102 | ├── runtimes
|
103 | ├── services
|
104 | └── tests
|
105 | ```
|
106 |
|
107 | Supports the following subcommands:
|
108 |
|
109 | ~~~
|
110 | Usage: init [options]
|
111 |
|
112 | Populates the current folder with the worspace folders structure
|
113 |
|
114 | Options:
|
115 |
|
116 | -t, --template <template> The workspace template (default: @kumori/workspace)
|
117 | -h, --help output usage information
|
118 | ~~~
|
119 |
|
120 |
|
121 | The `kumoriConfig.json` file contains the configuration used in this workspace. The `build` folder can be used to store bundles with prepacked elements. The `components`, `services`, `deployments`, `projects`, `resources` and `runtimes` store the different elements under development.
|
122 |
|
123 | ### Component Command
|
124 |
|
125 | Supports the following subcommands:
|
126 |
|
127 | ```
|
128 | Usage: kumori component [options] [command]
|
129 |
|
130 | Options:
|
131 |
|
132 | -h, --help output usage information
|
133 |
|
134 | Commands:
|
135 |
|
136 | add [options] <name> Adds a new component to the workspace
|
137 | build [options] <name> Creates a distributable version of the component
|
138 | register [options] <name> Registers a component in a stamp
|
139 | remove [options] <name> Removes an existing component from the workspace
|
140 | unregister [options] <name> Unregisters a component from a stamp
|
141 | ```
|
142 |
|
143 | With them, components can be added to the workspace, build distributable versions of them, register them to Kumori Platform (the official one or any other one), remove them to the workspace and unregister one version of that component in Kumori Platform.
|
144 |
|
145 | ### Deployment Command
|
146 |
|
147 | Supports the following subcommands:
|
148 |
|
149 | ```
|
150 | Usage: kumori deployment [options] [command]
|
151 |
|
152 | Options:
|
153 |
|
154 | -h, --help output usage information
|
155 |
|
156 | Commands:
|
157 |
|
158 | add [options] <name> <service> Adds a new deployment configuration to the workspace
|
159 | update [options] <name> Updates a deployment configuration in the workspace
|
160 | deploy [options] <name> Creates a new service in the target stamp
|
161 | ps [options] Lists the services currently running in the target stamp
|
162 | remove <name> Removes an existing deployment from the workspace
|
163 | scale [options] <urn> <role> <instances> Unregisters a component from a stamp
|
164 | undeploy [options] <urn> Undeploys a service from the target stamp
|
165 | ```
|
166 |
|
167 | With them, a developer can define new configurations for the deployments in the workspace, use them to create new services in Kumori Platform, list the current services hosted in Kumori Platform, remove a configuration from the workspace, scale a component of a given deployment or undeploy a hosted service.
|
168 |
|
169 | ### Project Command
|
170 |
|
171 | Supports the following subcommand:
|
172 |
|
173 | ```
|
174 | Usage: kumori-project [options] [command]
|
175 |
|
176 | Options:
|
177 |
|
178 | -h, --help output usage information
|
179 |
|
180 | Commands:
|
181 |
|
182 | add [options] <name> Populates the workspace with a project elements. A project might include components, resoureces, services, runtimes and deployments
|
183 | ```
|
184 |
|
185 | This command is used to populate your workspace with a set of elements. This is typically used to create in one shot all elements you need to create a new service, including all its components and so on.
|
186 |
|
187 | ### Resource Command
|
188 |
|
189 | Supports the following subcommand:
|
190 |
|
191 | ```
|
192 | Usage: kumori resource [options] [command]
|
193 |
|
194 | Options:
|
195 |
|
196 | -h, --help output usage information
|
197 |
|
198 | Commands:
|
199 |
|
200 | add [options] <name> Adds a new resource to the workspace
|
201 | register [options] <name> Registers a resource in a stamp
|
202 | remove [options] <name> Removes an existing resource from the workspace
|
203 | unregister [options] <name> Unregisters a resource from a stamp
|
204 | ```
|
205 |
|
206 | In this case, a resource refers to platform elements that can be registered and assigned to deployments (like volumes, certificates and so on). The subcommands for this commands can be used to create define new resources, create them un a platform and remove previously created and registered resources.
|
207 |
|
208 | ### Runtime Command
|
209 |
|
210 | A runtime is the environment used to execute components instances. In essence, a runtime is a Docker image. Developers can create new runtimes from scratch but it is strongly recommended to extend one of the existing runtimes:
|
211 |
|
212 | * `eslap://eslap.cloud/runtime/native/X_Y_Z`: enviroment used to executed components implemented in Node.jS. `XYZ` represent the major, minor and patch version of the runtime. Each version might support different versions of the component API and include a different version of NodeJS.
|
213 | * `eslap://eslap.cloud/runtime/java/X_Y_Z`: enviroment used to executed components implemented in Java. `XYZ` represent the major, minor and patch version of the runtime.
|
214 |
|
215 | Usually, users will not create custom runtimes and use directly the native one. However, the command line application can help in the process of creating new runtimes with the following subcommands:
|
216 |
|
217 | ```
|
218 | Usage: kumori runtime [options] [command]
|
219 |
|
220 | Options:
|
221 |
|
222 | -h, --help output usage information
|
223 |
|
224 | Commands:
|
225 |
|
226 | add [options] <name> Adds a new runtime to the workspace
|
227 | build [options] <name> Creates a distributable version of the runtime
|
228 | register [options] <name> Registers a runtime in a stamp
|
229 | remove [options] <name> Removes an existing runtime from the workspace
|
230 | unregister [options] <name> Unregisters a runtime from a stamp
|
231 | ```
|
232 |
|
233 | The subcommands `add` and `remove` are used to create and remove custom runtime configuration (Dockerfile and manifest) in the workspace.
|
234 |
|
235 | The `build` subcommand is used to create the Docker image. We strongly recommend to use this subcommand instead of the plain `docker build` since this subcommand will create a delta image containing only the docker layers on the top of the parent native image used. That might reduce a lot the weight of the resulting image.
|
236 |
|
237 | Finally, `register` and `unregister` subcommands are used to upload or remove images from the Kumori Platform.
|
238 |
|
239 | ### Service Command
|
240 |
|
241 | This command is used to manage the services in the workspace and includes the following subcommands:
|
242 |
|
243 | ````
|
244 | Usage: kumori service [options] [command]
|
245 |
|
246 | Options:
|
247 |
|
248 | -h, --help output usage information
|
249 |
|
250 | Commands:
|
251 |
|
252 | add [options] <name> Adds a new service to the workspace
|
253 | register [options] <name> Registers a service in a stamp
|
254 | remove [options] <name> Removes an existing service from the workspace
|
255 | unregister [options] <name> Unregisters a service from a stamp
|
256 | ````
|
257 |
|
258 | The subcommands `add` and `remove` are used to define new services in the workspace and remove them. The subcommands `register` and `unregister` are used to upload and remove the services from the Kumori Platform.
|
259 |
|
260 | ### Set Command
|
261 |
|
262 | This one is used mainly to change the default values used when adding new elements to the workspace.
|
263 |
|
264 | ```
|
265 | Usage: kumori set [options] [command]
|
266 |
|
267 | Options:
|
268 |
|
269 | -h, --help output usage information
|
270 |
|
271 | Commands:
|
272 |
|
273 | domain <domain> Changes the default domain used in the workspace elements
|
274 | ```
|
275 |
|
276 | Currently, only the default domain can be set, usually to the developer's company domain. The domain is used to name the elements.
|
277 |
|
278 | ### Stamp Command
|
279 |
|
280 | The stamp command register new platforms in the command line client. By default, the client comes with Local Stamp and the official kumori platform registered.
|
281 |
|
282 | ```
|
283 | Usage: kumori stamp [options] [command]
|
284 |
|
285 | Options:
|
286 |
|
287 | -h, --help output usage information
|
288 |
|
289 | Commands:
|
290 |
|
291 | add [options] <name> <admission> Adds a new stamp to the workspace
|
292 | list [options] Shows detailed information about the stamps registered in this workspace
|
293 | remove <name> Removes a stamp
|
294 | update [options] <name> Updates the information of a previously registered stamp
|
295 | use <name> Sets a stamp as the default stamp
|
296 | ```
|
297 |
|
298 | For each stamp the following information must be provided:
|
299 |
|
300 | * The stamp nickname. This is used to refere to this stamp in other commands.
|
301 | * The stamp admission URL. This is used by the command line application to interact with the Kumori Platform.
|
302 | * The stamp authentication token. This token can be picked up from the platform dashboard. Recall that tokens expire.
|
303 |
|
304 | So, taken that into account, with the `add` subcommand a new platform can be registered. The `update` subcommand can be used to change the configuration of a previously registered stamp. The `remove` subcommand deletes a previously registered Kumori Platform instance. The `use` subcommand sets the Kumori Platform used by default. Finally, registered stamps can be listed by using the `list` subcommand.
|
305 |
|
306 | ## License
|
307 |
|
308 | MIT © Kumori Systems
|
309 |
|
\ | No newline at end of file |