From d31e13048cec1b41bdc6335987cfefd4b2666ad9 Mon Sep 17 00:00:00 2001 From: David Oppenheimer Date: Tue, 14 Jul 2015 23:56:51 -0700 Subject: [PATCH] Move diagrams out of top-level docs/ directory and merge docs/devel/developer-guide.md into docs/devel/README.md --- docs/README.md | 2 +- docs/{ => design}/architecture.dia | Bin docs/design/architecture.md | 2 +- docs/{ => design}/architecture.png | Bin docs/{ => design}/architecture.svg | 0 docs/devel/README.md | 66 +++++++++++++++++++++++------ docs/devel/developer-guide.md | 62 --------------------------- docs/user-guide/README.md | 2 +- docs/{ => user-guide}/cadvisor.png | Bin docs/{ => user-guide}/gcm.png | Bin docs/user-guide/monitoring.md | 4 +- 11 files changed, 57 insertions(+), 81 deletions(-) rename docs/{ => design}/architecture.dia (100%) rename docs/{ => design}/architecture.png (100%) rename docs/{ => design}/architecture.svg (100%) delete mode 100644 docs/devel/developer-guide.md rename docs/{ => user-guide}/cadvisor.png (100%) rename docs/{ => user-guide}/gcm.png (100%) diff --git a/docs/README.md b/docs/README.md index 71ad8def5c5..19c9713d9fa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -28,7 +28,7 @@ certainly want the docs that go with that version. * The [Cluster Admin's guide](admin/README.md) is for anyone setting up a Kubernetes cluster or administering it. -* The [Developer guide](devel/developer-guide.md) is for anyone wanting to write +* The [Developer guide](devel/README.md) is for anyone wanting to write programs that access the kubernetes API, write plugins or extensions, or modify the core code of kubernetes. diff --git a/docs/architecture.dia b/docs/design/architecture.dia similarity index 100% rename from docs/architecture.dia rename to docs/design/architecture.dia diff --git a/docs/design/architecture.md b/docs/design/architecture.md index 3deeb3aa95e..1591068f991 100644 --- a/docs/design/architecture.md +++ b/docs/design/architecture.md @@ -24,7 +24,7 @@ certainly want the docs that go with that version. A running Kubernetes cluster contains node agents (kubelet) and master components (APIs, scheduler, etc), on top of a distributed storage solution. This diagram shows our desired eventual state, though we're still working on a few things, like making kubelet itself (all our components, really) run within containers, and making the scheduler 100% pluggable. -![Architecture Diagram](../architecture.png?raw=true "Architecture overview") +![Architecture Diagram](architecture.png?raw=true "Architecture overview") ## The Kubernetes Node diff --git a/docs/architecture.png b/docs/design/architecture.png similarity index 100% rename from docs/architecture.png rename to docs/design/architecture.png diff --git a/docs/architecture.svg b/docs/design/architecture.svg similarity index 100% rename from docs/architecture.svg rename to docs/design/architecture.svg diff --git a/docs/devel/README.md b/docs/devel/README.md index f97c49b4bcd..aed7276d062 100644 --- a/docs/devel/README.md +++ b/docs/devel/README.md @@ -20,28 +20,36 @@ certainly want the docs that go with that version. -# Developing Kubernetes +# Kubernetes Developer Guide -Docs in this directory relate to developing Kubernetes. +The developer guide is for anyone wanting to either write code which directly accesses the +kubernetes API, or to contribute directly to the kubernetes project. +It assumes some familiarity with concepts in the [User Guide](../user-guide/README.md) and the [Cluster Admin +Guide](../admin/README.md). -* **On Collaborative Development** ([collab.md](collab.md)): info on pull requests and code reviews. -* **Development Guide** ([development.md](development.md)): Setting up your environment tests. +## The process of developing and contributing code to the Kubernetes project -* **Making release notes** ([making-release-notes.md](making-release-notes.md)): Generating release nodes for a new release. +* **On Collaborative Development** ([collab.md](collab.md)): Info on pull requests and code reviews. + +* **GitHub Issues** ([issues.md](issues.md)): How incoming issues are reviewed and prioritized. + +* **Pull Request Process** ([pull-requests.md](pull-requests.md)): When and why pull requests are closed. + +* **Faster PR reviews** ([faster_reviews.md](faster_reviews.md)): How to get faster PR reviews. + +* **Getting Recent Builds** ([getting-builds.md](getting-builds.md)): How to get recent builds including the latest builds that pass CI. + + +## Setting up your dev environment, coding, and debugging + +* **Development Guide** ([development.md](development.md)): Setting up your development environment. * **Hunting flaky tests** ([flaky-tests.md](flaky-tests.md)): We have a goal of 99.9% flake free tests. Here's how to run your tests many times. -* **GitHub Issues** ([issues.md](issues.md)): How incoming issues are reviewed and prioritized. - * **Logging Conventions** ([logging.md](logging.md)]: Glog levels. -* **Pull Request Process** ([pull-requests.md](pull-requests.md)): When and why pull requests are closed. - -* **Releasing Kubernetes** ([releasing.md](releasing.md)): How to create a Kubernetes release (as in version) - and how the version information gets embedded into the built binaries. - * **Profiling Kubernetes** ([profiling.md](profiling.md)): How to plug in go pprof profiler to Kubernetes. * **Instrumenting Kubernetes with a new metric** @@ -51,9 +59,39 @@ Docs in this directory relate to developing Kubernetes. * **Coding Conventions** ([coding-conventions.md](coding-conventions.md)): Coding style advice for contributors. -* **Faster PR reviews** ([faster_reviews.md](faster_reviews.md)): How to get faster PR reviews. -* **Getting Recent Builds** ([getting-builds.md](getting-builds.md)): How to get recent builds including the latest builds to pass CI. +## Developing against the Kubernetes API + +* API objects are explained at [http://kubernetes.io/third_party/swagger-ui/](http://kubernetes.io/third_party/swagger-ui/). + +* **Annotations** ([docs/user-guide/annotations.md](../user-guide/annotations.md)): are for attaching arbitrary non-identifying metadata to objects. + Programs that automate Kubernetes objects may use annotations to store small amounts of their state. + +* **API Conventions** ([api-conventions.md](api-conventions.md)): + Defining the verbs and resources used in the Kubernetes API. + +* **API Client Libraries** ([client-libraries.md](client-libraries.md)): + A list of existing client libraries, both supported and user-contributed. + + +## Writing plugins + +* **Authentication Plugins** ([docs/admin/authentication.md](../admin/authentication.md)): + The current and planned states of authentication tokens. + +* **Authorization Plugins** ([docs/admin/authorization.md](../admin/authorization.md)): + Authorization applies to all HTTP requests on the main apiserver port. + This doc explains the available authorization implementations. + +* **Admission Control Plugins** ([admission_control](../design/admission_control.md)) + + +## Building releases + +* **Making release notes** ([making-release-notes.md](making-release-notes.md)): Generating release nodes for a new release. + +* **Releasing Kubernetes** ([releasing.md](releasing.md)): How to create a Kubernetes release (as in version) + and how the version information gets embedded into the built binaries. diff --git a/docs/devel/developer-guide.md b/docs/devel/developer-guide.md deleted file mode 100644 index 8801cb3d40b..00000000000 --- a/docs/devel/developer-guide.md +++ /dev/null @@ -1,62 +0,0 @@ - - - - -![WARNING](http://kubernetes.io/img/warning.png) -![WARNING](http://kubernetes.io/img/warning.png) -![WARNING](http://kubernetes.io/img/warning.png) - -

PLEASE NOTE: This document applies to the HEAD of the source -tree only. If you are using a released version of Kubernetes, you almost -certainly want the docs that go with that version.

- -Documentation for specific releases can be found at -[releases.k8s.io](http://releases.k8s.io). - -![WARNING](http://kubernetes.io/img/warning.png) -![WARNING](http://kubernetes.io/img/warning.png) -![WARNING](http://kubernetes.io/img/warning.png) - - - - -# Kubernetes Developer Guide - -The developer guide is for anyone wanting to either write code which directly accesses the -kubernetes API, or to contribute directly to the kubernetes project. -It assumes some familiarity with concepts in the [User Guide](../user-guide/README.md) and the [Cluster Admin -Guide](../admin/README.md). - - -## Developing against the Kubernetes API - -* API objects are explained at [http://kubernetes.io/third_party/swagger-ui/](http://kubernetes.io/third_party/swagger-ui/). - -* **Annotations** ([docs/user-guide/annotations.md](../user-guide/annotations.md)): are for attaching arbitrary non-identifying metadata to objects. - Programs that automate Kubernetes objects may use annotations to store small amounts of their state. - -* **API Conventions** ([api-conventions.md](api-conventions.md)): - Defining the verbs and resources used in the Kubernetes API. - -* **API Client Libraries** ([client-libraries.md](client-libraries.md)): - A list of existing client libraries, both supported and user-contributed. - -## Writing Plugins - -* **Authentication Plugins** ([docs/admin/authentication.md](../admin/authentication.md)): - The current and planned states of authentication tokens. - -* **Authorization Plugins** ([docs/admin/authorization.md](../admin/authorization.md)): - Authorization applies to all HTTP requests on the main apiserver port. - This doc explains the available authorization implementations. - -* **Admission Control Plugins** ([admission_control](../design/admission_control.md)) - -## Contributing to the Kubernetes Project - -See this [README](README.md). - - - -[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/developer-guide.md?pixel)]() - diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md index a04418ea6a6..716a1001b76 100644 --- a/docs/user-guide/README.md +++ b/docs/user-guide/README.md @@ -32,7 +32,7 @@ certainly want the docs that go with that version. -The user guide is intended for anyone who wants to run programs and services on an existing Kubernetes cluster. Setup and administration of a Kubernetes cluster is described in the [Cluster Admin Guide](../../docs/admin/README.md). The [Developer Guide](../../docs/devel/developer-guide.md) is for anyone wanting to either write code which directly accesses the kubernetes API, or to contribute directly to the kubernetes project. +The user guide is intended for anyone who wants to run programs and services on an existing Kubernetes cluster. Setup and administration of a Kubernetes cluster is described in the [Cluster Admin Guide](../../docs/admin/README.md). The [Developer Guide](../../docs/devel/README.md) is for anyone wanting to either write code which directly accesses the kubernetes API, or to contribute directly to the kubernetes project. Please ensure you have completed the [prerequisites for running examples from the user guide](prereqs.md). diff --git a/docs/cadvisor.png b/docs/user-guide/cadvisor.png similarity index 100% rename from docs/cadvisor.png rename to docs/user-guide/cadvisor.png diff --git a/docs/gcm.png b/docs/user-guide/gcm.png similarity index 100% rename from docs/gcm.png rename to docs/user-guide/gcm.png diff --git a/docs/user-guide/monitoring.md b/docs/user-guide/monitoring.md index 38cf005c9a3..200fc521812 100644 --- a/docs/user-guide/monitoring.md +++ b/docs/user-guide/monitoring.md @@ -38,7 +38,7 @@ cAdvisor is an open source container resource usage and performance analysis age On most Kubernetes clusters, cAdvisor exposes a simple UI for on-machine containers on port 4194. Here is a snapshot of part of cAdvisor’s UI that shows the overall machine usage: -![cAdvisor](../cadvisor.png) +![cAdvisor](cadvisor.png) ### Kubelet @@ -69,7 +69,7 @@ Here is a video showing how to setup and run a Google Cloud Monitoring backed He Here is a snapshot of the a Google Cloud Monitoring dashboard showing cluster-wide resource usage. -![Google Cloud Monitoring dashboard](../gcm.png) +![Google Cloud Monitoring dashboard](gcm.png) ## Try it out! Now that you’ve learned a bit about Heapster, feel free to try it out on your own clusters! The [Heapster repository](https://github.com/GoogleCloudPlatform/heapster) is available on GitHub. It contains detailed instructions to setup Heapster and its storage backends. Heapster runs by default on most Kubernetes clusters, so you may already have it! Feedback is always welcome. Please let us know if you run into any issues. Heapster and Kubernetes developers hang out in the [#google-containers](http://webchat.freenode.net/?channels=google-containers) IRC channel on freenode.net. You can also reach us on the [google-containers Google Groups mailing list](https://groups.google.com/forum/#!forum/google-containers).