Skip to content

Commit 12a26b1

Browse files
Harold Longleyrustydb
Harold Longley
authored and
rustydb
committed
CASMINST-3010: Revise description in index.md, purge most content from README.md
1 parent f51aba4 commit 12a26b1

File tree

3 files changed

+107
-208
lines changed

3 files changed

+107
-208
lines changed

‎README.md

+4-107
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
<a name="cray-system-management"></a>
2-
# Cray System Management (CSM) - Documentation
1+
# Cray System Management (CSM) - README
32

43
The documentation included here describes how to install or upgrade the Cray System Management (CSM)
54
software and related supporting operational procedures. CSM software is the foundation upon which
@@ -14,110 +13,8 @@ There are many tools which can render the Markdown format to get these advantage
1413
for Markdown tools will provide a long list of these tools. Some of the tools are better than others
1514
at displaying the images and allowing you to follow the navigational links.
1615

17-
The exploration of the CSM documentation begins with the Table of Contents in
18-
the [Cray System Management Installation Guide](index.md) which introduces
16+
The exploration of the CSM documentation begins with
17+
the [Cray System Management Documentation](index.md) which introduces
1918
topics related to CSM software installation, upgrade, and operational use. Notice that the
20-
previous sentence had a link to the index.md file for the Cray System Management Installation Guide.
19+
previous sentence had a link to the index.md file for the Cray System Management Documentation.
2120
If the link does not work, then a better Markdown viewer is needed.
22-
23-
Within this README.md file, these topics are described.
24-
25-
* [Offline Documentation](#offline-documentation)
26-
* [Review and Contribution](#review-and-contribution)
27-
* [Releases](#releases)
28-
* [Versioning](#versioning)
29-
30-
31-
<a name="offline-documentation"></a>
32-
### Offline Documentation
33-
34-
The CSM documentation is included within the CSM product release tarball. After it has been installed, the
35-
documentation will be available at `/usr/share/doc/csm` as installed by the docs-csm-install RPM.
36-
37-
This command will report the version of your installed documentation:
38-
39-
```bash
40-
ncn# rpm -q docs-csm-install
41-
```
42-
43-
To install the latest docs-csm-install RPM after installation:
44-
45-
```bash
46-
ncn# zypper ar -cf --gpgcheck-allow-unsigned https://packages.local/repository/csm-sle-15sp2 csm-sle-15sp2
47-
ncn# zypper ref csm-sle-15sp2
48-
ncn# zypper in -y --from csm-sle-15sp2 docs-csm-install
49-
```
50-
51-
<a name="review-and-contribution"></a>
52-
### Review and Contribution
53-
54-
Anyone with Git access to this repo may feel free to submit changes for review -- tagging to the
55-
relevant ticket(s) (if necessary).
56-
57-
All changes undergo a review process. This governance is up to the reviewers' discretion. The
58-
review serves to keep core contributors in alignment while maintaining coherency throughout
59-
the documentation.
60-
61-
<a name="releases"></a>
62-
### Releases
63-
64-
This guide follows a basic release model for enabling amendments and maintenance across releases.
65-
66-
> Note: Leading up to a release the "stable" and "unstable" branches may be _equal_.
67-
> However once a release has shipped, any amendments to that release must be made to the respective release branch.
68-
69-
- The "stable" (release) version of this guide exists within branches prefixed with "`release/`"
70-
- The "unstable" (latest) version of this guide exists within the `main` branch
71-
72-
<a name="versioning"></a>
73-
74-
### Versioning
75-
76-
This CSM documentation is versioned and packaged for offline reference.
77-
78-
X.Y.Z-HASH
79-
80-
The HASH will always change, it changes for every contribution that is pushed to this repository.
81-
82-
The X.Y.Z does not always change, it must be incremented by the contributor or this repository's
83-
owner(s). This pattern follows semantic version as described by http://semver.org.
84-
85-
- X: Major Version - This should be incremented by the repository owner for dramatic, or substantial
86-
changes to the structure or format.
87-
- Y: Minor Version - This should be incremented by the developer when making new pages or large
88-
amendments to the flow.
89-
- Z: Bug Fix/patch - This should be incremented by the developer when making amendments confined to
90-
a page.
91-
92-
Any contributor should feel welcome to ask for clarification on versioning within their change's
93-
review.
94-
95-
<a name="discussions"></a>
96-
97-
### Discussions
98-
99-
See the Cray /HPE Slack [#docs-csm-install][1] (not public; external access may be available for
100-
various partners and customers).
101-
102-
<a name="original-authors--reviewers"></a>
103-
104-
##### Original Authors / Reviewers
105-
106-
This document can be discussed in [#docs-csm-install][1].
107-
108-
These folks are main contributors or reviewers, none of which are the owners of this repository. Any
109-
email should include the list, otherwise ping the slack channel.
110-
111-
- PET: [Brad Klein](mailto:[email protected])
112-
- PET: [Craig DeLatte](mailto:[email protected])
113-
- METAL: [Jacob Salmela](mailto:[email protected])
114-
- PET: [Jeanne Ohren](mailto:[email protected])
115-
- METAL: [Russell Bunch](mailto:[email protected])
116-
- CMS: [Mitch Harding](mailto:[email protected])
117-
118-
[1]: https://cray.slack.com/messages/docs-csm-install
119-
120-
[2]: https://semver.org/
121-
122-
[3]: http://web.us.cray.com/~ekoen/slingshot_portal/master/portal/public/developer-portal/overview/
123-
>>>>>>> release/0.9

‎index.md

+66-87
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Cray System Management Installation Guide
1+
# Cray System Management Documentation
22

33
### Scope and Audience
44

5-
The documentation included here describes how to install or upgrade the Cray System Management (CSM)
6-
software and related supporting operational procedures to manage an HPE Cray EX system. CSM software
7-
is the foundation upon which other software product streams for the HPE Cray EX system depend.
5+
The documentation included here describes the Cray System Management (CSM) software, how to install
6+
or upgrade CSM software, and related supporting operational procedures to manage an HPE Cray EX system.
7+
CSM software is the foundation upon which other software product streams for the HPE Cray EX system depend.
88

99
The CSM installation prepares and deploys a distributed system across a group of management
1010
nodes organized into a Kubernetes cluster which uses Ceph for utility storage. These nodes
@@ -18,7 +18,7 @@ demand for them varies, such as when booting many compute nodes or application n
1818

1919
This information is intended for system installers, system administrators, and network administrators
2020
of the system. It assumes some familiarity with standard Linux and open source tools, such as shell
21-
scripts, Ansible, YAML, JSON, and TOML file formats, etc.
21+
scripts, revision control with git, configuration management with Ansible, YAML, JSON, and TOML file formats, etc.
2222

2323
### Trademarks
2424

@@ -30,98 +30,77 @@ The chapters with topics which need to be done as part of an ordered procedure a
3030

3131
1. [Introduction to CSM Installation](introduction/index.md)
3232

33-
Topics:
34-
* [CSM Overview](introduction/index.md#csm_overview)
35-
* [Scenarios for Shasta v1.5](introduction/index.md#scenarios)
36-
* [CSM Product Stream Updates](introduction/index.md#product-stream-updates)
37-
* [CSM Operational Activities](introduction/index.md#operations)
38-
* [Differences from Previous Release](introduction/index.md#differences)
39-
* [Documentation Conventions](introduction/index.md#documentation_conventions)
33+
This chapter provides an introduction to using the CSM software to manage the HPE Cray EX system which
34+
also describes the scenarios for installation and upgrade of CSM software, how product stream updates
35+
for CSM are delivered, the operational activities done after installation for on-going management
36+
of the HPE Cray EX system, differences between previous release and this release, and conventions
37+
used in this documentation.
4038

4139
1. [Update CSM Product Stream](update_product_stream/index.md)
4240

43-
Topics:
44-
1. [Download and Extract CSM Product Release](update_product_stream/index.md#download-and-extract)
45-
1. [Apply Patch to CSM Release](update_product_stream/index.md#patch)
46-
1. [Check for Latest Workarounds and Documentation Updates](update_product_stream/index.md#workarounds)
47-
1. [Check for Field Notices about Hotfixes](update_product_stream/index.md#hotfixes)
41+
This chapter explains how to get the CSM product release, any patches, update to the latest set of
42+
documenation and any installation workarounds, and check for any Field Notices or Hotfixes.
4843

4944

5045
1. [Install CSM](install/index.md)
5146

52-
Topics:
53-
1. [Validate Management Network Cabling](install/index.md#validate_management_network_cabling)
54-
1. [Prepare Configuration Payload](install/index.md#prepare_configuration_payload)
55-
1. [Prepare Management Nodes](install/index.md#prepare_management_nodes)
56-
1. [Bootstrap PIT Node](install/index.md#bootstrap_pit_node)
57-
1. [Configure Management Network Switches](install/index.md#configure_management_network)
58-
1. [Collect MAC Addresses for NCNs](install/index.md#collect_mac_addresses_for_ncns)
59-
1. [Deploy Management Nodes](install/index.md#deploy_management_nodes)
60-
1. [Install CSM Services](install/index.md#install_csm_services)
61-
1. [Validate CSM Health Before PIT Node Redeploy](install/index.md#validate_csm_health_before_pit_redeploy)
62-
1. [Redeploy PIT Node](install/index.md#redeploy_pit_node)
63-
1. [Configure Administrative Access](install/index.md#configure_administrative_access)
64-
1. [Validate CSM Health](operations/validate_csm_health.md)
65-
1. [Configure Prometheus Alert Notifications](install/index.md#configure_prometheus_alert_notifications)
66-
1. [Update Firmware with FAS](operations/firmware/Update_Firmware_with_FAS.md)
67-
1. [Prepare Compute Nodes](install/index.md#prepare_compute_nodes)
68-
1. [Next Topic](install/index.md#next_topic)
69-
1. [Troubleshooting Installation Problems](install/troubleshooting_installation.md)
47+
This chapter provides an order list of procedures which can be used for CSM software installation or reinstall
48+
that indicate when to do operational tasks as part of the installation workflow. Updating software is in another chapter.
49+
Installation of the CSM product stream has many steps in multiple procedures which should be done in a
50+
specific order. Information about the HPE Cray EX system and the site is used to prepare the configuration
51+
payload. The initial node used to bootstrap the installation process is called the PIT node because the
52+
Pre-Install Toolkit is installed there. Once the management network switches have been configured, the other
53+
management nodes can be deployed with an operating system and the software to create a Kubernetes cluster
54+
utilizing Ceph storage. The CSM services provide essential software infrastructure including the API gateway
55+
and many micro-services with REST APIs for managing the system. Once administrative access has been configured,
56+
the installation of CSM software and nodes can be validated with health checks before doing operational tasks
57+
like the check and update of firmware on system components or the preparation of compute nodes.
7058

7159
1. [Upgrade CSM](upgrade/index.md)
7260

73-
Topics:
74-
1. [Prepare for Upgrade](upgrade/index.md#prepare_for_upgrade)
75-
1. [Update Management Network Configuration](upgrade/index.md#update_management_network)
76-
1. [Upgrade Management Nodes and CSM Services](upgrade/index.md#upgrade_management_nodes_csm_services)
77-
1. [Validate CSM Health](upgrade/index.md#validate_csm_health)
78-
1. [Update Firmware with FAS](upgrade/index.md#update_firmware_with_fas)
79-
1. [Next Topic](upgrade/index.md#next_topic)
61+
This chapter provides an order list of procedures which can be used to update CSM software that indicate when
62+
to do operational tasks as part of the software upgrade workflow. There are procedures to prepare the
63+
HPE Cray system for the upgrade, and update the management network, the management nodes, and the CSM services.
64+
After the upgrade of CSM software, the CSM health checks are used to validate the system before doing any other
65+
operational tasks like the check and update of firmware on system components.
8066

8167
1. [CSM Operational Activities](operations/index.md)
8268

83-
Topics:
84-
* [CSM Product Management](operations/index.md#csm-product-management)
85-
* [Image Management](operations/index.md#image-management)
86-
* [Boot Orchestration](operations/index.md#boot-orchestration)
87-
* [System Power Off Procedures](operations/index.md#system-power-off-procedures)
88-
* [System Power On Procedures](operations/index.md#system-power-on-procedures)
89-
* [Power Management](operations/index.md#power-management)
90-
* [Artifact Management](operations/index.md#artifact-management)
91-
* [Compute Rolling Upgrades](operations/index.md#compute-rolling-upgrades)
92-
* [Configuration Management](operations/index.md#configuration-management)
93-
* [Kubernetes](operations/index.md#kubernetes)
94-
* [Package Repository Management](operations/index.md#package-repository-management)
95-
* [Security and Authentication](operations/index.md#security-and-authentication)
96-
* [Resiliency](operations/index.md#resiliency)
97-
* [ConMan](operations/index.md#conman)
98-
* [Utility Storage](operations/index.md#utility-storage)
99-
* [System Management Health](operations/index.md#system-management-health)
100-
* [System Layout Service (SLS)](operations/index.md#system-layout-service-sls)
101-
* [System Configuration Service](operations/index.md#system-configuration-service)
102-
* [Hardware State Manager (HSM)](operations/index.md#hardware-state-manager-hsm)
103-
* [Node Management](operations/index.md#node-management)
104-
* [River Endpoint Discovery Service (REDS)](operations/index.md#river-endpoint-discovery-service-reds)
105-
* [Network](operations/index.md#network)
106-
* [Update Firmware with FAS](operations/index.md#update-firmware-with-fas)
107-
* [User Access Service (UAS)](operations/index.md#user-access-service-uas)
108-
109-
2. [CSM Troubleshooting Information](troubleshooting/index.md)
110-
111-
Topics:
112-
* [Known Issues](troubleshooting/index.md#known-issues)
113-
114-
3. [CSM Background Information](background/index.md)
115-
116-
Topics:
117-
* [Cray Site Init Files](background/cray_site_init_files.md)
118-
* [Certificate Authority](background/certificate_authority.md)
119-
* [NCN Images](background/ncn_images.md)
120-
* [NCN Boot Workflow](background/ncn_boot_workflow.md)
121-
* [NCN Networking](background/ncn_networking.md)
122-
* [NCN Mounts and File Systems](background/ncn_mounts_and_file_systems.md)
123-
* [NCN Packages](background/ncn_packages.md)
124-
* [NCN Operating System Releases](background/ncn_operating_system_releases.md)
125-
* [cloud-init Basecamp Configuration](background/cloud-init_basecamp_configuration.md)
126-
127-
4. [Glossary](glossary.md)
69+
This chapter provides an unordered set of administrative procedures required to operate an HPE Cray EX system with CSM software and grouped into several major areas:
70+
* CSM Product Management
71+
* Artifact Management
72+
* Boot Orchestration
73+
* Compute Rolling Upgrade
74+
* Configuration Management
75+
* Console Management
76+
* Firmware Management
77+
* Hardware State Manager
78+
* Image Management
79+
* Kubernetes
80+
* Network Management
81+
* Node Management
82+
* Package Repository Management
83+
* Power Management
84+
* Resiliency
85+
* River Endpoint Discovery Service
86+
* Security And Authentication
87+
* System Configuration Service
88+
* System Layout Service
89+
* System Management Health
90+
* UAS User And Admin Topics
91+
* Utility Storage
92+
* Validate CSM Health
93+
94+
1. [CSM Troubleshooting Information](troubleshooting/index.md)
95+
96+
This chapter provides information about some known issues in the system and tips for troubleshooting Kubernetes.
97+
98+
1. [CSM Background Information](background/index.md)
99+
100+
This chapter provides background information about the NCNs (non-compute nodes) which function as
101+
management nodes for the HPE Cray EX system. This information is not normally needed to install
102+
or upgrade software, but provides background which might be helpful for troubleshooting an installation.
103+
104+
1. [Glossary](glossary.md)
105+
106+
This chapter provides a explanations of terms and acronyms used throughout the rest of this documentation.

‎update_product_stream/index.md

+37-14
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
The software included in the CSM product stream is released in more than one way. The initial product release may be augmented with patches, late-breaking workarounds and documentation updates, or hotfixes after the release.
44

5+
The CSM documentation is included within the CSM product release tarball inside the docs-csm-install RPM.
6+
After it has been installed, the documentation will be available at `/usr/share/doc/csm` as installed by
7+
the docs-csm-install RPM.
8+
59
### Topics:
610
* [Download and Extract CSM Product Release](#download-and-extract)
711
* [Apply Patch to CSM Release](#patch)
@@ -131,28 +135,47 @@ System installer
131135
#### Objective
132136
Acquire the late-breaking CSM workarounds and documentation update RPMs. These fixes were not available until after the software release. The software installation and upgrade processes have several breakpoints where you check and apply workarounds before or after a critical procedure.
133137
138+
This command will report the version of your installed documentation.
139+
140+
```bash
141+
ncn# rpm -q docs-csm-install
142+
```
143+
144+
134145
#### Limitations
135146
None.
136147
137148
### Procedure
138149
139-
Download and upgrade the latest workaround and documentation RPMs.
150+
1. Check the version of the currently installed CSM documentation.
140151
141-
```bash
142-
linux# rpm -Uvh --force https://storage.googleapis.com/csm-release-public/shasta-1.5/docs-csm-install/docs-csm-install-latest.noarch.rpm
143-
linux# rpm -Uvh --force https://storage.googleapis.com/csm-release-public/shasta-1.5/csm-install-workarounds/csm-install-workarounds-latest.noarch.rpm
144-
```
152+
```bash
153+
ncn# rpm -q docs-csm-install
154+
```
145155
146-
If this machine does not have direct Internet access these RPMs will need to be externally downloaded and then copied to the system. This example copies them to ncn-m001.
156+
1. Download and upgrade the latest workaround and documentation RPMs.
147157
148-
```bash
149-
linux# wget https://storage.googleapis.com/csm-release-public/shasta-1.5/docs-csm-install/docs-csm-install-latest.noarch.rpm
150-
linux# wget https://storage.googleapis.com/csm-release-public/shasta-1.5/csm-install-workarounds/csm-install-workarounds-latest.noarch.rpm
151-
linux# scp -p docs-csm-install-*rpm csm-install-workarounds-*rpm ncn-m001:/root
152-
linux# ssh ncn-m001
153-
ncn-m001# rpm -Uvh --force docs-csm-install-latest.noarch.rpm
154-
ncn-m001# rpm -Uvh --force csm-install-workarounds-latest.noarch.rpm
155-
```
158+
```bash
159+
linux# rpm -Uvh --force https://storage.googleapis.com/csm-release-public/shasta-1.5/docs-csm-install/docs-csm-install-latest.noarch.rpm
160+
linux# rpm -Uvh --force https://storage.googleapis.com/csm-release-public/shasta-1.5/csm-install-workarounds/csm-install-workarounds-latest.noarch.rpm
161+
```
162+
163+
If this machine does not have direct Internet access these RPMs will need to be externally downloaded and then copied to the system. This example copies them to ncn-m001.
164+
165+
```bash
166+
linux# wget https://storage.googleapis.com/csm-release-public/shasta-1.5/docs-csm-install/docs-csm-install-latest.noarch.rpm
167+
linux# wget https://storage.googleapis.com/csm-release-public/shasta-1.5/csm-install-workarounds/csm-install-workarounds-latest.noarch.rpm
168+
linux# scp -p docs-csm-install-*rpm csm-install-workarounds-*rpm ncn-m001:/root
169+
linux# ssh ncn-m001
170+
ncn-m001# rpm -Uvh --force docs-csm-install-latest.noarch.rpm
171+
ncn-m001# rpm -Uvh --force csm-install-workarounds-latest.noarch.rpm
172+
```
173+
174+
1. Check the version of the newly installed documentation.
175+
176+
```bash
177+
ncn# rpm -q docs-csm-install
178+
```
156179
157180
<a name="apply-workarounds"></a>
158181
## Check for and Apply Workarounds

0 commit comments

Comments
 (0)