add design principles

site/config.toml

@@ -59,6 +59,13 @@ sectionPagesMenu = "main"
     title = "Initial"
     url = "/docs/design/initial"
     weight = 1
+  [[menu.main]]
+    parent = "design"
+    identifier = "design-principles"
+    name = "Principles"
+    title = "Principles"
+    url = "/docs/design/principles"
+    weight = 1
   [[menu.main]]
     parent = "design"
     identifier = "base-image"

site/content/_index.md

@@ -66,7 +66,7 @@ See also: the Kubernetes [community page].
  - kind supports building Kubernetes with make/bash/docker, bazel, or installing from apt, in addition to pre-published builds.
  - kind is written in go, and can be used as a library, has binary releases
  - kind supports windows in addition to mac and linux
- - for more details see [the design documentation][design doc]
+ - for more details see the [design documentation][design doc]
 
 ## Alternatives
 
@@ -98,7 +98,7 @@ Participation in the Kubernetes community is governed by the [Kubernetes Code of
 [images]: https://github.com/kubernetes-sigs/kind/tree/master/images
 [kubetest]: https://github.com/kubernetes/test-infra/tree/master/kubetest
 [kubeadm]: https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm/
-[design doc]: ./docs/design/
+[design doc]: ./docs/design/initial
 [user guide]: ./docs/user/
 [the docs]: ./docs
 [SIG-Testing Mailing List]: https://groups.google.com/forum/#!forum/kubernetes-sig-testing

site/content/docs/_index.md

@@ -1,3 +1,7 @@
+<!--
+TODO(bentheelder): this page should probably be removed now that we have navigation
+-->
+
 # Welcome to kind's Documentation
 
 
@@ -20,6 +24,6 @@ out.
 You man also be interested in the [roadmap].
 
 [roadmap]: ./roadmap
-[design]: ./design/
+[design]: ./design/initial
 [user guide]: ./user/
 [dev guide]: ./devel/

site/content/docs/design/initial.md

@@ -6,6 +6,8 @@ This document covers some of the the initial design for `kind`.
 This mostly exists for historical purposes, the [the original proposal][original proposal]
 covers some more details.
 
+Going forward the [design principles] may be more relevant.
+
 ## Overview
 
 `kind` or **k**ubernetes **in** **d**ocker is a suite of tooling for local 
@@ -96,9 +98,10 @@ we can simply list and delete containers with this label.
 [q-lee]: https://github.com/q-lee
 [sig-testing-post]: https://groups.google.com/d/msg/kubernetes-sig-testing/uVkosorBnVc/8DDC3qvMAwAJ
 [kubernetes-sig-testing]: https://groups.google.com/forum/#!forum/kubernetes-sig-testing
-[pkg/cluster]: ./../../pkg/cluster
-[base-image.md]: ./base-image.md
-[node-image.md]: ./node-image.md
-[entrypoint]: ../../images/base/entrypoint
+[pkg/cluster]: https://github.com/kubernetes-sigs/kind/tree/master/pkg/cluster
+[base-image.md]: /docs/design/base-image
+[node-image.md]: /docs/design/node-image
+[entrypoint]: https://github.com/kubernetes-sigs/kind/tree/master/images/base/entrypoint
 [kubeconfig]: https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/
 [overlay network]: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#pod-network
+[design principles]: /docs/design/principles

site/content/docs/design/principles.md

@@ -0,0 +1,101 @@
+# Principles
+
+While developing kind the following principles should be considered.
+
+## Degrade Gracefully
+
+As much as possible kind should not fail, because it is to be used for testing.
+Partially degraded states can still be useful and still be debugged.
+
+As a concrete example: We "pre-load" images that the cluster depends on by
+packing them into the "[node image][node image]". If these images fail to
+load or are not present in the node image kind will fall back to letting the
+"node"s container runtime attempt to pull them.
+
+Similarly we must at least support all officially supported Kubernetes releases,
+which may mean gracefully degrading functionality for older releases.
+
+## Target CRI Functionality
+
+Currently kind only supports [docker] and uses it directly to create "node" containers.
+
+In order to aid [supporting multiple container runtimes] going forward and
+avoid unnecessary coupling, we should target functionality covered by the 
+Kubernetes [CRI][CRI] (Container Runtime Interface).
+
+## Leverage Existing Tooling
+
+Where possible we should _not_ reinvent the wheel.
+
+Examples include:
+
+- [kubeadm] is used to handle node configuration, certificates, etc.
+- [kustomize] is used to handle merging user provided config patches with our
+generated kubeadm configs
+- [k8s.io/apimachinery] is used to build our own configuration functionality
+- In general we re-use k8s.io utility libraries and generators
+
+Re-implementing some amount of functionality is expected, particularly
+between languages and for internal / insufficiently-generic components, but in general
+we should collaborate where possible.
+
+## Avoid Breaking Users
+
+Going forward kind will avoid breaking changes to the command line interface
+and configuration.
+
+Next we will extend this to a documented set of re-usable
+packages (To be determind, but likely IE [pkg/cluster]).
+
+While we are alpha grade currently, we will move to beta and respect
+the [Kubernetes Deprecation Policy].
+
+Externally facing features should consider long-term supportability and
+extensibility.
+
+## Follow Kubernetes API Conventions
+
+As a general rule of thumb kind prefers to implement configuration using
+Kubernetes style configuration files.
+
+While doing this we should respect the Kubernetes [API Conventions].
+
+Addtionally we should minimize the number of flags used and avoid structured
+values in flags as these cannot be versioned. 
+
+## Minimize Assumptions
+
+Avoid making any unnecessary assumptions. Currently we assume:
+
+- Docker is installed on the host and the current user has permission to talk to dockerd
+  - In the future we may instead only assume that a CRI is available. See [above](#target-cri-functionality).
+- "node" images follow our format
+  - However whenever we make changes we do not assume the updated contents definitely exist
+  - Metadata in the images is assumed to be correct
+- When building Kubernetes, we make the same assumptions & requirements as upstream
+
+## Be Hermetic
+
+As an extension of minimizing assumptions, kind should be as hermetic as possible.
+In other words:
+
+- Strive for reproducibility of operations
+- Avoid depending on external services, vendor / pre-pull dependencies
+
+## Consider Automation
+
+While kind strives to present a pleasant UX to users on their local machines,
+automation for end to end testing is the original & primary use case.
+Automated usage should be considered for all features.
+
+
+[docker]: https://www.docker.com/
+[node image]: /docs/design/node-image
+[supporting multiple container runtimes]: https://github.com/kubernetes-sigs/kind/issues/154
+[CRI]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-node/container-runtime-interface.md
+[kubeadm]: https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm/
+[kustomize]: https://github.com/kubernetes-sigs/kustomize
+[k8s.io/apimachinery]: https://github.com/kubernetes/apimachinery
+[Kubernetes Deprecation Policy]: https://kubernetes.io/docs/reference/using-api/deprecation-policy/
+[API Conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
+[pkg/cluster]: https://github.com/kubernetes-sigs/kind/tree/master/pkg/cluster

site/content/docs/devel/getting-started.md

@@ -4,7 +4,7 @@
 
 This page covers some of how to develop `kind` itself.
 
-The [project structure] and [design] may be helpful to review.
+The [design principles], [roadmap], [project structure], and [initial design] may be helpful to review.
 
 ## Get the required development tools for Linux or MacOS
 Here we will explain the software you need to use Linux or MacOS for `kind`
@@ -53,9 +53,10 @@ $ docker --version
 This documentation is written using Docker version 18.09.0.
 
 
-
-[project structure]: ./project-structure
-[design]: ./../design
+[design principles]: /docs/design/principles
+[roadmap]: /docs/roadmap
+[project structure]: /docs/devel/project-structure
+[initial design]: /docs/design/initial
 [github]: https://github.com/
 [community]: https://github.com/kubernetes/community
 [contributor]: https://github.com/kubernetes/community/blob/master/contributors/guide/README.md