From 4e466a4446fa189c0ff85f888b71ad846de4821c Mon Sep 17 00:00:00 2001 From: Tuomo Tanskanen Date: Wed, 24 Jan 2024 12:38:47 +0200 Subject: [PATCH] switch markdownlint container to markdownlint-cli2 cli2 supports inline markdownlint-ignore for local ignoring. Also fix all the markdownlint issues. Signed-off-by: Tuomo Tanskanen --- .markdownlint-cli2.yaml | 9 +++++ CONTRIBUTING.md | 11 ++++-- docs/api.md | 77 ++++++++++++++++++++++--------------- docs/configuration.md | 6 +-- docs/deploying.md | 11 +++--- docs/dev-setup.md | 12 ++++-- hack/markdownlint.sh | 35 ++++++----------- ironic-deployment/README.md | 29 +++++++++----- test/e2e/README.md | 3 +- 9 files changed, 116 insertions(+), 77 deletions(-) create mode 100644 .markdownlint-cli2.yaml diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000000..7811fc6631 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,9 @@ +# Reference: https://github.com/DavidAnson/markdownlint-cli2#markdownlint-cli2yaml + +config: + ul-indent: + # Kramdown wanted us to have 3 earlier, tho this CLI recommends 2 or 4 + indent: 3 + +# Don't autofix anything, we're linting here +fix: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2010bf31b2..a22f7a3f8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,8 +41,9 @@ Commit message should contain signed off section with full name and email. For e Signed-off-by: John Doe ``` -When making commits, include the `-s` flag and `Signed-off-by` section will be automatically -added to your commit message. If you want GPG signing too, add the `-S` flag alongside `-s`. +When making commits, include the `-s` flag and `Signed-off-by` section +will be automatically added to your commit message. If you want GPG +signing too, add the `-S` flag alongside `-s`. ```bash # Signing off commit @@ -112,10 +113,14 @@ the ability to backport and release patch versions; - The EOL date of each API Version is determined from the last release available once a new API version is published. + + | API Version | Maintained Until | | ------------ | ------------------------------------------------------------- | | **v1alpha1** | TBD (current latest) | -| **v1beta1** | Upcoming (Proposal [PR](https://github.com/metal3-io/metal3-docs/pull/332)) | +| **v1beta1** | Upcoming (Proposal [PR](https://github.com/metal3-io/metal3-docs/pull/332)) | + + - For the current stable API version (v1alpha1) we support the two most recent minor releases; older minor releases are immediately unsupported when a new diff --git a/docs/api.md b/docs/api.md index 1f0ed8f132..af8d6c39e7 100644 --- a/docs/api.md +++ b/docs/api.md @@ -29,6 +29,8 @@ The sub-fields are BMC URLs vary based on the type of BMC and the protocol used to communicate with them. + + | Technology | Protocol | Boot method | Format | Notes | |-----------------|----------|---------------|---------------------------------------------------|-------------------------------------------------------------------------| | Generic IPMI | IPMI | iPXE | `ipmi://:` or just `:` | Port is optional, defaults to 623 | @@ -45,6 +47,8 @@ communicate with them. | | Redfish | iPXE | `ilo5-redfish://:/` | | | | Redfish | Virtual media | `ilo5-virtualmedia://:/` | | + + All protocols based on HTTPS (i.e. not IPMI) with an exception of iRMC allow optionally specifying the carrier protocol in the form of `+http` or `+https`, for example: `redfish+http://...` or `idrac-virtualmedia+https`. iLO (both @@ -834,35 +838,44 @@ metadata: ## HardwareData -A **HardwareData** resource contains hardware specifications data of a specific host -and it is tightly coupled to its owner resource BareMetalHost. The data in the HardwareData -comes from Ironic after a successful inspection phase. As such, operator will create HardwareData -resource for a specific BareMetalHost during transitioning phase from inspecting into available -state of the BareMetalHost. HardwareData gets deleted automatically by the operator whenever its -BareMetalHost is deleted. Deprovisioning of the BareMetalHost should not trigger the deletion of -HardwareData, but during next provisioning it can be re-created (with the same name and namespace) -with the latest inspection data retrieved from Ironic. HardwareData holds the same name and namespace -as its corresponding BareMetalHost resource. Currently, HardwareData doesn't have *Status* subresource -but only the *Spec*, which we cover next. +A **HardwareData** resource contains hardware specifications data of a +specific host and it is tightly coupled to its owner resource +BareMetalHost. The data in the HardwareData comes from Ironic after a +successful inspection phase. As such, operator will create HardwareData +resource for a specific BareMetalHost during transitioning phase from +inspecting into available state of the BareMetalHost. HardwareData gets +deleted automatically by the operator whenever its BareMetalHost is +deleted. Deprovisioning of the BareMetalHost should not trigger the +deletion of HardwareData, but during next provisioning it can be +re-created (with the same name and namespace) with the latest inspection +data retrieved from Ironic. HardwareData holds the same name and +namespace as its corresponding BareMetalHost resource. Currently, +HardwareData doesn't have *Status* subresource but only the *Spec*, +which we cover next. ### HardwareData spec -As you probably already noticed, the *Spec* of HardwareData is the same as [.Status.hardware](#hardware) -of the BareMetalHost. However, this behaviour is temporary and eventually we will drop -[.Status.hardware](#hardware) from BareMetalHost and only rely on HardwareData *Spec*. The reason -for having duplication of inspection data at the moment is to avoid breaking the existing deployments. +As you probably already noticed, the *Spec* of HardwareData is the same +as [.Status.hardware](#hardware) of the BareMetalHost. However, this +behaviour is temporary and eventually we will drop +[.Status.hardware](#hardware) from BareMetalHost and only rely on +HardwareData *Spec*. The reason for having duplication of inspection +data at the moment is to avoid breaking the existing deployments. ## PreprovisioningImage -A **PreprovisioningImage** resource is automatically created by baremetal-operator for each BareMetalHost -to ensure creation of a *preprovisioning image* for it. In this context, a preprovisioning image -is an ISO or initramfs file that contains the [Ironic agent](https://docs.openstack.org/ironic-python-agent/). -The relevant parts of BareMetalHost are copied to the PreprovisioningImage *Spec*, +A **PreprovisioningImage** resource is automatically created by +baremetal-operator for each BareMetalHost to ensure creation of a +*preprovisioning image* for it. In this context, a preprovisioning image +is an ISO or initramfs file that contains the [Ironic +agent](https://docs.openstack.org/ironic-python-agent/). The relevant +parts of BareMetalHost are copied to the PreprovisioningImage *Spec*, the resulting image is expected to appear in the *Status*. -The baremetal-operator project contains a simple controller for PreprovisioningImages -that uses images provided in the environment variables `DEPLOY_ISO_URL` and `DEPLOY_RAMDISK_URL`. -More sophisticated controllers may be written downstream (for example, the OpenShift +The baremetal-operator project contains a simple controller for +PreprovisioningImages that uses images provided in the environment +variables `DEPLOY_ISO_URL` and `DEPLOY_RAMDISK_URL`. More sophisticated +controllers may be written downstream (for example, the OpenShift [image-customization-controller](https://github.com/openshift/image-customization-controller)). ### PreprovisioningImage spec @@ -874,8 +887,9 @@ The PreprovisioningImage's spec provides input for the image building process. * `architecture`: the CPU architecture to build the image for, e.g. `x86_64`. The default PreprovisioningImage controller does not use this field. -* `networkData`: the name of a *Secret* with the network configuration for the image. - The default PreprovisioningImage controller does not use this field. +* `networkData`: the name of a *Secret* with the network configuration + for the image. The default PreprovisioningImage controller does not + use this field. ### PreprovisioningImage status @@ -883,15 +897,18 @@ The PreprovisioningImage's status provides information about the resulting image * `architecture`: the CPU architecture of the image, e.g. `x86_64`. -* `extraKernelParams`: additional kernel parameters that baremetal-operator will add to the node - when PXE booting the initramfs image. Has no meaning for ISO images. +* `extraKernelParams`: additional kernel parameters that + baremetal-operator will add to the node when PXE booting the initramfs + image. Has no meaning for ISO images. -* `format`: format of the image: `iso` or `initrd`. Must be one of the formats provided in `acceptFormats`. +* `format`: format of the image: `iso` or `initrd`. Must be one of the + formats provided in `acceptFormats`. * `imageUrl`: the URL of the resulting image. -* `kernelUrl`: the URL of the kernel to use together with the initramfs image. If not provided, - baremetal-operator uses the default kernel image from the environment variables. - Has no meaning for ISO images. +* `kernelUrl`: the URL of the kernel to use together with the initramfs + image. If not provided, baremetal-operator uses the default kernel + image from the environment variables. Has no meaning for ISO images. -* `networkData`: the name of a *Secret* with the network configuration of the image. +* `networkData`: the name of a *Secret* with the network configuration + of the image. diff --git a/docs/configuration.md b/docs/configuration.md index c140ea3654..2421cf3e58 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -42,9 +42,9 @@ but overflows could happen in case of slow provisioners and / or higher number o concurrent reconciles. For such reasons, it is highly recommended to keep BMO_CONCURRENCY value lower than the requested PROVISIONING_LIMIT. Default is 20. -`IRONIC_EXTERNAL_URL_V6` -- This is the URL where Ironic will find the image for -nodes that use IPv6. In dual stack environments, this can be used to tell Ironic which IP -version it should set on the BMC. +`IRONIC_EXTERNAL_URL_V6` -- This is the URL where Ironic will find the +image for nodes that use IPv6. In dual stack environments, this can be +used to tell Ironic which IP version it should set on the BMC. Kustomization Configuration --------------------------- diff --git a/docs/deploying.md b/docs/deploying.md index 5816f3965c..dedc0428af 100644 --- a/docs/deploying.md +++ b/docs/deploying.md @@ -136,11 +136,12 @@ ironic-deployment/ └── README.md ``` -The `ironic-deployment` folder contains kustomizations for deploying Ironic. -It makes use of kustomize components for basic auth, TLS and keepalived configurations. -This makes it easy to combine the configurations, for example basic auth + TLS. -There are some ready made overlays in the `overlays` folder that shows how this can be done. -For more information, check the readme in the `ironic-deployment` folder. +The `ironic-deployment` folder contains kustomizations for deploying +Ironic. It makes use of kustomize components for basic auth, TLS and +keepalived configurations. This makes it easy to combine the +configurations, for example basic auth + TLS. There are some ready made +overlays in the `overlays` folder that shows how this can be done. For +more information, check the readme in the `ironic-deployment` folder. ## Deployment commands diff --git a/docs/dev-setup.md b/docs/dev-setup.md index 80751039de..bff0e10f3f 100644 --- a/docs/dev-setup.md +++ b/docs/dev-setup.md @@ -176,19 +176,25 @@ and specially the [Baremetal Operator Integration](https://github.com/metal3-io/ ### Making (virtual) BareMetalHosts with Tilt interface -Virtinst, libvirt-clients, libvirt-daemon-system, and [Virtualbmc](https://pypi.org/project/virtualbmc/) are required to to create BareMetalHosts this way. The network and VBMC needed for making a BareMetalHosts can be initialized with +Virtinst, libvirt-clients, libvirt-daemon-system, and +[Virtualbmc](https://pypi.org/project/virtualbmc/) are required to to +create BareMetalHosts this way. The network and VBMC needed for making a +BareMetalHosts can be initialized with ```sh tools/bmh_test/run_local_bmh_test_setup.sh ``` -When Tilt is up, it is possible to make BareMetalHosts by pressing a button in the Tilt localhost interface. This is currently only supported for Unix based systems. This button runs the content of file +When Tilt is up, it is possible to make BareMetalHosts by pressing a +button in the Tilt localhost interface. This is currently only supported +for Unix based systems. This button runs the content of file ```sh tools/bmh_test/create_bmh.sh ``` -and adds the values given to the button as arguments. Controlplane host can be created with +and adds the values given to the button as arguments. Controlplane host +can be created with ```sh tools/bmh_test/create_bmh.sh diff --git a/hack/markdownlint.sh b/hack/markdownlint.sh index ab9b9105df..5258d27417 100755 --- a/hack/markdownlint.sh +++ b/hack/markdownlint.sh @@ -1,31 +1,20 @@ -#!/bin/bash - -# TODO: -# Fix these two failures in future commit, and remove the ignore rules -# -# Further documentation is available for these failures: -# - MD029: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md#md029---ordered-list-item-prefix -# - MD013: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md#md013---line-length +#!/bin/sh +# markdownlint-cli2 has config file(s) named .markdownlint-cli2.yaml in the repo set -eux -IS_CONTAINER=${IS_CONTAINER:-false} +IS_CONTAINER="${IS_CONTAINER:-false}" CONTAINER_RUNTIME="${CONTAINER_RUNTIME:-podman}" +# all md files, but ignore .github if [ "${IS_CONTAINER}" != "false" ]; then - TOP_DIR="${1:-.}" - find "${TOP_DIR}" \ - \( -path ./vendor -o -path ./.github \) \ - -prune -o -name '*.md' -exec \ - mdl --style all --warnings \ - --rules "~MD013,~MD029" \ - {} \+ + markdownlint-cli2 "**/*.md" "#.github" else - "${CONTAINER_RUNTIME}" run --rm \ - --env IS_CONTAINER=TRUE \ - --volume "${PWD}:/workdir:ro,z" \ - --entrypoint sh \ - --workdir /workdir \ - docker.io/pipelinecomponents/markdownlint:0.13.0@sha256:9c0cdfb64fd3f1d3bdc5181629b39c2e43b6a52fc9fdc146611e1860845bbae0 \ - /workdir/hack/markdownlint.sh "$@" + "${CONTAINER_RUNTIME}" run --rm \ + --env IS_CONTAINER=TRUE \ + --volume "${PWD}:/workdir:ro,z" \ + --entrypoint sh \ + --workdir /workdir \ + docker.io/pipelinecomponents/markdownlint-cli2:0.9.0@sha256:71370df6c967bae548b0bfd0ae313ddf44bfad87da76f88180eff55c6264098c \ + /workdir/hack/markdownlint.sh "$@" fi diff --git a/ironic-deployment/README.md b/ironic-deployment/README.md index 05aa2b4e7f..f2dc2cb672 100644 --- a/ironic-deployment/README.md +++ b/ironic-deployment/README.md @@ -1,13 +1,24 @@ # Kustomizations for Ironic -This folder contains kustomizations for Ironic. -They are mainly used through the [deploy.sh](../tools/deploy.sh) script, which takes care of generating the necessary config for basic-auth and TLS. +This folder contains kustomizations for Ironic. They are mainly used +through the [deploy.sh](../tools/deploy.sh) script, which takes care of +generating the necessary config for basic-auth and TLS. - **base** - This is the kustomize base that we start from. -- **components** - In here you will find re-usable kustomize components for running Ironic with TLS, basic-auth, keepalived or mariadb. - - **basic-auth** - Enable basic authentication. Note that the basic-auth component is missing the actual credentials. This is on purpose, to make sure that the user is setting the password. - - **tls** - Enable TLS. The TLS component needs to have the proper IP/SAN set for the certificates. - - **keepalived** - Add a keepalived container to the deployment. This is useful when using a VIP for exposing the Ironic endpoint, so that the IP can move with the pod. - - **mariadb** - Use MariaDB instead of SQLite. TLS required for this to work. -- **default** - A minimal, fully working, Ironic kustomization including configmap and password. Use only for development! The DB password is hard coded in the repo and there is no TLS or basic-auth. -- **overlays** - Here you will find ready made overlays that use the above mentioned components. +- **components** - In here you will find re-usable kustomize components + for running Ironic with TLS, basic-auth, keepalived or mariadb. + - **basic-auth** - Enable basic authentication. Note that the + basic-auth component is missing the actual credentials. This is on + purpose, to make sure that the user is setting the password. + - **tls** - Enable TLS. The TLS component needs to have the proper + IP/SAN set for the certificates. + - **keepalived** - Add a keepalived container to the deployment. This + is useful when using a VIP for exposing the Ironic endpoint, so + that the IP can move with the pod. + - **mariadb** - Use MariaDB instead of SQLite. TLS required for this + to work. +- **default** - A minimal, fully working, Ironic kustomization including + configmap and password. Use only for development! The DB password is + hard coded in the repo and there is no TLS or basic-auth. +- **overlays** - Here you will find ready made overlays that use the + above mentioned components. diff --git a/test/e2e/README.md b/test/e2e/README.md index a058ca8a32..fb470749b5 100644 --- a/test/e2e/README.md +++ b/test/e2e/README.md @@ -38,7 +38,8 @@ Ironic. Without any changes, the whole suite (including optional tests) will be Please note, however, that it is quite questionable to call this configuration "end to end". -Fixture provider is configured to be the default one. This is how to run the e2e test suite with it: +Fixture provider is configured to be the default one. This is how to run +the e2e test suite with it: ```bash make test-e2e