diff --git a/README.md b/README.md index 4dfef8055..cffb97953 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,128 @@ -#CPU Feature Discovery for Kubernetes -This software enables Intel Architecture (IA) feature discovery for Kubernetes. It detects the CPU features, such as Intel [Resource Director Technology][intel-rdt] (RDT), available in each node of the Kubernetes cluster and labels them appropriately. +# CPU Feature Discovery for Kubernetes - - [Getting Started](#getting-started) - * [System Requirements](#system-requirements) - * [Installation](#installation) - * [Usage](#usage) - - [Documentation](#documentation) - - [License](#license) +- [Overview](#overview) +- [Getting Started](#getting-started) + * [System Requirements](#system-requirements) + * [Usage](#usage) +- [Building from source](#building-from-source) +- [License](#license) + +## Overview + +This software enables Intel Architecture (IA) feature discovery for Kubernetes. +It detects CPU features available on each node in a Kubernetes cluster, such as +Intel [Resource Director Technology][intel-rdt] and advertises those +features using node labels. + +### Intel Resource Director Technology (RDT) Features + +| Feature name | Description | +| :------------: | :---------------------------------------------------------------------------------: | +| RDTMON | Intel Cache Monitoring Technology (CMT) and Intel Memory Bandwidth Monitoring (MBM) +| RDTL3CA | Intel L3 Cache Allocation Technology +| RDTL2CA | Intel L2 Cache Allocation Technology + +### Other Features (Partial List) + +| Feature name | Description | +| :------------: | :----------------------------------------------------------: | +| ADX | Multi-Precision Add-Carry Instruction Extensions (ADX) +| AESNI | Advanced Encryption Standard (AES) New Instructions (AES-NI) +| AVX | Advanced Vector Extensions (AVX) +| AVX2 | Advanced Vector Extensions 2 (AVX2) +| BMI1 | Bit Manipulation Instruction Set 1 (BMI) +| BMI2 | Bit Manipulation Instruction Set 2 (BMI2) +| SSE4.1 | Streaming SIMD Extensions 4.1 (SSE4.1) +| SSE4.2 | Streaming SIMD Extensions 4.2 (SSE4.2) +| SGX | Software Guard Extensions (SGX) + +The published node labels encode a few pieces of information: + +- A "namespace" to denote vendor-specific information + (`node.alpha.intel.com`). +- The version of this discovery code (e.g. `v0.1.0`) that wrote the + label. +- The relevant hardware component each label describes (e.g. `cpu`). +- The name of the discovered feature as it appears in the underlying + source, mostly `cpuid` (e.g. `AESNI`). + +_Note: only features that are available on a given node are labeled, so the +only label value published is the string `"true"`. This feature discovery code +will not add a label with the falue `"false"` for features that are not +present._ + +``` +"node.alpha.intel.com/v0.1.0/cpu/": "true" +``` -##Getting Started ### System Requirements + At a minimum, you will need: - 1. [Docker] [docker-down] (only required to build and push docker images) - 2. [GCC] [gcc-down] (only required to build software to detect Intel RDT feature set) - 3. Linux (x86_64) - 4. [kubectl] [kubectl-setup] (properly setup and configured to work with a Kubernetes cluster) -###Installation -####Downloading the Source Code -``` -git clone https://github.com/intelsdi-x/dbi-iafeature-discovery -``` +1. Linux (x86_64) +1. [kubectl] [kubectl-setup] (properly set up and configured to work with your Kubernetes cluster) +1. [GCC] [gcc-down] (only required to build software to detect Intel RDT feature set) +1. [Docker] [docker-down] (only required to build and push docker images) + +### Usage + +Feature discovery is done as a one-shot job. There is an example script in this +repo that demonstrates how to deploy the job to unlabeled nodes. -####Building from Source -The build steps described below are optional. The default docker image in Docker hub at `intelsdi/nodelabels` can be used to decorate the Kubernetes node with IA features. Skip to usage instructions if you do not need to build your own docker image. - -Build the Intel RDT Detection Software Using `make` (Optional): ``` -cd /rdt-discovery -make +./label-nodes.sh ``` -Build the Docker Image (Optional): +The discovery script will launch a job on each each unlabeled node in the +cluster. When the job runs, it contacts the Kubernetes API server to add +labels to the node to advertise hardware features (initially, from `cpuid` and +RDT). + +## Building from source + +Download the source code. + ``` -cd +git clone https://github.com/intelsdi-x/dbi-iafeature-discovery +``` + +The build steps described below are optional. The default docker image in +Dockerhub at `intelsdi/nodelabels` can be used to decorate the Kubernetes node +with CPU features. Skip to usage instructions if you do not need to build your +own docker image. + +**Build the Intel RDT Detection Software Using `make` (Optional):** + +``` +cd /rdt-discovery +make +``` + +**Build the Docker image (optional):** + +``` +cd docker build -t / . ``` -Push the Docker Image (Optional) +Push the Docker Image (optional) + ``` docker push ``` -Change the Job Spec to Use the Appropriate Image (Optional): -Change line #40 in `featurelabeling-job.json.template` to the appropriate image name in the `/` format used for building the image above or use the default `intelsdi/nodelabels` image. +**Change the job spec to use your new image (optional):** -###Usage -Deploying Kubernetes Job for Node Feature Labeling: -``` -./label-nodes.sh -``` -The above command will label each node in the cluster with the features from cpuid. The labeling format used is -``` - = <"node.alpha.intel.com/", "true"> -``` -Note that only features that are available in that node are labelled. +To use your published image from the step above instead of the +`intelsdi/nodelabels` image, edit line 40 in the file +`[featurelabeling-job.json.template](featurelabeling-job.json.template)` to +the new location (`/`). -##Documentation -This software determines the Intel Architecture (IA) features associated with a processor using `cpuid`. The following set of features are discovered and labelled by this software. +## License -###Intel Resource Director Technology (RDT) Features -| Label | Feature(s) Represented | -| :------------: | :---------------------------------------------------------------------------------: | -| RDTMON | Intel Cache Monitoring Technology (CMT) and Intel Memory Bandwidth Monitoring (MBM) | -| RDTL3CA | Intel L3 Cache Allocation Technology | -| RDTL2CA | Intel L2 Cache Allocation Technology | - -###Other Features (Partial List) -| Label | Feature(s) Represented | -| :------------: | :---------------------------------------------------------------------------------: | -| ADX | Multi-Precision Add-Carry Instruction Extensions (ADX) | -| AESNI | Advanced Encryption Standard (AES) New Instructions (AES-NI) | -| AVX | Advanced Vector Extensions (AVX)| -| AVX2 | Advanced Vector Extensions 2 (AVX2)| -| BMI1 | Bit Manipulation Instruction Set 1 (BMI)| -| BMI2 | Bit Manipulation Instruction Set 2 (BMI2)| -| SSE4.1 | Streaming SIMD Extensions 4.1 (SSE4.1)| -| SSE4.2 | Streaming SIMD Extensions 4.2 (SSE4.2)| -| SGX | Software Guard Extensions (SGX) | - -##License -This is an Open Source software released under the Apache 2.0 [License](LICENSE). +This is open source software released under the [Apache 2.0 License](LICENSE). + [intel-rdt]: http://www.intel.com/content/www/us/en/architecture-and-technology/resource-director-technology.html [docker-down]: https://docs.docker.com/engine/installation/ [golang-down]: https://golang.org/dl/ diff --git a/rdt-discovery/Makefile b/rdt-discovery/Makefile index b979fa77c..431163367 100644 --- a/rdt-discovery/Makefile +++ b/rdt-discovery/Makefile @@ -8,9 +8,9 @@ LDLIBS=-lpqos CFLAGS=-I$(INCDIR) -default: +default: $(MAKE) all all: $(CC) $(CFLAGS) -o mon-discovery monitoring-discovery.c $(LDFLAGS) $(LDLIBS) $(CC) $(CFLAGS) -o l3-alloc-discovery l3-allocation-discovery.c $(LDFLAGS) $(LDLIBS) - $(CC) $(CFLAGS) -o l2-alloc-discovery l2-allocation-discovery.c $(LDFLAGS) $(LDLIBS) + $(CC) $(CFLAGS) -o l2-alloc-discovery l2-allocation-discovery.c $(LDFLAGS) $(LDLIBS) diff --git a/rdt-discovery/l2-allocation-discovery.c b/rdt-discovery/l2-allocation-discovery.c index f02923c68..0287befcd 100644 --- a/rdt-discovery/l2-allocation-discovery.c +++ b/rdt-discovery/l2-allocation-discovery.c @@ -16,25 +16,25 @@ limitations under the License. #include "machine.h" int main(int argc, char *argv[]) { - int ret, det=1; - struct cpuid_out res; - - //Logic below from https://github.com/01org/intel-cmt-cat/blob/master/lib/host_cap.c - lcpuid(0x7, 0x0, &res); - if (!(res.ebx & (1 << 15))) { - det = 0; - printf("NOT DETECTED"); - } - else { - lcpuid(0x10, 0x0, &res); - if (!(res.ebx & (1 << 2))) { - det = 0; - printf("NOT DETECTED"); - } - } - - if (det) - printf("DETECTED"); + int ret, det=1; + struct cpuid_out res; - return 0; + // Logic below from https://github.com/01org/intel-cmt-cat/blob/master/lib/host_cap.c + lcpuid(0x7, 0x0, &res); + if (!(res.ebx & (1 << 15))) { + det = 0; + printf("NOT DETECTED"); + } + else { + lcpuid(0x10, 0x0, &res); + if (!(res.ebx & (1 << 2))) { + det = 0; + printf("NOT DETECTED"); + } + } + + if (det) + printf("DETECTED"); + + return 0; } diff --git a/rdt-discovery/l3-allocation-discovery.c b/rdt-discovery/l3-allocation-discovery.c index c4a3219cf..598a1cd9f 100644 --- a/rdt-discovery/l3-allocation-discovery.c +++ b/rdt-discovery/l3-allocation-discovery.c @@ -16,28 +16,28 @@ limitations under the License. #include "machine.h" int main(int argc, char *argv[]) { - int ret, det=1; - struct cpuid_out res; - - //Logic below from https://github.com/01org/intel-cmt-cat/blob/master/lib/host_cap.c - //TODO(balajismaniam): Implement L3 CAT detection using brand string and MSR probing if - //not detected using cpuid - - lcpuid(0x7, 0x0, &res); - if (!(res.ebx & (1 << 15))) { - det = 0; - printf("NOT DETECTED"); - } - else { - lcpuid(0x10, 0x0, &res); - if (!(res.ebx & (1 << 1))) { - det = 0; - printf("NOT DETECTED"); - } - } - - if (det) - printf("DETECTED"); + int ret, det=1; + struct cpuid_out res; - return 0; + // Logic below from https://github.com/01org/intel-cmt-cat/blob/master/lib/host_cap.c + // TODO(balajismaniam): Implement L3 CAT detection using brand string and MSR probing if + // not detected using cpuid + + lcpuid(0x7, 0x0, &res); + if (!(res.ebx & (1 << 15))) { + det = 0; + printf("NOT DETECTED"); + } + else { + lcpuid(0x10, 0x0, &res); + if (!(res.ebx & (1 << 1))) { + det = 0; + printf("NOT DETECTED"); + } + } + + if (det) + printf("DETECTED"); + + return 0; } diff --git a/rdt-discovery/monitoring-discovery.c b/rdt-discovery/monitoring-discovery.c index 14b4cae5c..b5c3a7891 100644 --- a/rdt-discovery/monitoring-discovery.c +++ b/rdt-discovery/monitoring-discovery.c @@ -16,25 +16,25 @@ limitations under the License. #include "machine.h" int main(int argc, char *argv[]) { - int ret, det=1; - struct cpuid_out res; - - //Logic below from https://github.com/01org/intel-cmt-cat/blob/master/lib/host_cap.c - lcpuid(0x7, 0x0, &res); - if (!(res.ebx & (1 << 12))) { - det = 0; - printf("NOT DETECTED"); - } - else { - lcpuid(0xf, 0x0, &res); - if (!(res.edx & (1 << 1))) { - det=0; - printf("NOT DETECTED"); - } - } - - if (det) - printf("DETECTED"); + int ret, det=1; + struct cpuid_out res; - return 0; + // Logic below from https://github.com/01org/intel-cmt-cat/blob/master/lib/host_cap.c + lcpuid(0x7, 0x0, &res); + if (!(res.ebx & (1 << 12))) { + det = 0; + printf("NOT DETECTED"); + } + else { + lcpuid(0xf, 0x0, &res); + if (!(res.edx & (1 << 1))) { + det=0; + printf("NOT DETECTED"); + } + } + + if (det) + printf("DETECTED"); + + return 0; }