Merge pull request #5109 from twz123/adr01-formatting-nits

ADR 1: Some formatting nits
k0sproject · Oct 11, 2024 · 66080bf · 66080bf
2 parents 6b72bf4 + 58480b1
commit 66080bf
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 36 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -8,15 +8,15 @@ on:
     paths:
       - '**.md'
       - .github/workflows/docs.yml
-      - .github/workflows/markdownlint-config.jsonc
+      - .markdownlint.jsonc
   pull_request:
     branches:
       - main
       - release-*
     paths:
       - '**.md'
       - .github/workflows/docs.yml
-      - .github/workflows/markdownlint-config.jsonc
+      - .markdownlint.jsonc
 jobs:
   lint:
     name: Lint markdown
@@ -25,6 +25,6 @@ jobs:
       - uses: actions/checkout@v4
       - uses: articulate/actions-markdownlint@v1
         with:
-          config: .github/workflows/markdownlint-config.jsonc
+          config: .markdownlint.jsonc
           ignore: autopilot
           version: 0.42.0
diff --git a/.github/workflows/markdownlint-config.jsonc → .markdownlint.jsonc b/.github/workflows/markdownlint-config.jsonc → .markdownlint.jsonc
@@ -5,6 +5,9 @@
   "first-line-h1": false,
   "single-trailing-newline": false,
   "ol-prefix": "one_or_ordered",
+  "MD010": {
+    "code_blocks": false // Go uses tabs ¯\_(ツ)_/¯
+  },
   "MD033": {
     "allowed_elements": [
       "br" // The br tag is more readable than two trailing spaces.

diff --git a/docs/architecture/adr-001-autopilot-oci-basic-auth-support.md b/docs/architecture/adr-001-autopilot-oci-basic-auth-support.md
@@ -6,12 +6,12 @@ Registries are increasingly being used as generic artifact stores, expanding
 beyond their traditional role of hosting container images. To align with this
 trend, it is beneficial for Autopilot to support pulling artifacts directly
 from registries. Currently, Autopilot's capabilities are limited to downloading
-artifacts via the HTTP[S] protocols.
+artifacts via the HTTP\[S\] protocols.
 
 Enhancing Autopilot to pull artifacts directly from registries will streamline
 workflows and improve efficiency by allowing integration and deployment of
-diverse artifacts without relying solely on HTTP[S] endpoints. This update will
-enable Autopilot to handle registry-specific protocols and authentication
+diverse artifacts without relying solely on HTTP\[S\] endpoints. This update
+will enable Autopilot to handle registry-specific protocols and authentication
 mechanisms, aligning it with modern deployment practices.
 
 Currently, Autopilot does not support the retrieval of artifacts via the HTTP
@@ -31,12 +31,12 @@ Starting with the current `PlanResourceURL` struct:
 
 ```go
 type PlanResourceURL struct {
-        // URL is the URL of a downloadable resource.
-        URL string `json:"url"`
+	// URL is the URL of a downloadable resource.
+	URL string `json:"url"`
 
-        // Sha256 provides an optional SHA256 hash of the URL's content for
-        // verification.
-        Sha256 string `json:"sha256,omitempty"`
+	// Sha256 provides an optional SHA256 hash of the URL's content for
+	// verification.
+	Sha256 string `json:"sha256,omitempty"`
 }
 ```
 
@@ -45,33 +45,35 @@ pulls. This will be achieved by adjusting the struct as follows:
 
 ```go
 type PlanResourceURL struct {
-        // URL is the URL of a downloadable resource.
-        URL string `json:"url"`
-
-        // Sha256 provides an optional SHA256 hash of the URL's content for
-        // verification.
-        Sha256 string `json:"sha256,omitempty"`
-
-        // SecretRef holds a reference to a secret where the credentials are
-        // stored. We use these credentials when pulling the artifacts from the
-        // provided URL using
-        // any of the supported protocols (http, https, and oci).
-        SecretRef *corev1.SecretReference `json:"secretRef,omitempty"`
-
-        // InsecureSkipTLSVerify indicates whether certificates in the remote
-        // URL (if using TLS) can be ignored.
-        InsecureSkipTLSVerify bool  `json:"insecureSkipTLSVerify,omitempty"`
+	// URL is the URL of a downloadable resource.
+	URL string `json:"url"`
+
+	// Sha256 provides an optional SHA256 hash of the URL's content for
+	// verification.
+	Sha256 string `json:"sha256,omitempty"`
+
+	// SecretRef holds a reference to a secret where the credentials are
+	// stored. We use these credentials when pulling the artifacts from the
+	// provided URL using
+	// any of the supported protocols (http, https, and oci).
+	SecretRef *corev1.SecretReference `json:"secretRef,omitempty"`
+
+	// InsecureSkipTLSVerify indicates whether certificates in the remote
+	// URL (if using TLS) can be ignored.
+	InsecureSkipTLSVerify bool `json:"insecureSkipTLSVerify,omitempty"`
 }
 ```
 
 `SecretRef` property is of type `SecretReference` as defined by
 `k8s.io/api/core/v1` package. The secret pointed by the provided `SecretRef`
-will be used for pulling artifacts using either HTTP[S] or OCI protocols and is
-expected to by of type `kubernetes.io/dockerconfigjson` if the protocol in use
-is `oci://` or of type `Opaque` if protocols `http://` or `https://` are used
-(see below for details on the Secret layout).
+will be used for pulling artifacts using either HTTP\[S\] or OCI protocols and
+is expected to by of type `kubernetes.io/dockerconfigjson` if the protocol in
+use is `oci://` or of type `Opaque` if protocols `http://` or `https://` are
+used (see below for details on the Secret layout).
 
-Example configuration for OCI:
+### Example Configurations
+
+#### Configuration for OCI
 
 ```yaml
 url: oci://my.registry/binaries/k0s:v1.30.1+k0s.0
@@ -81,7 +83,7 @@ secretRef:
   name: artifacts-registry
 ```
 
-Example configuration for OCI using plain HTTP transport:
+#### Configuration for OCI using plain HTTP transport
 
 ```yaml
 url: oci+http://my.registry/binaries/k0s:v1.30.1+k0s.0
@@ -91,7 +93,7 @@ secretRef:
   name: artifacts-registry
 ```
 
-Example configuration for HTTPS:
+#### Configuration for HTTPS
 
 ```yaml
 url: https://my.file.server/binaries/k0s-v1.30.1+k0s.0
@@ -101,7 +103,7 @@ secretRef:
   name: artifacts-basic-auth
 ```
 
-Example configuration for HTTP:
+#### Configuration for HTTP
 
 ```yaml
 url: http://my.file.server/binaries/k0s-v1.30.1+k0s.0
@@ -133,7 +135,7 @@ behaviour in case of conflicting configurations:
 
 > In the case where the three properties are set (`username`, `password`, and
 > `authorization`) Autopilot will ignore `username` and `password`, i.e.
-> `authorization`  takes precedence over username and password.
+> `authorization` takes precedence over username and password.
 
 The `authorization` entry is used as is, its content is placed directly into
 the `Authorization` header. For example a secret like the following will make