Commit d372ab95 authored by JeremJR's avatar JeremJR Committed by Agustin Larreinegabe

Feat/add bconf management bcd 296 (#94)

* add livingapp_manage_configuration.md [BCD-296]
* update cli [BCD-296]
* hide bcd in the toc
* fix typo
* update cli wording for bconf management
* Add merge-conf information
parent b518f866
......@@ -73,7 +73,7 @@ This section describes the comprehensive usage information for the `bcd` command
You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND] --help` - where SUBCOMMAND is in `[livingapp, stack]` - from the command line.
<div class="section" id="bcd">
<span class="h2">bcd</span>
<span class="h3">bcd</span>
<p>Bonita Continuous Delivery CLI.</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd <span class="o">[</span>OPTIONS<span class="o">]</span> COMMAND <span class="o">[</span>ARGS<span class="o">]</span>...
</pre></div>
......@@ -122,7 +122,7 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
</dd></dl>
<div class="section" id="bcd-livingapp">
<span class="h3">livingapp</span>
<h4>livingapp</h4>
<p>Manage Bonita Living Application</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd livingapp <span class="o">[</span>OPTIONS<span class="o">]</span> COMMAND1 <span class="o">[</span>ARGS<span class="o">]</span>... <span class="o">[</span>COMMAND2 <span class="o">[</span>ARGS<span class="o">]</span>...<span class="o">]</span>...
</pre></div>
......@@ -135,7 +135,7 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
</dd></dl>
<div class="section" id="bcd-livingapp-build">
<span class="h4">build</span>
<h5>build</h5>
<p>Build Bonita Living Application</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd livingapp build <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
......@@ -144,7 +144,7 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
<dl class="option">
<dt id="cmdoption-bcd-livingapp-build-p">
<code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--path</code><code class="descclassname"> &lt;path&gt;</code></dt>
<dd><p>Bonita Living Application workspace path</p>
<dd><p>Bonita Living Application repository path</p>
</dd></dl>
<dl class="option">
......@@ -167,7 +167,7 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
</div>
<div class="section" id="bcd-livingapp-deploy">
<span class="h4">deploy</span>
<h5>deploy</h5>
<p>Deploy Bonita Living Application</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd livingapp deploy <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
......@@ -176,7 +176,13 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
<dl class="option">
<dt id="cmdoption-bcd-livingapp-deploy-p">
<code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--path</code><code class="descclassname"> &lt;path&gt;</code></dt>
<dd><p>Bonita Living Application file path</p>
<dd><p>Bonita Living Application archive or directory path</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-deploy-c">
<code class="descname">-c</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--configuration-path</code><code class="descclassname"> &lt;configuration_path&gt;</code></dt>
<dd><p>Bonita configuration (.bconf) archive path</p>
</dd></dl>
<dl class="option">
......@@ -191,10 +197,74 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
<dd><p>Show this help message</p>
</dd></dl>
</div>
<div class="section" id="bcd-livingapp-extract-conf">
<h5>extract-conf</h5>
<p>Extract parameters from a Bonita configuration archive (.bconf)</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd livingapp extract-conf <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-extract-conf-p">
<code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--path</code><code class="descclassname"> &lt;path&gt;</code></dt>
<dd><p>Bonita configuration (.bconf) archive path</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-extract-conf-without-value">
<code class="descname">--without-value</code><code class="descclassname"></code></dt>
<dd><p>Only extract parameters which do not have a value</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-extract-conf-o">
<code class="descname">-o</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--output</code><code class="descclassname"> &lt;output&gt;</code></dt>
<dd><p>Output file</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-extract-conf-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
</div>
<div class="section" id="bcd-livingapp-merge-conf">
<h5>merge-conf</h5>
<p>Merge parameters into a Bonita configuration archive</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd livingapp merge-conf <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
<p class="rubric">Options</p>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-merge-conf-p">
<code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--path</code><code class="descclassname"> &lt;path&gt;</code></dt>
<dd><p>Bonita configuration (.bconf) archive path</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-merge-conf-i">
<code class="descname">-i</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--input</code><code class="descclassname"> &lt;input&gt;</code></dt>
<dd><p>Input parameter file</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-merge-conf-o">
<code class="descname">-o</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--output</code><code class="descclassname"> &lt;output&gt;</code></dt>
<dd><p>Output file</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-bcd-livingapp-merge-conf-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code></dt>
<dd><p>Show this help message</p>
</dd></dl>
</div>
</div>
<div class="section" id="bcd-stack">
<span class="h3">stack</span>
<h4>stack</h4>
<p>Manage Bonita stack (infrastructure)</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack <span class="o">[</span>OPTIONS<span class="o">]</span> COMMAND1 <span class="o">[</span>ARGS<span class="o">]</span>... <span class="o">[</span>COMMAND2 <span class="o">[</span>ARGS<span class="o">]</span>...<span class="o">]</span>...
</pre></div>
......@@ -207,8 +277,8 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
</dd></dl>
<div class="section" id="bcd-stack-create">
<span class="h4">create</span>
<p>Create AWS instances</p>
<h5>create</h5>
<p>Create infra machines</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack create <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
......@@ -227,7 +297,7 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
</div>
<div class="section" id="bcd-stack-deploy">
<span class="h4">deploy</span>
<h5>deploy</h5>
<p>Deploy Bonita stack (creates Docker containers)</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack deploy <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
......@@ -241,8 +311,8 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
</div>
<div class="section" id="bcd-stack-destroy">
<span class="h4">destroy</span>
<p>Destroy AWS machines (EC2 instances)</p>
<h5>destroy</h5>
<p>Destroy infra machines</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack destroy <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
</div>
......@@ -261,7 +331,7 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
</div>
<div class="section" id="bcd-stack-status">
<span class="h4">status</span>
<h5>status</h5>
<p>Show the platform status</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack status <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
......@@ -275,7 +345,7 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
</div>
<div class="section" id="bcd-stack-undeploy">
<span class="h4">undeploy</span>
<h5>undeploy</h5>
<p>Undeploy Bonita stack (removes Docker containers)</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd stack undeploy <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
......@@ -290,7 +360,7 @@ You can also see this information by running `bcd --help` and `bcd [SUBCOMMAND]
</div>
</div>
<div class="section" id="bcd-version">
<span class="h3">version</span>
<h4>version</h4>
<p>Show BCD version information</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>bcd version <span class="o">[</span>OPTIONS<span class="o">]</span>
</pre></div>
......
# How to manage Living Apps Configuration
This tutorial describes how to configure your Bonita Living Application from the command line using BCD.
## How it works
Since BCD 3.0.0, if you build a living Application you will get separatly:
- a zip file which contains binaries
- a bconf file which contains the configuration for the target [environment](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/environments) (Local by default)
Here is an example of a build result:
```
bonita-vacation-management-example
├── target
   └── bonita-vacation-management-example-Qualification-20181003140237.zip
   └── bonita-vacation-management-example-Qualification-20181003140237.bconf
```
It's possible to extract the configuration to check it and also override (merge) some parameters if needed.
### Extract configuration
You can extract the configuration if you want to check it or modify it
```bash
bcd -y -s scenarios/euwest1_performance.yml livingapp extract-conf \
-p bonita-vacation-management-example/target/bonita-vacation-management-example-Qualification-20181003140237.bconf \
-o scenarios/euwest1_performance_Qualification.yml
```
The configuration looks like this :
```yml
---
processes:
- name: "Modify Pending Vacation Request"
version: "1.4.1"
parameters:
- name: "calendarApplicationName"
value: "Bonitasoft-NewVacationRequest/1.4.0"
type: "String"
- name: "calendarCalendarId"
value: "mydomain.com_4gc5656x7f57cfsrejgb@group.calendar.google.com"
type: "String"
```
As it may contain sensitive data, it's recommended to encrypt your configuration using [vault](how_to_use_bcd_with_data_encrypted):
```
ansible-vault encrypt scenarios/euwest1_performance_Qualification.yml
New Vault password:
Confirm New Vault password:
Encryption successful
```
You can also just check if there are parameters that have no value for this environment:
```bash
bcd -y -s scenarios/euwest1_performance.yml livingapp extract-conf --without-value \
-p bonita-vacation-management-example/target/bonita-vacation-management-example-Qualification-20181003140237.bconf \
-o scenarios/euwest1_performance_Qualification_missing_parameters.yml
```
Notes :
- If you omit to specify -o, the name of the output file by default is __parameters.yml__ and it will be created in the same directory of the original ***bconf*** file.
- If all parameters are set, no file will be created.
### Merge configuration
You may want to complete or override some parameter values coming from your Living App repository, to do that you can modify the output file of the __extract-conf__ command and ***merge*** with your ***bconf*** file.
```bash
bcd -y -s scenarios/euwest1_performance.yml livingapp merge-conf \
-p bonita-vacation-management-example/target/bonita-vacation-management-example-Qualification-20181003140237.bconf \
-i scenarios/euwest1_performance_Qualification.yml \
-o /tmp/bonita-vacation-management-example-Qualification-20181003140237-modified.bconf
```
Note : the content of bconf file is not encrypted so it's recommended to clean them after usage.
#### Override parameters with the same name
You may have the same parameter name in more than one processes and you want to override them in all processes, to do that you can create an ***yml*** file as shown:
```yml
---
global_parameters:
- name: "ParameterNameInAllProcesses"
value: "SameValueInAllProcess"
type: "String"
```
::: info
Important:
A specific parameter setting has priority over a global parameter configuration.
:::
**Example**:
Let assume that these processes __P1, P2, P3__ have all these three paremeters: ***calendarApplicationName***, ***emailNotificationSender***, ***emailServerUseSSL***.
```yml
---
processes:
- name: "P1"
version: "1.4.1"
parameters:
- name: "calendarApplicationName"
value: "Bonitasoft-NewVacationRequest/1.4.0"
type: "String"
- name: "emailNotificationSender"
value: "cancelvacationconfirmation@mail.com"
type: "String"
- name: "P2"
version: "1.4.1"
parameters:
- name: "calendarApplicationName"
value: "Bonitasoft-NewVacationRequest/1.4.0"
type: "String"
- name: "P3"
version: "1.4.1"
parameters:
- name: "calendarApplicationName"
value: "Bonitasoft-NewVacationRequest/1.4.0"
type: "String"
global_parameters:
- name: "emailNotificationSender"
value: "vacation-notification@mail.com"
type: "String"
- name: "emailServerUseSSL"
value: true
type: "Boolean"
```
The result of __merge-conf__ will be:
* The value of ***emailServerUseSSL*** in __global_parameters__ will override __P1, P2, P3__.
* The value of ***emailNotificationSender*** in __global_parameters__ will override only __P2 and P3__ because the setting of ***emailNotificationSender*** in __P1__ has priority.
* The value of ***emailNotificationSender*** in __P1__ will override only the parameter of __P1__.
......@@ -18,6 +18,7 @@
* [Enabling remote monitoring with JMX](how_to_enable_remote_monitoring_jmx.md)
* [Manage Bonita Living Applications](_manage_living_application.md)
* [Build a Living App repository](livingapp_build.md)
* [Manage Living App configuration](livingapp_manage_configuration.md)
* [Deploy Living App artifacts](livingapp_deploy.md)
* [Build and deploy (Best Practices)](livingapp_build_and_deploy.md)
* [Use BCD with sensitive data encrypted](how_to_use_bcd_with_data_encrypted.md)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment