SEBA-702 Remove watchers from arch document;
update xosgenx docs;
expunge Openstack and ExmapleService from SUMMARY
Change-Id: Ia626a471247fc7582b7952751d1fe8cefb9eb39f
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 0bd0311..98f3ecf 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -22,9 +22,6 @@
* [XOS Shell (xossh)](dev/xossh.md)
* [Platform Services](platform.md)
* [Kubernetes](kubernetes/kubernetes-service.md)
- * [OpenStack](openstack/openstack-service.md)
* [ONOS](onos/README.md)
* [Example Services](examples.md)
* [Simple Example Service](simpleexampleservice/simple-example-service.md)
- * [Example Service](exampleservice/example-service.md)
-
diff --git a/docs/core_models.md b/docs/core_models.md
index 6351857..606893f 100644
--- a/docs/core_models.md
+++ b/docs/core_models.md
@@ -118,7 +118,7 @@
corresponding ServiceInstance of B would then record specific state about that
data plane connection (e.g., what address each is known by).
-## Model Glossary
+## Service-related Model Glossary
The XOS core models are defined by a set of [xproto](dev/xproto.md)
specifications. They are defined in their full detail in the source code (see
@@ -126,6 +126,14 @@
The following summarizes these core models—along with the key relationships
(bindings) among them—in words.
+* **TrustDomain:** Trust domains represent a namespace where resources
+ are often grouped together. This can be used to isolate groups of services
+ from one another. There is typically a default `TrustDomain` provided.
+
+* **Principal:** Principals provide identities for compute resources. For
+ example, a `Principal` might convey a set of rights to perform operations on
+ a particular API.
+
* **Service:** Represents an elastically scalable, multi-tenant program,
including the declarative state needed to instantiate, control, and scale
functionality.
@@ -177,7 +185,7 @@
* **Slice:** Represents a distributed resource container that includes the
compute and network resources that belong to (are used by) some `Service`.
- * Bound to a set of `Instances` that provide compute resources for the
+ * Bound to a set of `ComputeServiceInstances` that provide compute resources for the
`Slice`.
* Bound to a set of `Networks` that connect the slice's `Instances` to
@@ -187,14 +195,28 @@
disk, memory, and cores) allocated to an instance. Current flavors borrow
from EC2.
- * Bound to a default `Image` that boots in each of the slice's`Instances`.
+ * Bound to a default `Image` that boots in each of the slice's`ComputeServiceInstances`.
Each `Image` implies a virtualization layer (e.g., Docker, KVM).
-* **Instance:** Represents a single compute instance associated with a Slice
- and instantiated on some physical Node. Each Instance is of some `isolation`
- type: `vm` (implemented as a KVM virtual machine), `container` (implemented
- as a Docker container), or `container_vm` (implemented as a Docker container
- running inside a KVM virtual machine).
+ * Optionally bound to a `TrustDomain` that specifies the namespace where the Slice's
+ resources should be created.
+
+ * Optionally bound to a `Principal` that permits compute resources of this
+ slice to interact with APIs and other components.
+
+* **ComputeServiceInstance:** This is derived from `ServiceInstance` and
+ represents a single compute instance associated with a Slice
+ and instantiated on some physical Node. A `ComputeServiceInstance`
+ inherently links two services. The first is the service that realizes
+ the compute resource, and is the `owner` of the
+ `ComputerServiceIsntance`. An example is the `Kubernetes` service, which
+ creates pods. The second is the service that owns the `Slice` that is
+ linked to the `ComputeServiceInstance`. This is the service that
+ is requesting the `ComputeServiceInstance`. The `ComputeServiceInstance`
+ also includes an `image` field which describes the image that should
+ be deployed. The `SimpleExampleService` service is a working example
+ of the interplay between two services (`SimpleExampleService` and
+ `Kubernetes`) via the `ComputeServiceInstance` model.
* **Network:** Represents a virtual network associated with a `Slice`. The
behavior of a given `Network`is defined by a `NetworkTemplate`, which
@@ -206,7 +228,7 @@
`MANAGEMENT_LOCAL`, `MANAGEMENT_HOST`, `VSG`, or `ACCESS__AGENT`.
* **Node:** Represents a physical server that can be virtualized and host
- Instances.
+ resources
* Bound to the `Site` where the `Node` is physically located.
@@ -219,9 +241,14 @@
* **Site:** Represents a logical grouping of `Nodes` that are co-located at the
same geographic location, which also typically corresponds to the nodes'
- location in the physical network. The typical use case involves one
- configuration of a system deployed at a single location, although the
- underlying core includes allows for multi-site deployments.
+ location in the physical network. The current convention is that there is
+ only one Site in the data model.
* Bound to a set of `Nodes` located at the `Site`.
+The above models comprise the core Service abstraction of XOS, but there are
+additional models in the data model that provide additional features. For
+example, there are models for initiating Backup and Restore and models for
+controlling the appearance of the XOS GUI. Please see
+[core.xproto](https://github.com/opencord/xos/blob/master/xos/core/models/core.xproto)
+and/or separate documentation on these features for more information.
diff --git a/docs/dev/sync_arch.md b/docs/dev/sync_arch.md
index 82c7260..9617ff8 100644
--- a/docs/dev/sync_arch.md
+++ b/docs/dev/sync_arch.md
@@ -37,7 +37,7 @@
## Actors and Types of State
-There are three actors in a Synchronizer that interact with a Data Model:
+There are four actors in a Synchronizer that interact with a Data Model:
* **Synchronizer Actuators:** An actuator is notified of changes to the data
model, upon which it refers to the current state of its service in the data
@@ -46,21 +46,17 @@
core in an ordering consistent with the dependencies on the model that it
synchronizes, with possible retries and error management.
-* **Synchronizer Watchers:** A watcher is also notified of changes to a data
- model, with the difference that it is not responsible for actuating its state
- by applying it to the system substrate. A Watcher for a given model is an
- actuator for a different model (i.e., not the one it watches). It subscribes
- to the watched model to gather information that it needs in addition to the
- data model that it synchronizes. For example, a synchronizer for a daemon may
- watch the IP address of the host it runs on, not because it configures the
- host with the IP address, but because it needs to advertise its address to
- clients that use the daemon.
-
* **Model Policies:** A model policy encapsulates data relationships between
related data models, such as “for every Network there must be at least one
interface.” Concretely in this example, a model policy would intercept
creations of Network models and create Interface models accordingly.
+* **Event Steps:** Event steps listen for external events and update the
+ data model.
+
+* **Pull Steps:** Pull steps poll external components for state and update
+ the data model.
+
The Data Model represents the authoritative and abstract state of the system.
By authoritative, we mean that if there is a conflict, then it is given
precedence over the internal configuration of services. This state is a
@@ -86,16 +82,14 @@
* Read/Write Feedback state
* Be scheduled upon changes to Declarative state
-* Watchers can:
- * Read Declarative state
- * Read Feedback state
- * Subscribe to changes to Declarative state (meaning no dependency
- ordering, no retries, no error propagation)
-
* Model Policies can
* Read/Write Declarative state
* Subscribe to changes to Declarative state
+* Event Steps and Pull Steps can
+ * Read/Write Declarative state
+ * Read/Write Feedback state
+
## Relationships Between Synchronizers and Models
A single synchronizer can synchronize multiple data models, usually through an
@@ -202,13 +196,13 @@
* `changed_by_policy`. This timestamp is set whenever non-bookkeeping fields in the model are changed during the execution of a model policy. If no changes occur during a save, then this timestamp is not set.
-For a given model, if we take the maximum of the three timestamps, `max(model.updated, model.changed_by_step, model.changed.by_policy)`, we can use that calculation as an overall version of the substantive fields of the model. If a user updated the model, or if a policy or syncstep changed the model, then one of those timestamps will be updated.
+For a given model, if we take the maximum of the three timestamps, `max(model.updated, model.changed_by_step, model.changed.by_policy)`, we can use that calculation as an overall version of the substantive fields of the model. If a user updated the model, or if a policy or syncstep changed the model, then one of those timestamps will be updated.
The following two timestamps are set when a sync or a model_policy is completed.
* `enacted`. Enacted indicates the model has been successfully synced. It is set to `max(model.updated, model.changed_by_policy)`. The enacted timestamp does not indicate the time of the synchronization, but rather indicates the version of the data that was synchronized.
-* `policed`. Policed indicates the model has successfully had model policies applied. It is set to `max(model.updated, model.changed_by_step)`. The policed timestamp does not indicate the time the policy completed, but rather indicates the version of the data that had policies applied.
+* `policed`. Policed indicates the model has successfully had model policies applied. It is set to `max(model.updated, model.changed_by_step)`. The policed timestamp does not indicate the time the policy completed, but rather indicates the version of the data that had policies applied.
The rules for running steps and policies are as follows:
diff --git a/docs/dev/xosgenx.md b/docs/dev/xosgenx.md
index 53a03e5..09671d9 100644
--- a/docs/dev/xosgenx.md
+++ b/docs/dev/xosgenx.md
@@ -136,9 +136,12 @@
You can print the tool’s syntax by running `xosgenx --help`.
```shell
-usage: xosgenx [-h] [--rev] --target TARGET [--output OUTPUT] [--attic ATTIC]
- [--kvpairs KV] [--write-to-file {single,model,target}]
+usage: xosgenx [-h] [--rev] [--output OUTPUT] [--attic ATTIC] [--kvpairs KV]
+ [--write-to-file {single,model,target}] [--version] [-v]
+ [--include-models INCLUDE_MODELS] [--include-apps INCLUDE_APPS]
[--dest-file DEST_FILE | --dest-extension DEST_EXTENSION]
+ (--target TARGET | --checkers CHECKERS | --lint)
+ [--strict-validation]
<input file> [<input file> ...]
XOS Generative Toolchain
@@ -149,18 +152,27 @@
optional arguments:
-h, --help show this help message and exit
--rev Convert proto to xproto
- --target TARGET Output format, corresponding to <output>.yaml file
--output OUTPUT Destination dir
--attic ATTIC The location at which static files are stored
--kvpairs KV Key value pairs to make available to the target
--write-to-file {single,model,target}
Single output file (single) or output file per model
(model) or let target decide (target)
+ --version show program's version number and exit
+ -v, --verbosity increase output verbosity
+ --include-models INCLUDE_MODELS
+ list of models to include
+ --include-apps INCLUDE_APPS
+ list of models to include
--dest-file DEST_FILE
Output file name (if write-to-file is set to single)
--dest-extension DEST_EXTENSION
Output file extension (if write-to-file is set to
single)
+ --target TARGET Output format, corresponding to <output>.yaml file
+ --checkers CHECKERS Comma-separated list of static checkers
+ --lint Parse the xproto but don't execute any xtargets
+ --strict-validation Exit if validation fails
```
For example usage of `xosgenx`, see the Dockerfiles in