This chapter describes how to configure the Services Controller and Traffic Manager instance host, and how to deploy and configure Traffic Manager instances. It includes the following sections:
“Overview of Instances” on page 41
“Enabling Services Controller Communication with Instance Hosts” on page 42 “Adding Supporting Resources” on page 43
“Creating Instance Hosts” on page 45
“Deploying and Configuring Traffic Manager Instances” on page 46
Note: The procedures in this chapter are appropriate for all supported operating systems.
Overview of Instances
The information in this chapter assumes you have already installed the Services Controller and its related components, the Services Controller software is running, and you can access the REST API. For details, see Chapter 3, “Installing and Configuring the Services Controller Software.”
The instructions in this chapter describe how to configure a simple deployment. That is, a single Services Controller server and a single Traffic Manager instance host.
More complex deployments are supported and are described below.
Services Controller High Availability Deployments
Typically, high availability (HA) production environments deploy multiple copies of the Services Controller with multiple Traffic Manager instance hosts on each. Each instance host runs multiple Traffic Manager instances. For more information about HA configurations, see Chapter 10, “Configuring for High Availability.”
Configuring Traffic Manager Instances Enabling Services Controller Communication with Instance Hosts
Traffic Manager Instance Clusters
You can deploy Traffic Manager instances in clusters to ensure HA at the Traffic Manager level. By configuring Traffic Manager instance clusters using Traffic IP Groups, you can ensure that if one Traffic Manager instance in a cluster goes down, then the remaining active Traffic Manager instances in the cluster share the IP addresses, and therefore the traffic load, from the failed Traffic Manager instance. (This type of HA requires that you configure Traffic IP Groups in the Traffic Manager.)
While the Services Controller enables multiple instances to run on a host, it allows only one instance from a given cluster to be installed on an instance host. Adding another instance to the cluster requires another available instance host. This additional host enables the Services Controller to spread the traffic load, and thus promotes HA.
However, if the instance hosts are virtual machines, residing on the same physical host, HA is diminished because the entire cluster might be vulnerable to the failure of a single piece of hardware.
As a best practice, virtualized instance hosts should be distributed over multiple physical hosts.
Enabling Services Controller Communication with Instance
Hosts
The Services Controller uses passwordless SSH to communicate with your instance hosts. Passwordless SSH enables the Services Controller to copy files and remotely run commands to deploy, start, stop, upgrade, and delete Traffic Manager instances. When you add a new instance host to the Services Controller, you must set up the credentials to allow this.
To generate a new SSH key
1. As root user, generate a new SSH authentication key by running the following command on the Services Controller server (you must be logged in as the user used to run the Services Controller software):
ssh-keygen -t rsa
2. When prompted, enter a blank pass-phrase, and accept the default key location This operation results in the generation of these key files:
~/.ssh/id_rsa (certificate) ~/.ssh/id_rsa.pub (public key)
3. Use the ssh-copy-id command (included in the openssh-client package) to install your public key to the instance host authorized_keys file. For example:
ssh-copy-id root@<instancehost>
4. Return to the command line of the Services Controller and, as root user, connect to the new instance host by SSH. If you are successful, the credentials for passwordless SSH are correctly set up.
After these credentials have been set up, it is possible to add the host to the Services Controller system by means of a REST request.
Stingray Services Controller User’s Guide 43
Adding Supporting Resources Configuring Traffic Manager Instances
Adding Supporting Resources
Before you perform any of the following procedures, you must first obtain your Traffic Manager installation package (that is, a .tgz file) and an FLA-style license key. For details about retrieving your Traffic Manager licenses, see “To retrieve Stingray and Services Controller product licenses” on page 18.
You copy these files to the location specified by the Source File Location parameter during the installation process for the Services Controller. For detailed information see, “Required Installation Parameters” on
page 30.
Creating Version Resources
Perform the following procedures to create a REST API version resource. For detailed information about the properties for this resource, see “version Resource” on page 152.
To create a version resource
1. To create a version resource, perform a PUT request:
https://<sschost>:<port>/api/tmcm/1.4/version/9.7
Use the following JSON structure as the body of your request:
{
"version_filename" : "ZeusTM_97_Linux-x86_64.tgz", "info" : "Version 9.7"
}
Creating License Resources
Perform the following procedures to create a REST API license resource. For detailed information about the properties for this resource, see “license Resource” on page 146.
To create a version and license resource
1. To create a license resource for an FLA-style license key file (for example flexlic1), perform a PUT request:
https://<sschost>:<port>/api/tmcm/1.4/license/flexlic1
Include the following JSON structure as the body of your request:
{
"info" : "This is the resource for the flexlic1 license" }
Note: You can pass an empty JSON structure ({}) to the license resource because there are no mandatory properties for this resource type.
Verifying a Resource
You can use the Services Controller REST API to verify that all the required files are present and accessible. Perform a file status check GET request to verify that the Services Controller can find and access the files that are referred to in any of the defined resources.
Configuring Traffic Manager Instances Adding Supporting Resources
To verify a resource
1. To verify that the Services Controller can find and access the Traffic Manager package and license key files, perform a file status check GET request:
https://<sschost>:<port>/api/tmcm/1.4/status/files
The following output is displayed:
{ "licenses": [{ "href": "/api/tmcm/1.4/license/flexlic1", "name": "flexlic1", "present": true, "filename": "/var/lib/ssc/files/flexlic1" }], "versions": [{ "href": "/api/tmcm/1.4/version/9.7", "name": "9.7", "present": true, "filename": "/var/lib/ssc/files/ZeusTM_97_Linux-x86_64.tgz" }] }
Creating Feature Pack Resources
To complete the set of supporting resources required by a Traffic Manager instance, you must specify one or more feature packs with the required feature sets. The stm_sku value must be the name of one of the available sku resources created when the Services Controller was installed. The choice of SKU depends on a combination of:
the features you want to enable on the instances that will use the feature pack. the available licensed bandwidth for the SKU (for Enterprise Licensed customers). the metered cost of the SKU (for Cloud Service Provider licensed customers).
To create a feature pack
1. To create a feature_pack resource (for example, STM-U-CSP-200-FP), perform a PUT request:
https://<sschost>:<port>/api/tmcm/1.4/feature_pack/STM-U-CSP-200-FP
Use the following JSON structure as the body of your request to define the SKU:
{
"stm_sku" : "STM-U-CSP-200", "excluded" : ""
}
In this example, STM-U-CSP-200 represents an available sku resource in the Services Controller.
2. When complete, the following response is displayed:
{ "info": "", "status": "Active", "stm_sku": "STM-200", "add_on_skus": [], "excluded": "" }
Stingray Services Controller User’s Guide 45
Creating Instance Hosts Configuring Traffic Manager Instances
Creating Instance Hosts
After you create your Traffic Manager instance host, and all supporting resources are in place, you can add the instance host to the Services Controller configuration. This is the server on which you have the Services Controller deploy your Traffic Manager instances.
Note: An Instance Host resource is not required when you are only configuring one or more nonmanaged instances.
To create an instance host
1. Prepare a Traffic Manager instance host server:
This server must conform to the minimum requirements as specified in the release notes provided with your Services Controller software.
Set up the required credentials for passwordless SSH access between the Services Controller and your instance host server.
Create a working directory and installation root directory locations. These directories are set as
work_location and install_root during creation of the corresponding host resource in the next step. Verify that these directories have read, write, and execute permissions (770 in octal) set for both the user and group.
Verify that the instance host has an appropriate UTF-8 locale.
2. To create a new host resource for the Traffic Manager instance host server, perform a PUT request:
https://<sschost>:<port>/api/tmcm/1.4/host/ih1.mydomain.com
Use the following JSON structure as the body of your request (the directories used here are examples; substitute your own values):
{
"work_location" : "/var/lib/ssc/files", "install_root" : "/root/install", "username" : "root"
}
In this example, the resource name ih1.mydomain.com corresponds to the fully resolvable, qualified hostname of your instance host server. This correspondence is required by the Services Controller FLA license scheme.
3. To verify that the Services Controller server has access to the Traffic Manager instance host, perform a GET request. For example:
https://<sschost>:<port>/api/tmcm/1.4/host/ih1.mydomain.com?status_check=true
If the Services Controller detects any problems, they are reported under the status_check property of the returned resource. In this case, fix any reported problems and perform this procedure again.
Configuring Traffic Manager Instances Deploying and Configuring Traffic Manager Instances
If there are no problems, the request returns an empty status_check property. For example:
{ "info": "", "install_root": "/root/install", "work_location": "/var/lib/ssc/files", "status_check": {}, "username": "root", "status": "Active", "usage_info": "" }
Deploying and Configuring Traffic Manager Instances
After you have created and verified the host resource, you can deploy and configure your Traffic Manager instances. You may require that Linux Containers (LXC) are used during deployment.
This table summarizes the supported options for Traffic Manager instances.
Once preparations are complete for a managed instance, you can deploy an instance. See “Deploying a
Managed Instance” on page 56.
Nonmanaged instances are not deployed from the Services Controller. Required configuration Managed
Instance? Container? Network Isolation? Section Managed Instance in an LXC
Container with Network Isolation
Yes Yes Yes “Preparing to Deploy a Managed
Instance in a Container with Network Isolation” on page 47
Managed Instance in an LXC Container without Network Isolation
Yes Yes No “Preparing to Deploy a Managed
Instance in a Container without Network Isolation” on page 50 Managed Instance without
LXC Containers Yes No No “Preparing to Deploy a Managed Instance Outside of a Container” on page 52
Nonmanaged Instance No No No “Configuring a Nonmanaged
Stingray Services Controller User’s Guide 47
Deploying and Configuring Traffic Manager Instances Configuring Traffic Manager Instances
Preparing to Deploy a Managed Instance in a Container with Network
Isolation
Before deploying instances in a Linux container with network isolation, you must perform the following tasks:
Configure a virtual network on the instance host for the Traffic Manager instance. Typically, this configuration requires setting up a virtual bridge (using, for example, Linux bridge or Open vSwitch), then configuring the Linux container to attach to the bridge when running Traffic Manager.
Create a Linux container configuration file for the instance in which you specify the virtual network, the CPU usage, and the hostname of the instance (that is, the lxc.utsname setting). The name and location of the container configuration file is important:
– You must name the container configuration file <fqdn>.conf, where <fqdn> is the fully qualified domain name of the host. This hostname is the value of the lxc.utsname setting in the container configuration file.
– You must place the container configuration file in the installation root directory on the instance host. For example:
/root/install
Once these preparations are complete, you can deploy the instance. See “Deploying a Managed Instance”
on page 56.
Container Configuration File Example
The container configuration file must include networking entries for your Traffic Manager instance IP address. You can use either Linux virtual networking or Open vSwitch to set up network isolation for your Traffic Manager instance.
For example, a container configuration file, stm1.example.com.conf, uses Linux virtual networking:
lxc.utsname = stm1.example.com lxc.network.type = veth lxc.network.link = br0 lxc.network.flags = up lxc.network.ipv4 = XX.XX.XX.XX/SS lxc.network.ipv4.gateway = YY.YY.YY.YY In this example:
XX.XX.XX.XX/SS is the IP address and subnet mask of the LXC container network. YY.YY.YY.YY is the IP address of the subnetwork gateway inside the LXC container.
In addition, the configuration file can define any other characteristics (for example, CPU and memory usage) that will apply to the LXC container.
Properties for a Managed Instance in a Container with Network Isolation
The table below describes the REST API properties for a managed instance in a container with network isolation.
When you create the instance, make sure you assign the same name to both the instance and the container, because the instance uses the container name as its hostname.
Configuring Traffic Manager Instances Deploying and Configuring Traffic Manager Instances
For details of all instance properties, see “instance Resource” on page 137.
Property Description
host_name The name of the Traffic Manager instance host on which you deploy the instance. This name must match the fully qualified domain name of the instance host that was created. You must create a host entry before you create an instance.
container_name The name of the LXC container for the Traffic Manager instance. This name must match the name of the required container configuration (.conf) file in the installation directory. (Do not include the .conf file extension.)
You must create an appropriate container configuration file of the form <containername>.conf in the install_root directory of the container host. For example, a container_name of stm1.example.com requires a container configuration file named stm1.example.com.conf.
The container configuration file must set lxc.utsname to the container name for the licensing server to operate correctly.
container_configuration A JSON-formatted string used to set up the default network gateway inside the LXC container. Use this format:
"{\"gateway\":\"<ip_address>\"}"
For LXC deployments, this is the IP address raised on the bridge interface this container is connected to.
owner Specify who owns the instance.
stm_version The name of the Traffic Manager version resource for the instance.
stm_feature_pack The name of the feature_pack resource associated with the Traffic Manager instance. This feature pack represents the set of features that are available for the instance.
license_name The name of the FLA license resource you want to use for this instance. When you modify this property, the Services Controller updates the license on the Traffic Manager instance.
config_options If you specify the cluster_id property, then you must also set the config_options property to include admin_ui=yes and start_flipper=yes.
Note: Whenever the config_options property is set, all currently modified options must be specified again in the REST call. Any options that are not specified will lose their current value and be reset to their default value.
Note: Any change to the config_options settings on a managed instance will cause a restart of the instance. Nonmanaged instances are not affected.
bandwidth The maximum allowed bandwidth for the Traffic Manager instance (in units of Mbps).
tag A text property which provides an alternative way of referring to an instance. Unlike the unique ID for an instance, the tag value can be changed or reused, subject to some restrictions. See “Understanding the Tag Property” on page 49. Note: You cannot set the tag property on a service instance.
cpu_usage A string that describes which CPUs are used for this Traffic Manager instance. The CPU affinity is defined using the lxc.cgroups.cpuset setting in the container configuration file, in which case cpu_usage is set to an empty string.
Note: Any change to the cpu_usage settings of a managed instance will cause a restart of the instance. Nonmanaged instances are not affected.
Stingray Services Controller User’s Guide 49
Deploying and Configuring Traffic Manager Instances Configuring Traffic Manager Instances
Understanding the Tag Property
Each instance has a tag property which provides an alternative way of identifying the instance.
A tag is a user-friendly name which, unlike the unique ID for an instance, can be changed or reused (subject to some restrictions).
A tag is useful in the situation where you want to identify an instance by a consistent name. If an error occurs that requires that instance to be deleted, the unique ID is no longer available, as the instance persists with a Deleted status. The tag, however, can be reused on a new instance, enabling consistent naming. Restrictions to tag values are as follows:
A tag cannot be the same as a unique ID of any instance (except itself). This restriction includes Deleted instances.
A tag must be unique among the tags of all instances. This restriction does not include Deleted instances.
The tag property is available in the REST API only; it is not available in the Services Controller VA or Services Controller CLI.
Note: The tag property on a service instance is always an empty string. You cannot change this.
cluster_id Optionally, the name of a cluster resource to which the instance belongs. If you specify an entry for this property, it must refer to a cluster resource.
The cluster_id property cannot be changed after you create an instance. Instances must be added to a cluster when you create them. (This requirement also applies to the first instance in a cluster.)
If you specify the cluster_id property, then you must also set the config_options property to include admin_ui=yes and start_flipper=yes.
management_address In an LXC-isolated network, the management_address property is typically the same as the lxc.utsname and the container configuration filename (minus the .conf file extension). This property is a fully qualified domain name.
For example, if the container configuration filename is:
stm1.example.com.conf
and the lxc.utsname is defined as follows:
lxc.utsname = stm1.example.com
then the management_address is defined as follows:
management_address = stm1.example.com
Configuring Traffic Manager Instances Deploying and Configuring Traffic Manager Instances
Preparing to Deploy a Managed Instance in a Container without
Network Isolation
You can use LXCs for purposes other than network isolation. For example, LXCs can provide CPU and