Getting started with Babylon¶

This is a guide to getting started with Babylon. You'll learn how to install, run, and experiment with the Babylon.

Azure requirements¶

Requirements

The following elements are required before you can use Babylon on an Azure subscription

Fully set up Cosmo Tech Platform installed on your Azure Tenant
App registration for Babylon

Babylon uses a Service Principal to interact with the API and other resources. To do so, Babylon needs to be registered as an application in the Azure Active Directory.

This App Registration will be used to authenticate and get the required tokens to connect to your Platform. Rights on the App Registration depends on the type of connection you want to make.

We recommend defining this app registration as a mobile and desktop application in Azure configuration with redirection URL (mostly for authenticating against Azure services.

See official documentation :

* https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow
* https://learn.microsoft.com/en-us/entra/identity-platform/msal-client-application-configuration
* https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/msa-oauth?view=odsp-graph-online

The App registration needs the following API permissions:

Microsoft Graph
- Application.ReadWrite.All (Application)
- Application.ReadWrite.OwnedBy (Application)
- Group.ReadWrite.All (Application)
Platform Api
- Platform.Admin (Application)

For those concerned with specifics Azure policies, all Microsoft Graph's permissions can be deleted excepted User.Read.All (Application), but this implies that some operations would be handled manually. The platform API permission is mandatory.

Important

Babylon App registration needs at least Contributor role on Cosmo Tech Platform Resource Group.

Get Babylon from source¶

Requirements

Python 3.10+
Pip 22.2+
Git (latest version)

We will go through the process of getting a version of Babylon before the installation.

Get sources from git

You can download the latest version of Babylon using git clone command

git clone git@github.com:Cosmo-Tech/Babylon.git babylon

cd babylon

Get the specific version from git

If you want a specific version of Babylon (3.0.0 for example)

git clone -b 3.0.0 git@github.com:Cosmo-Tech/Babylon.git babylon

cd babylon

Install Babylon¶

You can install babylon globally in your system

pip install .

Now that you have a fully functional installation of Babylon, you can check the next steps to learn how to start running commands.

Setup Babylon¶

Babylon use a Vault service and provides a group of commands that can be used.

The first thing to do in order to check if Babylon is working properly:

babylon --help

Setup environment variables¶

The vault service is required to work with babylon cli. Contact your babylon admin to get your URI service and your userpass.

Set URI vault service.

export BABYLON_SERVICE=<uri_babylon_vault_server>

Now, you will need set some environment variables before interacting with Babylon cli. To do so, perform the login command.

Login and get an access token.

babylon hvac login

questions:

[?] Username: <username>
[?] Password: ****
[?] Organization: <organization_name>

Copy the response and paste it in your environment.

If entries does not exist, you may need to create it (e.g. for a newly deployed platform): We provide a tool for this, you can find it here This needs an initial Terraform deployment as it uses the Terraform state to parse and populate the Vault. Useful information can be found in the Readme of this repository !

Configuration¶

At this point, you will need three variables to perform Babylon commands.

context_id : project name
platform_id : platform name
state_id: state name

context_id and state_id can be strings of your choice, but they cannot contain special characters. platform_id represents the id of the platform, such as dev, staging, etc. To initialize it, perform this command:

babylon namespace use -c <context_id> -p <platform_id> -s <state_id>

It will be saved in a local file /home/.config/cosmotech/babylon/namespace.yaml

You can now test Babylon by performing a simple command, e.g.:

babylon api organizations get-all

Initial configuration will be retrieved from vault and saved in Azure Storage and in local file /home/.config/cosmotech/babylon/state_id.yaml

State file specification¶

If state file doesn't exist, the first babylon command you launch will create one and store it in Azure Storage and in /home/.config/cosmotech/babylon/<state_id>.yaml file in local.

You will find three main sections:

files: []
id: teststate
services:

The last one contains following keys with some information already prefilled with data from vault:

Azure Container Registry

  acr:
    login_server: 
    simulator_repository: 
    simulator_version:

Azure Digital Twins

  adt:
    built_owner_id: 
    built_reader_id: 
    digital_twin_url:

Azure Explorer Database

  adx:
    built_contributor_id: 
    built_owner_id: 
    cluster_name: 
    cluster_principal_id: 
    cluster_uri: 
    database_name:

Cosmotech API

  api:
    connector.adt_id: 
    connector.adt_version: 
    connector.storage_id: 
    connector.storage_version: 
    connector.twin_id: 
    connector.twin_version: 
    dataset.adt_id: 
    dataset.storage_id: 
    dataset.twin_id: 
    organization_id: 
    organization_url: 
    run_templates: 
    scope: 
    send_scenario_metadata_to_event_hub: 
    solution_id: 
    url: 
    use_dedicated_event_hub_namespace: 
    workspace_id: 
    workspace_key:

Azure App Registration

  app:
    app_id: 
    name: 
    object_id: 
    principal_id:

Azure

    azure:
      cli_client_id:
      email: 
      eventhub_built_contributor_id:
      eventhub_built_data_receiver:
      eventhub_built_data_sender:
      function_artifact_url: 
      resource_group_name: 
      resource_location: 
      storage_account_name: 
      storage_blob_reader: 
      subscription_id:
      team_id:
      user_principal_id:

Azure Babylon App Registration

    babylon:
      client_id: 
      principal_id:

Github

    github:
      branch: 
      organization: 
      repository: 
      run_url: 
      workflow_path:

Cosmotech Platform

    platform:
      app_id: 
      principal_id: 
      scope_id:

PowerBI

    powerbi:
      dashboard_view: 
      scenario_view: 
      scope: 
      workspace.id:
      workspace.name:

WebApp

    webapp:
      deployment_name: 
      enable_insights: 
      hostname: 
      insights_instrumentation_key: 
      location: 
      static_domain: