BryanMLima opened a new pull request, #8942:
URL: https://github.com/apache/cloudstack/pull/8942
### 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 <a
href="#json-configurations" class="internal-link">JSON Configurations</a>
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 <a
href="#json-configurations" class="internal-link">JSON Configurations</a>
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)
- [x] 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
- [x] 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?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
