Create a minimum documentation page (kubernetes-sigs#68)

* Create a minimum documentation page Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com> * parametize docs dependant of version Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com> * docs: show full version number in sidebar Change the sidebar customization so that the full version (e.g. v0.2.0) is displayed, instead of the truncated "releae branch version" (e.g. v0.2) in the top left corner of the page. The items in the version menu are unchanged and will still show the shorter form. Cherry picked from node-feature-discovery repo commit 4d19e1ab85b6cf4c6a2f6e556bf04654e4fb238e. * beat yamllinter remove the whitespace (around the template variable) to prevent needing to split the reference into multiple lines Co-authored-by: Markus Lehtonen <markus.lehtonen@intel.com> * Create a minimum documentation page Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com> * parametize docs dependant of version Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com> * use production image Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com> * use operand_version for doc config Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com> * use container_image as example IMAGE_TAG Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com> * use release to force a better git clone Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com> * add small documentation to variable on config site Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com> * last fixes or I will unfriend Markus Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com> Co-authored-by: Markus Lehtonen <markus.lehtonen@intel.com> Co-authored-by: Kubernetes Prow Robot <k8s-ci-robot@users.noreply.github.com> Signed-off-by: Carlos Eduardo Arango Gutierrez <carangog@redhat.com>
ArangoGutierrez · Jun 2, 2021 · c1c3084 · c1c3084
1 parent c5c6060
commit c1c3084
Show file tree

Hide file tree

Showing 11 changed files with 356 additions and 66 deletions.
diff --git a/README.md b/README.md
@@ -3,6 +3,10 @@
 The Node Feature Discovery operator manages detection of hardware features and configuration in a kubernetes cluster.
 The operator orchestrates all resources needed to run the [Node-Feature-Discovery](https://github.com/kubernetes-sigs/node-feature-discovery) DaemonSet
 
+Welcome to Node Feature Discovery Operator!
+
+### See our [Documentation][documentation] for detailed instructions and reference
+
 ## Community, discussion, contribution, and support
 
 Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
@@ -12,63 +16,8 @@ You can reach the maintainers of this project at:
 - [Slack channel](https://kubernetes.slack.com/messages/node-feature-discovery)
 - [Mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-node)
 
-
-## Building the operator
-
-Checkout the sources
-
-```bash
-$ git clone https://github.com/kubernetes-sigs/node-feature-discovery-operator
-```
-
-Build the operator image
-
-```bash
-IMAGE_REGISTRY=<my registry>
-make image 
-```
-
-Optionally you can push it to your image repo
-
-```bash
-IMAGE_REGISTRY=<my registry>
-make push
-```
-
-Alternatively, instead of specifying variables on the command line, you can edit the Makefile to permanently change parameter defaults like name of the image or namespace where the operator is deployed.
-
-## Manual deploy of the operator
-
-The default `NodeFeatureDiscovery` CR will create the operand (NFD) in the `node-feature-discovery-operator` namespace,
-also an empty [nfd-worker-conf](https://kubernetes-sigs.github.io/node-feature-discovery/v0.6/get-started/deployment-and-usage.html#configuration),
-the CR can be edited to choose another namespace, image, imagePullPolicy and nfd-worker-conf. See the `manifests/0700_cr.yaml` for the default values.
-
-```bash
-IMAGE_REGISTRY=<my registry>
-make deploy 
-```
-
-The operator will use the operand node-feature-discovery image built from: https://github.com/kubernetes-sigs/node-feature-discovery
-
-To uninstall the operator run
-
-```bash
-make undeploy
-```
-
-## Extending Node-feature-discovery with sidecar containers and hooks
-
-First see upstream documentation of the hook feature and how to create a correct hook file:
-
-https://github.com/kubernetes-sigs/node-feature-discovery#local-user-specific-features.
-
-The DaemonSet running on the workers will mount the `hostPath: /etc/kubernetes/node-feature-discovery/source.d`.
-Additional hooks can than be provided by a sidecar container that is as well running on the workers and mounting the same hostpath and writing the hook executable (shell-script, compiled code, ...) to this directory.
-
-NFD will execute any file in this directory, if one needs any configuration for the hook,
-a separate configuration directory can be created under `/etc/kubernetes/node-feature-discovery/source.d`
-e.g. `/etc/kubernetes/node-feature-discovery/source.d/own-hook-conf`, NFD will not recurse deeper into the file hierarchy.
-
 ### Code of conduct
 
 Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).
+
+[documentation]: https://kubernetes-sigs.github.io/node-feature-discovery-operator
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -52,3 +52,5 @@ release: master
 
 # Container image which to point to in the documentation
 container_image: gcr.io/k8s-staging-nfd/node-feature-discovery-operator:master
+# Operand Node Feature Discovery documentation version
+operand_version: v0.8
diff --git a/docs/advanced/developer-guide.md b/docs/advanced/developer-guide.md
@@ -0,0 +1,80 @@
+---
+title: "Developer guide"
+layout: default
+sort: 1
+---
+
+# Developer guide
+
+{: .no_toc }
+
+## Table of contents
+
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+## Building the operator
+
+### Download the source code
+
+```bash
+git clone https://github.com/kubernetes-sigs/node-feature-discovery-operator
+```
+
+### Build the operator image
+
+```bash
+IMAGE_REGISTRY=<my registry>
+make image
+```
+
+#### Push the container image
+
+```bash
+IMAGE_REGISTRY=<my registry>
+make push
+```
+
+Alternatively, instead of specifying variables on the command line,
+you can edit the Makefile to permanently change parameter defaults
+like name of the image or namespace where the operator is deployed.
+
+## Manual deployment of the operator
+
+After building the image you can simply run
+
+```bash
+IMAGE_REGISTRY=<my registry>
+make deploy
+```
+
+Then create a NodeFeatureDiscovery CR by running
+
+```bash
+kubectl apply -f config/samples/nfd.kubernetes.io_v1_nodefeaturediscovery.yaml
+```
+
+## Undeploy the operator
+
+The operator will use the operand node-feature-discovery
+image built from: `https://github.com/kubernetes-sigs/node-feature-discovery`
+
+To uninstall the operator run
+
+```bash
+make undeploy
+```
+
+## Clean up labels
+
+In case you need to reomve the labels created by NFD,
+the source Makefile comes with a built in target
+
+```bash
+make clean-labels
+```
+
+This will clean all labels referencing to
+`feature.node.kubernetes.io` and `nfd.node.kubernetes.io`
diff --git a/docs/advanced/index.md b/docs/advanced/index.md
@@ -0,0 +1,9 @@
+---
+title: "Advanced"
+layout: default
+sort: 2
+---
+
+# Advanced
+
+Advanced topics and reference.
diff --git a/docs/advanced/nodefeaturediscovery.md b/docs/advanced/nodefeaturediscovery.md
@@ -0,0 +1,136 @@
+---
+title: "NodeFeatureDiscovery"
+layout: default
+sort: 2
+---
+
+# The NodeFeatureDiscovery CR
+
+The `NodeFeatureDiscovery` CustomResource defines operational variables
+to define the behaviour of the Node Feature Discovery Operand,
+an example of the CustomResource:
+
+```yaml
+apiVersion: nfd.kubernetes.io/v1
+kind: NodeFeatureDiscovery
+metadata:
+  name: nfd-master-server
+  namespace: node-feature-discovery-operator
+spec:
+  operand:
+    namespace: node-feature-discovery-operator
+    image: gcr.io/k8s-staging-nfd/node-feature-discovery:master
+    imagePullPolicy: Always
+    servicePort: 12000
+  workerConfig:
+    configData: |
+      #core:
+      #  labelWhiteList:
+      #  noPublish: false
+      #  sleepInterval: 60s
+      #  sources: [all]
+      #  klog:
+      #    addDirHeader: false
+      #    alsologtostderr: false
+      #    logBacktraceAt:
+      #    logtostderr: true
+      #    skipHeaders: false
+      #    stderrthreshold: 2
+      #    v: 0
+      #    vmodule:
+      ##   NOTE: the following options are not dynamically run-time configurable
+      ##         and require a nfd-worker restart to take effect after being changed
+      #    logDir:
+      #    logFile:
+      #    logFileMaxSize: 1800
+      #    skipLogHeaders: false
+      #sources:
+      #  cpu:
+      #    cpuid:
+      ##     NOTE: whitelist has priority over blacklist
+      #      attributeBlacklist:
+      #        - "BMI1"
+      #        - "BMI2"
+      #        - "CLMUL"
+      #        - "CMOV"
+      #        - "CX16"
+      #        - "ERMS"
+      #        - "F16C"
+      #        - "HTT"
+      #        - "LZCNT"
+      #        - "MMX"
+      #        - "MMXEXT"
+      #        - "NX"
+      #        - "POPCNT"
+      #        - "RDRAND"
+      #        - "RDSEED"
+      #        - "RDTSCP"
+      #        - "SGX"
+      #        - "SSE"
+      #        - "SSE2"
+      #        - "SSE3"
+      #        - "SSE4.1"
+      #        - "SSE4.2"
+      #        - "SSSE3"
+      #      attributeWhitelist:
+      #  kernel:
+      #    kconfigFile: "/path/to/kconfig"
+      #    configOpts:
+      #      - "NO_HZ"
+      #      - "X86"
+      #      - "DMI"
+      #  pci:
+      #    deviceClassWhitelist:
+      #      - "0200"
+      #      - "03"
+      #      - "12"
+      #    deviceLabelFields:
+      #      - "class"
+      #      - "vendor"
+      #      - "device"
+      #      - "subsystem_vendor"
+      #      - "subsystem_device"
+      #  usb:
+      #    deviceClassWhitelist:
+      #      - "0e"
+      #      - "ef"
+      #      - "fe"
+      #      - "ff"
+      #    deviceLabelFields:
+      #      - "class"
+      #      - "vendor"
+      #      - "device"
+      #  custom:
+      #    - name: "my.kernel.feature"
+      #      matchOn:
+      #        - loadedKMod: ["example_kmod1", "example_kmod2"]
+      #    - name: "my.pci.feature"
+      #      matchOn:
+      #        - pciId:
+      #            class: ["0200"]
+      #            vendor: ["15b3"]
+      #            device: ["1014", "1017"]
+      #        - pciId :
+      #            vendor: ["8086"]
+      #            device: ["1000", "1100"]
+      #    - name: "my.usb.feature"
+      #      matchOn:
+      #        - usbId:
+      #          class: ["ff"]
+      #          vendor: ["03e7"]
+      #          device: ["2485"]
+      #        - usbId:
+      #          class: ["fe"]
+      #          vendor: ["1a6e"]
+      #          device: ["089a"]
+      #    - name: "my.combined.feature"
+      #      matchOn:
+      #        - pciId:
+      #            vendor: ["15b3"]
+      #            device: ["1014", "1017"]
+      #          loadedKMod : ["vendor_kmod1", "vendor_kmod2"]
+```
+
+For more information about how to setup the `WorkerConfig` stanza,
+see
+[worker config reference](https://kubernetes-sigs.github.io/node-feature-discovery/{{site.operand_version}}/advanced/worker-configuration-reference.html)
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
@@ -0,0 +1,32 @@
+---
+title: "Contributing"
+layout: default
+sort: 3
+---
+
+# Contributing
+
+---
+
+## Community
+
+You can reach us via the following channels:
+
+- [#node-feature-discovery](https://kubernetes.slack.com/messages/node-feature-discovery)
+  channel in [Kubernetes Slack](slack.k8s.io)
+- [SIG-Node](https://groups.google.com/g/kubernetes-sig-node) mailing list
+- File an
+  [issue](https://github.com/kubernetes-sigs/node-feature-discovery-operator/issues/new)
+  in this repository
+
+## Governance
+
+This is a
+[SIG-node](https://github.com/kubernetes/community/blob/master/sig-node/README.md)
+subproject, hosted under the
+[Kubernetes SIGs](https://github.com/kubernetes-sigs) organization in Github.
+The project was established in 2016 and was migrated to Kubernetes SIGs in 2018.
+
+## License
+
+This is open source software released under the [Apache 2.0 License](LICENSE).
diff --git a/docs/get-started/index.md b/docs/get-started/index.md
@@ -0,0 +1,19 @@
+---
+title: "Get Started"
+layout: default
+sort: 1
+---
+
+# Node Feature Discovery Operator
+
+Welcome to Node Feature Discovery Operator – an Operator
+Framework implementation around the Node Feature Discovery project to enable
+detecting hardware features and system configuration!
+
+Continue to:
+
+- **[Introduction](introduction.md)** for more details on the
+  project.
+
+- **[Quick start](quick-start.md)** for quick step-by-step
+  instructions on how to get NFD running on your cluster.
diff --git a/docs/get-started/introduction.md b/docs/get-started/introduction.md
@@ -0,0 +1,18 @@
+---
+title: "Introduction"
+layout: default
+sort: 1
+---
+
+# Introduction
+
+The Node Feature Discovery Operator manages the detection
+of hardware features and configuration in a Kubernetes
+cluster by labeling the nodes with hardware-specific information.
+The Node Feature Discovery (NFD) will label the host with
+node-specific attributes,
+like PCI cards, kernel, or OS version, and many more.
+
+The NFD Operator is based on the [Operator Framework](https://operatorframework.io/)
+an open source toolkit to manage Kubernetes native applications, called
+Operators, in an effective, automated, and scalable way.