diff --git a/README.md b/README.md index e73804bc..a570ea73 100644 --- 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= -make image -``` - -Optionally you can push it to your image repo - -```bash -IMAGE_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= -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 \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml index f6b27729..92dd0f5a 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -45,9 +45,12 @@ remote_theme: rundocs/jekyll-rtd-theme@v2.0.9 version: master display_version_list: true -# Release is used to make external links to point to the correct blobs in the -# Github repo +# 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 # 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/_includes/class/sidebar-wrap.liquid b/docs/_includes/class/sidebar-wrap.liquid index e2a7340a..e7fdcce2 100644 --- a/docs/_includes/class/sidebar-wrap.liquid +++ b/docs/_includes/class/sidebar-wrap.liquid @@ -6,7 +6,7 @@ {{ site.title }} - {{ site.version }} + {{ site.release }}
diff --git a/docs/advanced/developer-guide.md b/docs/advanced/developer-guide.md new file mode 100644 index 00000000..38270988 --- /dev/null +++ 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= +make image +``` + +#### Push the container image + +```bash +IMAGE_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= +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` \ No newline at end of file diff --git a/docs/advanced/index.md b/docs/advanced/index.md new file mode 100644 index 00000000..53177286 --- /dev/null +++ b/docs/advanced/index.md @@ -0,0 +1,9 @@ +--- +title: "Advanced" +layout: default +sort: 2 +--- + +# Advanced + +Advanced topics and reference. \ No newline at end of file diff --git a/docs/advanced/nodefeaturediscovery.md b/docs/advanced/nodefeaturediscovery.md new file mode 100644 index 00000000..a16e2c1b --- /dev/null +++ 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 new file mode 100644 index 00000000..42c0e6f4 --- /dev/null +++ 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 new file mode 100644 index 00000000..96500d56 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/get-started/introduction.md b/docs/get-started/introduction.md new file mode 100644 index 00000000..82d99fb5 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/get-started/quick-start.md b/docs/get-started/quick-start.md new file mode 100644 index 00000000..2af0179c --- /dev/null +++ b/docs/get-started/quick-start.md @@ -0,0 +1,53 @@ +--- +title: "Quick start" +layout: default +sort: 2 +--- + +# Quick start + +Get the source code + +```bash +git clone -b {{ site.release }} https://github.com/kubernetes-sigs/node-feature-discovery-operator +``` + +Deploy the operator + +```bash +IMAGE_TAG={{ site.container_image }} +make deploy +``` + +Create a NodeFeatureDiscovery instance + +```bash +kubectl apply -f config/samples/nfd.kubernetes.io_v1_nodefeaturediscovery.yaml +``` + +## Verify + +The Operator will deploy NFD based on the information +on the NodeFeatureDiscovery CR instance, +after a moment you should be able to see + +```bash +$ kubectl -n node-feature-discovery-operator get ds,deploy +NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE +daemonset.apps/nfd-worker 3 3 3 3 3 5s +NAME READY UP-TO-DATE AVAILABLE AGE +deployment.apps/nfd-master 1/1 1 1 17s +``` + +Check that NFD feature labels have been created + +```bash +$ kubectl get no -o json | jq .items[].metadata.labels +{ + "beta.kubernetes.io/arch": "amd64", + "beta.kubernetes.io/os": "linux", + "feature.node.kubernetes.io/cpu-cpuid.ADX": "true", + "feature.node.kubernetes.io/cpu-cpuid.AESNI": "true", + "feature.node.kubernetes.io/cpu-cpuid.AVX": "true", +... +``` diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..f22e68ef --- /dev/null +++ b/docs/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 38c57ba7..00000000 --- a/docs/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Introduction" -layout: default -sort: 1 ---- - -# Introduction - -***COMING SOON.***