Merge pull request #52594 from ShaunaDiaz/OSDOCS-4468

mjpytlak · web-flow · commit cdcf17ab5d5b · 2022-11-10T12:50:30.000-05:00
OSDOCS-4468: updating MicroShift intro
diff --git a/_attributes/attributes-microshift.adoc b/_attributes/attributes-microshift.adoc
@@ -6,3 +6,5 @@
 :OCP: OpenShift Container Platform
 :op-system-first: Red Hat Enterprise Linux for Edge (RHEL for Edge)
 :op-system: RHEL for Edge
+:op-system-ram: 2GB RAM
+:op-system-chip: two-core AMD64 1.5GHz processor
diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml
@@ -31,14 +31,14 @@ Topics:
 - Name: Legal notice
   File: legal-notice
 ---
-Name: Introduction to MicroShift
-Dir: microshift_architecture
+Name: Getting Started
+Dir: microshift_getting-started
 Distros: microshift
 Topics:
 - Name: Understanding MicroShift
   File: microshift-understanding
-- Name: MicroShift APIs
-  File: microshift-apis
+- Name: Architecture
+  File: microshift-architecture
 ---
 # Name: Release notes
 # Dir: release_notes
@@ -145,5 +145,5 @@ Name: Troubleshooting
 Dir: microshift_support
 Distros: microshift
 Topics:
-- Name: Checking the MicroShift Version
-  File: microshift-version
+- Name: MicroShift Troubleshooting
+  File: microshift-troubleshooting
diff --git a/cli_reference/openshift_cli/usage-oc-kubectl.adoc b/cli_reference/openshift_cli/usage-oc-kubectl.adoc
@@ -18,7 +18,7 @@ Resources such as `DeploymentConfig`, `BuildConfig`, `Route`, `ImageStream`, and
 +
 ifndef::microshift[]
 The `oc` binary offers a built-in `login` command for authentication and lets you work with {product-title} projects, which map Kubernetes namespaces to authenticated users.
-See xref:../../authentication/understanding-authentication.adoc#understanding-authentication[Understanding authentication] for more information.
+Read xref:../../authentication/understanding-authentication.adoc#understanding-authentication[Understanding authentication] for more information.
 endif::[]
 +
 ifdef::microshift[]
diff --git a/microshift_architecture/attributes b/microshift_architecture/attributes
diff --git a/microshift_architecture/images b/microshift_architecture/images
diff --git a/microshift_architecture/microshift-understanding.adoc b/microshift_architecture/microshift-understanding.adoc
diff --git a/microshift_architecture/modules b/microshift_architecture/modules
diff --git a/microshift_architecture/snippets b/microshift_architecture/snippets
diff --git a/microshift_getting-started/_attributes b/microshift_getting-started/_attributes
diff --git a/microshift_getting-started/images b/microshift_getting-started/images
@@ -0,0 +1 @@
+../images
diff --git a/microshift_getting-started/microshift-architecture.adoc b/microshift_getting-started/microshift-architecture.adoc
@@ -0,0 +1,30 @@
+:_content-type: ASSEMBLY
+[id="microshift-architecture"]
+= Architecture
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-architecture
+
+toc::[]
+
+Learn the specifics of {product-title} architecture including design intent, how it differs from {OCP}, and API compatibility.
+
+== Architectural design
+{product-title} is a single-node container orchestration runtime designed to extend the benefits of using containers for running applications to low-resource edge environments. {product-title} contains only the APIs and features essential to operating in edge and small form factor computing environments.
+
+== Key differences from {OCP}
+* Application-level events and metrics are observation-only
+* Devices with {product-title} installed are self-managing
+* Compatible with rpm-ostree-based systems
+* Uses only the APIs needed for essential functions, such as security and runtime controls
+* Reuses select commands from the OpenShift CLI (`oc`) tool
+
+// * You can use in locations where full control is needed
+// * Works offline and in low-connectivity environments
+// * You do not need to perform external orchestration
+// * Installs on top of {op-system-first}, an operating system especially for edge computing
+// * Use several single-node deployments to ... (use case example)
+// Bullets need more specific detail
+
+include::modules/microshift-openshift-apis.adoc[leveloffset=+1]
+
+include::modules/microshift-k8s-apis.adoc[leveloffset=+1]
diff --git a/microshift_getting-started/microshift-understanding.adoc b/microshift_getting-started/microshift-understanding.adoc
@@ -0,0 +1,12 @@
+:_content-type: ASSEMBLY
+[id="con-microshift-understanding"]
+= Understanding MicroShift
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-understanding
+
+toc::[]
+
+Get an overview of what you can do with {product-title}, a distribution of {OCP} designed for optimizing small form factors and edge computing.
+
+include::modules/about-microshift.adoc[leveloffset=+1]
+
diff --git a/microshift_getting-started/modules b/microshift_getting-started/modules
@@ -0,0 +1 @@
+../modules
diff --git a/microshift_getting-started/snippets b/microshift_getting-started/snippets
@@ -0,0 +1 @@
+../snippets/
diff --git a/microshift_install/_attributes b/microshift_install/_attributes
@@ -0,0 +1 @@
+../_attributes
diff --git a/microshift_install/attributes b/microshift_install/attributes
diff --git a/microshift_install/images b/microshift_install/images
@@ -1 +1 @@
-../../images/
+../images
diff --git a/microshift_install/modules b/microshift_install/modules
@@ -1 +1 @@
-../../modules/
+../modules
diff --git a/microshift_install/snippets b/microshift_install/snippets
@@ -1 +1 @@
-../../snippets/
+../snippets/
diff --git a/microshift_support/_attributes b/microshift_support/_attributes
@@ -0,0 +1 @@
+../_attributes
diff --git a/microshift_support/microshift-troubleshooting.adoc b/microshift_support/microshift-troubleshooting.adoc
@@ -0,0 +1,12 @@
+:_content-type: ASSEMBLY
+[id="microshift-troubleshooting"]
+= MicroShift Troubleshooting
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-troubleshooting
+toc::[]
+
+Determine which version of {product-title} you have, find out about known issues, and troubleshoot common problems.
+
+include::modules/microshift-version-cli.adoc[leveloffset=+1]
+
+include::modules/microshift-version-api.adoc[leveloffset=+1]
diff --git a/microshift_support/microshift-version.adoc b/microshift_support/microshift-version.adoc
diff --git a/modules/about-microshift.adoc b/modules/about-microshift.adoc
@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// microshift/understanding-microshift.adoc 
+
+[id="con-about-microshift_{context}"]
+= About MicroShift
+
+Working with low-resource field environments and hardware presents many challenges not experienced with cloud computing. {product-title} enables you to solve problems for edge devices by:
+
+* Overcoming the operational challenge of minimal system resources, for example, a {op-system-chip} with {op-system-ram}.
+* Addressing the environmental challenges of severe networking constraints such as low or no connectivity.
+* Meeting the physical constraint of hard-to-access locations by installing your system images directly on edge devices.
+* Building on and integrating with edge-optimized operating systems such as {op-system-first}.
+
+{product-title} has the simplicity of single-node deployment with the functions and services you need for computing in resource-constrained locations. You can have many deployments on different hosts, creating the specific system image needed for each of your applications. Installing {product-title} on top of your managed {op-system} devices in hard-to-service locations also allows for streamlined over-the-air updates.
+
+//For more information about installing and interacting with {product-title}, read the following:
+//we can change this to refer to a Quick Start Guide for 4.13
+
+//* xref:../installing/...etc. once modules are ready
diff --git a/modules/microshift-k8s-apis.adoc b/modules/microshift-k8s-apis.adoc
@@ -0,0 +1,22 @@
+// Module included in the following assemblies:
+//
+// * microshift_support/microshift-version.adoc
+
+:_content-type: CONCEPT
+[id="microshift-k8s-apis_{context}"]
+= MicroShift Kubernetes APIs
+
+ {product-title} supports the following standard Kubernetes APIs:
+
+NOTE: TABLE IS FOR PLACEMENT ONLY (FPO)
+
+[cols="1,1",options="header"]
+|===
+^| API ^| API group
+| xref:../rest_api/network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[Route]
+| route.openshift.io/v1
+| xref:../rest_api/security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[SecurityContextConstraints]
+| security.openshift.io/v1
+|===
+
+//FIXME: Links are broken, table is incorrectly displaying
diff --git a/modules/microshift-openshift-apis.adoc b/modules/microshift-openshift-apis.adoc
@@ -1,9 +1,10 @@
-:_content-type: ASSEMBLY
-[id="microshift-apis"]
-= MicroShift APIs
-include::_attributes/attributes-microshift.adoc[]
-:context: microshift-apis
-toc::[]
+// Module included in the following assemblies:
+//
+// * // * microshift_troubleshooting/microshift-openshift-apis.adoc
+
+:_content-type: CONCEPT
+[id="microshift-openshift-apis_{context}"]
+= MicroShift OpenShift APIs
 
 In addition to the standard Kubernetes APIs, {product-title} includes a subset of the APIs supported by {OCP}.
 
diff --git a/modules/microshift-version-api.adoc b/modules/microshift-version-api.adoc
@@ -1,13 +1,15 @@
 // Module included in the following assemblies:
 //
-// * microshift_support/microshift-version.adoc
+// * microshift_architecture/microshift-version-api.adoc
+
+:_content-type: CONCEPT
+[id="microshift-version-api_{context}"]
 
-[id="microshift-version-api"]
 = Checking the {product-title} Version via the API
 
 .Procedure
 
-* Using the API, access the `kube-public/microshift-version` ConfigMap to retrieve the same information.
+* To get the version number using the OpenShift CLI (`oc`), view the `kube-public/microshift-version` config map by running the following command:
 
 [source,terminal]
 ----
diff --git a/modules/microshift-version-cli.adoc b/modules/microshift-version-cli.adoc
@@ -2,7 +2,7 @@
 //
 // * microshift_support/microshift-version.adoc
 
-[id="microshift-version-cli"]
+[id="microshift-version-cli_{context}"]
 = Checking the {product-title} Version from the command-line
 
 .Procedure

Original file line number	Diff line number	Diff line change
@@ -18,7 +18,7 @@ Resources such as `DeploymentConfig`, `BuildConfig`, `Route`, `ImageStream`, and
`18`	`18`	`+`
`19`	`19`	`ifndef::microshift[]`
`20`	`20`	The `oc` binary offers a built-in `login` command for authentication and lets you work with {product-title} projects, which map Kubernetes namespaces to authenticated users.
`21`		`-See xref:../../authentication/understanding-authentication.adoc#understanding-authentication[Understanding authentication] for more information.`
	`21`	`+Read xref:../../authentication/understanding-authentication.adoc#understanding-authentication[Understanding authentication] for more information.`
`22`	`22`	`endif::[]`
`23`	`23`	`+`
`24`	`24`	`ifdef::microshift[]`