Merge pull request #60550 from brahmaroutu/conf_network

Automatic merge from submit-queue (batch tested with PRs 66827, 60550). If you want to cherry-pick this change to another branch, please follow the instructions <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md">here</a>.

Adding details to Conformance Tests using RFC 2119 standards.

This PR is part of the conformance documentation. This is to provide more formal specification using RFC 2119 keywords to describe the test so that who ever is running conformance tests do not have to go through the code to understand why and what is tested.
The documentation information added here into each of the tests eventually result into a document which is currently checked in at location https://github.com/cncf/k8s-conformance/blob/master/docs/KubeConformance-1.9.md

I would like to have this PR reviewed for v1.10 as I consider it important to strengthen the conformance documents.

test/e2e/network/dns.go

@@ -37,8 +37,9 @@ var _ = SIGDescribe("DNS", func() {
 	f := framework.NewDefaultFramework("dns")
 
 	/*
-	   Testname: dns-for-clusters
+		Release : v1.9
-	   Description: Make sure that DNS can resolve the names of clusters.
+		Testname: DNS, cluster
+		Description: When a Pod is created, the pod MUST be able to resolve cluster dns entries such as kubernetes.default via DNS and /etc/hosts.
 	*/
 	framework.ConformanceIt("should provide DNS for the cluster ", func() {
 		// All the names we need to be able to resolve.
@@ -67,8 +68,9 @@ var _ = SIGDescribe("DNS", func() {
 	})
 
 	/*
-	   Testname: dns-for-services
+		Release : v1.9
-	   Description: Make sure that DNS can resolve the names of services.
+		Testname: DNS, services
+		Description: When a headless service is created, the service MUST be able to resolve all the required service endpoints. When the service is created, any pod in the same namespace must be able to resolve the service by all of the expected DNS names.
 	*/
 	framework.ConformanceIt("should provide DNS for services ", func() {
 		// Create a test headless service.

test/e2e/network/proxy.go

@@ -61,26 +61,25 @@ var _ = SIGDescribe("Proxy", func() {
 		prefix := "/api/" + version
 
 		/*
-			    Testname: proxy-subresource-node-logs-port
+			Release : v1.9
-			    Description: Ensure that proxy on node logs works with node proxy
+			Testname: Proxy, logs port endpoint
-				subresource and explicit kubelet port.
+			Description: Select any node in the cluster to invoke /proxy/nodes/<nodeip>:10250/logs endpoint. This endpoint MUST be reachable.
 		*/
 		framework.ConformanceIt("should proxy logs on node with explicit kubelet port using proxy subresource ", func() { nodeProxyTest(f, prefix+"/nodes/", ":10250/proxy/logs/") })
 
 		/*
-			    Testname: proxy-subresource-node-logs
+			Release : v1.9
-			    Description: Ensure that proxy on node logs works with node proxy
+			Testname: Proxy, logs endpoint
-				subresource.
+			Description:  Select any node in the cluster to invoke /proxy/nodes/<nodeip>//logs endpoint. This endpoint MUST be reachable.
 		*/
 		framework.ConformanceIt("should proxy logs on node using proxy subresource ", func() { nodeProxyTest(f, prefix+"/nodes/", "/proxy/logs/") })
 
 		// using the porter image to serve content, access the content
 		// (of multiple pods?) from multiple (endpoints/services?)
-
 		/*
-			    Testname: proxy-service-pod
+			Release : v1.9
-			    Description: Ensure that proxy through a service and a pod works with
+			Testname: Proxy, logs service endpoint
-				both generic top level prefix proxy and proxy subresource.
+			Description: Select any node in the cluster to invoke  /logs endpoint  using the /nodes/proxy subresource from the kubelet port. This endpoint MUST be reachable.
 		*/
 		framework.ConformanceIt("should proxy through a service and a pod ", func() {
 			start := time.Now()

test/e2e/network/service.go

@@ -100,8 +100,9 @@ var _ = SIGDescribe("Services", func() {
 	// TODO: We get coverage of TCP/UDP and multi-port services through the DNS test. We should have a simpler test for multi-port TCP here.
 
 	/*
-	   Testname: service-kubernetes-exists
+		Release : v1.9
-	   Description: Make sure kubernetes service does exist.
+		Testname: Kubernetes Service
+		Description: By default when a kubernetes cluster is running there MUST be a ‘kubernetes’ service running in the cluster.
 	*/
 	framework.ConformanceIt("should provide secure master service ", func() {
 		_, err := cs.CoreV1().Services(metav1.NamespaceDefault).Get("kubernetes", metav1.GetOptions{})
@@ -109,9 +110,9 @@ var _ = SIGDescribe("Services", func() {
 	})
 
 	/*
-		    Testname: service-valid-endpoints
+		Release : v1.9
-		    Description: Ensure a service with no pod, one pod or two pods has
+		Testname: Service, endpoints
-			valid/accessible endpoints (same port number for service and pods).
+		Description: Create a service with a endpoint without any Pods, the service MUST run and show empty endpoints. Add a pod to the service and the service MUST validate to show all the endpoints for the ports exposed by the Pod. Add another Pod then the list of all Ports exposed by both the Pods MUST be valid and have corresponding service endpoint. Once the second Pod is deleted then set of endpoint MUST be validated to show only ports from the first container that are exposed. Once both pods are deleted the endpoints from the service MUST be empty.
 	*/
 	framework.ConformanceIt("should serve a basic endpoint from pods ", func() {
 		serviceName := "endpoint-test2"
@@ -166,9 +167,9 @@ var _ = SIGDescribe("Services", func() {
 	})
 
 	/*
-		    Testname: service-valid-endpoints-multiple-ports
+		Release : v1.9
-		    Description: Ensure a service with no pod, one pod or two pods has
+		Testname: Service, endpoints with multiple ports
-			valid/accessible endpoints (different port number for pods).
+		Description: Create a service with two ports but no Pods are added to the service yet.  The service MUST run and show empty set of endpoints. Add a Pod to the first port, service MUST list one endpoint for the Pod on that port. Add another Pod to the second port, service MUST list both the endpoints. Delete the first Pod and the service MUST list only the endpoint to the second Pod. Delete the second Pod and the service must now have empty set of endpoints.
 	*/
 	framework.ConformanceIt("should serve multiport endpoints from pods ", func() {
 		// repacking functionality is intentionally not tested here - it's better to test it in an integration test.

test/e2e/network/service_latency.go

@@ -47,10 +47,9 @@ var _ = SIGDescribe("Service endpoints latency", func() {
 	f := framework.NewDefaultFramework("svc-latency")
 
 	/*
-		    Testname: service-endpoint-latency
+		Release : v1.9
-		    Description: Ensure service endpoint's latency is not high
+		Testname: Service endpoint latency, thresholds
-		    (e.g. p50 < 20 seconds and p99 < 50 seconds). If any call to the
+		Description: Run 100 iterations of create service with the Pod running the pause image, measure the time it takes for creating the service and the endpoint with the service name is available. These durations are captured for 100 iterations, then the durations are sorted to compue 50th, 90th and 99th percentile. The single server latency MUST not exceed liberally set thresholds of 20s for 50th percentile and 50s for the 90th percentile.
-			service endpoint fails, the test will also fail.
 	*/
 	framework.ConformanceIt("should not be very high ", func() {
 		const (