diff --git a/05-quickstarts.md b/05-quickstarts.md index 61aeada0cdd36ee6884becddad2e2159f05bea5e..0101b6ed70b61a9c983d03ffcfb43d0b6fa57b19 100644 --- a/05-quickstarts.md +++ b/05-quickstarts.md @@ -6,6 +6,7 @@ This sections uses some of the [OSM Community examples](https://osm.etsi.org/git 2. [Single VDU Router with Ansible](#single-vdu-router-with-snmp-metrics-and-ansible-playbook) 3. [Single VDU Virtual Desktop with Native Charms](#single-vdu-virtual-desktop-with-native-charms) 4. [OpenLDAP CNF with Helm Charts](#openldap-cnf-modeled-with-helm-charts) +5. [Kamailio and SIPP CNF with juju bundles](#kamailio-and-sipp-cnf-modeled-with-juju-bundles) ## Single VDU Linux machine with simple action through Proxy Charm @@ -1068,3 +1069,175 @@ applications: - https://discourse.charmhub.io/t/k8s-spec-reference/3495 - Juju docs: https://juju.is/docs/sdk - Operator framework docs: https://ops.readthedocs.io/en/latest/index.html + +## Kamailio and SIPP CNF modeled with juju bundles + +This example implements a CNF of kamailio and SIPP client + +### Onboarding + +#### Onboarding requirements + +- OSM Client installed in linux +- Internet access to clone packages + +#### Step 1: Clone the OSM packages to your local machine + +If you don't have the OSM Packages folder cloned yet, proceed with cloning it: + +``` +git clone --recursive https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages && cd osm-packages/charm-packages +``` + +#### Step 2: Explore the packages + +First, explore the folder `kamailio/kamailio_knf`, + +``` +kamailio_knf +| - juju-bundles +| | - bundle.yaml +| | - kamailio-k8s_ubuntu-20.04-amd64.charm +| | - sipp-k8s_ubuntu-20.04-amd64.charm +| - kamailio_cnfd.yaml +``` + +Next `juju-bundles/bundle.yaml` which conatins the actual deployment unit definitions. + +```yaml +bundle: kubernetes +applications: + kamailio: + charm: ./kamailio-k8s_ubuntu-20.04-amd64.charm + scale: 1 + trust: true + options: + sip-domain: localhost + resources: + kamailio-image: kamailio/kamailio:5.3.3-stretch + sipp: + charm: ./sipp-k8s_ubuntu-20.04-amd64.charm + scale: 1 + trust: true + options: + resources: + sipp-image: grigiu/sipp:latest +``` + +The charms referenced in this bundle is local which is present as part of package. + +For more details of kamailio charm refer [here](https://github.com/davigar15/kamailio-operator) and on sipp charm refer [here](https://github.com/davigar15/sipp-operator). + +The file `kamailio_cnfd.yaml` is the CNF descriptor, which models a single KDU (Kubernetes Deployment Unit) with the specified bundle (`juju-bundles/bundle.yaml`) here, a single connection point (`mgmt-ext`) where all Kubernetes services of this juju-bundle will be exposed, and certain k8s-cluster requirements (in this case, it must have at least one network to expose services). + +##### Explore Day 0 Actions + +For day-0 configuration in OSM, cloud-init is usually used, but that is not available in CNFs. Instead, in the juju bundle, we could be able to define some options to the charms, that will be considered at deployment time. These configs could trigger some internal actions in the charms, so we can consider these as day-0 actions. + +```yaml +sipp: + charm: ./sipp-k8s_ubuntu-20.04-amd64.charm + scale: 1 + trust: true + options:{} # <-- OPTIONS FOR THE CHARM HERE +``` + +##### Explore Day 1 Actions + +Generally, Day 1 actions can be specified under the `initial-config-primitive` section in the vnfd descriptor. Current kamailio_knf package does not contain one. + +##### Explore Day 2 Actions + +Day 2 actions are specifies under the `config-primitive` section in the vnfd descriptor. + +```yaml +config-primitive: + - name: options + parameter: + - name: application-name + data-type: STRING + default-value: sipp + - name: ip + data-type: STRING + - name: port + data-type: INTEGER + default-value: 5060 +``` + +It must be noted that the descriptor follows a format defined in OSM, augmenting SOL006, because the modeling of CNF or any Kubernetes applications has not yet been included in ETSI NFV SOL006. + +The file `kamailio_ns/kamailio_nsd.yaml` is the SOL006-compliant network service descriptor, which maps the CNF to VIM-level networks. + +#### Step 3: Upload the packages to the catalogue + +Using the folders above, you can directly validate, compress and upload the contents to the OSM catalogues as packages, in this way: + +``` +# Upload the VNF package first +osm nfpkg-create kamailio_knf + +# Then, upload the NS package that refers to the VNF package +osm nspkg-create kamailio_ns +``` + +With this last step, the onboarding process has finished. + +### Instantiation + +#### Instantiation requirements + +- Full OSM installation (Release 9+) +- A Kubernetes cluster where to run the CNF, refer [here](https://osm.etsi.org/docs/user-guide/05-osm-usage.html#osm-kubernetes-requirements). +- A VIM added with a Kubernetes cluster registered and enabled + +#### Step 1: Ensure your infrastructure is ready + +Ensure you have a VIM created, for example, for OpenStack we would use the following command: + +``` +osm vim-create --name MY_VIM --tenant MY_VIM_TENANT --user MY_TENANT_USER --password MY_TENANT_PASSWORD --auth_url 'http://MY_KEYSTONE_URL' --account_type openstack +``` + +Make sure that you have your Kubernetes credentials file (`kubeconfig.yaml`). Then, if your Kubernetes cluster is running inside of a VIM as a set of VM, identify the VIM network where the VM are connected. If your Kubernetes cluster is running outside the VIM, identify the VIM network where the Kubernetes cluster is physically connected. Check [this guide](https://osm.etsi.org/docs/user-guide/05-osm-usage.html#adding-kubernetes-cluster-to-osm) for more details. + +Once you have identified the VIM network, e.g. MY_K8S_NETWORK, register the Kubernetes cluster and associate it to the VIM as follows: + +``` +osm k8scluster-add MY_CLUSTER --creds kubeconfig.yaml --vim MY_VIM --k8s-nets '{net1: MY_K8S_NETWORK}' --version "1.20" --description="My Kubernetes Cluster" +``` + +In some cases, you might be interested in using an isolated K8s cluster to deploy your KNF. Although these situations are discouraged (an isolated K8s cluster does not make sense in the context of an operator network), it is still possible by creating a dummy VIM target and associating the K8s cluster to that VIM target: + +osm vim-create --name MY_LOCATION_1 --user u --password p --tenant p --account_type dummy --auth_url http://localhost/dummy +osm k8scluster-add MY_CLUSTER --creds kubeconfig.yaml --vim MY_LOCATION_1 --k8s-nets '{k8s_net1: null}' --version "v1.15.9" --description="Isolated K8s cluster in MY_LOCATION_1" + +#### Step 2: Instantiate the Network Service + +Launch the Network Service with the following command (in this example we are using "osm-ext" as the network name) + +``` +osm ns-create --ns_name kamailio_sipp --nsd_name kamailio_ns --vim_account etsi-vim --config '{vld: [ {name: mgmtnet, vim-network-name: osm-ext}]} ' +``` + +#### Step 3: Visualize the results + +Once instantiated, you can see the NS status with the `osm ns-list` command or visiting the GUI. + +Furthermore, you can check: + +- The status of the KDU directly from OSM by getting the NF instance ID (`osm vnf-list --ns kamailio_sipp`) and getting the status using the command `osm vnf-show VNF-ID --kdu kamailio-kdu`. +- The status of the KDU using juju (`juju status -m kamailio-kdu-NS_ID`). +- The status of the KDU directly from the k8s-cluster (`kubectl get all -n kamailio-kdu-NS_ID`). + +#### Step 4: Execute Day 2 action + +``` +osm ns-action --action_name options --vnf_name kamailio --kdu_name kamailio-kdu --params '{ip: SIP_SERVER_IP}' kamailio_sipp +``` + +Action "options" is executed against SIPP KDU which allows a User Agent (UA) to query another UA or a proxy regarding its capabilities. + +Furthermore, you can check: + +- The status of the action can be identified with `osm ns-op-list kamailio_sipp` command or visiting the GUI. +- The detailed status of an action can be retrieved using `osm ns-op-show NS_OP_ID`.