MF-1125 - add provision service docs #33

mteodor · 2020-05-05T11:18:14Z

https://github.com/mainflux/mainflux/issues/1125

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

drasko · 2020-05-05T21:50:52Z

Please remove WIP label

drasko · 2020-05-05T21:51:43Z

docs/provision.md

@@ -0,0 +1,162 @@
+# Provision service
+
+Provision service provides an HTTP API to interact with [Mainflux][mainflux]. 


Tell us first what this service is, then what it provides.

Maybe als explain why we neded this service, the complexity of manual provisioning, what are the manual steps that can be automated, etc...

drasko · 2020-05-05T21:52:52Z

docs/provision.md

+Provision service provides an HTTP API to interact with [Mainflux][mainflux]. 
+Provision service is used to setup initial applications configuration i.e. things, channels, connections and certificates that will be required for the specific use case especially useful for gateway provision.  
+
+For gateways to communicate with [Mainflux][mainflux] configuration is required (mqtt host, thing, channels, certificates...). To get the configuration gateway will send a request to [Bootstrap][bootstrap] service providing `<external_id>` and `<external_key>` in request. To make a request to [Bootstrap][bootstrap] service you can use [Agent][agent] service on a gateway.  


It is unclear what is configuration gateway. Yuo mean unconfigured gateway maybe?

drasko · 2020-05-05T21:54:06Z

docs/provision.md

+
+For gateways to communicate with [Mainflux][mainflux] configuration is required (mqtt host, thing, channels, certificates...). To get the configuration gateway will send a request to [Bootstrap][bootstrap] service providing `<external_id>` and `<external_key>` in request. To make a request to [Bootstrap][bootstrap] service you can use [Agent][agent] service on a gateway.  
+
+To create bootstrap configuration you can use [Bootstrap][bootstrap] or `Provision` service. [Mainflux UI][mfxui] uses [Bootstrap][bootstrap] service for creating gateway configurations.  `Provision` service should provide an easy way of provisioning your gateways i.e creating bootstrap configuration and as many things and channels that your setup requires.  


This is a bit confusing. Why UI uses Bootstrap when there is Provisioning? Maybe this is temporary slution, and UI will move to Provision?

that is something that we need to consider

OK, once you reach the conclusion, please write it here as a note.

drasko · 2020-05-05T21:59:52Z

docs/provision.md

+| MF_PROVISION_BS_AUTO_WHITEIST       | Should thing be auto whitelisted                  | true                           |
+| MF_PROVISION_BS_CONTENT             | Bootstrap service content                         | {}                             |
+
+By default, call to `/mapping` endpoint will create one thing and two channels (`control` and `data`) and connect it. If there is a requirement for different provision layout we can use [config](docker/configs/config.toml) file in addition to environment variables. 


Take care with these links, they will not work in docs repo, as they are relative

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

manuio · 2020-05-06T15:38:24Z

docs/provision.md


-For gateways to communicate with [Mainflux][mainflux] configuration is required (mqtt host, thing, channels, certificates...). To get the configuration gateway will send a request to [Bootstrap][bootstrap] service providing `<external_id>` and `<external_key>` in request. To make a request to [Bootstrap][bootstrap] service you can use [Agent][agent] service on a gateway.  
+For provisioning we can use [Mainflux CLI](./cli.md) creating users and for each node in the edge (eg. gateway) required number of things, channels, connecting them and creating certificates if needed.


I would use https://github.com/mainflux/mainflux/tree/master/cli here

manuio · 2020-05-06T15:39:17Z

docs/provision.md

+
+For gateways to communicate with [Mainflux][mainflux] configuration is required (mqtt host, thing, channels, certificates...). Gateway will send a request to [Bootstrap][bootstrap] service providing `<external_id>` and `<external_key>` in http request to get the configuration. To make a request to [Bootstrap][bootstrap] service you can use [Agent][agent] service on a gateway.  
+
+To create bootstrap configuration you can use [Bootstrap][bootstrap] or `Provision` service. [Mainflux UI][mfxui] uses [Bootstrap][bootstrap] service for creating gateway configurations.  `Provision` service should provide an easy way of provisioning your gateways i.e creating bootstrap configuration and as many things and channels that your setup requires.  


Remove 1 white space before Provision service should provide

manuio · 2020-05-06T15:41:45Z

docs/provision.md

+
+To create bootstrap configuration you can use [Bootstrap][bootstrap] or `Provision` service. [Mainflux UI][mfxui] uses [Bootstrap][bootstrap] service for creating gateway configurations.  `Provision` service should provide an easy way of provisioning your gateways i.e creating bootstrap configuration and as many things and channels that your setup requires.  
+
+Also you may use provision service to create certificates for each thing. Each service running on gateway may require more than one thing and channel for communication. Let's say that you are using services [Agent][agent] and [Export][exp] on a gateway you will need two channels for `Agent` (`data` and `control`) and one for `Export` and one thing. Additionally if you enabled mtls each service will need its own thing and certificate for access to [Mainflux][mainflux]. Your setup could require any number of things and channels this kind of setup we can call `provision layout`.


I'm not convinced about Let's say that in docs.
Also, is this correct? you will need two channels for Agent (data and control) and one for Export and one thing.

manuio · 2020-05-06T15:45:34Z

docs/provision.md

+
+In `config.toml` we can enlist array of things and channels that we want to create and make connections between them which we call provision layout.
+
+Metadata can be whatever suits your needs except that at least one thing needs to have `external_id` (which is populated with value from [request](#example)). Thing that has `external_id` will be used for creating bootstrap configuration which can be fetched with [Agent][agent].


Things Metadata must have an "external_id" field which is populated with...

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

manuio · 2020-05-07T09:43:00Z

docs/provision.md

+It is part of process of setting up IoT application where
+we connect devices on edge with platform in cloud.
+
+For provisioning we can use [Mainflux CLI][cli] for creating users 


Is this return new line after ...creating users ok?

this new line will not be rendered, if that is what you mean

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

dborovcanin · 2020-05-07T10:21:30Z

docs/provision.md

+
+Things Metadata can be whatever suits your needs. 
+Thing that has metadata with `external_id` will have bootstrap configuration created, `external_id` value will be populated with value from [request](#example)). 
+Bootstrap configuration which can be fetched with [Agent][agent].


Bootstrap configuration ~~which~~ can be fetched with [Agent][agent].

dborovcanin · 2020-05-07T10:44:54Z

docs/provision.md

+# Provision service
+
+Provisioning is a process of configuration of an IoT platform in which system operator creates
+and sets-up different entities used in the platform - users, channels and things. 


..., and things.

dborovcanin · 2020-05-07T10:46:09Z

docs/provision.md

+
+Provisioning is a process of configuration of an IoT platform in which system operator creates
+and sets-up different entities used in the platform - users, channels and things. 
+It is part of process of setting up IoT application where


applications (plural)

dborovcanin · 2020-05-07T10:46:34Z

docs/provision.md

+we connect devices on edge with platform in cloud.
+
+For provisioning we can use [Mainflux CLI][cli] for creating users 
+and for each node in the edge (eg. gateway) required number of things, channels, connecting them and creating certificates if needed.


..., and creating certificates...

dborovcanin · 2020-05-07T10:48:04Z

docs/provision.md

+For provisioning we can use [Mainflux CLI][cli] for creating users 
+and for each node in the edge (eg. gateway) required number of things, channels, connecting them and creating certificates if needed.
+
+Provision service is used to setup initial applications configuration once user is created. 


... is used to set up initial application...

dborovcanin · 2020-05-07T10:49:02Z

docs/provision.md

+Provision service is used to setup initial applications configuration once user is created. 
+Provision service creates  things, channels, connections and certificates. 
+Once user is created we can use provision to create setup for edge node 
+in one http request instead of issuing several cli commands. 


Please use capital letters in acronyms: HTTP request, MQTT protocol, CLI (commands), TLS, API... Check for these in the rest of the document, as well.

dborovcanin · 2020-05-07T10:51:51Z

docs/provision.md

+Things Metadata can be whatever suits your needs. 
+Thing that has metadata with `external_id` will have bootstrap configuration created, `external_id` value will be populated with value from [request](#example)). 
+Bootstrap configuration which can be fetched with [Agent][agent].
+For channels metadata `type` is reserved for `control` and `data` which we use with [Agent][agent].


For channels, metadata...

dborovcanin · 2020-05-07T10:52:40Z

docs/provision.md

+Also you may use provision service to create certificates for each thing. 
+Each service running on gateway may require more than one thing and channel for communication. 
+If, for example, you are using services [Agent][agent] and [Export][exp] on a gateway you will need two channels for `Agent` (`data` and `control`) and one thing for `Export`. 
+Additionally if you enabled mtls each service will need its own thing and certificate for access to [Mainflux][mainflux]. 


Additionally, if you enable mTLS...

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

drasko · 2020-05-07T13:40:52Z

docs/platform-management.md

@@ -0,0 +1,324 @@
+Provisioning is a process of configuration of an IoT platform in which system operator creates and sets-up different entities
+used in the platform - users, channels and things.


No need to break line here

drasko · 2020-05-07T13:41:50Z

docs/platform-management.md

+> This endpoint will be depreciated in 0.11.0.  It will be replaced with the bulk endpoint currently found at /things/bulk.
+
+Things are created by executing request `POST /things` with a JSON payload.
+Note that you will also need `user_auth_token` in order to create things


You can move this to the upper line

drasko · 2020-05-07T13:42:00Z

docs/platform-management.md

+## System provisioning
+
+Before proceeding, make sure that you have created a new account, and obtained
+an authorization key.


No need for line break here

drasko · 2020-05-07T13:42:41Z

docs/platform-management.md

+
+### Bulk provisioning channels
+
+Multiple channels can be created by executing a `POST /things/bulk` request with a JSON payload.  The payload should contain a JSON array of the channels to be created.  If there is an error any of the channels, none of the channels will be created.


This line is actually good. Renders nicely, easy to read. Maybe align all to this style.

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

drasko

LGTM

dborovcanin · 2020-05-07T17:02:39Z

docs/platform-management.md

@@ -1,5 +1,4 @@
-Provisioning is a process of configuration of an IoT platform in which system operator creates and sets-up different entities
-used in the platform - users, channels and things.
+Provisioning is a process of configuration of an IoT platform in which system operator creates and sets-up different entities used in the platform - users, channels and things.


, and things.

note that this , is optional

What's this comment about? Putting , before and is gramatically incorrect.

I think it is not

dborovcanin · 2020-05-07T17:07:04Z

docs/platform-management.md

@@ -116,29 +107,25 @@ Content-Length: 1105
 }
 ```

-You can specify `offset` and `limit` parameters in order to fetch specific
-group of things. In that case, your request should look like:
+You can specify `offset` and `limit` parameters in order to fetch specific group of things. In that case, your request should look like:


...to fetch a specific group...

i think that this is ok

dborovcanin · 2020-05-07T17:07:43Z

docs/platform-management.md

 curl -s -S -i --cacert docker/ssl/certs/ca.crt -H "Authorization: <user_auth_token>" https://localhost/things?offset=0&limit=5
 ```

-You can specify `name` and/or `metadata` parameters in order to fetch specific
-group of things. When specifiying metadata you can specify just a part of the metadata json you want to match
+You can specify `name` and/or `metadata` parameters in order to fetch specific group of things. When specifiying metadata you can specify just a part of the metadata json you want to match


specifying, JSON

Also, after match .

dborovcanin · 2020-05-07T17:09:44Z

docs/provision.md

+
+For provisioning we can use [Mainflux CLI][cli] for creating users and for each node in the edge (eg. gateway) required number of things, channels, connecting them, and creating certificates if needed.
+
+Provision service is used to setup initial application configuration once user is created. Provision service creates  things, channels, connections, and certificates. Once user is created we can use provision to create setup for edge node in one HTTP request instead of issuing several CLI commands. 


Provision service is used to set up...
...to create a setup...

dborovcanin · 2020-05-07T17:10:31Z

docs/provision.md

+
+To create bootstrap configuration you can use [Bootstrap][bootstrap] or `Provision` service. [Mainflux UI][mfxui] uses [Bootstrap][bootstrap] service for creating gateway configurations. `Provision` service should provide an easy way of provisioning your gateways i.e creating bootstrap configuration and as many things and channels that your setup requires.  
+
+Also you may use provision service to create certificates for each thing. Each service running on gateway may require more than one thing and channel for communication. 


Also, you...

dborovcanin · 2020-05-07T17:11:41Z

docs/provision.md

+
+Configuration can be specified in [config.toml][conftoml]. Config file can specify all the settings that environment variables can configure and in addition `/mapping` endpoint provision layout can be configured.
+
+In `config.toml` we can enlist array of things and channels that we want to create and make connections between them which we call provision layout.


... enlist an array...

dborovcanin · 2020-05-07T17:12:17Z

docs/provision.md

+In order to create necessary entities provision service needs to authenticate against Mainflux. 
+To provide authentication credentials to the provision service you can pass it in as an environment variable or in a config file as Mainflux user and password or as API token (that can be issued on `/users` or `/keys` endpoint of [authn][authn]. 
+
+Additionally users or API token can be passed in Authorization header, this authentication takes precedence over others.


Additionally, ...

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

manuio

LGTM

* add provision service docs Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * update docs Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * add some desc on prov Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * fix layout, and minor text change Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * fix links Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * add section, text change Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * lector fix Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * fix link Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * renam file Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * reformat and fix typos Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * fix name Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * renam file Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * update style Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com> * small changes Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

add provision service docs

7cf1c11

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

mteodor added the WIP label May 5, 2020

mteodor requested a review from a team as a code owner May 5, 2020 11:18

drasko requested changes May 5, 2020

View reviewed changes

update docs

81672b4

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

mteodor removed the WIP label May 6, 2020

add some desc on prov

e1de123

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

manuio suggested changes May 6, 2020

View reviewed changes

fix layout, and minor text change

bb9dc36

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

mteodor added the documentation Improvements or additions to documentation label May 7, 2020

mteodor added 2 commits May 7, 2020 08:30

fix links

73d0f7b

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

add section, text change

37d938a

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

manuio suggested changes May 7, 2020

View reviewed changes

mteodor added 2 commits May 7, 2020 11:44

lector fix

a1a9247

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

fix link

effcb78

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

dborovcanin requested changes May 7, 2020

View reviewed changes

mteodor added 3 commits May 7, 2020 13:57

renam file

d0edde4

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

reformat and fix typos

4343786

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

fix name

b2c2af0

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

drasko requested changes May 7, 2020

View reviewed changes

mteodor added 2 commits May 7, 2020 15:50

renam file

0d4968b

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

update style

dde3566

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

drasko previously approved these changes May 7, 2020

View reviewed changes

blokovi previously approved these changes May 7, 2020

View reviewed changes

dborovcanin requested changes May 7, 2020

View reviewed changes

small changes

5836448

Signed-off-by: Mirko Teodorovic <mirko.teodorovic@gmail.com>

mteodor dismissed stale reviews from blokovi and drasko via 5836448 May 7, 2020 21:01

manuio approved these changes May 7, 2020

View reviewed changes

dborovcanin approved these changes May 7, 2020

View reviewed changes

dborovcanin merged commit 47fd64e into absmach:master May 7, 2020

mteodor mentioned this pull request May 8, 2020

Document Provision service absmach/magistrala#1125

Closed

		@@ -0,0 +1,162 @@
		# Provision service

		Provision service provides an HTTP API to interact with [Mainflux][mainflux].


		For gateways to communicate with [Mainflux][mainflux] configuration is required (mqtt host, thing, channels, certificates...). To get the configuration gateway will send a request to [Bootstrap][bootstrap] service providing `<external_id>` and `<external_key>` in request. To make a request to [Bootstrap][bootstrap] service you can use [Agent][agent] service on a gateway.

		To create bootstrap configuration you can use [Bootstrap][bootstrap] or `Provision` service. [Mainflux UI][mfxui] uses [Bootstrap][bootstrap] service for creating gateway configurations. `Provision` service should provide an easy way of provisioning your gateways i.e creating bootstrap configuration and as many things and channels that your setup requires.


		For gateways to communicate with [Mainflux][mainflux] configuration is required (mqtt host, thing, channels, certificates...). To get the configuration gateway will send a request to [Bootstrap][bootstrap] service providing `<external_id>` and `<external_key>` in request. To make a request to [Bootstrap][bootstrap] service you can use [Agent][agent] service on a gateway.
		For provisioning we can use [Mainflux CLI](./cli.md) creating users and for each node in the edge (eg. gateway) required number of things, channels, connecting them and creating certificates if needed.


		To create bootstrap configuration you can use [Bootstrap][bootstrap] or `Provision` service. [Mainflux UI][mfxui] uses [Bootstrap][bootstrap] service for creating gateway configurations. `Provision` service should provide an easy way of provisioning your gateways i.e creating bootstrap configuration and as many things and channels that your setup requires.

		Also you may use provision service to create certificates for each thing. Each service running on gateway may require more than one thing and channel for communication. Let's say that you are using services [Agent][agent] and [Export][exp] on a gateway you will need two channels for `Agent` (`data` and `control`) and one for `Export` and one thing. Additionally if you enabled mtls each service will need its own thing and certificate for access to [Mainflux][mainflux]. Your setup could require any number of things and channels this kind of setup we can call `provision layout`.


		In `config.toml` we can enlist array of things and channels that we want to create and make connections between them which we call provision layout.

		Metadata can be whatever suits your needs except that at least one thing needs to have `external_id` (which is populated with value from [request](#example)). Thing that has `external_id` will be used for creating bootstrap configuration which can be fetched with [Agent][agent].

		@@ -0,0 +1,324 @@
		Provisioning is a process of configuration of an IoT platform in which system operator creates and sets-up different entities
		used in the platform - users, channels and things.


		### Bulk provisioning channels

		Multiple channels can be created by executing a `POST /things/bulk` request with a JSON payload. The payload should contain a JSON array of the channels to be created. If there is an error any of the channels, none of the channels will be created.


		For provisioning we can use [Mainflux CLI][cli] for creating users and for each node in the edge (eg. gateway) required number of things, channels, connecting them, and creating certificates if needed.

		Provision service is used to setup initial application configuration once user is created. Provision service creates things, channels, connections, and certificates. Once user is created we can use provision to create setup for edge node in one HTTP request instead of issuing several CLI commands.


		Configuration can be specified in [config.toml][conftoml]. Config file can specify all the settings that environment variables can configure and in addition `/mapping` endpoint provision layout can be configured.

		In `config.toml` we can enlist array of things and channels that we want to create and make connections between them which we call provision layout.

MF-1125 - add provision service docs #33

MF-1125 - add provision service docs #33

Conversation

mteodor commented May 5, 2020

drasko commented May 5, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dborovcanin May 7, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dborovcanin May 7, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dborovcanin May 7, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

drasko left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

manuio left a comment

Choose a reason for hiding this comment

dborovcanin May 7, 2020 •

edited

Loading

dborovcanin May 7, 2020 •

edited

Loading

dborovcanin May 7, 2020 •

edited

Loading