GUI whitelabel runtime system

[BryanMLima]

Description

1. Problem description

Currently ACS allows the GUI personalization (color changing, add a personalized logo, and so on); however, those configurations are set for the whole environment, which does not allow Apache CloudStack to have a personalized GUI by domain, account and so on. In a scenario of cloud providers reselling the infrastructure, the current behavior does not allow the operators to personalize the GUI for each use case (reseller, domain, account, and so on).

2. Proposed Changes

This spec introduces the concept of Runtime White Label to the Apache CloudStack GUI, which combines the market concept of White Label and enables it to be configured in runtime and by scope (domain, account, and so on). Briefly, we will introduce APIs to allow the operators to define GUI themes for a set of Internet common names (fixed or wildcard), a set of ACS domain UUIDs (also known as ID for the end-user), and a set of ACS account UUIDs (also known as ID for the end-user). The APIs will receive the CSS and JSON configuration as parameter and will store them into the database. When accessing Apache CloudStack, the UI will retrieve the CSS and JSON configurations according to the access definition and import them into the browser. If there are no themes match, the GUI will fallback to the current environment configuration.

Operations that create/modify/remove the themes will be registered with events in ACS.

2.1. Database model

A table named gui_themes will be created in the cloud schema and will have the following columns:

Name	Type	Nullable	Default	Description
id	bigint(20) unsigned	No	Auto increment	-
uuid	varchar(40)	No	null	-
name	varchar(2048)	No	null	A name to identify the theme.
description	varchar(4096)	Yes	null	A description for the theme.
css	text	Yes	null	The CSS to be retrieved and imported into the GUI when matching the theme access configurations.

Name	Type	Nullable	Default	Description
json_configuration	text	Yes	null	The JSON with the configurations to be retrieved and imported into the GUI when matching the theme access configurations.
common_names	text	Yes	null	A set of Internet common names (fixed or wildcard) separated by comma that can use the theme; e.g.: *acme.com,acme2.com.
domain_uuids	text	Yes	null	A set of [ACS] domain IDs separated by comma that can use the theme.
account_uuids	text	Yes	null	A set of [ACS] account IDs separated by comma that can use the theme
is_public	boolean	Yes	true	Defines whether a theme can be retrieved by anyone when only the common_names is informed. If the domain_uuids or account_uuids is informed, it is considered as false.
created	datetime	No	null	When the theme was created.
removed	datetime	Yes	null	When the theme was removed.

2.2. APIs

Right below there are the descriptions of the APIs to be introduced to allow the management of GUI themes by scope.

2.2.1. createGuiTheme

The API createGuiTheme will be accessible only by the operators (Root Admin accounts) and will allow them to create themes for several scopes. It will have the following parameters:

Parameter	Description	Mandatory	Type	Default value	Length
name	A name to identify the theme.	Yes	String	null	2048
description	A description for the theme.	No	String	null	4096

Parameter	Description	Mandatory	Type	Default value	Length
css	The CSS to be retrieved and imported into the GUI when matching the theme access configurations.	No	String	null	65535
jsonconfiguration	The JSON with the configurations to be retrieved and imported into the GUI when matching the theme access configurations. More details about the JSON configurations can be found in the JSON Configurations session.	No	String	null	65535
commonnames	A set of Internet common names (fixed or wildcard) separated by comma that can retrieve the theme; e.g.: *acme.com,acme2.com	No	String	null	65535
domainids	A set of [ACS] domain UUIDs (also known as ID for the end-user) separated by comma that can retrieve the theme.	No	String	null	65535
accountids	A set of [ACS] account UUIDs (also known as ID for the end-user) separated by comma that can retrieve the theme	No	String	null	65535
ispublic	Defines whether a theme can be retrieved by anyone when only the domainnames is informed. If the domainids or accountids is informed, it is considered as false.	No	Boolean	true	-

Either css or jsonconfiguration parameter must be informed for the GUI theme creation. If neither commonnames, domainids, and accountids is defined, the theme will be considered as the default; there can exist only one default theme and it automatically will be public. If there are no themes match, the GUI will fallback to the current environment configuration.

2.2.2. listGuiThemes

The API listGuiThemes will be accessible by anyone and will retrieve the themes according to the parameters and the caller access. It will have the following parameters:

Parameter	Description	Mandatory	Type	Default value	Length
id	The theme ID.	No	String	null	40
name	The name of the theme.	No	String	null	2048
commonname	The Internet common name to be filtered.	No	String	null	256
domainid	The UUID (also known as ID for the end-user) of the domain to be filtered.	No	String	null	40
accountid	The UUID (also known as ID for the end-user) of the account to be filtered.	No	String	null	40
listall	Whether to list all themes.	No	Boolean	false	-
listremoved	Whether to list removed themes.	No	Boolean	false	-
ispublic	Whether to list public themes. By default, it lists them all.	No	Boolean	null	-
listonlydefaulttheme	Whether to list only the default theme. If this parameter is true, than all other parameters are ignored.	No	Boolean	false	-

In order to allow the theme to be displayed yet in the login web page, it will be possible to call this API without authentication; however, there will be limitations and all the parameters will be ignored. An unauthenticated call to the API listGuiThemes will retrieve no entry or only a single entry; the single entry will be the default theme or the public, most recently, and active theme that matches the Internet common name requesting the API.

2.2.3. updateGuiTheme

The API updateGuiTheme will be accessible only by the operators (Root Admin accounts) and will allow them to update a theme. It will have the following parameters:

Parameter	Description	Mandatory	Type	Default value	Length
id	The ID of the theme to be updated.	Yes	String	null	40
name	A name to identify the theme.	No	String	null	2048
description	A description for the theme.	No	String	null	4096
css	The CSS to be retrieved and imported into the GUI when matching the theme access configurations.	No	String	null	65535
jsonconfiguration	The JSON with the configurations to be retrieved and imported into the GUI when matching the theme access configurations. More details about the JSON configurations can be found in the JSON Configurations session.	No	String	null	65535
commonnames	A set of Internet common names (fixed or wildcard) separated by comma that can retrieve the theme; e.g.: *acme.com,acme2.com	No	String	null	65535
domainids	A set of [ACS] domain UUIDs (also known as ID for the end-user) separated by comma that can retrieve the theme.	No	String	null	65535
accountids	A set of [ACS] account UUIDs (also known as ID for the end-user) separated by comma that can retrieve the theme	No	String	null	65535
ispublic	Defines whether a theme can be retrieved by anyone when only the domainnames is informed. If the domainids or accountids is informed, it is considered as false.	No	Boolean	null	-

By default, all the parameters are null; therefore, to remove one of the parameters, it will be necessary to explicitly pass it as an empty string. If commonnames, domainids, and accountids are passed as empty, the theme will be considered as the default; there can exist only one default theme and it automatically will be public. If there are no themes match, the GUI will fallback to the current environment configuration.

2.2.4. removeGuiTheme

The API removeGuiTheme will be accessible only by the operators (Root Admin accounts) and will allow them to remove a theme. It will have the following parameter:

Parameter	Description	Mandatory	Type	Default value	Length
id	The UUID (also known as ID for the end-user) of the theme to be removed.	Yes	String	null	40

If the default theme is removed and there is no match to a theme access configuration, the GUI will fallback to the current environment configuration.

3.0. Future works

With this proposal, it will be only possible to manage the themes via API; for the future, we plan to add support for the themes management on the GUI. We will extend the feature to comply with projects, identity federation and domains change. Also, we will extend the feature to allow domain admins and users to manage their own themes.

Types of changes

• Breaking change (fix or feature that would cause existing functionality to change)
• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Enhancement (improves an existing feature and functionality)
• Cleanup (Code refactoring and cleanup, that may add test cases)
• build/CI

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

• Major
• Minor

Screenshots (if appropriate):

There were two themes added with this PR: Dark theme and Apache Foundation theme. They can be used by anyone using the createGuiTheme API. They serve only to demonstrate the usage of this new feature, as presented in the screenshots below:

• Apache theme:

Dark theme:

How Has This Been Tested?

I created multiple themes for specific accounts, domains and common names; they were correctly assigned.

How did you try to break this feature and the system with this change?

[DaanHoogland]

interesting

[DaanHoogland]

@blueorangutan package

[blueorangutan]

@DaanHoogland a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

[blueorangutan]

Packaging result [SF]: ✔️ el7 ✔️ el8 ✔️ el9 ✖️ debian ✔️ suse15. SL-JID 9322

[DaanHoogland]

@blueorangutan test alma9 kvm-alma9 keepEnv

[blueorangutan]

@DaanHoogland a [SL] Trillian-Jenkins test job (alma9 mgmt + kvm-alma9) has been kicked to run smoke tests

[blueorangutan]

[SF] Trillian test result (tid-9917)
Environment: kvm-alma9 (x2), Advanced Networking with Mgmt server a9
Total time taken: 51841 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr8942-t9917-kvm-alma9.zip
Smoke tests completed. 127 look OK, 2 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File
test_01_events_resource	Error	318.04	test_events_resource.py
test_01_events_resource	Error	318.05	test_events_resource.py
test_04_deploy_vm_for_other_user_and_test_vm_operations	Failure	96.36	test_network_permissions.py
ContextSuite context=TestNetworkPermissions>:teardown	Error	1.62	test_network_permissions.py

[BryanMLima]

@blueorangutan package

[blueorangutan]

@BryanMLima a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

[blueorangutan]

Packaging result [SF]: ✔️ el7 ✔️ el8 ✔️ el9 ✔️ debian ✔️ suse15. SL-JID 9365

[DaanHoogland]

@blueorangutan test

[blueorangutan]

@DaanHoogland a [SL] Trillian-Jenkins test job (centos7 mgmt + kvm-centos7) has been kicked to run smoke tests

[github-actions]

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

[blueorangutan]

[SF] Trillian test result (tid-9967)
Environment: kvm-centos7 (x2), Advanced Networking with Mgmt server 7
Total time taken: 47193 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr8942-t9967-kvm-centos7.zip
Smoke tests completed. 127 look OK, 2 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File
test_01_events_resource	Error	306.15	test_events_resource.py
test_01_events_resource	Error	306.16	test_events_resource.py
test_04_deploy_vm_for_other_user_and_test_vm_operations	Failure	92.52	test_network_permissions.py
ContextSuite context=TestNetworkPermissions>:teardown	Error	1.50	test_network_permissions.py

[DaanHoogland]

nice work @BryanMLima , haven't reviewed all of it, but I like it so far.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 8.48564% with 701 lines in your changes missing coverage. Please review.

Project coverage is 15.77%. Comparing base (46201ee) to head (a6ad100).

Files with missing lines	Patch %	Lines
...ache/cloudstack/gui/theme/GuiThemeServiceImpl.java	24.32%	166 Missing and 2 partials ⚠️
...va/org/apache/cloudstack/gui/theme/GuiThemeVO.java	0.00%	80 Missing ⚠️
...ache/cloudstack/api/response/GuiThemeResponse.java	0.00%	75 Missing ⚠️
...oudstack/gui/theme/dao/GuiThemeDetailsDaoImpl.java	0.00%	66 Missing ⚠️
.../cloudstack/gui/theme/dao/GuiThemeJoinDaoImpl.java	1.53%	64 Missing ⚠️
.../api/command/user/gui/theme/UpdateGuiThemeCmd.java	0.00%	46 Missing ⚠️
.../api/command/user/gui/theme/CreateGuiThemeCmd.java	0.00%	43 Missing ⚠️
...rg/apache/cloudstack/gui/theme/GuiThemeJoinVO.java	0.00%	43 Missing ⚠️
...k/api/command/user/gui/theme/ListGuiThemesCmd.java	0.00%	36 Missing ⚠️
...apache/cloudstack/gui/theme/GuiThemeDetailsVO.java	0.00%	32 Missing ⚠️
... and 7 more

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #8942      +/-   ##
============================================
- Coverage     15.78%   15.77%   -0.02%     
- Complexity    12565    12583      +18     
============================================
  Files          5627     5640      +13     
  Lines        492260   493080     +820     
  Branches      63882    62479    -1403     
============================================
+ Hits          77710    77775      +65     
- Misses       406076   406828     +752     
- Partials       8474     8477       +3     

Flag	Coverage Δ
uitests	4.04% <ø> (-0.01%)	⬇️
unittests	16.59% <8.48%> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[JoaoJandre]

Overall looks great, just a few minor remarks.

[github-actions]

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

[BryanMLima]

@blueorangutan package

[blueorangutan]

@BryanMLima a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

[blueorangutan]

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ debian ✔️ suse15. SL-JID 11366

[DaanHoogland]

@blueorangutan test

[blueorangutan]

@DaanHoogland a [SL] Trillian-Jenkins test job (ol8 mgmt + kvm-ol8) has been kicked to run smoke tests

[blueorangutan]

[SF] Trillian test result (tid-11707)
Environment: kvm-ol8 (x2), Advanced Networking with Mgmt server ol8
Total time taken: 73222 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr8942-t11707-kvm-ol8.zip
Smoke tests completed. 132 look OK, 2 have errors, 7 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File
ContextSuite context=TestCreateVolume>:setup	Error	0.00	test_volumes.py
test_01_root_volume_encryption	Error	1028.32	test_volumes.py
test_03_root_and_data_volume_encryption	Error	2068.99	test_volumes.py
test_03_root_and_data_volume_encryption	Error	2069.00	test_volumes.py
ContextSuite context=TestVolumeEncryption>:teardown	Error	2957.34	test_volumes.py
ContextSuite context=TestVolumes>:setup	Error	3095.23	test_volumes.py
test_01_verify_ipv6_vpc	Error	2386.50	test_vpc_ipv6.py
test_01_verify_ipv6_vpc	Error	2386.52	test_vpc_ipv6.py
ContextSuite context=TestIpv6Vpc>:teardown	Error	2975.22	test_vpc_ipv6.py
all_test_vpc_redundant	Skipped	---	test_vpc_redundant.py
all_test_vpc_router_nics	Skipped	---	test_vpc_router_nics.py
all_test_vpc_vpn	Skipped	---	test_vpc_vpn.py
all_test_webhook_delivery	Skipped	---	test_webhook_delivery.py
all_test_webhook_lifecycle	Skipped	---	test_webhook_lifecycle.py
all_test_host_maintenance	Skipped	---	test_host_maintenance.py
all_test_hostha_kvm	Skipped	---	test_hostha_kvm.py