installers/charm/README.md

   1 <!--
   2  Copyright 2020 Canonical Ltd.
   3
   4  Licensed under the Apache License, Version 2.0 (the "License");
   5  you may not use this file except in compliance with the License.
   6  You may obtain a copy of the License at
   7
   8      http://www.apache.org/licenses/LICENSE-2.0
   9
  10  Unless required by applicable law or agreed to in writing, software
  11  distributed under the License is distributed on an "AS IS" BASIS,
  12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  See the License for the specific language governing permissions and
  14  limitations under the License.
  15 -->
  16
  17 # OSM Charms and interfaces
  18
  19 **Description**: This document describes the high-level view of the OSM Charms and interfaces. An important note is that these charms Kubernetes Charms, so they must be deployed on top of a Kubernetes Cloud using Juju.
  20
  21 ## Folder tree
  22
  23 In the current directory, there is one folder "interfaces" that has all the interfaces of the OSM components, which are basically two: osm-nbi, and osm-ro.
  24
  25 Additionally, we can see six folders that contain each OSM core components: lcm-k8s, mon-k8s, nbi-k8s, pol-k8s, ro-k8s, and ui-k8s.
  26
  27 Then, we can see a folder "bundle" which has the templates for the OSM bundles in single instance and HA.
  28
  29 The "layers" folder include one common layer for all the osm charms (osm-common)
  30
  31 ```txt
  32
  33 ├── bundles
  34 │   ├── osm
  35 │   └── osm-ha
  36 ├── interfaces
  37 │   ├── osm-nbi
  38 │   └── osm-ro
  39 ├── layers
  40 │   └── osm-common
  41 ├── lcm-k8s
  42 ├── mon-k8s
  43 ├── nbi-k8s
  44 ├── pol-k8s
  45 ├── ro-k8s
  46 ├── ui-k8s
  47 └── ng-ui --> new operator framework
  48
  49 ```
  50
  51 ## Charms
  52
  53 All the charms have a very similar structure. This subsection explains the purpose of each file inside the charms, as well as basic steps to get started.
  54
  55 The folder structure for each charm looks like this:
  56
  57 ```txt
  58 <charm>-k8s/
  59 ├── config.yaml
  60 ├── icon.svg
  61 ├── layer.yaml
  62 ├── metadata.yaml
  63 ├── reactive
  64 │   ├── <charm>.py
  65 │   └── spec_template.yaml
  66 ├── README.md
  67 ├── .gitignore
  68 ├── .yamllint.yaml
  69 └── tox.ini
  70 ```
  71
  72 Purpose of each file:
  73
  74 - **config.yaml**: YAML file that include all the configurable options for the charm.
  75 - **icon.svg**: SVG icon. This is the icon that will appear in the Charm Store.
  76 - **layer.yaml**: YAML file with the layers that the charm needs. All the OSM Charms need at least the following layers: caas-base, status, leadership, and osm-common. If charms provide or require interfaces, which all of them do, those interfaces should be specified in this file too.
  77 - **metadata.yaml**: YAML file that describe the top level information of the charm: name, description, series, interfaces that provide/require, needed storage, and deployment type.
  78 - **reactive/\<charm>.py**: Python file that implements the actual logic to the charm.
  79 - **reactive/spec_template.yaml**: Pod spec template to be used by the pods.
  80 - **README.md**: This file describes how to build the charm, how to prepare the environment to test it with Microk8s.
  81 - **.gitignore**: Typical Git Ignore file, to avoid pushing unwanted files to upstream.
  82 - **.yamllint.yaml**: YAML file to specify the files to exclude from the yamllint test that tox.ini does.
  83 - **tox.ini**: Includes basic functions to build the charms, and check the linting.
  84
  85 ## Interfaces
  86
  87 Each interface needs at least three files:
  88
  89 - **interface.yaml:** Metadata of the interface: name, maintainer, and summary.
  90 - **provides.py:** Code for the charm that provides the interface.
  91 - **requires.py:** Code for the charm that requires the interface.
  92
  93 Additionally, there are also files for copyright and a README that explains how to use the interface.
  94
  95 # Steps for testing
  96
  97 ## Dependencies
  98
  99 ```bash
 100 sudo apt install tox -y
 101 ```
 102
 103 ## Check the syntax of the charms
 104
 105 ```bash
 106 ./lint.sh
 107 ```
 108
 109 ## Build all the charms
 110
 111 ```bash
 112 ./build.sh
 113 ```
 114
 115 ## Generate bundle
 116
 117 ```bash
 118 # Generate bundle from built charms
 119 python3 generate_bundle.py --local --destination osm.yaml
 120 # Help
 121 python3 generate_bundle.py --help
 122 ```
 123
 124 ## Install VCA
 125
 126 ```bash
 127 sudo snap install juju --classic
 128 juju bootstrap localhost osm-lxd
 129 ```
 130
 131 ## Generate overlay
 132
 133 > NOTE: This will be removed once the installer is merged.
 134
 135 ```bash
 136 sudo snap install osmclient
 137 sudo snap alias osmclient.osm osm
 138 sudo snap connect osmclient:juju-client-observe
 139 sudo snap connect osmclient:ssh-public-keys
 140 sudo snap connect osmclient:network-control
 141 osmclient.overlay  # Execute the commands printed by this command to enable native charms
 142 ```
 143
 144 ## Bootstrap Juju controller in Microk8s
 145
 146 ```bash
 147 sudo snap install microk8s --classic
 148 sudo usermod -a -G microk8s ubuntu
 149 sudo chown -f -R ubuntu ~/.kube
 150 newgrp microk8s
 151 microk8s.status --wait-ready
 152 microk8s.enable storage dns  # (metallb) is optional
 153 juju bootstrap microk8s osm-k8s
 154 ```
 155
 156 ## Deploy OSM with charms
 157
 158 ```bash
 159 juju add-model osm
 160 juju deploy ./osm.yaml --overlay vca-overlay.yaml
 161 ```
 162
 163 ## Wait until Charms are deployed
 164
 165 ```bash
 166 watch -c juju status --color  # Wait until every application is in active state
 167 export OSM_HOSTNAME=<ip-nbi>
 168 osm ns-list
 169 # ...
 170 ```