Browse Source

Added base documentation

Purnendu Ghosh 4 months ago
parent
commit
440015d591
4 changed files with 174 additions and 11 deletions
  1. 6
    3
      README.md
  2. 68
    6
      doc/source/getting_started.rst
  3. 3
    2
      doc/source/index.rst
  4. 97
    0
      doc/source/tugboat.rst

+ 6
- 3
README.md View File

@@ -23,7 +23,10 @@ all the information that will be rendered to generate Airship site
23 23
 manifests. This optional step will help the deployment engineer to
24 24
 modify any data if required.
25 25
 
26
-Basic Usage
27
------------
26
+Getting Started
27
+---------------
28
+For more detailed installation and setup information, please refer to the
29
+`Getting Started`_ guide.
28 30
 
29
-TODO
31
+
32
+.. _`Getting Started`: ./doc/source/getting_started.rst

+ 68
- 6
doc/source/getting_started.rst View File

@@ -19,7 +19,7 @@ Getting Started
19 19
 ===============
20 20
 
21 21
 What is Spyglass?
22
-----------------
22
+-----------------
23 23
 
24 24
 Spyglass is a data extraction tool which can interface with
25 25
 different input data sources to generate site manifest YAML files.
@@ -28,6 +28,7 @@ for a site deployment. These site manifest YAML files generated
28 28
 by spyglass will be saved in a Git repository, from where Pegleg
29 29
 can access and aggregate them. This aggregated file can then be
30 30
 fed to Shipyard for site deployment / updates.
31
+Reference: https://review.openstack.org/#/c/605227
31 32
 
32 33
 Architecture
33 34
 ------------
@@ -62,6 +63,65 @@ Architecture
62 63
 
63 64
 --
64 65
 
66
+Supported Features
67
+------------------
68
+1. Tugboat Plugin: Supports extracting site data from Excel files and
69
+   then generate site manifests for sitetype:airship-seaworthy.
70
+   Find more documentation for Tugboat, see :ref:`tugboatinfo`.
71
+
72
+2. Remote Data Source Plugin: Supports extracting site data from a REST
73
+   endpoint.
74
+
75
+3. YAML Editor for Intermediary YAML: Support runtime editing of missing
76
+   site parameters
77
+
78
+Future Work
79
+-----------
80
+1) Schema based manifest generation instead of Jinja2 templates. It shall
81
+be possible to cleanly transition to this schema based generation keeping a unique
82
+mapping between schema and generated manifests. Currently this is managed by
83
+considering a mapping of j2 templates with schemas and site type.
84
+
85
+List of Generated Site Manifests:
86
+---------------------------------
87
+The spyglass uses the plugin data source to generate the following site
88
+manifests:
89
+
90
+- site-definition.yaml
91
+- profile/
92
+- profile/region.yaml
93
+- baremetal/
94
+- baremetal/nodes.yaml
95
+- networks/
96
+- networks/common_addresses.yaml
97
+- networks/control-plane-addresses.yaml
98
+- networks/physical/
99
+- networks/physical/networks.yaml
100
+- software/
101
+- software/charts/
102
+- software/charts/osh/
103
+- software/charts/osh/openstack-tenant-ceph/
104
+- software/charts/osh/openstack-tenant-ceph/ceph-client.yaml
105
+- software/charts/ucp/
106
+- software/charts/ucp/divingbell/
107
+- software/charts/ucp/divingbell/divingbell.yaml
108
+- software/config/
109
+- software/config/corridor.yaml
110
+- software/config/common-software-config.yaml
111
+- deployment/
112
+- deployment/deployment-strategy.yaml
113
+- pki/
114
+- pki/kubelet-node-pkicatalog.yaml
115
+
116
+Spyglass maintains corresponding J2 templates for these files
117
+and then those are processed with site information obtained
118
+from plugin data source.
119
+
120
+In some cases, the site might require additional site
121
+manifests containing static information independent of the
122
+plugin data received. In such cases one can just place the
123
+corresponding J2 templates in the appropriate folder.
124
+
65 125
 Basic Usage
66 126
 -----------
67 127
 
@@ -72,7 +132,7 @@ Before using Spyglass you must:
72 132
 
73 133
    .. code-block:: console
74 134
 
75
-    git clone https://github.com/att-comdev/tugboat/tree/spyglass
135
+    git clone https://github.com/att-comdev/spyglass
76 136
 
77 137
 2. Install the required packages in spyglass:
78 138
 
@@ -100,8 +160,7 @@ Options:
100 160
                                   excel spec
101 161
   -idir, --intermediary_dir PATH  The path where intermediary file needs to be
102 162
                                   generated
103
-  -e, --edit_intermediary / -nedit, --no_edit_intermediary
104
-                                  Flag to let user edit intermediary
163
+  -e, --edit_intermediary         Flag to let user edit intermediary
105 164
   -m, --generate_manifests        Generate manifests from the generated
106 165
                                   intermediary file
107 166
   -mdir, --manifest_dir PATH      The path where manifest files needs to be
@@ -115,6 +174,9 @@ Options:
115 174
                                   20]
116 175
   --help                          Show this message and exit.
117 176
 
177
+--------
178
+Examples
179
+--------
118 180
 
119 181
 1. Running Spyglass with  Remote Data Source Plugin
120 182
 
@@ -125,8 +187,8 @@ spyglass -mg --type formation -f <URL> -u <user_id> -p <password> -d <site_confi
125 187
 spyglass -mg --type tugboat -x <Excel File> -e <Excel Spec> -d <Site Config> -s <Region> --template_dir=<j2 template dir>
126 188
 
127 189
 for example:
128
-spyglass -mg -t tugboat -x SiteDesignSpec_v0.1.xlsx -e excel_spec_upstream.yaml -d site_config.yaml -s airship-seaworthy --template_dir=<j2 template dir>
190
+spyglass -mg -t tugboat -x SiteDesignSpec_v1.1.xlsx -e excel_spec_upstream.yaml -d site_config.yaml -s airship-seaworthy --template_dir=<j2 template dir>
191
+
129 192
 Where sample 'excel_spec_upstream.yaml', 'SiteDesignSpec_v0.1.xlsx'
130 193
 'site_config.yaml' and J2 templates can be found under 'spyglass/examples'
131 194
 folder
132
-

+ 3
- 2
doc/source/index.rst View File

@@ -14,9 +14,9 @@
14 14
       License for the specific language governing permissions and limitations
15 15
       under the License.
16 16
 
17
-=====================
17
+======================
18 18
 Spyglass Documentation
19
-=====================
19
+======================
20 20
 
21 21
 Overview
22 22
 --------
@@ -32,3 +32,4 @@ fed to Shipyard for site deployment / updates.
32 32
    :maxdepth: 2
33 33
 
34 34
    getting_started
35
+   tugboat

+ 97
- 0
doc/source/tugboat.rst View File

@@ -0,0 +1,97 @@
1
+
2
+      Copyright 2018 AT&T Intellectual Property.
3
+      All Rights Reserved.
4
+
5
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
6
+      not use this file except in compliance with the License. You may obtain
7
+      a copy of the License at
8
+
9
+          http://www.apache.org/licenses/LICENSE-2.0
10
+
11
+      Unless required by applicable law or agreed to in writing, software
12
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
+      License for the specific language governing permissions and limitations
15
+      under the License.
16
+
17
+.. _tugboatinfo:
18
+
19
+=======
20
+Tugboat
21
+=======
22
+
23
+What is Tugboat?
24
+----------------
25
+
26
+Tugboat is a Spyglass plugin to generate airship-seaworthy site manifest files
27
+from an excel based engineering spec. The plugin is configured with an Excel
28
+sheet and its corresponding excel specification as inputs. Spyglass uses this
29
+plugin to construct an intermediary yaml which is processed further using J2
30
+templates to generate site manifests.
31
+
32
+Excel specification
33
+-------------------
34
+Excel Spec is like an index to the Excel sheet to look for the data to be
35
+collected by the tool. Excel Spec Sample specifies all the details that
36
+need to be filled by the Deployment Engineer.
37
+
38
+Below is the definition for each key in the Excel spec
39
+
40
+::
41
+
42
+
43
+     ipmi_sheet_name - name of the sheet from where IPMI and host profile information is to be read
44
+     start_row - row number from where the IPMI and host profile information starts
45
+     end_row - row number from where the IPMI and host profile information ends
46
+     hostname_col - column number where the hostnames are to be read from
47
+     ipmi_address_col - column number from where the ipmi addresses are to be read
48
+     host_profile_col - column number from where the host profiles are to be read
49
+     ipmi_gateway_col - column number from where the ipmi gateways are to be read
50
+     private_ip_sheet - name of the sheet which has the private IP information
51
+     net_type_col - column number from where the network type is to be read
52
+     vlan_col - column number from where the network vlan is to be read
53
+     vlan_start_row - row number from where the vlan information starts
54
+     vlan_end_row - row number from where the vlan information ends
55
+     net_start_row - row number from where the network information starts
56
+     net_end_row - row number from where the network information ends
57
+     net_col - column number where the IP ranges for network is to be read
58
+     net_vlan_col - column number where the vlan information is present in the pod wise network section
59
+     public_ip_sheet - name of the sheet which has the public IP information
60
+     oam_vlan_col - column number from where the OAM vlan information is to be read from
61
+     oam_ip_row - row number from where the OAM network information is to be read from
62
+     oam_ip_col - column number from where the OAM network information is to be read from
63
+     oob_net_row - row number which has the OOB network subnet ranges
64
+     oob_net_start_col - column number from where the OOB network ranges start
65
+     oob_net_end_col - column number from where the OOB network ranges end
66
+     ingress_ip_row - row number from where the Ingress network information is to be read from
67
+     dns_ntp_ldap_sheet - name of the sheet which has the DNS, NTP and LDAP information
68
+     login_domain_row - row number which has the ldap login domain
69
+     ldap_col - column number which has the all ldap related information
70
+     global_group - row number which has the ldap group information
71
+     ldap_search_url_row - row number which has the ldap url
72
+     ntp_row - row number which has the ntp information
73
+     ntp_col - column number which has the ntp information
74
+     dns_row - row number which has the dns information
75
+     dns_col - column number which has the dns information
76
+     domain_row - row number which has the domain information
77
+     domain_col - column number which has the domain information
78
+     location_sheet - name of the sheet which has the location information
79
+     column - column number which has all the information
80
+     corridor_row - row number which has the corridor information
81
+     site_name_row - row number which has the site name
82
+     state_name_row - row number which has the state name
83
+     country_name_row - row number which has the country name
84
+     clli_name_row - row number which has CLLI information
85
+
86
+Example: Tugboat Plugin Usage
87
+-----------------------------
88
+1. Required Input(Refer to 'spyglass/examples' folder to get these inputs)
89
+   a) Excel File: SiteDesignSpec_v0.1.xlsx
90
+   b) Excel Spec: excel_spec_upstream.yaml
91
+   c) Site Config: site_config.yaml
92
+   d) Template_dir: '../examples/templates'
93
+   c) Site name: airship-seaworthy
94
+
95
+2. Spyglass CLI Command:
96
+   spyglass -mg -t tugboat -x SiteDesignSpec_v0.1.xlsx -e excel_spec_upstream.yaml -d site_config.yaml -s airship-seaworthy --template_dir=<relative path to '../examples/templates'
97
+

Loading…
Cancel
Save