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
  48 ```
  49
  50 ## Charms
  51
  52 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.
  53
  54 The folder structure for each charm looks like this:
  55
  56 ```txt
  57 <charm>-k8s/
  58 ├── config.yaml
  59 ├── icon.svg
  60 ├── layer.yaml
  61 ├── metadata.yaml
  62 ├── reactive
  63 │   ├── <charm>.py
  64 │   └── spec_template.yaml
  65 ├── README.md
  66 ├── .gitignore
  67 ├── .yamllint.yaml
  68 └── tox.ini
  69 ```
  70
  71 Purpose of each file:
  72
  73 - **config.yaml**: YAML file that include all the configurable options for the charm.
  74 - **icon.svg**: SVG icon. This is the icon that will appear in the Charm Store.
  75 - **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.
  76 - **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.
  77 - **reactive/\<charm>.py**: Python file that implements the actual logic to the charm.
  78 - **reactive/spec_template.yaml**: Pod spec template to be used by the pods.
  79 - **README.md**: This file describes how to build the charm, how to prepare the environment to test it with Microk8s.
  80 - **.gitignore**: Typical Git Ignore file, to avoid pushing unwanted files to upstream.
  81 - **.yamllint.yaml**: YAML file to specify the files to exclude from the yamllint test that tox.ini does.
  82 - **tox.ini**: Includes basic functions to build the charms, and check the linting.
  83
  84 ## Interfaces
  85
  86 Each interface needs at least three files:
  87
  88 - **interface.yaml:** Metadata of the interface: name, maintainer, and summary.
  89 - **provides.py:** Code for the charm that provides the interface.
  90 - **requires.py:** Code for the charm that requires the interface.
  91
  92 Additionally, there are also files for copyright and a README that explains how to use the interface.
  93
  94 # Steps for testing
  95
  96 ## Dependencies
  97
  98 ```bash
  99 sudo apt install tox -y
 100 ```
 101
 102 ## Check the syntax of the charms
 103
 104 ```bash
 105 ./lint.sh
 106 ```
 107
 108 ## Build all the charms
 109
 110 ```bash
 111 ./build.sh
 112 ```
 113
 114 ## Generate bundle
 115
 116 ```bash
 117 # Generate bundle from built charms
 118 python3 generate_bundle.py --local --destination osm.yaml
 119 # Help
 120 python3 generate_bundle.py --help
 121 ```
 122
 123 ## Install VCA
 124
 125 ```bash
 126 sudo snap install juju --classic
 127 juju bootstrap localhost osm-lxd
 128 ```
 129
 130 ## Generate overlay
 131
 132 > NOTE: This will be removed once the installer is merged.
 133
 134 ```bash
 135 sudo snap install osmclient
 136 sudo snap alias osmclient.osm osm
 137 sudo snap connect osmclient:juju-client-observe
 138 sudo snap connect osmclient:ssh-public-keys
 139 sudo snap connect osmclient:network-control
 140 osmclient.overlay  # Execute the commands printed by this command to enable native charms
 141 ```
 142
 143 ## Bootstrap Juju controller in Microk8s
 144
 145 ```bash
 146 sudo snap install microk8s --classic
 147 sudo usermod -a -G microk8s ubuntu
 148 sudo chown -f -R ubuntu ~/.kube
 149 newgrp microk8s
 150 microk8s.status --wait-ready
 151 microk8s.enable storage dns  # (metallb) is optional
 152 juju bootstrap microk8s osm-k8s
 153 ```
 154
 155 ## Deploy OSM with charms
 156
 157 ```bash
 158 juju add-model osm
 159 juju deploy ./osm.yaml --overlay vca-overlay.yaml
 160 ```
 161
 162 ## Wait until Charms are deployed
 163
 164 ```bash
 165 watch -c juju status --color  # Wait until every application is in active state
 166 export OSM_HOSTNAME=<ip-nbi>
 167 osm ns-list
 168 # ...
 169 ```