Skip to content

Sidra.exe CLI tool

Deployment of the Sidra solution – the initial installation – is being done using the command-line interface (CLI) tool Sidra.exe. Sidra CLI tool has been designed to ease the process of installing and updating Sidra Core. It also helps with a few post-deployment operations.

Simplified to basics, a Sidra installation means running a deployment pipeline from an Azure DevOps Git repository. The deployment pipeline applies ARM templates to create, configure, and populate the needed Azure resources. The Git repository would be a clone of one maintained by Plain Concepts.

The Sidra CLI tool assists in preparing the target environment - Azure AD, Subscription, DevOps repo - so that the deployment pipeline mentioned above can be executed.

Note

Given the dependencies needed and potential conflicts with existing setups, it is recommended that the Sidra.exe tool should be executed from a fresh Windows installation, perhaps a VM purposed for managing the Sidra installation using this tool.

Intended audience

This tool was designed to be used by engineers deploying a Sidra solution or making updates on it. Although the tool may be used by engineers from the customer organization, it is expected that assistance from a Plain Concepts support engineer for Sidra may be needed.

Usage of the tool requires some familiarity with the following technologies, at least at the level of functionality:

  • Azure Subscriptions, resources, Resource Groups, Azure regions
  • Azure Active Directory and Application Registrations, access rights management in Azure
  • PowerShell and Azure CLI, .NET (Core) SDK
  • Azure DevOps projects and access rights, Git
  • Sidra’s overall architecture

As could be seen in the Prerequisites section, the engineer(s) will need proper access rights granted on the Azure Subscription, Active Directory tenant, DevOps space, in order to successfully execute the tool.

Overall functionality

The aim of the tool is to help replicate a base structure of the Sidra solution, from the Plain Concepts’ environment into the target environment of the customer organization. In this context, “environment” is being seen as the combination of:

  1. Azure Active Directory and Application Registrations
  2. Azure Subscription with Resource Groups and needed resources
  3. Azure DevOps code repository and automation CI/CD pipelines

The Sidra.exe CLI tool is going to help to:

  • Create the necessary access control structures into the customer’s Azure Active Directory tenant
  • Copy the needed code from the Plain Concepts’ Azure DevOps space into the target customer’s space
  • Apply the copied code files to create the Resource Groups and resources needed
  • Configure the created resources to get a basic Sidra solution in place.

Note

Once the basic Sidra solution is installed, additional steps will be needed to customize its functionality according to the specific needs of the customer organization.

A basic documentation of the tool’s usage syntax is available running:

    .\sidra.exe --help 
    .\sidra.exe [command] --help

Please find below in the Sequence of commands section how the tool should be used.

Prerequisites

While Sidra.exe is able to assist installing needed external dependencies, this installation tool is not going to set everything up. Some prerequisite steps - provisioning the Azure dependencies and access rights - need to be taken prior to attempting using the tool.

External dependencies

The following programs need to be installed on the machine from where Sidra.exe will be executed. The tool will check for the existence of these and does help installing them if they are missing. Details on having the dependencies installed by Sidra CLI tool may be found consulting the documentation for the prerequisites command.

.NET Core SDK

  • Sidra.exe can download and install the needed SDK version; see the Prerequisites command.
  • Currently, this SDK version is hardcoded at .NET Core 3.1.119.
  • Alternatively, the SDK version may be manually downloaded and installed from Microsoft .NET download page.
  • Check the existence and version(s) installed on the machine by typing the following in a command-line console:
        dotnet --info

Git, version control

  • The tool can download and install GIT by itself; see the Prerequisites command.
  • Alternatively, the instrument may be manually downloaded and installed from Git SCM download page.
  • Check the existence and version(s) installed on the machine by typing the following in a command-line console:
        git --version

Internet Explorer

On fresh machines – such as VMs purposely created for installing Sidra – Internet Explorer should be run at least once outside the context of Sidra.exe, prior to attempting executing the tool. Sidra.exe is using Internet Explorer libraries to download needed data. If Internet Explorer does not have the initial configuration – “first-time run” – Sidra.exe may encounter exceptions originating in a non-initialized Internet Explorer.

PowerShell

Sidra.exe heavily relies on PowerShell and tests are not made to determine the lowest version possible. It is recommended usage of a recent version of Windows and/or PowerShell, such as Windows 10 or Windows Server 2016, with PowerShell 5.0+.

Azure CLI

Azure dependencies

Sidra.exe cannot assist with the following; these would need to be provisioned before attempting to using Sidra CLI tool:

  • Azure Active Directory
    • The target Azure Active Directory tenant must be created prior to launching the tool.
    • The tenant ID GUID will be needed to configure Sidra.exe.
  • Azure Subscription
    • Sidra.exe will create the needed Resource Groups and Azure resources under this subscription.
    • It is preferable to have a separate Subscription for each Sidra environment: dev, test, prod.
    • Authentication and authorization to these resources is partly based on App Registrations recorded in the above Azure Active Directory tenant.
  • Azure DevOps space and project with Git repository
    • The DevOps space (organization) with a dedicated project for Sidra and its corresponding Git repository must be provisioned.
    • Sidra code, automation pipelines, and variables, will be cloned from Plain Concepts’ space to this target.
    • Client applications consuming data ingested by Sidra installation will also have their source code in this space.

Identifiers, names, or URLs of the above constitute parameters for the other Sidra.exe commands.

Access rights

Given the sequence of operations that Sidra.exe will take, the engineer(s) running the tool will need to have the following access rights:

  • Machine: Administrator
    The user needs to be Administrator on the machine from where Sidra.exe will be executed, since the tool may need to install dependencies on the machine.
  • Subscription: Subscription Owner
    Since Sidra.exe will create Resource Groups, resources, and grant access rights to these, the user executing the corresponding commands will need to be a Subscription owner in the target customer’s Azure Subscription.
  • Azure Active Directory: Create and Manage Applications
    Since Sidra.exe will create Application Registration entries in the target customer’s Azure Active Directory tenant, the user executing the corresponding command(s) will need to have the needed access rights for creating and managing such entries as Application Administrator.
  • Azure DevOps: Project Administrator
    Sidra.exe will clone solution source files, CI/CD pipelines, and variables, to the target Azure DevOps space, the user executing the corresponding commands should have enough access rights to perform these actions.

Additionally, in DevOps, the Basic license is required; it is not enough to have a Stakeholder license.

Sequence of commands

The common flow of the tool usage is described below. The syntax is:

    sidra.exe [command] [option] [parameters]
Order Command Description
1 prerequisites Checks for the existence of dependencies or helps installing them if they are missing.
2 profile Persists those parameters that are needed in other commands, to avoid entering those over and over again. It is recommended to create a new profile before starting an installation process.
3 install Creates the Application Registrations, resources for automation, applications such as Power BI, etc.
4 deploy Copies code in the Azure DevOps repository, creates the CI/CD pipelines, applies templates to create Azure resources, updates the solution.
5 provider Manages the data Providers that will feed data to Sidra for ingestion, post installation.
6 customize Sets customization options, such as the user interface for Identity Server or password policies.

Summarizing, the process of setting up Sidra with the CLI tool goes down to using the following 4 commands, with their respective parameters:

    for each deployed environment
    do
        sidra profile create <parameters>
        sidra install aadapplications <parameters>
        sidra deploy source <parameters>
        sidra deploy configure <parameters>
        <execute deployment pipeline in DevOps project>

Consult the deployment documentation to see the specific sequence of steps that need to be taken using these commands. Each command and option may be invoked with a --help parameter to access the inline documentation of the tool:

    .\sidra.exe --help
    .\sidra.exe prerequisites --help
    .\sidra.exe profile create --help

Power BI Application for Sidra

Finally, as an additional setting, Power BI can be configured with the customer account in order to work with Sidra's report. You can see more details in the tutorial for Power BI.


Next: The Prerequisites command


Last update: 2022-04-19
Back to top