diff --git a/05-quickstarts.md b/05-quickstarts.md index 19bb5e28037ddd816072e21fee5a76e4cd3162d7..d6eb9a13f7e0ca135a91b52e6449080709eb349f 100644 --- a/05-quickstarts.md +++ b/05-quickstarts.md @@ -182,6 +182,230 @@ Some common customizations that make this package easily reusable are: - Modify the playbook contents at the `snmp_setcomm_ee_vnf/helm-charts/eechart/source/community.yaml` folder. - Modify the day-0 (cloud_init) configurations, with the `snmp_setcomm_ee_vnf/cloud_init/vyos-userdata` file and the "config" primitive contents at the VNFD. + +## Squid CNF modeled with Juju bundles + +This example implements an Squid web proxy operator for Kubernetes. On instantiation, an operator charm is run, creating the pod spec with all the information Kubernetes need to spin up the deployment. + +### 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 +``` + +#### Step 2: Explore the packages + +The file `squid_metrics_cnf_ns/squid_cnf_ns.yaml` is the SOL006-compliant network service descriptor, which maps the CNF to VIM-level networks. There is only one networks that this service will use: + +1. "mgmtnet": the management network, which represents the internal, private management network that is used for controlling the Squid service + +The vnf directory `squid_cnf` contains: + +1. the SOL006-compliant virtual network function descriptor `squid_cnf.yaml` +2. a `juju-bundles` folder where the juju bundle and all the charms are located. + +###### 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. + +In the file `squid_metrics_cnf/juju-bundles/bundle.yaml`, we can set the options here: + +```yaml +description: Squid Bundle +bundle: kubernetes +applications: + squid: + charm: ./charms/squid-operator + scale: 1 + options: {} # <-- OPTIONS FOR THE CHARM HERE +``` + +##### Explore Day 1 Actions + +Day 1 actions are specifies under the `initial-config-primitive` section in the vnfd descriptor. + +```yaml +initial-config-primitive: + - seq: 0 + name: add-url + parameter: + - name: application-name + data-type: STRING + value: squid + - name: url + data-type: STRING + value: "osm.etsi.org" +``` + +There is only one day 1 action in this package, which is `add-url`. There are two parameters passed, `application-name` and `url`. The first one indicates the name of the application the action should be executed on. The second one indicates the domain that we would like to enable through the use of our proxy. + +In this action we are allowing access to `osm.etsi.org` through the proxy. + +##### Explore Day 2 Actions + +Day 2 actions are specifies under the `config-primitive` section in the vnfd descriptor. + +```yaml +config-primitive: + - name: add-url + parameter: + - name: application-name + data-type: STRING + default-value: squid + - name: url + data-type: STRING + default-value: "" + - name: delete-url + parameter: + - name: application-name + data-type: STRING + default-value: squid + - name: url + data-type: STRING + default-value: "" +``` + +There are two actions available: `add-url` and `delete-url`. The first action is the same as the one used for day 1 configuration. The second one is similar, because the set of parameters that are passed to the action are the same; the main difference is that this action will remove previously added url from squid, so that we are not longer able to reach that url through the proxy. + +#### 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 squid_metrics_cnf/ + +# Then, upload the NS package that refers to the VNF package +osm nspkg-create squid_metrics_cnf_ns/ +``` + +With this last step, the onboarding process has finished. + +### Instantiation + +#### Instantiation requirements + +- Full OSM installation (Release 9+) +- A VIM added with a Kubernetes cluster registered and enabled + +#### Step 1: Ensure your infrastructure is ready + +Ensure you have a VIM created, and a K8s cluster registered to it: + +``` +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 --config '{management_network_name: MY_MANAGEMENT_NETWORK}' + +osm k8scluster-add MY_CLUSTER --creds kubeconfig.yaml --vim MY_VIM --k8s-nets '{net1: MY_MANAGEMENT_NETWORK}' --version "1.20" --description="My Kubernetes Cluster" +``` + +If you do not want to associate the Kubernetes cluster with an actual VIM, you can always create a dummy vim-account and register your cluster with that: + +``` +osm vim-create --name MY_DUMMY_VIM_NAME --user u --password p --tenant p --account_type dummy --auth_url http://localhost/dummy + +osm k8scluster-add MY_CLUSTER --creds kubeconfig.yaml --vim MY_DUMMY_VIM_NAME --k8s-nets '{net1: MY_MANAGEMENT_NETWORK}' --version "1.20" --description="My Kubernetes Cluster" +``` + +To ensure the K8s cluster has been added properly, execute the following command and ensure both Juju is in `ENABLED` state. + +``` +osm k8scluster-list +``` + +#### 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 squid-cnf-ns \ + --nsd_name squid_cnf_ns \ + --vim_account MY_VIM \ + --config \ + '{vld: [ {name: mgmtnet, vim-network-name: osm-ext} ] }' +``` + +This shows how to provide an override to the name of the management network in the NS: + +- `mgmtnet` is mapped to a network in the VIM called `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. + +Once it finished instantiating, you can get the IP address of the squid service from Kubernetes with the following commands: + +``` +cnf_id=`osm vnf-list | grep squid | awk '{ print $2 }'` +osm vnf-show --literal $cnf_id | yq ".kdur[0].services[]" +``` + +Search for the `external_ip` of the service named `squid`. + +#### Step 4: Check Day 1 action + +First of all you need to get the `external_ip` from the `squid` service as mentioned before. One you have that, execute the following command to check that the day 1 action has worked properly: + +``` +https_proxy=EXTERNAL_SQUID_IP:3128 curl https://osm.etsi.org +``` + +You should be able to get some content from there. Then test with a different domain and check that you are getting a `403` error. + +> Note: Once the deployment is finished, it could take up to 1 minute to properly apply the configuration to squid. If you initially get a `403` error accessing `osm.etsi.org`, wait a bit. + +#### Step 5: Execute Day 2 action + +First of all you need to get the `external_ip` from the `squid` service as mentioned before. One you have that, execute the following command: + +``` +osm ns-action --action_name add-url --vnf_name squid_cnf --kdu_name squid-metrics-kdu --params '{url: MY_DOMAIN}' squid-cnf-ns +``` + +Check that the action has worked with the following command: + +``` +https_proxy=EXTERNAL_SQUID_IP:3128 curl https://MY_DOMAIN +``` + +### Possible quick customizations + +Uncomment the commented lines in `squid_metrics_cnf/juju-bundles/bundle.yaml` in order to enable metrics. + +```yaml +description: Squid Bundle +bundle: kubernetes +applications: + squid: + charm: ./charms/squid-operator + scale: 1 + options: + enable-exporter: true + prometheus: + charm: ./charms/prometheus-operator + scale: 1 + grafana: + charm: ./charms/grafana-operator + scale: 1 +relations: +- - prometheus:target + - squid:prometheus-target +- - grafana:grafana-source + - prometheus:grafana-source +``` + +This will add Prometheus and Grafana to the deployment, and also it will enable a node exporter in the squid so you are able to see the cpu and network metrics from it. + + ## Single VDU Virtual Desktop with Native Charms This example implements an Ubuntu Mate virtual machine with XRDP, created from a stock Ubuntu Cloud image (https://cloud-images.ubuntu.com/focal/current/). On instantiation, a native charm is run, installing all the required packages and configuring the VM to run as a desktop.