expanded guide content
Change-Id: Id31ce3b9a761aa95b87d07675fc56cb573ddfd97
diff --git a/docs/README.md b/docs/README.md
index 76ca47c..33d173e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,7 @@
-# XOS
+# Models for CORD
-Welcome to the XOS documentation.
+CORD adopts a model-based architecture, where XOS implements its
+modeling support. This guide describes the how models are expressed in
+XOS, and documents the XOS toolchain used to auto-generate various
+elements of CORD from these models.
diff --git a/docs/core_models.md b/docs/core_models.md
new file mode 100644
index 0000000..b2aa20c
--- /dev/null
+++ b/docs/core_models.md
@@ -0,0 +1,133 @@
+#Core Models
+
+CORD adopts a model-based design. Each service configured into a
+given CORD deployment has a service-specific model, but CORD
+also defines a set of core models. Service-specific models are
+anchored in these core models.
+
+CORD's 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:
+[core.xproto](https://github.com/opencord/xos/blob/master/xos/core/models/core.xproto).
+The following describes these core models -- along with the
+relationships (bindings) among them -- in words.
+
+* **Service:** Represents an elastically scalable, multi-tenant
+program, including the means to instantiate, control, and scale
+functionality.
+
+ - Bound to a set of Slices that contains the collection of
+ virtualized resources (e.g., compute, network) in which the Service runs.
+
+ - Bound to a set of Controllers that represents the service's control
+ interface.
+
+* **ServiceDependency:** Represents a dependency between a *Subscriber*
+Service on a *Provider* Service. The set of ServiceDependency
+and Service models defined in CORD collectively represent the edges
+and verticies of a *Service Graph*. (There is no explicit **ServiceGraph** model.)
+The dependency between a pair of services is parameterized by the method
+by which they are interconnected in the data plane. Connect methods include:
+
+ - **None:** The two services are not connected in the data plane.
+ - **Private:** The two services are connected by a common private network.
+ - **Public:** The two services are connected by a publicly routable network.
+
+* **Slice:** A distributed resource container that includes the compute and
+network resources that belong to (are used by) some Service.
+
+ - Bound to a (possibly empty) set of Instances that provide compute
+ resources for the Slice.
+
+ - Bound to a set of Networks that connect the Slice's Instances to
+ each other, and connect this Slice to the Slices of other Services.
+
+ - Bound to a Flavor that defines how the Slice's Instances are
+ scheduled.
+
+ - Bound to an Image that boots in each of the Slice's Instances.
+
+* **Instance:** Represents a single compute instance associated
+ with a Slice and instantiated on some physical Node. Each Instance
+ is of some isolation type:
+
+ - **VM:** The instance is implemented as a KVM virtual machine.
+ - **Container:** The instance is implemented as a Docker container.
+ - **Container-in-VM:** The instance is implemented as a Docker
+ container running inside a KVM virtual machine.
+
+* **Network:** A virtual network associated with a Slice. Networks are
+of one of the following types:
+
+ - **PRIVATE:** Virtual network for the instances in the same service
+ - **PUBLIC:** Externally accessible network
+ - **MANAGEMENT_LOCAL:** Instance management network which does not span
+ compute nodes, only accessible from the host machine
+ - **MANAGEMENT_HOST:** Real management network which spans compute and
+ head nodes
+ - **ACCESS_AGENT:** Network for access agent infrastructure service
+
+* **Image:** A bootable image that runs in a virtual machine. Each
+ Image implies a virtualization layer (e.g., Docker, KVM), so the latter
+ need not be a distinct object.
+
+* **Flavor:** Represents a bundle of resources (e.g., disk, memory,
+ and cores) allocated to an instance. Current flavors borrow from EC2.
+
+* **Controller:** Represents the binding of an object
+ in the data model to a back-end element (e.g., an OpenStack head
+ node). Includes the credentials required to invoke the backend
+ resource.
+
+* **Node:** A physical server that can be virtualized and host Instances.
+
+ - Bound to the Site where the Node is physically located.
+
+ - Bound to a Deployment that defines the policies applied to the
+ Node.
+
+##Principals and Access Control
+
+* **User:** Represents an authenticated principal that is granted a set of
+ privileges to invoke operations on a set of models, objects, and
+ fields in the data model.
+
+* **Privilege:** Represents the right to perform a set of read, write,
+ or grant operations on a set of models, objects, and fields.
+
+##Sites and Deployments
+
+The typical use case involves one configuration of a CORD POD
+deployed at a single location. However, the underlying core includes
+two models for multi-site/multi-configuration deployments:
+
+* **Site:** 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.
+
+ - Bound to a set of Users that are affiliated with the Site.
+
+ - Bound to a set of Nodes located at the Site.
+
+ - Bound to a set of Deployments that the Site may access.
+
+* **Deployment:** A logical grouping of Nodes running a compatible set
+ of virtualization technologies and being managed according to a
+ coherent set of resource allocation policies.
+
+ - Bound to a set of Users that establish the Deployment's policies.
+
+ - Bound to a set of Nodes that adhere to the Deployment's policies.
+
+ - Bound to a set of supported Images that can be booted on the
+ Deployment's nodes.
+
+ - Bound to a set of Controllers that represent the back-end
+ infrastructure service that provides cloud resources (e.g., an
+ OpenStack head node).
+
+Sites and Deployments are often one-to-one, which corresponds
+to a each Site establishing its own policies, but in general,
+Deployments may span multiple Sites. It is also possible that a single
+Site hosts Nodes that belong to more than one Deployment.
+
diff --git a/docs/example_service.md b/docs/example_service.md
new file mode 100644
index 0000000..efb5336
--- /dev/null
+++ b/docs/example_service.md
@@ -0,0 +1,3 @@
+# Example Service
+
+A placeholder for the Example Service Tutorial (from the wiki).
diff --git a/docs/modeling_conventions.md b/docs/modeling_conventions.md
new file mode 100644
index 0000000..3011b90
--- /dev/null
+++ b/docs/modeling_conventions.md
@@ -0,0 +1,3 @@
+#Modeling Conventions
+
+A placeholder for the modeling conventions document (from the wiki)
diff --git a/docs/modules/xosconfig.md b/docs/modules/xosconfig.md
index 5cf2d9d..fcfebc4 100644
--- a/docs/modules/xosconfig.md
+++ b/docs/modules/xosconfig.md
@@ -1,65 +1,88 @@
-# Xos Config
+# Configuring XOS
-This module is responsible to read, validate and distribute the configuration for all
-the XOS based components.
+The `xosconfig` module is used to read, validate and distribute
+configuration information for all XOS-related components.
_The code for this module can be found in lib/xos-config_
-The `xosconfig` module use a combination of parameters provided via a `.yaml` file and a service discovery mechanism.
+The `xosconfig` module uses a combination of parameters provided
+via a `.yaml` file and a service discovery mechanism.
-## How to use this module
+## How to Use This Module
-This module needs to be initialized once (and only once) when you application start, you can do it with:
+This module needs to be initialized once (and only once) when you
+start the application. You can do it with:
+
```python
from xosconfig import Config
Config.init()
```
-By default the `xosconfig` module will look for a configuration file in `/opt/xos/config.yaml`, if for any reason you need to pass a different config file it can be done with:
+By default, `xosconfig` looks for a configuration file
+in `/opt/xos/config.yaml`. Passing a
+different config file can be done with:
+
```python
from xosconfig import Config
Config.init("/path/to/my/config.yaml")
```
-### Configuration defaults
-Note that defaults are defined for some of the configuration items. Defaults are defined in `lib/xos-config/xosconfig/default.py`.
+### Configuration Defaults
-### Reading data from the configuration file
+Defaults are defined for some of the configuration items
+in `lib/xos-config/xosconfig/default.py`.
-To access static information defined in the `config.yaml` file you can use this api:
+### Reading Data from the Configuration File
+
+To access static information defined in the `config.yaml` file, use
+the following API:
+
```python
from xosconfig import Config
res = Config.get('database')
```
-this call will return something like:
+This call returns something like:
+
```python
{
'username': 'test',
'password': 'safe'
}
```
-Since the configuration support nested dictionary is possible to query directly nested values using a `dot` notation, for example:
+
+Since the configuration supports a nested dictionary, it is possible to
+query directly nested values using `dot` notation. For example:
+
```python
from xosconfig import Config
res = Config.get('database.username')
```
-will return:
+
+returns
+
```python
"test"
```
+
**The configuration schema is defined in `/lib/xos-config/config-schema.yaml`**
-### Reading service information
+### Reading Service Information
-XOS is composed by a plethora of services, to discover them and their address we are using
-a tool called [registrator](https://github.com/gliderlabs/registrator).
+XOS is composed of a set of services. To discover these services and
+their address, use the
+[registrator](https://github.com/gliderlabs/registrator) tool.
-#### Retrieve a list of services:
+#### Retrieving a List of Services
+
+Invoking
+
```python
from xosconfig import Config
Config.get_service_list()
```
-this call will return an array of available services, by default:
+
+returns an array of available services; by default:
+
```python
[
"xos-ws",
@@ -71,17 +94,23 @@
"consul",
]
```
+
>You can get the same information on the `head node` using:
>```bash
> curl consul:8500/v1/catalog/services
>```
-#### Retrieve information for a single service:
+#### Retrieve Information for a Single Service
+
+Invoking
+
```python
from xosconfig import Config
Config.get_service_info('xos-db')
```
-that will return:
+
+returns
+
```python
{
'name': 'xos-db',
@@ -94,12 +123,17 @@
> curl consul:8500/v1/catalog/service/xos-db
>```
-#### Retrieve endpoint for a single service:
+#### Retrieving Endpoint for a Single Service
+
+Invoking
+
```python
from xosconfig import Config
Config.get_service_endpoint('xos-db')
```
-that will return:
+
+returns
+
```python
"http://172.18.0.4:5432"
-```
\ No newline at end of file
+```
diff --git a/docs/security_policies.md b/docs/security_policies.md
new file mode 100644
index 0000000..d900788
--- /dev/null
+++ b/docs/security_policies.md
@@ -0,0 +1,52 @@
+# Security Policies
+
+CORD security policies are implemented by XOS. These policies answer
+the question: *Who can do what?* The *who* in this case generally
+refers to a user (represented by a *User* model), but it can also
+refer to an API context. The *what* refers to two things: (1) the
+piece of information being accessed (a model, an object, or a field
+within that object), and (2) the access type (whether it is a read, a
+write, or a privilege update).
+
+## Summary of Policy Mechanism
+
+The mechanism for expressing these policies is provided by xproto’s
+policy extensions. The policies are enforced at the API boundary. When
+an API call is made, the appropriate policy is executed to determine
+whether or not access should be granted, and an audit trail is left
+behind. (Note: auditing is a TODO). The policy enforcers are
+auto-generated by the generative toolchain as part of the model
+generation process.
+
+Policies are generic logic expressions and can operate on any model
+or on the environment, but they frequently use the *Privilege* model.
+Specifically, when a policy cannot be expressed as a general principle
+(e.g., “a user can do whatever they want to a slice if he or she is
+its creator”) and instead depends on dynamic conditions, then it is
+encoded with the help of Privilege objects. For example, a Privilege
+object may be created to indicate that a user who is not a slice’s
+creator has admin privileges on it.
+
+Details on how policies are encoded can be found elsewhere.
+This document is about the “what” rather than the “how.”
+
+The set of security policies is being bootstrapped into the following
+state:
+
+* Privilege objects are automatically created for Slices. Most access
+control (e.g., to Networks and Instances) is via Slice, so this
+privilege covers the bulk of the access control.
+
+* Privileges for other models need to be created manually via the API
+(e.g., Sites, Services).
+
+* Any principal that has access to object *X* is also granted access
+to object *ControllerX*.
+
+* There are three types of access permissions: *Read*, *Write*, and
+*Grant*. Grant arbitrates access to Privilege objects (e.g., a slice
+admin could grant slice admin privileges to a user).
+
+The current policies are defined as follows:
+
+**To be included...*