7.9 KiB
Configure environments from CLI
Blueprint for this specification:
https://blueprints.launchpad.net/python-muranoclient/+spec/env-configuration-from-cli
Currently there is no way to configure and/or deploy a murano environment from the command line. This specification describes how this issue can be addressed and what steps have to be taken in order to implement this abilities.
Problem description
Currently the only possible way to deploy a murano environment is through interaction with horizon. CLI client currently lacks commands to add apps to environment or deploy an environment. This makes murano useless without horizon and murano-dashboard. It also means, that scripting and/or automating deployment of murano apps/environments is currently problematic to say the least.
Proposed change
This spec proposes to add several new CLI commands and modify existing to allow user to add apps to the env, configure it and send it to deploy.
Command environment-create
currently only supports
adding the name of the environment, while the api call supports setting
aditional params, such as defaultNetworks.
environment-create
should be updated to allow setting
custom keys to environment model.
environment-edit
command should perform all the editing
(adding, deleting, modifying of existing apps) This command should be
non-interctive, adding an interactive mode is a good idea as of itself,
but is out of scope of this spec.
environment-edit
would use jsonpatch format for input
(as described by RFC 6902). This is a well known and powerfull
instrument to manipulate json, and object model is currently stored in
json. This would allow easy addition, modification and deletion of apps.
Editing of environment attributes is not allowed by API, so it's beyond
the scope of this spec.
During command execution, env configuration parameters should be read
from stdin or a file. Supporting stdin as input source means it should
be possible to issue a command like
murano environment-edit env_id < app_patch.json
An example app_patch.json
might look like:
[
{ "op": "add", "path": "/services/-",
"value":
{'?':
{'id': '2fc3005d-b4f8-420d-9e15-f961b41f49ee',
'type': 'io.murano.apps.App1'
},
'instance':
{'?': {'id': '53366263-04e9-49d1-829d-50e27158749c',
'type': 'io.murano.resources.LinuxMuranoInstance'},
'assignFloatingIp': True,
'availabilityZone': 'nova',
'flavor': 'm1.medium',
'image': 'afc1aa61-f623-4c66-bbd8-5359261c5272',
'name': 'ilphvibwqyu6h1' },
'name': 'App1'
}
},
]
All operations would only apply to services field, so the /services/ part of the path can be ommitted.
- note::
-
This means, that a user has to generate unique ids. This can be a difficult task and may hinder scripting capabilities. We might think of a way to mitigate this issue, by introducing a way to generate ids. This can be done by introducing an optional parameter
--id-format
. It would accept a template for strings to be replaced with generated ids. For example:--id-format=##id##
would replace all occurrences of ##id##-1 with fist generated id, all occurrences of ##id##-2 with second generated id and all occurrences of ##id## with a unique id. uuids should be used for id generation.
Command should perform validation of its input. This can be done
using MuranoPL classes and property contracts. If an error happens
during non-interactive mode (for example validation fails for some
field) murano
should return a non-zero status, to
facilitate scipting and error-detecting.
Command environment-edit
should support optional
--session
parameter, that allows user to specify a session
for editing an environment. It should also warn user in case more than
one session is open. If the session parameter is omitted: last open
session for given environment is used. If there are no open sessions — a
new session would be opened.
- note::
-
This means that to deploy a simple application one has to know jsonpatch syntax. We might think about optional syntax sugar commands, that would allow adding a single app to the environment. These would use predefined jsonpatch patch documents and would accept only value to be added to /Objects/services/- path.
We should implement session controlling commands during implementation of this spec, for example:
session-list
Show list of open sessions for a given environment.session-show
Show details of currently configured session..session-delete
Discard an open session for a given environment.
In case an error occurs during environment deployment this would allow to rollback the changes to the previous version of environment. This should also allow to handle cases, when a single environment is edited simultaneously by different users.
environment-action
command should be implemented to
allow performing actions against an environment. One example of actions
is a deploy action, so murano environment-action deploy
should deploy the environment.
Alternatives
Alternatively we can implement an interactive mode, that would mimic current dashboard behaviour. This would not allow scripting, but would allow us to build a more user-friendly CLI interface. The dowside is that current UI definitions are scheduled to be changed and would most likely be replaced in the forseable future. This means, that most of the work would go to waste.
Data model impact
None
REST API impact
None, CLI should reuse API calls, already used by dashboard
Versioning impact
Since we're adding functionality — None
Other end user impact
None
Deployer impact
It is possible that implementation of this spec would require setting and reading intermediate environment variables to work correctly with sessions, during app addition, env deployment.
Overall deployment of murano would not be affected.
Developer impact
None
Murano-dashboard / Horizon impact
None
Implementation
Assignee(s)
- Primary assignee:
-
<kzaitsev>
Work Items
environment-edit
command (should create session, check permissions, add patch resulting model into ).- Input validation for
envieonment-edit
(request packages from API, check ID uniqueness, check input field adequacy). - (optional)
--format-id
option support - (optional) syntax sugar command, that would allow easy addition of a package to an environment.
- Session controlling commands.
environment-action
command.- Shell unit tests.
- Integration tests.
Dependencies
None
Testing
We shall need Unit tests for new commands introduced.
Also, since this change introduces a way to deploy an env from CLI. This means that integration tests for murano client should be implemented. A typical test should upload and app, configure a simple environment with 1-2 apps and set some custom parameters, like access port and optionally deploy the env in question. This tests should probably take place in murano-ci.
Documentation Impact
New python-muranoclient commands would have to get a proper documentation. It's also possible, that we would want to document the whole process of deploying an app or scripting of such a deployment as a separate article in murano documentattion.