adelorenzo/kilo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs,README.md: clean up documentation

Browse Source 
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>
This commit is contained in:
Lucas Servén Marín 2021-05-20 12:45:02 +02:00
parent 9f37a93859
commit 845df22a32
No known key found for this signature in database
GPG Key ID: 586FEAF680DA74AD
6 changed files with 19 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Makefile
View File

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

4
README.md
View File

@ -110,7 +110,7 @@ kubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kil
## VPN ## 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. 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 ```shell
cat <<'EOF' | kubectl apply -f - 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 - kgctl --kubeconfig $KUBECONFIG2 showconf node $n --as-peer -o yaml --allowed-ips $SERVICECIDR2 | kubectl --kubeconfig $KUBECONFIG1 apply -f -
done done
# Create a Service in cluster2 to mirror the Service in cluster1. # 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 apiVersion: v1
kind: Service kind: Service
metadata: metadata:

23
cmd/gen-docs/main.go → cmd/docs-gen/main.go
View File

@ -12,6 +12,8 @@
// See the License for the specific language governing permissions and // See the License for the specific language governing permissions and
// limitations under the License. // 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 package main
import ( import (
@ -35,15 +37,8 @@ This document is a reference of the API types introduced by Kilo.
var ( var (
links = map[string]string{ links = map[string]string{
"metav1.ObjectMeta": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#objectmeta-v1-meta", "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.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",
} }
selfLinks = map[string]string{} selfLinks = map[string]string{}
@ -69,7 +64,7 @@ func printTOC(types []KubeTypes) {
func printAPIDocs(paths []string) { func printAPIDocs(paths []string) {
fmt.Println(firstParagraph) fmt.Println(firstParagraph)
types := ParseDocumentationFrom(paths) types := parseDocumentationFrom(paths)
for _, t := range types { for _, t := range types {
strukt := t[0] strukt := t[0]
selfLinks[strukt.Name] = "#" + strings.ToLower(strukt.Name) 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 // we need to parse once more to now add the self links and the inlined fields
types = ParseDocumentationFrom(paths) types = parseDocumentationFrom(paths)
printTOC(types) 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 // KubeTypes is an array to represent all available types in a parsed file. [0] is for the type itself
type KubeTypes []Pair 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 // 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, ""}. // struct definitions that have no documentation as {name, ""}.
func ParseDocumentationFrom(srcs []string) []KubeTypes { func parseDocumentationFrom(srcs []string) []KubeTypes {
var docForTypes []KubeTypes var docForTypes []KubeTypes
for _, src := range srcs { for _, src := range srcs {

6
docs/api.md
View File

@ -12,7 +12,7 @@ This document is a reference of the API types introduced by Kilo.
## DNSOrIP ## 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 | | Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- | | ----- | ----------- | ------ | -------- |
@ -34,7 +34,7 @@ Peer is a WireGuard peer that should have access to the VPN.
## PeerEndpoint ## 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 | | 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 | | 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 | | 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 | | 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 | | publicKey | PublicKey is the WireGuard public key for the peer. | string | true |
[Back to TOC](#table-of-contents) [Back to TOC](#table-of-contents)

1
pkg/k8s/apis/kilo/v1alpha1/openapi_generated.go
View File

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

6
pkg/k8s/apis/kilo/v1alpha1/types.go
View File

@ -77,12 +77,12 @@ type PeerSpec struct {
PersistentKeepalive int `json:"persistentKeepalive,omitempty"` PersistentKeepalive int `json:"persistentKeepalive,omitempty"`
// PresharedKey is the optional symmetric encryption key for the peer. // PresharedKey is the optional symmetric encryption key for the peer.
// +optional // +optional
PresharedKey string `json:"presharedKey"` PresharedKey string `json:"presharedKey,omitempty"`
// PublicKey is the WireGuard public key for the peer. // PublicKey is the WireGuard public key for the peer.
PublicKey string `json:"publicKey"` 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 { type PeerEndpoint struct {
// DNSOrIP is a DNS name or an IP address. // DNSOrIP is a DNS name or an IP address.
DNSOrIP `json:"dnsOrIP"` DNSOrIP `json:"dnsOrIP"`
@ -91,7 +91,7 @@ type PeerEndpoint struct {
} }
// DNSOrIP represents either a DNS name or an IP address. // 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 { type DNSOrIP struct {
// DNS must be a valid RFC 1123 subdomain. // DNS must be a valid RFC 1123 subdomain.
// +optional // +optional