Add munger to verify kubectl -f targets, fix docs

kubernetes · Jul 16, 2015 · f7512d0 · f7512d0
1 parent 596a8a4
commit f7512d0
Show file tree

Hide file tree

Showing 47 changed files with 377 additions and 122 deletions.
diff --git a/cmd/mungedocs/kubectl_dash_f.go b/cmd/mungedocs/kubectl_dash_f.go
@@ -0,0 +1,116 @@
+/*
+Copyright 2015 The Kubernetes Authors All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"path"
+	"strings"
+)
+
+// Looks for lines that have kubectl commands with -f flags and files that
+// don't exist.
+func checkKubectlFileTargets(file string, markdown []byte) ([]byte, error) {
+	inside := false
+	lines := splitLines(markdown)
+	errors := []string{}
+	for i := range lines {
+		if strings.HasPrefix(lines[i], "```") {
+			inside = !inside
+		}
+		if inside {
+			if err := lookForKubectl(lines, i); err != nil {
+				errors = append(errors, err.Error())
+			}
+		}
+	}
+	err := error(nil)
+	if len(errors) != 0 {
+		err = fmt.Errorf("%s", strings.Join(errors, "\n"))
+	}
+	return markdown, err
+}
+
+func lookForKubectl(lines []string, lineNum int) error {
+	fields := strings.Fields(lines[lineNum])
+	for i := range fields {
+		if fields[i] == "kubectl" {
+			return gotKubectl(lineNum, fields, i)
+		}
+	}
+	return nil
+}
+
+func gotKubectl(line int, fields []string, fieldNum int) error {
+	for i := fieldNum + 1; i < len(fields); i++ {
+		switch fields[i] {
+		case "create", "update", "replace", "delete":
+			return gotCommand(line, fields, i)
+		}
+	}
+	return nil
+}
+
+func gotCommand(line int, fields []string, fieldNum int) error {
+	for i := fieldNum + 1; i < len(fields); i++ {
+		if strings.HasPrefix(fields[i], "-f") {
+			return gotDashF(line, fields, i)
+		}
+	}
+	return nil
+}
+
+func gotDashF(line int, fields []string, fieldNum int) error {
+	target := ""
+	if fields[fieldNum] == "-f" {
+		if fieldNum+1 == len(fields) {
+			return fmt.Errorf("ran out of fields after '-f'")
+		}
+		target = fields[fieldNum+1]
+	} else {
+		target = fields[fieldNum][2:]
+	}
+	// Turn dirs into file-like names.
+	target = strings.TrimRight(target, "/")
+
+	// Now exclude special-cases
+
+	if target == "-" || target == "FILENAME" {
+		// stdin and "FILENAME" are OK
+		return nil
+	}
+	if strings.HasPrefix(target, "http://") || strings.HasPrefix(target, "https://") {
+		// URLs are ok
+		return nil
+	}
+	if strings.HasPrefix(target, "./") {
+		// Same-dir files are usually created in the same example
+		return nil
+	}
+	if strings.HasPrefix(target, "/") {
+		// Absolute paths tend to be /tmp/* and created in the same example.
+		return nil
+	}
+
+	// If we got here we expect the file to exist.
+	_, err := os.Stat(path.Join(*rootDir, *repoRoot, target))
+	if os.IsNotExist(err) {
+		return fmt.Errorf("%d: target file %q does not exist", line, target)
+	}
+	return err
+}
diff --git a/cmd/mungedocs/kubectl_dash_f_test.go b/cmd/mungedocs/kubectl_dash_f_test.go
@@ -0,0 +1,139 @@
+/*
+Copyright 2015 The Kubernetes Authors All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package main
+
+import "testing"
+
+func TestKubectlDashF(t *testing.T) {
+	var cases = []struct {
+		in string
+		ok bool
+	}{
+		// No match
+		{"", true},
+		{
+			"Foo\nBar\n",
+			true,
+		},
+		{
+			"Foo\nkubectl blah blech\nBar",
+			true,
+		},
+		{
+			"Foo\n```shell\nkubectl blah blech\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create blech\n```\nBar",
+			true,
+		},
+		// Special cases
+		{
+			"Foo\n```\nkubectl -blah create -f -\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create -f-\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create -f FILENAME\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create -fFILENAME\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create -f http://google.com/foobar\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create -fhttp://google.com/foobar\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create -f ./foobar\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create -f./foobar\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create -f /foobar\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create -f/foobar\n```\nBar",
+			true,
+		},
+		// Real checks
+		{
+			"Foo\n```\nkubectl -blah create -f mungedocs.go\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah create -fmungedocs.go\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah update -f mungedocs.go\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah update -fmungedocs.go\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah replace -f mungedocs.go\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah replace -fmungedocs.go\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah delete -f mungedocs.go\n```\nBar",
+			true,
+		},
+		{
+			"Foo\n```\nkubectl -blah delete -fmungedocs.go\n```\nBar",
+			true,
+		},
+		// Failures
+		{
+			"Foo\n```\nkubectl -blah delete -f does_not_exist\n```\nBar",
+			false,
+		},
+		{
+			"Foo\n```\nkubectl -blah delete -fdoes_not_exist\n```\nBar",
+			false,
+		},
+	}
+	for i, c := range cases {
+		*rootDir = ""
+		*repoRoot = ""
+		_, err := checkKubectlFileTargets("filename.md", []byte(c.in))
+		if err != nil && c.ok {
+			t.Errorf("case[%d]: expected success, got %v", i, err)
+		}
+		if err == nil && !c.ok {
+			t.Errorf("case[%d]: unexpected success", i)
+		}
+	}
+}
diff --git a/cmd/mungedocs/mungedocs.go b/cmd/mungedocs/mungedocs.go
@@ -49,6 +49,7 @@ Examples:
 		{"check-links", checkLinks},
 		{"unversioned-warning", updateUnversionedWarning},
 		{"analytics", checkAnalytics},
+		{"kubectl-dash-f", checkKubectlFileTargets},
 	}
 	availableMungeList = func() string {
 		names := []string{}

diff --git a/docs/admin/resource-quota.md b/docs/admin/resource-quota.md
@@ -93,7 +93,7 @@ $ cat <<EOF > quota.json
   }
 }
 EOF
-$ kubectl create -f quota.json
+$ kubectl create -f ./quota.json
 $ kubectl get quota
 NAME
 quota

diff --git a/docs/admin/service-accounts-admin.md b/docs/admin/service-accounts-admin.md
@@ -94,7 +94,7 @@ secret.json:
 	"type": "kubernetes.io/service-account-token"
 }
 
-$ kubectl create -f secret.json
+$ kubectl create -f ./secret.json
 $ kubectl describe secret mysecretname
 ```
 

diff --git a/docs/devel/flaky-tests.md b/docs/devel/flaky-tests.md
@@ -56,7 +56,7 @@ spec:
 Note that we omit the labels and the selector fields of the replication controller, because they will be populated from the labels field of the pod template by default.
 
 ```
-kubectl create -f controller.yaml
+kubectl create -f ./controller.yaml
 ```
 
 This will spin up 24 instances of the test.  They will run to completion, then exit, and the kubelet will restart them, accumulating more and more runs of the test.

diff --git a/docs/getting-started-guides/aws-coreos.md b/docs/getting-started-guides/aws-coreos.md
@@ -194,7 +194,7 @@ Create a pod manifest: `pod.json`
 ### Create the pod using the kubectl command line tool
 
 ```bash
-kubectl create -f pod.json
+kubectl create -f ./pod.json
 ```
 
 ### Testing

diff --git a/docs/getting-started-guides/coreos/azure/README.md b/docs/getting-started-guides/coreos/azure/README.md
@@ -97,12 +97,12 @@ kube-02             environment=production   Ready
 Let's follow the Guestbook example now:
 ```
 cd guestbook-example
-kubectl create -f redis-master-controller.json
-kubectl create -f redis-master-service.json
-kubectl create -f redis-slave-controller.json
-kubectl create -f redis-slave-service.json
-kubectl create -f frontend-controller.json
-kubectl create -f frontend-service.json
+kubectl create -f examples/guestbook/redis-master-controller.yaml
+kubectl create -f examples/guestbook/redis-master-service.yaml
+kubectl create -f examples/guestbook/redis-slave-controller.yaml
+kubectl create -f examples/guestbook/redis-slave-service.yaml
+kubectl create -f examples/guestbook/frontend-controller.yaml
+kubectl create -f examples/guestbook/frontend-service.yaml
 ```
 
 You need to wait for the pods to get deployed, run the following and wait for `STATUS` to change from `Unknown`, through `Pending` to `Running`.

diff --git a/docs/getting-started-guides/fedora/fedora_manual_config.md b/docs/getting-started-guides/fedora/fedora_manual_config.md
@@ -146,7 +146,7 @@ done
 Now create a node object internally in your kubernetes cluster by running:
 
 ```
-$ kubectl create -f node.json
+$ kubectl create -f ./node.json
 
 $ kubectl get nodes
 NAME                LABELS              STATUS
@@ -205,7 +205,7 @@ fed-node          name=fed-node-label     Ready
 To delete _fed-node_ from your kubernetes cluster, one should run the following on fed-master (Please do not do it, it is just for information):
 
 ```
-$ kubectl delete -f node.json
+$ kubectl delete -f ./node.json
 ```
 
 *You should be finished!*

diff --git a/docs/getting-started-guides/logging.md b/docs/getting-started-guides/logging.md
@@ -63,7 +63,7 @@ This pod specification has one container which runs a bash script when the conta
 namespace.
 
 ```
- $ kubectl create -f counter-pod.yaml
+ $ kubectl create -f examples/blog-logging/counter-pod.yaml
  pods/counter
 ```
 
@@ -114,7 +114,7 @@ pods/counter
 Now let’s restart the counter.
 
 ```
-$ kubectl create -f counter-pod.yaml
+$ kubectl create -f examples/blog-logging/counter-pod.yaml
 pods/counter
 ```
 Let’s wait for the container to restart and get the log lines again.

diff --git a/docs/getting-started-guides/mesos.md b/docs/getting-started-guides/mesos.md
@@ -198,7 +198,7 @@ EOPOD
 Send the pod description to Kubernetes using the `kubectl` CLI:
 
 ```bash
-$ kubectl create -f nginx.yaml
+$ kubectl create -f ./nginx.yaml
 pods/nginx
 ```
 
@@ -256,8 +256,8 @@ sed -e "s/{{ pillar\['dns_server'\] }}/10.10.10.10/g" \
 Now the kube-dns pod and service are ready to be launched:
 
 ```bash
-kubectl create -f skydns-rc.yaml
-kubectl create -f skydns-svc.yaml
+kubectl create -f ./skydns-rc.yaml
+kubectl create -f ./skydns-svc.yaml
 ```
 
 Check with `kubectl get pods --namespace=kube-system` that 3/3 containers of the pods are eventually up and running. Note that the kube-dns pods run in the `kube-system` namespace, not in  `default`.
@@ -286,7 +286,7 @@ EOF
 Then start the pod:
 
 ```bash
-kubectl create -f busybox.yaml
+kubectl create -f ./busybox.yaml
 ```
 
 When the pod is up and running, start a lookup for the Kubernetes master service, made available on 10.10.10.1 by default:

diff --git a/docs/man/man1/kubectl-create.1 b/docs/man/man1/kubectl-create.1
@@ -133,7 +133,7 @@ JSON and YAML formats are accepted.
 
 .nf
 // Create a pod using the data in pod.json.
-$ kubectl create \-f pod.json
+$ kubectl create \-f ./pod.json
 
 // Create a pod based on the JSON passed into stdin.
 $ cat pod.json | kubectl create \-f \-
-Original file line number
+Diff line change
@@ Expand Up / @@ -93,7 +93,7 @@ $ cat <<EOF > quota.json @@
       }
     }
     EOF
-    $ kubectl create -f quota.json
+    $ kubectl create -f ./quota.json
     $ kubectl get quota
     NAME
     quota
@@ Expand Down @@