--- /dev/null
+<!--
+ Copyright 2020 Canonical Ltd.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# OSM Charms and interfaces
+
+**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.
+
+## Folder tree
+
+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.
+
+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.
+
+Then, we can see a folder "bundle" which has the templates for the OSM bundles in single instance and HA.
+
+The "layers" folder include one common layer for all the osm charms (osm-common)
+
+```txt
+
+├── bundles
+│ ├── osm
+│ └── osm-ha
+├── interfaces
+│ ├── osm-nbi
+│ └── osm-ro
+├── layers
+│ └── osm-common
+├── lcm-k8s
+├── mon-k8s
+├── nbi-k8s
+├── pol-k8s
+├── ro-k8s
+└── ui-k8s
+
+```
+
+## Charms
+
+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.
+
+The folder structure for each charm looks like this:
+
+```txt
+<charm>-k8s/
+├── config.yaml
+├── icon.svg
+├── layer.yaml
+├── metadata.yaml
+├── reactive
+│ ├── <charm>.py
+│ └── spec_template.yaml
+├── README.md
+├── .gitignore
+├── .yamllint.yaml
+└── tox.ini
+```
+
+Purpose of each file:
+
+- **config.yaml**: YAML file that include all the configurable options for the charm.
+- **icon.svg**: SVG icon. This is the icon that will appear in the Charm Store.
+- **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.
+- **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.
+- **reactive/\<charm>.py**: Python file that implements the actual logic to the charm.
+- **reactive/spec_template.yaml**: Pod spec template to be used by the pods.
+- **README.md**: This file describes how to build the charm, how to prepare the environment to test it with Microk8s.
+- **.gitignore**: Typical Git Ignore file, to avoid pushing unwanted files to upstream.
+- **.yamllint.yaml**: YAML file to specify the files to exclude from the yamllint test that tox.ini does.
+- **tox.ini**: Includes basic functions to build the charms, and check the linting.
+
+## Interfaces
+
+Each interface needs at least three files:
+
+- **interface.yaml:** Metadata of the interface: name, maintainer, and summary.
+- **provides.py:** Code for the charm that provides the interface.
+- **requires.py:** Code for the charm that requires the interface.
+
+Additionally, there are also files for copyright and a README that explains how to use the interface.
+
+# Steps for testing
+
+## Dependencies
+
+```bash
+sudo apt install tox -y
+```
+
+## Check the syntax of the charms
+
+```bash
+./lint.sh
+```
+
+## Build all the charms
+
+```bash
+./build.sh
+```
+
+## Generate bundle
+
+```bash
+# Generate bundle from built charms
+python3 generate_bundle.py --local --destination osm.yaml
+# Help
+python3 generate_bundle.py --help
+```
+
+## Install VCA
+
+```bash
+sudo snap install juju --classic
+juju bootstrap localhost osm-lxd
+```
+
+## Generate overlay
+
+> NOTE: This will be removed once the installer is merged.
+
+```bash
+sudo snap install osmclient
+sudo snap alias osmclient.osm osm
+sudo snap connect osmclient:juju-client-observe
+sudo snap connect osmclient:ssh-public-keys
+sudo snap connect osmclient:network-control
+osmclient.overlay # Execute the commands printed by this command to enable native charms
+```
+
+## Bootstrap Juju controller in Microk8s
+
+```bash
+sudo snap install microk8s --classic
+sudo usermod -a -G microk8s ubuntu
+sudo chown -f -R ubuntu ~/.kube
+newgrp microk8s
+microk8s.status --wait-ready
+microk8s.enable storage dns # (metallb) is optional
+juju bootstrap microk8s osm-k8s
+```
+
+## Deploy OSM with charms
+
+```bash
+juju add-model osm
+juju deploy ./osm.yaml --overlay vca-overlay.yaml
+```
+
+## Wait until Charms are deployed
+
+```bash
+watch -c juju status --color # Wait until every application is in active state
+export OSM_HOSTNAME=<ip-nbi>
+osm ns-list
+# ...
+```
projects / osm / devops.git / blobdiff