From 449ec0fa51fa2560e332eed6bd8c3e773cf44070 Mon Sep 17 00:00:00 2001 From: David Garcia Date: Fri, 11 Jun 2021 13:15:09 +0000 Subject: [PATCH] Add distributed VCA documentation (cherry picked from commit 54d52a9eedc168bbd2030fea64069d708a2ffbdd) --- 04-vim-setup.md | 4 +- 06-osm-platform-configuration.md | 224 +++++++++++++++---------------- 2 files changed, 109 insertions(+), 119 deletions(-) diff --git a/04-vim-setup.md b/04-vim-setup.md index 151bea6..37a6d12 100644 --- a/04-vim-setup.md +++ b/04-vim-setup.md @@ -1041,6 +1041,6 @@ The previous configuration has taken as a reference the documents in the links b - -## Distributed Proxy Charms +## Distributed VCA -You can configure the VIM to, instead of using the default lxd and k8s clouds, use clouds hosted in that specific VIM. **[This section](06-osm-platform-configuration.md#Distributed-Proxy-Charms)** explains the details on how to set everything up. +You can configure the VIM to use a Distributed VCA instead of using the default one. **[This section](06-osm-platform-configuration.html#distributed-vca)** explains the details on how to set everything up. diff --git a/06-osm-platform-configuration.md b/06-osm-platform-configuration.md index e7fe284..69968be 100644 --- a/06-osm-platform-configuration.md +++ b/06-osm-platform-configuration.md @@ -686,161 +686,151 @@ To **show packages details** available in the repository it is posible use the f ``` -## Distributed Proxy Charms -Charms allow OSM to deploy network services with VNF/KNFs that can be configured, integrated, and operated with day-1 and day-2 actions. Charm is software that drives software, and that follows what in the Kubernetes world is known as the _operator pattern_. The VCA (Juju controller) is responsible for deploying, configuring, integrating, and executing actions in the Charms. +## Distributed VCA -Particularly, Proxy charms provide capabilities to add all these benefits to workloads that are “fixed” (i.e. PNFs, VNFs that come with a custom image, and software cannot be installed there, etc). In this case, the Charm/operator lives in a container different from the workload. +The VCA is the component in OSM in charge of the life cycle of charms, which are operators that allow integration, configuration, day-1 and day-2 operation of Network Functions. This OSM release offers the capability to register VCAs to projects, and associate VIM accounts to specific VCAs, allowing the VCA to be distributed and located in the same datacenter as the VIM. -Currently, OSM supports two types of Proxy Charms: LXD and Kubernetes charms. With any of the Kubernetes-based installations (charmed or k8s), two clouds will be automatically added to the VCA, which will be afterwards used to deploy LXD and K8s Proxy charms. By default, these clouds are installed in the same machine as OSM, but they can be configured to be external: +A VCA is a Juju controller which has at least two clouds associated: k8s and lxd. This means that it will be capable of deploying and managing charms in both Kubernetes and LXD. +### How to deploy a VCA + +This subsection explains how to deploy a VCA in one machine. This is not recommended for production, just for testing and validation. Additionally, the IP of the machine in which the VCA will be installed, must be reachable by the OSM cluster. ```bash -$ juju clouds --controller osm-vca -Clouds available on the controller: -Cloud Regions Default Type -lxd-cloud 1 default lxd -microk8s 1 localhost k8s +./install_osm.sh --charmed --only-vca ``` -By default, all LXD Proxy charms will be deployed to the lxd cloud, and all the K8s Proxy charms to the k8s cloud. That behavior can be changed by adding additional clouds to the VCA, and referencing them in the vim account. - -### Add clouds to the VCA +This script will install Microk8s and LXD, bootstrap the Juju controller to Microk8s, and add the LXD cloud to the controller. That way the Juju controller will be able to deploy charms to both Kubernetes and LXD. -Adding clouds to the VCA is a very straightforward process, but the commands are slightly different depending on the target cloud type. +When the installation has finished, the script will print out at the end the command that should be executed in the OSM client in order to register it to OSM. Something similar to this: -#### k8s -To add a Kubernetes cloud to Juju, we only need the kubeconfig file of the Kubernetes cluster that we will be adding. +``` +Use the following command to register the installed VCA to your OSM: -```bash -$ cat kubeconfig.yaml | juju add-k8s --controller + osm vca-add --endpoints 10.37.45.21:17070 \ + --user admin \ + --secret 15c775fa78da526f45e8aef34239dcf4 \ + --cacert LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk... \ + --lxd-cloud lxd-cloud \ + --lxd-credentials lxd-cloud \ + --k8s-cloud microk8s \ + --k8s-credentials microk8s\ + angelic-iguanodon-vca ``` -Where: -- `juju add-k8s` command takes the kubeconfig from stdin. -- ``: Name of the controller to which this cloud will be added to. -- ``: The cloud name that will be assigned to the cloud. By default, the credential name will be the same as the cloud name. Underscores (“_”) or names starting with numbers (“1-9”) are not valid. +### Managing VCAs -Example: +There are a few commands that will allow us to manage VCAs in OSM: -``` bash -$ cat kubeconfig.yaml | juju add-k8s --controller osm-vca my-k8s-cloud -``` +- osm vca-add +- osm vca-edit +- osm vca-list +- osm vca-show +- osm vca-delete + +The vca-add, vca-edit, and vca-delete commands can only be executed by users in a project with system-admin or project-admin roles. -#### lxd +#### Add -To add a LXD cloud to Juju we just need to execute the following commands: +The osm vca-add command allows registering a VCA to OSM. The following options will be needed to perform the operation: + +- --endpoints TEXT: Comma-separated list of IP or hostnames of the Juju controller +- --user TEXT: Username in the Juju controller with admin privileges +- --secret TEXT: Password of the specified username +- --cacert TEXT: Base64 encoded CA certificate +- --lxd-cloud TEXT: Name of the cloud registered in Juju that will be used for LXD containers (LXD proxy charms) +- --lxd-credentials TEXT: Name of the cloud credentials registered in Juju to be used for the LXD cloud +- --k8s-cloud TEXT: Name of the cloud registered in Juju that will be used for K8s containers (K8s proxy charms) +- --k8s-credentials TEXT Name of the cloud credentials registered in Juju to be used for the K8s cloud +- --model-config TEXT: Configuration options for the Juju models. Both JSON and YAML files are accepted, or inline JSON. For the list of items that can be specified, please see [this](https://discourse.charmhub.io/t/configuring-models). +- --description TEXT: human readable description + +Example: ```bash -$ juju add-cloud --controller --force -$ juju add-credential --controller -f +osm vca-add --endpoints 172.21.248.164:17070 \ + --user admin \ + --secret e7b253af37785045d1ca08b8d929e556 \ + --cacert LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t... \ + --lxd-cloud lxd-cloud \ + --lxd-credentials lxd-cloud \ + --k8s-cloud microk8s \ + --k8s-credentials microk8s \ + vca ``` -Where: -- ``: Name of the controller to which this cloud will be added to. -- ``: The cloud name that will be assigned to the cloud. By default, the credential name will be the same as the cloud name. Underscores (“_”) or names starting with numbers (“1-9”) are not valid. -- `` and ``: Path to the cloud and credentials files. The following subsections explain how to build these files. +#### Edit -##### Cloud file +The osm vca-edit command allows editing an VCA in OSM. It accepts the same options as the osm vca-add command, but all of them are optional; only the specified values in this operation will be overridden. -```yaml -clouds: - : - type: lxd - auth-types: [certificate] - endpoint: "https://:8443" - config: - ssl-hostname-verification: false +#### List + +The osm vca-list command allows to list the registered VCAs in the current project. + +```bash +$ osm vca-list ++------+--------------------------------------+-------------------+ +| Name | Id | Operational State | ++------+--------------------------------------+-------------------+ +| vca | 2ade7f0e-9b58-4dbd-93a3-4ec076185d39 | ENABLED | ++------+--------------------------------------+-------------------+ ``` -- ``: Name of the cloud that will be specified in the `juju add-cloud` command. Underscores are not valid. -- ``: The endpoint of the LXD cloud, is the URL needed to reach the LXD Nodes. For more information, [go here](https://osm.etsi.org/docs/user-guide/16-lxd-cluster.html), and search for “What IP address or DNS name should be used to reach this node?”. +#### Show -##### Credentials file +The osm vca-show command allows to show the details of a registered VCA. -```yaml -credentials: - : - : - auth-type: certificate - server-cert: | - - client-cert: | - - client-key: | - -``` - -- ``: Name of the cloud that will be specified in the `juju add-cloud` command. -- ``: Name of the credentials for the cloud. No underscores or names starting with numbers are valid. -- ``: Obtaining the server certificate is as easy as executing the following command in an LXD Node: `$ cat /var/snap/lxd/common/lxd/server.crt` -- `` and ``: The client key and certificate will be used by Juju, to contact the LXD cloud endpoint. Can be generated with the following command: `$ openssl req -nodes -new -x509 -keyout client.key -out client.crt -days 365 -subj "/C=FR/ST=Nice/L=Nice/O=ETSI/OU=OSM/CN=osm.etsi.org"`. It is important to trust the certificate in the LXD node: `$ lxc config trust add local: client.crt` +```bash +$ osm vca-show vca ++------------+-------------------------------------------------------+ +| key | attribute | ++------------+-------------------------------------------------------+ +| _id | "2ade7f0e-9b58-4dbd-93a3-4ec076185d39" | +| name | "vca" | +| endpoints | [ "172.21.248.164:17070" ] | +| ... | ... | ++------------+-------------------------------------------------------+ +``` -Example: +#### Delete -`cloud.yaml` +The osm vca-delete command allows deleting a registered VCA. -```yaml -clouds: - my-lxd-cloud: - type: lxd - auth-types: [certificate] - endpoint: "https://172.21.248.56:8443" - config: - ssl-hostname-verification: false +```bash +$ osm vca-delete vca ``` -`credentials.yaml` +### Associate a VCA with a VIM account -```yaml -credentials: - my-lxd-cloud: - my-lxd-cloud-credentials: - auth-type: certificate - server-cert: | - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- - client-cert: | - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- - client-key: | - -----BEGIN PRIVATE KEY----- - ... - -----END PRIVATE KEY----- -``` +As it was previously mentioned, adding VCAs to OSM is a privilege operation, and only system-admins and project-admins can do that. But then, regular users are able to list the VCAs that are available to them in their projects. Therefore a regular user will be able to add a VIM account, and select, from the list of VCAs available, which one it wants to use. + +To do that, the osm vim-create command allows an optional parameter --vca \ ```bash -$ juju add-cloud --controller osm-vca my-lxd-cloud cloud.yaml --force -$ juju add-credential --controller osm-vca my-lxd-cloud-f credentials.yaml +$ osm vca-list ++------+--------------------------------------+-------------------+ +| Name | Id | Operational State | ++------+--------------------------------------+-------------------+ +| vca | 2ade7f0e-9b58-4dbd-93a3-4ec076185d39 | ENABLED | ++------+--------------------------------------+-------------------+ + +$ osm vim-create --name openstack \ + --user *** \ + --password *** \ + --auth_url http://***:5000/v3 \ + --tenant *** \ + --account_type openstack \ + --vca 2ade7f0e-9b58-4dbd-93a3-4ec076185d39 ``` -### Select clouds for vim account +### Associate a VCA with a K8s cluster -Now that we know how to add LXD and K8s clouds to Juju, we only need to associate specific clouds with the vim account, so all the Proxy charms of the network functions targeting that vim will be deployed in the clouds we select. +To associate the K8s cluster with a Distributed VCA, follow these steps: -Technically, it is possible to add the configuration for only one of the clouds, and the other one will point to the default. +1. Deploy a VCA and register it to OSM. For more details, see [this](#how-to-deploy-a-vca) section. +2. Associate the VCA with a VIM account. For more details, see [this](#associate-a-vca-with-a-vim-account) section. +3. Register your K8s cluster associating it to the VIM account added in step 2. For more details, see [this](#management-of-k8s-clusters) section. -```bash -$ osm vim-create --name \ - --user "$OS_USERNAME" \ - --password "$OS_PASSWORD" \ - --auth_url "$OS_AUTH_URL/v3" \ - --tenant "$OS_USERNAME" \ - --account_type openstack \ - --config='{ - vca_cloud: my-lxd-cloud, - vca_cloud_credential: my-lxd-cloud-credentials, - vca_k8s_cloud: my-k8s-cloud, - vca_k8s_cloud_credential: my-k8s-cloud-credential, - }' -``` - -The important thing to explain are the four parameters in the configuration of the vim account: - -- vca_cloud: Name of the cloud for LXD Proxy charms -- vca_cloud_credential: Name of the cloud credentials for LXD Proxy charms -- vca_k8s_cloud: Name of the cloud for K8s Proxy charms -- vca_k8s_cloud_credential: Name of the cloud credentials for K8s Proxy charms + Note: if you are not using an actual VIM, in the step 2, set the VIM account type to `dummy` with the following flag: `--account_type dummy`. \ No newline at end of file -- GitLab