docs,README.md: clean up documentation

This commit cleans up some typos in the documentation, clarifies some
explanations, fixes a bash script that would not expand a variable, and
renames the API documentation generator command from gen-docs to
docs-gen to match the output binary name.

Signed-off-by: Lucas Servén Marín <lserven@gmail.com>

Makefile

@@ -335,8 +335,8 @@ $(LISTER_GEN_BINARY):
 $(OPENAPI_GEN_BINARY):
 	go build -mod=vendor -o $@ k8s.io/kube-openapi/cmd/openapi-gen
 
-$(DOCS_GEN_BINARY): cmd/gen-docs/main.go
-	go build -mod=vendor -o $@ ./cmd/gen-docs
+$(DOCS_GEN_BINARY): cmd/docs-gen/main.go
+	go build -mod=vendor -o $@ ./cmd/docs-gen
 
 $(GOLINT_BINARY):
 	go build -mod=vendor -o $@ golang.org/x/lint/golint

README.md

@@ -110,7 +110,7 @@ kubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kil
 ## VPN
 
 Kilo also enables peers outside of a Kubernetes cluster to connect to the VPN, allowing cluster applications to securely access external services and permitting developers and support to securely debug cluster resources.
-In order to declare a peer, start by defining a Kilo peer resource:
+In order to declare a peer, start by defining a Kilo Peer resource:
 
 ```shell
 cat <<'EOF' | kubectl apply -f -
@@ -151,7 +151,7 @@ for n in $(kubectl --kubeconfig $KUBECONFIG2 get no -o name | cut -d'/' -f2); do
     kgctl --kubeconfig $KUBECONFIG2 showconf node $n --as-peer -o yaml --allowed-ips $SERVICECIDR2 | kubectl --kubeconfig $KUBECONFIG1 apply -f -
 done
 # Create a Service in cluster2 to mirror the Service in cluster1.
-cat <<'EOF' | kubectl --kubeconfig $KUBECONFIG2 apply -f -
+cat <<EOF | kubectl --kubeconfig $KUBECONFIG2 apply -f -
 apiVersion: v1
 kind: Service
 metadata:

cmd/docs-gen/main.go

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// This file was adapted from https://github.com/prometheus-operator/prometheus-operator/blob/master/cmd/po-docgen/api.go.
+
 package main
 
 import (
@@ -35,15 +37,8 @@ This document is a reference of the API types introduced by Kilo.
 
 var (
 	links = map[string]string{
-		"metav1.ObjectMeta":        "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#objectmeta-v1-meta",
-		"metav1.ListMeta":          "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#listmeta-v1-meta",
-		"metav1.LabelSelector":     "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#labelselector-v1-meta",
-		"v1.ResourceRequirements":  "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#resourcerequirements-v1-core",
-		"v1.LocalObjectReference":  "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#localobjectreference-v1-core",
-		"v1.SecretKeySelector":     "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#secretkeyselector-v1-core",
-		"v1.PersistentVolumeClaim": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#persistentvolumeclaim-v1-core",
-		"v1.EmptyDirVolumeSource":  "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#emptydirvolumesource-v1-core",
-		"apiextensionsv1.JSON":     "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#json-v1-apiextensions-k8s-io",
+		"metav1.ObjectMeta": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#objectmeta-v1-meta",
+		"metav1.ListMeta":   "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#listmeta-v1-meta",
 	}
 
 	selfLinks = map[string]string{}
@@ -69,7 +64,7 @@ func printTOC(types []KubeTypes) {
 func printAPIDocs(paths []string) {
 	fmt.Println(firstParagraph)
 
-	types := ParseDocumentationFrom(paths)
+	types := parseDocumentationFrom(paths)
 	for _, t := range types {
 		strukt := t[0]
 		selfLinks[strukt.Name] = "#" + strings.ToLower(strukt.Name)
@@ -77,7 +72,7 @@ func printAPIDocs(paths []string) {
 	}
 
 	// we need to parse once more to now add the self links and the inlined fields
-	types = ParseDocumentationFrom(paths)
+	types = parseDocumentationFrom(paths)
 
 	printTOC(types)
 
@@ -107,11 +102,11 @@ type Pair struct {
 // KubeTypes is an array to represent all available types in a parsed file. [0] is for the type itself
 type KubeTypes []Pair
 
-// ParseDocumentationFrom gets all types' documentation and returns them as an
+// parseDocumentationFrom gets all types' documentation and returns them as an
 // array. Each type is again represented as an array (we have to use arrays as we
-// need to be sure for the order of the fields). This function returns fields and
+// need to be sure of the order of the fields). This function returns fields and
 // struct definitions that have no documentation as {name, ""}.
-func ParseDocumentationFrom(srcs []string) []KubeTypes {
+func parseDocumentationFrom(srcs []string) []KubeTypes {
 	var docForTypes []KubeTypes
 
 	for _, src := range srcs {

docs/api.md

@@ -12,7 +12,7 @@ This document is a reference of the API types introduced by Kilo.
 
 ## DNSOrIP
 
-DNSOrIP represents either a DNS name or an IP address. IPs, as they are more specific, are preferred.
+DNSOrIP represents either a DNS name or an IP address. When both are given, the IP address, as it is more specific, override the DNS name.
 
 | Field | Description | Scheme | Required |
 | ----- | ----------- | ------ | -------- |
@@ -34,7 +34,7 @@ Peer is a WireGuard peer that should have access to the VPN.
 
 ## PeerEndpoint
 
-PeerEndpoint represents a WireGuard enpoint, which is a ip:port tuple.
+PeerEndpoint represents a WireGuard endpoint, which is an IP:port tuple.
 
 | Field | Description | Scheme | Required |
 | ----- | ----------- | ------ | -------- |
@@ -63,7 +63,7 @@ PeerSpec is the description and configuration of a peer.
 | allowedIPs | AllowedIPs is the list of IP addresses that are allowed for the given peer's tunnel. | []string | true |
 | endpoint | Endpoint is the initial endpoint for connections to the peer. | *[PeerEndpoint](#peerendpoint) | false |
 | persistentKeepalive | PersistentKeepalive is the interval in seconds of the emission of keepalive packets by the peer. This defaults to 0, which disables the feature. | int | false |
-| presharedKey | PresharedKey is the optional symmetric encryption key for the peer. | string | true |
+| presharedKey | PresharedKey is the optional symmetric encryption key for the peer. | string | false |
 | publicKey | PublicKey is the WireGuard public key for the peer. | string | true |
 
 [Back to TOC](#table-of-contents)

pkg/k8s/apis/kilo/v1alpha1/openapi_generated.go

@@ -325,7 +325,6 @@ func schema_k8s_apis_kilo_v1alpha1_PeerSpec(ref common.ReferenceCallback) common
 					"presharedKey": {
 						SchemaProps: spec.SchemaProps{
 							Description: "PresharedKey is the optional symmetric encryption key for the peer.",
-							Default:     "",
 							Type:        []string{"string"},
 							Format:      "",
 						},

pkg/k8s/apis/kilo/v1alpha1/types.go

@@ -77,12 +77,12 @@ type PeerSpec struct {
 	PersistentKeepalive int `json:"persistentKeepalive,omitempty"`
 	// PresharedKey is the optional symmetric encryption key for the peer.
 	// +optional
-	PresharedKey string `json:"presharedKey"`
+	PresharedKey string `json:"presharedKey,omitempty"`
 	// PublicKey is the WireGuard public key for the peer.
 	PublicKey string `json:"publicKey"`
 }
 
-// PeerEndpoint represents a WireGuard enpoint, which is a ip:port tuple.
+// PeerEndpoint represents a WireGuard endpoint, which is an IP:port tuple.
 type PeerEndpoint struct {
 	// DNSOrIP is a DNS name or an IP address.
 	DNSOrIP `json:"dnsOrIP"`
@@ -91,7 +91,7 @@ type PeerEndpoint struct {
 }
 
 // DNSOrIP represents either a DNS name or an IP address.
-// IPs, as they are more specific, are preferred.
+// When both are given, the IP address, as it is more specific, override the DNS name.
 type DNSOrIP struct {
 	// DNS must be a valid RFC 1123 subdomain.
 	// +optional