Add initial documentation with with mkdocs

.github/workflows/publish_docs.yaml

@@ -0,0 +1,23 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 'pypy3.9'
+      - uses: actions/cache@v4
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - name: Deploy docs
+        uses: afritzler/mkdocs-gh-pages-action@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.reuse/dep5

@@ -27,6 +27,7 @@ Files:
   test/*
   CONTRIBUTING.md
   PROJECT
+  mkdocs.yml
   .dockerignore
   .golangci.yml
 Copyright: 2024 SAP SE or an SAP affiliate company and IronCore contributors

Makefile

@@ -4,6 +4,9 @@ IMG ?= controller:latest
 # ENVTEST_K8S_VERSION refers to the version of kubebuilder assets to be downloaded by envtest binary.
 ENVTEST_K8S_VERSION = 1.31.0
 
+# Docker image name for the mkdocs based local development setup
+IMAGE=ironcore-dev/boot-operator-docs
+
 # Get the currently used golang install path (in GOPATH/bin, unless GOBIN is set)
 ifeq (,$(shell go env GOBIN))
 GOBIN=$(shell go env GOPATH)/bin
@@ -171,6 +174,7 @@ ENVTEST ?= $(LOCALBIN)/setup-envtest-$(ENVTEST_VERSION)
 GOLANGCI_LINT = $(LOCALBIN)/golangci-lint-$(GOLANGCI_LINT_VERSION)
 ADDLICENSE ?= $(LOCALBIN)/addlicense
 GOIMPORTS ?= $(LOCALBIN)/goimports-$(GOIMPORTS_VERSION)
+GEN_CRD_API_REFERENCE_DOCS ?= $(LOCALBIN)/gen-crd-api-reference-docs-$(GEN_CRD_API_REFERENCE_DOCS_VERSION)
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v5.3.0
@@ -179,6 +183,7 @@ ENVTEST_VERSION ?= latest
 GOLANGCI_LINT_VERSION ?= v1.61.0
 ADDLICENSE_VERSION ?= v1.1.1
 GOIMPORTS_VERSION ?= v0.26.0
+GEN_CRD_API_REFERENCE_DOCS_VERSION ?= v0.3.0
 
 .PHONY: kustomize
 kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
@@ -200,6 +205,16 @@ golangci-lint: $(GOLANGCI_LINT) ## Download golangci-lint locally if necessary.
 $(GOLANGCI_LINT): $(LOCALBIN)
 	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,${GOLANGCI_LINT_VERSION})
 
+
+.PHONY: startdocs
+startdocs: ## Start the local mkdocs based development environment.
+	docker build -t $(IMAGE) -f docs/Dockerfile . --load
+	docker run -p 8000:8000 -v `pwd`/:/docs $(IMAGE)
+
+.PHONY: cleandocs
+cleandocs: ## Remove all local mkdocs Docker images (cleanup).
+	docker container prune --force --filter "label=project=boot_operator"
+
 .PHONY: addlicense
 addlicense: $(ADDLICENSE) ## Download addlicense locally if necessary.
 $(ADDLICENSE): $(LOCALBIN)
@@ -210,6 +225,15 @@ goimports: $(GOIMPORTS) ## Download goimports locally if necessary.
 $(GOIMPORTS): $(LOCALBIN)
 	$(call go-install-tool,$(GOIMPORTS),golang.org/x/tools/cmd/goimports,$(GOIMPORTS_VERSION))
 
+.PHONY: docs
+docs: gen-crd-api-reference-docs ## Run go generate to generate API reference documentation.
+	$(GEN_CRD_API_REFERENCE_DOCS) -api-dir ./api/v1alpha1 -config ./hack/api-reference/config.json -template-dir ./hack/api-reference/template -out-file ./docs/api-reference/api.md
+
+.PHONY: gen-crd-api-reference-docs
+gen-crd-api-reference-docs: $(GEN_CRD_API_REFERENCE_DOCS) ## Download gen-crd-api-reference-docs locally if necessary.
+$(GEN_CRD_API_REFERENCE_DOCS): $(LOCALBIN)
+	$(call go-install-tool,$(GEN_CRD_API_REFERENCE_DOCS),github.com/ahmetb/gen-crd-api-reference-docs,$(GEN_CRD_API_REFERENCE_DOCS_VERSION))
+
 # go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
 # $1 - target path with name of binary (ideally with version)
 # $2 - package url which can be installed

docs/Dockerfile

@@ -0,0 +1,14 @@
+FROM squidfunk/mkdocs-material:latest
+
+LABEL project=boot_operator
+
+WORKDIR /docs
+
+COPY docs/requirements.txt requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+EXPOSE 8000
+
+# Start development server by default
+ENTRYPOINT ["mkdocs"]
+CMD ["serve", "--dev-addr=0.0.0.0:8000"]

docs/README.md

@@ -0,0 +1,51 @@
+# Metal-Operator Documentation
+
+**Welcome to the Metal-Operator Documentation!**
+
+The `metal-operator` is a Kubernetes-native operator, part of the IronCore open-source project, designed for robust bare metal infrastructure management. By leveraging Baseboard Management Controllers (BMCs) and the Redfish API, `metal-operator` enables streamlined and automated server discovery, provisioning, and lifecycle management. Using the Kubernetes Controller pattern, `metal-operator` provides a CRD-based operational model that standardizes bare metal management across different hardware environments. Integration with vendor-specific tooling is also possible for enhanced functionality when needed.
+
+---
+
+## Key Features
+
+### 1. **Discover and Onboard Bare Metal Servers**
+- Automatically detect and register bare metal servers through BMCs and the Redfish API.
+- Efficiently gather hardware specs, network configurations, and initial health checks directly from BMC interfaces.
+
+### 2. **Provision Software on Bare Metal Servers**
+- Deploy and configure software on registered servers using BMC interactions and standardized provisioning workflows.
+- Support for dynamic software configuration and Redfish API-based management for consistent, vendor-neutral provisioning.
+
+### 3. **Manage Server Reservations**
+- Reserve specific bare metal resources based on workload needs.
+- Prevent resource conflicts by managing reservations via Kubernetes-native CRDs, ensuring that workloads align with available hardware resources.
+
+### 4. **Perform Day 2 Operations**
+- Utilize the Redfish API to manage BIOS, firmware, and driver updates.
+- Automate ongoing maintenance tasks and operational workflows to maintain infrastructure resilience and uptime.
+
+### 5. **Decommission and Maintain Faulty Servers**
+- Decommission servers via BMC controls for clean removal from active pools.
+- Schedule and perform maintenance tasks with BMC data to optimize uptime and maintain hardware reliability.
+
+---
+
+## How It Works
+
+The `metal-operator` relies on **BMCs and the Redfish API** to handle bare metal server management tasks. Through a CRD-based operational model, `metal-operator` provides Kubernetes-native management of bare metal infrastructure, enabling consistent, vendor-neutral interactions.
+
+### Core Components
+- **Custom Resources (CRs)**: Extend Kubernetes to manage server configurations, reservations, and operational workflows.
+- **Controllers**: Automate lifecycle management through Redfish-enabled interactions, from provisioning to decommissioning.
+- **Reconcilers**: Ensure the desired state matches the actual state by continuously monitoring hardware via BMC integrations.
+
+### Architecture Overview
+
+1. **Discovery**: Register new bare metal servers through BMCs and Redfish API, creating CRDs for streamlined management.
+2. **Provisioning**: Apply software images and configurations using Redfish API, based on templates or custom configurations.
+3. **Operations**: Execute BIOS, firmware updates, and other maintenance tasks through standardized workflows.
+4. **Decommissioning**: Safely remove or maintain servers using Redfish and BMC controls, marking them for reuse or retirement as needed.
+
+---
+
+The `metal-operator` is a core component of the IronCore project, designed to simplify and automate bare metal management across various hardware environments using BMC and Redfish API integrations. Expect continuous updates to expand capabilities and enhance usability.

docs/architecture.md

@@ -0,0 +1,24 @@
+# Boot-Operator Architectural Description
+
+## Architectural Diagram
+
+TBD
+
+## Key Components
+
+### 1. Custom Resource Definitions (CRDs)
+
+- [**IPXEBootConfiguration**](concepts/ipxebootconfig.md): TBD
+- [**HTTPBootConfiguration**](concepts/httpbootconfig.md): TBD
+
+### 2. Controllers
+
+TBD
+
+## Workflow Summary
+
+TBD
+
+## Architectural Benefits
+
+TBD

docs/development/dev_docs.md

@@ -0,0 +1,15 @@
+# metal-operator documentation
+
+## Local dev setup
+
+You can run the documentation via:
+
+```shell
+make startdocs
+```
+
+You can remove the `mkdocs` container image by running:
+
+```shell
+make cleandocs
+```

docs/requirements.txt

@@ -0,0 +1 @@
+# your mkdocs plugins go here

hack/api-reference/config.json

@@ -0,0 +1,32 @@
+{
+  "hideMemberFields": [
+    "TypeMeta"
+  ],
+  "hideTypePatterns": [
+    "ParseError$",
+    "List$"
+  ],
+  "externalPackages": [
+    {
+      "typeMatchPrefix": "^net/netip",
+      "docsURLTemplate": "https://pkg.go.dev/net/netip#{{.TypeIdentifier}}"
+    },
+    {
+      "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/api/resource",
+      "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#{{.TypeIdentifier}}"
+    },
+    {
+      "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/types",
+      "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/types#{{.TypeIdentifier}}"
+    },
+    {
+      "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/",
+      "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
+    }
+  ],
+  "typeDisplayNamePrefixOverrides": {
+    "k8s.io/api/": "Kubernetes ",
+    "k8s.io/apimachinery/pkg/apis/": "Kubernetes "
+  },
+  "markdownDisabled": false
+}

hack/api-reference/template/members.tpl

@@ -0,0 +1,48 @@
+{{ define "members" }}
+
+{{ range .Members }}
+{{ if not (hiddenMember .)}}
+<tr>
+    <td>
+        <code>{{ fieldName . }}</code><br/>
+        <em>
+            {{ if linkForType .Type }}
+                <a href="{{ linkForType .Type}}">
+                    {{ typeDisplayName .Type }}
+                </a>
+            {{ else }}
+                {{ typeDisplayName .Type }}
+            {{ end }}
+        </em>
+    </td>
+    <td>
+        {{ if fieldEmbedded . }}
+            <p>
+                (Members of <code>{{ fieldName . }}</code> are embedded into this type.)
+            </p>
+        {{ end}}
+
+        {{ if isOptionalMember .}}
+            <em>(Optional)</em>
+        {{ end }}
+
+        {{ safe (renderComments .CommentLines) }}
+
+    {{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
+        Refer to the Kubernetes API documentation for the fields of the
+        <code>metadata</code> field.
+    {{ end }}
+
+    {{ if or (eq (fieldName .) "spec") }}
+        <br/>
+        <br/>
+        <table>
+            {{ template "members" .Type }}
+        </table>
+    {{ end }}
+    </td>
+</tr>
+{{ end }}
+{{ end }}
+
+{{ end }}

hack/api-reference/template/pkg.tpl

@@ -0,0 +1,48 @@
+{{ define "packages" }}
+
+{{ with .packages}}
+<p>Packages:</p>
+<ul>
+    {{ range . }}
+    <li>
+        <a href="#{{- packageAnchorID . -}}">{{ packageDisplayName . }}</a>
+    </li>
+    {{ end }}
+</ul>
+{{ end}}
+
+{{ range .packages }}
+    <h2 id="{{- packageAnchorID . -}}">
+        {{- packageDisplayName . -}}
+    </h2>
+
+    {{ with (index .GoPackages 0 )}}
+        {{ with .DocComments }}
+        <div>
+            {{ safe (renderComments .) }}
+        </div>
+        {{ end }}
+    {{ end }}
+
+    Resource Types:
+    <ul>
+    {{- range (visibleTypes (sortedTypes .Types)) -}}
+        {{ if isExportedType . -}}
+        <li>
+            <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
+        </li>
+        {{- end }}
+    {{- end -}}
+    </ul>
+
+    {{ range (visibleTypes (sortedTypes .Types))}}
+        {{ template "type" .  }}
+    {{ end }}
+    <hr/>
+{{ end }}
+
+<p><em>
+    Generated with <code>gen-crd-api-reference-docs</code>
+</em></p>
+
+{{ end }}