Stack Manager for Mediant CE

Transcription

1 User's Manual Stack Manager for Mediant CE Version 7.2

2

3 User's Manual Contents Table of Contents 1 Introduction Deployment Operational Environment Deployment Topology IAM Role for Stack Manager Subnet and Elastic IPs Security Groups Distribution Installation Runtime Data Storing Runtime Data on AWS S Operational Logs CLI Interface Accessing CLI Interface Invocation Usage Configuring Stack Manager Verifying Stack Manager s Configuration name prefix create stack SBC Cluster Configuration Tool Sample Configuration File list stacks show stack Stack Deployment Details Stack Deployment in AWS Environment Adjusting Configuration of Security Groups Using Pre-Defined Elastic IPs Using Pre-Defined Private IPs Cluster Scaling scale-out stack scale-in stack scale stack Automatic Scaling Cool Down Period Auto Scale Step Changing Cluster Size at Specific Time of Day modify stack update stack Service Interruption During Stack Update Upgrading Software on Idle Media Components stop stack start stack delete stack purge stack heal stack Version Mediant CE

4 Stack Manager Automatic Healing Multiple Operations REST API Overview Asynchronous Tasks Authentication Discovery list stacks show stack create stack delete stack purge stack heal stack scale-in stack scale-out stack scale stack modify stack update stack stop stack start stack Get Global Configuration Update Global Configuration User's Manual 4 Document #: LTRT-28905

5 User's Manual Notices Notice Information contained in this document is believed to be accurate and reliable at the time of printing. However, due to ongoing product improvements and revisions, AudioCodes cannot guarantee accuracy of printed material after the Date Published nor can it accept responsibility for errors or omissions. Updates to this document can be downloaded from This document is subject to change without notice. Date Published: June WEEE EU Directive Pursuant to the WEEE EU Directive, electronic and electrical waste must not be disposed of with unsorted waste. Please contact your local recycling authority for disposal of this product. Customer Support Customer technical support and services are provided by AudioCodes or by an authorized AudioCodes Service Partner. For more information on how to buy technical support for AudioCodes products and for contact information, please visit our Web site at Abbreviations and Terminology Each abbreviation, unless widely used, is spelled out in full when first used. Document Revision Record LTRT Description Initial document release for Version 7.2. Documentation Feedback AudioCodes continually strives to produce high quality documentation. If you have any comments (suggestions or errors) regarding this document, please fill out the Documentation Feedback form on our Web site at Version Mediant CE

6 Stack Manager This page is intentionally left blank. User's Manual 6 Document #: LTRT-28905

7 User's Manual 1. Introduction 1 Introduction Stack Manager is used for managing 'software stacks' deployed in virtual environments. It implements the complete stack lifecycle, including: Stack deployment Stack termination Manual stack size adjustment using user-initiated scale-in / scale-out Automatic stack size adjustment using automatic scaling Stack configuration update Initial implementation supports Mediant CE (Cloud Edition) SBC in the Amazon Web Services (AWS) environment. Future versions will add support for additional cloud environments (e.g., Microsoft Azure) and optionally other products. Stack Manager provides CLI and REST APIs, that implement VNFM (Virtual Network Function Manager) functionality as defined in the NFV Management and Organization (MANO) architectural framework. Version Mediant CE

8 Stack Manager This page is intentionally left blank. User's Manual 8 Document #: LTRT-28905

9 User's Manual 2. Deployment 2 Deployment 2.1 Operational Environment Stack Manager is implemented as a set of Python scripts that may run on one of the following operating systems: Ubuntu Linux Amazon Linux Red Hat Linux 7 CentOS Linux Deployment Topology Stack Manager needs to have access to the following API s for correct operation: Virtual Infrastructure Management API e.g., AWS API for deploying stack components and managing their lifecycle Management and Automation API of the 'software stack' e.g., REST API of Mediant CE for assessing operational status of deployed stack instances and managing their configuration and state Figure 2-1: Stack Manager Deployment Topology Virtual Infrastructure Management API Stack Manager Management & Automation API Stack #1 Stack #2 If you are using Stack Manager for deploying Mediant CE stacks in the AWS environment, the simplest way to satisfy these requirements is as follows: Deploy Stack Manager on a virtual instance running in the same AWS Virtual Private Cloud (VPC) as Mediant CE stack(s) that will be deployed. Version Mediant CE

10 Stack Manager Create the IAM Role that enables Stack Manager to access all needed AWS APIs (see Section for the detailed description) and attach it to the Stack Manager s virtual instance. Connect Stack Manager s virtual instance to the same 'OAM Subnet' that will be used for carrying management traffic of deployed Mediant CE stack(s) and assign it with the Elastic IP (see Section for the detailed description) IAM Role for Stack Manager The following IAM role ensures that Stack Manager can access all needed AWS APIs for successful stack deployment and management. This role must be attached to the Stack Manager s virtual instances as described in Section 2.4. "Version": " ", "Statement": [ "Action": [ "ec2:*", "cloudwatch:*", "cloudformation:*", "iam:passrole", "iam:listinstanceprofiles" ], "Effect": "Allow", "Resource": "*" ] To create an IAM Role 1. Open the AWS IAM console. 2. Under Policies create a new policy as specified above 3. Under Rules create a new rule based on the policy created in the previous step Subnet and Elastic IPs Stack Manager uses the following IP addresses when communicating with Mediant CE stack instances that it deploys: If stack instance has Elastic IP assigned to its management (OAM) interface, Stack Manager will use this Elastic IP to access stack instance s automation and management API. Otherwise, Stack Manager will use private IP address of stack s management (OAM) interface. The simplest way to enable Stack Manager to properly access deployed Mediant CE stack s automation and management APIs is by deploying Stack Manager to the same OAM Subnet that will be used for carrying management traffic of deployed Mediant CE stack(s). You should always assign Elastic IP to the Stack Manager because it is needed for proper communication with AWS API. User's Manual 10 Document #: LTRT-28905

11 User's Manual 2. Deployment Security Groups Security Groups of the OAM Subnet and of the virtual instance where Stack Manager is installed must allow Stack Manager to communicate with both AWS API and deployed Mediant CE stack instances using HTTPS protocol (Port 443). 2.3 Distribution Stack Manager is distributed as a ZIP archive stack_mgr.zip that includes installation script install.sh. 2.4 Installation The procedure below describes how to install Stack Manager. To install Stack Manager: 1. Create a new AWS virtual instance with one of the supported operating systems. For example, launch the following new AWS instance: Image (AMI): Ubuntu Server LTS (HVM), SSD Volume Type Instance Type: t2.small Storage: 8 GiB 2. Attach the IAM role, created in Section 2.2.1, to the Stack Manager s virtual instance. 3. Connect Stack Manager s virtual instance to the 'OAM Subnet' that will be used for carrying management traffic of deployed Mediant CE stack(s). Assign an Elastic IP address to the Stack Manager s virtual instance as described in Section Make sure that Security Groups of the 'OAM Subnet' and Stack Manager s virtual instance allow Stack Manager to communicate with both AWS API and deployed Mediant CE stack instances. as described in Section Login to the launched virtual instance via SSH using the credentials obtained during the launch. 6. Transfer the 'installation package' (stack_mgr.zip) to the virtual instance using the SCP/SFTP protocol. 7. Run the following commands: $ unzip stack_mgr.zip $ chmod 755 stack_mgr/install.sh $ sudo stack_mgr/install.sh The Stack Manager is installed in the /opt/stack_mgr directory. Version Mediant CE

12 Stack Manager 2.5 Runtime Data Stack Manager uses stack descriptors to keep information about created stacks, including their configuration and references to all corresponding resources. By default, Stack Manager stores this information on the local file system in the /opt/stack_mgr/data directory. However, you may configure Stack Manager to store the stack descriptors in AWS Simple Cloud Storage Service (S3) as described below. Doing so significantly improves runtime data availability and provides service continuity if the Stack Manager instance must be rebuilt. Note: Stack descriptors are for internal Stack Manager use and should not be manipulated by the user Storing Runtime Data on AWS S3 The procedure below describes how to configure Stack Manager to store its runtime data on AWS S3. To configure Stack Manager to store its runtime data on AWS S3: 1. Create a new S3 bucket in the same region where the Stack Manager instance is deployed. Enter the bucket name e.g., stack-mgr. Figure 2-2: Create Bucket User's Manual 12 Document #: LTRT-28905

13 User's Manual 2. Deployment 2. Create a new IAM policy that allows the Stack Manager instance to access data in the created S3 bucket. In the 'Bucket name' field, replace stack-mgr with the actual name of the bucket that you created. "Version": " ", "Statement": [ "Effect": "Allow", "Action": [ "s3:listbucket" ], "Resource": "arn:aws:s3:::stack-mgr", "Effect": "Allow", "Action": [ "s3:putobject", "s3:getobject", "s3:deleteobject" ], "Resource": "arn:aws:s3:::stack-mgr/*" 3. Attach the created IAM policy to the Stack Manager instance (in addition to the policy created in Section 2.2.1) 4. Login to the Stack Manager instance via SSH using the credentials obtained during instance launch 5. Run the following commands to configure Stack Manager to use the created S3 bucket. Replace stack-mgr with the actual name of the bucket that you created. $ stack_mgr_cli 6. $ stack_mgr configure -s3-bucket stack-mgrverify configuration by running the following command: $ stack_mgr configure -s3-verify Verify access to S3 API... done 2.6 Operational Logs Stack Manager stores its logs in the /var/log/stack_mgr directory. The following files are created: stack_mgr.log main log file auto_scale.log auto-scale logs rest_api.log REST API logs rest_api_access.log REST API access log rest_api_error.log REST API error log Log files are rotated daily. Up to seven copies of each file are stored. Version Mediant CE

14 Stack Manager This page is intentionally left blank. User's Manual 14 Document #: LTRT-28905

15 User's Manual 3. CLI Interface 3 CLI Interface 3.1 Accessing CLI Interface Stack Manager s CLI interface is accessed by switching to the stack_mgr user using the following command: $ stack_mgr_cli If the above command doesn t work, use the following alternative command to do the same: $ sudo su - stack_mgr 3.2 Invocation 3.3 Usage Most of the Stack Manager CLI is provided using the stack_mgr command. Auto-completion is available for sub-commands and optional parameters. Brief usage information is provided by running the stack_mgr command without arguments: $ stack_mgr usage: stack_mgr [-h] [--version] create,delete,purge,list,show,scale-out,scalein,heal,auto-scale,update... More detailed usage information is provided when '-h' or '--help' arguments are specified: $ stack_mgr --help usage: stack_mgr [-h] [--version] create, delete,purge, list, show, scale-out, scale-in, heal, auto-scale, update... AudioCodes Stack Manager positional arguments: create, delete, purge, list, show, scale-out, scale-in, heal, auto-scale, update, modify, reboot,stop,start,configure create create stack delete delete stack list list stacks show show stack scale-out scale out stack scale-in scale in stack scale scale stack heal heal stack modify modify stack configuration update update stack stop stop stack Version Mediant CE

16 Stack Manager start purge configure optional arguments: -h, --help --version start stack purge stack stack manager configuration show this help message and exit show program's version number and exit 3.4 Configuring Stack Manager Before using Stack Manager, you need to ensure that it has access to AWS APIs. The simplest way to do so is to create the IAM role, as described in Section 2.2.1, and attach it to the Stack Manager s virtual instance during its creation, as described in Section 2.4. Alternatively, you may configure AWS access and a secret key using the configure command, as described below. Make sure that the provided credentials correspond to the user account which has the same policy as described in Section 1.2.1,: CloudFormation: full access CloudWatch: full access EC2: full access IAM: list, write $ stack_mgr configure --help usage: stack_mgr configure [-h] [--aws-access-key AWS_ACCESS_KEY] [--aws-secret-key AWS_SECRET_KEY] [--aws-verify] [--name-prefix NAME_PREFIX] [--rest-api-username REST_API_USERNAME] [--rest-api-password REST_API_PASSWORD] [--s3-bucket S3_BUCKET] [--s3-verify] optional arguments: -h, --help show this help message and exit --aws-access-key AWS_ACCESS_KEY AWS access key --aws-secret-key AWS_SECRET_KEY AWS secret key --aws-verify Verify access to AWS API --name-prefix NAME_PREFIX Prefix to be assigned to stacks and instances --rest-api-username REST_API_USERNAME REST API username --rest-api-password REST_API_PASSWORD REST API password --s3-bucket S3_BUCKET S3 bucket name --s3-verify Verify access to S3 API User's Manual 16 Document #: LTRT-28905

17 User's Manual 3. CLI Interface For example: $ stack_mgr configure --aws-access-key ABCDEFG --aws-secret-key Verifying Stack Manager s Configuration Use the '--aws-verify' argument to verify that Stack Manager can successfully connect to AWS API: $ stack_mgr configure --aws-verify Verify access to AWS API... done name prefix By default, AWS resources created by Stack Manager (e.g., EC2 instances) use the following naming convention: <stack name>-<resource name> For example, for stack 'stack1' corresponding resources will be named stack1-sc-1, stack1-mc-1 etc. It is possible to define additional prefix that will be added to created resources via the following command: $ stack_mgr configure --name-prefix lab1- In this case, corresponding resources will be named lab1-stack1-sc-1 etc. 3.5 create stack The create command creates a new stack. You must specify the stack name and provide the stack configuration file. $ stack_mgr create --help usage: stack_mgr create [-h] name cfg_file positional arguments: name cfg_file optional arguments: -h, --help Name of the stack; may contain letters, numbers and dash symbol only (spaces are not allowed) configuration file Show this help message and exit Version Mediant CE

18 Stack Manager Note: Prior to creating Mediant CE stack instance(s) make sure that the following prerequisites are met: You have copied the Mediant CE official AMI to your account You have created an IAM role that enables the Mediant CE to manage its network interfaces You have created all subnets needed for Mediant CE deployment, including the Cluster Subnet with the NAT Gateway Refer to the Mediant Cloud Edition Installation Manual for additional information. The manual can be downloaded from the AudioCodes Web site at The configuration file may be created in one of the following ways: Using the SBC Cluster Configuration Tool (recommended). See the detailed description below. Copying the sample configuration file from the /opt/stack_mgr/cfg directory and modifying it on the server with a text editor (e.g., vi or nano ). Copying the sample configuration file from the /opt/stack_mgr/cfg directory, transferring it from the server via SFTP/SCP to the PC, modifying it using regular text editor (e.g., Notepad) and transferring it back to the server. $ cp /opt/stack_mgr/cfg/sbc-cluster.cfg stack1.cfg $ vi stack1.cfg If you modify the stack configuration file using a text editor (instead of using the SBC Cluster Configuration Tool), make sure the following parameters are updated: aws_region Defines the AWS region where the Mediant CE stack will be deployed. vpc_id Defines the VPC where the Mediant CE stack will be deployed. *_subnet_id Defines the subnet IDs for all applicable subnets. ssh_key_pair Defines the SSH key pair that will be used for connecting to the Mediant CE command-line interface. *_image_id Defines the AMI ID of the local copy of the Mediant VE/CE SBC image. sc_iam_role Defines the SBC IAM Role name. Refer to the Mediant CE Installation Manual for detailed instructions on how to create this role. The create process takes a few minutes and detailed progress information is displayed on the console: $ stack_mgr create stack1 sbc-cluster.cfg Initializing AWS client... done Creating SBC network resources... done Creating SBC media components... done Creating SBC signaling components... done Waiting until signaling components are ready... done Waiting until media components are ready... done Removing media components 'mc-3, mc-4, mc-5' from SBC configuration Removing media components 'mc-3, mc-4, mc-5'... done Stopping components 'mc-3, mc-4, mc-5'... done Use to connect to the management interface. Stack 'stack1' is successfully created User's Manual 18 Document #: LTRT-28905

19 User's Manual 3. CLI Interface 3.6 SBC Cluster Configuration Tool The SBC Cluster Configuration Tool provides a simple interactive user interface (UI) for creating the configuration file. To run the tool, enter sbc_cluster_config. You will be asked to provide basic SBC cluster configuration parameters and a new configuration file will be created. You may use this file to create the SBC cluster using the stack_mgr create command described above. It is recommended to review the created file prior to SBC cluster creation and adjust it if needed. $ sbc_cluster_config SBC Cluster Configuration Tool This tool creates a configuration file that may be used to create the Mediant CE cluster using the stack_mgr create command. Enter configuration file name: stack1.cfg List of AWS regions: # name ap-south-1 2 eu-west-3 3 eu-west-2 4 eu-west-1 5 ap-northeast-2 6 ap-northeast-1 7 sa-east-1 8 ca-central-1 9 ap-southeast-1 10 ap-southeast-2 11 eu-central-1 12 us-east-1 13 us-east-2 14 us-west-1 15 us-west Choose region: 11 List of AWS VPCs: Version Mediant CE

20 Stack Manager # id name cidr block vpc-45f3152c /16 2 vpc c QAAUTO_VPC /16 3 vpc-39d23352 QAOVOC / Choose VPC: 1 Copy the official Mediant VE SBC AMI published by AudioCodes, to your account and use it instead of the public one. This ensures that your cluster will be able to scale even if the public AMI becomes unavailable, for some reason. Enter AMI ID: ami-9a50cff5 Key Pair is used to provide secure access to the SBC cluster's CLI interface using the SSH protocol. It is mandatory for the AWS environment even though the SBC, in its default configuration, supports the SSH login using username/password # name qa_key 2 qa_auto_key 3 aws_ssh_frankfurt_ Choose key pair: 3 You must create the IAM role that allows the SBC to manage its IP addresses. The role must look like, as follows: "Version": " ", "Statement": [ "Action": [ "ec2:assignprivateipaddresses", "ec2:unassignprivateipaddresses", "ec2:associateaddress", "ec2:describeaddresses", "ec2:describenetworkinterfaceattribute", "ec2:describenetworkinterfaces", "s3:get*", "s3:list*" ], "Effect": "Allow", "Resource": "*" User's Manual 20 Document #: LTRT-28905

21 User's Manual 3. CLI Interface ] Refer to the Mediant CE Installation Manual for additional information. Enter IAM role: SBC-HA-3 Instance type of Signaling Components (SC) is r4.2xlarge. Instance type of Media Components (MC) depends on their profile # mc profile instance type forwarding r4.large 2 transcoding c4.4xlarge Enter media components profile: 1 Signaling Component (SC) network interfaces are connected as follows: - eth0: cluster - eth1: oam - eth2: signaling1 - eth3: signaling2 At least two network interfaces are required. Notes: - "eth1" may carry both OAM and SIGNALING traffic. - Primary IP addresses are not used except for "eth0" (cluster interface). Secondary IP addresses are used instead and "float" across the two SC instances (in HA configuration). Enter the number of interfaces for signaling components (2, 3 or 4): 2 To access instances deployed in AWS from outside the VPC you must assign Elastic IPs to the relevant network interfaces. Provide a comma-separated list of SC network interfaces that will be assigned with Elastic IP addresses. For example: "eth1" or "eth1,eth2" Notes: Version Mediant CE

22 Stack Manager - Elastic IP cannot be assigned to "eth0" because it is used for Internal cluster management. - If you want to access SBC management interface from outside the VPC, assign Elastic IP to the "eth1" interface. - If you do not need Elastic IPs, press Enter to continue. Enter value: eth1 Media Component (MC) network interfaces are connected as follows: - eth0: cluster - eth1: oam - eth2: media1 - eth3: media2 At least two network interfaces are required. Notes: - "eth1" may carry both OAM and MEDIA traffic. - Primary IP addresses are available on all interfaces. Enter the number of interfaces for media components (2, 3 or 4): 2 To access instances deployed in the AWS from outside the VPC, you must assign Elastic IPs to the relevant network interfaces. Provide a comma-separated list of MC network interfaces that will be assigned with Elastic IP addresses. For example: "eth1" or "eth1,eth2" Notes: - The Elastic IP cannot be assigned to "eth0" because it is used for internal cluster management. - If you do not need Elastic IPs, press Enter to continue. Enter value: eth1 Cluster subnet carries internal traffic between SBC cluster components and is used for accessing the AWS API. It must have the NAT Gateway attached, as all communication (including AWS API access) is done using private IP addresses. The subnet is connected to both signaling (SC) and media (MC) components. Use a dedicated subnet and protect it from unauthorized access # id name cidr range avail. zone subnet-be6e8bc3 cluster /20 eu-central-1b 2 subnet-e19c649c test /20 eu-central-1a User's Manual 22 Document #: LTRT-28905

23 User's Manual 3. CLI Interface 3 subnet-1536d368 oam /2 eu-central-1b Cluster subnet: 1 OAM subnet carries management traffic (HTTP, SSH, NTP, etc.). It is connected to both signaling (SC) and media (MC) components. Despite the name, OAM subnet may also carry signaling (SIP) and media (RTP) traffic # id name cidr range avail. zone subnet-1536d368 oam /2 eu-central-1b OAM subnet: 1 The size of the cluster, and specifically the number of media components, may vary to match the required service capacity. This ensures that the cluster utilizes optimal amount of resources at any point of time and elastically scales on demand. The scaling decision may be done either manually - by executing 'scale-in' or 'scale-out' commands - or automatically based on the current cluster utilization. The size of the cluster is controlled by the following two parameters: * Minimum Number of Media Components * Maximum Number of Media Components To ensure the fast scaling, Stack Manager pre-creates all needed media components in advance (up to the maximum number) and stops/starts them accordingly during scale in/out operations. Minimum Number of Media Components (0-21): 2 Maximum Number of Media Components (2-21): 5 Creating configuration file stack1.cfg Done Version Mediant CE

24 Stack Manager Note: When selecting the region, VPC, subnets and other listed objects, enter either a corresponding row number (e.g., 1 ) or an Object ID (e.g., vpc-45f3152c ). 3.7 Sample Configuration File The following is a sample configuration file for Mediant CE in the AWS cloud: # # Stack descriptor # # stack type stack_type = sbc-cluster # virtual infrastructure manager vim = aws # # Generic parameters # # Initial cluster size mc_num = 2 # Minimal cluster size min_mc_num = 2 # Maximum cluster size max_mc_num = 5 # # Auto-scaling configuration # # Auto-scaling - enable/disable auto_scale = disable # Media utilization scale in threshold - in accumulative free # percentage points (when auto-scaling is enabled and total # amount of free resources in the cluster raises above this # threshold scale-in will be triggered) media_util_scale_in_threshold = 250 # Media utilization scale out threshold - in accumulative free # percentage points (when auto-scaling is enabled and total # amount of free resources in the cluster falls below this # threshold scale-in will be triggered) User's Manual 24 Document #: LTRT-28905

25 User's Manual 3. CLI Interface media_util_scale_out_threshold = 100 # DSP utilization scale in threshold - in accumulative free # percentage points (when auto-scaling is enabled and total # amount of free resources in the cluster raises above this # threshold scale-in will be triggered) dsp_util_scale_in_threshold = 0 # DSP utilization scale out threshold - in accumulative free # percentage points (when auto-scaling is enabled and total # amount of free resources in the cluster falls below this # threshold scale-in will be triggered) dsp_util_scale_out_threshold = 0 # Auto-scaling cool down time in seconds # (minimum time between two consecutive 'opposite' auto-scaling # operations - e.g. scale-out after scale-in) auto_scale_cooldown_time = 900 # Auto-scaling scale-in step # (number of media instances to be removed) auto_scale_in_step = 1 # Auto-scaling scale-out step # (number of media instances to be added) auto_scale_out_step = 1 # # Network configuration # # AWS region name # (use 'aws ec2 describe-regions' command to find all # available regions) aws_region = eu-central-1 # VPC where stack will be deployed vpc_id = vpc-45f3152c # SBC cluster requires the following subnets: # - cluster - used for internal communication between # cluster nodes # - OAM - used for management traffic # - signaling - used for carrying signaling (SIP) traffic # - media - used for carrying media (RTP) traffic # # Notes: # - OAM subnet may carry control / media traffic too if needed # - during normal cluster operation, only active Signaling # Component (SC) is accessed for management purposes Version Mediant CE

26 Stack Manager # (Web / CLI / SNMP / REST) # # It is perfectly fine to specify the same value for all below # subnet_ids except for cluster_subnet_id. cluster_subnet_id = subnet-be6e8bc3 oam_subnet_id = subnet-1536d368 signaling1_subnet_id = signaling2_subnet_id = media1_subnet_id = media2_subnet_id = # Key Pair is used to provide secure access to the SBC cluster's # CLI interface via SSH protocol. It is mandatory for the AWS # environment even though SBC in its default configuration # supports SSH login using username/password. ssh_key_pair = aws_ssh_frankfurt_1 # # Signaling Component (SC) configuration # # 1+1 HA mode - enable / disable sc_ha_mode = enable # Signaling Components (SC) network interfaces are connected # as follows: # - eth0: cluster # - eth1: oam # - eth2: signaling1 # - eth3: signaling2 # # At least two network interfaces are required. # Notes: # - "eth1" may carry both OAM and SIGNALING traffic. # - Primary IP addresses are not used except for "eth0" (cluster # interface). Secondary IP addresses are used instead and # 'float' across the two SC instances (in HA configuration). # Number of network interfaces - valid values: 2, 3, 4 sc_num_of_interfaces = 2 # Comma-separated list of network interfaces will be assigned # with Public IP addresses (Elastic IPs). # For example: "eth1,eth3" # Notes: # - Public IPs cannot be assigned to "eth0" because it's used # for internal cluster management. # - Public IPs cannot be assigned to "additional" IP addresses. # - If you want to access SBC management interface from outside User's Manual 26 Document #: LTRT-28905

27 User's Manual 3. CLI Interface # the VPC, assign Public IP to "eth1" interface. # - If you do not need Public IPs, leave this field blank sc_public_ips = eth1 # Comma-separated list of network interface names and number of # corresponding additional IP addresses. # For example: "eth1:2" means "two additional IP addresses # on eth1" sc_additional_ips = # AWS instance type # (recommended type is r4.2xlarge) sc_instance_type = r4.2xlarge # AWS image id sc_image_id = ami-9a50cff5 # SC disk size (in GB) sc_disk_size = 100 # AWS IAM role that allows SC components to automatically # configure network interfaces and perform activity switchover sc_iam_role = SBC-HA-3 # URL of initial SBC cluster configuration file # For example: " # If you don't have such URL, leave value blank sc_ini_file_url = # Configuration file contains Admin user - true / false # (change this to "false" if your configuration file doesn't # contain WebUsers table and you want the Stack Manager to # automatically create default Admin user). sc_ini_file_contains_admin_user = true # # Media Component (MC) configuration # # Media Components (MC) network interfaces are connected # as follows: # - eth0: cluster # - eth1: oam # - eth2: media1 # - eth3: media2 # # At least two network interfaces are required. # Primary IP addresses are available on all interfaces. # Number of network interfaces - valid values: 2, 3, 4 Version Mediant CE

28 Stack Manager mc_num_of_interfaces = 2 # Comma-separated list of network interfaces that will be assigned # with Public IP addresses (Elastic IPs) # For example: "eth1,eth3" # Notes: # - Public IPs cannot be assigned to "eth0" because it's used # for internal cluster management # - Public IPs cannot be assigned to "additional" IP addresses mc_public_ips = eth1 # Comma-separated list of network interface names and number of # corresponding additional IP addresses # For example: "eth1:2" means "two additional IP addresses # on eth1" mc_additional_ips = # AWS instance type # Recommended types are: # - r4.large for media forwarding # - c4.4xlarge for transcoding mc_instance_type = r4.large # AWS image id mc_image_id = ami-9a50cff5 # Media component profile - forwarding / transcoding mc_profile = forwarding # Media component max rate limit (in kpps) # In addition to numeric values the following special string # values are supported: # - "auto" means that PPS limit is automatically calculated # based on instance type # - "unlimited" means that no limit is imposed mc_max_pps_limit = auto # # Additional configuration # # Prefix to be added to all created components # (note that there is also global stack_mgr configuration # parameter with a similar name, but this one overrides it if # set to non-empty value) name_prefix = # Manage SBC cluster via HTTPS or HTTP protocol - valid values: # enable / disable # (change this to Disable if, for example, your firewall User's Manual 28 Document #: LTRT-28905

29 User's Manual 3. CLI Interface # intercepts HTTPS connections and blocks them due to self-signed # certificate being used) manage_via_https = enable 3.8 list stacks The list command lists available stacks. $ stack_mgr list name type vim state stack1 sbc-cluster aws idle stack2 sbc-cluster aws scaling-out show stack The show command shows detailed information about specific stacks. You must specify a valid stack name. $ stack_mgr show --help usage: stack_mgr show [-h] name positional arguments: name name of the stack optional arguments: -h, --help show this help message and exit --no-status do not show real-time status --idle-mcs show 'idle' media components $ stack_mgr show stack1 Name Type VIM State : stack1 : sbc-cluster : aws : idle Created at : May 09, :55:29 Region VPC : eu-central-1 : vpc-45f3152c Signaling Components Instance type : r4.2xlarge Image ID : ami-d771563c Version Mediant CE

30 Stack Manager Disk size : 100 GB id IP address status type sc running r4.2xlarge sc-2 running r4.2xlarge Network configuration: interface subnet id status eth0 cluster subnet-be6e8bc3 in-use eth1 oam subnet-1536d368 in-use eth2 signaling1 eth3 signaling SC number of network interfaces : 2 SC interfaces with public IPs : eth1 SC interfaces with additional IPs : Media Components Instance type : r4.large Image ID : ami-d771563c Profile : forwarding Max rate limit : auto id IP address status %media %dsp type mc connected 0 - r4.large mc connected 0 - r4.large Number of media components : 2 Connected media components : 2 Free media resources : 200% Free DSP resources : - Network configuration: interface subnet id status eth0 cluster subnet-be6e8bc3 in-use eth1 oam subnet-1536d368 in-use eth2 media1 User's Manual 30 Document #: LTRT-28905

31 User's Manual 3. CLI Interface eth3 media MC number of network interfaces : 2 MC interfaces with public IPs : eth1 MC interfaces with additional IPs : Min number of media components : 2 Max number of media components : 10 Automatic scaling : enable Media utilization scale in threshold : 250% Media utilization scale out threshold : 100% DSP utilization scale in threshold : 0 (disabled) DSP utilization scale out threshold : 0 (disabled) Automatic scaling cool down time : 900 sec Automatic scaling scale-out step : 1 Automatic scaling scale-in step : 1 Management IP address : Use HTTPS for cluster management : enable Unless --no-status argument is specified, Stack Manager collects the following additional information: For signaling components: runtime status running/stopped using AWS API active instance that currently holds public IP via AWS API For media components: runtime status running/stopped using AWS API connectivity status connected/disconnected using SBC REST API media and DSP utilization using SBC REST API If --no-status argument is specified or the Stack Manager fails to communicate with the SBC cluster, it will display an internal state of the component instead. Version Mediant CE

32 Stack Manager 3.10 Stack Deployment Details This chapter describes the methods that Stack Manager uses to deploy stacks in different virtualization environments. Understanding these details allows you to monitor stack behavior using virtualization environment s management interfaces e.g., AWS dashboard and to troubleshoot various abnormal scenarios. It is also needed to alter some stack configuration, as described in Section Stack Deployment in AWS Environment Stack Manager uses multiple Cloud Formation templates to deploy stacks in the AWS environment. This simplifies deployment of multiple stack components and provides tracking for all AWS resources that correspond to the specific stack. For each Mediant CE stack instance, the following Cloud Formation templates are created: <stack_name>-network creates security groups and OAM interface of signaling components <stack_name>-sc creates signaling component instance(s) <stack_name>-mc-n creates media component instance mc-n (where N is 1, 2, etc.) Figure 3-1: Create Stack Once all components are created, Stack Manager manages their state and specifically state of media components by stopping/starting corresponding instances. Instances that correspond to active media components are started and are expected to be in the running state. Instances that correspond to the idle media components are stopped and are expected to be in the stopped state. Stack Manager implements the update command by changing the corresponding Cloud Formation s template and issuing update to the specific Cloud Formation stack. User's Manual 32 Document #: LTRT-28905

33 User's Manual 3. CLI Interface Adjusting Configuration of Security Groups Stack Manager creates the following Security Groups as part of <stack_name>-network Cloud Formation template: clustersecuritygroup Defines rules for internal communication between Mediant CE components; applied to the interfaces in Cluster Subnet oamsecuritygroup Defines rules for the management (OAM) traffic; applied to the interfaces in OAM Subnet mcsecuritygroup Defines rules for signaling and media traffic; applied to the interfaces in OAM, Signaling and Media Subnets All security groups contain default set of rules needed for normal Mediant CE operation. However, you may need to adjust these rules for example to allow signaling traffic on additional interfaces (besides default ports 5060 and 5061) or to limit management traffic to specific machines / subnets. To adjust Security Groups rules: 1. Locate the security group in the AWS VPC dashboard. 2. Adjust inbound/outbound rules as per your needs Using Pre-Defined Elastic IPs Stack Manager assigns Elastic IPs to signaling and media components based on the sc_public_ips and mc_public_ips configuration parameters as described in Section 3.7. By default, it creates new Elastic IP addresses and assigns them to the instances. If you wish to use pre-defined Elastic IP addresses instead, you must add the following parameters to the stack configuration file: public_ip_<component name>_<interface name> = <EIP Allocation ID> where: <component name> is name of the component to which you want to assign predefined Elastic IP; valid component names are sc-1, mc-1, mc-2, etc. <interface name> is name of the network interface to which you want to assign predefined Elastic IP; valid interface names are eth1, eth2 and eth3 <EIP Allocation ID> is allocation ID of pre-defined Elastic IP For example: public_ip_sc-1_eth1 = eipalloc-461b3468 public_ip_mc-1_eth1 = eipalloc public_ip_mc-2_eth1 = eipalloc-f51f1edb Stack Manager will use pre-defined Elastic IPs for all user-defined components/interfaces as per the above configuration and will allocate new Elastic IPs for all the rest. Version Mediant CE

34 Stack Manager Using Pre-Defined Private IPs Stack Manager assigns Private IPs to signaling and media components based on the sc_num_of_interfaces, sc_additional_ips, mc_num_of_interfaces and mc_public_ips configuration parameters as described in Section 3.7. By default, IP addresses are automatically allocated from the corresponding subnets. If you wish to manually specify private IP addresses instead, you may add the following parameters to the stack configuration file: private_ip_<component name>_<interface name> = <private IPs> where: <component name> is name of the component to which you want to assign predefined Elastic IP; valid component names are sc-1, sc-2, mc-1, mc-2, etc. <interface name> is name of the network interface to which you want to assign predefined Elastic IP; valid interface names are eth0, eth1, eth2 and eth3 <private IPs> is comma-separated list of private IP addresses; first address is primary address; additional addresses are secondary addresses Follow these rules when specifying private IP addresses: For sc-1 : eth0 must have two IP addresses Other interfaces must have two IP addresses plus additional IP addresses, as specified by sc_additional_ips For sc-2 : All interfaces must have one IP address For mc-1, mc-2 etc.: eth0 must have one IP address Other interfaces must have one IP addresses plus additional IP addresses, as specified by sc_additional_ips The private_ip_... configuration parameter configures all private IP addresses on the specific interface of the specific instance. It s impossible to configure some IP addresses of the network interface manually and allocate others automatically. For example: private_ip_sc-1_eth0 = , private_ip_sc-1_eth1 = , private_ip_sc-1_eth2 = , private_ip_sc-2_eth0 = private_ip_sc-2_eth1 = private_ip_sc-2_eth2 = private_ip_mc-1_eth0 = private_ip_mc-1_eth1 = private_ip_mc-1_eth2 = private_ip_mc-2_eth0 = private_ip_mc-2_eth1 = private_ip_mc-2_eth2 = User's Manual 34 Document #: LTRT-28905

35 User's Manual 3. CLI Interface 3.11 Cluster Scaling The size of the cluster, and specifically the number of media components, may vary to match the required service capacity. This ensures that the cluster utilizes optimal amount of resources at any point of time and elastically scales on demand. The scaling decision may be triggered either manually by executing scale-in or scale-out commands or automatically based on the current cluster utilization. The size of the cluster is controlled by the following two configuration parameters: Minimum Number of Media Components Maximum Number of Media Components To ensure the fast scaling, Stack Manager pre-creates all needed media components in advance (up to the maximum number) and stops/starts them accordingly during scale in/out operations. The number and detailed status of media components reported by the show command corresponds to the active (running) media components. Idle (stopped) media components may be viewed by adding the --idle-mcs argument to the show command or using the virtual environment (e.g., AWS EC2) dashboard corresponding instances are in the stopped state. $ stack_mgr show stack1 --idle-mcs Media Components Instance type : r4.large Image ID : ami-d771563c Profile : forwarding Max rate limit : auto id IP address status %media %dsp type mc connected 0 - r4.large mc connected 0 - r4.large mc down - - r4.large mc down - - r4.large mc down - - r4.large Number of media components : 2 Connected media components : 2 Free media resources : 200% Free DSP resources : -... Version Mediant CE

36 Stack Manager scale-out stack The scale-out command increases the number of media components in the stack by starting additional pre-created idle media components (corresponding to the AWS EC2 instance state changes from stopped to running). You must specify a valid stack name and may optionally specify a number of media components to be added to the service. If the number of media components is not specified, one media component will be added. $ stack_mgr scale-out --help usage: stack_mgr scale-out [-h] [-n num] name positional arguments: name of the stack optional arguments: -h, --help show this help message and exit -n num, --num number of media components to be added The scale-out command is allowed only in idle state. For example, if you initiated the scale-in command, you must wait for it to complete prior to initiating the scale-out command. The scale-out command is not allowed when Automatic Scaling is enabled. $ stack_mgr scale-out stack1 The following media components will be brought into service: mc-3 Checking that configuration is allowed... done Initializing AWS client... done Starting components 'mc-3'... done Successfully started 'mc-3' Adding media components 'mc-3' to SBC configuration... done Waiting until media components are ready... done scale-in stack The scale-in command decreases the number of media components in the stack by stopping certain amount of active media components (corresponding to the AWS EC2 instance state changes from running to stopped). You must specify the valid stack name and may optionally specify one of the following: number of media components to be removed from the service names of specific media components to be removed from the service If neither of the above parameters is specified, one media component will be removed. If you do not specify media component names, Stack Manager automatically chooses removal media components with the lowest media utilization. $ stack_mgr scale-in --help usage: stack_mgr scale-in [-h] [-n num] [-i ids] name positional arguments: name name of the stack User's Manual 36 Document #: LTRT-28905

37 User's Manual 3. CLI Interface optional arguments: -h, --help show this help message and exit -n num, --num num number of media components to be removed -i ids, --ids ids comma-separated list of media component ids to be removed, e.g. mc-3,mc-4 The scale-in command is allowed only in 'idle' state. For example, if you initiated the scaleout command you must wait for it to complete prior to initiating the scale-in command. The scale-in command is not allowed when Automatic Scaling is enabled. $ stack_mgr scale-in stack1 Choosing media components to be taken out of service... done The following media components will be taken out of service: mc-3 Checking that configuration is allowed... done Initializing AWS client... done Removing media components 'mc-3' from SBC configuration Locking media component 'mc-3'... done Removing media components 'mc-3'... done Stopping components 'mc-3'... done scale stack The scale command sets the number of media components in the stack to the specified value. It performs scale-in or scale-out command, depending on the current number of media components available in the cluster. You must specify the valid stack name and a number of active media components in the cluster. $ stack_mgr scale --help usage: stack_mgr scale [-h] [-n num] name positional arguments: name name of the stack optional arguments: -h, --help show this help message and exit -n num, --num num number of media components The scale command is allowed only in 'idle' state. For example, if you initiated the scale-out command you must wait for it to complete prior to initiating the scale command. Contrary to scale-in and scale-out commands, the scale command is allowed when Automatic Scaling is enabled. Regardless of whether it adds or removes media components, for the purposes of calculating a cool down period, the scaling operation is considered to be a result of the scale-out command. This means that cluster size may be increased immediately after completing the scale command if needed. $ stack_mgr scale stack1 -n 3 The following media components will be brought into service: mc-3 Checking that configuration is allowed... done Initializing AWS client... done Starting components 'mc-3'... done Successfully started 'mc-3' Version Mediant CE

38 Stack Manager Adding media components 'mc-3' to SBC configuration... done Waiting until media components are ready... done 3.12 Automatic Scaling Automatic Scaling adjusts cluster size to the current service needs by measuring current cluster utilization and changing its size accordingly. It is implemented via a background job that runs every minute. For every stack that is in 'idle' state and has Automatic Scaling enabled, Stack Manager calculates the total amount of 'free' media and DSP resources using accumulative percentage points, where 100% corresponds to the capacity of a single media component. For example, for a cluster that is in the following state: id IP address status %media %dsp mc connected 30 0 mc connected 40 0 mc connected free media resources are calculated as follows: free_media = (100-30) + (100-20) + (100-25) = 205 % Note: The calculated number describes the number of excessive media components capacity in the cluster. For example, 100% corresponds to the state where total amount of excessive capacity equals the capacity of a single media component. In this state, the failure of a single media component has no effect on traffic capacity thus providing N+1 redundancy for media cluster. The calculated number is then compared against scale-in and scale-out thresholds, that are defined in stack configuration. If the number is below the scale-out threshold, the scale-out operation is triggered. If the number is above the scale-in threshold, the scale-in operation is triggered. It is possible to disable media or DSP thresholds by setting them to 0 (zero). If both media and DSP thresholds are used, the decision is made as follows: scale-out is performed when either media or DSP utilization is below the threshold scale-in is performed when both media and DSP utilization are above the threshold media_util_scale_in_threshold = 250 media_util_scale_out_threshold = 100 dsp_util_scale_in_threshold = 0 dsp_util_scale_out_threshold = 0 Maximum / minimum cluster size is defined using max_mc_num and min_mc_num parameters and automatic scaling mechanism takes them into account when making its decisions. User's Manual 38 Document #: LTRT-28905