diff --git a/00-introduction.md b/00-introduction.md index 94e36ad73d5900cc54cc6ae04bc7d6d7737d388b..075fdb2e3c8e7b383bfd63a0b6b3f1cd00522f14 100644 --- a/00-introduction.md +++ b/00-introduction.md @@ -8,7 +8,7 @@ The onboarded VNF should aim to fulfill the lifecycle stages that the NFV MANO l More information on the delimitation of these stages can be found in the [*OSM Scope and Functionality*](http://osm-download.etsi.org/ftp/Documentation/201902-osm-scope-white-paper/#!02-osm-scope-and-functionality.md) document. -As such, the document is structured in the following parts, providing guidelines for building the VNF Package to achieve each lifecycle stage successfully. +This document provides guidelines for building the VNF Package to achieve each lifecycle stage successfully and is structured as follows: 1. Onboarding Requirements 2. Day 0: VNF Instantiation & management setup diff --git a/01-requirements.md b/01-requirements.md index b3bb8f9a7671c0372a645f9c7fcc585518a5574a..52b52935ecde4464f0c0346a789591b00b855010 100644 --- a/01-requirements.md +++ b/01-requirements.md @@ -1,10 +1,12 @@ # Onboarding Requirements -To achieve the onboarding of each lifecycle stage successfully, the following specific requirements of the VNF must be collected. +Each lifecycle stage targets specific configurations in the VNF. These are: management setup during instantiation (Day-0), service initialization right after instantiation (Day-1) and re-configuration during runtime (Day-2). -## Day 0 requirements +In order to provide a VNF with as many capabilities for each lifecycle stage as possible, the following specific requirements should be adressed. -The main objetive of Day 0 is to instantiate the VNF and establish management access so it can be configured. To achieve this, the main requirements are: +## Day-0 requirements + +During the Day-0 stage, the VNF is instantiated and the management access is established so that the VNF can be configured at a later stage. The main requirements to achieve this are: ### Description of each VNF component @@ -26,7 +28,7 @@ These requirements refer to properties like the number of vCPUs, RAM GBs and dis | uMgmt | 1 | 1 | 2 | N | | sBE | 2 | 8 | 10 | Y | -For some VNFs, Enhanced Platform Awareness (EPA) characteristics need to be defined when VNF requires 'higher than default' performance capabilities or any particular hardware architecture from the NFVI. Popular EPA attributes include: +For some VNFs, the Enhanced Platform Awareness (EPA) characteristics need to be defined when the VNF requires performance capabilities which are "higher than default" or any particular hardware architecture from the NFVI. Popular EPA attributes include: - Compute performance attributes: - CPU Pinning @@ -52,14 +54,17 @@ Additional topology examples, along with sample descriptor files, can be found [ ### Images and cloud-init files -The images for each component should be available in the format that corresponds to the main supported hypervisor. This image should contain the minimal configuration that makes it generic (not scenario-specific) and with **no hardcoded parameters*- that are relevant to the service. Furthermore, cloud-init files can be used to inject this minimal configuration to the VNF. Some examples: +The images for each component should be available in the format that corresponds to the main supported hypervisor. This image should contain the minimal configuration that makes it generic (not scenario-specific) and with **no hardcoded parameters** that are relevant to the service. Furthermore, cloud-init files can be used to inject this minimal configuration to the VNF. Some examples: ```yaml # Cloud-init using cloud-config format #cloud-config hostname: vnfc01 -chpasswd: { expire: False } +chpasswd: + list: | + ubuntu:ubuntu + expire: False ssh_pwauth: True ``` @@ -80,24 +85,24 @@ echo -y | cp /tmp/ipcfg /etc/sysconfig/network-scripts/ifcfg-eth0 systemctl restart network ``` -### Identifying the need for instantiation parameters +### Identifying the instantiation parameters The VNF Day-0 configuration may require some parameters passed at instantiation time in order to fulfill the needs of the particular environment or of other VNFs in the Network Service. This parameters should be identified as early in the process as possible. -## Day 1 requirements +## Day-1 requirements -The main objetive of Day 1 is to configure the VNF so it starts providing the expected service. To achieve this, the main requirements are: +The main objetive of the Day-1 stage is to configure the VNF so it starts providing the expected service. To achieve this, the main requirements are: ### Identifying dependencies between components This may be required to identify instantiation parameters or special timing requirements. Examples of dependencies between components include: -- Components needing parameters from other components of from the infrastructure to complete the parameters configuration. +- Components needing parameters from other components or from the infrastructure to complete the parameters configuration. - Components depending on others for their configuration to be initialized. ### Defining the required configuration for service initialization -This initial configuration will run automatically after the VNF has been instantiated. It should activate the service that the VNF is supposed to deliver, and should be initially prepared in the language that the VNF supports. Once it's defined, it would need to be incorporated by the mechanism that the generic VNF Manager implements. For example: +This initial configuration will run automatically after the VNF is instantiated. It should activate the service delivered by the VNF and should be initially prepared in the language that the VNF supports. Once it's defined, it would need to be incorporated by the mechanism that the generic VNF Manager implements. For example: ```python # A Python script (NETCONF/YANG in the example) @@ -113,15 +118,15 @@ config = """ """ -host = {'name':'VNF1','ip': '192.168.0.1'} -interface_list = ['eth1','eth2'] +host = {'name':'VNF1', 'ip': '192.168.0.1'} +interface_list = ['eth1', 'eth2'] -m = manager.connect(host=host['ip'],username='ws',password='ws') +m = manager.connect(host=host['ip'], username='ws', password='ws') for interface in interface_list: - response = m.edit_config(target='candidate', config=config.format(interface=interface)) - commit = m.commit() - print(commit) + response = m.edit_config(target='candidate', config=config.format(interface=interface)) + commit = m.commit() + print(commit) m.close_session() ``` @@ -142,11 +147,11 @@ m.close_session() ### Identifying the need for instantiation parameters -The VNF Day-1 configuration may require some parameters passed at instantiation time in order to fulfill the needs of the particular environment or of other VNFs in the Network Service. This parameters should be identified as early in the process as possible. +The VNF Day-1 configuration may require some parameters passed at instantiation time in order to fulfill the needs of the particular environment or of other VNFs in the Network Service. These parameters should be identified as early in the process as possible. -## Day 2 requirements +## Day-2 requirements -The main objetive of Day 2 is to be able to **re-configure** the VNF so its behavior can be modified during runtime, as well as being able to monitor its main KPIs and run scaling actions over it. +The main objetive of Day-2 is to be able to **re-configure** the VNF so its behavior can be modified during runtime, as well as being able to monitor its main KPIs and run scaling actions over it. To achieve this, the main requirements are: ### Identifying dependencies between components @@ -155,12 +160,12 @@ This process may be required to identify if a VNF component requires a parameter ### Defining all possible configurations for runtime operations -This set of configurations should be available to be triggered from the orchestrator during the VNF runtime, either manually by the operator, or automatically based on some state. Once this set of configurations have been defined, they would need to be incorporated by the mechanism that the generic VNF Manager implements. -Just as in Day-1, the set of configurations can be provided by Python scripts, Ansible playbooks, VNF-specific commands run over SSH, REST API calls, or whatever the VNF makes available to expose its main operations. +The set of configurations should be available to be triggered from the orchestrator during the VNF runtime, either manually by the operator or automatically, based on some state. Once that set of configurations has been defined, it needs to be incorporated by the mechanism that the generic VNF Manager implements. +Just as in Day-1, the set of configurations can be provided by Python scripts, Ansible playbooks, VNF-specific commands that run over SSH, REST API calls, or whatever the VNF makes available to expose its main operations. ### Defining key performance indicators -The metrics that are relevant to the VNF should be specified, either if they are supposed to be collected from the infrastructure (through the VIM) or directly from the VNF (or its EM, through any API, MIB or command that the VNF exposes). Some examples include: +The metrics that are relevant to the VNF should be specified, either if they are supposed to be collected from the infrastructure (through the VIM) or directly from the VNF (or its Element Manager, through any API, MIB or command that the VNF exposes). Some examples include: - Metrics typically collected from the VIM/NFVI: - CPU Usage @@ -175,7 +180,7 @@ The metrics that are relevant to the VNF should be specified, either if they are ### Defining closed-loop operations -Closed-loop operations are actions triggered by the status of a particular metric. Main use cases include: +Closed-loop operations are actions triggered by the status of a particular metric. The main use cases include: - Auto-scaling: a VNF component scales horizontally (out/in) to match the current demand. Some typical definitions that must be clear are: - How the VNF will load-balance the traffic once it scales. diff --git a/02-day0.md b/02-day0.md index 746186517f26c4855caed75fd282983ec68ae9ec..abf56ec4ed4c668c422f3ef811a9c0c3acf1d78a 100644 --- a/02-day0.md +++ b/02-day0.md @@ -6,11 +6,11 @@ The objective of this section is to provide the guidelines for including all the The way to achieve this in OSM is to prepare the descriptor so that it accurately details the VNF requirements, prepare cloud-init scripts (if needed), and identify parameters that may have to be provided at later stages to further adapt to different infrastructures. -## Day 0 Onboarding Guidelines +## Day-0 Onboarding Guidelines ### Building the initial package -The most straightforward way to build a VNF package from scratch, is to use the existing script available a the OSM Devops repository. From a Linux/Unix-based system: +The most straightforward way to build a VNF package from scratch is to use the existing script available a the OSM Devops repository. From a Linux/Unix-based system: #### Clone the OSM DevOps repository and access the tools folder. @@ -49,14 +49,14 @@ For example: --cloud-init-file init_lb --interfaces 2 --vendor ACME --nsd vLB ``` -Note that we are adding the 'nsd' keyword to create also a NS Package and simplify testing. So the above example will create, in the `/home/ubuntu` folder: +Note that we are adding the 'nsd' keyword to create also a NS Package and simplify testing. So the above example will create, in the `/home/ubuntu` folder, the following files: - `vLB_vnfd` → VNFD Folder - `vLB_vnfd.tar.gz` → VNFD Package - `test_vnf01_nsd` → NSD Folder - `test_vnf01_nsd.tar.gz` → NSD Package -**The VNFD Folder will contain the YAML file which models the VNF, it should be further edited to achieve the desired characteristics.** +**The VNFD Folder will contain the YAML file which models the VNF. This should be further edited to achieve the desired characteristics.** ### Modelling advanced topologies @@ -71,7 +71,7 @@ When dealing with multiple VDUs inside a VNF, it is important to understand the | Internal CP | Element internal to a VNF, maps VDU interfaces to internal VLDs | VNFD | | External CP | Element exposed externally by a VNF, maps VDU interfaces to external VLDs | NSD | -As VNF Package builders, we should clearly identify interfaces that are internal to the VNF and used to interconnect our own VDUs through internal VLDs, and interfaces that we want to expose to other VNFs within a Network Service, using external VLDs. +As VNF Package builders, we should clearly identify interfaces that i) are internal to the VNF and used to interconnect our own VDUs through internal VLDs, and ii) those we want to expose to other VNFs within a Network Service, using external VLDs. In this example from the [5th OSM Hackfest](https://osm.etsi.org/wikipub/index.php/5th_OSM_Hackfest), we are building the following Multi-VDU topology: @@ -189,7 +189,7 @@ nsd:nsd-catalog: Even though it is not recommended to hard-code networking values in order to maximize the VNF Package uniqueness, there may be some freedom for doing this at internal VLDs, especially when they are not externally accessible by other VNFs and not directly accessible from the management network. -The **IP Profiles** feature allows us to set some subnet specifics that can become useful. The following VNFD extract can be used as a reference, further IP Profile settings can be found at the [OSM Information Model Documentation](https://osm.etsi.org/wikipub/index.php/OSM_Information_Model). +The **IP Profiles** feature allows us to set some subnet specifics that can become useful. Further IP Profile settings can be found at the [OSM Information Model Documentation](https://osm.etsi.org/wikipub/index.php/OSM_Information_Model). The following VNFD extract can be used as a reference: ```yaml vnfd:vnfd-catalog: @@ -247,14 +247,29 @@ Cloud-init is normally used for Day-0 operations like: * Setting a default locale * Setting an instance hostname -* Generating instance SSH private keys +* Generating instance SSH private keys or defining passwords * Adding SSH keys to a user’s .ssh/authorized_keys so they can log in * Setting up ephemeral mount points * Configuring network devices * Adding users and groups * Adding files -Cloud-init scripts are referred at the VDU level. They should be included in the **cloud_init** folder of the VNF package, then referred in the descriptor like this: +Cloud-init scripts are referred at the VDU level. These can be defined inline or can be included in the **cloud_init** folder of the VNF package, then referred in the descriptor. + +For inline cloud-init definition, follow this: + +```yaml +vnfd:vnfd-catalog: + vnfd: + - ... + vdu: + - ... + cloud-init: | + #cloud-config + ... +``` + +For external cloud-init definition, proceed like this: ```yaml vnfd:vnfd-catalog: @@ -265,7 +280,7 @@ vnfd:vnfd-catalog: cloud-init-file: cloud_init_filename ``` Its content can have a number of formats, including #cloud-config and bash. -For example, the following script sets a password in Linux. +For example, any of the following scripts sets a password in Linux. ```yaml #cloud-config @@ -275,6 +290,15 @@ chpasswd: { expire: False } ssh_pwauth: True ``` +```yaml +#cloud-config +hostname: lb_vdu +chpasswd: + list: | + ubuntu:osm2018 + expire: False +``` + Additional information about cloud-init can be found in [this documentation](http://cloudinit.readthedocs.io/en/latest/). #### Parametrizing Cloud-init files @@ -326,7 +350,7 @@ The `mempage-size` attribute can take any of these values: #### CPU Pinning -CPU Pinning allows for different settings related to vCPU assignment and hyper threading: +CPU pinning allows for different settings related to vCPU assignment and hyper threading: ```yaml vnfd:vnfd-catalog: @@ -378,7 +402,7 @@ vnfd:vnfd-catalog: ... ``` -`node-cnt` defines the number of NUMA nodes to expose to the VM, while `mem-policy` defines if the memory should be allocated from the strictly from the 'local' NUMA node (STRICT), or not necessarily (PREFERRED). +`node-cnt` defines the number of NUMA nodes to expose to the VM, while `mem-policy` defines if the memory should be allocated strictly from the 'local' NUMA node (STRICT) or not necessarily from that node (PREFERRED). The rest of the settings request a specific mapping between the NUMA nodes and the VM resources and can be explored at detail in the [OSM Information Model Documentation](https://osm.etsi.org/wikipub/index.php/OSM_Information_Model) #### SR-IOV and PCI-Passthrough @@ -431,7 +455,7 @@ vnfd:vnfd-catalog: Once the VNF Descriptor has been updated with all the Day-0 requirements, its folder needs to be repackaged. For example, in Linux/UNIX, it would be something like: `tar -cvfz vLB_vnfd.tar.gz vLB_vnfd/` -A Network Service package containing at least this single VNF needs to be used to instantiate the VNF. This could have been generated with the _devops tool_ described earlier. +A Network Service package containing at least this single VNF needs to be used to instantiate the VNF. This could be generated with the _devops tool_ described earlier. Remember the objectives of this phase: 1. Instantiating the VNF with all the required VDUs, images, initial (unconfigured) state and NFVI requirements. @@ -443,7 +467,7 @@ osm ns-create --ns_name [ns name] --nsd_name [nsd name] --vim_account [vim name] --ssh_keys [comma separated list of public key files to inject to vnfs] ``` -At launch time, extra **_instantiation parameters_** can be passed so that the VNF can be adapted to the particular instantiation environment or to achieve a proper inter-operation with other VNFs into the specific NS. -Further information about these parameters will be revised during the next chapter as part of Day-1 objectives, or can be reviewed [here](https://osm.etsi.org/wikipub/index.php/OSM_instantiation_parameters). +At launch time, extra **_instantiation parameters_** can be passed so that the VNF can be adapted to the particular instantiation environment or to achieve a proper inter-operation with other VNFs within the specific NS. +More information about these parameters will be revised during the next chapter as part of Day-1 objectives, or can be reviewed [here](https://osm.etsi.org/wikipub/index.php/OSM_instantiation_parameters). -The following sections will provide details on how to keep populating the VNF Package to automate Day 1/2 operations. +The following sections will provide details on how to further populate the VNF Package to automate Day 1/2 operations. diff --git a/03-day1.md b/03-day1.md index 3e27fb235ac4c6516a4f1ff3726eefb5ff1d40a5..071411cf2b6e5e1e7ba8153fe25241fdd7776c2b 100644 --- a/03-day1.md +++ b/03-day1.md @@ -2,29 +2,29 @@ ## Description of this phase -The objective of this section is to provide the guidelines for including all the necessary elements in the VNF Package for its services to be automatically initialized right after the VNF has been instantiated. +The objective of this section is to provide the guidelines to include all necessary elements in the VNF Package. This allows the exposed services inside the VNF to be automatically initialized right after the VNF instantiation. The main mechanism to achieve this in OSM is to build a Proxy Charm and include it in the descriptor. -## Day 1 Onboarding Guidelines +## Day-1 Onboarding Guidelines ### Adding Day-1 primitives to the descriptor -These type of initial actions will run automatically after instantiation and should be specified in the VNF descriptor. They can be defined at two different levels: +This type of initial actions will run automatically after instantiation and should be specified in the VNF descriptor. These can be defined at two different levels: -* VDU-level: for a specific VDU, used when there's a VDU needing configuration, which is different that the VDU used for managing the VNF. -* VNF-level: for the 'management VDU', used when the configuration needs to apply to the VDU exposing a interface for managing the whole VNF. +* VDU-level: for a specific VDU, used when a VDU needs configuration, which is different than the VDU used for managing the VNF. +* VNF-level: for the "management VDU", used when the configuration applies to the VDU exposing a interface for managing the whole VNF. **Initial primitives** must include a primitive named `config` that passes information for OSM VCA to be able to authenticate and run further primitives into the VNF. The *config primitive* should provide, at least, the following parameters: -* `ssh-hostname`: Typically used with the that is automatically replaced by the VNF or VDU management IP address specified in the correspondent section. +* `ssh-hostname`: Typically used with the , which is automatically replaced by the VNF or VDU management IP address specified in the correspondent section. * `ssh-username`: The username used for authentication with the VDU. * `ssh-password` or `ssh-public-key`: A static password (not recommended unless it is changed afterwards) or a public-key from the OSM host. `[TODO: confirm that if none is provided, there is an automatic injection with feature 1429?]` -Additional to the *config primitive*, more initial primitives can be run in a desired order for the VNF to initialize its services. Note that each of these additional actions will be later detailed in the proxy charm that implements them. +Additional to the *config primitive*, more initial primitives can be run in the desired order so that the VNF initializes its services. Note that each of these additional actions will be later detailed in the proxy charm that implements them. -The following example shows VNF-level initial primitives named *configure-remote* and *start-service* in addition to the required *config* primitive. +The following example shows VNF-level initial primitives: both the expected *config* primitive in the beginning, but also the *configure-remote* and *start-service* to be run in addition right after initialization. ```yaml vnfd:vnfd-catalog: @@ -55,7 +55,7 @@ vnfd:vnfd-catalog: charm: samplecharm ``` -**Instantiation parameters** can be used for the values of these parameters. The following example shows a VDU-level parameter with variables. Note that when using VDU-level primitives, an interface must be specified as the 'management interface' for that specific VDU. +**Instantiation parameters** can be used to define the values of these parameters in a later time, during the NS instantiation. The following example shows a VDU-level parameter with variables. Note that when using VDU-level primitives, an interface must be specified as the "management interface" for that specific VDU. ```yaml vnfd:vnfd-catalog: @@ -97,11 +97,11 @@ osm ns-create ... --config "{additionalParamsForVnf: [{member-vnf-index: '1', ad ### Building a Proxy Charm -The charm is the element that implements the primitives, it is defined inside the 'charms' folder of the VNF package. The contents of the charm need to be built from a Linux machine. +The charm is the element that implements the primitives or, put in other words, it provides the logic for the different configurations on the VNF. It is defined inside the "charms" folder of the VNF package. The contents of the charm must be built from a Linux machine. #### Method 1: Building a Proxy Charm the traditional way -a) Install the charm tools and setup your environment. You might want to copy the `export` lines to your `~/.bashrc` profile file to automatically load them in the next session. +a) Install the charm tools and setup your environment. You might want to copy the `export` lines to your "~/.bashrc" profile file to automatically load them in the next session. ```bash snap install charm @@ -111,14 +111,14 @@ export LAYER_PATH=$JUJU_REPOSITORY/layers cd $LAYER_PATH ``` -b) A proxy charm includes, by default, the "VNF" and "basic" layers, that take care of the initial SSH connection to the VNF. Create the new personalized *layer* for your proxy charm: +b) A proxy charm includes, by default, the "VNF" and "basic" layers, which take care of the initial SSH connection to the VNF. Create the new personalized *layer* for your proxy charm: ```bash charm create samplecharm cd samplecharm ``` -c) Modify the basic files, like this: +c) Modify the basic files like this: ```bash # layers.yaml file @@ -140,7 +140,7 @@ series: - xenial ``` -d) Modify the `actions.yaml` file, adding all actions/primitives and their parameters. Note that the value of these parameters are defined at the VNFD, either statically or by using variables, as explained earlier. +d) Modify the "actions.yaml" file, adding all actions/primitives and their parameters. Note that the value of these parameters are defined at the VNFD, either statically or by using variables, as explained earlier. ```bash # layers.yaml file @@ -155,7 +155,7 @@ start-service: description: "Starts the service of the VNF" ``` -e) Create an `actions` folder and populate it with files representing each action. File names should match the name of the primitive, should be made executable with `chmod +x`, and must contain the following exact content. +e) Create an "actions" folder and populate it with files representing each action. Filenames should match the name of the primitive, should be made executable with `chmod +x` and all must contain the following exact content. ```bash # actions/configure-remote and actions/start-service files @@ -181,7 +181,7 @@ except Exception as e: EOF ``` -f) Open the respective file at the 'reactive/' folder, which will be used to code, in Python, the actual actions that will run, through SSH, when each primitive is triggered. Note that any variable can be recovered in two ways: +f) Open the respective file at the 'reactive/' folder. This will be used to code, in Python, the actual actions that will run through SSH when each primitive is triggered. Note that any variable can be recovered in two ways: * Using the `config()` function if the variable belongs to that specific primitive. * Using the `action_get('name-of-parameter')` function to get any other parameter. @@ -225,7 +225,7 @@ def start_service(): ``` -g) Finally, build the charm with `charm build` and copy the resulting folder (in this case the `~/charms/builds/simplecharm` directory) inside the `charms` folder of your VNF Package. +g) Finally, build the charm with `charm build` and copy the resulting folder (in this case the "~/charms/builds/simplecharm" directory) inside the "charms" folder of your VNF Package. Futher information about building charms can be found [here](https://osm.etsi.org/wikipub/index.php/Creating_your_own_VNF_charm_(Release_THREE)). #### Method 2: Using Proxy Charm Generators @@ -252,13 +252,13 @@ A sample Ansible playbook would look like this: Once the Ansible playbook has been tested against your VNF, the procedure to incorporate it in a charm is as follows: -a) Create your environment and charm in the same way as in the traditional one (steps (a) and (b) from the previous method) +a) Create your environment and charm in the traditional way (that is, steps (a) and (b) from the previous method) b) Clone the devops repository elsewhere and copy the generator files to your charm root folder. For example: `cp -r ~/devops/descriptor-packages/tools/charm-generator/* ./` `[TODO: migrate to binary]` c) Install the dependencies of the generator with `sudo pip3 install -r requirements.txt` -d) Run the generator, which will populate all the required files automatically. It requires an Ansible playbook to be copied inside a new `playbooks` folder in the charm root directory, and the primitive to be named 'playbook' (by default). The following example runs the generator with the minimal options. +d) Run the generator, which will populate all the required files automatically. It requires an Ansible playbook to be copied inside a new "playbooks" folder under the charm root directory, and the primitive to be named "playbook" (by default). The following example runs the generator with the minimal options. ```bash python3 generator-runner.py --ansible --summary "Configures VNF using Ansible" \ @@ -266,7 +266,7 @@ python3 generator-runner.py --ansible --summary "Configures VNF using Ansible" \ --description "Configures VNF using Ansible" ``` -e) Adjust the 'reactive' file as desired, for example, if you wish to pass some parameters to your playbook (which supports Jinja) +e) Adjust the "reactive" file as desired, for example, if you wish to pass some parameters to your playbook (which supports Jinja) ```python @when('actions.playbook') @@ -294,14 +294,14 @@ def playbook(): remove_flag('actions.playbook') ``` -f) Finally, build the charm with `charm build` and copy the resulting folder (in this case the `~/charms/builds/simplecharm` directory) inside the `charms` folder of your VNF Package. +f) Finally, build the charm with `charm build` and copy the resulting folder (in this case the "~/charms/builds/simplecharm" directory) inside the "charms" folder of your VNF Package. -Once the VNF is launched, the results from running the generator will be found inside the proxy charm *lxc* container, at the `/var/log/ansible.log` file. If not successful, it could indicate the need for other possible modifications which are applicable for certain VNFs. +Once the VNF is launched, the results from running the generator will be found inside the proxy charm *lxc* container, at the "/var/log/ansible.log" file. If not successful, it could indicate the need for other possible modifications which are applicable for certain VNFs. Some modifications may include: -* **Adding a dependency**: if your playbook needs a dependency to run, the pip3 package should be copied to the `wheelhouse` folder after the charm has been built. `[TODO: explore ways of effectively adding dependencies before building the charm]` -* **Disabling SSH connection type**: some VNFs will not pass some SSH pre-checks that Ansible performs in some operations (SFTP, SCP, etc.) In those cases, it has been noted that `ansible_connection=ssh`, which is a default set of the generator, needs to be disabled. This preset would need to be deleted from the `lib/charms/libansible.py` file, `create_hosts` function. `[TODO: explore an enhancement to the Ansible Generator, to be as generic as possible]` +* **Adding a dependency**: if your playbook needs a dependency to run, the pip3 package should be copied to the "wheelhouse" folder after the charm has been built. `[TODO: explore ways of effectively adding dependencies before building the charm]` +* **Disabling SSH connection type**: some VNFs will not pass some SSH pre-checks that Ansible performs in some operations (SFTP, SCP, etc.) In those cases, it has been noted that the `ansible_connection=ssh` directive, which is a default set of the generator, needs to be disabled - being deleted from the `create_hosts` function in the "lib/charms/libansible.py" file. `[TODO: explore an enhancement to the Ansible Generator, to be as generic as possible]` ### Testing Instantiation of the VNF Package @@ -313,7 +313,7 @@ To test this out, the NS can be launched using the OSM client, like this: osm ns-create --ns_name [ns name] --nsd_name [nsd name] --vim_account [vim name] --ssh_keys [comma separated list of public key files to inject to vnfs] --config "{additionalParamsForVnf: [{member-vnf-index: '1', additionalParams:{password: 'secretpassword', destination_ip: '10.1.1.1'}}]}" ``` -Furthermore, as mentioned earlier, extra **_instantiation parameters_** can be passed so that the VNF can be adapted to the particular instantiation environment or to achieve a proper inter-operation with other VNFs into the specific NS. +Furthermore, and as mentioned earlier, extra **_instantiation parameters_** can be passed so that the VNF can be adapted to the particular instantiation environment or to achieve a proper inter-operation with other VNFs into the specific NS. For example, if using IP Profiles to predefine subnet values, a specific IP address could be passed to an interface like this: ```bash @@ -321,4 +321,4 @@ osm ns-create ... --config '{vnf: [ {member-vnf-index: "1", internal-vld: [ {nam additionalParamsForVnf...}' ``` -As you can see, the parameters being defined at instantation time follow the information model structure. Further information and examples about these parameters can be reviewed [here](https://osm.etsi.org/wikipub/index.php/OSM_instantiation_parameters). +As you can see, the parameters being defined at instantiation time follow the information model structure. Further information and examples about these parameters can be reviewed [here](https://osm.etsi.org/wikipub/index.php/OSM_instantiation_parameters). diff --git a/04-day2.md b/04-day2.md index 588745b4fa5269e6c61f2500ea8fabc1cd474976..f261376e9f2505de2f74d6f13a5865162a8ccd08 100644 --- a/04-day2.md +++ b/04-day2.md @@ -2,11 +2,11 @@ ## Description of this phase -The objective of this section is to provide the guidelines for including all the necessary elements in the VNF Package so that it can be operated at runtime. Typical operations include reconfiguration of services, KPI monitoring and the enablement of automatic, closed-loop operations triggered by monitored status. +The objective of this section is to provide the guidelines for including all the necessary elements in the VNF Package so that it can be operated at runtime and therefore, reconfigured on demand at any point by the end-user. Typical operations include reconfiguration of services, KPI monitoring and the enablement of automatic, closed-loop operations triggered by monitored status. -The main mechanisms to achieve reconfiguration in OSM is to build a Proxy Charm and include it in the descriptor, while monitoring and VNF-specific policy management can be achieved by specifying the requirements at the descriptor (modifying monitored indicators and policies at runtime is not supported in OSM as of the present release) +The main mechanisms to achieve reconfiguration in OSM is to build a Proxy Charm and include it in the descriptor. On the other hand, monitoring and VNF-specific policy management can be achieved by specifying the requirements at the descriptor (modifying monitored indicators and policies at runtime is not supported in OSM as of version 5.0.5) -## Day 2 Onboarding Guidelines +## Day-2 Onboarding Guidelines ### Adding Day-2 primitives to the descriptor @@ -40,13 +40,13 @@ vnfd:vnfd-catalog: ### Building a Proxy Charm -Proxy Charms for implementing Day-2 primitives are built exactly in the same way as when implementing Day-1 primitives. +Proxy charms for implementing Day-2 primitives are built exactly in the same way as when implementing Day-1 primitives. ### Adding monitoring parameters #### Collecting NFVI metrics -In order to collect NFVI-level metrics associated to any given VDU and store them in the OSM TSDB (Prometheus), a set of `monitoring-params` should be declared globally and at the VDU level. +In order to collect NFVI-level metrics associated to any given VDU and store them in the OSM TSDB (using Prometheus software), a set of `monitoring-params` should be declared both globally and at the VDU level. Only CPU and Memory are supported as of OSM version 5.0.5. For example: @@ -84,14 +84,14 @@ vnfd:vnfd-catalog: #### Collecting VNF indicators -As of OSM version 5.0.5, collection of VNF Indicators is done by using Proxy Charms with the *metrics layer*. This is a simple method that has a couple of limitations: +As of OSM version 5.0.5, collection of VNF indicators is done by using Proxy Charms with the *metrics layer*. This is a simple method that has a couple of limitations: * Metrics are collected every five minutes and this can't be changed. * Only positive decimal values of *gauge* or *absolute* types can be collected. -At the charm level, the only file that needs to be created before building the it is the `metrics.yaml` file at the root folder of the charm. +At the charm level, the only file that needs to be created before building it is the "metrics.yaml" file at the root folder of the charm. -For example, the following file collects *active users* and *load* values from a Linux machine. +For example, the following file collects *active users* and *loads* values from a Linux machine. ```yaml # metrics.yaml file @@ -183,7 +183,7 @@ vnfd:vnfd-catalog: Scaling operations happen at a VDU level and can be added with automatic triggers (*closed-loop* mode triggered by *monitoring-param* thresholds), or with a manual trigger. -In both cases, a `scaling-group-descriptor` section must be added to the VNF descriptor. The following example enables VDU scaling based on a manual trigger (OSM API or CLI) +In both cases, a `scaling-group-descriptor` section must be added to the VNF descriptor. The following example enables VDU scaling based on a manual trigger (OSM API or CLI). ```yaml vnfd:vnfd-catalog: @@ -238,8 +238,8 @@ More information about scaling can be found in the [OSM Autoscaling documentatio Each of the objectives of this phase can be tested as follows: -* **Enabling a way of re-configuring the VNF on demand** - Primitives can be called through the OSM API, dashboard, or directly by running the following OSM client command: `osm ns-action [ns-name] --vnf_name [vnf-index] --action_name [primitive-name] --params '{param-name-1: "param-value-1", param-name-2: "param-value-2", ...}` +* **Enabling a way of re-configuring the VNF on demand**: primitives can be called through the OSM API, dashboard, or directly by running the following OSM client command: `osm ns-action [ns-name] --vnf_name [vnf-index] --action_name [primitive-name] --params '{param-name-1: "param-value-1", param-name-2: "param-value-2", ...}` -* **Monitor the main KPIs of the VNF** - If correctly enabled, metrics will automatically start appearing in the OSM Prometheus database. More information on how to access, visualize and troubleshoot metrics can be found in the [OSM Performance Management documentation](https://osm.etsi.org/wikipub/index.php/OSM_Performance_Management) +* **Monitor the main KPIs of the VNF**: if correctly enabled, metrics will automatically start appearing in the OSM Prometheus database. More information on how to access, visualize and troubleshoot metrics can be found in the [OSM Performance Management documentation](https://osm.etsi.org/wikipub/index.php/OSM_Performance_Management) -* **Enabling scaling operations** - automatic scaling should be tested by making the metric reach the corresponding threshold, while manual scaling can be tested by using the following command (which also works when the 'scaling-type' has been set to 'automatic'): `osm vnf-scale [ns-name] [vnf-name] --scaling-group [scaling-group name] [--scale-in|--scale-out]` +* **Enabling scaling operations**: automatic scaling should be tested by making the metric reach the corresponding threshold, while manual scaling can be tested by using the following command (which also works when the "scaling-type" has been set to "automatic"): `osm vnf-scale [ns-name] [vnf-name] --scaling-group [scaling-group name] [--scale-in|--scale-out]` diff --git a/05-knownissues.md b/05-knownissues.md index 3d83e85769079faf2846fb2f624f7a545e5fc6c7..57334ef5d987a470c8bc329f2b13fca4fa2da903 100644 --- a/05-knownissues.md +++ b/05-knownissues.md @@ -4,5 +4,5 @@ ### v5.0.5 -* Instantiation 'additional' parameters can't be passed with the config object through the dashboard. Being addressed by [this fix.](https://osm.etsi.org/gerrit/#/c/7357/) -* Cloud-init will not allow parameter names with hyphens due to Jinja2 (Python Identifiers) implementation, but the error is misleading. Being addressed through [this bug](https://osm.etsi.org/bugzilla/show_bug.cgi?id=667) \ No newline at end of file +* Instantiation "additional" parameters can't be passed with the config object through the dashboard. Being addressed by [this fix](https://osm.etsi.org/gerrit/#/c/7357/). +* Cloud-init will not allow parameter names with hyphens due to Jinja2 (Python Identifiers) implementation, but the error is misleading. Being addressed through [this bug](https://osm.etsi.org/bugzilla/show_bug.cgi?id=667).