Merge pull request #50054 from dhellmann/microshift-poc

kalexand-rh · web-flow · commit 1f901991c547 · 2022-11-03T17:03:01.000-04:00
USHIFT-267: stubs for MicroShift product documentation
diff --git a/.travis.yml b/.travis.yml
@@ -38,6 +38,17 @@ jobs:
         - pip3 install aura.tar.gz
       script:
         - python3 build.py --distro openshift-rosa --product "Red Hat OpenShift Service on AWS" --version 4 --no-upstream-fetch && python3 makeBuild.py
+    - # stage name not required, will continue to use `build`
+      if: branch IN (main, enterprise-4.12)
+      name: "Build microshift distro"
+      before_install:
+        - gem install asciidoctor
+        - gem install asciidoctor-diagram
+      install:
+        - pip3 install pyyaml
+        - pip3 install aura.tar.gz
+      script:
+        - python3 build.py --distro microshift --product "MicroShift" --version 4 --no-upstream-fetch && python3 makeBuild.py
     - stage: check-with-vale
       if: type IN (pull_request)
       name: "Run Vale against PR asciidoc files"
diff --git a/_attributes/attributes-microshift.adoc b/_attributes/attributes-microshift.adoc
@@ -0,0 +1,8 @@
+// common attributes
+:toc:
+:toc-title:
+:experimental:
+:imagesdir: images
+:OCP: OpenShift Container Platform
+:op-system-first: Red Hat Enterprise Linux for Edge (RHEL for Edge)
+:op-system: RHEL for Edge
diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml
@@ -0,0 +1,149 @@
+# This configuration file dictates the organization of the topic groups and
+# topics on the main page of the doc site for this branch. Each record
+# consists of the following:
+#
+# ---                                  <= Record delimiter
+# Name: Origin of the Species          <= Display name of topic group
+# Dir:  origin_of_the_species          <= Directory name of topic group
+# Topics:
+#   - Name: The Majestic Marmoset      <= Topic name
+#     File: the_majestic_marmoset      <= Topic file under group dir +/-
+#   - Name: The Curious Crocodile      <= Topic 2 name
+#     File: the_curious_crocodile      <= Topic 2 file
+#   - Name: The Numerous Nematodes     <= Sub-topic group name
+#     Dir: the_numerous_nematodes      <= Sub-topic group dir
+#     Topics:
+#       - Name: The Wily Worm          <= Sub-topic name
+#         File: the_wily_worm          <= Sub-topic file under <group dir>/<subtopic dir>
+#       - Name: The Acrobatic Ascarid  <= Sub-topic 2 name
+#         File: the_acrobatic_ascarid  <= Sub-topic 2 file under <group dir>/<subtopic dir>
+#
+# The ordering of the records in this document determines the ordering of the
+# topic groups and topics on the main page.
+
+---
+Name: About
+Dir: welcome
+Distros: microshift
+Topics:
+- Name: Welcome
+  File: index
+- Name: Legal notice
+  File: legal-notice
+---
+Name: Introduction to MicroShift
+Dir: microshift_architecture
+Distros: microshift
+Topics:
+- Name: Understanding MicroShift
+  File: microshift-understanding
+- Name: MicroShift APIs
+  File: microshift-apis
+---
+# Name: Release notes
+# Dir: release_notes
+# Distros: microshift
+# Topics:
+# - Name: MicroShift 4.12 release notes
+#   File: microshift-4-12-release-notes
+# ---
+Name: Installing
+Dir: microshift_install
+Distros: microshift
+Topics:
+- Name: Installing MicroShift from RPM
+  File: microshift-install-rpm
+- Name: Installing MicroShift in a RHEL for Edge Image
+  File: microshift-install-rhel-for-edge
+---
+Name: API reference
+Dir: rest_api
+Distros: microshift
+Topics:
+- Name: Network APIs
+  Dir: network_apis
+  Topics:
+    # FIXME: need to incorporate the supported k8s APIs
+  - Name: 'Route [route.openshift.io/v1]'
+    File: route-route-openshift-io-v1
+- Name: Security APIs
+  Dir: security_apis
+  Topics:
+  - Name: 'SecurityContextConstraints [security.openshift.io/v1]'
+    File: securitycontextconstraints-security-openshift-io-v1
+---
+Name: CLI tools
+Dir: cli_reference
+Distros: microshift
+Topics:
+- Name: CLI tools overview
+  File: index
+- Name: OpenShift CLI (oc)
+  Dir: openshift_cli
+  Topics:
+  - Name: Getting started with the OpenShift CLI
+    File: getting-started-cli
+  - Name: Configuring the OpenShift CLI
+    File: configuring-cli
+  - Name: Managing CLI profiles
+    File: managing-cli-profiles
+  - Name: Extending the OpenShift CLI with plug-ins
+    File: extending-cli-plugins
+  # FIXME: auto-generated content in the next file includes commands
+  # not supported on MicroShift
+  - Name: OpenShift CLI developer command reference
+    File: developer-cli-commands
+  # FIXME: Review the commands we expect to support in this file
+  # - Name: OpenShift CLI administrator command reference
+  #   File: administrator-cli-commands
+  #   Distros: openshift-enterprise,openshift-origin
+  - Name: Usage of oc and kubectl commands
+    File: usage-oc-kubectl
+# ---
+# Name: Storage
+# Dir: storage
+# Distros: microshift
+# Topics:
+# - Name: Persistent storage
+#   Dir: persistent_storage
+#   Topics:
+#   - Name: Persistent storage using ODF-LVM
+#     File: microshift-persistent-storage-odf-lvm
+# ---
+# Name: Networking
+# Dir: networking
+# Distros: microshift
+# Topics:
+# - Name: Understanding the Ingress Operator
+#   File: ingress-operator
+# - Name: Configuring a cluster-wide proxy during installation
+#   File: configuring-cluster-wide-proxy
+# - Name: CIDR range definitions
+#   File: cidr-range-definitions
+# - Name: Network policy
+#   Dir: network_policy
+#   Topics:
+#   - Name: About network policy
+#     File: about-network-policy
+#   - Name: Creating a network policy
+#     File: creating-network-policy
+#   - Name: Viewing a network policy
+#     File: viewing-network-policy
+#   - Name: Deleting a network policy
+#     File: deleting-network-policy
+#   - Name: Configuring multitenant isolation with network policy
+#     File: multitenant-network-policy
+# ---
+# Name: Updating clusters
+# Dir: updating
+# Distros: microshift
+# Topics:
+# - Name: Updating MicroShift Clusters
+#   File: TBD
+---
+Name: Troubleshooting
+Dir: microshift_support
+Distros: microshift
+Topics:
+- Name: Checking the MicroShift Version
+  File: microshift-version
diff --git a/cli_reference/index.adoc b/cli_reference/index.adoc
@@ -10,9 +10,11 @@ A user performs a range of operations while working on {product-title} such as t
 
 * Managing clusters
 * Building, deploying, and managing applications
+ifndef::microshift[]
 * Managing deployment processes
 * Developing Operators
 * Creating and maintaining Operator catalogs
+endif::[]
 
 {product-title} offers a set of command-line interface (CLI) tools that simplify these tasks by enabling users to perform various administration and development operations from the terminal.
 These tools expose simple commands to manage the applications, as well as interact with each component of the system.
@@ -24,10 +26,12 @@ The following set of CLI tools are available in {product-title}:
 
 * xref:../cli_reference/openshift_cli/getting-started-cli.adoc#cli-getting-started[OpenShift CLI (oc)]: This is the most commonly used CLI tool by {product-title} users. It helps both cluster administrators and developers to perform end-to-end operations across {product-title} using the terminal. Unlike the web console, it allows the user to work directly with the project source code using command scripts.
 
+ifndef::microshift[]
 * xref:../cli_reference/kn-cli-tools.adoc#kn-cli-tools[Knative CLI (kn)]: The Knative (`kn`) CLI tool provides simple and intuitive terminal commands that can be used to interact with OpenShift Serverless components, such as Knative Serving and Eventing.
 
 * xref:../cli_reference/tkn_cli/installing-tkn.adoc#installing-tkn[Pipelines CLI (tkn)]: OpenShift Pipelines is a continuous integration and continuous delivery (CI/CD) solution in {product-title}, which internally uses Tekton. The `tkn` CLI tool provides simple and intuitive commands to interact with OpenShift Pipelines using the terminal.
 
 * xref:../cli_reference/opm/cli-opm-install.adoc#cli-opm-install[opm CLI]: The `opm` CLI tool helps the Operator developers and cluster administrators to create and maintain the catalogs of Operators from the terminal.
 
 * xref:../cli_reference/osdk/cli-osdk-install.adoc#cli-osdk-install[Operator SDK]: The Operator SDK, a component of the Operator Framework, provides a CLI tool that Operator developers can use to build, test, and deploy an Operator from the terminal. It simplifies the process of building Kubernetes-native applications, which can require deep, application-specific operational knowledge.
+endif::microshift[]
diff --git a/cli_reference/openshift_cli/getting-started-cli.adoc b/cli_reference/openshift_cli/getting-started-cli.adoc
@@ -17,6 +17,7 @@ You can install the OpenShift CLI (`oc`) either by downloading the binary or by
 // Installing the CLI by downloading the binary
 include::modules/cli-installing-cli.adoc[leveloffset=+2]
 
+ifndef::microshift[]
 // Installing the CLI by using the web console
 include::modules/cli-installing-cli-web-console.adoc[leveloffset=+2]
 
@@ -28,6 +29,7 @@ include::modules/cli-installing-cli-web-console-windows.adoc[leveloffset=+3]
 
 // Installing the CLI on macOS by using the web console
 include::modules/cli-installing-cli-web-console-macos.adoc[leveloffset=+3]
+endif::microshift[]
 
 ifndef::openshift-origin[]
 // Installing the CLI by using an RPM
diff --git a/cli_reference/openshift_cli/managing-cli-profiles.adoc b/cli_reference/openshift_cli/managing-cli-profiles.adoc
@@ -6,7 +6,14 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-A CLI configuration file allows you to configure different profiles, or contexts, for use with the xref:../../cli_reference/index.adoc#cli-tools-overview[CLI tools overview]. A context consists of xref:../../authentication/understanding-authentication.adoc#understanding-authentication[user authentication] and {product-title} server information associated with a _nickname_.
+A CLI configuration file allows you to configure different profiles, or contexts, for use with the xref:../../cli_reference/index.adoc#cli-tools-overview[CLI tools overview]. A context consists of
+ifndef::microshift[]
+xref:../../authentication/understanding-authentication.adoc#understanding-authentication[user authentication]
+endif::[]
+ifdef::microshift[]
+user authentication
+endif::[]
+and {product-title} server information associated with a _nickname_.
 
 include::modules/about-cli-profiles-switch.adoc[leveloffset=+1]
 
diff --git a/cli_reference/openshift_cli/usage-oc-kubectl.adoc b/cli_reference/openshift_cli/usage-oc-kubectl.adoc
@@ -16,7 +16,10 @@ Resources such as `DeploymentConfig`, `BuildConfig`, `Route`, `ImageStream`, and
 +
 * **Authentication**
 +
-The `oc` binary offers a built-in `login` command that allows authentication and enables you to 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.
+The `oc` binary offers a built-in `login` command that allows authentication and enables you to work with {product-title} projects, which map Kubernetes namespaces to authenticated users.
+ifndef::microshift[]
+See xref:../../authentication/understanding-authentication.adoc#understanding-authentication[Understanding authentication] for more information.
+endif::[]
 +
 * **Additional commands**
 +
diff --git a/microshift_architecture/attributes b/microshift_architecture/attributes
@@ -0,0 +1 @@
+../../_attributes/
diff --git a/microshift_architecture/images b/microshift_architecture/images
@@ -0,0 +1 @@
+../../images/
diff --git a/microshift_architecture/microshift-apis.adoc b/microshift_architecture/microshift-apis.adoc
@@ -0,0 +1,17 @@
+:_content-type: ASSEMBLY
+[id="microshift-apis"]
+= MicroShift APIs
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-apis
+toc::[]
+
+In addition to the standard Kubernetes APIs, {product-title} includes a subset of the APIs supported by {OCP}.
+
+[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
+|===
diff --git a/microshift_architecture/microshift-understanding.adoc b/microshift_architecture/microshift-understanding.adoc
@@ -0,0 +1,21 @@
+:_content-type: ASSEMBLY
+[id="microshift-understanding"]
+= Understanding MicroShift
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-understanding
+toc::[]
+
+Learn about {product-title}, interacting with {product-title} the command-line interface (CLI) tools, consumption experience, and integration with {op-system-first}.
+
+[id="microshift-understanding-about_{context}"]
+== About MicroShift
+
+MicroShift is a distribution of {OCP} optimized for small form factor and edge computing.
+
+Edge devices deployed in the field pose very different operational, environmental, and business challenges from those of cloud computing. These challenges motivate different engineering trade-offs for Kubernetes at the far edge than for cloud or near-edge scenarios. MicroShift's design goals cater to this:
+
+* Make frugal use of system resources, such as CPU, memory, network, and storage
+* Tolerate severe networking constraints
+* Update securely, safely, quickly, and seamlessly, without disrupting workloads
+* Extend and integrate cleanly with edge-optimized operating systems, like Fedora IoT and {op-system-first}
+* Provide a consistent development and management experience with other distributions of {OCP}
diff --git a/microshift_architecture/modules b/microshift_architecture/modules
@@ -0,0 +1 @@
+../../modules/
diff --git a/microshift_architecture/snippets b/microshift_architecture/snippets
@@ -0,0 +1 @@
+../../snippets/
diff --git a/microshift_install/attributes b/microshift_install/attributes
@@ -0,0 +1 @@
+../../_attributes/
diff --git a/microshift_install/images b/microshift_install/images
@@ -0,0 +1 @@
+../../images/
diff --git a/microshift_install/microshift-install-rhel-for-edge.adoc b/microshift_install/microshift-install-rhel-for-edge.adoc
@@ -0,0 +1,8 @@
+:_content-type: ASSEMBLY
+[id="microshift-install-rhel-for-edge"]
+= Installing MicroShift in a RHEL for Edge Image
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-install-rhel-for-edge
+toc::[]
+
+// The content of this file should be based on https://github.com/openshift/microshift/blob/main/docs/rhel4edge_iso.md
diff --git a/microshift_install/microshift-install-rpm.adoc b/microshift_install/microshift-install-rpm.adoc
@@ -0,0 +1,8 @@
+:_content-type: ASSEMBLY
+[id="microshift-install-rpm"]
+= Installing MicroShift from RPM
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-install-rpm
+toc::[]
+
+// The content of this file should be based on https://github.com/openshift/microshift/blob/main/docs/devenv_rhel8.md but without the steps for building from source.
diff --git a/microshift_install/modules b/microshift_install/modules
@@ -0,0 +1 @@
+../../modules/
diff --git a/microshift_install/snippets b/microshift_install/snippets
@@ -0,0 +1 @@
+../../snippets/
diff --git a/microshift_support/attributes b/microshift_support/attributes
@@ -0,0 +1 @@
+../../_attributes/
diff --git a/microshift_support/images b/microshift_support/images
@@ -0,0 +1 @@
+../../images/
diff --git a/microshift_support/microshift-version.adoc b/microshift_support/microshift-version.adoc
@@ -0,0 +1,48 @@
+:_content-type: ASSEMBLY
+[id="microshift-version"]
+= MicroShift Version
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-version
+toc::[]
+
+[id="microshift-version-cli"]
+== Checking the MicroShift Version from the command line
+
+From the command line, use `microshift version` to check the version information.
+
+[source,terminal]
+----
+$ microshift version
+----
+
+.Example output
+[source,terminal]
+----
+MicroShift Version: 4.10.0-0.microshift-e6980e25
+Base OCP Version: 4.10.18
+----
+
+[id="microshift-version-api"]
+== Checking the MicroShift Version via the API
+
+Through the API, access the `kube-public/microshift-version` ConfigMap to retrieve the same information.
+
+[source,terminal]
+----
+$ oc get configmap -n kube-public microshift-version -o yaml
+----
+
+.Example output
+[source,terminal]
+----
+apiVersion: v1
+data:
+  major: "4"
+  minor: "10"
+  version: 4.10.0-0.microshift-e6980e25
+kind: ConfigMap
+metadata:
+  creationTimestamp: "2022-08-08T21:06:11Z"
+  name: microshift-version
+  namespace: kube-public
+----
diff --git a/microshift_support/modules b/microshift_support/modules
@@ -0,0 +1 @@
+../../modules/
diff --git a/microshift_support/snippets b/microshift_support/snippets
@@ -0,0 +1 @@
+../../snippets/
diff --git a/modules/cli-about-cli.adoc b/modules/cli-about-cli.adoc
@@ -10,4 +10,9 @@ With the OpenShift command-line interface (CLI), the `oc` command, you can creat
 
 * Working directly with project source code
 * Scripting {product-title} operations
+ifndef::microshift[]
 * Managing projects while restricted by bandwidth resources and the web console is unavailable
+endif::microshift[]
+ifdef::microshift[]
+* Managing projects while restricted by bandwidth resources
+endif::microshift[]
diff --git a/modules/cli-using-cli.adoc b/modules/cli-using-cli.adoc
diff --git a/welcome/index.adoc b/welcome/index.adoc

Original file line number	Diff line number	Diff line change
@@ -16,7 +16,10 @@ Resources such as `DeploymentConfig`, `BuildConfig`, `Route`, `ImageStream`, and
`16`	`16`	`+`
`17`	`17`	`* Authentication`
`18`	`18`	`+`
`19`		-The `oc` binary offers a built-in `login` command that allows authentication and enables you to 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.
	`19`	+The `oc` binary offers a built-in `login` command that allows authentication and enables you to work with {product-title} projects, which map Kubernetes namespaces to authenticated users.
	`20`	`+ifndef::microshift[]`
	`21`	`+See xref:../../authentication/understanding-authentication.adoc#understanding-authentication[Understanding authentication] for more information.`
	`22`	`+endif::[]`
`20`	`23`	`+`
`21`	`24`	`* Additional commands`
`22`	`25`	`+`