-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Documentation] Release v5.0.0 (#2257)
* Add AWS documentation page and move Azure to dedicated page (#1961) * add AWS and Azure tabs in the documentation * doc tabs uodated * AWS architecture image added * Doc -> AWS settings updated * 1943 docs task add a button on the readme page to deploy the whole platform (#2015) * #1943 Add AWS Deployment - Add AWS Deployment - Add AWS information in the different sections * #1943 Update documentation Quick start in each tab of cloud provider * #1943 docs adjusting parameters for aws * #1943 docs lint-documentation corrections * Doc: Add AWS BucketName in Aws configuration (#2090) * Update template paths * Add AccountId Attribute in AWS doc (#2129) * Update AWS documentation * Update Doc for Azure specific param (#2159) * Update Doc for Azure specific param * update the doc * enable fleet index mode for AWS support (#2225) * Add doc v4-to-v5 migration page (#2232) * Add doc v4-to-v5 migration page * Update v4-to-v5.md * Update v4-to-v5.md * Update configuration for lorawan support * Update database migration documentation --------- Co-authored-by: ssgueye2 <127868584+ssgueye2@users.noreply.github.com> Co-authored-by: DELAGE Raphaël <36408929+delager@users.noreply.github.com>
- Loading branch information
3 people
authored
Jun 26, 2023
1 parent
ffc788d
commit a1bb6ba
Showing
8 changed files
with
245 additions
and
57 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,94 @@ | ||
| # AWS configurations | ||
|
|
||
| ## Overall Architecture | ||
|
|
||
| This schema represent the various components and how they interact to have a better understanding of the various solution elements. | ||
|
|
||
|  | ||
|
|
||
| 1. The user is authenticated by the OpenID Connect server. | ||
| 1. The user access to the IoT Hub Portal with the OAuth2.0 token. | ||
| 1. The IoT Hub portal uses the AWS IoT REST API to retrieve the data. | ||
| 1. The IoT Hub portal uses the AWS S3 storage to store the device models configuration (Images, Commands, etc.). | ||
| 1. The IoT Hub portal synchronizes its data with the IoT Hub to provide a consistent view of the data. | ||
|
|
||
| ## Quick Start | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| * You must have an AWS Account. Get an [AWS Free account](https://portal.aws.amazon.com/billing/signup#/start/email) to get started. | ||
| * You must enable Fleet Indexing for registry and shadow | ||
| ***Using AWS CLI:*** | ||
|
|
||
| ```console | ||
| aws iot update-indexing-configuration --thing-indexing-configuration thingIndexingMode=REGISTRY_AND_SHADOW | ||
| ``` | ||
|
|
||
| > Please note that you'll need the necessary permissions to execute this command. Make sure your AWS IAM user or role has the appropriate permissions to access and modify the IoT indexing configuration. | ||
|
|
||
| ### Deployed Resources | ||
|
|
||
| The template will deploy in your AWS Account the Following resources: | ||
|
|
||
| * AWS RDS - Database for PostgreSQL | ||
| * AWS S3 Bucket | ||
| * AWS App Runner Service | ||
|
|
||
| ### Instructions | ||
|
|
||
| 1. Choose a stack name for your AWS Deployment. | ||
|
|
||
| 1. Follow next step below to start your deployment: | ||
|
|
||
| 1. Press on the button here below to download the template AWS: | ||
| [Download the template](https://raw.githubusercontent.com/CGI-FR/IoT-Hub-Portal/arm/main-vnext/templates/aws/awsdeploy.yml) | ||
|
|
||
| 1. Import your template : | ||
| ***From the AWS console: [CloudFormation new stack](https://eu-west-1.console.aws.amazon.com/cloudformation/home?region=eu-west-1#/stacks/create)*** | ||
| - You can change the deployment region by changing the region directly in the URL | ||
| - In "Upload a template file" import the previously downloaded file | ||
| ***With AWS CLI:*** | ||
|
|
||
| ```console | ||
| aws cloudformation deploy --template /path_to_template/awsdeploy.yml --stack-name your-stack-name --region your-region | ||
| ``` | ||
|
|
||
| > see: [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-cli-deploy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-cli-deploy.html) for more option about aws cloudformation deploy | ||
|
|
||
| 1. You will get to a page asking you to fill the following fields: | ||
| * **Stack Name**: A name for the stack where all the template resource would be put into, just choose a meaningful name. | ||
| * **PostgreSQL user**: The PostgreSQL user name to be used for the IoT Hub Portal database. | ||
| * **PostgreSQL password**: The PostgreSQL password to be used for the IoT Hub Portal database. | ||
| * **AWS Access Key**: The AWS Access Key of your AWS environment. | ||
| * **AWS Access Secret Key**: The AWS Access Secret Key of your AWS environment. | ||
| * **Api Client Id**: the ID of the API client that will be used to authenticate the portal. | ||
| * **Client Id**: the ID of the web client that will be used to authenticate the portal. | ||
| * **Open Id Authority**: The OpenID authority used by the portal. | ||
| * **OpenId Metadata URL**: The OpenID metadata URL used by the portal. | ||
| * **OpenId Scope Name**: The Open ID Scope name | ||
|
|
||
| ## Configurations | ||
|
|
||
| This configurations are used to get access to AWS cloud Platform. You have to enter them in a `json` file to be able to connect to the Iot Hub Portal. Here is a template of a such `json` file. | ||
|
|
||
| ```json | ||
| { | ||
| "CloudProvider": "AWS", | ||
| "AWS:Access": "<ACCESS_KEY>", | ||
| "AWS:AccessSecret": "<ACCESS_SECRET_KEY>", | ||
| "AWS:Region": "<REGION_KEY>", | ||
| "AWS:BucketName": "<BUCKET_NAME>", | ||
| "AWS:AccountId": "<ACCOUNT_IDENTIFIER>", | ||
| "AWS:GreengrassRequiredRoles:<ID>": "<GREENGRASS_ROLE_NAME>", | ||
| "OIDC:Scope": "<SCOPE>", | ||
| "OIDC:MetadataUrl": "<METADATA_URL>", | ||
| "OIDC:ClientId": "<CLIENT_ID>", | ||
| "OIDC:Authority": "<AUTHORITY>", | ||
| "OIDC:ApiClientId": "<API_CLIENT_ID>", | ||
| "PostgreSQL:ConnectionString": "<POSTGRE_SQL_CONNECTION_STRING>" | ||
| } | ||
| ``` | ||
|
|
||
| > <u>Note:</u> You must replace all values in the brackets by your own AWS settings. If you can't find them in the AWS Portal, please contact an administrator of this project to have more information. | ||
| You are now ready to start your IoT Hub Portal development ! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| # Azure Configurations | ||
|
|
||
| ## Overall Architecture | ||
|
|
||
| This schema represent the various components and how they interact to have a better understanding of the various solution elements. | ||
|
|
||
|  | ||
|
|
||
| 1. The user is authenticated by the OpenID Connect server. | ||
| 1. The user access to the IoT Hub Portal with the OAuth2.0 token. | ||
| 1. The IoT Hub portal uses the Azure IoT Hub REST API to retrieve the data. | ||
| 1. The IoT Hub portal uses the Azure Device Provisioning Service to manage IoT Edge devices. | ||
| 1. The IoT Hub portal uses the Azure Storage account to store the device models configuration (Images, Commands, etc.). | ||
| 1. The IoT Hub portal uses the LoRa Key Management Facade to send Cloud to Device (C2D) messages to LoRa devices. | ||
| 1. The LoRa Key Management Facade uses Redis to store its cached data. | ||
| 1. The LoRa Key Management Facade uses the Azure IoT Hub REST API to retrieve the LoRa device keys and send C2D messages. | ||
| 1. The IoT Hub portal synchronizes its data with the IoT Hub to provide a consistent view of the data. | ||
|
|
||
| > Note: For more information about the LoRa Key Management Facade, see the [Azure IoT Edge LoRaWAN Starter Kit](https://azure.github.io/iotedge-lorawan-starterkit) page. | ||
| ## Quick Start | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| * You must have an Azure subscription. Get an [Azure Free account](https://azure.microsoft.com/en-us/offers/ms-azr-0044p/) to get started. | ||
| * You must have configured an Azure AD B2C Tenant with applications. See [Portal AD applications configuration](https://cgi-fr.github.io/IoT-Hub-Portal/stable/b2c-applications) page. | ||
| * Understand how IoT Edge LoraWAN StarterKit work. Have a look at [https://azure.github.io/iotedge-lorawan-starterkit](https://azure.github.io/iotedge-lorawan-starterkit) to get started. | ||
|
|
||
| ### Deployed Resources | ||
|
|
||
| The template will deploy in your Azure subscription the Following resources: | ||
|
|
||
| * IoT Hub | ||
| * Azure Function and Consumption Service Plan | ||
| * Redis Cache | ||
| * Application Insights | ||
| * Log Analytics (when opted in to use Azure Monitor) | ||
| * Azure WebApp and Service Plan | ||
| * Azure Database for PostgreSQL | ||
|
|
||
| ### Instructions | ||
|
|
||
| 1. Choose a solution prefix for your Azure Deployment. | ||
|
|
||
| 1. Configure your AD to connect to the portal. | ||
| Use [Portal AD applications configuration](https://cgi-fr.github.io/IoT-Hub-Portal/stable/b2c-applications) page to configure your AD B2C Tenant : | ||
|
|
||
| > You should have recorded the following information: | ||
| > | ||
| > * OpenID authority: `<your-openid-authority>` | ||
| > * OpenID metadata URL: `<your-openid-provider-metadata-url>` | ||
| > * Client ID: `<your-client-id>` | ||
| > * API Client ID: `<your-client-id>` | ||
| 1. Press on the button here below to start your deployment on Azure: | ||
| [](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FCGI-FR%2FIoT-Hub-Portal%2Farm%2Fmain-vnext%2Ftemplates%2Fazure%2Fazuredeploy.json/uiFormDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2FCGI-FR%2FIoT-Hub-Portal%2Farm%2Fmain-vnext%2Ftemplates%2Fazure%2FazuredeployUI.json) | ||
|
|
||
| 1. You will get to a page asking you to fill the following fields: | ||
| * **Resource Group**: A logical "folder" where all the template resource would be put into, just choose a meaningful name. | ||
| * **Location**: In which DataCenter the resources should be deployed. Make sure to choose a location where IoT Hub is available | ||
| * **Unique Solution Prefix**: A string that would be used as prefix for all the resources name to ensure their uniqueness. | ||
| * **PostgreSQL user**: The PostgreSQL user name to be used for the IoT Hub Portal database. | ||
| * **PostgreSQL password**: The PostgreSQL password to be used for the IoT Hub Portal database. | ||
| * **Confirm PostgreSQL password**: The PostgreSQL password to be used for the IoT Hub Portal database. | ||
| * **Open Id Authority**: The OpenID authority used by the portal. | ||
| * **OpenId Metadata URL**: The OpenID metadata URL used by the portal. | ||
| * **Client Id**: the ID of the web client that will be used to authenticate the portal. | ||
| * **Api Client Id**: the ID of the API client that will be used to authenticate the portal. | ||
| * **Edge gateway name**: the name of your LoRa Gateway node in the IoT Hub. | ||
| * **Deploy Device**: Do you want demo end devices to be already provisioned (one using OTAA and one using ABP)? If yes set this to true, the code located in the Arduino folder would be ready to use immediately. | ||
| * **Reset pin**: The reset pin of your gateway (the value should be 7 for the Seed Studio LoRaWan, 25 for the IC880A) | ||
| * **Region**: In what region are you operating your device (currently only EU868 and US915 is supported) | ||
|
|
||
| > see: [https://azure.github.io/iotedge-lorawan-starterkit/dev/quickstart/#deployed-azure-infrastructure](https://azure.github.io/iotedge-lorawan-starterkit/dev/quickstart/#deployed-azure-infrastructure) for more information about the LoRaWan IoT Hub and Azure deployment. | ||
| ## Configurations/Secrets | ||
|
|
||
| _Secrets_ are used to fill in the login credentials to the cloud platform. You have to enter them in a `json` file to be able to connect to the IoT Hub Portal. Here is a template of a such `json` file : | ||
|
|
||
| ```json | ||
| { | ||
| "CloudProvider": "Azure", | ||
| "OIDC:Scope": "<SCOPE>", | ||
| "OIDC:MetadataUrl": "<METADATA_URL>", | ||
| "OIDC:ClientId": "<CLIENT_ID>", | ||
| "OIDC:Authority": "<AUTHORITY>", | ||
| "OIDC:ApiClientId": "<API_CLIENT_ID>", | ||
| "LoRaFeature:Enabled": "<TRUE_OR_FALSE>", | ||
| "Azure:LoRaRegionRouterConfig:Url": "<LORA_WAN_ROUTER_CONFIGURATION_URL>", | ||
| "Azure:LoRaKeyManagement:Url": "<LORA_WAN_KEY_MANAGEMENT_URL>", | ||
| "Azure:LoRaKeyManagement:Code": "<LORA_WAN_KEY_MANAGEMENT_CODE>", | ||
| "Kestrel:Certificates:Development:Password": "<DEV_PASSWORD>", | ||
| "Azure:IoTHub:ConnectionString": "<IOT_HUB_CONNECTION_STRING>", | ||
| "Azure:IoTHub:EventHub:Endpoint": "<IOT_HUB_EVENT_HUB_ENDPOINT>", | ||
| "Azure:IoTHub:EventHub:ConsumerGroup": "<IOT_HUB_EVENT_HUB_CONSUMER_GROUP>", | ||
| "Azure:IoTDPS:ServiceEndpoint": "<SERVICE_END_POINT>", | ||
| "Azure:IoTDPS:LoRaEnrollmentGroup": "<LORA_WAN_ENROLLMENT_GROUP>", | ||
| "Azure:IoTDPS:DefaultEnrollmentGroup": "<LORA_WAN_DEFAULT_ENROLLMENT_GROUP>", | ||
| "Azure:IoTDPS:ConnectionString": "<IOT_DPS_CONNECTION_STRING>", | ||
| "PostgreSQL:ConnectionString": "<POSTGRE_SQL_CONNECTION_STRING>", | ||
| "Azure:StorageAccount:ConnectionString": "<CONNECTION_STRING_STORAGE_ACCOUNT>" | ||
| } | ||
| ``` | ||
|
|
||
| > <u>Note:</u> You must replace all values in the brackets by your own Azure settings. If you can't find them in the Azure Portal, please contact an administrator of this project to have more information. | ||
| This `json` file must be added into your project solution. To do that, click on the `AzureIoTHub.Server` project in Visual Studio and select `Manage User Secrets` from the context menu. You can now add your secrets inside this file. | ||
|
|
||
| You are now ready to start your IoT Hub Portal development ! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| # Migrate from v4 to v5 | ||
|
|
||
| In this v5, the major change is the integration of AWS in the portal. | ||
| Some changes have also been made at the portal web app settings. | ||
|
|
||
| ## AWS | ||
|
|
||
| Starting from version 5, the portal now supports `AWS` integration. | ||
| To learn how to deploy `AWS services` using the portal, please refer to the [Quick Start](/aws/#quick-start) for AWS documentation. It provides step-by-step instructions on setting up and deploying AWS resources using the portal's interface. | ||
|
|
||
| ## Azure | ||
|
|
||
| To migrate from v4 to v5 `manually`, you have to add `CloudProvider` with `Azure` as default value. | ||
| You have to add also `Azure__` prefix in all setting to the portal web app. | ||
|
|
||
| | Name | Setting Type | Detail | | ||
| |---|---|---| | ||
| | `CloudProvider` | Application setting | (Possible value `Azure`) The name of the CLoud Provider to run in the portal | | ||
| | `Azure__LoRaRegionRouterConfig__Url` | Application setting | The Url for LoRa Region Router Configuration | | ||
| | `Azure__LoRaKeyManagement__Url` | Application setting | The Url for LoRa Key Management | | ||
| | `Azure__LoRaKeyManagement__Code` | Application setting | The Code for LoRa Key Management | | ||
| | `Azure__LoRaFeature__Enabled` | Application setting | To enable or disable LoRa Feature | | ||
| | `Azure__IoTHub__ConnectionString` | Connection string | The IotHub Connection String | | ||
| | `Azure__IoTHub__EventHub__Endpoint` | Connection string | The IotHub Event Hub compatible endpoint | | ||
| | `Azure__IoTHub__EventHub__ConsumerGroup` | Application setting | (Default value `iothub-portal`) The name of the consumer group used to to pull data from the IoT Hub | | ||
| | `Azure__IoTDPS__ServiceEndpoint` | Application setting | The IotDPS Service Endpoint | | ||
| | `Azure__IoTDP__LoRaEnrollmentGroup` | Application setting | The name of the IotDPS LoRa Enrollment group | | ||
| | `Azure__IoTDPS__DefaultEnrollmentGroup` | Application setting | The name of the default IotDPS Enrollment group | | ||
| | `Azure__IoTDPS__ConnectionString` | Connection string | The IotDPS Connection String | |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters