Configuration of 5G CUPS

The GigaVUE-FM CUPS solution collects the User Intent Definition in YAML format and automatically creates and manages the components like GigaSMART Groups, GSOPS, VPorts, First Level Maps. Second Level Maps, SFFP Profile, etc.

The CUPS policies and the site information are provided in YAML format. The policies are configured in GigaVUE-FM through Ansible Play book. The updates to the configurations are made in the YAML files.

The CUPS solution can be created, edited or deleted using Ansible. GigaVUE-FM allows you to monitor and troubleshoot the solution.

The following diagram shows the configuration of CUPS solution:

Refer to the following sections for configuring the 5G CUPS solution:

Pre-requisites

Ensure that the following environment is available before installation:

Rules and Notes

Installation and Environmental Setup for CUPS in Ansible:

1. Download the .deb/.rpm package from the customer portal.
2. Install the .deb/.rpm package to install Gigamon’s ansible module under /usr/local/share/gigamon. The package contains README (common Readme file) and README_CUPS/ directory. The README_CUPS/ directory contains one more README, specific to CUPS solution, and reference files.
3. Source the /usr/local/share/gigamon/setup-gigamon file to update the PYTHONPATH envirnoment. Also, export ANSIBLE_FM_IP in case if you are managing single FM. For multiple FM, this envirnonment variable is not required.
4. The ansible.cfg setting is available in usr/local/share/gigamon/ansible.cfg. To learn more about the file refer to "Ansible Configuration Settings" section in the common README file (../README)
5. Install the required python packages specified in the Pre-requisites section.

Initial Setup for Configuring 5G CUPS solution

The initial setup for configuring 5G CUPS solutions involves:

Steps How to.. Refer to..
Preparing GigaVUE-FM Credentials file

Prepare a GigaVUE-FM credential file with the below YAML format:

fmInfo:

10.115.54.132:

username:admin

password: admin123A!!

 

10.115.46.156:

username: admin password: admin123A!!

For more information about encrypting the GigaVUE-FM credential, refer to the README file in the CUPS solution package.

Preparing Path Configuration files

Prepare an Input JSON file (for example ~/ansible_inputs.json) for the ansible command line to specify the below paths:

  • Yaml_payload_path – Path in which the successfully configured payloads are saved.

For Example:

yaml_payload_path": "/home/user/cups_payload_consolidated.yaml

• Golden_payload_path - Path in which the successfully configured JSON payloads are saved.

For Example:

golden_payload_path": "/home/user/cups_golden_payload.yaml

  • deployment_report_path - Location to generate the deployment Report after sending the CUPS solution payload to GigaVUE-FM.

For Example:

deployment_report_path": "/home/user/deploymentReport.yaml

  • •fm_credential_file – GigaVUE-FM Credentials file path.

 

Configure 5G CUPS Solution

To configure a 5G CUPS solution, perform the following steps:

 

S.No Steps How to.. Refer to..
1. Creating Directory Create a directory to keep your inventories for example ~/myInventory. Create a directory host_vars under your directory ~/myInventory/host_vars/.  
2. Defining 5G and LTE Policies Define 5G and LTE policy in the YAML Schema and place your policy YAML files in ~/myInventory/host_vars/ like ~/myInventory/host_vars/lte_policy_1.yaml , ~/myInventory/5g_policy_1.yaml README_CUPS/CUPS_YAML_DEFINTION.yaml in the solution package.
3. Defining the Parameters of 5G CUPS

Define the following information related to configuration of 5G CUPS in the template provided and save them in .CSV format:

  • Network Sources
  • CPN and UPN information
  • Site information

Note:  You can also create your own CPN/UPN/Site.yaml files and master orchestrating ansible inventory file manually.

Inputs tab in the excel file README_CUPS/ CUPS_Siteconfigs.xls in the solution package
4. Converting the CSV files to YAML

Convert the .CSV files to YAML using the Python tool provided with the solution in the path.

FM_Ansible/integration/tools/cupsCsvToYaml.py

Note:   Use./cupsCsvToYaml.py -h to check for the supported command line options

. tools/cupsCsvToYaml.py --inventory_dir_path ~/myInventory --nwCsv cups_csvs/NetworkSources.csv --vfCsv cups_csvs/CUPNInfo.csv --siteInfo cups_csvs/SiteInfo.csv --ltePolicy lte_policy.yml --5gPolicy 5g_policy.yml --cupsSolutionAlias cups1.

Note:   The tool also creates the Ansible Inventory file in ~/myInventory/cups_inventory.

 
5. Adding Pre-requisites configurations

Edit the Inventory host_vars file to add the pre-requisites configurations such as:

  • GTPwhiteLists
  • IpInterfaces
  • ToolGroups
  • GigaSTREAM
README_CUPS/CUPS_Prerequisites_per_cluster_template.yml in the solution package
6. Execute the ansible-playbook

Cups_inventory file provides the following information:

  • CPN/UPNs that correspond to the Sites.
  • Sites that belongs to the solution.
  • Policy chosen is either 5G or LTE, or both.
  • Pre-requisite clusterIds in the respective Pre-requisite groups.

After editing the inventory file, execute the ansible-playbook to deploy the solution using:

ansible-playbook -e "@/home/user/ansible_inputs.json"-vvv -i ~/myInventory/cups_inventory playbooks/cups/deploy_cups.yml

Note:  Ansible CUPS deployment fails when GigaVUE-FM CUPS deployment fails.

 

Inventory File Samples

The following are the sample cups_inventory, which are generated by the above csv and then provided to the yaml tool. This includes the details for groups such as, [Policies], [CPN], [UPN], [Sites], [CUPS]. It creates empty groups for [GTPWhitelist], [IPInterfaces], [ToolGroups], and [Gigastreams], which are the pre-requisites for the CUPS solution. You must provide the clusterId where prerequisites need to be configured, and also make sure that you have created the corresponding <clusterId>.yml under host_vars/ in your inventory directory.

If you have manually created all your pre-requisites configurations in all the clusters, you can leave it empty.

Single FM:

For Single FM, specify your fmIp in the environment variable, ANSIBLE_FM_IP and make sure that the fmIP given has entry in your fm_credential_file (fmInfo.yml)

[GTPWhitelist]

10.115.54.83

 

[IPInterfaces]

10.115.54.83

 

[ToolGroups]

10.115.54.83

 

[Gigastreams]

 

[Policies]

5g_policy

 

[CPN]

CPN_5G_01

 

[UPN]

UPN_5G_01

 

[Sites]

LA cpn_list='["CPN_5G_01"]' upn_list='["UPN_5G_01"]'

 

[CUPS]

cups_5g_1 5g_policy=5g_policy sites='["LA"]'

 

Multiple FMs:

In Multiple GigaVUE-FM cases, you must follow these steps:

[GTPWhitelist]

10.115.54.83 fm_ip=1.1.1.1

10.115.54.84 fm_ip=1.1.1.2

 

[IPInterfaces]

10.115.54.83 fm_ip=1.1.1.1

10.115.54.84 fm_ip=1.1.1.2

 

[ToolGroups]

10.115.54.83 fm_ip=1.1.1.1

10.115.54.84 fm_ip=1.1.1.2

 

[Gigastreams]

10.115.54.83 fm_ip=1.1.1.1

10.115.54.84 fm_ip=1.1.1.2

 

[Policies]

5g_policy

 

[CPN]

CPN_5G_01

 

[UPN]

UPN_5G_01

 

[Sites]

LA cpn_list='["CPN_5G_01"]' upn_list='["UPN_5G_01"]'

 

[CUPS]

cups_5g_1 5g_policy=5g_policy sites='["LA"]' fm_ip=1.1.1.1

cups_5g_2 5g_policy=5g_policy sites='["LA"]' fm_ip=1.1.1.2

Features Supported for CUPS solution in Ansible

Ansible supports the following features for CUPS in addition to creating, updating or deleting a CUPS solution across Single or Multiple GigaVUE-FM:

Deployment Report

Whenever ansible creates, updates or deletes a CUPS solution, deployment report is generated in the path given in the "deployment_report_path" variable of ansible_input.json. It appends the GigaVUE-FM IP at the end of the path to generate the deployment report for each GigaVUE-FM in case of multiple GigaVUE-FM deployment. For example, for the path, "deployment_report_path": "/home/user/deploymentReport_tc1.yaml", then deployment report path is /home/user/deploymentReport_tc1_<fmip>.yaml.

The deployment report provides the following information:

Sample Deployment Report in YAML

deploymentPayloadDiff:

updated:

- path: //trafficPolicies/LTE/whitelisting/flowMaps/wlMapGeoProbe/rules/rule_1/apn

old_value: apn.vodafone.com

new_value: apn.airtel.com

- path: //trafficPolicies/LTE/sampling/flowMaps/samplingMapToeEEA/rules/rule_1/userPlanePercentage

old_value: 50

new_value: 25

removed:

- path: //sites/SanFrancisco/cpNodes/CPN_01/trafficSources/cpn1_pod2/networkElementFunctionInterfaces/S11/tunnelIdentifiers/VLAN_16777214

value:

interfaceTunnelIdentifierValue:

value: 16777214

interfaceTunnelIdentifierType: VLAN

created:

- path: //sites/SanFrancisco/cpNodes/CPN_01/trafficSources/cpn1_pod2/networkElementFunctionInterfaces/S11/tunnelIdentifiers/VLAN_16777215

value:

interfaceTunnelIdentifierValue:

value: 16777215

interfaceTunnelIdentifierType: VLAN

deploymentRequest: EDIT

deploymentStatus:

msg: CUPS solution cupsMixed1 updated

failed: false

skipped: false

changed: true

deploymentResponse:

deleted: []

failed: []

updated:

- status: SUCCESS

alias: UPN_01

clusterId: 10.115.54.83

objectType: UPN

- status: SUCCESS

alias: CPN_01

clusterId: 10.115.54.83

objectType: CPN

skipped: []

created: []

timeStamp: 09-Mar-2020::12:04:1583780672

Check Mode

The CUPS ansible solution also supports checkmode which states that even without deploying the solution in the payload, it fetches you the differences between the current payload and the proposed payload. You can use it while editing the solution to cross-check the components that can be created, removed, or updated.

To run the solution in checkmode, use the ansible command line option "–check" as follows:

ansible-playbook --check -i ~/myInventory3/cups_inventory -e "@~/ansible_inputs.json" --ask-vault-pass playbooks/cups/deploy_cups.yml

The check mode generates the deployment Report. Since it is not deployed in GigaVUE-FM, the "deploymentResponse" field in the report is in "CHECKMODE" (for real deployment, GigaVUE-FM response will be present). You can check the difference between the current and proposed payload in the field, "deploymentPayloadDiff".

Golden Payload

Whenever the CUPS payload is successfully deployed or updated, that instance of the complete YAML payload is saved as Golden Payload in the path given in the ansible_input.json file as "golden_payload_path". If the path is not given, it is saved in the current directory.

At times, when you feel that the CUPS solution is messed up and need to deploy the golden payload, you can apply the saved golden payload using the ansible command line option, "-e applyGP=True". Before applying the golden payload, make sure that the golden_payload_path is updated in the ansible_input.json and the path exists.

Run "-e applyGP=True" with "–check" to know the difference between the current system's payload and proposed golden payload. Ansible throws a Confirmation message to run in check mode everytime when you apply the "-e applyGP=True". If you are in check mode, you can enter to continue, or Press Ctrl+C and A to abort the execution.

Once you confirm to applyGP with check mode, you can omit the --check option to deploy golden payload.

 

Command to run applyGP in check mode:

ansible-playbook -e "applyGP=True" --check -i ~/myInventory3/cups_inventory -e "@~/ansible_inputs.json" --ask-vault-pass playbooks/cups/deploy_cups.yml

Command to apply the golden payload:

ansible-playbook -e "applyGP=True" -i ~/myInventory3/cups_inventory -e "@~/ansible_inputs.json" --ask-vault-pass playbooks/cups/deploy_cups.yml

When you apply the golden payload, it prompts you the below message ensure that you run in the check mode. If you done with Check mode, press enter to continue or Ctrl+C and A to abort.

[cups : Check before apply golden payload]

Note:  Ensure that you run Check mode only to find the difference between the Golden Payload and the current state. Press Ctrl+C and 'A' to abort, and 'ENTER' to continue.

 

Using gigamon_cups ansible module to create your own playbooks:

If you want to use the module in your own playbook instead of using the playbooks and pre-requisites defined above, you can send the full yaml payload through 'input_payload' option in the module. Ensure that you have created all the pre-requisite configurations on your own before using this module in your playbook.

Example Playbook:

name: Configure CUPS

hosts: localhost

# fm_credential_file is passed through cmdline extra args and its contents example is given below.

vars_files: "{{ fm_credential_file }}"

vars:

fm_ip: "{{ hostvars[inventory_hostname].fm_ip | default(lookup('env', 'ANSIBLE_FM_IP')) }}"

tasks:

- name: Configuring only cups

gigamon_cups:

fm_ip: "{{ fm_ip }}"

fm_username: "{{ fmInfo[fm_ip]['username'] }}"

fm_password: "{{ fmInfo[fm_ip]['password'] }}"

dr_path: "{{ deployment_report_path }}"

payload_path: "{{ yaml_payload_path }}"

input_payload: "/home/user/golden_payload.yaml"

state: "present"

If you do not want to use vars_files for credential, you can pass the IP, username, password directly in the tasks.

 

Sample Ansible Commands

The following are the sample ansible commands for various use cases:

ansible-playbook -i ~/myInventory3/cups_inventory -e "@~/ansible_inputs.json" --ask-vault-pass playbooks/cups/deploy_cups.yml

--ask-value is used if you create ansible-vault for fmInfo.yml

It is the same command as create solution, ansible will update the solution instead of creating the solution.

ansible-playbook -i ~/myInventory3/cups_inventory -e "@~/ansible_inputs.json" --ask-vault-pass playbooks/cups/deploy_cups.yml

For deleting the solution, including the pre-requisites, call the delete_cups.yml playbook under playbooks/cups/delete_cups.yml

ansible-playbook -i ~/myInventory3/cups_inventory -e "@~/ansible_inputs.json" --ask-vault-pass playbooks/cups/delete_cups.yml

To run in check mode, include the command line option, "–check".

ansible-playbook --check -i ~/myInventory3/cups_inventory -e "@~/ansible_inputs.json" --ask-vault-pass playbooks/cups/deploy_cups.yml

This will not deploy the solution. It only generates the deployment report with the difference between the current and proposed payload.

ansible-playbook -e "applyGP=True" --check -i ~/myInventory3/cups_inventory -e "@~/ansible_inputs.json" --ask-vault-pass playbooks/cups/deploy_cups.yml

ansible-playbook -e "applyGP=True" -i ~/myInventory3/cups_inventory -e "@~/ansible_inputs.json" --ask-vault-pass playbooks/cups/deploy_cups.yml