Skip to content

Install command

This command prepares the target environment for the actual deployment of the Sidra solution. It is used to:

  • Add the necessary service principals, Application Registration entries in the Azure Active Directory tenant of the target organization.
  • Provision the necessary resources to use: Key Vault and the Automation.
  • Install a Power BI application in an existing Sidra solution installation.

Usage Options

The usage options are aadapplications, deployautomation and powerbiapp options.

    .\sidra.exe install aadapplications [parameters]
    .\sidra.exe install deployautomation [parameters]
    .\sidra.exe install powerbiapp [parameters]
    .\sidra.exe install [aadapplications|deployautomation|powerbiapp] --help

Note

When executing this command, the login window can appear below the current window without being noticed. The process will not continue unless the user logs in.

1. aadApplications option

This option creates the necessary Application Registration entries in the Azure Active Directory tenant and some of the Azure resources needed by the Sidra deployment.

The person executing this command option needs to have an account with sufficient permissions to create Application Registration entries, Azure resources, and Resource Groups. Most commonly, this means being Tenant Administrator and Subscription Owner.

Currently, there are five App Registrations created by this command in the Azure Active Directory tenant:

  • <Project>.<Env>.IdentityServerAdAccess

This has access to Microsoft Graph with the permissions Directory.Read-All, to allow our Identity Server federating with the Active Directory of the subscription;

  • <Project>.<Env>.Manager

This is assigned the Contributor role over the subscription. It has also complete access over the KeyVault. This application is used to manage tasks on Azure resources, primarily needed for the Data Factory services.

  • <Project>.<Env>.VSTS

This is assigned the Subscription Owner role and has read permissions over the Active Directory. This application uses the same service account as DevOps to automate the infrastructure deployment.

  • Automation account

This account automates and orchestrates administrative tasks inside Azure.

  • App Registration for Power BI service*

This is optionally created in order to manage Power BI workspaces. These tasks are performed through the service principal that is associated with the app; so, in the Power BI portal, the option for the agents to consume the Power BI API needs to be enabled.

This command is idempotent. If something fails during the process of creating the Azure AD application, this command can be re-run again; one does not need to manually delete what has already been created, before executing this command again.

Prerequisites

Run as Administrator
This command uses New-AzAutomationCertificate at CreateAutomationCertificateAsset PowerShell method from a MS Module. This method should be run on a machine that you are an administrator of, as well as in an elevated PowerShell session; before the certificate is uploaded, this cmdlet uses the local X.509 store to retrieve the thumbprint and key, and if this cmdlet is run outside of an elevated PowerShell session, you will receive an "Access denied" error. More information can be seen in the official documentation.

Log in to Azure
Perform an az login before attempting sidra.exe install aadapplications. This command creates Azure Active Directory App Registrations, so make sure that you're logging in with an account having sufficient privileges. Also make sure that you're logging in to the right Azure Active Directory tenant: check the Tenant ID.

Parameters

    --subscription
The Subscription ID GUID identifies the Azure subscription where resources will be created.
    --location
Establishes the Azure region where the Azure resources will be placed. Example: westeurope.
    --identityServerUrl
Base URL of the Identity Server, allowing to authenticate the services. This URL is composed out of a series of strings, folllowing the convention:
<INSTALLATION_NAME>-core-<ENVIRONMENT>-wst-is.azurewebsites.net

We could have:

  • pcsi: arbitrary string, maximum 4 characters, chosen at Sidra installation (resourceNamePrefix); here, we chose the acronym for PlainConcept Sidra Installation.
  • core: arbitrary string, maximum 4 characters, chosen at Sidra installation (resourceNameMiddle); here, we chose it indicating this is for Sidra Core.
  • dev is the environment name, shortening from development.
  • wst is a hardcoded particle, a fixed string, added automatically at Sidra's deployment, for Sidra's Azure App Services.
  • is is a hardcoded particle, a fixed string, added automatically at Sidra's deployment, signifying Identity Server.
  • azurewebsites.net is the common domain name for Azure App Services.

Example: pcsi-core-dev-wst-is.azurewebsites.net

    --keyvaultName
Name of the Core Azure KeyVault resource, following the standard Sidra naming convention:
<INSTALLATION_NAME>-core-<ENVIRONMENT>-kva

We could have:

  • pcsi: arbitrary string, maximum 4 characters, chosen at the Sidra installation (resourceNamePrefix); here, we chose the acronym for PlainConcept Sidra Installation.
  • core: arbitrary string, maximum 4 characters, chosen at the Sidra installation (resourceNameMiddle); here, we chose it indicating this is for Sidra Core.
  • dev is the environment name, shortening from development.
  • kva is a hardcoded particle, a fixed string, added automatically at Sidra's deployment, signifying Key Vault.

Example: pcsi-core-dev-kva

    --customerClientSecret
Provided by Plain Concepts, it is a password-like string associated with the Sidra usage license. This is required to consume the Sidra backoffice configuration service, called Llagar, a centralized service for installations to retrieve transversal data and provide transversal configurations and artifacts.
    --customerClientId
Provided by Plain Concepts, it is a GUID associated with the Sidra usage license. This is required to consume the Sidra backoffice configuration service, called Llagar, a centralized service for installations to retrieve transversal data and provide transversal configurations and artifacts.
    --llagarACRPassword
Tells the Azure Container Service password for the Llagar container service.
    --resourceGroup
The name of the Azure Resource Group where Sidra resources will be created.
Commonly used: Sidra.Core or Sidra.Core.<ENVIRONMENT>.
    --createPowerBiApp

This is an optional switch parameter, defaulting to false. It may be present (set to true) or absent (defaulting to false) in the command.

If true, an Application Registration entry will be created in the Azure Active Directory tenant for the Power BI interaction. This is required for the access to the operational Power BI reports.

If false, the installation of a Power BI Azure Active Directory app can later be achieved through the Sidra.exe install powerbiapp option; see below in this document.

    --automationAccountName
Determines the name of the Sidra Automation Account. Provided by Plain Concepts, this automation account will be in charge of executing different automation runbooks for the system.
The naming convention is the same as for the --keyvaultName, replacing kva by aa.

Usage example

    .\sidra.exe install aadapplications `
        --subscription="GUIDGUID-GUID-GUID-GUID-GUIDGUIDGUID" `
        --location="westeurope" `
        --identityServerUrl="https://pcsi-core-dev-wst-is.azurewebsites.net" `
        --keyvaultName="pcsi-core-dev-kva" `
        --customerClientId="GUIDGUID-GUID-GUID-GUID-GUIDGUIDGUID" `
        --customerClientSecret="j6zqsNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNtquda" `
        --llagarACRPassword="o9nGK@!dCWTP67v#" `
        --resourceGroup="Sidra.Core" `
        --automationAccountName="pcsi-core-dev-aa" `
        --createPowerBiApp

2. Configure your AAD application to use Power BI service APIs

When the Install AadApplications step is finished, in the case that security groups are going to be used, it is mandatory to add the main service of Power BI already created to said group. This section shows how to configure an AAD application in Sidra to use Power BI service APIs as an additional setting for the access to the operational Power BI reports.

Steps

  • Step 1. Open app.powerbi.com in a web browser.

    Click on sign-in button using the administrator account related to Power BI service:

    Login portal

  • Step 2. Once logged in, in the main menu, click on the configuration icon and select Admin portal option:

    Configuration

  • Step 3. Once in the Admin Portal find the menu Tenant settings.

    Look for Developer settings and, inside this section, find the setting Allow service principals to use Power BI APIs:

    Administrator panel

    Set the toggle button to the Enabled position. Then decide which applications in your tenant will have permissions to access.

    This setting allows to configure two different modes:

    • The entire organization: all applications in your tenant will be able to access the Power BI APIs.
    • Specific security groups: defines the set of security groups that are allowed to use Power BI APIs. There is also an option to define deny list groups.

    Finally, click on Apply to save the settings.

Troubleshooting

  • If you can't see Tenant settings section, please ensure that you sign in with the administrator account.
  • If you can't find your app in Specific security groups: please ensure that you already created a security group before, which contains the Power BI Application Azure AD in your tenant Active Directory.

3. DeployAutomation option

This option installs the necessary resources for using Automation.

Note that Install AadApplications already does this; so, normally, one does not need to use the DeployAutomation option.

Prerequisites

Run as Administrator
This command uses New-AzAutomationCertificate at CreateAutomationCertificateAsset PowerShell method from a MS Module. This method should be run on a machine that you are an administrator of, as well as in an elevated PowerShell session; before the certificate is uploaded, this cmdlet uses the local X.509 store to retrieve the thumbprint and key, and if this cmdlet is run outside of an elevated PowerShell session, you will receive an "Access denied" error. More information can be seen in the official documentation.

Log in to Azure
Perform an az login before attempting sidra.exe install deployautomation. This command creates Azure Active Directory App Registrations, so make sure that you're logging in with an account having sufficient privileges. Also make sure that you're logging in to the right Azure Active Directory tenant: check the Tenant ID.

Parameters

    --subscription
The Subscription ID GUID, identifying the Azure subscription where resources will be created.
    --location
Establishes the Azure region where the Azure resources will be placed. Example: westeurope.
    --resourceGroup
The name of the Azure Resource Group where Sidra resources will be created.
Commonly used: Sidra.Core or Sidra.Core.<ENVIRONMENT>.
    --keyvaultName
Name of the Core Azure KeyVault resource, following the standard Sidra naming convention:
<INSTALLATION_NAME>-core-<ENVIRONMENT>-kva

We could have:

  • pcsi: arbitrary string, maximum 4 characters, chosen at Sidra installation (resourceNamePrefix); here, we chose the acronym for PlainConcept Sidra Installation.
  • core: arbitrary string, maximum 4 characters, chosen at Sidra installation (resourceNameMiddle); here, we chose it indicating this is for Sidra Core.
  • dev is the environment name, shortening from development;
  • kva is a hardcoded particle, a fixed string, added automatically at Sidra's deployment, signifying Key Vault.

Example: pcsi-core-dev-kva

    --automationAccountName
Determines the name of the Sidra Automation Account. Provided by Plain Concepts, this automation account will be in charge of executing different automation runbooks for the system. The naming convention is:
<INSTALLATION_NAME>-core-<ENVIRONMENT>-wst-is.azurewebsites.net

We could have:

  • pcsi: arbitrary string, maximum 4 characters, chosen at Sidra installation (resourceNamePrefix); here, we chose the acronym for PlainConcept Sidra Installation.
  • core: arbitrary string, maximum 4 characters, chosen at Sidra installation (resourceNameMiddle); here, we chose it indicating this is for Sidra Core.
  • dev is the environment name, shortening from development.
  • aa is a hardcoded particle, a fixed string, added at Sidra's deployment, signifying Automation Account.

Example: pcsi-core-dev-aa

Usage example

    .\sidra.exe install deployautomation `
        --subscription="GUIDGUID-GUID-GUID-GUID-GUIDGUIDGUID" `
        --location="westeurope" `
        --keyvaultName="pcsi-core-dev-kva" `
        --resourceGroup="Sidra.Core" `
        --automationAccountName="pcsi-core-dev-aa"

4. PowerBiApp option

The operational Power BI report is a report provided by Sidra, using the Power BI service. In order to make this report available for an existing installation, it is required to execute this CLI tool command.

Parameters

    --powerBiUserPrincipalName
The user principal name (UPN) for the Power BI service, from the Azure Active Directory tenant: an e-mail address associated with the Power BI application.

It would be convenient if this account would be a Power BI Administrator.

    --powerBiCapacityName
The capacity name for the Power BI service. This is a Power BI Premium functionality.
    --powerBiRefreshPeriod
This is the refresh period configured for the Power BI report in Power BI service.

If a different refesh period is required to the default one, it needs to be provided in the format HH:MM,HH:MM,HH:MM.

Example: 08:00, 14:00,16:00

See Power BI, Refreshing Data.

Usage example

    .\sidra.exe install powerbiapp `
        --powerBiUserPrincipalName="<POWERBIUSERPRINCIPAL>" `
        --powerBiCapacityName="<POWERBICAPACITY>" `
        --powerBiRefreshPeriod="Daily"

Next: The Deploy command


Last update: 2022-05-03
Back to top