Skip to content

Commit 822d59b

Browse files
steveperry-53steveperry-53
committed
Write page templates and canonical examples.
Conflicts: _data/tasks.yml _data/tutorials.yml docs/tasks/access-kubernetes-api/http-proxy-access-api.md docs/tasks/index.md docs/tutorials/index.md
1 parent 51add3e commit 822d59b

23 files changed

+1246
-29
lines changed

‎_data/concepts.yml

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
bigheader: "Concepts"
2+
toc:
3+
- title: Concepts
4+
path: /docs/concepts/
5+
- title: Object Metadata
6+
section:
7+
- title: Annotations
8+
path: /docs/concepts/object-metadata/annotations/

‎_data/globals.yml

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
tocs:
22
- guides
3+
- tutorials
4+
- tasks
5+
- concepts
36
- reference
47
- samples
5-
- support
8+
- support

‎_data/support.yml

+5
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ toc:
44
- title: Support
55
path: /docs/troubleshooting/
66

7+
- title: Contributing to the Kubernetes Docs
8+
section:
9+
- title: Using Page Templates
10+
path: /docs/contribute/page-templates/
11+
712
- title: Troubleshooting
813
section:
914
- title: Debugging Pods and Replication Controllers

‎_data/tasks.yml

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
bigheader: "Tasks"
2+
toc:
3+
- title: Tasks
4+
path: /docs/tasks/
5+
- title: Accessing Applications in a Cluster
6+
section:
7+
- title: Using Port Forwarding to Access Applications in a Cluster
8+
path: /docs/tasks/access-application-cluster/port-forward-access-application-cluster/
9+
- title: Accessing the Kubernetes API
10+
section:
11+
- title: Using an HTTP Proxy to Access the Kubernetes API
12+
path: /docs/tasks/access-kubernetes-api/http-proxy-access-api/
13+

‎_data/tutorials.yml

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
bigheader: "Tutorials"
2+
toc:
3+
- title: Tutorials
4+
path: /docs/tutorials/
5+
- title: Stateless Applications
6+
section:
7+
- title: Running a Stateless Application Using a Deployment
8+
path: /docs/tutorials/stateless-application/run-stateless-application-deployment/
9+
- title: Exposing an External IP Address Using a Service
10+
path: /docs/tutorials/stateless-application/expose-external-ip-address-service/

‎_includes/templates/concept.md

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{% if overview %}
2+
3+
{{ overview }}
4+
5+
{% else %}
6+
7+
{% include templates/_errorthrower.md missing_block='overview' purpose='provides an overview of this concept.' %}
8+
9+
{% endif %}
10+
11+
* TOC
12+
{:toc}
13+
14+
{% if body %}
15+
16+
{{ body }}
17+
18+
{% else %}
19+
20+
{% include templates/_errorthrower.md missing_block='body' purpose='supplies the body of the page content.' %}
21+
22+
{% endif %}
23+
24+
25+
{% if whatsnext %}
26+
27+
### What's next
28+
29+
{{ whatsnext }}
30+
31+
{% endif %}
32+

‎_includes/templates/task.md

+33-14
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,55 @@
1-
{% if purpose %}
1+
{% if overview %}
22

3-
### Purpose
4-
5-
{{ purpose }}
3+
{{ overview }}
64

75
{% else %}
86

9-
{% 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.' %}
7+
{% include templates/_errorthrower.md missing_block='overview' purpose='states, in one or two sentences, the purpose of this document' %}
108

119
{% endif %}
1210

13-
{% if recommended_background %}
1411

15-
### Recommended background
12+
* TOC
13+
{: toc}
14+
15+
16+
{% if prerequisites %}
1617

17-
{{ recommended_background }}
18+
### Before you begin
19+
20+
{{ prerequisites }}
1821

1922
{% else %}
2023

21-
{% 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.' %}
24+
{% include templates/_errorthrower.md missing_block='prerequisites' heading='Before you begin' purpose='lists action prerequisites and knowledge prerequisites' %}
2225

2326
{% endif %}
2427

2528

26-
{% if step_by_step %}
29+
{% if steps %}
30+
31+
{{ steps }}
2732

28-
### Step by step
33+
{% else %}
34+
35+
{% include templates/_errorthrower.md missing_block='steps' purpose='lists a sequence of numbered steps that accomplish the task.' %}
36+
37+
{% endif %}
2938

30-
{{ step_by_step }}
39+
40+
{% if discussion %}
41+
42+
{{ discussion }}
3143

3244
{% else %}
3345

34-
{% 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.' %}
46+
{% endif %}
47+
3548

36-
{% endif %}
49+
{% if whatsnext %}
50+
51+
### What's next
52+
53+
{{ whatsnext }}
54+
55+
{% endif %}

‎_includes/templates/tutorial.md

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
{% if overview %}
2+
3+
{{ overview }}
4+
5+
{% else %}
6+
7+
{% include templates/_errorthrower.md missing_block='overview' purpose='states, in one or two sentences, the purpose of this document' %}
8+
9+
{% endif %}
10+
11+
12+
* TOC
13+
{: toc}
14+
15+
16+
{% if objectives %}
17+
18+
### Objectives
19+
20+
{{ objectives }}
21+
22+
{% else %}
23+
24+
{% include templates/_errorthrower.md missing_block='objectives' heading='Objectives' purpose='lists the objectives for this tutorial.' %}
25+
26+
{% endif %}
27+
28+
29+
{% if prerequisites %}
30+
31+
### Before you begin
32+
33+
{{ prerequisites }}
34+
35+
{% else %}
36+
37+
{% include templates/_errorthrower.md missing_block='prerequisites' heading='Before you begin' purpose='lists action prerequisites and knowledge prerequisites' %}
38+
39+
{% endif %}
40+
41+
42+
{% if lessoncontent %}
43+
44+
{{ lessoncontent }}
45+
46+
{% else %}
47+
48+
{% include templates/_errorthrower.md missing_block='lessoncontent' purpose='provides the lesson content for this tutorial.' %}
49+
50+
{% endif %}
51+
52+
53+
{% if cleanup %}
54+
55+
### Cleaning up
56+
57+
{{ cleanup }}
58+
59+
{% endif %}
60+
61+
62+
{% if whatsnext %}
63+
64+
### What's next
65+
66+
{{ whatsnext }}
67+
68+
{% endif %}

‎_layouts/docwithnav.html

+17-14
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,22 @@
77

88
<!-- HERO -->
99
<section id="hero" class="light-text">
10-
<h1>{{ site.data[foundTOC].bigheader }}</h1>
11-
<h5>{{ site.data[foundTOC].abstract }}</h5>
12-
<div id="vendorStrip" class="light-text">
13-
<ul>
14-
<li><a href="/docs/" {% if site.data[foundTOC].bigheader == "Guides" %}class="YAH"{% endif %}>GUIDES</a></li>
15-
<li><a href="/docs/reference" {% if site.data[foundTOC].bigheader == "Reference Documentation" %}class="YAH"{% endif %}>REFERENCE</a></li>
16-
<li><a href="/docs/samples" {% if site.data[foundTOC].bigheader == "Samples" %}class="YAH"{% endif %}>SAMPLES</a></li>
17-
<li><a href="/docs/troubleshooting/" {% if site.data[foundTOC].bigheader == "Support" %}class="YAH"{% endif %}>SUPPORT</a></li>
18-
</ul>
19-
<div id="searchBox">
20-
<input type="text" id="search" placeholder="Search" onkeydown="if (event.keyCode==13) window.location.replace('/docs/search/?q=' + this.value)">
21-
</div>
22-
</div>
10+
<h1>{{ site.data[foundTOC].bigheader }}</h1>
11+
<h5>{{ site.data[foundTOC].abstract }}</h5>
12+
<div id="vendorStrip" class="light-text">
13+
<ul>
14+
<li><a href="/docs/" {% if site.data[foundTOC].bigheader == "Guides" %}class="YAH"{% endif %}>GUIDES</a></li>
15+
<li><a href="/docs/tutorials/" {% if site.data[foundTOC].bigheader == "Tutorials" %}class="YAH"{% endif %}>TUTORIALS</a></li>
16+
<li><a href="/docs/tasks/" {% if site.data[foundTOC].bigheader == "Tasks" %}class="YAH"{% endif %}>TASKS</a></li>
17+
<li><a href="/docs/concepts/" {% if site.data[foundTOC].bigheader == "Concepts" %}class="YAH"{% endif %}>CONCEPTS</a></li>
18+
<li><a href="/docs/reference" {% if site.data[foundTOC].bigheader == "Reference Documentation" %}class="YAH"{% endif %}>REFERENCE</a></li>
19+
<li><a href="/docs/samples" {% if site.data[foundTOC].bigheader == "Samples" %}class="YAH"{% endif %}>SAMPLES</a></li>
20+
<li><a href="/docs/troubleshooting/" {% if site.data[foundTOC].bigheader == "Support" %}class="YAH"{% endif %}>SUPPORT</a></li>
21+
</ul>
22+
<div id="searchBox">
23+
<input type="text" id="search" placeholder="Search" onkeydown="if (event.keyCode==13) window.location.replace('/docs/search/?q=' + this.value)">
24+
</div>
25+
</div>
2326
</section>
2427

2528
<section id="encyclopedia">
@@ -34,7 +37,7 @@ <h5>{{ site.data[foundTOC].abstract }}</h5>
3437
{% if notitle != "true" %}<h1>{{ title }}</h1>{% endif %}
3538
{{ content }}
3639
<p><a href=""><img src="https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/{{ page.path }}?pixel" alt="Analytics" /></a>
37-
{% if page.url != "/404.html" && page.url != "/docs/search/" %}<div id="pd_rating_holder_8345992"></div>
40+
{% if page.url != "/404.html" and page.url != "/docs/search/" %}<div id="pd_rating_holder_8345992"></div>
3841
<script type="text/javascript">
3942
PDRTJS_settings_8345992 = {
4043
"id" : "8345992",

‎docs/concepts/index.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
---
3+
4+
The Concepts section of the Kubernetes documentation is a work in progress.
5+
6+
#### Object Metadata
7+
8+
[Annotations](/docs/concepts/object-metadata/annotations/)
9+
10+
### What's next
11+
12+
If you would like to write a concept page, see
13+
[Using Page Templates](/docs/contribute/page-templates/)
14+
for information about the concept page type and the concept template.

‎docs/concepts/object-metadata/annotations.md

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
---
3+
4+
{% capture overview %}
5+
You can use Kubernetes annotations to attach arbitrary non-identifying metadata
6+
to objects. Clients such as tools and libraries can retrieve this metadata.
7+
{% endcapture %}
8+
9+
{% capture body %}
10+
### Attaching metadata to objects
11+
12+
You can use either labels or annotations to attach metadata to Kubernetes
13+
objects. Labels can be used to select objects and to find
14+
collections of objects that satisfy certain conditions. In contrast, annotations
15+
are not used to identify and select objects. The metadata
16+
in an annotation can be small or large, structured or unstructured, and can
17+
include characters not permitted by labels.
18+
19+
Annotations, like labels, are key/value maps:
20+
21+
"annotations": {
22+
"key1" : "value1",
23+
"key2" : "value2"
24+
}
25+
26+
Here are some examples of information that could be recorded in annotations:
27+
28+
* Fields managed by a declarative configuration layer. Attaching these fields
29+
as annotations distinguishes them from default values set by clients or
30+
servers, and from auto-generated fields and fields set by
31+
auto-sizing or auto-scaling systems.
32+
33+
* Build, release, or image information like timestamps, release IDs, git branch,
34+
PR numbers, image hashes, and registry address.
35+
36+
* Pointers to logging, monitoring, analytics, or audit repositories.
37+
38+
* Client library or tool information that can be used for debugging purposes:
39+
for example, name, version, and build information.
40+
41+
* User or tool/system provenance information, such as URLs of related objects
42+
from other ecosystem components.
43+
44+
* Lightweight rollout tool metadata: for example, config or checkpoints.
45+
46+
* Phone or pager numbers of persons responsible, or directory entries that
47+
specify where that information can be found, such as a team web site.
48+
49+
Instead of using annotations, you could store this type of in information in an
50+
external database or directory, but that would make it much harder to produce
51+
shared client libraries and tools for deployment, management, introspection,
52+
and the like.
53+
54+
{% endcapture %}
55+
56+
{% capture whatsnext %}
57+
Learn more about [Labels and Selectors](/docs/user-guide/labels/).
58+
{% endcapture %}
59+
60+
{% include templates/concept.md %}

0 commit comments

Comments
 (0)