Configuring the cloud plugins

Several cloud plugins can be installed on the Plugin Portal, in order to manage Amazon Web Services, Microsoft Azure, Google Cloud Platform and VMware cloud environments.

All plugin store commands to configure the plugins should start with the plugin store command. For more details on the commands syntax to operate on the PluginStore database, see Introduction.

The required plugin names that should follow the "plugin store" keyword for the configuration of the cloud plugins are:

- AWSAssetDiscoveryPlugin

- AzureAssetDiscoveryPlugin

- GCPAssetDiscoveryPlugin

- VMwareAssetDiscoveryPlugin

This information is key to configure the settings in the Plugin Store, since the plugin store action commands rely on those names to correctly build up the settings keys.

The options accepted by the plugin store command are set, multiple set and delete. If the set and multiple set keywords are decorated with the keyword encrypted, it will result in an encrypted value in the database.

The set option must be followed by the Plugin Store key that we want to set, followed by the value keyword and the value itself that we want to store. Lastly, the current date is specified after the on keyword.

Here follows an example:

plugin store "AWSAssetDiscoveryPlugin" set "Credentials_AccessKey_myLabel" value "myAccessKey" on "{parameter "action issue date" of action}"

pluginstore "AWSAssetDiscoveryPlugin" set encrypted "Credentials_SecretAccessKey_myLabel" value "mySecret" on "{parameter "action issue date" of action}"

The following settings will display in the Plugin Store:


Key	Value	Effective Date
_AWSAssetDiscoveryPlugin_Credentials_AccessKey_myLabel	myAccessKey	0123456789
_AWSAssetDiscoveryPlugin_Credentials_SecretAccessKey_myLabel	{obf}ABCDEF...	0123456789

The multiple set option is used to quickly configure multiple settings at once. The encrypted option is available for this as well. The multiple set option must be followed by a percent encoded JSON that contains a list of the key-value pairs that must be added to the database. An example of the decoded JSON is the following:

{
    "Credentials_AccessKey_myLabel" : "myAccessKey",
    "Credentials_Region_myLabel" : "myLabelRegion",
    "HTTP_ProxyURL" : "myProxyURL",
    "HTTP_ProxyUser" : "myProxyUser"
}

For example, the output of the following command:

plugin store "AWSAssetDiscoveryPlugin" multiple set <example json> on "{parameter "action issue date" of action}"

should be the addition of the following settings to the Plugin Store:


Key	Value	Effective Date
_AWSAssetDiscoveryPlugin_Credentials_AccessKey_myLabel	myAccessKey	0123456789
_AWSAssetDiscoveryPlugin_Credentials_Region_myLabel	myLabelRegion	0123456789
_AWSAssetDiscoveryPlugin_HTTP_ProxyURL	myProxyURL	0123456789
_AWSAssetDiscoveryPlugin_HTTP_ProxyUser	myProxyUser	0123456789

The "on" keyword is required by the set commands and should be followed by the date at which the setting is issued:

[...] on "{parameter "action issue date" of action}"

The delete option will simply remove a certain key from the plugin store:

plugin store "AWSAssetDiscoveryPlugin" delete "Credentials_Region_myLabel"


Key	Value	Effective Date
_AWSAssetDiscoveryPlugin_Credentials_AccessKey_myLabel	myAccessKey	0123456789
_AWSAssetDiscoveryPlugin_HTTP_ProxyURL	myProxyURL	0123456789
_AWSAssetDiscoveryPlugin_HTTP_ProxyUser	myProxyUser	0123456789

Issuing the delete command followed by the keyword all will result in all the Plugin Store settings for a given plugin to be deleted.

plugin store "AWSAssetDiscoveryPlugin" delete all

Many of the plugins settings are bound to a certain set of credentials, which in turn are identified by what we call a credential label. As such, is a good practice, when building an action script, to store a label in an action parameter in order to re-use it multiple times later in the action script:

parameter "credentialsLabel" = "<my label>"

Note: The values that you must replace are only the ones wrapped by angled brackets, like <my label>.

If a key or part of it needs to be repreated multiple times, it can be stored in a parameter as well and it can be concatenated later.

parameter "accessKey" = "Credentials_AccessKey"
parameter "secretAccessKey" = "Credentials_SecretAccessKey"

For example, a new parameter can be defined by the concatenation of the previous parameters:

parameter "credentialsLabel" = "<my label>"

When configuring the plugin programmatically it could be useful to check whether a parameter exists or if it is not empty, in order to achieve that, simply wrap your code in an if block:

if {(exists parameter "myParam")AND (parameter "myParam" != "")}
	// my code
endif

Common Plugin settings

The following settings are common among all cloud plugins:

Discovery_Region - The default region for the plugin. This region will be used to retrieve the list of region enabled for all the AWS accounts related to the credentials stored in the plugin. This setting is mandatory.

Log_Path - The path of the log of the plugin.

Log_Verbose - When set to 1, debug logging is enabled. When set to 0, only info logging is displayed.

JSON file settings - Some settings are defined for the cloud plugins through a JSON called settings.json. Here is an example of such a JSON.

{
    "ID": <plugin name>,
    "ConfigurationOptions": "",
    "DeviceReportRefreshIntervalMinutes": <refresh interval in minutes>,
    "DeviceReportExpirationIntervalHours": 168,
    "CommandFormat": "JSON",
    "SendSettingsToPlugin": [],
    "ExecutablePath": <executable path>,
    "HandlePartialRefresh": false,
    "FullReportsInRefreshAll": true,
    "NoRefreshBeforeActionIntervalMinutes": 60
}

AWSAssetDiscoveryPlugin configuration

Here are the settings needed to fully configure the Amazon Web Services plugin.

IAM User specific settings

Credentials_AccessKey_<label> - The Access Key ID associated to an IAM User. This setting is mandatory.

Credentials_SecretAccessKey_<label> - The Secret Access Key associated to an IAM User. The value of this setting must be encrypted. This setting is mandatory.

Credentials_Region_<label> - The default region for the IAM User credentials with label <label>. This region overrides the Discovery Region.

Credentials_Roles_<label>_<arn> - The region of the role with ARN <arn> to be assumed by the IAM User with label <label>. This region overrides both the Credentials Region and the Discovery Region. The value can be empty.

Credentials_Roles_ExternalId_<label>_<arn> - The external ID of the role with ARN <arn> to be assumed by the IAM User with label <label>. The value must be encrypted. The setting can be omitted if the IAM Roles does not require an external ID.

Advanced settings

HTTP_ProxyURL - The URL of the HTTP Proxy for the plugin.

HTTP_ProxyUser - The User of the HTTP Proxy for the plugin.

HTTP_ProxyPassword - The Password of the HTTP Proxy for the plugin. The value of this setting must be encrypted.

RegionAllowedList_<label> - Forces the plugin to execute discovery only on the listed regions for the user with label <label>. Separate regions with a semicolon ';'.

Example: eu-central-1;eu-west-1;us-east-1

When installing the AWS plugin, you can specify the allowed regions. For more details about how to limit the AWS regions, see Limit AWS Regions to restrict the scope of device discovery.

Example of AWSAssetDiscoveryPlugin configuration

Initializing some parameters:

parameter "firstLabel" = "foo"
parameter "secondLabel" = "bar"

parameter "accessKey" = "Credentials_AccessKey"
parameter "secretAccessKey" = "Credentials_SecretAccessKey"

Note: foo and bar are just invented names for our labels. However, Credentials_AccessKey and Credentials_SecretAccessKey are real setting names. We are defining these four parameters because, by combining them, we can define the keys that we need to set the user key and password like specified above.

Setting the plugin default region:

plugin store "AWSAssetDiscoveryPlugin" set "Discovery_Region" value "eu-west-1" on "{parameter "action issue date" of action}"

Configuring the first user:

parameter "firstUserAccessKey" = "{parameter "accessKey"}_{parameter "firstLabel"}"
parameter "firstUserPassword" = "{parameter "secretAccessKey"}_{parameter "firstLabel"}"
plugin store "AWSAssetDiscoveryPlugin" set "{parameter "firstUserAccessKey"}" value "<myUserKey1>" on "{parameter "action issue date" of action}"
plugin store "AWSAssetDiscoveryPlugin" set encrypted "{parameter "firstUserPassword} value "<myUserPass1>" on "{parameter "action issue date" of action}"
plugin store "AWSAssetDiscoveryPlugin" set "Credentials_Region_{parameter "firstLabel"}" value "eu-central-1" on "{parameter "action issue date" of action}"

Note: We combined the first four parameters into two new parameters, by concatenating them by pairs, in order to fully define the Plugin Store keys. To concatenate the parameters, we are just assigning to a new parameter the string composed by the two parameters separated by an underscore. As such, the content of the parameter “firstUserAccessKey” would be “Credentials_AccessKey_foo”.

Configuring the second user:

parameter "secondUserAccessKey" = "{parameter "accessKey"}_{parameter "secondLabel"}"
parameter "secondUserPassword" = "{parameter "secretAccessKey"}_{parameter "secondLabel"}"
plugin store "AWSAssetDiscoveryPlugin" set "{parameter "secondUserAccessKey"}" value "<myUserKey2>" on "{parameter "action issue date" of action}"
plugin store "AWSAssetDiscoveryPlugin" set encrypted "{parameter "secondUserPassword} value "<myUserPass2>" on "{parameter "action issue date" of action}"
plugin store "AWSAssetDiscoveryPlugin" set "Credentials_Roles_{parameter "secondLabel"}_fakeRoleARN1" value "us-east-1" on "{parameter "action issue date" of action}"
plugin store "AWSAssetDiscoveryPlugin" set "Credentials_Roles_{parameter "secondLabel"}_fakeRoleARN2" value "us-west-1" on "{parameter "action issue date" of action}"
plugin store "AWSAssetDiscoveryPlugin" set encrypted "Credentials_Roles_ExternalId_{parameter "secondLabel"}_fakeRoleARN2" value "myExternalId" on "{parameter "action issue date" of action}"

Setting the log to verbose:

plugin store "AWSAssetDiscoveryPlugin" set "Log_Verbose" value "1" on "{parameter "action issue date" of action}"

Setting the list of allowed regions:

plugin store "AWSAssetDiscoveryPlugin" set "RegionAllowedList_{parameter "secondLabel"}" value "us-east-1;us-west-1" on "{parameter "action issue date" of action}"

When installing the AWS plugin, you can specify the allowed regions. For more details about how to limit the AWS regions, see Limit AWS Regions to restrict the scope of device discovery.

An example of the expected output in the PluginStore is:


Key	Value	Effective Date
_AWSAssetDiscoveryPlugin_Credentials_AccessKey_foo	myUserKey1	0123456789
_AWSAssetDiscoveryPlugin_Credentials_SecretAccessKey_foo	{obf}ABCDEF...	0123456789
_AWSAssetDiscoveryPlugin_Credentials_Region_foo	eu-central-1	0123456789
_AWSAssetDiscoveryPlugin_Credentials_AccessKey_bar	myUserKey2	0123456789
_AWSAssetDiscoveryPlugin_Credentials_SecretAccessKey_bar	{obf}ABCDEF...	0123456789
_AWSAssetDiscoveryPlugin_Credentials_Roles_bar_fakeRoleARN1	us-east-1	0123456789
_AWSAssetDiscoveryPlugin_Credentials_Roles_bar_fakeRoleARN2	us-west-1	0123456789
_AWSAssetDiscoveryPlugin_Credentials_Roles_ExternalId_bar_fakeRoleARN2	{obf}ABCDEF...	0123456789
_AWSAssetDiscoveryPlugin_Discovery_Region	eu-west-1	0123456789
_AWSAssetDiscoveryPlugin_Log_Verbose	1	0123456789
_AWSAssetDiscoveryPlugin_RegionAllowedList_bar	us-east-1;us-west-1	0123456789

AzureAssetDiscoveryPlugin configuration

Here are the settings needed to fully configure the Microsoft Azure Plugin.

IAM User specific settings

Credentials_ClientID_<label> - The Client ID for the user with label <label>.

Credentials_ClientSecret_<label> - The Client Secret for the user with label <label>.

Credentials_SubscriptionID_<label> - The Subscription ID for the user with label <label>.

Credentials_TenantID_<label> - The tenant ID for the user with label <label>.

Example of AzureAssetDiscoveryPlugin configuration

parameter "myLabel" = "foo"
plugin store "AzureAssetDiscoveryPlugin" set "Credentials_TenantID_{parameter "myLabel"}" value "myTenantID" on "{parameter "action issue date" of action}"
plugin store "AzureAssetDiscoveryPlugin" set "Credentials_ClientID_{parameter "myLabel"}" value "myClientID" on "{parameter "action issue date" of action}"
plugin store "AzureAssetDiscoveryPlugin" set encrypted "Credentials_ClientSecret_{parameter "myLabel"}" value "myClientSecret" on "{parameter "action issue date" of action}"
plugin store "AzureAssetDiscoveryPlugin" set "Credentials_SubscriptionID_{parameter "myLabel"}" value "mySubscriptionID" on "{parameter "action issue date" of action}"

Where:

myTenantID: Is the tenant ID for the user.
myClientID: Is the Client ID for the user.
myClientSecret: Is the Client Secret for the user.
mySubscriptionID: Is the Subscription ID for the user.

GCPAssetDiscoveryPlugin configuration

Here are the settings needed to fully configure the Google Cloud Platform Plugin.

Service Account specific settings

Credentials_JSON_<label> - The encrypted JSON key related to a service account member of a project on GCP.

The GCP JSON key file will look something like this:

{
  "type": "service_account",
  "project_id": "test-123456",
  "private_key_id": "0123456789abcdefghilmnopqrstuvz",
  "private_key": "-----BEGIN PRIVATE KEY-----\naVeryLongKey\n-----END PRIVATE KEY-----\n",
  "client_email": "testusersvc@test-123456.iam.gserviceaccount.com",
  "client_id": "01234567891011121314",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/
  testusersvc%40test-123456.iam.gserviceaccount.com"
}

The JSON key must be percent encoded before feeding it to the plugin store action command. Since all the information required to configure a service account into the GCP Plugin is contained in the JSON, this is the only setting to insert or delete.

The JSON must be encrypted, since it contains the private key.

Example of GCPAssetDiscoveryPlugin configuration

parameter "jsonKey" = "<percent encoded json>"
plugin store "GCPAssetDiscoveryPlugin" set encrypted "Credentials_JSON_foo" value "{parameter "jsonKey"}" on "{parameter "action issue date" of action}"

VMWareAssetDiscoveryPlugin configuration

Here are the settings needed to fully configure the VMware Plugin.

IAM User specific settings

Credentials_Username_<label> - The username for the user with label <label>.

Credentials_Password_<label> - The encrypted password for the user with label <label>.

Credentials_URL_<label> - The credentials label for the user with label <label>.

Example of VMwareAssetDiscoveryPlugin configuration

parameter "myLabel" = "foo"
plugin store "VMWareAssetDiscoveryPlugin" set "Credentials_Username_{parameter "myLabel"}" value "myUsername" on "{parameter "action issue date" of action}"
plugin store "VMWareAssetDiscoveryPlugin" set "Credentials_URL_{parameter "myLabel"}" value "myURL" on "{parameter "action issue date" of action}"
plugin store "VMWareAssetDiscoveryPlugin" set encrypted "Credentials_Password_{parameter "myLabel"}" value "myPassword" on "{parameter "action issue date" of action}"

Where:

myUsername: Is the username for the user.
myURL: Is the credentials label for the user.
myPassword: Is the encrypted password for the user.