Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation
Guide That Contains This Content
[+] Expand All
[-] Collapse All

    Using Server Manager to Automate Provisioning

    Overview of Server Manager

    Starting with Contrail Release 1.10, the Contrail Server Manager can be used to provision, configure, and reimage a Contrail virtual network system of servers, clusters, and nodes. Server Manager is an alternative to using Fabric commands to provision a Contrail system.

    This section describes the functions and usage guidelines for the Contrail server manager.

    The server manager provides a simple, centralized way for users to manage and configure components of a virtual network system running across multiple physical and virtual servers in a cloud infrastructure.

    You can use the server manager to configure, provision, and reimage servers with the correct software version and packages for the nodes that are running on each server in multiple virtual network system clusters.

    The server manager:

    • Provides REST APIs to handle customer requests.
    • Manages its own database to store information about the servers.
    • Interacts with other open source products such as Cobbler and Puppet to configure servers based on user requests.

    Server Manager Requirements and Assumptions

    The following requirements are assumed for the server manager:

    • The server manager runs on a Linux server (bare metal or virtual machine) and assumes availability of several software products with which it interacts to provide the functionality of managing servers.
    • The server manager has network connectivity to the servers it is trying to manage.
    • The server manager has access to a remote power management tool to power cycle the servers that it manages.
    • The server manager uses Cobbler software for Linux provisioning to configure and download software to physical servers. Cobbler resides on the same server that is running the server manager daemon.
      • Contrail 1.10 server manager assumes that DNS and DHCP servers embedded with Cobbler provide IP addresses and names to the servers being managed, although it is possible to use external DNS and DHCP servers.
    • The server manager uses Puppet software, an open source configuration management tool, to accomplish the configuration management of target servers, including the installation and configuration of different software packages and the launching of various services.
    • SQLite3 database management software is used to maintain and manage server configurations and it runs on the same machine where the server manager daemon is running.

    Server Manager Component Interactions

    The server manager runs as a daemon and provides REST APIs for interaction with the client. The server manager accepts user input in the form of REST API requests, performs the requested function on the resources, and responds to the user with a REST API response.

    Configuration parameters required by the server manager are provided in the server manager configuration file, however, the parameters can be overridden by server manager command line parameters.

    Figure 1 illustrates several high-level components with which the server manager interacts.

    Figure 1: Server Manager Component Interactions

    Server Manager Component Interactions

    Internally, the server manager uses a SQLite3 database to hold server configuration information. The server manager coordinates the database configuration information and user requests to manage the servers defined in the database.

    While managing the servers, the server manager also communicates with other software components. It uses Cobbler for reimaging target servers and it uses Puppet for provisioning, thereby ensuring necessary software packages are installed and configured, required services are running, and so on.

    A server manager agent runs on each of the servers and communicates with the server manager, providing the information needed to monitor the operation of the servers. The server manager agent also uses REST APIs to communicate with the server manager, and it can use other software tools to fetch other information, such as Nagios infrastructure monitoring, Razor spam filtering, Intelligent Platform Interface (IPMI), and so on. Monitoring functionality is not part of server manager for the Contrail release. It will be available at a later date.

    Configuring Server Manager

    When the installation of all server manager components and dependent packages is finished, configure the server manager with parameters that identify your environment and make it available for clients to serve REST API requests.

    Upon installation, a sample server manager configuration file is created at:

    /opt/contrail/server_manager/sm-config.ini

    Modify the sm-config.ini configuration file to include parameter values specific to your environment.

    The environment-specific configuration section of the sm-config.ini file is named SERVER-MANAGER.

    The following example shows the format and parameters of the SERVER-MANAGER section. Typically, only the listen_ip_addr, cobbler_user, and cobbler_passwd values need to be modified.

    [SERVER-MANAGER]
    
    listen_ip_addr = <IP-Address-of-SM>
    
    listen_port    = <port-number>
    
    database_name  = <database-file-name>
    
    server_manager_base_dir = <base-dir-where-SM-files-are-created>
    
    html_root_dir  = <html-root-dir>
    
    cobbler_ip_address = <cobbler-ip-address>
    
    cobbler_port   = <cobbler-port-number>
    
    cobbler_username = <cobbler-username>
    
    cobbler_password = <cobbler-password>
    
    puppet_dir    = <puppet-directory>
    
    ipmi_username = <IPMI username>
    
    ipmi_password = <IPMO password>
    
    ipmi_type = <IPMI type>

    Table 1 provides details for each of the parameters in SERVER-MANAGER section.

    Table 1: Server Manager Paremeters

    Parameter

    Configuration

    listen_ip_addr

    Specify the IP address of the server on which the server manager is listening for REST API requests.

    listen_port

    Specify the port number on which the server manager is listening for REST API requests. The default is 9001.

    database_name

    The name of the database file where the server manager stores configuration information. This file is created under server_manager_base_dir.

    server_manager_base_dir

    The base directory where all of the server manager configuration files are created. The default is /etc/contrail .

    html_root_dir

    The HTML root directory, /var/www/html .

    cobbler_ip_address

    The IP address used to access Cobbler. This address MUST be the same address as the listen_ip_address. The server manager assumes that the Cobbler service is running on the same server as the server manager service.

    cobbler_port

    The port on which Cobbler listens for user requests. Leave this field blank.

    cobbler_username

    The user name to access the Cobbler service. Specify cobblerunless your Cobbler settings have been modified to use a different user name.

    cobbler_password

    The password to access the Cobbler service. Specify cobbler unless your Cobbler settings have been modified to use a different password.

    puppet_dir

    The directory where the Puppet manifests and templates are created. This should be /etc/puppet, unless your Puppet configuration has been modified to use another directory.

    ipmi_username

    The IPMI username for power management.

    ipmi_password

    The IPMI password for power management.

    ipmi_type

    The IPMI type (ipmilan, or other cobbler supported types).

    Configuring the Cobbler DHCP Template

    In addition to configuring the server_config.ini file, you must manually change the settings in the /etc/cobbler/dhcp.template file to use the correct subnet address, mask, and DNS domain name for your environment. Optionally, you can also restrict the use of the current instance of the server manager and Cobbler to a subset of servers in the network.

    Below is a snippet from the dhcp.template file showing the fields to be modified.

    Note: The IP addresses and other values in the following are shown for example purposes only. Be sure to use values that are correct for your environment.

    subnet <ip address> netmask <ip address> {
    
        option routers                    <ip address>;
    
        option subnet-mask           <ip address>;
    
        option domain-name-servers  $next_server, <ip address> ;
    
        option domain-search        "demo.company.net", "company.net";
    
        option domain-name          "demo.company.net" ;
    
        option ntp-servers          $next_server;
    
        default-lease-time          21600;
    
        max-lease-time              43200;
    
        next-server                 $next_server;
    
        filename                    "/pxelinux.0";
    
    }

    User-Defined Tags for Server Manager

    Server manager provides the user the ability to define tags that can be used to group servers for performing a particular operation such as show information, reimage, provision, and so on. The server manager supports up to seven different tags that can be configured and used for grouping servers.

    The names of user-defined tags are kept in the tags.ini file, at /etc/contrail_smgr/tags.ini.

    It is possible to modify tag names, and add or remove tags dynamically using the server manager REST API interface. However, if a tag is already being used to group servers, the tag must be removed from the servers before tag modification is allowed.

    The following is a sample tags.ini file that is copied on installation. In the sample file, the user has defined five tags – datacenter, floor, hall, rack, and user_tag. The tags can be used to group servers together.

     [TAGS]
      tag1 = datacenter
      tag2 = floor
      tag3 = hall
      tag4 = rack
      tag5 = user_tag

    Server Manager Client Configuration File

    The server manager client application installation copies a sample configuration file, /opt/contrail/server_manager/client/sm-client-config.ini, that contains parameter values such as the IP address to reach the server manager, the port used by server manager, default values for cluster table entries, default values for server table entries, and so on. You must modify the values in the sm-client-config.ini file to match your environment.

    Use values from the CLUSTER and SERVER subsections in the ini file during creation of new clusters and servers, unless you explicitly override the values at the time of creation.

    The following is a sample client configuration file.

    [SERVER-MANAGER]  
    ; ip address of the server manager  
    ; replace the following with proper server manager address  
    listen_ip_addr = <ip address>  
    ; server manager listening port  
    listen_port    = 9001  
    [CLUSTER]  
    subnet_mask = <ip address>  
    domain = contrail.juniper.net  
    database_dir = /home/cassandra  
    encapsulation_priority = MPLSoUDP,MPLSoGRE,VXLAN  
    router_asn = <asn>  
    keystone_username = admin  
    keystone_password = <password>  
    password = <password>  
    analytics_data_ttl = 168  
    haproxy = disable  
    use_certificates = False  
    multi_tenancy = False  
    database_token =  
    service_token = <password>  
    analytics_data_ttl = 168  
    [SERVER]  

    Restart Services

    When all user changes have been made to the configuration files, restart the server manager to run with the modifications by issuing the following:

    service contrail-server-manager​ restart

    Accessing Server Manager

    When the server manager configuration has been customized to your environment, and the required daemon services are running, clients can request and use services of the server manager by using REST APIs. Any standard REST API client can be used to construct and send REST API requests and process server manager responses.

    The following steps are typically required to fully implement a new cluster of servers being managed by the server manager.

    1. Configure elements such as servers, clusters, and images in the server manager.

      Before managing servers, the server manager needs to have configuration details of the servers that the server manager is managing.

    2. Specify the name and location of boot images, packages, and repositories used to bring up the servers with needed software.

      Currently, the servers can be imaged with CentOS, Ubuntu Linux, or VMWare ESXi distributions.

    3. Provision or configure the servers by installing necessary packages, creating configuration files, and bringing up the correct services so that each server can perform the functions or role(s) configured for that server.

      A Contrail system of servers has several components or roles that work together to provide the functionality of the virtual network system, including: control, config, analytics, compute, web-ui, openstack, and database. Each of the roles has different requirements for software and services needed. The provisioning REST API enables the client to configure the roles on servers using the server manager.

    4. Set up API calls for monitoring servers.

      Once the servers in the Contrail system are correctly reimaged and provisioned to run configured roles, the server monitoring REST API calls allow clients to monitor performance of the servers as they provide one or more role functions. Monitoring functionality is not available in server manager for Contrail Release 1.10.

    Communicating with the Server Manager Client

    Server Manager provides a REST API interface for clients to talk to the server manager software. Any client that can send and receive REST API requests and responses can be used to communicate with server manager, for example, Curl or Postman. Additionally, the server manager software provides a client with a simplified CLI interface, in a separate package. The server manager client can be installed and run on the server manager machine itself or on another server with an IP connection to the server manager machine.

    Prior to using the server manager client CLI commands, youneed to modify the sm-client-config.ini file to specify the IP address and the port for the server manager, along with other parameters.

    Each of the commands described in this section takes a set of parameters from the user, constructs a REST API request to the server manager, and provides the server’s response to the user.

    The following describes each server manager client CLI command in detail.

    Server Manager Commands for Configuring Servers

    This section describes commands that are used to configure servers and server parameters in the server manager database. These commands allow you to add, modify, delete, or view servers.

    Create New Servers or Update Existing Servers

    Use the server-manager add command to create a new server or update a server in the server manager database.

    Usage:

    server-manager [-h] [--config_file CONFIG_FILE] server [-f FILE_NAME]
    

    Table 2 lists the optional arguments.

    Table 2: Server Manager Add Server Command Options

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    --file_name FILE_NAME, -f FILE_NAME

    The JSON file that contains the server parameter values.

    If no JSON file is specified, the client program accepts all the needed server parameter values interactively from the user, then builds a JSON file and makes a REST API call to the server manager. The JSON file contains a number of server entries, in the format shown in the following example:

    {
    
        "server": [
    
            {  
    
                "id": "demo2-server",
    
                "mac_address": "<mac address>",
    
                "ip_address": "<ip address>",
    
                "parameters" : {
    
                    "interface_name": "eth1",
    
                    "partition": ""
    
                },
    
                "roles" : ["config","openstack","control","compute","collector","webui","database"],
    
                "cluster_id": "demo-cluster",
    
                "subnet_mask": "<ip address>",
    
                "gateway": "<ip address>",
    
                "password": "<password>",
    
                "domain": "demo.company.net",
    
                "ipmi_address": "<ip address>",
    
                "tag" : {
    
                     "datacenter" : "demo-dc",
    
                     "floor" : "demo-floor",
    
                     "hall" : "demo-hall",
    
                     "rack" : "demo-rack",
    
                     "user_tag"  : "demo-user"
    
                 }
    
            }
    
        ]
    
    }

    Most of the parameters in the JSON sample file are self-explanatory. Cluster_id defines the cluster to which the server belongs. The interface_name is the Ethernet interface name on the server used to configure the server and roles define the roles that can be configured for the server. The sample roles array in the example lists all valid role values. Tag defines the list of tag values for grouping and classifying the server.

    The server-manager add command adds a new entry if the server with the given ID or mac_address does not exist in the server manager database. If an entry already exists, the add command modifies the fields in the existing entry with any new parameters specified.

    Delete Servers

    Use the server-manager delete command to delete one or more servers from the server manager database.

    Table 3 lists the optional arguments.

    Table 3: Server Manager Delete Server Command Options

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    --server_id SERVER_ID

    The server ID for the server or servers to be deleted.

    --mac MAC

    The MAC address for the server or servers to be deleted.

    --ip IP

    The IP address for the server or servers to be deleted.

    --cluster_id CLUSTER_ID

    The cluster ID for the server or servers to be deleted.

    --tag TagName=TagValue

    The TagName that is to be matched with the Tagvalue. Up to seven TagName and Tagvalue pairs separated by commas can be provided.

    The criteria to identify servers to be deleted can be specified by providing the server_id or the server: mac address, ip, cluster_id, or the TagName = TagValue. ​

    Provide one of the server matching criteria to display a list of servers available to be deleted.

    Show Server Configuration

    Use the server-manager show command to display the configuration of servers from the server manager database​.

    Usage:

    server-manager show  [--config_file CONFIG_FILE]
                          server (--server_id SERVER_ID | --mac MAC | --ip IP | --cluster_id CLUSTER_ID | --tag <tag_name=tag_value>.. ) [--detail]

    Table 4 lists the optional arguments.

    Table 4: Server Manager Show Server Command Options

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    --server_id SERVER_ID

    The server ID for the server or servers to be deleted.

    --mac MAC

    The MAC address for the server or servers to be displayed.

    --ip IP

    The IP address for the server or servers to be displayed.

    --cluster_id CLUSTER_ID

    The cluster ID for the server or servers to be displayed.

    --tag TagName=TagValue

    The TagName that is to be matched with the Tagvalue. Up to seven TagName and Tagvalue pairs separated by commas can be provided.

    --detail, -d

    Flag to indicate if details are requested.

    The criteria to identify servers to be displayed can be specified by providing the server_id or the server: mac address, ip, VNS_id, cluster_id, or TagName=TagValue. ​

    Provide one or more of the server matching criteria to display a list of servers.

    Server Manager Commands for Managing Clusters

    A cluster is used to store parameter values that are common to all servers belonging to that cluster. The commands in this section facilitate managing clusters in the server manager database, enabling the user to add, modify, delete, and view clusters.

    Note: Whenever a server is created with a specific cluster_id, Server Manager checks to see if a cluster with that ID has already been created. If there is no matching cluster_id already in the database, an error is returned.

    Create a New Cluster or Update an Existing Cluster

    Use the server-manager add command to create a new cluster or update an existing cluster in the server manager database.

    Usage:

    server-manager [-h] [--config_file CONFIG_FILE] 
    cluster [--file_name FILE_NAME]

    Table 5 lists the optional arguments.

    Table 5: Server Manager Add Cluster Command Options

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is:   /opt/contrail/server_manager/client/sm-client-config.ini

    --file_name FILE_NAME, -f FILE_NAME

    The JSON file that contains the cluster parameter values.

    If no JSON file is specified, the client program accepts all the needed cluster parameter values interactively from the user, then builds a JSON file and makes a REST API call to the server manager. The JSON file contains a number of cluster entries, in the format shown in the following example:

    {
    
        "cluster" : [
    
            {  
    
                "id" : "demo-cluster",
    
                "parameters" : {
    
                    "router_asn": "<asn>",
    
                    "database_dir": "/home/cassandra",
    
                    "database_token": "",
    
                    "use_certificates": "False",
    
                    "multi_tenancy": "False",
    
                    "encapsulation_priority": "MPLSoUDP,MPLSoGRE,VXLAN",
    
                    "service_token": "<password>",
    
                    "keystone_username": "admin",
    
                    "keystone_password": "<password>",
    
                    "keystone_tenant": "admin",
    
                    "analytics_data_ttl": "168",
    
                    "haproxy": "disable",
    
                    "subnet_mask": "<ip address>",
    
                    "gateway": "<ip address>",
    
                    "password": "<password>",
    
                    "external_bgp": "",
    
                    "domain": "<domain name"
    
                    }
    
            }
    
        ]
    
    }

    Server membership to a cluster is determined by specifying the ID corresponding to the cluster when defining the server. All of the cluster parameters are available to the server when provisioning roles on the server.

    Delete a Cluster

    Use the server-manager delete command to delete a cluster from the server manager database that are no longer needed and after all servers in the cluster have also been deleted.

    Usage:

    server-manager delete [-h] [--config_file CONFIG_FILE]
    
              cluster [--cluster_id CLUSTER_ID] 

    Table 6 lists the optional arguments.

    Table 6: Server Manager Delete Cluster Command Options

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    Show Cluster Configuration

    Use the server-manager show command to list the configuration of a cluster.

    Usage:

    server-manager show [-h] [ --config_file CONFIG_FILE]
    
                cluster [--cluster_id CLUSTER_ID] [--detail]

    Table 7 lists the optional arguments.

    Table 7: Server Manager Show Cluster Command Options

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    --detail, -d

    Flag to indicate if details are requested.

    --cluster_id CLUSTER_ID

    The cluster ID for the cluster or clusters.

    You can optionally specify a cluster ID to get information about a particular cluster. If the optional parameter is not specified, information about all clusters in the system is returned.

    Server Manager Commands for Managing Tags

    Tags are used for grouping servers together so that an operation such as get, reimage, provision, status, and so on can be easily performed on servers that have matching tags. The server manager provides a flexible way for users to define their own tags, then use those tags to assign values to servers. Servers with matching tag values can be easily grouped together. The server manager can store a maximum of seven tag values. At initialization, the server manager reads the tag names from the configuration file. The tag names can be retrieved or modified using CLI commands. When modifying tag names, the server manager ensures that the tag name being modified is not used by any of the server entries.

    Create a New Tag or Update an Existing Tag

    Use the server-manager add command to create a new or update a tag in the server manager database.

    Usage:

    server-manager add [-h] [--config_file CONFIG_FILE] 
    tag [--file_name FILE_NAME]

    Optional arguments include the following:

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    --file_name FILE_NAME, -f FILE_NAME

    The JSON file that contains the tag names.

    If no JSON file is specified, the client program prompts the user for tag names, then builds a JSON file and makes a REST API call to the server manager. The JSON file contains a number of tag entries, in the format shown in the following example:

    {
    
        "tag1" : "data-center",
    
        "tag2" : "floor",
    
        "tag3" : "",
    
        "tag4" : "pod",
    
        "tag5" : "rack",
    
    }
    

    In the example, the user is specifying JSON to add or modify the tags, tag1 thru tag5. For tag3, the “” value specifies that if the tag is defined prior to the CLI command, it is removed on execution of the command. The tag name for tag1 is set to data-center. This is allowed if, and only if, none of the server entries are using tag1.

    Show Tag Configuration

    Use the server-manager show command to list the configuration of a tag.

    Usage:

    server-manager show [-h] [ --config_file CONFIG_FILE] tag
    

    Optional arguments include the following:

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    The following is sample output for the show tag command.

    {
    
        "tag1": "datacenter",
    
        "tag2": "floor",
    
        "tag3": "hall",
    
        "tag4": "rack",
    
        "tag5": "user_tag"
    
    }

    Server Manager Commands for Managing Images

    In addition to servers and clusters, the server manager also manages information about images and packages that can be used to reimage and configure servers. Images and packages are both stored in the database as images. When new images are added to the database, or existing images are modified or deleted, the server manager interfaces with Cobbler to make corresponding modifications in the Cobbler distribution profile for the specified image.

    The image types currently supported are summarized in the following table:

    Image Type

    Description

    centos

    Manages the CentOS stock ISO, and does not include the Contrail packages repository packaged with the ISO.

    contrail-centos-package

    Maintains a repository of the package to be installed on the CentOS system image.

    ubuntu

    Manages the base Ubuntu ISO.

    contrail-ubuntu-package

    Maintains a repository of packages that contain Contrail and dependent packages to be installed on an Ubuntu base system.

    ESXi5.1/ESXi5.5

    Manages VMware ESXi 5.1 or 5.5 ISO.

    Creating New Images or Updating Existing Images

    The server manager maintains five types of images – CISO, Ubuntu ISO, ESXi hypervisor ISO, Contrail CentOS package, and Contrail Ubuntu package.

    Use the server-manager add command or the server-manager upload command to add new images to the server manager database.

    • Use add when the new image is present locally on the server manager machine. The path provided is the image path on the server manager machine.
    • Use upload_image when the new image is present on the machine where the client program is being invoked. The path provided is the image path on the client machine.

    Add an Image

    Usage:

    server-manager add [-h] [ --config_file CONFIG_FILE]
                              image [--file_name FILE_NAME]

    Optional arguments include the following:

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    --file_name FILE_NAME, -f FILE_NAME

    The name of the JSON file that contains the image parameter values.

    If no JSON file is specified, the client program accepts parameter values from the user interactively, then builds a JSON file and makes a REST API call to the server manager.

    The JSON file contains an array of possible entries, in the following sample format. The sample shows three images: one CentOS ISO containing Contrail packages, one Ubuntu base ISO, and one Contrail Ubuntu package. When the images were added, corresponding distribution, profile, and repository entries were created in Cobbler by the server manager.

    {
    
        "image": [
    
            {  
    
                "id": "ubuntu-12.04.3",
    
                "type": "ubuntu",
    
                "version": "ubuntu-12.04.3",
    
                "path": "/iso/ubuntu-12.04.3-server-amd64.iso"
    
            },
    
            {  
    
                "id": "centos-6.4",
    
                "type": "centos",
    
                "version": "centos-6.4",
    
                "path": "/iso/CentOS-6.4-x86_64-minimal.iso"
    
            },
    
            {  
    
                "id": "contrail-ubuntu-r11-b33",
    
                "type": "contrail-ubuntu-package",
    
                "version": "contrail-ubuntu-r11-b33",
    
                "path": "/iso/contrail-install-packages_1.11-33_all.deb"
    
            }
    
        ]
    
    }

    Upload an Image

    The server-manager upload_image command is similar to the server-manager add command, except that the path provided for the image being added is the local path on the client machine. This command is useful if the client is being run remotely, not on the server manager machine, and the image being added is not physically present on the server manager machine.

    Usage:

    server-manager upload_image [-h]
    
           --config_file CONFIG_FILE]
    
           image_id image_version image_type file_name

    Positional arguments include the following:

    Option

    Description

    image_id

    Name of the new image.

    image_version

    Version number of the new image.

    image_type

    Type of the image: fedora, centos, ubuntu, contrail- ubuntu-package, contrail-centos-package

    file_name

    Complete path for the file.

    Optional arguments include the following:

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    Delete an Image

    Use the server-manager delete command to delete an image from the server manager database. When an image is deleted from server manager database, the corresponding distribution, profile, or repository that corresponds to the image is also deleted from the Cobbler database.

    Usage:

    server-manager delete [-h]  [ --config_file CONFIG_FILE]
     image image_id

    Positional arguments include the following:

    Option

    Description

    image_id

    The image ID for the image to be deleted.

    Optional arguments include the following:

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    Show Image Configuration

    Use the server-manager show command to list the configuration of images from the server manager database. If the detail flag is specified, detailed information about the image is returned. If the optional image_id is not specified, information about all the images is returned.

    Usage:

    server-manager [-h] [--config_file CONFIG_FILE] image [--image_id IMAGE_ID] [--detail]

    Optional arguments include the following:

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    image_id

    The image ID for the image or images.

    --detail, -d

    Flag to indicate if details are requested.

    Server Manager Operational Commands for Managing Servers

    The server manager commands in the following sections are operational commands for performing a specific operation on a server or a group of servers. These commands assume that the base configuration of entities required to execute the operational commands is already completed using configuration CLI commands.

    Reimaging Server(s)

    Use the server-manager reimage command to reimage an identified server or servers with a provided base ISO and package. Servers are specified by providing match conditions to select servers from the database.

    Before issuing the reimage command, the images must be added to the server manager using the create image command, which also adds the images to Cobbler. The set of servers to be reimaged can be specified by providing match criteria for servers already added to the server manager database, using the server_id or server: vns_id, cluster_id, pod_id, or rack_id.

    You must identify the base image ID to be used to reimage, plus any optional Contrail package to be used. When a Contrail package is provided, a local repository is created that can be used for subsequent provisioning of reimaged servers.

    The command asks for a confirmation before making the REST API call to the server manager to start reimaging the servers. This confirmation message can be bypassed by specifying the optional --no_confirm or –F parameter on the command line.

    Usage:

    server-manager reimage [-h]
    
               [ --config_file CONFIG_FILE]
    
               [--package_image_id PACKAGE_IMAGE_ID]
    
               [--no_reboot]
    
               (--server_id SERVER_ID | --cluster_id CLUSTER_ID |--tag <tag_name=tag_value>)
    
               [--no_confirm]
    base_image_id

    Positional arguments include the following:

    Option

    Description

    base_image_id

    The image ID of the base image to be used.

    Optional arguments include the following:

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    --package_image_id PACKAGE_IMAGE_ID, -p PACKAGE_IMAGE_ID

    The optional Contrail package to be used to reimage the server or servers.

    --no_reboot, -n

    Optional parameter to indicate that the server should not be rebooted following the reimage setup.

    --server_id SERVER_ID

    The server ID for the server or servers to be reimaged.

    --cluster_id CLUSTER_ID

    The cluster ID for the server or servers to be reimaged.

    --tag TagName=TagValue

    TagName which is to be matched with Tagvalue

    --no_confirm, -F

    Flag to bypass confirmation message, default = do NOT bypass.

    Provisioning and Configuring Roles on Servers

    Use the server-manager provision command to provision identified server(s) with configured roles for the virtual network system. The servers can be selected from the database configuration (using standard server match criteria), identified in a JSON file, or provided interactively by the user.

    From the configuration of servers in the database, the server manager determines which roles to configure on which servers and uses this information along with other server and VNS parameters from the database to achieve the task of configuring the servers with specific roles.

    When the server-manager provision command is used, the server manager builds the manifest files corresponding to each of the servers and pushes them to the Puppet agent for execution upon the servers.

    Usage:

    server-manager provision [-h]
    
             [--config_file CONFIG_FILE]
              (--server_id SERVER_ID | --cluster_id CLUSTER_ID | --tag <tag_name=tag_value> | --provision_params_file PROVISION_PARAMS_FILE | --interactive)
              [--no_confirm]
              package_image_id

    Positional arguments include the following:

    Option

    Description

    package_image_id

    The Contrail package image ID to be used for provisioning.

    Optional arguments include the following:

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    --server_id SERVER_ID

    The server ID for the server or servers to be provisioned.

    --cluster_id CLUSTER_ID

    The cluster ID for the server or servers to be provisioned.

    --tag TagName=TagValue

    TagName to be matched with Tagvalue.

    --provision_params_file PROVISION_PARAMS_FILE, -f PROVISION_PARAMS_FILE

    Optional JSON file containing the parameters for provisioning the server(s).

    --interactive, -I

    Flag indicating that the user will manually enter the server parameters for provisioning.

    --no_confirm, -F

    Flag to bypass confirmation message, default = do NOT bypass.

    You can specify roles different from what is configured in the database by using the JSON file option parameter. When using the file option, the rest of the server parameters, the cluster parameters, and the list of servers must be configured before using the provision command. The following is a sample format for the file option:

    {
    
        "roles" : {
    
            "database" : ["demo2-server"],
    
            "openstack" : ["demo2-server"],
    
            "config" : ["demo2-server"],
    
            "control" : ["demo2-server"],
    
            "collector" : ["demo2-server"],
    
            "webui" : ["demo2-server"],
    
            "compute" :  ["demo2-server"]
    
        }
    
    }

    The final option for specifying roles for provisioning servers is to specify the –interactive option flag. When the provision command is used, the user is prompted to enter role definitions interactively.

    Restarting Server(s)

    Use the server-manager restart command to reboot identified server(s). Servers can be specified from the database by providing standard match conditions. The restart command provides a way to reboot or power-cycle the servers, using the server manager REST API interface. If reimaging is intended, use the restart command with the net-boot flag enabled. When netbooted, the Puppet agent is also installed and configured on the servers. If there are Puppet manifest files created for the server prior to rebooting, the agent pulls those from the server manager and executes the configured Puppet manifests. The restart command uses an IPMI mechanism to power cycle the servers, if available and configured. Otherwise, the restart command uses SSH to the server and the existing reboot command mechanism is used.

    Usage:

    server-manager restart [-h]
    
                [ --config_file CONFIG_FILE]
    
                 (--server_id SERVER_ID | --cluster_id CLUSTER_ID | --tag <tag_name=tag_value>)
    
                 [--net_boot]

    [--no_confirm]

    Optional arguments include the following:

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini.

    --server_id SERVER_ID

    The server ID for the server or servers to be restarted.

    --cluster_id CLUSTER_ID

    The cluster ID for the server or servers to be restarted.

    --tag TagName=TagValue

    TagName to be matched with Tagvalue.

    --net_boot, -n

    Optional parameter to indicate if the server should be netbooted.

    --no_confirm, -F

    Flag to bypass confirmation message, default = do NOT bypass.

    Show Status of Server(s)

    Use the server-manager status command to view the reimaging or provisioning status of server(s).

    Usage:

    server-manager status server [-h]
                                  [--config_file CONFIG_FILE]
                                  (--server_id SERVER_ID | --cluster_id CLUSTER_ID | --tag <tag_name=tag_value>)

    Optional arguments include the following:

    Option

    Description

    -h, --help

    Show the options available for the current command and exit.

    --config_file CONFIG_FILE, -c CONFIG_FILE

    The name of the server manager client configuration file. The default file is: /opt/contrail/server_manager/client/sm-client-config.ini

    --server_id SERVER_ID

    The server ID for the server whose status is to be fetched.

    --cluster_id CLUSTER_ID

    The cluster ID for the server or servers to be restarted.

    --tag TagName=TagValue

    TagName to be matched with Tagvalue.

    The status CLI provides a way to fetch the current status of a server.

    Status outputs include the following:

    • restart_issued

      reimage_started

      provision_started

      provision_completed

      database_started

      database_completed

      openstack_started

      openstack_completed

      config_started

      config_completed

      control_started

      control_completed

      collector_started

      collector_completed

      webui_started

      webui_completed

      compute_started

      compute_completed

    Server Manager REST API Calls

    This section describes all of the REST API calls to the server manager. Each description includes an example configuration.

    REST APIs for Server Manager Configuration Database Entries

    The REST API calls in this section help in configuring different elements in the server manager database.

    Note: The IP addresses and other values in the following are shown for example purposes only. Be sure to use values that are correct for your environment.

    API: Add a Server

    To add a new server to the service manager configuration database:

    URL : http://<SM-IP-Address>:<SM-Port>/server

    Method: PUT

    Payload: JSON payload containing array of servers to be added. For each server in the array, all the parameters are specified as JSON fields. The fields mask, gateway, password, and domain are optional, and if not specified, the values of these fields are taken from the cluster to which the server belongs.

    The following is a sample JSON file format for adding a server.

    {
        "server": [
            { 
                "id": "demo2-server",
                "mac_address": "<mac address>",
                "ip_address": "<ip address>",
                "parameters" : {
                    "interface_name": "eth1"
                },
                "roles" :  [
                                       "config",
                                       "openstack",
                                       "control",
                                       "compute",
                                       "collector",
                                       "webui",
                                       "database"
                ],
                "cluster_id": "demo-cluster",
                "mask": "<ip address>",
                "gateway": "<ip address>",
                "password": "juniper",
                "domain": "demo.company.net",
                "email": "id@company.net",
                "tag" : {
                                  "datacenter": "demo-dc",
                                  “rack” : “demo-rack”
                },
            }
        ]
    }
    
    

    API: Delete Servers

    Use one of the following formats to delete a server.

    URL: http://<SM-IP-Address>:<SM-Port>/server?server_id=SERVER_ID

    http://<SM-IP-Address>:<SM-Port>/server?cluster_id=CLUSTER_ID

    http://<SM-IP-Address>:<SM-Port>/server?mac=MAC

    http://<SM-IP-Address>:<SM-Port>/server?ip=IP

    http://<SM-IP-Address>:<SM-Port>/server[?tag=<tag_name>=<tag_value>,.]

    Method : DELETE

    Payload : None

    API: Retrieve Server Configuration

    Use one of the following methods to retrieve a server configuration. The detail argument is optional, and specified as part of the URL if details of the server entry are requested.

    URL: http://<SM-IP-Address>:<SM-Port>/server[?server_id=SERVER_ID&detail]

    http://<SM-IP-Address>:<SM-Port>/server[?cluster_id=CLUSTER_ID&detail]

    http://<SM-IP-Address>:<SM-Port>/server[?tag=<tag_name>=<tag_value>,.]

    http://<SM-IP-Address>:<SM-Port>/server[?mac=MAC&detail]

    http://<SM-IP-Address>:<SM-Port>/server[?ip=IP&detail]

    http://<SM-IP-Address>:<SM-Port>/server[?tag=<tag_name>=<tag_value>,.]

    Method : GET

    Payload : None

    API: Add an Image

    Use the following to add a new image to the server manager configuration database from the server manager machine.

    An image is either an ISO for a CentOS or Ubuntu distribution or an Ubuntu Contrail package repository. When adding an image, the image file is assumed to be available on the server manager machine.

    URL : http://<SM-IP-Address>:<SM-Port>/image

    Method: PUT

    Payload: Specifies all the parameters that define the image being added.

    {      
        "image": [
            {
                " id": "Image-id",
                "type": "image_type",  <ubuntu or centos or esxi5.1 or esxi5.5 or contrail-ubuntu-package or contrail-centos-package>
                "version": "image_version",
                "path":"path-to-image-on-server-manager-machine"
            }
        ]  
    }         

    API: Upload an Image

    Use the following to upload a new image from a client to the server manager configuration database.

    An image is an ISO for a CentOS or Ubuntu distribution or an Ubuntu Contrail package repository. Add image assumes the file is available on the server manager, whereas upload image transfers the image file from the client machine to the server manager machine.

    URL : http://<SM-IP-Address>:<SM-Port>/image/upload

    Method: PUT

    Payload: Specifies all the parameters that define the image being added.

    {      
        "image": [
            {
                " id": "Image-id",
                "type": "image_type",  <ubuntu or centos or esxi5.1 or esxi5.5 or contrail-ubuntu-package or contrail-centos-package>
                "version": "image_version",
                "path":"path-to-image-on-client-machine"
            }
        ]  
    }        

    API: Get Image Information

    Use the following to get image information.

    URL : http://<SM-IP-Address>:<SM-Port>/image[?image_id=IMAGE_ID&detail]

    Method: GET

    Payload: Specifies criteria for the image being sought. If no match criteria is specified, information about all the images is provided. The details field specifies if details of the image entry in the database are requested.

    API: Delete an Image

    Use the following to delete an image.

    URL : http://<SM-IP-Address>:<SM-Port>/image?image_id=IMAGE_ID

    Method: DELETE

    Payload: Specifies criteria for the image being deleted.

    API: Add or Modify a Cluster

    Use the following to add a cluster to the server manager configuration database. A cluster maintains parameters for a set of servers that work together in different roles to provide complete functions for a Contrail cluster.

    URL : http://<SM-IP-Address>:<SM-Port>/cluster

    Method: PUT

    Payload: Contains the definition of the cluster, including all the global parameters needed by all the servers in the cluster. The fields subnet_mask, gateway, password, and domain define parameters that apply to all servers in the VNS. These parameter values can be individually overridden for a server by specifying different values in the server entry.

    {
        "cluster" : [
            { 
                "id" : "demo-cluster",
                "parameters" : {
                    "router_asn": "<asn>",
                    "database_dir": "/home/cassandra",
                    "database_token": "",
                    "use_certificates": "False",
                    "multi_tenancy": "False",
                     "encapsulation_priority": "MPLSoUDP,MPLSoGRE,VXLAN",
                    "service_token": "<password>",
                    "keystone_user": "admin",
                    "keystone_password": "<password>",
                    "keystone_tenant": "admin",
                    "analytics_data_ttl": "168",
                    "subnet_mask": "<ip address>",
                    "gateway": "<ip address>",
                    "password": "<password>",
                    "haproxy": "disable",
                    "external_bgp": "",
                    "domain": "demo.company.net"
                     }
            }
        ]
     }
    
    

    API: Delete a Cluster

    Use this API to delete a cluster from the server manager database.

    URL : http://<SM-IP-Address>:<SM-Port>/cluster?cluster_id=CLUSTER_ID

    Method: DELETE

    Payload: None

    API: Get Cluster Configuration

    Use this API to get a cluster configuration.

    URL : http://<SM-IP-Address>:<SM-Port>/cluster[?cluster_id=CLUSTER_ID&detail]

    Method: GET

    Payload: None

    The optional detail argument is specified as part of the URL if details of the VNS entry are requested.

    API: Get All Server Manager Configurations

    Use this API to get all configurations of server manager objects, including servers, clusters, images, and tags.

    URL : http://<SM-IP-Address>:<SM-Port>/all[?detail]

    Method: GET

    Payload: None

    The optional detail argument is specified as part of the URL if details of the server manager configuration are requested.

    API: Reimage Servers

    Use one of the following API formats to reimage one or more servers.

    URL : http://<SM-IP-Address>:<SM-Port>/server/reimage?server_id=SERVER_ID
    http://<SM-IP-Address>:<SM-Port>/server/reimage?cluster_id=CLUSTER_ID
    http://<SM-IP-Address>:<SM-Port>/server/reimage?mac=MAC
    http://<SM-IP-Address>:<SM-Port>/server/reimage?ip=IP
    http://<SM-IP-Address>:<SM-Port>/server/reimage [?tag=<tag_name>=<tag_value>,.]

    Method: POST

    Payload: None

    API: Provision Servers

    Use this API to provision or configure one or more servers for roles configured on them.

    URL : http://<SM-IP-Address>:<SM-Port>/server/provision

    Method: POST

    Payload: Specifies the criteria to be used to identify servers which are being provisioned. The servers can be identified by server_id, mac, cluster_id or tags. See the following example.

    {
        server_id : <server_id> OR
        mac : <server_mac_address> OR
        cluster_id : <cluster_id> OR
        tag : {“data-center” : “dc1”} OR
        provision_parameters = {
        "roles" : {
            "database" : ["demo2-server"],
            "openstack" : ["demo2-server"],
            "config" : ["demo2-server"],
            "control" : ["demo2-server"],
            "collector" : ["demo2-server"],
            "webui" : ["demo2-server"],
            "compute" :  ["demo2-server"]
         }
       }
    }

    API: Restart Servers

    This REST API is used to power cycle the servers and reboot either with net-booting enabled or disabled.

    If the servers are to be reimaged and reprovisioned, the net-boot flag should be set.

    If servers are only being reprovisioned, the net-boot flag ​is not needed, however, the Puppet agent must be running on the target systems with the correct puppet configuration to talk to the puppet master running on the server manager.

    URL : http://<SM-IP-Address>:<SM-Port>/server/restart?server_id=SERVER_ID
    http://<SM-IP-Address>:<SM-Port>/server/restart?[netboot&]cluster_id=CLUSTER_ID
    http://<SM-IP-Address>:<SM-Port>/server/restart? [netboot&]mac=MAC
    http://<SM-IP-Address>:<SM-Port>/server/restart? [netboot&]ip=IP
    http://<SM-IP-Address>:<SM-Port>/server/restart ? [netboot&]tag=<tag_name>=<tag_value>

    Method: POST

    Payload: Specifies the criteria to be used to identify servers which are being restarted. The servers can be identified by their server_id, mac, cluster_id, or tag. The netboot parameter specifies if the servers being power-cycled are to be booted from Cobbler or locally.

    Example: Reimaging and Provisioning a Server

    This example shows the steps used in server manager software to configure, reimage, and provision a server running all roles of the Contrail system in a single-node configuration.

    Note: Component names and IP addresses in the following are used for example, only. To use this example in your own environment, be sure to use addresses and names specific to your environment.

    The server manager client configuration file used for the following CLI commands, is /opt/contrail/server_manager/client/sm-client-config.ini . It contains the values for the server IP address and port number as follows:

    [SERVER-MANAGER]

    listen_ip_addr = <ip address> (Server Manager IP address)

    listen_port = 9001

    The steps to be followed include:

    1. Configure cluster.
    2. Configure servers.
    3. Configure images.
    4. Reimage servers (either using servers configured above or using explicitly specified reimage parameters with the request).
    5. Provision servers (either using servers configured above or using explicitly specified provision parameters with the request).
    1. Configure a cluster.

      server-manager add cluster -f cluster.json

      Where cluster.json contains :

      {
          "cluster" : [
              { 
                  "id" : "demo-cluster",
                  "parameters" : {
                      "router_asn": "<asn>",
                      "database_dir": "/home/cassandra",
                      "database_token": "",
                      "use_certificates": "False",
                      "multi_tenancy": "False",
        "encapsulation_priority": "MPLSoUDP,MPLSoGRE,VXLAN",
                      "service_token": "<password>",
                      "keystone_user": "admin",
                      "keystone_password": "<password>",
                      "keystone_tenant": "admin",
                      "analytics_data_ttl": "168",
                      "subnet_mask": "<ip address>",
                      "gateway": "<ip address>",
                      "password": "<password>",
                    "haproxy": "disable",
                      "external_bgp": "",
                      "domain": "demo.company.net"
                      }
              }
          ]
      }
      
      
    2. Configure the server.

      server-manager add server –f server.json

      Where server.json contains :

      {
      "server": [
      {
      "id": "demo2-server",
      "mac_address": "<mac address>",
      "ip_address": "<ip address>",
      "parameters" : {
      "interface_name": "eth1",
      },
      "roles" : ["config","openstack","control","compute","collector","webui","database"],
      "cluster_id": "demo-cluster",
      "subnet_mask": "<ip address>",
      "gateway": "<ip address>",
      "password": "<password>",
      "domain": "demo.company.net",
      "ipmi_address": "<ip address>"
      }
      ]
      }
      
      
    3. Configure images.

      In the example, the image files for ubuntu 12.04.3 and contrail-ubuntu-164 are located at the corresponding image path specified on the server manager.

      server-manager add -c smgr_client_config.ini image –f image.json

      Where image.json contains:

      {
          "image": [
              {
                  " id": "ubuntu-12.04.3",
                  "type": "ubuntu",
                  "version": "ubuntu-12.04.3",
                  "path":"/iso/ubuntu-12.04.3-server-amd64.iso"
              },
              {
                  "id": "contrail-ubuntu-164",
                  "type": "contrail-ubuntu-package",
                  "version": "contrail-ubuntu-164",
                  "path":"/iso/contrail-install-packages_1.05-164~havana_all.deb"
              }
                        ]
      }
    4. Reimage servers.

      This step can be performed after the configuration in the previous steps is in the server manager database.

      server-manager reimage –server_id demo2-server –r contrail-ubuntu-164 ubuntu-12.04.3

    5. Provision servers.

      server-manager provision –server_id demo2-server contrail-ubuntu-164

    Note: Optionally, the Contrail package to be used can be specified with the reimage command, in which case the repository with the Contrail packages is created and made available to the target nodes as part of the reimage process. It is a mandatory parameter of the provision command.

    Modified: 2016-06-13