Configuring the VIM Connector During Installation

To configure the VIM Connector during installation, the following parameter must be provided to bootvm.py:

Configuring the VIM Connector After Installation

To configure the VIM Connector after installation, the following parameter must be provided to bootvm.py:

--no_vim_credentials

When the no_vim_credentials parameter is provided, the following bootvm.py arguments are ignored:

• os_tenant_name

• os_username

• os_password

• os_auth_url

For details on Installation, see the Cisco Elastic Services Controller Install and Upgrade Guide. You can configure the same using the VIM Connector APIs post installation, for more details, see Managing VIM Connector Using the VIM Connector APIs.

Managing using Netconf API

• Passing VIM credential using Netconf:

  
  
  <esc_system_config xmlns="http://www.cisco.com/esc/esc">
    <vim_connectors>
      <!--represents a vim-->
      <vim_connector>
        <!--unique id for each vim-->
        <id>my-server</id>
        <!--vim type [OPENSTACK|VMWARE_VSPHERE|LIBVIRT|AWS|CSP]-->
        <type>OPENSTACK</type>
        <properties>
          <property>
            <name>os_auth_url</name>
            <value>http://{os_ip:port}/v3</value>
          </property>
          <!-- The project name for openstack authentication and authorization -->
          <property>
            <name>os_project_name</name>
            <value>vimProject</value>
          </property>
          <!-- The project domain name is only needed for openstack v3 identity api -->
          <property>
            <name>os_project_domain_name</name>
            <value>default</value>
          </property>
          <property>
            <name>os_identity_api_version</name>
            <value>3</value>
          </property>
        </properties>
        <users>
          <user>
            <id>admin</id>
            <credentials>
              <properties>
                <property>
                  <name>os_password</name>
                  <value>********</value>
                </property>
                <!-- The user domain name is only needed for openstack v3 identity api -->
                <property>
                  <name>os_user_domain_name</name>
                  <value>default</value>
                </property>
              </properties>
            </credentials>
          </user>
        </users>
      </vim_connector>
    </vim_connectors>
  </esc_system_config>
  

• Updating VIM Connector using Netconf:

  
  
  <esc_system_config xmlns="http://www.cisco.com/esc/esc">
    <vim_connectors>
      <vim_connector nc:operation="replace">
        <id>example_vim</id>
        <type>OPENSTACK</type>
        <properties>
          <property>
            <name>os_auth_url</name>
            <value>{auth_url}</value>
          </property>
          <property>
            <name>os_project_name</name>
            <value>vimProject</value>
          </property>
          <!-- The project domain name is only needed for openstack v3 identity api -->
          <property>
            <name>os_project_domain_name</name>
            <value>default</value>
          </property>
          <property>
            <name>os_identity_api_version</name>
            <value>3</value>
          </property>
        </properties>
      </vim_connector>
    </vim_connectors>
  </esc_system_config>
  
  

• Updating VIM user using Netconf:

  <esc_system_config xmlns="http://www.cisco.com/esc/esc">
    <vim_connectors>
      <vim_connector>
        <id>example_vim</id>
          <users>
            <user nc:operation="replace">
              <id>my_user</id>
              <credentials>
               <properties>
                <property>
                  <name>os_password</name>
                  <value>********</value>
                </property>
                <!-- The user domain name is only needed for openstack v3 identity api -->
                <property>
                  <name>os_user_domain_name</name>
                  <value>default</value>
                </property>
               </properties>
             </credentials>
            </user>
          </users>
      </vim_connector>
    </vim_connectors>
  </esc_system_config>

• Deleting VIM connector using Netconf:

  
  <esc_system_config xmlns="http://www.cisco.com/esc/esc">  <vim_connectors>
      <vim_connector nc:operation="delete">
        <id>example_vim</id>
      </vim_connector>
    </vim_connectors>
  </esc_system_config>
  
  

• Deleting VIM User using Netconf:

  <esc_system_config xmlns="http://www.cisco.com/esc/esc">
    <vim_connectors>
      <vim_connector>
        <id>example_vim</id>
          <users>
            <user nc:operation="delete">
              <id>my_user</id>
            </user>
          </users>
      </vim_connector>
    </vim_connectors>
  </esc_system_config>

• Deleting VIM Connector using command:

  $/opt/cisco/esc/esc-confd/esc-cli/esc_nc_cli delete-vim-connector <vim connector id>

• Deleting VIM user using command:

  $/opt/cisco/esc/esc-confd/esc-cli/esc_nc_cli delete-vim-user <vim connector id> <vim user id>

Managing using REST API

• Adding VIM using REST:

  
  POST /ESCManager/v0/vims/
  HEADER: content-type, callback
   
  <?xml version="1.0"?>
  <vim_connector xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <id>example_vim</id>
    <type>OPENSTACK</type>
    <properties>
      <property>
        <name>os_auth_url</name>
        <value>{auth_url}</value>
      </property>
      <property>
        <name>os_project_name</name>
        <value>vimProject</value>
      </property>
      <!-- The project domain name is only needed for openstack v3 identity api -->
      <property>
        <name>os_project_domain_name</name>
        <value>default</value>
      </property>
      <property>
        <name>os_identity_api_version</name>
        <value>3</value>
      </property>
    </properties>
  </vim_connector>

• Adding VIM user using REST:

  
  POST /ESCManager/v0/vims/{vim_id}/vim_users
  HEADER: content-type, callback
  
  <?xml version="1.0"?>
  <user xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <id>my_user</id>
    <credentials>
      <properties>
        <property>
          <name>os_password</name>
          <value>********</value>
        </property>
        <!-- The user domain name is only needed for openstack v3 identity api -->
        <property>
          <name>os_user_domain_name</name>
          <value>default</value>
        </property>
      </properties>
    </credentials>
  </user>

• Updating VIM using REST:

  
  PUT /ESCManager/v0/vims/{vim_id}
  HEADER: content-type, callback
   
  <?xml version="1.0"?>
  <vim_connector xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <!--unique id for each vim-->
    <id>example_vim</id>
    <type>OPENSTACK</type>
    <properties>
      <property>
        <name>os_auth_url</name>
        <value>{auth_url}</value>
      </property>
      <property>
        <name>os_project_name</name>
        <value>vimProject</value>
      </property>
      <!-- The project domain name is only needed for openstack v3 identity api -->
      <property>
        <name>os_project_domain_name</name>
        <value>default</value>
      </property>
      <property>
        <name>os_identity_api_version</name>
        <value>3</value>
      </property>
   </properties>
  </vim_connector>

• Updating VIM user using REST:

  
  PUT /ESCManager/v0/vims/{vim_id}/vim_users/{vim_user_id}
  HEADER: content-type, callback
   
  <?xml version="1.0"?>
  <user xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <id>my_user</id>
    <credentials>
      <properties>
        <property>
          <name>os_password</name>
          <value>********</value>
        </property>
        <!-- The user domain name is only needed for openstack v3 identity api -->
        <property>
          <name>os_user_domain_name</name>
          <value>default</value>
        </property>
      </properties>
    </credentials>
  </user>

• Deleting VIM using REST:

  DELETE /ESCManager/v0/vims/{vim_id}

• Deleting VIM user using REST:

  DELETE /ESCManager/v0/vims/{vim_id}/vim_users/{vim_user_id}

• Notification example after each VIM or VIM user configuration is done:

  
  <?xml version="1.0" encoding="UTF-8"?>
  <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
    <eventTime>2016-10-06T16:24:05.856+00:00</eventTime>
    <escEvent xmlns="http://www.cisco.com/esc/esc">
      <status>SUCCESS</status>
      <status_code>200</status_code>
      <status_message>Created vim connector successfully</status_message>
      <vim_connector_id>my-server</vim_connector_id>
      <event>
        <type>CREATE_VIM_CONNECTOR</type>
      </event>
    </escEvent>
  </notification>
  

  For more information on the APIs, see Cisco Elastic Services Controller API Guides.

  Important Notes:

  • You can add more than one VIM connector, but all the VIM connectors must have the same VIM type. Multiple VIM connectors can be added for OpenStack VIM only. However, only one VIM user can be configured per VIM connector.

  • os_project_name and os_project_domain_name properties specify the OpenStack project details for authentication and authorization under the VIM connector properties. If the os_tenant_name property exists under the Vim User, it will be ignored.

  • The VIM connector properties os_auth_url and os_project_name and VIM User property os_password are mandatory properties for the OpenStack VIM. If these properties are not provided, then the request to create the VIM connector is rejected.

  • VIM username and password can be updated anytime. VIM endpoint cannot be updated while resources created through ESC exist.

  • The name of a VIM property or VIM user credentials property are not case sensitive, e.g. OS_AUTH_URL and os_auth_url is the same to ESC.

You can encrypt the VIM connector credentials by replacing the existing <value> field with <encrypted_value>.

For example,

<credentials>
  <properties>
    <property>
      <name>os_password</name>
      <encrypted_value>********</encrypted_value>
    </property>
    <property>
      <name>os_user_domain_name</name>
      <value>default</value>
    </property>
  </properties>
</credentials>

This stores the os_value password as an aes-cfb-128-encrypted-string in the CFB using the keys contained in /opt/cisco/esc/esc_database/esc_production_confd.conf.

Note	The existing value must be replaced with encrypted value only within the credentials specified.

For more information, see Encrypting Configuration Data.

Creating Non-admin Roles for ESC Users in OpenStack

By default, OpenStack assigns an admin role to the ESC user. Some policies may restrict using the default admin role for certain ESC operations. Starting from ESC Release 3.1, you can create non-admin roles with limited permissions for ESC users in OpenStack.

To create a non-admin role,

1. Create a non-admin role in OpenStack.

2. Assign the non-admin role to the ESC user.

   You must assign ESC user roles in OpenStack Horizon (Identity) or using the OpenStack command line interface. For more details see, OpenStack Documentation.

   The role name can be customized in OpenStack. By default, all non-admin roles in OpenStack have the same level of permissions.

3. Grant the required permissions to the non-admin role.

   You must modify the policy.json file to provide the necessary permissions.

   Note	You must grant permissions to the create_port: fixed_ips and create_port: mac_address parameters in the policy.json file for ESC user role to be operational.

The table below lists the ESC operations that can be performed by the non-admin role after receiving the necessary permissions.

For more details on managing resources on OpenStack, see Managing Resources on OpenStack .

Overwriting OpenStack Endpoints

By default, ESC uses endpoints catalog return option provided by OpenStack after a successful authentication. ESC uses these endpoints to communicate with different APIs in OpenStack. Sometimes the endpoints are not configured correctly, for example, the OpenStack instance is configured to use KeyStone V3 for authentication, but the endpoint returned from OpenStack is for KeyStone V2. You can overcome this by overwriting the OpenStack endpoints.

You can overwrite (configure) the OpenStack endpoints while configuring the VIM connector. This can be done at the time of installation using the bootvm.py parameters, and using the VIM connector APIs.

The following OpenStack endpoints can be configured using the VIM connector configuration:

• OS_IDENTITY_OVERWRITE_ENDPOINT

• OS_COMPUTE_OVERWRITE_ENDPOINT

• OS_NETWORK_OVERWRITE_ENDPOINT

• OS_IMAGE_OVERWRITE_ENDPOINT

• OS_VOLUME_OVERWRITE_ENDPOINT

To overwrite OpenStack endpoints at the time of installation, a user can create an esc configuration parameters file, and pass the file as an argument to bootvm.py while deploying an ESC VM.

Below is an example of the param.conf file:

openstack.os_identity_overwrite_endpoint=http://www.xxxxxxxxxxx.com

For more information on configuring the VIM connector at the time of Installation, see Configuring the VIM Connector.

To overwrite (configure) the OpenStack endpoints for a non-default VIM connector using the VIM connector APIs (both REST and NETCONF), add the overwriting endpoints as the VIM connector properties either while creating a new VIM connector or updating an existing one.

Each VIM connector can have its own overwriting endpoints. There is no default overwriting endpoint.

In the example below, os_identity_overwrite_endpoint and os_network_overwrite_endpoint properties are added to overwrite the endpoints.

<esc_system_config xmlns="http://www.cisco.com/esc/esc">
  <vim_connectors>
    <!--represents a vim-->
    <vim_connector>
      <id>default_openstack_vim</id>
      <type>OPENSTACK</type>
      <properties>
        <property>
          <name>os_auth_url</name>
          <value>http://172.16.0.0:35357/v3</value>
        </property>
        <property>
          <name>os_project_domain_name</name>
          <value>default</value>
        </property>
        <property>
          <name>os_project_name</name>
          <value>admin</value>
        </property>
        <property>
          <name>os_identity_overwrite_endpoint</name>
          <value>http://some_server:some_port/</value>
        </property>
        <property>
          <name>os_network_overwrite_endpoint</name>
          <value>http://some_other_server:some_other_port/</value>
        </property>
      </properties>
    </vim_connector>
  </vim_connectors>
</esc_system_config>