SEBA-386 Update onos-service documentation
Change-Id: Ie12f62a5f117d615dbefde9168eb3b22113bc451
diff --git a/VERSION b/VERSION
index f1547e6..815e68d 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.0.7
+2.0.8
diff --git a/docs/README.md b/docs/README.md
index 8e82320..482b4d1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,108 +1,144 @@
# ONOS Service
-This service is intended to manage ONOSes.
+This service manages ONOS and apps contained within ONOS. Although at this time CORD typically uses only one deployment of ONOS on a pod, this service is capable of managing multiple deployments of ONOS.
-It can:
+The ONOS Service is responsible for:
-- push global configuration to ONOS
-- install applications
-- push application specific configuration
+- Pushing global configuration to ONOS.
+- Installing and activating applications.
+- Pushing application specific configuration.
+- Deactivating and uninstalling applications.
## Models
-This service is composed by two models:
+This service is comprised of two models:
-- `ONOSService` responsible to hold urls and authentication informations
-- `ONOSApp` represents and ONOS application and track its dependencies (this extend the `ServiceInstance` model)
+- `ONOSService`. Contains global service parameters. In addition to standard `Service` fields such as the `name` of the service, this model contains the following ONOS specific fields:
+ - `rest_hostname`. Hostname of ONOS rest API endpoint.
+ - `rest_port`. Port of ONOS rest endpoint.
+ - `rest_username`. Username to use when authenticating to ONOS.
+ - `rest_password`. Password to use when authenticating to ONOS.
+- `ONOSApp` represents an ONOS application and tracks its dependencies. This model extends the `ServiceInstance` model, adding the following fields:
+ - `app_id`. Application identifier.
+ - `dependencies`. Comma-separated list of apps that must be installed before this app.
+ - `url`. URL at which the application is available, if it needs to be downloaded.
+ - `version`. Version of the app.
-This service uses `ServiceAttributes` and `ServiceInstanceAttributes`
-to hold the configuration details.
+In addtion to the above models, this service uses `ServiceAttributes` and
+`ServiceInstanceAttributes` to hold additional configuration details for the
+ONOSService and ONOSApp models.
-For more informations about the models, please refer to the
+For more information about the models, please refer to the
[xproto](https://github.com/opencord/onos-service/blob/master/xos/synchronizer/models/onos.xproto) definition
### Example TOSCA
-This is an example TOSCA recipe you can use to install an application
-and add some configuration to it:
+The following TOSCA recipe is a subset of a recipe taken from the seba-services profile that configures ONOS services as for the 6.1 release of CORD. For the complete recipe, please see the SEBA profile.
-```yaml
-tosca_definitions_version: tosca_simple_yaml_1_0
+```tosca_definitions_version: tosca_simple_yaml_1_0
+
imports:
- - custom_types/onosapp.yaml
- - custom_types/onosservice.yaml
- - custom_types/serviceinstanceattribute.yaml
-description: Configures fabric switches and related ports
+ - custom_types/onosapp.yaml
+ - custom_types/onosservice.yaml
+ - custom_types/serviceinstanceattribute.yaml
+
+description: Configures the VOLTHA ONOS service
+
topology_template:
node_templates:
+
service#onos:
type: tosca.nodes.ONOSService
properties:
- name: onos
- must-exist: true
+ name: onos
+ kind: data
+ rest_hostname: "onos-ui.default.svc.cluster.local"
+ rest_port: 8181
-
- # Local app
- dhcp:
+ onos_app#olt:
type: tosca.nodes.ONOSApp
properties:
- name: dhcp
- app_id: org.onosproject.dhcp
+ name: olt
+ app_id: org.opencord.olt
+ url: https://oss.sonatype.org/service/local/repositories/releases/content/org/opencord/olt-app/2.1.0/olt-app-2.1.0.oar
+ version: 2.1.0
+ dependencies: org.opencord.sadis
requirements:
- owner:
node: service#onos
relationship: tosca.relationships.BelongsToOne
- # Remote app
- cord-config:
+ onos_app#sadis:
type: tosca.nodes.ONOSApp
properties:
- app_id: org.opencord.cord-config
- name: cord-config
- url: https://oss.sonatype.org/content/repositories/public/org/opencord/cord-config/1.4.0-SNAPSHOT/cord-config-1.4.0-20180604.071543-275.oar
- version: 1.4.0.SNAPSHOT
+ name: sadis
+ app_id: org.opencord.sadis
+ url: https://oss.sonatype.org/service/local/repositories/releases/content/org/opencord/sadis-app/2.2.0/sadis-app-2.2.0.oar
+ version: 2.2.0
requirements:
- owner:
node: service#onos
relationship: tosca.relationships.BelongsToOne
- # CORD-Configuration
- cord-config-attr:
+ olt-config-attr:
type: tosca.nodes.ServiceInstanceAttribute
properties:
- name: /onos/v1/network/configuration/apps/org.opencord.olt
+ name: /onos/v1/configuration/org.opencord.olt.impl.Olt?preset=true
value: >
{
- "kafka" : {
- "bootstrapServers" : "cord-kafka-kafka.default.svc.cluster.local:9092"
+ "enableDhcpOnProvisioning" : true
+ }
+ requirements:
+ - service_instance:
+ node: onos_app#olt
+ relationship: tosca.relationships.BelongsToOne
+
+ sadis-config-attr:
+ type: tosca.nodes.ServiceInstanceAttribute
+ properties:
+ name: /onos/v1/network/configuration/apps/org.opencord.sadis
+ value: >
+ {
+ "sadis" : {
+ "integration" : {
+ "cache" : {
+ "maxsize" : 1000,
+ "ttl": "PT300S"
+ },
+ "url" : "http://sadis-service:8000/subscriber/%s"
+ }
}
}
requirements:
- service_instance:
- node: cord-config
+ node: onos_app#sadis
relationship: tosca.relationships.BelongsToOne
```
+## Integration with other Services
+
+The ONOS service is a dependency of many other services, including the Fabric and Fabric-crosconnect services. The ONOS service often is responsible for bringing up and configuring apps that these other services use.
+
## Synchronization workflow
### ONOSService
-Anytime an `ONOSService` model is created/updated, the synchronizer checks
-for the corresponding `ServiceAttribute`s and if any are found it pushes the configuration
-to ONOS
+Any time an `ONOSService` model is created/updated, the synchronizer checks
+for the corresponding `ServiceAttributes` and if any are found it pushes the configuration to ONOS.
### ONOSServiceInstance
-Anytime an `ONOSServiceInstance` model is created/updated, the synchronizer checks
-for the corresponding `ServiceInstanceAttribute`s and if any are found:
+Any time an `ONOSServiceInstance` model is created/updated, the synchronizer checks
+for the corresponding `ServiceInstanceAttributes` and if any are found:
- checks for the application dependencies
-- if they are not matched defer the synchronization
+- if they are not matched
+ - defer the synchronization
- if they are matched
-- it pushes the configuration to ONOS
-- it installs/activates the application in ONOS
+ - it pushes the configuration to ONOS
+ - it installs/activates the application in ONOS
-> ONOS Applications can be activated (if they already present in the container),
-> in that case you just need to provide the `app_id`, or they can be installed from a remote `.oar`,
-> in which case you need to also provide an `url` and a `version`
-
\ No newline at end of file
+> ONOS Applications can be activated if they already present in the container
+> by providing the `app_id`. If an application is not already present in the
+> container then it can be installed from a remote `.oar`,
+> in which case it is necessary to also provide an `url` and a `version`