// removed jquery ui css and js

Arcus Server

Overview

The CloudCenter platform allows you to define your own parameters or use the CloudCenter-supported parameters as identified in Parameters and Macros > Parameter Type. The webservice option is listed in the Parameter Type dropdown. If you configure this option, you must provide the Protocol (HTTP or HTTPS), Web Service URL, and the credentials (Username and Password) for the webservice. To do this, you can optionally launch an isolated Arcus server and configure the webservice to point to the Arcus server. Arcus is an API broker and translator.

While the CloudCenter platform provides the Arcus integration, it is up to the customer using this feature to address the following dependencies:

  • Send requests to the device's API URL

  • Call the correct device-specific webservice method

  • Convert the webservice response to the format expected by CloudCenter

Arcus installer packages are available as a standalone component and can be downloaded along with other CloudCenter components from the Cisco CloudCenter download location.

Requirements

To use the Arcus integration, verify the following requirements:

  • OS with BASH installed

  • Docker v1.12.0 or later installed and accessible to the user running the installer

  • If using SSL, the certificate chain (arcus.crt) and key (arcus.key) in PEM format – the self-signed certificates are available in the arcus/certs folder from the same authority as the CCM and thus, works by default when you install the CCM.

  • An Arcus API account

  • CloudCenter 4.9.0 or later releases

Installation Process

To configure an Arcus server, an Arcus administrator who is also a CloudCenter administrator must follow this procedure.

  1. Download package files:

    See Virtual Appliance Overview to understand the required components.

    See Virtual Appliance Process to understand the process.

    See Phase 4 Overview  to understand the various types of software download files.

    1. SSH into the VM instance designated for this component by using the key pair that you used to launch the VM.

      Along with the key pair, you may need to use your login credentials for sudo or root access based on your environment.

    2. Download the following required files for this component from software.cisco.com. Be aware that the following files are contained in a file name that uses the following syntax:

      cloudcenter-release-<release.tag>-installer-artifacts.tar
    • core_installer.bin

  2. Use the defaults or override defaults for the environment variables that the following table describes.

    Environment VariableDefaultDescription
    PRODUCTION_PASSWORDRandomly generated hex valueUsed to set the MariaDB password
    MYSQL_DATA_DIR/opt/arcus/dataThe location where Arcus should store the MariaDB files
    ARCUS_CERT_DIR/opt/arcus/certsIf using SSL, the directory containing the certificate and key
    ARCUS_CERT_KEYssl.keyIf using SSL, the name of the key file, relative to the directory ARCUS_CERT_DIR
    ARCUS_CERT_FILEssl.certIf using SSL, the name of the cert chain file, relative to the directory ARCUS_CERT_DIR
  3. Run the core installer to setup core system components using the following commands.

    sudo -i
    cd /tmp
    chmod 755 core_installer.bin
    
    #Set the following only if a local package store is setup 
    export CUSTOM_REPO=<http://local_package_store ip>
    
    ./core_installer.bin <ostype> <cloudtype> arcus

    For example:

    ./core_installer.bin centos7 amazon arcus

    Syntax:

    <ostype>= centos7, rhel7

    <cloudtype>= amazon, azurerm, azurepack, azurestack, google, kubernetes, opsource, openstack, softlayer, vmware, or vcd
    (run the ./core_installer.bin help command for a complete list)

  4. Remove the core_installer.bin file.

    rm core_installer.bin
  5. Reboot the Arcus VM.

You have successfully installed the Arcus server! You must now configure the Arcus server to integrate with the CloudCenter platform.

Arcus API Account Access

The Arcus API Account is required to authorize access to the Arcus web service. The credentials for the Arcus API account must be set in Cisco CloudCenter when configuring a call through Arcus to gather information from your infrastructure device.

  1. Create an Arcus API account.

    1. Log in to Arcus. The following screenshot shows information for Arcus API accounts.

    2. Select Arcus API Accounts from the left navigation menu to view a list of all Arcus API Accounts. From this list of devices, you can view, edit, or remove existing Arcus API Accounts.

    3. Click the New Arcus API Account button.

    4. Enter a descriptive name for the account.

    5. Optionally, enter a longer description for the account.

    6. Enter a Username.

    7. Enter a Password and confirm the password.

      If you change the Username or Password for an Arcus API Account, you will have to make the corresponding changes to the automation created in the CloudCenter platform.

    8. Click the Create Arcus API Account button.

Installing a Trusted Certificate Authority

To integrate the CloudCenter platform with an Arcus server, your client must trust the HTTPS endpoint. If the client is not using an SSL certificate signed by the standard Java JRE's trusted CAs, you must add a trusted certificate.

Be sure to import the certificate from the CCM and update the certificates as specified in the Certificate Authentication > Update the certs.zip File on the Arcus Server section.

User Configuration

An Arcus user who is not an Arcus administrator is called a Member. Members cannot create additional Arcus users. Members can create and manage device types, devices, templates, and service accounts.

In addition to all of the capabilities of a Member, Admin users have the additional capability to create and manage Member users and other Admin users on the Arcus server. Only Admin users can create, modify, and remove other user accounts

To configure a Member or Admin user, follow this procedure:

  1. Log in to the Arcus server as an Admin user. 

  2. Select Admin Users from the left navigation menu. The list of configured users is displayed! From this list of devices, you can view, edit, or remove existing users.

    • Click the New Admin User button to add a new user.

      1. Enter the user’s email address.

      2. Enter a password and confirm the password.

      3. Choose either a Member or Admin for the role.

      4. Click the Create Admin User button

    • Click the Edit button for a specific user to change the password: Changing the password of the user you are logged in as will require you to sign in again

      1. Enter a new password and confirm the new password.

      2. Click the Update Admin User button.

    • Click the Delete button for a specific user to delete this user: You cannot delete the user you are logged in as.

      1. Verify the user name.

      2. Confirm that you wish to delete the user.

Reset Admin Password from the Command Line

If any user has forgotten their password, then any Admin user can reset the user's password. If all admins have forgotten their passwords, you can reset the password for one of the Admins from the command line.

  1. Log onto the host system for Arcus as a user who has Docker permission

  2. Run the following command:

    docker exec -it arcus_web_1 rake reset_admin {email of user to reset}
  3. The system prompts you to enter the new password twice.

  4. Once accepted, the system confirms that the password has been set and you can log in using the web interface.

Device Type Configuration

A Device Type represents the make and model of a brand or class of device existing in your infrastructure. As an example, if you have a number of F5 BIG-IP LTM 7050 load balancers in use, you would create a Device Type representing this type of infrastructure device. By creating this Device Type, you will be able to create individual devices for each of the 7050s deployed to your infrastructure and you will, further, be able to create templates that you can use to retrieve information from this Device Type.

Both Devices and Templates belong to a Device Type.

  • A Template returns data for any Device which shares its Device Type.

  • It is important to use the appropriate Device Type so Templates return meaningful data for all Devices belonging to the same Device Type.

To configure a Device Type, follow this procedure.

  1. Login to the Arcus server as an Admin user. The following screenshot highlights the Device Types > New Device Type button.

  2. Select Device Types from the left navigation menu. The list of configured devices is displayed! From this list of devices types, you can view, edit, or remove existing devices.

    • Click the New Device Type button to add a new device type:

      1. Enter a unique name to describe the device type.

      2. Click the Add New Step button.

      3. Provide a step name that describes it.

      4. If the device type should also apply the template settings to this step, check the Apply template box.

        If different settings are configured in both the template setting and the step setting, be aware that the template setting overrides the step setting. The template's transformation is applied to the response body.

      5. Configure the step to make the appropriate HTTP request.

      6. If the device type should also include the basic authentication header using the device credentials in this step, check the Basic auth box.

      7. Optional. Click Add New Step if you need to add another step.

      8. Click the Create Device Type button to save all changes.

    • Click the Edit button for a specific device type: Changing the authentication details affects all devices associated with this device type

    • Click the Delete button for a specific device type: Device Types associated with one or more devices and/or templates cannot be removed. The Delete button will only be available for device types that are not associated with a device and/or template.

Device Configuration

A Device represents an individual and uniquely addressable device from your infrastructure. For example, you could have a F5 BIG-IP LTM 7050 load balancer with the IP address 12.18.1.1 represented by a device in Arcus. The device contains the information required to send requests to the device and collect information from the device’s APIs, including the username and password for the device’s APIs and the base URL or IP address to use when contacting the device’s APIs. Using a combination of a unique device and a template for the appropriate device type, you can retrieve information from the device using APIs.

To configure a device, follow this procedure.

  1. Login to the Arcus server as an Admin user. The following screenshot highlights the Device Types > New Device button.

  2. Select Devices from the left navigation menu. The list of configured devices is displayed! From this list of devices, you can view, edit, or remove existing devices.

    • Click the New Device button to add a new device:

      1. Select the appropriate device type for the device (If the appropriate device type does not exist for this device, create a new device type for this class of device).

      2. Enter a unique name to describe the device.

      3. Enter the base URL or IP address assigned to the device.

      4. When available and required, enter the username and password necessary to authenticate to the device.

      5. If the device allows or requires SSL validation, check the Ssl validation box.

      6. Click the Create Device button.

    • Click the Edit button for a specific device: Changing the authentication details affects all devices associated with this device type

    • Click the Delete button for a specific device: Device Types associated with one or more devices and/or templates cannot be removed. The Delete button will only be available for device types that are not associated with a device and/or template.

Template Configuration

Templates contain instructions specific to the detailed API endpoint you are trying to access. This includes the relative path to the endpoint, any payload that needs to be included with the request, and how to parse the data that is returned from the endpoint.

To configure a Device Type, follow this procedure.

  1. Login to the Arcus server as an Admin user. The following screenshot highlights the Device Types > New Template button and a relative URL of the endpoint from which to access the data.

  2. Select Templates from the left navigation menu.

  3. Click the New Template button.

  4. Select the appropriate Device Type for the device (If the appropriate device type does not exist for this device, create a new device type for this class of device).

  5. Enter a unique name to describe the template.

  6. Enter a description (optional). This is used to help other users of the system know the purpose of the template.

  7. Enter the relative URL of the endpoint to from which to access the data.

  8. Select the HTTP method to use to retrieve the data (get or post).

  9. Enter the body that should be passed to the service during the request (mainly used when retrieving data with POST).

  10. Add additional headers to pass the request, if needed.

  11. Enter a valid XSLT in the Transformation section. For details on how to create a transformation, see the XSLT Transformation below.

  12. Click the Create Template button.

XSLT Transformation

Arcus uses XSLT to retrieve results from various types of endpoints and return them in a common format. XSLT uses XPath to locate the required data inside the source XML document. See the following resources for more information on XSLT:

The CloudCenter platform's XSLT format is as follows:

<?xml version="1.0" encoding="ISO-8859-1"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="/root/imdata">
	<data>
		<xsl:for-each select="imdatum">
			<xsl:sort select="fvnsVlanInstP/attributes/name"/>
			<results>
				<name><xsl:value-of select="fvnsVlanInstP/attributes/dn"/></name>
				<displayName><xsl:value-of select="fvnsVlanInstP/attributes/name"/>
                </displayName>
			</results>
		</xsl:for-each>
	</data>
  </xsl:template>
</xsl:stylesheet>

The components for the XSLT transformation is explained in the following table.

ComponentDescriptionFixed?Mutable?
<?xml version="1.0" encoding="ISO-8859-1"?>

Declares the version and encoding for the transformation.

Yes (in most cases)No
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
Opens the transformationYesNo
<xsl:template match="/root/imdata">

The first line of the transformation and opens the CloudCenter template. Use the value of the match attribute to dive into the returned data set to reduce repetition, or use “/” to indicate the root of the returned data.

NoYes
<data>

Arcus uses this tag to identify the dataset location in the resulting XML document.

YesNo
<xsl:for-each select="imdatum">

Declares the individual elements to loop over. The XML attribute select should be the relative path from match above to the individual elements.

NoYes
<xsl:sort select="fvnsVlanInstP/attributes/name"/>

By default, Arcus returns data in the same order provided by the source system. To enforce sorting using an alternate key, add this line and set the select attribute to the key location.

NoYes
<results>

Arcus uses this tag to identify the individual results of the data set.

YesNo
<name><xsl:value-of select="fvnsVlanInstP/attributes/dn"/></name>

The internal name to use GUID or CIDR block, and so forth.

Each result should contain both a name and a displayName element. Set the select attribute as the relative location of the attribute to fetch.

NoYes
<displayName><xsl:value-of select="fvnsVlanInstP/attributes/name"/></displayName>

The information displayed to the user.

Set the select attribute as the relative location to fetch the displayName data.

NoYes
</results></xsl:foreach></data></xsl:template></xsl:stylesheet>
Closes each elementYesNo

Arcus accepts structured data in both XML and JSON formats. The returned information is parsed and transformed based on the template.

Example 1 (XML Data)

Data returned as XML is available to be parsed using the existing structure with which the endpoint returns the data.

<?xml version="1.0" encoding="UTF-8"?>
<dataset>
   <hosts>
      <host>
         <name>Bins-Dicki</name>
         <internal>
            <account-id>e34667de-baad-45f3-b0c3-bcf954af93ba</account-id>
         </internal>
      </host>
      <host>
         <name>Corwin, Runte and Schumm</name>
         <internal>
            <account-id>0b0cefa7-6786-4add-a7e4-21f6b99f1d60</account-id>
         </internal>
      </host>
      <host>
         <name>Braun, Steuber and Kuphal</name>
         <internal>
            <account-id>8e63ec0a-38b6-407c-9652-0fe75dc2329e</account-id>
         </internal>
      </host>
      <host>
         <name>Lind LLC</name>
         <internal>
            <account-id>6f10eddd-b9bc-4347-8258-d1c1c7d539ab</account-id>
         </internal>
      </host>
      <host>
         <name>Ernser Group</name>
         <internal>
            <account-id>f74c899e-6324-4ffb-9241-cdc97cb45884</account-id>
         </internal>
      </host>
   </hosts>
</dataset>						

The following XSLT:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <xsl:template match="/dataset/hosts">
      <data>
         <xsl:for-each select="host">
            <xsl:sort select="name" />
            <results>
               <name>
                  <xsl:value-of select="internal/account-id" />
               </name>
               <displayName>
                  <xsl:value-of select="name" />
               </displayName>
            </results>
         </xsl:for-each>
      </data>
   </xsl:template>
</xsl:stylesheet>

Returns this data:

[
{"name":"e34667de-baad-45f3-b0c3-bcf954af93ba","displayName":"Bins-Dicki"},
{"name":"8e63ec0a-38b6-407c-9652-0fe75dc2329e","displayName":"Braun, Steuber and Kuphal"},
{"name":"0b0cefa7-6786-4add-a7e4-21f6b99f1d60","displayName":"Corwin, Runte and Schumm"},
{"name":"f74c899e-6324-4ffb-9241-cdc97cb45884","displayName":"Ernser Group"},
{"name":"6f10eddd-b9bc-4347-8258-d1c1c7d539ab","displayName":"Lind LLC"}
]

Example 2 (JSON Data)

The JSON spec does not require a top-level key to be valid. Consequently, the CloudCenter platform wraps the JSON response in a root element before attempting to transform the data. Hence, the XSLT written to consume JSON data must contain root as the first part of the select participle.

Arcus converts underscores to dashes in keys (so account_id is converted to account-id).

{
   "accounts":[
      {
         "name":"Langosh, Pfeffer and Kutch",
         "internal":{
            "account_id":"26a44c79-1627-4485-9393-a88e49655481",
            "datacenter":"GB-LDN"
         }
      },
      {
         "name":"Stamm-Zboncak",
         "internal":{
            "account_id":"26a990fb-88db-43f0-b3cf-e89267864072",
            "datacenter":"US-ARL"
         }
      },
      {
         "name":"Hirthe-Braun",
         "internal":{
            "account_id":"cf37947a-f8e9-4c0d-bdfe-50b4f0b04798",
            "datacenter":"GB-LDN"
         }
      },
      {
         "name":"Sanford Group",
         "internal":{
            "account_id":"327e73b6-8ae7-45dc-aa7a-92341d39c55e",
            "datacenter":"GB-LDN"
         }
      },
      {
         "name":"Medhurst-Keebler",
         "internal":{
            "account_id":"94f91032-0f01-49a9-9002-c912ef124605",
            "datacenter":"GB-LDN"
         }
      }
   ]
}

The following XSLT:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <xsl:template match="/root/accounts">
      <data>
         <xsl:for-each select="account">
            <xsl:sort select="internal/datacenter" />
            <xsl:sort select="name" />
            <results>
               <name>
                  <xsl:value-of select="internal/account-id" />
               </name>
               <displayName>
                  <xsl:value-of select="internal/datacenter" />
                  -
                  <xsl:value-of select="name" />
               </displayName>
            </results>
         </xsl:for-each>
      </data>
   </xsl:template>
</xsl:stylesheet>					

Returns this data:

[
{"name":"cf37947a-f8e9-4c0d-bdfe-50b4f0b04798","displayName":"GB-LDN - Hirthe-Braun"},
{"name":"26a44c79-1627-4485-9393-a88e49655481","displayName":"GB-LDN - Langosh, Pfeffer and
Kutch"},
{"name":"94f91032-0f01-49a9-9002-c912ef124605","displayName":"GB-LDN - Medhurst-Keebler"},
{"name":"327e73b6-8ae7-45dc-aa7a-92341d39c55e","displayName":"GB-LDN - Sanford Group"},
{"name":"26a990fb-88db-43f0-b3cf-e89267864072","displayName":"US-ARL - Stamm-Zboncak"}
]

When converting arrays to XML, Arcus attempts to use the singular form of keys.

{
   "data":{
      "items":[
         {"name":"Host 1"},
         {"name":"Host 2"},
         {"name":"Host 3"}
      ]
   }
}

To loop over individual names, use the for-each string of root/data/items/item.

However, given this structure:

{
   "data":{
      "host":[
         {"name":"Host 1"},
         {"name":"Host 2"},
         {"name":"Host 3"}
      ]
   }
}

You would need to use the for-each string of root/data/host/host as host is already singular.

A key ending in “a” is a special case, as Arcus interprets the “a” ending as the plural form of the key.

{
   "data":{
      "imdata":[
         {"name":"Host 1"},
         {"name":"Host 2"},
         {"name":"Host 3"}
      ]
   }
}

To loop over the individual names, use the for-each string of root/data/imdata/imdatum.

  • No labels
© 2017-2019 Cisco Systems, Inc. All rights reserved