From c75c46bfa1f9f26646b0de88d08647911d872620 Mon Sep 17 00:00:00 2001 From: garciadeblas Date: Mon, 31 May 2021 00:01:20 +0200 Subject: [PATCH] Add openldap CNF quickstart Signed-off-by: garciadeblas --- 05-quickstarts.md | 194 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 192 insertions(+), 2 deletions(-) diff --git a/05-quickstarts.md b/05-quickstarts.md index 0490d75..19bb5e2 100644 --- a/05-quickstarts.md +++ b/05-quickstarts.md @@ -3,8 +3,9 @@ This sections uses some of the [OSM Community examples](https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages) to provide quick examples of onboarding and instantiation. 1. [Single VDU Linux with simple action through Proxy Charm](#single-vdu-linux-machine-with-simple-action-through-proxy-charm) -1. [Single VDU Router with Ansible](#single-vdu-router-with-snmp-metrics-and-ansible-playbook) -1. [Single VDU Virtual Desktop with Native Charms](#single-vdu-virtual-desktop-with-native-charms) +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) ## Single VDU Linux machine with simple action through Proxy Charm @@ -365,3 +366,192 @@ Some common customizations that make this package easily reusable are: - Modify the software installed by default - Modify the use of an Apt cache that is set up during the day 1 action - Add actions to add/remove users, or change passwords + +## OpenLDAP CNF modeled with Helm Charts + +This example implements a CNF with an openldap helm chart from stable helm chart repository. + +### About the openldap helm chart + +* LDAP server is slapd from . It follows [OpenLDAP Public License](https://openldap.org/software/release/license.html) +* The LDAP helm chart can be found in [Artifact Hub](https://artifacthub.io/packages/helm/geek-cookbook/openldap) and it is available via the [stable helm chart repo](https://charts.helm.sh/stable). +* The helm chart uses this [docker image](https://github.com/osixia/docker-openldap), which follows MIT license. + +### 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 + +First, explore the folder `openldap_knf`, in particular, the file `openldap_vnfd.yaml`. This is the CNF descriptor, which models a single KDU (Kubernetes Deployment Unit) with the specified helm chart (`stable/openldap` here), a single connection point (`mgmt-ext`) where all Kubernetes services of this helm-chart will be exposed, and certain k8s-cluster requirements (in this case, it must have at least one network to expose services). + +In most of the cases, adapting your package would be as simple as changing the helm chart. where all the Kubernetes services of this helm chart will be exposed). + +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. + +By default, it is assumed that the helm version for the helm charts is `v3`. If the helm chart is based on `v2`, the descriptor should add the line `helm-version: v2` in the kdu section. + +#### 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 openldap_knf + +# Then, upload the NS package that refers to the VNF package +osm nspkg-create openldap_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, with a Load Balancer and a default storage class. Details about the requirements can be found [here](https://osm.etsi.org/docs/user-guide/05-osm-usage.html#osm-kubernetes-requirements). + +#### 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 ldap --nsd_name openldap_ns --vim_account vim-name --config "{vld: [{name: mgmtnet, vim-network-name: osm-ext}]}" +``` + +##### Particularize your instantiation parameters + +You can use your own instantiation parameters for the KDU, for instance to specific IP address of the Kubernetes Load Balancer, or to initialize the LDAP server with an organization, domain and admin password. KDU params must be placed under `additionalParamsForVnf:[VNF_INDEX]:additionalParamsForKdu:[KDU_INDEX]:additionalParams` and they follow the structure defined in the helm chart values file `values.yaml`. + +``` +vld: +- name: mgmtnet + vim-network-name: osm-ext +additionalParamsForVnf: +- member-vnf-index: openldap + additionalParamsForKdu: + - kdu_name: ldap + additionalParams: + service: + type: LoadBalancer + loadBalancerIP: '172.21.248.204' # Load Balancer IP Address + adminPassword: osm4u + configPassword: osm4u + env: + LDAP_ORGANISATION: "Example Inc." + LDAP_DOMAIN: "example.org" + LDAP_BACKEND: "hdb" + LDAP_TLS: "true" + LDAP_TLS_ENFORCE: "false" + LDAP_REMOVE_CONFIG_AFTER_SETUP: "true" +``` + +#### 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 ldap`) and getting the status using the command `osm vnf-show VNF-ID --kdu ldap` +- The status of the KDU using kubectl. First get the OSM project ID (`osm project-list`), then use kubectl to get details from the namespace identified by OSM project ID, as follows: `kubectl -n OSM_PROJECT_ID get all`. +- The status of the KDU using helm. First get the OSM project ID (`osm project-list`), then use helm to get the helm release with `helm --kubeconfig kubeconfig.yaml -n OSM_PROJECT_ID`, then use helm to get the helm release with `helm --kubeconfig kubeconfig.yaml -n OSM_PROJECT_ID`. +- Access to openldap server: `ldapsearch -x -H :389 -b dc=example,dc=org -D "cn=admin,dc=example,dc=org" -w $LDAP_ADMIN_PASSWORD` + +### Possible quick customizations + +Some common customizations that make this package easily reusable are: + +- Modify the KDU's helm-chart to use: + - a different helm chart repo: `REPO_NAME/HELM_CHART` + - a specific version of a helm chart: `REPO_NAME/HELM_CHART:VERSION` + - a helm chart file `mychart.tgz`, which has to be placed in `VNF_PACKAGE_FOLDER/charts/mychart.tgz` +- Use different instantiation parameters, derived from the helm values file `values.yaml` + +#### Using a helm chart from a different repo + +If your helm chart is on a repo different from the stable repo, you can add it to OSM as follows: + +``` +osm repo-add --type helm-chart --description "Bitnami repo" bitnami https://charts.bitnami.com/bitnami +osm repo-add --type helm-chart --description "Cetic repo" cetic https://cetic.github.io/helm-charts +osm repo-add --type helm-chart --description "Elastic repo" elastic https://helm.elastic.co +osm repo-list +osm repo-show bitnami +``` + +Descriptors can include that reference as follows: + +``` +helm-chart: REPO_NAME/HELM_CHART +``` + +#### Using a specific version of a helm chart + +Descriptors can point to a specific version of a helm chart as follows: + +``` +helm-chart: REPO_NAME/HELM_CHART:VERSION +``` + +#### Using a helm chart file + +Sometimes it could be useful to use the tar.gz file. You could even fetch a helm chart from the repo and use it directly, or after modifying it. + +You need to [install helm client](https://helm.sh/docs/intro/install/). Then, you can use helm client to search and download charts. + +``` +helm repo add [NAME] [URL] [flags] +helm search repo [KEYWORD] +helm fetch [REPO_NAME/HELM_CHART] +helm repo add stable https://charts.helm.sh/stable +helm search repo openldap +helm fetch stable/openldap +helm fetch stable/openldap --version 1.2.6 +``` + +You could even modify a downloaded helm chart, for instance to add new parameters (called values). This [guide](https://helm.sh/docs/chart_template_guide/getting_started/) will help you. + +#### Using different instantiation parameters, derived from the helm values file + +The allowed instantiation parameters for a KDU comes from the helm values file `values.yaml` of a helm chart. You could get the default values, as well as other chart information, as follows: + +``` +helm show chart stable/openldap +helm show readme stable/openldap +helm show values stable/openldap +``` + +When instantiating with OSM, all you need to do is place those params under `additionalParamsForVnf:[VNF_INDEX]:additionalParamsForKdu:[KDU_INDEX]:additionalParams`, with the right indentation. -- GitLab