Merge pull request #75 from ArangoGutierrez/bp/docs_v2

Backport documentation pages
kubernetes-sigs · Jun 3, 2021 · 8f747e0 · 8f747e0
2 parents c5c6060 + 3d04ec3
commit 8f747e0
Show file tree

Hide file tree

Showing 11 changed files with 338 additions and 69 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
@@ -42,13 +42,15 @@ remote_theme: rundocs/jekyll-rtd-theme@v2.0.9
 #   - vendor/ruby/
 
 # Document versioning
-version: master
+version: v0.2
 display_version_list: true
 
 # Release is the full released version number. Used to make external links to
 # point to the correct blobs in the Github repo. This is also the version shown
 # in the sidebar (top left corner of the page)
-release: master
+release: v0.2.0
 
 # Container image which to point to in the documentation
-container_image: gcr.io/k8s-staging-nfd/node-feature-discovery-operator:master
+container_image: k8s.gcr.io/nfd/node-feature-discovery-operator:v0.2.0
+# Operand Node Feature Discovery documentation version
+operand_version: v0.7
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,115 @@
+---
+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: k8s.gcr.io/nfd/node-feature-discovery:v0.7.0
+    imagePullPolicy: Always
+  workerConfig:
+    configData: |
+    #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.