Version: On prem: 15.0.3

Omada Identity Ansible package

The purpose of the Omada Identity Ansible package is to provide you, our partners and customers, with the opportunity to automate the installation of the on-premises version of Omada Identity.

info

This feature is currently in Technical Preview. The goal of this preview phase is to gather initial customer feedback and ensure the feature reaches necessary parity with the Omada Identity Installation Tool.

What is Ansible?

Ansible is a well-known automation tool. For more information on how to use it alongside Windows servers, you can refer to the official Ansible documentation:

To learn more about getting started with Ansible on Windows and possible limitations, check the Windows Frequently Asked Questions.

Omada Identity Ansible cheat sheet

Linux text editors:
- Vim Text Editor Reference: Vim
- Nano Text Editor Reference: Nano
WSL Setup Guide: WSL Installation Guide

Use cases with Ansible

The following list covers example use cases for the Ansible package:

info

Utilize the resources in this package to address your own use cases and share your experiences via Omada Hub.

Installation of Omada Identity, it's components, and post-installation configuration/actions

Installation of Omada Identity components:

Enterprise Server
Role and Policy Engine
Omada Data Warehouse
Omada Provisioning Service
Data Preview
Standard Collector package deployment and registration
Standard Connector package deployment and registration
OData Omada Identity package deployment and registration

Post-installation tasks:

Portal initialization with Windows Integrated authentication
Setup of DB access for service users
Creation of SQL Agent user, proxies, and credential object
Feature package import
OPS and RoPE endpoints setup
Data connections update
Customer settings
Service users creation in Omada Identity portal
Archive DB initialization
ODW Imports trigger
- Import Configuration Import profile
- Import Import profile

Upgrade of Omada Identity and post-upgrade configuration/actions

Directory backup of Omada components
Uninstall and removal of existing directory of Omada components
Installation of Omada components:
- Enterprise Server
- Role and Policy Engine
- Omada Data Warehouse
- Omada Provisioning Service
- Data Preview
- Standard Collector package deployment
- Standard Connector package deployment
- OData Omada Identity package deployment
Post-upgrade tasks:
- Portal initialization
- Feature package import
- Customer settings
- Archive DB initialization
- ODW Imports trigger
  - Import Configuration Import profile
  - Import Import profile

Configuration of installed components

PSWencryptionKey
APISharedSecret
WebService Endpoints
Connection Strings

RoPE Engine Configuration

After upgrade, RoPE EngineConfiguration.config will be created from scratch. As a consequence, all customization done before the upgrade will need to be re-applied to the new file.

Future implementation

The following components are considered for future implementation:

Password rotation
Changeset merging and deployment
GMSA support

Ansible package file structure

The package contains a structured set of directories and files.

Playbooks

At the core, there are two playbooks:

installation_playbook.yml

Here is an example section of a playbook with comments:

---
- name: Enterprise Server play
  hosts: es  # Group of hosts for whose roles' tasks will run
  roles:     # List of roles which will be executed against the group of hosts
    - es
  tags:      # List of tags for more granular run options
    - es
  vars_files: # List of additional variable files, can be split into environment-related files
    - vars/main/main.yml
    - vars/main/users.yml

upgrade_playbook.yml

Here is an example section of a playbook with comments:

---
- name: Pre-upgrade tasks play
  hosts: pre_upgrade  # Group of hosts for whose roles' tasks will run
  roles:              # List of roles to be executed against the group of hosts
    - pre_upgrade
  tags:               # List of tags for more granular run options
    - pre_upgrade
  vars_files:         # List of additional variable files, can be split into environment related files
    - vars/main/main.yml
    - vars/main/users.yml

Variable files

Playbooks are supported by variable files:

vars/main/users.yml
vars/main/main.yml

These files contain all the information on how the environment should be configured.

Inventories

The environment landscape definition is kept in the hosts inventory file. It describes which Omada components run on which hosts. The path to this file is as follows: inventories/dev/hosts.

Role directories

A role directory represents a general goal to achieve or a topic to handle. For example, the role "es" (Omada Enterprise Server) defines everything needed to support the installation and upgrade tasks of the Omada Enterprise Server component. The "post_installation" role groups together all tasks related to what needs to be done after installing Omada components to initialize the environment and make it ready for consultants.

Here is a short explanation of some subdirectories and files typically found in a role directory:

README.md - provides basic information about role requirements and examples of how to use it.
defaults/main.yml - contains default values required for the role to work properly.
tasks/main.yml - orchestrates all tasks to be run in this role.
tasks/*.yml - other YAML files containing specific task or action code.
templates - contains Jinja2 template files used for component configuration or other tasks.

Installation and upgrade prerequisites

Before proceeding with the Omada Identity Ansible package installation or upgrade, the following prerequisites are expected to be present and working in the environment:

SQL Server DB Engine in a supported version
SQL Server Integration Services in a supported version
SQL Server Reporting Services in a supported version
- Connection to the DB engine is configured
- ReportServer endpoint is reachable
- Reports endpoint is reachable
- Ansible user is granted full access to ReportServer endpoint in order to load reports definitions
Set of domain users for service run purposes
SPNs (Server Principal Name) set for:
- Omada Identity portal (forms authentication is not yet supported by the package)
- SSRS (unless you decide to use a specific SSRS access account)
- SQL Server (unless you decide to use local SQL Server accounts)
The user used by Ansible to control target Windows Server nodes needs to be a Local Administrator and SYSADMIN in DB engines across the environment.
All software and sizing prerequisites are the same as for a standard installation. For more information, refer to the Omada Identity Installation guide.
Additionally, an Ansible control node to run Ansible playbooks is required. Furthermore, communication between the Ansible control node and Windows Server nodes in the environment is necessary. Check here for details:
- Windows Remote Management | Ansible Community Documentation
- Using Ansible and Windows | Ansible Community Documentation

Define hosts file

The optimal approach is to begin by defining your environment's hosts file.

Exemplary host file with comments

app1 ansible_host=app-st01.corporate.com
ssrs1 ansible_host=app-st01.corporate.com
ssis1 ansible_host=app-st01.corporate.com
ops1 ansible_host=app-st01.corporate.com
web1 ansible_host=web-st01.corporate.com
# You can define more servers if needed.
# Just add an alias and define host and remember to add it to appropriate group later one.
#web2 ansible_host=web-st02.corporate.com
rope1 ansible_host=web-st01.corporate.com instances=2
rope2 ansible_host=app-st01.corporate.com instances=2
#vault1 ansible_host=app-st01.corporate.com
preview_collector1 ansible_host=app-st01.corporate.com
preview_preview1 ansible_host=web-st01.corporate.com
db1 ansible_host=db-st01.corporate.com

# Do not modify controller line below
controller ansible_host=localhost ansible_connection=local

# "es" group of hosts, used to define all hosts where Omada Enterprise Server should be installed
[es]
web1
#web2

# "rope" group of hosts, used to define all hosts where Omada Role and Policy Engine should be installed
[rope]
rope1
rope2

# "ssrs" group of hosts, used to define all hosts where Omada Data Warehouse should be installed to support Reporting feature
[ssrs]
ssis1

# "ssis" group of hosts, used to define all hosts where Omada Data Warehouse should be installed to support SSIS/import feature
[ssis]
ssis1

# "odw" group of hosts, used to define all hosts where Omada Data Warehouse should be installed
[odw:children]
ssis
ssrs

# "ops" group of hosts, used to define all hosts where Omada Provisioning Service should be installed
[ops]
ops1

[preview_preview]
preview_preview1

[preview_collector]
preview_collector1

[data_preview:children]
preview_preview
preview_collector

#[vault]
#vault1

# "pre_upgrade" group of hosts, used to define all hosts where pre_upgrade role should run
[pre_upgrade:children]
es
rope
odw
ops
data_preview
#vault

# "post_upgrade" group of hosts, used to define all hosts where post_upgrade role should run
[post_upgrade:children]
es
rope
odw
ops
data_preview
#vault

# "post_intallation" group of hosts, used to define all hosts where post_intallation role should run
[post_installation:children]
es
rope
odw
ops
data_preview

# "all" general group of hosts
[all:children]
es
rope
ops
odw
data_preview

# vars section, used to define connection details for Windows Server nodes
[post_installation:vars]
ansible_user=corporate\demoadm
ansible_password=otn1!IAGvendor
ansible_port=5986
ansible_connection=winrm
ansible_winrm_transport=credssp
ansible_winrm_server_cert_validation=ignore

Define variable files

The next step in preparing for the Omada Identity Ansible package installation/upgrade is to ensure all variables are provided in variable files.

Exemplary vars\main\main.yml file with comments

---
# Do not modify
installers_path: "{{ installation_binaries }}\\Install"
log_path: "{{ installation_binaries }}\\Logs"
timestamp: '{{ lookup(''pipe'', ''date "+%Y%m%d_%H%M%S"'') }}'
db_access_rights: db_owner
timer_service: OETSVC
# Do not modify

## KEEP attention to the version!
# Path on target host where installation binaries are present
omada_packages: "C:\\OmadaInstall"
installation_binaries: "{{ omada_packages }}\\Omada Identity v15.0.3.13\\Omada Identity v15.0.3.13"
collectors_path: "{{ omada_packages }}\\Omada.Connectivity.StandardCollectors.15.0.0.225"
connectors_path: "{{ omada_packages }}\\Omada.Connectivity.StandardConnectors.15.0.0.238"
odata_omada_identity_path: "{{ omada_packages }}\\Omada.Connectivity.OData.OmadaIdentity.15.0.0.188"
new_ui_path: "{{ omada_packages }}\\Omada Identity v15.0.3.13 New UI Changesets\\Omada Identity v15.0.3.13 New UI Changesets"
data_preview_path: "{{ omada_packages }}\\Omada Identity v15.0.3.13 Data Preview Service"
third_party: "{{ omada_packages }}\\ThirdParty"

# Specify .net binaries version, use latest version avaialable
dot_net_version: "8.0.15"

# Full path to backup directory
backup_path: "C:\\OmadaBackup"

# Customer's License Key
license_key: "company=Omada;address1=Østerbrogade 135;address2=2100 Copenhagen;address3=Denmark;contact=Frank Larsen;exp_date=30122099;issue_date=16102017;lictype=1;usr_limit=0;id_limit=0;proctmpl_limit=0;modules=OMADADATAWAREHOUSE,ODWGENERIC,ODWSAP,SURVEY_MODULE,SOD_MODULE,AO_MODULE,SAP_MA,OIS,PASSWORDRESET,OPS,EXCHANGE,CIAM_MODULE;signature=Eb3CMgy6eNGH5u47Pwof2ddqRzlz6jHUvqTl324wkBgZ8dUIYHMXNA=="
customer_name: "Omada"

# Define Feature Package import mode, default is FULL.
# Possible values are:
# FULL >> imports all Omada features, for upgrade scenario IDENTITYGOVERNANCE feature is removed from the list.
# CORE >> imports only CORE set of features
# CUSTOM >> fill in below variable to define comma delimited list of Features to be imported
# MANUAL >> There will be a prompt during playbook run to remind you that's the time to go to the portal and import features.
# Once step is confirmed playbook will continue.
feature_packages_import_mode: "FULL"
custom_feature_package_list: ""

drive_letter: C
es_install_result_path: "{{ drive_letter }}:\\Program Files\\Omada Identity Suite\\Enterprise Server"
ops_install_result_path: "{{ drive_letter }}:\\Program Files\\Omada Identity Suite\\Provisioning Service"
rope_install_result_path: "{{ drive_letter }}:\\Program Files\\Omada Identity Suite\\Role and Policy Engine"
odw_install_result_path: "{{ drive_letter }}:\\Program Files\\Omada Identity Suite\\Datawarehouse"
preview_install_result_path: "{{ drive_letter }}:\\Program Files\\Omada Identity Suite\\Preview"
vault_install_result_path: "{{ drive_letter }}:\\Program Files\\Omada Identity Suite\\Vault Service"

backup_list:
  [
    "{{ es_install_result_path }}",
    "{{ ops_install_result_path }}",
    "{{ rope_install_result_path }}",
    "{{ odw_install_result_path }}",
    "{{ preview_install_result_path }}",
    "{{ vault_install_result_path }}",
  ]
omada_registry: HKLM:\SOFTWARE\Omada\

# Domain Base Name
# Example Full Domain Name >> corporate.com
# Domain >> corporate
domain: corporate
full_domain: "{{ domain }}.com"
# Data Store DB NetBios Name or DNS alias
# It's an example variable filter to get hostname from hosts file, if you want to go for FQDN then remove "| split('.') | first" 
# to fetch whatever you have in hots behind db1 server
data_store_db_server: "{{ hostvars['db1'].ansible_host | split('.') | first }}" 
# Data Store DB access port
data_store_db_port: 1433

# SSIS DB Server NetBios name
# It's an example variable filter to get hostname from hosts file, if you want to go for FQDN then remove "| split('.') | first" 
# to fetch whatever you have in host behind ssis1 server
ssis_db_server: "{{ hostvars['ssis1'].ansible_host | split('.') | first }}"
# SSIS DB Access Port
ssis_db_port: "1433"
# SSIS installation path, please mind the version yo have on the server side
ssis_binn_path: 'C:\Program Files\Microsoft SQL Server\140\DTS\Binn\' # It's in a different format than other PATHs on purpose.
# Version of ODW component package based on SSIS version
ssis_sql_server_version: "2017"

# db names for each Omada components
es_db: "OIS"
ssddb_db: "SSDDB"
es_archive_db: "OISA"
rope_db: "ROPE"
ops_db: "OPS"
odw_staging_db: "ODWS"
odw_master_db: "ODWM"
odw_db: "ODW"

# Define authentication type against SQL Server
# It will be used further in data connection strings
# However, how Invoke-SQLCmd is invoked is decided based on presence of {{ db_user_pwd }} variable
# Consequently these two matters have been decoupled.
db_connstr_authentication: "Integrated Security=SSPI"
# db_connstr_authentication: 'user id={{ db_user }};password="{{ db_user_pwd }}"'

# DB collation for ES/SSDDB/ES_ARCHIVE DBs
# All the other DBs are created by product installers and come with default collation
db_collation: "SQL_Latin1_General_CP1_CI_AS"

# Remember to provide here ";" at the begining and it need to be missing at the end,
# example: ";trusted_connection=yes;use encryption for data=false;trustservercertificate=yes"
connstr_options: ""
# connstr_provider: "provider=SQLNCLI11"
connstr_provider: "Provider=MSOLEDBSQL19"
es_connstr: "initial catalog={{ es_db }};data source={{ data_store_db_server }};{{ db_connstr_authentication }}{{ connstr_options }}"
ssddb_connstr: "initial catalog={{ ssddb_db }};data source={{ data_store_db_server }};{{ db_connstr_authentication }}{{ connstr_options }}"
es_archive_connstr: "initial catalog={{ es_archive_db }};data source={{ data_store_db_server }};{{ db_connstr_authentication }}{{ connstr_options }}"
rope_connstr: "initial catalog={{ rope_db }};data source={{ data_store_db_server }};{{ db_connstr_authentication }}{{ connstr_options }}"
ops_connstr: "initial catalog={{ ops_db }};data source={{ data_store_db_server }};{{ db_connstr_authentication }}{{ connstr_options }}"
odw_staging_connstr: "initial catalog={{ odw_staging_db }};data source={{ data_store_db_server }};{{ db_connstr_authentication }}{{ connstr_options }}"
odw_master_connstr: "initial catalog={{ odw_master_db }};data source={{ data_store_db_server }};{{ db_connstr_authentication }}{{ connstr_options }}"
odw_connstr: "initial catalog={{ odw_db }};data source={{ data_store_db_server }};{{ db_connstr_authentication }}{{ connstr_options }}"

# Variable based on which service is installed with domain service account or built-in Local service account
auth_type: "domain" # Anything <> "local" triggers domain account service setup
# auth_type: "local" # "local" triggers built-in local service account setup

# Service Users for Omada components
db_user: "omada_db_user" # to be used alongside SQL Server user instead of SSPI
es_service_user: "srvc_oi_st01" # Timer Service and APP Pool user
rope_service_user: "srvc_rope_st01" # RoPE Service user
ops_service_user: "srvc_ops_st01" # OPS Service User
preview_collector_service_user: "srvc_oi_st01"
preview_preview_service_user: "srvc_oi_st01"
sql_agent_user: "srvc_oi_st01" # User to run SQL Agent job
reporting_user: "srvc_oi_st01" # User to access SSRS Server
app_pool_user: "srvc_oi_st01" # Application Pool Service User
ssis_agent_user: "srvc_oi_st01" # Not yet in use
ssrs_access_user: "srvc_oi_st01" # Not yet in use
ansible_installation_user: demoadm # Installation user, later used for first Omada portal access via Windows Integrated Auth

# Enterprise Server website configuration
# HTTPS is not yet supported
es_mode: http
es_web_config: "Web.config"
es_binding: web-st01
es_app_pool: "{{ es_binding }}"
es_http_binding_port: 80
es_https_binding_port: 443
# In multi-node setup(more than one website server) this variable should be placed in inventories/dev/host_vars/webX.yml, where X is number of a website server in hosts file.
# It will allow for automatic usage of hosts specific certificate thumbprint.
es_certificate_thumbprint: ""

# Role and Policy Engine listener configuration
# HTTPS is not yet supported
rope_mode: http
rope_binding: "oi-rope-test01"
rope_http_binding_port: 8010
rope_https_binding_port: 8011
# Same note as above applies for multi-node RoPE deployments
rope_certificate_thumbprint: ""

# Omada Provisioning Service listener configuration
# HTTPS is not yet supported
ops_mode: http
ops_binding: "oi-ops-test01"
ops_http_binding_port: 8000
ops_https_binding_port: 8001
ops_auth_behavior: "ProvisioningServiceServiceBehaviorApiSharedSecret"
# Same note as above applies for multi-node OPS deployments
ops_certificate_thumbprint: ""

# SSRS ReportServer WebService endpoint
ssrs_report_server_url_ws: "http://app-st01/ReportServer"
# SSRS installation Path at target host
ssrs_installation_path: "C:\\Program Files\\Microsoft SQL Server Reporting Services\\SSRS\\ReportServer"

# Update at your best will and knowledge Customer Settings you would like to have configured as part of deployment.
# If Customer Setting listed here does not exists in the tblCusomterSetting table then INSERT will take place.
# As of now INSERT supports only 'key' and 'value' as input. NAME, DESCRIPTION ... are not supported.
customer_settings_value_str:
  - { key: "SSRSUrl", value: "{{ ssrs_report_server_url_ws }}" }
  - {
    key: "RoPERemoteApiUrl",
    # It's an example variable filter to get hostname from hosts file, if you want to go for FQDN then remove "| split('.') | first" 
    # to fetch whatever you have in host behind db1 server
    value: "{{ rope_mode }}://{{ hostvars['rope1'].ansible_host | split('.') | first }}:{{ rope_http_binding_port }}/RoPERemoteApi/",
  }
  # - {key: "SSISExecutionUser", value: "NULL" }
  # - {key: "SSISExecutionUserPassword", value: "NULL" }
  - { key: "SSISInstallationPath", value: "{{ ssis_binn_path }}" }
  - { key: "SSISServer", value: "{{ ssis_db_server }}" }
  - {
    key: "SqlAgentJobProxyAccountName",
    value: "{{ domain }}\\{{ es_service_user }}",
  }
  - { key: "SqlAgentJobServerInstance", value: "{{ ssis_db_server }}" }
  - { key: "SqlAgentJobSSISServerInstance", value: "{{ ssis_db_server }}" }
  - { key: "ItemsPerPage", value: "20,40,200,1000" }
  - {
    key: "StagingHostingServiceHost",
    value: "{{ hostvars['preview_collector1'].ansible_host | split('.') | first }}",
  }
  - {
    key: "StagingPreviewServiceHost",
    value: "{{ hostvars['preview_preview1'].ansible_host | split('.') | first }}",
  }

customer_settings_value_int:
  - { key: "StagingPreviewServicePort", value: "5001" }
  - { key: "StagingHostingServicePort", value: "5002" }
# Set appropriate value to 1 depending on the import method of your choice
# For Single Server setup both must be 0
# For other setups please use "SqlAgentJobUse" = 1
customer_settings_value_bool:
  - { key: "SSISUseKerberos", value: "0" }
  - { key: "SqlAgentJobUse", value: "1" }

Exemplary vars\main\users.yml file with comments

# Provide passwords for service users
# Provide passwords for service users
es_service_user_pwd: "Onew12345!"
rope_service_user_pwd: "Onew12345!"
ops_service_user_pwd: "Onew12345!"
app_pool_user_pwd: "Onew12345!"
ssis_agent_user_pwd: "Onew12345!"
ssrs_access_user_pwd: "Onew12345!"
preview_preview_service_user_pwd: "Onew12345!"
preview_collector_service_user_pwd: "Onew12345!"

# db_user_pwd: "Omada12345!"
db_user_pwd: ""
# Provide values
psw_encryption_key: "SomeEncryptionKey"
api_shared_secret: "SomeAPISharedSecret"

The above file examples are shown in plain text, but the recommended approach is to encrypt them using the ansible-vault utility to enhance security. Here's the exemplary encryption:

ansible-vault encrypt vars/main/users.yml

New Vault password:

Confirm New Vault password:

Encryption successful

After encryption, the content of the file looks as follows:

$ANSIBLE_VAULT;1.1;AES256
65326331666563626564336636396536363165386138376S63373638B23366396139323439653664
33653234343662333236386561376S3661356436663139330a3735346S3831626233383938616137
65363436666433313330613661663538306239366630353133656138643465386434326564373163
3064353637336338630a326461623233616337376563636431613866623639626238333433373132
34656266323635383734616539376462643235313464316132626261396135343861323534636265
37666664623537633536353163663239663436626365366662303065623038303364343532323035
37356230343339396535623861393862646130616230643361383636343031306636376165376266
34353961666666366334316239353936333435613764613830626435306436303566613931323333
62613437323933336132636133313338373533336364313363353238373630303463663139303335
34613031666361353761393434346461323331313234326136326164363438653139336137373662
66373463646363303436393035663362363763393162313739363034323030306236316634363564
39323266343966306536633631333263623733393666393832643531623235336433616238636564
61343266616365633163623731663635623564336164656366643862373463323566363630313462
33396234303765383233653661353538396265356666336436343563356136316239326466353563
63613836343664366361633564663639643333373262646130376464333261646236626530366361
64633563633361303631666138626266316439393666313365306235383435376232663234353731
36336431303037306435373263313232616531663231613839656563316462383933633136653066
62343963316162636135353966613732396464313166663139613533393037373330303566336464
363066643231306538376236333835663739

However, furthermore, to edit the file, you need to use ansible-vault:

ansible-vault edit vars/main/users.yml

Vault password:

For information on the ansible-vault, refer to the Protecting sensitive data with Ansible vault documentation.

Upload installation files on all servers

The expectation is to have a single directory containing installation binaries, structured as shown below:

This comprises the standard contents of unpacked installation zip packages, along with additional directories for Third-party and Connectivity packages:

The Third-party directory contains all third-party software required for Omada installation.

However, if you would like to use different structure of packages then please adjust accordingly vars\main\main.yml to reflect your won structure.

info

At this moment, the Third-party directory is not provided as a package.

Installation steps

note

Before proceeding with installation steps, make sure you've completed all tasks described in the Installation and upgrade prerequisites section.

Run installation playbook

Installation playbook can be triggered in various ways.

For a holistic approach, use the following command:
```
ansible-playbook -i inventories/dev/hosts installation_playbook.yml --tags install
```
This command executes all installation tasks defined in the playbook.
For a more specific approach, use the following command to run the installation for a particular component in Omada Identity:
```
ansible-playbook -i inventories/dev/hosts installation_playbook.yml --tags install --skip-tags rope,ops,odw,data_preview,post_installation,post_installation_es
```
Due to the ambiguity of Ansible tags inheritance, this method is the only way to execute installation for just one Omada component. In the example above, the installation is executed solely for the Enterprise Server (the only tag NOT skipped). Additional examples can be found in the role's README.md file.

tip

To run a playbook with ansible-vault encrypted files, use the following command:

ansible-playbook -i inventories/dev/hosts installation_playbook.yml --tags install --skip-tags rope,ops,odw --ask-vault-pass 

To check which tasks will be executed when you are uncertain about tags used, use the following command:

ansible-playbook -i inventories/dev/hosts installation_playbook.yml --tags install --skip-tags rope,ops,odw --list-tasks 

Upgrade steps

Prerequisites

note

Before proceeding with installation steps, make sure you've completed all tasks described in the Installation and upgrade prerequisites section.

The upgrade runbook encompasses steps outlined in the upgrade guides available in the Upgrade guides section.

Software requirements can be reviewed in the Installation guide section.

However, Omada recommends to double-check to ensure all necessary steps are covered, ensuring a seamless upgrade experience.

Run upgrade playbook

Upgrade playbook can be triggered in various ways.

For a holistic approach, use the following command:
```
ansible-playbook -i inventories/dev/hosts upgrade_playbook.yml --tags upgrade 
```
This command executes all upgrade tasks defined in the playbook.
For a more specific approach, use the following command to run the upgrade for a particular component in Omada Identity:
```
ansible-playbook -i inventories/dev/hosts upgrade_playbook.yml --tags upgrade --skip-tags rope,ops,odw,post_upgrade,post_upgrade_es 
```
Due to the ambiguity of Ansible tags inheritance, this method is the only way to execute upgrade for just one Omada component. In the example above, the upgrade is executed solely for the Enterprise Server (the only tag not skipped). Additional examples can be found in the role's README.md file.

tip

To run a playbook with ansible-vault encrypted files, use the following command:

ansible-playbook -i inventories/dev/hosts upgrade_playbook.yml --tags upgrade --skip-tags rope,ops,odw --ask-vault-pass 

To check which tasks will be executed when you are uncertain about tags used, use the following command:

ansible-playbook -i inventories/dev/hosts upgrade_playbook.yml --tags upgrade --skip-tags rope,ops,odw --list-tasks 

Considerations and limitations

Known issues and missing features

This consolidated list highlights known issues and features that are not yet implemented or covered in the current setup:

Initial surveys import
Language packages import
SQL Server local account authentication is not yet fully supported:
- If user/password authentication is defined in connection strings in the main.yml var file, it will overwrite configuration files and data connections to the desired state.
- Encryption of connection strings in Datawarehouse\Common\Omada ODW WebService.dtsConfig is not covered yet and needs to be done manually after installation.
- In general, passwords in data connections will not be encrypted.

Sometimes after deinstallation of Enterprise Server, deletion of the directory fails, and it needs to be removed manually to ensure proper upgrade. Example error message:

TASK [es : Delete folder]
fatal: [web1]: FAILED! => {"changed": false, "msg": "Failed to delete C:\\Program Files\\Omada Identity Suite\\Enterprise Server\\website\\Themes\\Default\\Infragistics\\structure\\Fonts\\jquery-ui.ttf: Access to the path 'C:\\Program Files\\Omada Identity Suite\\Enterprise Server\\website\\Themes\\Default\\Infragistics\\structure\\Fonts\\jquery-ui.ttf' is denied."}

Need to know

Tasks for which errors are ignored on purpose:
- Certain tasks may result in errors, indicated by red text, for example:
- The message "...ignoring" signifies that the error has been deliberately ignored, allowing the playbook to continue executing.
- The ignore_errors flag is used to achieve this. However, it's important to review ignored errors, as they may lead to subsequent task failures.
Re-run tasks creating a log file:
- Some tasks are designed to run only when a log file is not already created.
- For instance, the task in the post_upgrade role at Omada.Identity.Ansible\roles\post_upgrade\tasks\230_run_imports.yml creates a log file "{{ LOG_PATH }}\import_configuration_profile.log" during its execution. Subsequently, it won't run again if the log file already exists.
- When re-running such tasks, ensure to delete the existing log file.
Import product packages default behavior:
- In the post_installation and post_upgrade roles, task #150 is responsible for importing new product features, located at Omada.Identity.Ansible\roles\post_upgrade\tasks\150_import_product_packages.yml.
- By default, it imports all feature packages regardless of the license string. If there are unlicensed features, consider using an alternative task to import only the core set of features, or use Custom list of features you would like to import.
- To switch to the alternative task, edit Omada.Identity.Ansible\vars\main\main.yml section related to feature packages import:
```
# Define Feature Package import mode, default is FULL.
# Possible values are:
# FULL >> imports all Omada features, for upgrade scenario IDENTITYGOVERNANCE feature is removed from the list.
# CORE >> imports only CORE set of features
# CUSTOM >> fill in below variable to define comma delimited list of Features to be imported
# MANUAL >> There will be a prompt during playbook run to remind you that's the time to go to the portal and import features.
# Once step is confirmed plaubook will continue.
feature_packages_import_mode: "FULL"
custom_feature_package_list: ""
```
RoPE multi-instance approach in package:
- The package supports adding multiple RoPE service instances, all using the same directory as the source. Consequently, all instances will utilize the same settings and configuration.
- For example, if specific priority calculation is desired for certain instances, manual configuration is necessary. For more information, refer to the Multiple instances of RoPE section in the Installation guide.
New tags for each role:
- Each Omada Identiyt component role got new tags for ease of usage in spearate cases, examples:
  - <role>_features - to cover Windows features for specific role
  - <role>_third_party - to cover third party applications for specific role
  - <role>_install - to install only a specific Omada component
  - <role>_config - to configure files related to a specific role

What is Ansible?​

Use cases with Ansible​

Ansible package file structure​

Playbooks​

Variable files​

Inventories​

Role directories​

Installation and upgrade prerequisites​

Define hosts file​

Define variable files​

Upload installation files on all servers​

Installation steps​

Run installation playbook​

Upgrade steps​

Prerequisites​

Run upgrade playbook​

Considerations and limitations​

Known issues and missing features​

Need to know​

What is Ansible?

Use cases with Ansible

Ansible package file structure

Playbooks

Variable files

Inventories

Role directories

Installation and upgrade prerequisites

Define hosts file

Define variable files

Upload installation files on all servers

Installation steps

Run installation playbook

Upgrade steps

Prerequisites

Run upgrade playbook

Considerations and limitations

Known issues and missing features

Need to know