Purpose

This API returns the readiness status of the Cluster Manager VM.

Cluster Manager VM Readiness

If /mnt/iso/install.sh is executing, the status is returned as 'not ready'.

If /mnt/iso/install.sh has completed executing, status is returned as 'ready'.

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/status/cluman

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: GET

• Payload: JSON

• Response: 200 OK: success

  The following example shows the status reported for a new CPS deployment:

  {
      "status": "ready",
  }

API logs are at written to: /var/log/orchestration-api-server.log

Purpose

This API is used to load an initial configuration or return (GET) the current CPS cluster configuration.

This API is also used to apply the loaded configuration to all VMs within the CPS cluster.

API logs are at written to: /var/log/orchestration-api-server.log

Retrieve the Current Configuration

To retrieve (GET) the current CPS cluster configuration that is loaded on the CPS Cluster Manager:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: GET

• Payload: There is no payload.

• Response Codes: 200: OK.

  Example Response (No Configuration Present) XML:

  ---
  configVersion: null
  hosts: null
  vlans: null
  additionalHosts: null
  config: null
  licenses: null
  replicaSets: null

  For a response showing an example configuration file refer to Sample YAML Configuration File - HA Setup.

Load a Configuration

Note	This API can only be used once for initial deployment. Once a configuration has been applied (/system/config/action/apply) as described below, this API is no longer available.

Note	Before loading the configuration file to your CPS cluster, verify that the YAML file uses the proper syntax. There are many publicly-available websites which you can use to validate your YAML configuration file.

Note

When this API is issued, the following basic validations are performed on the consolidated configuration (YAML) file submitted in the payload: The replica set hosts are included in hosts or additionalHosts section Standard CPS aliases are present (lb01, lb02, and so on) Standard CPS vlan names are present (Internal, Management, and so on) Range checking (for example, IPv4/IPv6 IP address syntax validation) Cross-referencing of vlans with hosts If a validation error is detected, an appropriate message is provided in the API response, and reported in /var/log/orchestration-api-server.log.

To load a new CPS cluster configuration on the CPS Cluster Manager:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: POST

• Payload: Include the YAML configuration file in the POST. Refer to Sample YAML Configuration File - HA Setup for more information about this configuration file.

• Response: 200: success; 400: malformed or invalid; 403: Configuration may not be changed at this time (for example, after it has been applied).

To verify the configuration was properly loaded, perform another GET to http://<Cluster Manager IP>:8458/api/system/config/

Apply the Loaded Configuration

Note	This API can only be used once for initial deployment. After a configuration has been applied, the API is no longer available.

Once a new configuration file has been uploaded to the Cluster Manager VM, you must apply the configuration. This triggers the Cluster Manager VM prepare and push out the new configurations to all VMs in the cluster, as well as perform any post-update steps.

During an initial deployment of a CPS cluster, the CPS VMs in the cluster will remain in an inactive/waiting state until this configuration file is applied.

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/action/apply

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: POST

• Payload: There is no payload.

• Response: 200: success; 400: malformed or invalid; 403: Configuration may not be applied at this time; 500: System error. See logs.

To check the status of the CPS cluster after applying a configuration, refer to /api/system/config/status.

The following parameters can be defined in the CPS configuration file. For sample configuration file, refer to Sample YAML Configuration File - HA Setup section.

In this file, the Internal, Management and Gx networks must have an exact case match of "Internal", "Management" and " Gx" in the following sections:

• hosts: interfaces: value of "network"

• vlans: value of "name"

All parameters and values are case sensitive.

Note	Before loading the configuration file to your CPS cluster, verify that the YAML file uses the proper syntax. There are many publicly-available websites which you can use to validate your YAML configuration file.

ldap.redis.qserver.1=lb01:6379
policy.redis.qserver.2=lb01:6380
policy.redis.qserver.3=lb01:6381
ldap.redis.qserver.4=lb02:6379
policy.redis.qserver.5=lb02:6380
policy.redis.qserver.6=lb02:6381

LDAP SSSD

Note	For LDAP SSSD routable IP is required. LDAP server must be accessible from CPS VMs (LDAP client).

After migration from CPS 13.x.x or CPS 14.x.x to CPS 18.2.0 release, LDAP SSSD configuration is installed on default VM (pcrfclient/lb) and not on all VMs. You need to configure LDAP SSSD on all the other VMs.

Once LDAP SSSD configuration is complete, you need to authenticate the LDAP certificate. For more information, refer to LDAP SSSD Configuration section in CPS Installation Guide for VMware.

If you are migrating from a lower version such as CPS 13.x.x to CPS 18.x.x and you do not want the LDAP SSSD, modify the LDAP parameters as follows in YAML file:

ldapOnAll=false
ldapEnabled=false

After the modification, run import_deploy.sh so that LDAP SSSD is not installed by default

For more information about LDAP SSSD certificate authentication and troubleshooting, refer to LDAP SSSD Configuration section in CPS Installation Guide for VMware.

Use the following file as a template to create the YAML configuration file for your CPS deployment. Refer to Configuration Parameters - HA System section for a description of the available parameters.

Important

GuestNic must be populated as per network VLAN defined on ethenet interfaces in VMs.

Note	RADIUS-based policy control is no longer supported in CPS 14.0.0 and later releases as 3GPP Gx Diameter interface has become the industry-standard policy control interface.

#
#  CPS system configuration
#
#  CPS configuration is a YAML file with all the configuration required
#  to bring up a new installation of CPS.
#
#  This example file lists all possible configuration fields.
#  Fields that are not marked as required can be left out of
#  the configuration. Fields that are not provided will use
#  the default value. If not default is indicated the default
#  is an empty string.p

# The version of the configuration file. The installation documentation
# for the version of the CPS you are installing will indicate which
# configuration version you must use.
# REQUIRED
configVersion: 1.0

# Configuration section for CPS hosts
# REQUIRED
hosts:
  # The host section must specify all hosts that are members of the CPS
  # deployment. Host entries consist of the following REQUIRED fields
  #  name: the string to be used as a hostname for the VM
  #  alias: the string to be used in hostname lookup for the VM
  #  interfaces: Network details consisting of the following REQUIRED fields
  #    network: The network name which must match a VLAN name (see below)
  #    ipAddress: The interface address
  - name: "lb01"
    alias: "lb01"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.201"
      - network: "Management"
        ipAddress: "172.18.11.154"
      - network: "Gx"
        ipAddress: "192.168.2.201"
  - name: "lb02"
    alias: "lb02"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.202"
      - network: "Management"
        ipAddress: "172.18.11.155"
      - network: "Gx"
        ipAddress: "192.168.2.202"
  - name: "sessionmgr01"
    alias: "sessionmgr01"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.22"
      - network: "Management"
        ipAddress: "172.18.11.157"
  - name: "sessionmgr02"
    alias: "sessionmgr02"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.23"
      - network: "Management"
        ipAddress: "172.18.11.158"
  - name: "qns01"
    alias: "qns01"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.24"
  - name: "qns02"
    alias: "qns02"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.25"
  - name: "qns03"
    alias: "qns03"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.26"
  - name: "qns04"
    alias: "qns04"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.27"
  - name: "pcrfclient01"
    alias: "pcrfclient01"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.20"
      - network: "Management"
        ipAddress: "172.18.11.152"
  - name: "pcrfclient02"
    alias: "pcrfclient02"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.21"
      - network: "Management"
        ipAddress: "172.18.11.153"

# Configuration section for CPS VLANs
# REQUIRED
vlans:
  # VLAN entries consist of the following REQUIRED fields
  #  name: The VLAN name. This name must be used in the "network" field
  #        host interfaces (see above)
  #  vipAlias: Hostname associated with the vip
  #  vip: Virtual IP used no this network, if any.
  #  guestNic: The name of the interface specified in the host cloud config
  #            or the Heat definition.
  #
  - name: "Internal"
    vipAlias: "lbvip02"
    vip: "172.16.2.200"
    guestNic: "eth0"
  - name: "Management"
    vipAlias: "lbvip01"
    vip: "172.18.11.156"
    
  - name: "Gx"
    vipAlias: "gxvip"
    vip: "192.168.2.200"
     
# Configuration section for hosts not configured in the hosts section above.
# REQUIRED
additionalHosts:
  # additionalHosts entries consist of the following REQUIRED fields
  #  name: The hostname
  #  alias: The string to be used in the etc/host file.
  #  ipAddress: The IP address to use in the etc/host file.
  #
  # the "arbitervip" to the pcrfclient01 internal ip is mandatory.
  #
  - name: "lbvip01"
    ipAddress: "172.18.11.156"
    alias: "lbvip01"
  - name: "lbvip02"
    ipAddress: "172.16.2.200"
    alias: "lbvip02"
  - name: "diam-int1-vip"
    ipAddress: "192.168.2.200"
    alias: "gxvip"
  - name: "arbitervip"
    ipAddress: "172.16.2.20"
    alias: "arbitervip"

# Configuration section for general configuration items.
# REQUIRED
config:
  # Do not change. See install documentation for details.
  # default: sys_user_0
  qpsUser: "sys_user_0"

  # Do not change. See install documentation for details.
  # default: disabled
  selinuxState: "disabled"

  # REQUIRED
  serviceLogTmpfsEnabled: "true"
  

  # REQUIRED
  lbProcMonList:
   - "whisper" 
  pcrfProcMonList:
   - "corosync"
   - "whisper"

# default: 1
  # Valid option:
  # 1 or undefined or less than 16 GB RAM on VM => QNS process is run   
  # by Zulu on QNS VMs
  # 2 => QNS process is run by Zing on QNS VMs
  performanceMode: "1"


   # REQUIRED
   cpuPriority: "-20"
 
 # Do not change. See install documentation for details.
  # default: targeted
  selinuxType: "targeted"

  # See install documentation for details.
  # default: broadhop
  broadhopVar: "broadhop"

  # Set true to enable TACACS+ authentication.
  # default: FALSE
  tacacsEnabled: "FALSE"

  # The IP Address of the TACACS+ server
  tacacsServer: "127.0.0.1"

  # The password/secret of the TACACS+ server.
  tacacsSecret: "CPE1704TKS"

  # A set of SNMP Network Management Stations.
  # NMS can be specified as IP addresses or IP
  # addresses. Entries are space separated.
  # Hostnames must also be specified in Additional
  # Host configuration.
  # See install documentation for details.
  nmsManagers:

  # Low Memory alert threshold %.
  # default: 0.1 (10% free)
  freeMemPer: "0.1"

  # A space separated set of protocol:hostname:port
  # entries. UDP is the only supported protocol.
  # Example:
  # upd:corporate_syslog_ip:514 udp:corporate_syslog_ip2:514
  syslogManagers:

  # A comma separated set of port values.
  # This must match values in the syslog_managers_list.
  # default: 514
  syslogManagersPorts: "514"

  # Port value for the rsyslog proxy server to listen
  # for incoming connections
  # default: 6515
  logbackSyslogDaemonPort: "6515"

  # IP address value used in the
  # /etc/broadhop/controlcenter/logback.xml
  # on the pcrfclient.
  # default: lbvip02
  logbackSyslogDaemonAddr: "lbvip02"


  # High CPU alert threshold.
  # The system will alert whenever the usage is
  # higher than this value.
  # default: 80
  cpuUsageAlertThreshold: "80"

  # Clear High CPU Trap threshold.
  # The system will generate a clear trap when a
  # High CPU trap has been generated and the CPU
  # usage is lower than this value.
  # default: 40
  cpuUsageClearThreshold: "40"

  # The number of 5 sec intervals to wait between
  # checking the CPU usage.
  # default: 12 (60 seconds)
  cpuUsageTrapIntervalCycle: "12"

  # The SNMP trap community string.
  snmpTrapCommunity: "broadhop"

  #The SNMP read community string.
  snmpRoCommunity: "broadhop"

  #
  monQnsLb:

 # The memory alert threshold (0.1 is 10%)
  freeMemoryPerAlert: "0.1"

  # The memory clear threshold (0.3 is 30%)
  freeMemoryPerClear: "0.3"

  # 
  monitorReplicaTimeout: "540"

  # Enable SCTP
  # TRUE - feature enabled
  # FALSE - feature disabled
  sctpEnabled: "TRUE"


  # Enables or disables linux firewall on all VMs (IPtables).
  # default: disabled
  firewallState: "disabled"

  # enable SNMP V3.
  # If null, SNMP V3 is disabled.
  # To enabled add the following:
  #   v3User: The SNMP V3 user: REQUIRED
  #   engineId: hex value (ie, 0x0102030405060708):  REQUIRED
  #   authProto: SHA or MD5: REQUIRED
  #   authPass: at least 8 characters:  REQUIRED
  #   privProto: AES or DES: REQUIRED
  #   privPass: OPTIONAL
  snmpv3:
     null
  #  v3User: "cisco_snmpv3"
  #  engineId: "0x0102030405060708"
  #  authProto: "SHA"
  #  authPass: "cisco_12345"
  #  privProto: "AES"
  #  privPass: ""


  # Users
  # There are different categories of users specified for the CPS.
  # All users have the following fields:
  #
  #  name: The user name. REQUIRED
  #  password: The password for the user. REQUIRED
  #            The password will need to be either in cleartext or
  #            encrypted. Please refer to Install documentation for details.
  #  groups: The groups for the user. Groups are specified as a list
  #          of group names.

  # System Users
  # Note that there must be a system use named sys_user_0
  sysUsers:
    - name: "qns"
      password: "$6$z5yv/Hf98NkO6Ven$5uramn6hvapA1Zq2AA4pA9ieDpKF7e9ICa0lFhFKrSwtRe7rPUdlyJ0La.dAW/Ws3CMlW2Ckr5GLNRhJU4XkC."
      groups:
        - pwauth
     
    - name: "qns-svn"
      password: "$6$z5yv/Hf98NkO6Ven$5uramn6hvapA1Zq2AA4pA9ieDpKF7e9ICa0lFhFKrSwtRe7rPUdlyJ0La.dAW/Ws3CMlW2Ckr5GLNRhJU4XkC."
    - name: "qns-ro"
      password: "$6$z5yv/Hf98NkO6Ven$5uramn6hvapA1Zq2AA4pA9ieDpKF7e9ICa0lFhFKrSwtRe7rPUdlyJ0La.dAW/Ws3CMlW2Ckr5GLNRhJU4XkC."

  # Hypervisor Users
  hvUsers:
    - name: "root"
      password: "CpS!^246"

  # Other Users for the CPS
  # e.g. Control Center Users
  additionalUsers:
    - name: "admin"
      password: "qns123"
      groups:
        - qns

# Configuration section for feature licenses
# REQUIRED
licenses:
  # Licenses have the following required fields:
  # feature: The name of the feature license.
  # license: The license key for the feature.
  # - feature: "feature 1  Name"
  #   license: "license 1 key string"
   - feature: "MOBILE_CORE"
     license: "xxxxxxx"
   - feature: "RADIUS_AUTH"
     license: "xxxxxxx"

# Configuration section for mongo replica sets
# REQUIRED
replicaSets:
  #
  # Mongo replica sets have the following REQUIRED fields
  # <Mongo Set Identifier> : The database for which the replica
  #                          set is being created.
  #   setName: The name of the replica set
  #   oplogSize: Mongo Oplog size
  #   arbiters: The Arbiter hostnames and ports
  #   arbiterDataPath: The data directory on the arbiter VM
  #   members: List of members for the replica set. Each list element
  #            will be a session manager hostname:port
  #   dataPath: The data directory path on the session manager VMs
  - title: SESSION-SET1
    setName: set01
    oplogSize: 5120
    arbiters:
    - "pcrfclient01:27717"
    arbiterDataPath: "/var/data/sessions.1"
    members:
      - "sessionmgr01:27717"
      - "sessionmgr02:27717"
    dataPath: "/var/data/sessions.1/1"
- title: SESSION-SET2
    setName: set08
    oplogSize: 5120
    arbiters:
    - "pcrfclient01:37717"
    arbiterDataPath: "/var/data/sessions.1/2"
        members:
      - "sessionmgr01:37717"
      - "sessionmgr02:37717"
    dataPath: "/var/data/sessions.1/2"
    seeds: "sessionmgr01:sessionmgr02:37717"
  - title: BALANCE-SET1
    setName: set02
    oplogSize: 5120
    arbiters: 
      - "pcrfclient01:27718"
    arbiterDataPath: "/var/data/sessions.2"
    members:
      - "sessionmgr01:27718"
      - "sessionmgr02:27718"
    dataPath: "/var/data/sessions.2"
  - title: REPORTING-SET1
    setName: set03
    oplogSize: 5120
    arbiters:
     - "pcrfclient01:27719"
    arbiterDataPath: "/var/data/sessions.3"
    members:
      - "sessionmgr01:27719"
      - "sessionmgr02:27719"
    dataPath: "/var/data/sessions.3"
  - title: SPR-SET1
    setName: set04
    oplogSize: 3072
    arbiters: 
    - "pcrfclient01:27720"
    arbiterDataPath: "/var/data/sessions.4"
    members:
      - "sessionmgr01:27720"
      - "sessionmgr02:27720"
    dataPath: /var/data/sessions.4
  - title: AUDIT-SET1
    setName: set05
    oplogSize: 3072
    arbiters: 
    - "pcrfclient01:27725
    arbiterDataPath: "/var/data/sessions.5"
    members:
      - "sessionmgr01:27725"
      - "sessionmgr02:27725"
    dataPath: "/var/data/sessions.5"
  - title: ADMIN-SET1
    setName: set06
    oplogSize: 3072
    arbiters:
    - "pcrfclient01:27721"
    arbiterDataPath: "/var/data/sessions.6"
    members:
      - "sessionmgr01:27721"
      - "sessionmgr02:27721"
    dataPath: "/var/data/sessions.6"
  - title: ADMIN-SET2
    setName: set07
    oplogSize: 3072
    arbiters:
    - "pcrfclient01:27731"
    arbiterDataPath: "/var/data/sessions.7"
    members:
      - "sessionmgr01:27731"
      - "sessionmgr02:27731"
    dataPath: "/var/data/sessions.7"

# Configuration section for LDAP/SSSD
			ldapEnabled: “true”
			ldapOnAll:true
			ldapServer: "ldaps://<serverip>:10648"
			ldapSearchBase: "ou=users,dc=cisco,dc=com"
			ldapDefaultBindDn: "uid=admin,ou=system"
			ldapSecret: “secret”
			ldapDefaultUser: “admin”
			ldapOuUser: “users”
			ldapOuGroup: “groups”
			ldapDefaultGroup: “Admin”
			ldapDefaultGroupEditor: “User”
			ldapDcName: "dc=cisco,dc=com"

# Configuration section for DSCP configuration
# OPTIONAL
dscpconfig:
  #
  # dscpconfig have the following fields	
  # vmRole - VM type i.e lb/pcrfclient/qns/sessionmgr/udc
  # ipFamily - ipv4 or ipv6 and if empty then ipv4 & ipv6
  # outInterface - interface name i.e eth0/eth1, if empty then apply to any interfaces
  # protocol - tcp/udp/etc.., if empty then apply to any protocol
  # destIp - Specify Destination IP
  # destPort - Specify Destination Port
  # sourcePort - Specify Source Port
  # dscpClass	 - Specify DSCP class or value
  # dscpValue - Specify DSCP class or value
   - vmRole: "lb"
     protocol: "tcp"
     outInterface: "eth1"
     destPort: "27717"
     dscpClass: "af11"
   - role: "lb"
     protocol: "udp"
     destIp: "1.1.1.1"
     destPort: "27717"
     dscpClass: "af12"

# Configuration section for Critical File Monitor configuration
#
# CriticalFilesConfig have the following fields	
# FileToBeMonitored: Absolute path of file which needs to monitor.
# ActionToBeMonitored: Action for which file needs to monitor. Supported options are wxa ( w –write, x - execute and a – attribute changes).
---
critFileMonConfig:
---
- fileToBeMonitored: "/etc/hosts"
  actionToBeMonitored: "wxa"
- fileToBeMonitored: "/etc/shadow"
  actionToBeMonitored: "xa"
- fileToBeMonitored: "/etc/passwd"
  actionToBeMonitored: "xa"

Purpose

This API retrieves the status of individual install and deploy tasks run when a new or updated configuration is applied on the Cluster Manager VM.

This API can be called while the installation and deployment tasks are actively running.

The status reports:

• timestamp: timestamp in milliseconds.

• taskname: name of the individual task.

• status:

  • START: start of task.

  • INFO: general information about the task.

  • WARNING: error information about the task.

  • SUCCESS: task was successfully completed.

  • FAILURE: task failed and deployment failed.

• details: information about this task.

Retrieve Deployment Status

To retrieve the deployment status:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/status

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: GET

• Payload: There is no payload.

• Response Codes: 200 OK: success.

  Example Response:

  ---
  [
  {"timestamp":"1454367943000","taskName":"CPS Installation","status":"START","details":""},
  {"timestamp":"1454367943000","taskName":"Cluman Setup","status":"START","details":""},
  {"timestamp":"1454367943000","taskName":"Cluman Setup","status":"SUCCESS","details":"Wait for Puppet to complete"},
  {"timestamp":"1454367943000","taskName":"Post Install","status":"START","details":""},
  {"timestamp":"1454367943000","taskName":"SyncSvn","status":"START","details":""},
  {"timestamp":"1454367943000","taskName":"SyncSvn","status":"WARNING","details":"Failed to sync SVN."},
  {"timestamp":"1454367943000","taskName":"SyncSvn","status":"SUCCESS","details":""},
  {"timestamp":"1454367943000","taskName":"build_set","status":"START","details":"Building replica sets"},
  {"timestamp":"1454367943000","taskName":"build_set","status":"INFO","details":"Wrote mongo config"},
  {"timestamp":"1454367943000","taskName":"build_set","status":"INFO","details":"Syncing mongo config to other hosts"},
  {"timestamp":"1454367943000","taskName":"build_set","status":"SUCCESS","details":"Replica sets have been created successfully"},
  {"timestamp":"1454367943000","taskName":"SetPriority","status":"START","details":""},
  {"timestamp":"1454367943000","taskName":"SetPriority","status":"SUCCESS","details":""},
  {"timestamp":"1454367943000","taskName":"AddAdditionalUsers","status":"START","details":""},
  {"timestamp":"1454367943000","taskName":"AddAdditionalUsers","status":"SUCCESS","details":""},
  {"timestamp":"1454367943000","taskName":"Licenses","status":"START","details":""},
  {"timestamp":"1454367943000","taskName":"Licenses","status":"SUCCESS","details":""},
  {"timestamp":"1454367943000","taskName":"Post Install","status":"SUCCESS","details":""}
  ]

The deployment process is complete when the following response is received: "Post Install","status":"SUCCESS"

Note	The amount of time needed to complete the entire deployment process depends on the number of VMs being deployed, as well as the hardware on which it is being deployed. A typical deployment can take 45 minutes or more.

Startup status logs are written to: /var/log/startupStatus.log on the Cluster Manager VM.

API logs are written to: /var/log/orchestration-api-server.log

Refer to the /api/system/config/status to determine the readiness status of the CPS cluster.

Purpose

This API returns the readiness status of CPS cluster.

Cluster Readiness

This API returns the "readiness" status of the CPS cluster.

The cluster is deemed "ready" when Puppet has run to completion on all VMs and the Replica set creation is complete on the Session Manager VMs. The Orchestrator can use this API to check when the cluster is ready so that it can then invoke the Service Creation APIs.

This API reports an aggregate status of MongoDB replica sets, qns processes, and the cluster (Puppet) for all VMs.

This API will timeout after 150 seconds.

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/status/cps

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: GET

• Payload: JSON

• Response:

  The following example shows the readiness status for a CPS cluster:

  {
      "clusterStatus": "ready",
      "mongoStatus": "ready",
      "qnsStatus": "ready"
  }

  mongoStatus and clusterStatus can report "ready", "not ready", or "error". qnsStatus can report "ready" or "not ready". If mongoStatus reports an "error" status, the clusterStatus also reports an "error" status.

  If any database replica-sets are reporting "ok", but members are "off-line", mongoStatus reports "not ready".

  If any of the replica-sets are down or in an error state, mongoStatus reports "error".

• Error Codes:

  • 200 OK: success

  • 404: Unknown entity

  • 500: Script config not found

  • 500: CPS status job interrupted

  • 500: CPS status job timeout

  • 500: CPS status job termination interrupted

  • 500: Failed retrieval of CPS status job results

API logs are at written to: /var/log/orchestration-api-server.log

Purpose

This API is to used to determine the current state of the CPS system, and if necessary, override it in the event the reported state does not match the actual system state.

Many CPS orchestration APIs are accepted only when the CPS system is in a particular state. This API provides a method of overriding the reported API system state. It does not rectify or correct the underlying issue. For example setting the state to pre_deploy does not un-deploy the CPS deployment.

API logs are at written to: /var/log/orchestration-api-server.log

Retrieve the Current API State

To determine the current system state:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: GET

• Payload: There is no payload.

• Response Codes: 200: OK.

  Example Response:

  {
    "state": "pre_config"
  }

  This API can be used at any time.

The following states can be reported:

• pre_config: no configuration has been loaded onto the system (/api/system/config).

• pre_deploy: a configuration has been loaded, but not applied (api/system/config/action/apply).

• deploying: the system is in the process of being deployed.

• deployed: the system has finished the installation/deployment.

• upgrading: the system is in the process of being upgraded.

• busy: the system is currently processing an operation.

Override the Current API State

Caution

This API should only be used as directed by a Cisco representative. Improper use can cause irreparable harm to the CPS deployment.

To override the current system state:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: POST

• Payload: JSON payload with the new state specified as one of the following options: pre_config, pre_deploy, deploying, deployed, or upgrading.

  For example:

  {
    "state": "pre_config"
  }

• Response Codes: 400: Invalid state, please use: [pre_config, pre_deploy, deploying, deployed, upgrading]; 500: System error. See logs.

  Example Response:

  {
    "state": "pre_config"
  }

Purpose

The following APIs are used to mount and unmount an ISO image to the Cluster Manager VM, trigger an out-of-service upgrade of a CPS deployment, and view the status of the upgrade.

Note	Before invoking any of these APIs, refer to Upgrade API Prerequisites.

Logs are at written to: /var/log/orchestration-api-server.log on the Cluster Manager VM.

Unmount ISO

To unmount an existing CPS ISO image from /mnt/iso directory on the Cluster Manager:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/upgrade/action/unmount

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: POST

• Payload: There is no payload.

• Response Codes: 200 OK: success; 400: The mount parameters are invalid; 500: System Error. See logs.

Note	After invoking this API, it is recommended to detach the ISO image from the Cluster Manager VM using relevant command in OpenStack.

Mount ISO

Note

Before invoking this API: A new cinder volume must be created in OpenStack based on the CPS ISO, and then attached to the Cluster Manager VM using relevant command in OpenStack. Refer to Upgrade API Prerequisites for more details. Run the lsblk command on the Cluster Manager VM to check the device name before running mount API. This needs to be checked after the CPS ISO volume has been attached to the Cluster Manager VM.

To mount the CPS ISO image onto /mnt/iso directory on the Cluster Manager:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/upgrade/action/mount

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: POST

• Payload:

  {
  "deviceName": "<filename of the block device at which the cinder volume is attached" Ex: "/dev/vdb>"
  }

  /dev/vdb is for illustration only. Replace with the device name to which the CPS ISO volume is attached on your Cluster Manager VM.

  Example:

  {
   "deviceName": "/dev/vdb"
  }
  

• Response Codes: 200 OK: success; 400: The mount parameters are invalid; 500: System Error. See logs.

Upgrade CPS

Caution

This API must only be used during a planned maintenance window. This API does not perform an in-service software upgrade. CPS processes will be restarted during this process and traffic will be affected.

This API can only be used once the CPS has been deployed and is in a ready state. Prior to that time this API will not be available.

To upgrade CPS using the mounted ISO:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/upgrade/action/apply

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: POST

• Payload:

  type: Only "OUT_OF_SERVICE" is supported.

  config: The SVN/policy repository configuration to back up prior to upgrade. This repository will be backed up and restored during the upgrade.

  installType: The type of CPS deployment. Only mobile is supported.

  Example:

  {
  "config": "run",
  "installType": "mobile",
  "type": "OUT_OF_SERVICE"
  }

• Response Codes: 200 OK: success; 400: The input parameters are malformed or invalid.

The upgrade logs are at written to: /var/log/install_console_<date_time>.log on the Cluster Manager VM.

Note

If you want to upgrade from 18.2.0 release to 18.3.0 release using option 2 (offline) upgrade, you need to execute the following steps as option 2 upgrade fails for the first run: rm /var/tmp/upgrade_status and start monit manually using service monit start Re-run the upgrade API again. For subsequent option 2 upgrades, you do not need to execute the above mentioned workaround. If you do not want to use the above workaround, contact your Cisco Technical Representative.

Upgrade Status

To view the status of an upgrade:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/upgrade/status

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: GET

• Payload: There is no payload.

• Response Codes: 200 OK: success; 500: Script config not found

  Example Response:

  {
          "status": "In-Progress"
      }

  • Not-Started - No upgrade has been initiated

  • In-Progress - Upgrade is currently underway

  • Completed - Upgrade has completed

  • Error - There is a problem with the upgrade

This API is only valid after the operator has issued an upgrade.

Purpose

This API is used to retrieve the contents of /etc/broadhop/mongoConfig.cfg. This API is also used to add members to existing Mongo replica sets.

Important

This API does not support modifications to any other parameters within the Mongo configuration. It only add members to existing Mongo replica sets.

Important

While choosing mongo ports for replica-sets, consider the following: Port is not in use by any other application. To check it, login to VM on which replica-set is to be created and execute the following command: netstat -lnp | grep <port_no> If no process is using same port then port can be chosen for replica-set for binding. Port number used should be greater than 1024 and not in ephemeral port range i.e, not in between following range : net.ipv4.ip_local_port_range = 32768 to 61000

API logs are at written to: /var/log/orchestration-api-server.log

Workflow

1. Retrieve Current Mongo Configuration

2. Manually edit the YAML file retrieved in step 1 to add members to the existing replica sets.

3. Load Updated Configuration

4. Apply Loaded Configuration

Retrieve Current Mongo Configuration

To retrieve (GET) the current configuration:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/mongo/config

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: GET

• Payload: There is no payload.

• Response Codes: 200 OK: success; 400: The request is invalid; 500: Server Error

  • Example Response (YAML format): HA Setup

    ---
    - title: "SESSION-SET1"
      setName: "set01"
      oplogSize: "5120"
      arbiters:
      - "pcrfclient01:27717"
      arbiterDataPath: "/var/data/sessions.1"
      members:
      - "sessionmgr01:27717"
      - "sessionmgr02:27717"
      dataPath: "/var/data/sessions.1"
    - title: "BALANCE-SET1"
      setName: "set02"
      oplogSize: "5120"
      arbiters: 
      - "pcrfclient01:27718"
      arbiterDataPath: "/var/data/sessions.2"
      members:
      - "sessionmgr01:27718"
      - "sessionmgr02:27718"
      dataPath: "/var/data/sessions.2"
    - ...

  • Example Response (YAML format): GR Setup

    
    - title: "SESSION-SET1"
      setName: "set01"
      oplogSize: "1024"
      arbiters: 
      - "arbiter-site3:27717"
      arbiterDataPath: "/var/data/sessions.1"
      siteId: "SITE1"
      members:
        - sessionmgr02-site1:27717
        - sessionmgr01-site1:27717
      dataPath: /var/data/sessions.1/set1
      primaryMembersTag: "SITE1"
      secondaryMembersTag: "SITE2"
      shardCount: "4"
      hotStandBy: "false"
      seeds: "sessionmgr01:sessionmgr02:27717"

    OR

    
      - title: "SESSION-SET1"
        setName: "set01"
        oplogSize: "1024"
        arbiters: 
        - "arbiter-site3:27717"
        arbiterDataPath: "/var/data/sessions.1"
        primaryMembers:
          - "sessionmgr02-site1:27717"
          - "sessionmgr01-site1:27717"
        secondaryMembers:
          - "sessionmgr02-site2:27717"
          - "sessionmgr01-site2:27717"
        dataPath: "/var/data/sessions.1"
        hotStandBy: "false"
        shardCount: "4"
        seeds: "sessionmgr01:sessionmgr02:27717"
        primaryMembersTag: "SITE1"
        secondaryMembersTag: "SITE2"
        siteId: "SITE1"
    

Note	The response includes the complete Mongo configuration in YAML format.

Load Updated Configuration

Note	This API can only be used once CPS has been deployed and is in a ready state. Prior to that time this API is not available.

Use this API to load an updated Mongo configuration on the CPS Cluster Manager:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/mongo/config/

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: PUT

• Payload: Include the YAML configuration file in the PATCH request. The entire contents of the Mongo config must be included.

• Response Codes: 200 OK: success; 400: The request is invalid; 500: Server Error

  Example Response:

  The updated contents of /etc/broadhop/mongoConfig.cfg is returned in the response in YAML format.

  Note	After using this API to load the updated mongo configuration, you must apply the configuration. Refer to Apply Loaded Configuration.

Apply Loaded Configuration

Note	This API can only be used once the CPS has been deployed and is in a ready state. Prior to that time this API is not available.

Use this API to apply the updated Mongo configuration that you loaded using Load Updated Configuration:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/mongo/action/addMembers

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/json

• Method: POST

• Payload: There is no payload.

• Response Codes: 200 OK: success; 400: The request is invalid; 500: Server Error

  This API returns immediately and does not wait for the members to be added. Refer to the log file to check the status.

  Example Response:

  {
      "logfile": "/var/log/broadhop/scripts/orch_api_03122016_203220.log"
  }

Purpose

This API is used to retrieve the current list of deployed CPS hosts, and to add or remove Policy Server (QNS), SessionMgr, and Policy Director (Load Balancer) hosts to the CPS cluster. This enables an orchestrator to increase (scale up) or decrease (scale down) the session processing capacity of the CPS cluster.

Important

To scale up, you must create VMs using heat or nova boot commands. However, already existing stacks cannot be used to scale up using heat.

Note	Only Policy Server (QNS) and SessionMgr hosts can be scaled down. Policy Director (Load Balancer) hosts cannot be scaled down.

Retrieve Current List of Deployed Hosts

To retrieve (GET) the current list of hosts deployed in the CPS cluster:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/hosts

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: GET

• Payload: There is no payload.

• Response Codes: 200 OK: success; 400: The request is invalid; 500: Server Error

  Example Response (YAML format):

  ---
  - name: "lb01"
    alias: "lb01"
    interfaces:
    - network: "Internal"
      ipAddress: "172.16.2.201"
    - network: "Management"
      ipAddress: "172.18.11.154"
    - network: "Gx"
      ipAddress: "192.168.2.201"
  - ...

  Note	The example response shown above is abbreviated. The response includes the complete list of configured hosts.

Add New Policy Server (QNS), Session Manager, and Policy Director (Load Balancer) Hosts

This API adds additional Policy Server (QNS), SessionMgr, and/or Policy Director (Load Balancer) hosts to an existing deployment. The API uses the PATCH method, which adds new hosts without affecting the existing configured hosts.

Policy Server (QNS), SessionMgr, and/or Policy Director (Load Balancer) VMs must be added in pairs (for example, qns05, qns06 and sessionmgr03, sessionmgr04). Attempts to add odd numbers of VMs are rejected.

Before issuing this API, you must create the additional VMs using Heat or Nova boot commands. For example, to create two additional Policy Server VMs (qns05, qns06):

nova boot --config-drive true --user-data=qns05-cloud.cfg --image "base_vm" --flavor "qps" --nic
net-id="2544e49e-0fda-4437-b558-f834e73801bb,v4-fixed-ip=172.16.2.28" --availability-zone
"az-2:os8-compute-2.cisco.com" "qns05"

nova boot --config-drive true --user-data=qns06-cloud.cfg --image "base_vm" --flavor "qps" --nic
net-id="2544e49e-0fda-4437-b558-f834e73801bb,v4-fixed-ip=172.16.2.29" --availability-zone
"az-2:os8-compute-2.cisco.com" "qns06"

Note	To add SessionMgr VMs, refer to /api/system/config/replica-sets section in this document to configure additional replica sets on newly deployed Session Mgr VMs.

When this API call completes, the Cluster Manager configuration is updated and all new VMs are deployed asynchronously.

Note	The amount of time needed to complete the process depends on the number of VMs being deployed.

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/hosts

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: PATCH

• Payload: Include the YAML configuration file in the PATCH request. Use the op: add parameter to add a host. Only the new hosts should be defined in the YAML configuration file submitted in the API request.

  Sample Payload:

  ---
  - op: add
    name: “qns05"
    alias: “qns05"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.28"
  - op: add
    name: “qns06"
    alias: “qns06"
    interfaces:
      - network: "Internal"
        ipAddress: "172.16.2.29"
  

• Response Codes: 200 OK: success; 400: Invalid data; 500: System error

To verify the configuration was properly loaded, perform another GET to http://<Cluster Manager IP>:8458/api/system/config/hosts

After issuing this API, /api/system reports a "busy" state. Once the operation is complete, it reports a "deployed" state.

Additionally, the /api/system/config/status can be used to monitor the progress of individual steps of the operation.

Status logs are also written to: /var/log/startupStatus.log on the Cluster Manager VM.

API logs are written to: /var/log/orchestration-api-server.log on the Cluster Manager VM.

In case of any errors, check the API log file /var/log/orchestration-api-server.log and do the following:

• Verify if puppet on the new Policy Director (Load Balancer) VM is completed successfully.

• In case of diameter calls issue, verify if puppet on lb01/02 VMs is completed successfully and haproxy-diameter configuration is updated. Also, verify if Policy Builder configuration for the new LB VMs is properly updated.

• Verify if diagnistics.sh status is clean after Policy Builder update.

Remove Policy Server (QNS) and Session Manager Hosts

This API removes Policy Server (QNS) and/or SessionMgr hosts from an existing deployment.

Note	Only Policy Server (QNS) and SessionMgr hosts can be removed from an existing deployment. Policy Director (Load Balancer) hosts cannot be removed.

Caution

Before removing any SessionMgr hosts, you must remove the replica-sets configured on those hosts using the /api/system/config/replica-sets section in this document.

Policy Server (QNS) VMs and SessionMgr VMs must be removed in pairs (for example qns05, qns06 and sessionmgr03, sessionmgr04). Attempts to remove odd numbers of VMs are rejected.

This API removes the specified VMs from the Cluster Manager configuration only. After issuing this API, the orchestrator terminates the VMs in OpenStack.

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/hosts

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: PATCH

• Payload: Include the YAML configuration file in the PATCH request. Use the op: remove parameter to remove a host. Only the hosts which are to be removed should be defined in the YAML configuration file submitted in the API request.

  Important

  Using op: remove parameter, only the hosts configuration is removed and not the actual VMs. You need to use nova commands to remove the VMs. For more information on nova commands, refer to OpenStack commands.

  Sample Payload:

  ---
  - op: remove
    name: “qns05"
    alias: “qns05"
   - op: remove
    name: “qns06"
    alias: “qns06"

After issuing this API, /api/system reports a "busy" state. Once the operation is complete, it reports a "deployed" state.

Additionally, the /api/system/config/status can be used to monitor the progress of individual steps of the operation.

Status logs are also written to: /var/log/startupStatus.log on the Cluster Manager VM.

API logs are written to: /var/log/orchestration-api-server.log on the Cluster Manager VM.

Purpose

This API is used to retrieve the current list of replica-sets for the Session database, to add additional replica-sets, or remove replica-sets.

Retrieve Current Replica-sets

To retrieve (GET) the current list of replica-sets configured for the Session database:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/replica-sets

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: GET

• Payload: There is no payload.

• Response Codes: 200 OK: success; 400: The request is invalid; 500: Server Error

  Example Payload (YAML format): HA Setup

  ---
  - title: "SESSION-SET1"
    setName: "set01"
    oplogSize: "5120"
    arbiters:
    - "pcrfclient01:27717"
    arbiterDataPath: "/var/data/sessions.1"
    members:
    - "sessionmgr01:27717"
    - "sessionmgr02:27717"
    dataPath: "/var/data/sessions.1"
   - ...
  

  Example Payload (YAML format): GR Setup

  ---
   - title: "SESSION-SET1"
      setName: "set01"
      oplogSize: "1024"
      arbiters:
      - "arbiter-site3:27717"
      arbiterDataPath: "/var/data/sessions.1"
      siteId: "SITE1"
      members:
        - "sessionmgr02-site1:27717"
        - "sessionmgr01-site1:27717"
      dataPath: "/var/data/sessions.1/set1"
      primaryMembersTag: "SITE1"
      secondaryMembersTag: "SITE2"
      shardCount: "4"
      hotStandBy: "false"
      seeds: "sessionmgr01:sessionmgr02:27717"
  

  If the user has configured primaryMembersTag: and secondaryMembersTag: parameters, then only these parameters will be visible in case of API GET is called to fetch configuration details. There will be single tag specified for SPR/balance/session geo tagging. The value will be matched with any one of the parameters mentioned in qns.conf for geo site tagging.

  Note	The response includes the complete list of configured replica-sets.

  Important

  While choosing mongo ports for replica-sets, consider the following: The port must not be in use by any other application. To check the port number, login to VM on which replica-set is to be created and execute the following command: netstat -lnp | grep <port_no> If no process is using the port, then the port number can be chosen for replica-set for binding. The port number used should be greater than 1024 and not be in the ephemeral port range i.e, not in between following range: 32768 to 61000. While configuring mongo ports in a GR environment, there should be a difference of 100 ports between two respective sites. For example, consider there are two sites: Site1 and Site2. For Site1, if the port number used is 27717, then you can configure 27817 as the port number for Site2. This is helpful to identify a mongo member’s site. By looking at first three digits, one can decide where the mongo member belongs to. However, this is just a guideline. You should avoid having mongo ports of two different sites to close to each other (for exampl, 27717 on Site-1 and 27718 on Site2). Reason: The reason is that the build_set.sh script fails when you create shards on the site (for example, Site1). This is because the script calculates the highest port number in the mongoConfig on the site where you are creating shards. This creates clash between the replica-sets on both sites. Since the port number which it allocates might overlap with the port number of mongoConfig on other site (for example, Site2). This is the reason why there should be some gap in the port numbers allocated between both the sites.

Add Replica-sets

This API configures additional replica-sets on newly deployed SessionMgr VMs. This API uses the PATCH method, which adds replica-sets without affecting the existing configured replica-sets.

When this API call completes, the Cluster Manager configuration is updated and all new replica-sets are created asynchronously.

Note	The amount of time needed complete the process depends on the number of replica-sets being deployed.

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/replica-sets

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: PATCH

• Payload: Include the YAML configuration file in the PATCH request. Use the op: add parameter to add a replica-set. Only the new replica-sets should be defined in the YAML configuration file submitted in the API request.

  Sample Payload (YAML format): HA Setup

  ---
  - op: add
     title: SESSION
     arbiters: 
     - "pcrfclient01"
     instances: 2
     members:
      - "sessionmgr03"
      - "sessionmgr04"
  

  Sample Payload (YAML format): GR Setup

  ---
  - op: add
     title: SESSION
     arbiters:
     - "pcrfclient01"
     instances: 2
     members:
      - "sessionmgr03"
      - "sessionmgr04"
         -primaryMembersTag: “sitename”
         -secondaryMembersTag: “sitename”
  

• Response Codes: 200 OK: success; 400: Invalid data; 500: System error

To verify the configuration was properly loaded, perform another GET to http://<Cluster Manager IP>:8458/api/system/config/replica-sets

The status of this API call is reported in http://:<Cluster Manager IP>8458/api/system/config/status

Status logs are also written to: /var/log/startupStatus.log on the Cluster Manager VM.

API logs are written to: /var/log/orchestration-api-server.log on the Cluster Manager VM.

Remove Replica-sets

This API removes replica-sets from deployed SessionMgr VMs. This API uses the PATCH method.

This API must be issued before removing any Session Manager VMs during a scale down of the CPS Cluster using the /api/system/config/hosts API.

After issuing this API, the /api/system/config/status API can be used to monitor the removal of the ring-sets and the replica-sets. After the operation has completed, this API will return a SUCCESS status for the operation.

While the operation is ongoing, performing a GET with the /api/system/config/ API returns a BUSY status for the operation. No other API operations are allowed while the system is in this state.

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/replica-sets

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: PATCH

• Payload: Include the YAML configuration file in the PATCH request. Only the replica-sets which are to be removed should be defined in the YAML configuration file submitted in the API request.

  Sample Payload (YAML format):

  ---
  - op: remove
     title: SESSION
     setName: set01
     arbiters: 
     - "pcrfclient01"
     instances: 2
     members:
      - "sessionmgr03"
      - "sessionmgr04"
  

• Response Codes: 200 OK: success; 400: Invalid data; 500: System error

To verify the configuration was properly loaded, perform another GET to http://<Cluster Manager IP>:8458/api/system/config/replica-sets

The status of this API call is reported in http://:<Cluster Manager IP>8458/api/system/config/status

Status logs are also written to: /var/log/startupStatus.log on the Cluster Manager VM.

API logs are written to: /var/log/orchestration-api-server.log on the Cluster Manager VM.

Adding/Updating Shard Count

Use this API to create shards. This API also supports existing scaling session replica-set and adding shards to existing session replica-sets.

Shards must be created during installation after the qns restart process (post install step).

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/replica-sets/

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: PATCH

• Payload:

  Sample Payload (YAML format) for scaling new replica-set:

  Note	hotStandBy, shardCount and seeds are optional parameters.

  ---
  - op: "add"
    title: "SESSION"
    instances: "1"
    arbiters:
    - "pcrfclient01"
    members:
    - "sessionmgr01"
    - "sessionmgr02"
   hotStandBy: “true”
   shardCount: “4”
  seeds: “sessionmgr01:sessionmgr02”
  

  Sample Payload (YAML format) for modifying the replica-set configuration:

  Note	hotStandBy, shardCount and seeds are required parameters.

  ---
  - op: "modify-shards"
    setName: "set10"
    hotStandBy: "true"
    shardCount: "5"
    seeds: "sessionmgr01:sessionmgr02:27820"
  

• Response Codes: 200 OK: success; 400: The request is invalid; 500: Server Error

To verify the configuration was properly loaded, perform another GET to http://<Cluster Manager IP>:8458/api/system/config/replica-sets

Update Priority

Priorities can be set in descending order using PATCH request.

In HA environment, priorities can be set for all replica sets of a particular replica database like session, admin, and so on. Also, you can set a particular replica-set under specific replica database.

In GR environment, priorities can be set for particular site and all replica-sets of a particular replica database like session, SPR, and so on. Also, you can set a particular replica-set under specific replica database. siteId parameter is mandatory in GR scenario.

Note	It is required that replica-set are created before priority can be set. During installation, priority is added for all replica sets. In case a member is added using addMember API. it is required to execute set-priority API to set priority for given replica-set.

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/replica-sets

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: PATCH

• Payload: To change the priority of more than one database type you must include another block in the request.

  Example Payload (YAML format): HA Setup

  ---
  - op: "set-priority"
    title: "SESSION"
    setName: “set01”
  
  - op: "set-priority"
    title: "SPR"
  

  Example Payload (YAML format): GR Setup

  ---
   - op: "set-priority"
    title: "SESSION"
    siteId: "SITE1"
  

  Note	For HA, title parameter is mandatory. For GR, title and siteId are mandatory parameters. setName is optional parameter for both HA and GR deployments.

• Response Codes: 200 OK: success; 400: The request is invalid; 500: Server Error

Purpose

This API is used to copy the /etc/broadhop/mongoConfig.cfg file from one site to another. API can be called on local cluman which in turn calls the remote cluman and update its data. The parameter remoteClumanIp needs to be configured using /api/system/config/config. This is required before syncing operation can be started.

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/replica-sets/action/sync-mongo

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: POST

• Payload: There is no payload.

• Response Codes: 200 OK: success; 400: The request is invalid; 500: Server Error

Purpose

This API is used to retrieve or update the 'config' section of the CPS cluster configuration.

API logs are at written to: /var/log/orchestration-api-server.log

Retrieve Current Configuration

To retrieve (GET) the 'config' section of the configuration currently loaded on the CPS cluster:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/config

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: GET

• Payload: There is no payload.

• Response Codes: 200: OK.

  Example Response (YAML format):

  ---
  config:
    qpsUser: "sys_user_0”
    selinuxState: "disabled”
    selinuxType: "targeted”
    ...
    sysUsers:
       ...
    hvUsers:
       ...
    additionalUsers:
       ...
  

  Note	The example response shown above is abbreviated. The response will include the complete list of parameters from the 'config' section of the consolidated configuration.

Update Configuration

This API modifies the parameters within the 'config' section of the consolidated configuration on an existing deployment. This API uses the PATCH method, which enables you to modify specific parameters without needing to submit the entire configuration.

Note	Only new sysUsers and additionalUsers can be added. Modifying existing sysUsers and additionalUsers is not supported. Adding new or modifying existing hvUsers is not supported.

When this API call completes, the Cluster Manager configuration is updated and the new configuration is then pushed to all CPS VMs.

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/config

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: PATCH

• Payload: Include the YAML configuration file in the PATCH request. Only the modified parameters should be defined in the YAML file.

  For a list of parameters which can be defined in this file, refer to the parameters defined in the config, sysUsers, hvUsers, and additionalUsers sections listed in Configuration Parameters - HA System section.

  Sample Payload (YAML format):

  ---
    selinuxType: "permissive"
    firewallState: "enabled"
    selinuxState: "enabled"
    snmpv3:
      v3User: "cps-snmp"
      engineId: "4321"
      authPass: "snmp123"
      privPass: "snmp321"
    tacacsEnabled: "TRUE"
    firewallState: "enabled”
    additionalUsers:
      - name: orchuser
        password: CpS!^246
        groups:
         - qns
  
  

  Note	root user group is not authorized group for Control Center.

  To add new TACACS configuration to an existing CPS deployment, use the PATCH method:

  Sample Payload (YAML format):

  ---
  tacacsEnabled: "TRUE"
  tacacsServer: "127.0.0.1"
  tacacsSecret: "CPE1704TKS"
  
  

  Note	The PATCH method will re-run puppet on all the VMs.

  'config' section also supports the following "extra" TACACS parameters:

  Sample Payload (YAML format):

  tacacsService: "pcrflinuxlogin"
  tacacsProtocol: "ssh"
  tacacsTimeout: "5"
  tacacsDebug: "0"
  
  

• Response Codes: 200 OK: success; 400: Invalid data; 500: System error

To verify the configuration was properly loaded, perform another GET to http://<Cluster Manager IP>:8458/api/system/config/config

The status of this API call is reported in http://:<Cluster Manager IP>8458/api/system/config/status

Status logs are also written to: /var/log/startupStatus.log on the Cluster Manager VM.

API logs are written to: /var/log/orchestration-api-server.log on the Cluster Manager VM.

Purpose

This API enables you to configure new peer nodes such as PCEF, NTP, NMS, and so on, by modifying the /etc/hosts files on all CPS VMs.

The API logs are written in the /var/log/orchestration-api-server.log and /var/log/startupStatus.log files.

Note	This API does not add a CPS VM to the CPS cluster.

Retrieve AdditionalHosts Configuration

To retrieve (GET) the AdditionalHosts configuration from the CPS Cluster Manager VM:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/additional-hosts

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: GET

• Payload: There is no payload

• Response Codes: 200 OK: success

  Example Response (YAML format):

  ---
   - name: "Host1 name"
     alias: "Host1 internal name"
     ipAddress: "Host1 IP address"
   - name: "Host2 name"
     alias: "Host2 internal name"
     ipAddress: "Host2 IP address"
   - name: "Host3 name"
     alias: "Host3 internal name"
     ipAddress: "Host3 IP address"
  

Add or Update AdditionalHosts Entry

This API adds or updates a new AdditionalHosts entry in the configuration file.

When this API call completes, the Cluster Manager is configured with the new /etc/hosts file. All the other deployed VMs are then updated asynchronously and the status is reported in http://:<Cluster Manager IP>8458/api/system/config/status.

To add or update an AdditionalHosts configuration:

• Endpoint and Resource: http://<Cluster Manager IP>:8458/api/system/config/additional-hosts

  Note	If HTTPS is enabled, the Endpoint and Resource URL changes from HTTP to HTTPS. For more information, see HTTPS Support for Orchestration API.

• Header: Content-Type: application/yaml

• Method: PUT

• Payload: Include the YAML configuration file in the PUT request.

  Sample Payload (YAML format):

  ---
   - name: "Host name"
     alias: "Host internal name"
     ipAddress: "Host IP address"
   - name: "NewHost name"
     alias: "NewHost internal name"
     ipAddress: "NewHost IP address"

  Important

  To add or update AdditionalHosts, update new payload with existing additional hosts information along with new or updated additional hosts. This request replaces all the additional hosts with new additional hosts information. To modify or delete AdditionalHosts, update new payload with modified or deleted additional hosts and perform PUT request. This request replaces additional hosts information in the /etc/hosts file of both Cluster Manager and CPS VMs. To verify that the AdditionalHosts configuration is properly loaded, perform another GET request to http://<Cluster ManagerIP>:8458/api/system/config/additional-hosts.

• Response Codes: 200 OK: success; 400: malformed or invalid; 500: system error