Skip to content

Commit

Permalink
switch markdownlint container to markdownlint-cli2
Browse files Browse the repository at this point in the history
cli2 supports inline markdownlint-ignore for local ignoring.
Also fix all the markdownlint issues.

Signed-off-by: Tuomo Tanskanen <tuomo.tanskanen@est.tech>
  • Loading branch information
tuminoid committed Jan 24, 2024
1 parent 7358a8b commit 4e466a4
Show file tree
Hide file tree
Showing 9 changed files with 116 additions and 77 deletions.
9 changes: 9 additions & 0 deletions .markdownlint-cli2.yaml
Original file line number Diff line number Diff line change
@@ -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
11 changes: 8 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,9 @@ Commit message should contain signed off section with full name and email. For e
Signed-off-by: John Doe <jdoe@example.com>
```

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
Expand Down Expand Up @@ -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.

<!-- markdownlint-disable MD013 -->

| 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)) |

<!-- markdownlint-enable MD013 -->

- For the current stable API version (v1alpha1) we support the two most recent
minor releases; older minor releases are immediately unsupported when a new
Expand Down
77 changes: 47 additions & 30 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- markdownlint-disable MD013 -->

| Technology | Protocol | Boot method | Format | Notes |
|-----------------|----------|---------------|---------------------------------------------------|-------------------------------------------------------------------------|
| Generic IPMI | IPMI | iPXE | `ipmi://<host>:<port>` or just `<host>:<port>` | Port is optional, defaults to 623 |
Expand All @@ -45,6 +47,8 @@ communicate with them.
| | Redfish | iPXE | `ilo5-redfish://<host>:<port>/<systemID>` | |
| | Redfish | Virtual media | `ilo5-virtualmedia://<host>:<port>/<systemID>` | |

<!-- markdownlint-enable MD013 -->

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
Expand Down Expand Up @@ -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
Expand All @@ -874,24 +887,28 @@ 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

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.
6 changes: 3 additions & 3 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------------------------
Expand Down
11 changes: 6 additions & 5 deletions docs/deploying.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
12 changes: 9 additions & 3 deletions docs/dev-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <NAME> <VBMC_PORT>
```

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 <NAME> <VBMC_PORT> <CONSUMER> <CONSUMER_NAMESPACE>
Expand Down
35 changes: 12 additions & 23 deletions hack/markdownlint.sh
Original file line number Diff line number Diff line change
@@ -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
29 changes: 20 additions & 9 deletions ironic-deployment/README.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 2 additions & 1 deletion test/e2e/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 4e466a4

Please sign in to comment.