Azure Resource Names #
Aggregator CLI has three ways of generating names for Azure Resources. Keep in mind, that Azure Function App and Storage resources must have unique names in Azure.
Basic template #
This template is used when you do not specify the --resourceGroup option.
In this scenario Aggregator tries to create an Azure Resource Group for each instance. The name of the resource group derives from the instance name.
| Object | Generated name |
|---|---|
| Instance Name | foo |
| Resource Group | aggregator-foo |
| StorageAccount | aggregator######## (8 random characters) |
| Function App | fooaggregator |
| Hosting Plan | fooaggregator-plan |
| AppInsight | fooaggregator-ai |
Default template #
This template is used when you specify the --resourceGroup option
| Object | Generated name |
|---|---|
| Instance Name | foo |
| Resource Group | bar |
| StorageAccount | aggregator######## (8 random characters) |
| Function App | fooaggregator |
| Hosting Plan | fooaggregator-plan |
| AppInsight | fooaggregator-ai |
In this scenario, you can have more than one Instance (Azure Function) in the same Resource Group.
Custom template #
This template allows a complete customisation of the generated names.
You specify both --namingTemplate and --resourceGroup options.
Given a custom template with this data
{
"ResourceGroupPrefix": "rgp-",
"ResourceGroupSuffix": "-rgs",
"FunctionAppPrefix": "p",
"FunctionAppSuffix": "s",
"HostingPlanPrefix": "hp-",
"HostingPlanSuffix": "-hs",
"AppInsightPrefix": "aip-",
"AppInsightSuffix": "-ais",
"StorageAccountPrefix": "strg",
"StorageAccountSuffix": "123456"
}
you have
| Object | Generated name |
|---|---|
| Instance Name | foo |
| Resource Group | rgp-bar-rgs |
| StorageAccount | strgfoo123456 |
| Function App | pfoos |
| Hosting Plan | hp-foo-hs |
| AppInsight | aip-foo-ais |
GitHub cache #
Aggregator CLI caches GitHub data for 24 hours to prevent API rate limit exceeded error. If CLI fails to find a specific version, check that it is still available in GitHub and delete the githubresponse.cache file in the %LOCALAPPDATA%\aggregator-cli (Windows) or $HOME/.local/share/aggregator-cli directory (Linux).
This cache applies to both install.instance and update.instance commands.
install.instance #
Creates a new Aggregator instance in Azure. It requires two mandatory options.
| Option | Short form | Description |
|---|---|---|
--name | -n | The name for the new Aggregator instance. |
--location | -l | Name of Azure region that will host the Aggregator instance. |
This command creates a few resources in Azure:
- An Azure Function App that will host the Rule Engine and receive the notifications from Azure DevOps.
- The associated Hosting Plan.
- A Storage account to support the Function App.
- An AppInsight instance to store the traces and messages generated by the Rules.
After the required Azure Resources are in place, it downloads the latest Aggregator Runtime from GitHub and uploads it so it is shared by future added Rules.
The overall process may require a few minutes. It is a good practice to set the --verbose option to track the progress.
If the process fails, the resources create are still in Azure. You can try re-run the command after fixing the failing step.
You can refine the process with additional options.
| Option | Short form | Description |
|---|---|---|
--resourceGroup | -g | Azure Resource Group that contains the Aggregator instances. If you specify this option, the Resource Group must already exists and the logon account must be a Contributor. |
--namingTemplate | n/a | Specify affixes for all Azure resources that will be created. This option requires defining --resourceGroup, also. This turns off automatic name generation and allow comply with enterprise requirements. |
--requiredVersion | n/a | Version of Aggregator Runtime required. This is mutually exclusive with --sourceUrl. The matching version is retrieved from GitHub and uploaded to the Azure Function App. The version number must match one of the Aggregator releases in GitHub. Note that GitHub caching applies. |
--sourceUrl | n/a | URL of Aggregator Runtime. This is mutually exclusive with --requiredVersion. It should be used in enterprise scenario where the CLI cannot read from GitHub. It supports http, https and file scheme, so you can download the Runtime on a network share. |
--hostingPlanTier | -t | Azure AppPlan Service tier hosting the Aggregator instances. Defaults to Dynamic. |
--hostingPlanSku | -k | Azure AppPlan SKU hosting the Aggregator instances. Defaults to Y1, matching the Dynamic tier. |
--appInsightLocation | n/a | Name of Azure region that will host AppInsight for the new Aggregator instance. This allows to host the Function App in a region where AppInsight is not available. |
configure.instance #
Reconfigures an existing Aggregator instance. It requires two mandatory options.
| Option | Short form | Description |
|---|---|---|
--name | -n | The name of an existing Aggregator instance. |
--location | -l | Name of Azure region hosting the Aggregator instance. |
You can use these two options to further specify the name.
| Option | Short form | Description |
|---|---|---|
--resourceGroup | -g | Azure Resource Group that contains the Aggregator instance. |
--namingTemplate | n/a | Specify affixes for Azure resources. This option requires defining --resourceGroup, also. This turns off automatic name generation and allow comply with enterprise requirements. |
Furthermore, you must specify one of these two options.
| Option | Short form | Description |
|---|---|---|
--authentication | -a | Refresh the Azure DevOps authentication data saved in the Function App configuration. |
--saveMode | -m | Sets the algorithm to save the data changed by Rules back to Azure DevOps. |
update.instance #
Updates an existing Aggregator instance in Azure, with latest runtime binaries. It requires one mandatory options.
It is not guaranteed to work across major version of runtime.
| Option | Short form | Description |
|---|---|---|
--instance | -i | The name of an existing Aggregator instance. |
You can use these two options to further specify the name.
| Option | Short form | Description |
|---|---|---|
--resourceGroup | -g | Azure Resource Group that contains the Aggregator instance. |
--namingTemplate | n/a | Specify affixes for Azure resources. This option requires defining --resourceGroup, also. This turns off automatic name generation and allow comply with enterprise requirements. |
Furthermore, you must specify one of these two options to identify the Runtime version you want to upgrade to.
| Option | Short form | Description |
|---|---|---|
--requiredVersion | n/a | Version of Aggregator Runtime required. This is mutually exclusive with --sourceUrl. The matching version is retrieved from GitHub and uploaded to the Azure Function App. The version number must match one of the Aggregator releases in GitHub. Note that GitHub caching applies. |
--sourceUrl | n/a | URL of Aggregator Runtime. This is mutually exclusive with --requiredVersion. It should be used in enterprise scenario where the CLI cannot read from GitHub. It supports http, https and file scheme, so you can download the Runtime on a network share. |
uninstall.instance #
Destroys an Aggregator instance in Azure, that is the Azure Function App created by install.instance. It requires two mandatory options.
| Option | Short form | Description |
|---|---|---|
--name | -n | The name of an existing Aggregator instance. |
--location | -l | Name of Azure region hosting the Aggregator instance. |
You can use these two options to further specify the operation.
| Option | Short form | Description |
|---|---|---|
--resourceGroup | -g | Azure Resource Group that contains the Aggregator instance. |
--namingTemplate | n/a | Specify affixes for Azure resources. This option requires defining --resourceGroup, also. This turns off automatic name generation and allow comply with enterprise requirements. |
--dont-remove-mappings | -m | Do not remove mappings from Azure DevOps (default is to remove them). |
The Resource Group is deleted only if it was created by Aggregator.