diff --git a/_includes/templates/_errorthrower.md b/_includes/templates/_errorthrower.md new file mode 100644 index 0000000000..f956a75709 --- /dev/null +++ b/_includes/templates/_errorthrower.md @@ -0,0 +1,16 @@ +### ERROR: You must define a `{{ include.missing_block }}` block +{: style="color:red" } + +This template requires that you provide text that {{ include.purpose }}. The text in this block will +be displayed under the heading **{{ include.heading }}**. + +To get rid of this message and take advantage of this template, define the `{{ include.missing_block }}` +variable and populate it with content. + +```liquid +{% raw %}{%{% endraw %} capture {{ include.missing_block }} {% raw %}%}{% endraw %} +Text that {{ include.purpose }}. +{% raw %}{%{% endraw %} endcapture {% raw %}%}{% endraw %} +``` + + \ No newline at end of file diff --git a/_includes/templates/concept-overview.md b/_includes/templates/concept-overview.md index 07a0d14ce0..0cb0831a81 100644 --- a/_includes/templates/concept-overview.md +++ b/_includes/templates/concept-overview.md @@ -10,20 +10,8 @@ {% else %} -### ERROR: You must define a "what_is" block -{: style="color:red" } +{% include templates/_errorthrower.md missing_block='what_is' heading='What is a (Concept)?' purpose='explains what this concept is and its purpose.' %} -This template requires that you explain what this concept is. This explanation will -be displayed under the heading, **What is a {{ concept }}?** - -To get rid of this message and take advantage of this template, define the `what_is` -variable and populate it with content. - -```liquid -{% raw %}{% capture what_is %}{% endraw %} -A {{ concept }} does x and y and z...(etc, etc, text goes on) -{% raw %}{% endcapture %}{% endraw %} -``` {% endif %} @@ -35,45 +23,21 @@ A {{ concept }} does x and y and z...(etc, etc, text goes on) {% else %} -### ERROR: You must define a "when_to_use" block -{: style="color:red" } +{% include templates/_errorthrower.md missing_block='when_to_use' heading='When to use (Concept)' purpose='explains when to use this object.' %} -This template requires that you explain when to use this object. This explanation will -be displayed under the heading, **When to use {{ concept }}s** - -To get rid of this message and take advantage of this template, define the `when_to_use` -variable and populate it with content. - -```liquid -{% raw %}{% capture when_to_use %}{% endraw %} -You should use {{ concept }} when... -{% raw %}{% endcapture %}{% endraw %} -``` {% endif %} {% if when_not_to_use %} -### When not to use {{ concept }}s (alternatives) +### When not to use {{ concept }}s {{ when_not_to_use }} {% else %} -### ERROR: You must define a "when_not_to_use" block -{: style="color:red" } +{% include templates/_errorthrower.md missing_block='when_not_to_use' heading='When not to use (Concept)' purpose='explains when not to use this object.' %} -This template requires that you explain when not to use this object. This explanation will -be displayed under the heading, **When not to use {{ concept }}s (alternatives)** - -To get rid of this message and take advantage of this template, define the `when_not_to_use` -block and populate it with content. - -```liquid -{% raw %}{% capture when_not_to_use %}{% endraw %} -You should not use {{ concept }} if... -{% raw %}{% endcapture %}{% endraw %} -``` {% endif %} @@ -85,69 +49,23 @@ You should not use {{ concept }} if... {% else %} -### ERROR: You must define a "status" block -{: style="color:red" } +{% include templates/_errorthrower.md missing_block='status' heading='Retrieving status for a (Concept)' purpose='explains how to retrieve a status description for this object.' %} -This template requires that you explain the current status of support for this object. -This explanation will be displayed under the heading, **{{ concept }} status**. - -To get rid of this message and take advantage of this template, define the `status` -block and populate it with content. - -```liquid -{% raw %}{% capture status %}{% endraw %} -The current status of {{ concept }}s is... -{% raw %}{% endcapture %}{% endraw %} -``` {% endif %} -{% if required_fields %} +{% if usage %} -### {{ concept }} spec +#### Usage -#### Required Fields - -{{ required_fields }} +{{ usage }} {% else %} -### ERROR: You must define a "required_fields" block -{: style="color:red" } - -This template requires that you provide a Markdown list of required fields for this -object. This list will be displayed under the heading **Required Fields**. - -To get rid of this message and take advantage of this template, define the `required_fields` -block and populate it with content. - -```liquid -{% raw %}{% capture required_fields %} -* `kind`: Always `Pod`. -* `apiVersion`: Currently `v1`. -* `metadata`: An object containing: - * `name`: Required if `generateName` is not specified. The name of this pod. - It must be an - [RFC1035](https://www.ietf.org/rfc/rfc1035.txt) compatible value and be - unique within the namespace. -{% endcapture %}{% endraw %} -``` - -**Note**: You can also define a `common_fields` block that will go under a heading -directly underneath **Required Fields** called **Common Fields**, but it is -not required. -{% endif %} - - -{% if common_fields %} - -#### Common Fields - -{{ common_fields }} +{% include templates/_errorthrower.md missing_block='usage' heading='Usage' purpose='shows the most basic, common use case for this object, in the form of a code sample, command, etc, using tabs to show multiple approaches' %} {% endif %} - {% else %} diff --git a/_includes/templates/kubectl.md b/_includes/templates/kubectl.md new file mode 100644 index 0000000000..1b50a7b95d --- /dev/null +++ b/_includes/templates/kubectl.md @@ -0,0 +1,37 @@ +{% if command %} + +# {% if site.data.kubectl[command].name != "kubectl" %}kubectl {% endif %}{{ site.data.kubectl[command].name }} + +{{ site.data.kubectl[command].synopsis }} + +## Description + +{{ site.data.kubectl[command].description }} + +{% if site.data.kubectl[command].options %} +## Options + +| Option | Shorthand | Default Value | Usage | +|--------------------|---------------|-------|{% for option in site.data.kubectl[command].options %} +| `{{option.name | strip}}` | {% if option.shorthand %}`{{ option.shorthand | strip }}`{% endif %} | {% if option.default_value %}`{{option.default_value| strip}}`{% endif %} | {% if option.usage %}{{option.usage| strip | replace:'|',', '}}{% endif %} |{% endfor %} +{% endif %} + +{% if site.data.kubectl[command].inherited_options %} +## Inherited Options + +| Option | Shorthand | Default Value | Usage | +|--------------------|---------------|-------|{% for option in site.data.kubectl[command].inherited_options %} +| `{{option.name | strip}}` | {% if option.shorthand %}`{{ option.shorthand | strip }}`{% endif %} | {% if option.default_value %}`{{option.default_value| strip}}`{% endif %} | {% if option.usage %}{{option.usage| strip | replace:'|',', '}}{% endif %} |{% endfor %} +{% endif %} + +## See also + +{% for seealso in site.data.kubectl[command].see_also %} +- [`{{ seealso }}`](/docs/kubectl/{% if seealso != "kubectl" %}kubectl_{{seealso}}{% endif %}) +{% endfor %} + +{% else %} + +{% include templates/_errorthrower.md missing_block='command' heading='kubectl (command)' purpose='names the kubectl command, so that the appropriate YAML file (from _data/kubectl) can be transformed into a page.' %} + +{% endif %} \ No newline at end of file diff --git a/_includes/templates/task.md b/_includes/templates/task.md new file mode 100644 index 0000000000..abb7ea6b10 --- /dev/null +++ b/_includes/templates/task.md @@ -0,0 +1,36 @@ +{% if purpose %} + +### Purpose + +{{ purpose }} + +{% else %} + +{% include templates/_errorthrower.md missing_block='purpose' heading='Purpose' purpose='states, in one sentence, what the purpose of this document is, so that the user will know what they are able to achieve if they follow the provided steps.' %} + +{% endif %} + +{% if recommended_background %} + +### Recommended background + +{{ recommended_background }} + +{% else %} + +{% include templates/_errorthrower.md missing_block='recommended_background' heading='Recommended background' purpose='lists assumptions of baseline knowledge that you expect the user to have before reading ahead.' %} + +{% endif %} + + +{% if step_by_step %} + +### Step by step + +{{ step_by_step }} + +{% else %} + +{% include templates/_errorthrower.md missing_block='step_by_step' heading='Step by step' purpose='lists a series of linear, numbered steps that accomplish the described task.' %} + +{% endif %} \ No newline at end of file diff --git a/docs/templatedemos/blankkubectl.md b/docs/templatedemos/blankkubectl.md new file mode 100644 index 0000000000..7403b84fb6 --- /dev/null +++ b/docs/templatedemos/blankkubectl.md @@ -0,0 +1,3 @@ +--- +--- +{% include templates/kubectl.md %} \ No newline at end of file diff --git a/docs/templatedemos/blanktask.md b/docs/templatedemos/blanktask.md new file mode 100644 index 0000000000..026c1afc41 --- /dev/null +++ b/docs/templatedemos/blanktask.md @@ -0,0 +1,3 @@ +--- +--- +{% include templates/task.md %} \ No newline at end of file diff --git a/docs/templatedemos/filledout.md b/docs/templatedemos/filledout.md index 7eef09134e..ba56528a20 100644 --- a/docs/templatedemos/filledout.md +++ b/docs/templatedemos/filledout.md @@ -1,32 +1,80 @@ --- --- - -{% assign concept="Replication Controller" %} +{% assign concept="Pod" %} {% capture what_is %} -A Replication Controller does x and y and z...(etc, etc, text goes on) +A pod is the vehicle for running containers in Kubernetes. A pod consists of: + +- One or more containers +- An IP address that is unique within the cluster +- Optionally: Environment variables, storage volumes, and enterprise features (such as health checking) + +Resources are shared amongst containers in the pod. Containers within a pod also share an IP address and port space, and can find each other via localhost, or interprocess communications (such as semaphores). + +![Pod diagram](/images/docs/pod-overview.svg){: style="max-width: 25%" } +{% comment %}https://drive.google.com/open?id=1pQe4-s76fqyrzB8f3xoJo4MPLNVoBlsE1tT9MyLNINg{% endcomment %} + {% endcapture %} {% capture when_to_use %} -You should use Replication Controller when... +Pods are used any time you need a container to be run. However, they are rarely created by a user, and are instead automatically created by controllers such as jobs, replication controllers, deployments, daemon set. The following table describes the strategy each controller uses to create pods. + + +| Controller | Usage Strategy | +|------------|----------------| +| Deployment | For running pods as a continuous and healthy application | +| Replication Controller | Used for the same purpose as Deployments (superseded Replication Controllers) | +| Jobs | For running pods "to completion" (which are then shut down) | +| Daemon Set | Mainly for performing operations on any nodes that match given parameters | + {% endcapture %} {% capture when_not_to_use %} -You should not use Replication Controller if... +Do not use pods directly. Pods should always be managed by a controller. {% endcapture %} {% capture status %} -The current status of Replication Controllers is... +To retrieve the status of a pod, run the following command: + +```shell +kubectl get pod +``` + +| Return Value | Description | +|--------------|-------------| +| `READY` | Describes the number of containers that are ready to recieve traffic. | +| `STATUS` | A value from the `PodPhase` enum describing the current status of the pod. Can be `Running`, `Pending`, `Succeeded`, `Failed`, and `Unknown`. | + +TODO: Link to refpage for `kubectl get pod` + + +To get a full description of a pod, including past events, run the following command: + +```shell +kubectl describe pod +``` + +TODO: Link to refpage for `kubectl describe pod` + +#### Possible status results + +| Value | Description | +|------------|----------------| +| Deployment | For running pods as a continuous and healthy application | +| Replication Controller | Used for the same purpose as Deployments (superseded Replication Controllers) | +| Jobs | For running pods "to completion" (which are then shut down) | +| Daemon Set | Mainly for performing operations on any nodes that match given parameters | + {% endcapture %} -{% capture required_fields %} -* `kind`: Always `Pod`. -* `apiVersion`: Currently `v1`. -* `metadata`: An object containing: - * `name`: Required if `generateName` is not specified. The name of this pod. - It must be an - [RFC1035](https://www.ietf.org/rfc/rfc1035.txt) compatible value and be - unique within the namespace. +{% capture usage %} +Pods are defined when configuring the controller of your choice. In controller specifications, +the parts that define the contents of the pod are inside the `template:` section. + +```yaml +YAML EXAMPLE HERE +``` + {% endcapture %} {% include templates/concept-overview.md %} \ No newline at end of file diff --git a/docs/templatedemos/index.md b/docs/templatedemos/index.md index d199e6d074..30bee2839c 100644 --- a/docs/templatedemos/index.md +++ b/docs/templatedemos/index.md @@ -1,19 +1,134 @@ --- --- - + + # Template Demos -This page demonstrates new doc templates being worked on. -Click the headings to see the source of the template in GitHub. +
+

Concept Overviews

+
{% capture instructions %} -## [Concept Overviews](https://github.com/kubernetes/kubernetes.github.io/blob/master/_includes/templates/concept-overview.md) +A concept overview covers the most essential, important information about core Kubernetes concepts and features. -- [Blank page that is trying to use template](blank/) -- [Partially filled out page](partial/) -- [Completely filled out page](filledout/) +### Demos -## [Landing Pages](https://github.com/kubernetes/kubernetes.github.io/blob/master/_includes/templates/landing-page.md) +- [Blank page that is trying to use template](blank/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blank.md)) +- [Partially filled out page](partial/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/partial.md)) +- [Completely filled out page](filledout/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/filledout.md)) -- [Blank](blanklanding/) -- [Filled Out](landingpage/) \ No newline at end of file +### Usage + +To use this template, create a new file with these contents: + +```liquid{% raw %} +--- +--- +{% capture concept %}{% endcapture %} +{% capture what_is %}{% endcapture %} +{% capture when_to_use %}{% endcapture %} +{% capture when_not_to_use %}{% endcapture %} +{% capture status %}{% endcapture %} +{% capture usage %}{% endcapture %} +{% include templates/concept-overview.md %} +{% endraw %}``` + +### Adding page to navigation + +Once your page is saved, somewhere in the `/docs/` directory, add a reference to the `concepts.yml` file under `/_data/` so that it will appear in the left-hand navigation of the site. This is also where you add a title to the page. + +{% endcapture %} +{{ instructions | markdownify }} + +
+ + +

Task

+
{% capture instructions %} + +A task page offers step-by-step instructions for completing a task with Kubernetes. **A task page should be narrowly focused on task completion and not delve into concepts or reference information.** + +### Demos + +- [Blank](blanktask/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blanktask.md)) +- [Filled Out](task/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/task.md)) + +### Usage + +```liquid{% raw %} +--- +--- +{% capture purpose %}{% endcapture %} +{% capture recommended_background %}{% endcapture %} +{% capture step_by_step %}{% endcapture %} +{% include templates/task.md %} +{% endraw %}``` + +### Adding page to navigation + +Once your page is saved, somewhere in the `/docs/` directory, add a reference to the `tasks.yml` file under `/_data/` so that it will appear in the left-hand navigation of the site. This is also where you add a title to the page. + +{% endcapture %} +{{ instructions | markdownify }} + +
+ +

Landing Pages

+
{% capture instructions %} + +Landing pages are a set of clickable "cards" arranged in a grid. Each card has a heading and description, and optioninall, a thumbnail image. They are meant to be index pages that quickly forward users on to deeper content. + +### Demos + +- [Blank](blanklanding/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blanklanding.md)) +- [Filled Out](landingpage/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/landingpage.md)) + +### Usage + +To use this template, create a new file with these contents. Essentially, you declare the cards you want by inserting the following YAML structure in the front-matter YAML section at the top of the page, and the body of the page just has the include statement. + +```yaml +--- +cards: +- progression: no #"yes" = display cards as linearly progressing +- card: + title: Mean Stack + image: /images/docs/meanstack/image_0.png + description: Lorem ipsum dolor it verberum. +# repeat -card: items as necessary +--- +{% raw %}{% include templates/landing-page.md %}{% endraw %} +``` + +### Adding page to navigation + +Once your page is saved, somewhere in the `/docs/` directory, add a reference to the appropriate .yml file under `/_data/` so that it will appear in the left-hand navigation of the site. This is also where you add a title to the page. + +{% endcapture %} +{{ instructions | markdownify }} + +
+ + +

kubectl yaml

+
{% capture instructions %} +You probably shouldn't be using this, but we also have templates which consume YAML files that are generated by the Kubernetes authors. These are turned into pages which display the reference information for the various CLI tools. + +### Demos + +- [Blank](blankkubectl/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blankkubectl.md)) +- [Filled Out](kubectl/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/kubectl.md)) + +### Adding page to navigation + +Once your page is saved, somewhere in the `/docs/` directory, add a reference to the `concepts.yml` file under `/_data/` so that it will appear in the left-hand navigation of the site. This is also where you add a title to the page. + +{% endcapture %} +{{ instructions | markdownify }} + +
+
\ No newline at end of file diff --git a/docs/templatedemos/kubectl.md b/docs/templatedemos/kubectl.md new file mode 100644 index 0000000000..1c106b166d --- /dev/null +++ b/docs/templatedemos/kubectl.md @@ -0,0 +1,4 @@ +--- +--- +{% capture command %}kubectl_annotate{% endcapture %} +{% include templates/kubectl.md %} \ No newline at end of file diff --git a/docs/templatedemos/task.md b/docs/templatedemos/task.md new file mode 100644 index 0000000000..3803492f2b --- /dev/null +++ b/docs/templatedemos/task.md @@ -0,0 +1,62 @@ +--- +--- +# Doing a thing with a thing + +{% capture purpose %} +This document teaches you how to do a thing. +{% endcapture %} + +{% capture recommended_background %} +In order to do a thing, you must be familiar with the following: + +- [Thing 1](/foo/) +- [Thing 2](/bar/) + +{% endcapture %} + +{% capture step_by_step %} +Here's how to do a thing with a thing. + +#### 1. Prepare the thing + +Lorem ipsum dolor it verberum. + +#### 2. Run the thing command + +Lorem ipsum dolor it verberum. + +#### 3. Create the thing.yaml file + +Lorem ipsum dolor it verberum. + +```yaml +# Creates three nginx replicas +apiVersion: extensions/v1beta1 +kind: Deployment +metadata: + name: nginx-deployment +spec: + replicas: 3 + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.7.9 + ports: + - containerPort: 80 +``` + +#### 4. ??? + +Lorem ipsum dolor it verberum. + +#### 5. Profit! + +Lorem ipsum dolor it verberum. + +{% endcapture %} + +{% include templates/task.md %} \ No newline at end of file diff --git a/images/docs/pod-overview.svg b/images/docs/pod-overview.svg new file mode 100644 index 0000000000..3243c73d55 --- /dev/null +++ b/images/docs/pod-overview.svg @@ -0,0 +1,4 @@ + + + +