diff --git a/_data/guides.yml b/_data/guides.yml index b70623619a4df..6f08b4c8c770c 100644 --- a/_data/guides.yml +++ b/_data/guides.yml @@ -233,6 +233,8 @@ toc: path: /docs/getting-started-guides/ubuntu/ - title: Ubuntu Nodes with Calico path: /docs/getting-started-guides/ubuntu-calico/ + - title: Validate Node Setup + path: /docs/admin/node-conformance - title: Portable Multi-Node Cluster path: /docs/getting-started-guides/docker-multinode/ - title: Building Large Clusters diff --git a/docs/admin/node-conformance.md b/docs/admin/node-conformance.md new file mode 100644 index 0000000000000..2adb159c5cb06 --- /dev/null +++ b/docs/admin/node-conformance.md @@ -0,0 +1,114 @@ +--- +assignees: +- Random-Liu + +--- + +* TOC +{:toc} + +## Node Conformance Test + +*Node conformance test* is a test framework validating whether a node meets the +minimum requirement of Kubernetes with a set of system verification and +functionality test. A node which passes the tests is qualified to join a +Kubernetes cluster. + +## Limitations + +There are following limitations in the current implementation of node +conformance test. They'll be improved in future version. + +* Node conformance test only supports Docker as the container runtime. +* Node conformance test doesn't validate network related system configurations + and functionalities. + +## Prerequisite + +Node conformance test is used to test whether a node is ready to join a +Kubernetes cluster, so the prerequisite is the same with a standard Kubernetes +node. At least, the node should have properly installed: + +* Container Runtime (Docker) +* Kubelet + +Node conformance test validates kernel configurations. If the kenrel module +`configs` is built as module in your environment, it must be loaded before the +test. (See [Caveats #3](#caveats) for more information) + +## Usage + +### Run Node Conformance Test + +* **Step 1:** Point your Kubelet to localhost `--api-servers="http://localhost:8080"`, +because the test framework starts a local master to test Kubelet. + +* **Step 2:** Run the node conformance test with command: + +```shell +# $CONFIG_DIR is the pod manifest path of your kubelet. +# $LOG_DIR is the test output path. +sudo docker run -it --rm --privileged --net=host \ + -v /:/rootfs:ro -v /var/run:/var/run \ + -v $CONFIG_DIR:/etc/manifest -v $LOG_DIR:/var/result \ + gcr.io/google_containers/node-test-amd64:v0.1 +``` + +### Run Node Conformance Test for Other Architectures + +We also build node conformance test docker images for other architectures: + + Arch | Image | +--------|:-----------------:| + amd64 | node-test-amd64 | + arm | node-test-arm | + arm64 | node-test-arm64 | + +### Run Selected Test + +In fact, Node conformance test is a containerized version of [node e2e +test](https://github.com/kubernetes/kubernetes/blob/release-1.4/docs/devel/e2e-node-tests.md). +By default, it runs all conformance test. + +Theoretically, you can run any node e2e test if you configure the container and +mount required volumes properly. But **it is strongly recommended to only run conformance +test**, because the non-conformance test needs much more complex framework configuration. + +To run specific tests, overwrite the environment variable `FOCUS` with the +regular expression of tests you want to run. + +```shell +sudo docker run -it --rm --privileged --net=host \ + -v /:/rootfs:ro -v /var/run:/var/run \ + -v $CONFIG_DIR:/etc/manifest -v $LOG_DIR:/var/result \ + -e FOCUS=MirrorPod \ # Only run MirrorPod test + gcr.io/google_containers/node-test-amd64:v0.1 +``` + +To skip specific tests, overwrite the environment variable `SKIP` with the +regular expression of tests you want to skip. + +```shell +sudo docker run -it --rm --privileged --net=host \ + -v /:/rootfs:ro -v /var/run:/var/run \ + -v $CONFIG_DIR:/etc/manifest -v $LOG_DIR:/var/result \ + -e SKIP=MirrorPod \ # Run all conformance test and skip MirrorPod test + gcr.io/google_containers/node-test-amd64:v0.1 +``` + +### Caveats + +* The test will leave some docker images on the node, including the node + conformance test image and images of containers used in the functionality + test. +* The test will leave dead containers on the node, these containers are created + during the functionality test. +* Node conformance test validates kernel configuration. However, in some os + distro the kernel module `configs` may not be loaded by default, and you will get + the error `no config path in [POSSIBLE KERNEL CONFIG FILE PATHS] is + available`. In that case please do either of the followings: + * Manually load/unload `configs` kernel module: run `sudo modprobe configs` to + load the kernel module, and `sudo modprobe -r configs` to unload it after the test. + * Mount `modprobe` into the container: Add option `-v /bin/kmod:/bin/kmod + -v /sbin/modprobe:/sbin/modprobe -v /lib/modules:/lib/modules` when starting + the test container. diff --git a/docs/admin/node-problem.md b/docs/admin/node-problem.md index abb08abeff2e7..b6926ba15baba 100644 --- a/docs/admin/node-problem.md +++ b/docs/admin/node-problem.md @@ -36,7 +36,7 @@ it to [support other log format](/docs/admin/node-problem/#support-other-log-for ## Enable/Disable in GCE cluster -Node problem detector is [running as a cluster addon](cluster-large.md/#Addon-Resources) enabled by default in the +Node problem detector is [running as a cluster addon](cluster-large.md/#addon-resources) enabled by default in the gce cluster. You can enable/disable it by setting the environment variable