Merge pull request #594 from dhellmann/markdown-lint

enable markdown linter in this repository

.github/workflows/linter.yml

@@ -0,0 +1,54 @@
+---
+## Linter GitHub Actions ##
+#
+# Taken from https://github.com/github/super-linter
+name: Lint
+
+#
+# Documentation:
+# https://help.github.com/en/articles/workflow-syntax-for-github-actions
+#
+
+#############################
+# Start the job on all push #
+#############################
+on:
+  push:
+    branches-ignore: [master]
+    # Remove the line above to run when pushing to master
+  pull_request:
+    branches: [master]
+
+###############
+# Set the Job #
+###############
+jobs:
+  build:
+    # Name the Job
+    name: Markdown lint
+    # Set the agent to run on
+    runs-on: ubuntu-latest
+
+    ##################
+    # Load all steps #
+    ##################
+    steps:
+      ##########################
+      # Checkout the code base #
+      ##########################
+      - name: Checkout Code
+        uses: actions/checkout@v2
+        with:
+          # Full git history is needed to get a proper list of changed files within `super-linter`
+          fetch-depth: 0
+
+      ################################
+      # Run Linter against code base #
+      ################################
+      - name: Run Linter
+        uses: github/super-linter@v3
+        env:
+          VALIDATE_ALL_CODEBASE: false
+          DEFAULT_BRANCH: master
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VALIDATE_MARKDOWN: true

.gitignore

@@ -2,4 +2,5 @@
 *.swp
 .idea/*
 tools/bin
-tools/cover.out
+tools/cover.out
+super-linter.log

.markdownlint.yaml

@@ -0,0 +1,13 @@
+# See https://github.com/DavidAnson/markdownlint#optionsconfig
+
+# forematter metadata seems to trigger this
+single-title: false
+
+# hard tabs are used when pasting go example code into files
+no-hard-tabs: false
+
+# we commonly paste bare urls in the middle of paragraphs
+no-bare-urls: false
+
+# really, this is a rule?
+commands-show-output: false

CONVENTIONS.md

@@ -62,7 +62,15 @@ experience across web consoles, command line tooling, and documentation.
 
 We prefer clear and consistent names that describe the concepts in a human friendly, terse, and jargon-free manner for all aspects of the system - components, API and code types, and concepts.  Jargon is discouraged as it increases friction for new users. Where possible reuse or combine words that are part of other names when those concepts overlap.
 
-For instance, the core component that rolls out the desired version of an OpenShift cluster is called the cluster-version-operator - it is an "operator" (a term with appropriate context in this domain) that controls the "version" of the "cluster". Other components reuse this pattern - this consistency allows a human to infer similarity and reorient as new or unfamiliar components are introduced over time. Likewise the API object that drives the behavior of the cluster related to versions and upgrades is known as `ClusterVersion` (allowing a human to guess at its function from either direction).
+For instance, the core component that rolls out the desired version of
+an OpenShift cluster is called the cluster-version-operator - it is an
+"operator" (a term with appropriate context in this domain) that
+controls the "version" of the "cluster". Other components reuse this
+pattern - this consistency allows a human to infer similarity and
+reorient as new or unfamiliar components are introduced over
+time. Likewise the API object that drives the behavior of the cluster
+related to versions and upgrades is known as `ClusterVersion`
+(allowing a human to guess at its function from either direction).
 
 Once you have decided on a name for a new component, follow these conventions:
 
@@ -89,7 +97,7 @@ metal3-io](https://github.com/metal3-io/metal3-docs/blob/master/design/bare-meta
 
 OpenShift APIs follow the [Kubernetes API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md).
 
-### Cluster Conventions 
+### Cluster Conventions
 
 A number of rules exist for individual components of the cluster in order to ensure
 the overall goals of the cluster can be achieved. These ensure OpenShift is resilient,
@@ -124,7 +132,7 @@ it is used to manage all elements of the cluster.
 * Every component must remain available to consumers without disruption during upgrades and reconfiguration
   * Disruption caused by node restarts is allowed but must respect disruption policies (PodDisruptionBudget) and should be optimized to reduce total disruption
     * Administrators may control the impact to workloads by pausing machine configuration pools until they wish to take outage windows, which prevents nodes from being restarted
-  * The kube-apiserver and all aggregated APIs must not return errors, reject connections, or pause for abnormal intervals (>5s) during change 
+  * The kube-apiserver and all aggregated APIs must not return errors, reject connections, or pause for abnormal intervals (>5s) during change
     * API servers may close long running connections gracefully (watches, log streams, exec connections) within a reasonable window (60s)
   * Components that support workloads directly must not disrupt end-user workloads during upgrade or reconfiguration
     * E.g. the upgrade of a network plugin must serve pod traffic without disruption (although tiny increases in latency are allowed)
@@ -135,7 +143,13 @@ it is used to manage all elements of the cluster.
 
 All cluster components must declare resource requests for CPU and memory, and should not describe limits.
 
-The CPU request of components scheduled onto the control plane should be proportional to existing etcd limits for a 6 node cluster running the standard e2e suite (if etcd on a control plane component uses 600m during an e2e run, and requests 100m, and the component uses 350m, then the component should request `100m/600m * 350m`).  Components scheduled to all nodes should be proportional to the SDN CPU request during the standard e2e suite.  
+The CPU request of components scheduled onto the control plane should
+be proportional to existing etcd limits for a 6 node cluster running
+the standard e2e suite (if etcd on a control plane component uses 600m
+during an e2e run, and requests 100m, and the component uses 350m,
+then the component should request `100m/600m * 350m`).  Components
+scheduled to all nodes should be proportional to the SDN CPU request
+during the standard e2e suite.
 
 The memory request of cluster components should be set at 10% higher than their p90 memory usage over a standard e2e suite execution.
 

Makefile

@@ -0,0 +1,12 @@
+.PHONY: help
+help:  ## Display this help
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+lint:  ## run the markdown linter
+	podman run \
+		--rm=true \
+		--env RUN_LOCAL=true \
+		--env VALIDATE_MARKDOWN=true \
+		-v \
+		$$(pwd):/tmp/lint \
+		github/super-linter

README.md

@@ -27,7 +27,7 @@ A rough heuristic for an enhancement is anything that:
 
 - impacts how a cluster is operated including addition or removal of significant
   capabilities
-- impacts upgrade/downgrade 
+- impacts upgrade/downgrade
 - needs significant effort to complete
 - requires consensus/code across multiple domains/repositories
 - has phases of maturity (Dev Preview, Tech Preview, GA)
@@ -51,7 +51,7 @@ Create an enhancement here once you:
 - have circulated your idea to see if there is interest
 - (optionally) have done a prototype in your own fork
 - have identified people who agree to work on and maintain the enhancement
-  - many enhancements will take several releases to complete  
+  - many enhancements will take several releases to complete
 
 ## Why are Enhancements Tracked
 

ROADMAP.md

@@ -105,7 +105,7 @@ These stories define the core use cases OpenShift looks to address.
 
 #### Stable Enterprise Kubernetes
 
-As an enterprise IT organization deploying Kubernetes, 
+As an enterprise IT organization deploying Kubernetes,
 I should have a stable and reliable Kubernetes distribution that reduces my support and operational burden while allowing me to meet the organizational, legal, and functional requirements I must work within,
 so that I can quickly evaluate, integrate, and deploy Kubernetest to production.
 
@@ -123,7 +123,7 @@ This includes:
 #### Programmable containerized application deployment environment
 
 As an organization with an existing development pipeline, or one building a new enterprise application
-platform, or as a small to medium sized team using Kubernetes as a deployment target, 
+platform, or as a small to medium sized team using Kubernetes as a deployment target,
 I should expect Kubernetes and the necessary ecosystem components to remain stable over multiple-year timeframes,
 so that I can delivery applications more rapidly, with better operational efficiency, at higher scales, and with better availability.
 
@@ -143,9 +143,9 @@ This includes:
 
 #### Self-service developer platform
 
-As an organization looking to modernize, innovate, or standardize large portions of application development, 
+As an organization looking to modernize, innovate, or standardize large portions of application development,
 I should have tools and patterns that are easily accessible and consumable by a wide range of
-developer skillsets and that allow organizational, operational, or security practices to easily integrate, 
+developer skillsets and that allow organizational, operational, or security practices to easily integrate,
 so that I can rapidly improve my development organization efficiency and react more quickly to business needs.
 
 This includes:
@@ -160,7 +160,7 @@ This includes:
 
 #### Project reliability engineering
 
-As an open-source community and product focused organization, 
+As an open-source community and product focused organization,
 OKD and OpenShift should have a development lifecycle that leverages automation and data capture to rapidly test, release, and
 validate the projects being developed within the product,
 so that we can deliver higher quality software faster to more environments, with less regressions, and with a tighter feedback loop between developer and deployer.
@@ -193,7 +193,7 @@ cannot be realized. A brief sketch of the approach is covered below (in rough or
 2. Make the bootstrap node look more like a full master and have additional masters join
 3. Front the API servers and other master services with service load balancers
 4. Automatically recover when a master machine dies on cloud providers by creating a new machine (machine health check)
-5. Add out-of-the-box metal load balancing support (with metallb project?). 
+5. Add out-of-the-box metal load balancing support (with metallb project?).
 6. Allow masters to be vertically scaled by changing a machine size property and replacing mismatched masters
 7. Add a simple backup recovery experience to etcd operator instances that requires no additional scripting / commands (form new cluster with X after shutting down other workers)
 8. Allow the bootstrap node to be easily transitioned to a worker node post boot (to reduce minimum cluster requirements)

enhancements/README.md

@@ -1 +1,3 @@
+# Enhancements
+
 The README has [moved](../guidelines/README.md).

enhancements/api-review/add-unqualified-search-registries.md

@@ -33,7 +33,7 @@ option called `unqualified-search-registries`. This is the list of registries th
 
 ## Motivation
 
-Today, when a user wants to pull images using short names, they have to create two `machineConfigs` (one for the master pool and one for the worker pool) that create a file under `/etc/containers/registries.conf.d` with the changes they want for `unqualified-search-registries`. 
+Today, when a user wants to pull images using short names, they have to create two `machineConfigs` (one for the master pool and one for the worker pool) that create a file under `/etc/containers/registries.conf.d` with the changes they want for `unqualified-search-registries`.
 
 Users may have multiple internal registries that they use for pulling images. The DNS of these registries could change, and that would require changing the image spec to match this, which can be tedious. Using `unqualified-search-registries` to be able to configure the list of registries to search from allows the user to use short names for image pulls.
 
@@ -46,7 +46,14 @@ Users can currently configure `AllowedRegistries`, `BlockedRegistries`, and `Ins
 
 ### Non-Goals
 
-- Builds and Imagestream Imports will not support the use of short names. There is an added complexity for these components to figure out the correct credentials needed for the short names and the security risks associated with using short names. Since we highly discourage short names, we are only adding support for `unqualified-search-registries` at the runtime level. Users can only use short names in their pod spec and only cri-o/podman will support it.
+- Builds and Imagestream Imports will not support the use of short
+  names. There is an added complexity for these components to figure
+  out the correct credentials needed for the short names and the
+  security risks associated with using short names. Since we highly
+  discourage short names, we are only adding support for
+  `unqualified-search-registries` at the runtime level. Users can only
+  use short names in their pod spec and only cri-o/podman will support
+  it.
 
 ## Proposal
 
@@ -56,7 +63,7 @@ The Image API is extended by adding an optional `UnqualifiedSearchRegistries` fi
 // RegistrySources holds cluster-wide information about how to handle the registries config.
 type RegistrySources struct {
     // ...
-    
+
 	// unqualifiedSearchRegistries are registries that will be searched when pulling images using short names.
 	// +optional
 	UnqualifiedSearchRegistries []string `json:"unqualifiedSearchRegistries,omitempty"`
@@ -88,7 +95,15 @@ The user can run `oc edit images.config.openshift.io cluster` and add `Unqualifi
 
 #### As a user, I would like to use multiple internal registries to pull my images
 
-The user can use multiple internal registries to pull images with short names without having to change the image spec every time that the registries' DNS changes. This can be done by configuring the list of `unqualified-search-registries` to reflect the changes in the internal registries names by running `oc edit images.config.openshift.io cluster` and add `UnqualifiedSearchRegistries` under `RegistrySources`. Once this is done, the containerRuntimeConfig controller will roll out the changes to the nodes.
+The user can use multiple internal registries to pull images with
+short names without having to change the image spec every time that
+the registries' DNS changes. This can be done by configuring the list
+of `unqualified-search-registries` to reflect the changes in the
+internal registries names by running `oc edit
+images.config.openshift.io cluster` and add
+`UnqualifiedSearchRegistries` under `RegistrySources`. Once this is
+done, the containerRuntimeConfig controller will roll out the changes
+to the nodes.
 
 ### Implementation Details/Notes/Constraints
 
@@ -98,7 +113,7 @@ Implementing this enhancement requires changes in:
 
 This is what the `/etc/containers/registries.conf` file currently looks like on the nodes:
 
-```
+```toml
 unqualified-search-registries = ['registry.access.redhat.com', 'docker.io']
 
 [[registry]]
@@ -107,7 +122,7 @@ unqualified-search-registries = ['registry.access.redhat.com', 'docker.io']
 
 This is an example of the cluster wide images.config.openshift.io:
 
-```
+```yaml
 apiVersion: config.openshift.io/v1
 kind: Image
 metadata:
@@ -122,7 +137,7 @@ spec:
 
 The above Image CR will create a drop-in file at `/etc/containers/registries.conf.d` on each file, which will look like:
 
-```
+```toml
 unqualified-search-registries = ['reg1.io', 'reg2.io', 'reg3.io']
 ```
 
@@ -131,7 +146,16 @@ Note: adding a drop-in file at `/etc/containers/registries.conf.d` completely ov
 The new list of `unqualified-search-registries` will be the list specified in the drop-in file at `/etc/containers/registries.conf.d`.
 When a user runs a pod using an image short name, cri-o/podman/buildah will check `reg1.io`, `reg2.io`, and `reg3.io` for any images matching the short name.
 
-Documentations: We will document that we heavily advise against using this feature unless it is absolutely needed due to the security risks. An example case would be when a user has multiple internal registries whose DNS changes frequently, so image short name has to be used in the image spec. We will also document that when you do this, the whole list is overridden and there is no fall back to the default list of `unqualified-search-registries`. We will also document that the `unqualified-search-registries` list will not work with the builds and imagestream imports components. It will only work with the pod spec when using short names.
+Documentations: We will document that we heavily advise against using
+this feature unless it is absolutely needed due to the security
+risks. An example case would be when a user has multiple internal
+registries whose DNS changes frequently, so image short name has to be
+used in the image spec. We will also document that when you do this,
+the whole list is overridden and there is no fall back to the default
+list of `unqualified-search-registries`. We will also document that
+the `unqualified-search-registries` list will not work with the builds
+and imagestream imports components. It will only work with the pod
+spec when using short names.
 
 ### Risks and Mitigations
 
@@ -182,5 +206,3 @@ History`.
 ## Drawbacks
 
 ## Alternatives
-
-

enhancements/api-review/centralized-manifest-openapi-generation.md

@@ -56,7 +56,8 @@ This provides the benefit of allowing these types to be imported with Go modules
 files for those packages.
 
 Example, for config manifests:
-```
+
+```text
 config/
 ├── install.go
 └── v1
@@ -130,4 +131,4 @@ there should not be much need for additional tests as this is essentially an org
 
 ## Drawbacks
 
-## Alternatives
+## Alternatives