Reference ToC refactor (#3427)
* Reference ToC refactor * Move Federation into Reference * Fix ToC, add deprecation notice * Fix Reference ToC * tweak ToC * Move content into Reference * touch up kubectl * fix ToC syntax error * remove resources-reference docs * change kubectl section name * adjust page titles * create Command-Line Tools section * Move Federation API out to top level * remove extensions/v1beta1 definitions * rewrite Kubernetes API in Concepts in a later PR * Add jbeda to Kubernetes API Overview page for reviews. * incorporate feedback * remove /docs/federation * move around copy * cleanup reference landing page * update reference landing page
This commit is contained in:
Andrew Chen
@@ -0,0 +1,92 @@
|
||||
---
|
||||
title: Kubernetes API Overview
|
||||
assignees:
|
||||
- bgrant0607
|
||||
- erictune
|
||||
- lavalamp
|
||||
- jbeda
|
||||
---
|
||||
|
||||
The REST API is the fundamental fabric of Kubernetes. All operations and
|
||||
communications between components are REST API calls handled by the API Server,
|
||||
including external user commands. Consequently, everything in the Kubernetes
|
||||
platform is treated as an API object and has a corresponding entry in the
|
||||
[API](/docs/api-reference/{{page.version}}/).
|
||||
|
||||
Most operations can be performed through the
|
||||
[kubectl](/docs/user-guide/kubectl-overview/) command-line interface or other
|
||||
command-line tools, such as [kubeadm](/docs/admin/kubeadm/), which in turn use
|
||||
the API. However, the API can also be accessed directly using REST calls.
|
||||
|
||||
## API versioning
|
||||
|
||||
To make it easier to eliminate fields or restructure resource representations, Kubernetes supports
|
||||
multiple API versions, each at a different API path, such as `/api/v1` or
|
||||
`/apis/extensions/v1beta1`.
|
||||
|
||||
We chose to version at the API level rather than at the resource or field level to ensure that the API presents a clear, consistent view of system resources and behavior, and to enable controlling access to end-of-lifed and/or experimental APIs. The JSON and Protobuf serialization schemas follow the same guidelines for schema changes - all descriptions below cover both formats.
|
||||
|
||||
Note that API versioning and Software versioning are only indirectly related. The [API and release
|
||||
versioning proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/versioning.md) describes the relationship between API versioning and
|
||||
software versioning.
|
||||
|
||||
Different API versions imply different levels of stability and support. The criteria for each level are described
|
||||
in more detail in the [API Changes documentation](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api_changes.md#alpha-beta-and-stable-versions). They are summarized here:
|
||||
|
||||
- Alpha level:
|
||||
- The version names contain `alpha` (e.g. `v1alpha1`).
|
||||
- May be buggy. Enabling the feature may expose bugs. Disabled by default.
|
||||
- Support for feature may be dropped at any time without notice.
|
||||
- The API may change in incompatible ways in a later software release without notice.
|
||||
- Recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.
|
||||
- Beta level:
|
||||
- The version names contain `beta` (e.g. `v2beta3`).
|
||||
- Code is well tested. Enabling the feature is considered safe. Enabled by default.
|
||||
- Support for the overall feature will not be dropped, though details may change.
|
||||
- The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens,
|
||||
we will provide instructions for migrating to the next version. This may require deleting, editing, and re-creating
|
||||
API objects. The editing process may require some thought. This may require downtime for applications that rely on the feature.
|
||||
- Recommended for only non-business-critical uses because of potential for incompatible changes in subsequent releases. If you have
|
||||
multiple clusters which can be upgraded independently, you may be able to relax this restriction.
|
||||
- **Please do try our beta features and give feedback on them! Once they exit beta, it may not be practical for us to make more changes.**
|
||||
- Stable level:
|
||||
- The version name is `vX` where `X` is an integer.
|
||||
- Stable versions of features will appear in released software for many subsequent versions.
|
||||
|
||||
## API groups
|
||||
|
||||
To make it easier to extend the Kubernetes API, we implemented [*API groups*](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-group.md).
|
||||
The API group is specified in a REST path and in the `apiVersion` field of a serialized object.
|
||||
|
||||
Currently there are several API groups in use:
|
||||
|
||||
1. the "core" (oftentimes called "legacy", due to not having explicit group name) group, which is at
|
||||
REST path `/api/v1` and is not specified as part of the `apiVersion` field, e.g. `apiVersion: v1`.
|
||||
1. the named groups are at REST path `/apis/$GROUP_NAME/$VERSION`, and use `apiVersion: $GROUP_NAME/$VERSION`
|
||||
(e.g. `apiVersion: batch/v1`). Full list of supported API groups can be seen in [Kubernetes API reference](/docs/reference/).
|
||||
|
||||
|
||||
There are two supported paths to extending the API.
|
||||
1. [Third Party Resources](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/extending-api.md)
|
||||
are for users with very basic CRUD needs.
|
||||
1. Coming soon: users needing the full set of Kubernetes API semantics can implement their own apiserver
|
||||
and use the [aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/aggregated-api-servers.md)
|
||||
to make it seamless for clients.
|
||||
|
||||
|
||||
## Enabling API groups
|
||||
|
||||
Certain resources and API groups are enabled by default. They can be enabled or disabled by setting `--runtime-config`
|
||||
on apiserver. `--runtime-config` accepts comma separated values. For ex: to disable batch/v1, set
|
||||
`--runtime-config=batch/v1=false`, to enable batch/v2alpha1, set `--runtime-config=batch/v2alpha1`.
|
||||
The flag accepts comma separated set of key=value pairs describing runtime configuration of the apiserver.
|
||||
|
||||
IMPORTANT: Enabling or disabling groups or resources requires restarting apiserver and controller-manager
|
||||
to pick up the `--runtime-config` changes.
|
||||
|
||||
## Enabling resources in the groups
|
||||
|
||||
DaemonSets, Deployments, HorizontalPodAutoscalers, Ingress, Jobs and ReplicaSets are enabled by default.
|
||||
Other extensions resources can be enabled by setting `--runtime-config` on
|
||||
apiserver. `--runtime-config` accepts comma separated values. For ex: to disable deployments and jobs, set
|
||||
`--runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/jobs=false`
|
||||
@@ -0,0 +1,262 @@
|
||||
---
|
||||
assignees:
|
||||
- bgrant0607
|
||||
- lavalamp
|
||||
- thockin
|
||||
title: Kubernetes Deprecation Policy
|
||||
---
|
||||
|
||||
Kubernetes is a large system with many components and many contributors. As
|
||||
with any such software, the feature set naturally evolves over time, and
|
||||
sometimes a feature may need to be removed. This could include an API, a flag,
|
||||
or even an entire feature. To avoid breaking existing users, Kubernetes follows
|
||||
a deprecation policy for aspects of the system that are slated to be removed.
|
||||
|
||||
This document details the deprecation policy for various facets of the system.
|
||||
|
||||
## Deprecating parts of the API
|
||||
|
||||
Since Kubernetes is an API-driven system, the API has evolved over time to
|
||||
reflect the evolving understanding of the problem space. The Kubernetes API is
|
||||
actually a set of APIs, called "API groups", and each API group is
|
||||
independently versioned. [API versions](http://kubernetes.io/docs/api/) fall
|
||||
into 3 main tracks, each of which has different policies for deprecation:
|
||||
|
||||
| Example | Track |
|
||||
|----------|----------------------------------|
|
||||
| v1 | GA (generally available, stable) |
|
||||
| v1beta1 | Beta (pre-release) |
|
||||
| v1alpha1 | Alpha (experimental) |
|
||||
|
||||
A given release of Kubernetes can support any number of API groups and any
|
||||
number of versions of each.
|
||||
|
||||
The following rules govern the deprecation of elements of the API. This
|
||||
includes:
|
||||
|
||||
* REST resources (aka API objects)
|
||||
* Fields of REST resources
|
||||
* Enumerated or constant values
|
||||
* Component config structures
|
||||
|
||||
These rules are enforced between official releases, not between
|
||||
arbitrary commits to master or release branches.
|
||||
|
||||
**Rule #1: API elements may only be removed by incrementing the version of the
|
||||
API group.**
|
||||
|
||||
Once an API element has been added to an API group at a particular version, it
|
||||
can not be removed from that version or have its behavior significantly
|
||||
changed, regardless of track.
|
||||
|
||||
Note: For historical reasons, there are 2 "monolithic" API groups - "core" (no
|
||||
group name) and "extensions". Resources will incrementally be moved from these
|
||||
legacy API groups into more domain-specific API groups.
|
||||
|
||||
**Rule #2: API objects must be able to round-trip between API versions in a given
|
||||
release without information loss, with the exception of whole REST resources
|
||||
that do not exist in some versions.**
|
||||
|
||||
For example, an object can be written as v1 and then read back as v2 and
|
||||
converted to v1, and the resulting v1 resource will be identical to the
|
||||
original. The representation in v2 might be different from v1, but the system
|
||||
knows how to convert between them in both directions. Additionally, any new
|
||||
field added in v2 must be able to round-trip to v1 and back, which means v1
|
||||
might have to add an equivalent field or represent it as an annotation.
|
||||
|
||||
**Rule #3: An API version in a given track may not be deprecated until a new
|
||||
API version at least as stable is released.**
|
||||
|
||||
GA API versions can replace GA API versions as well as beta and alpha API
|
||||
version. Beta API versions *may not* replace GA API versions.
|
||||
|
||||
**Rule #4: Other than the most recent API version in each track, older API
|
||||
versions must be supported after their announced deprecation for a duration of
|
||||
no less than:**
|
||||
|
||||
* **GA: 1 year or 2 releases (whichever is longer)**
|
||||
* **Beta: 3 months or 1 release (whichever is longer)**
|
||||
* **Alpha: 0 releases**
|
||||
|
||||
This is best illustrated by example. Imagine a Kubernetes release, version X,
|
||||
which supports a particular API group. A new Kubernetes release is made every
|
||||
approximately 3 months (4 per year). The following table describes which API
|
||||
versions are supported in a series of subsequent releases.
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Release</th>
|
||||
<th>API Versions</th>
|
||||
<th>Notes</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>X</td>
|
||||
<td>v1</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+1</td>
|
||||
<td>v1, v2alpha1</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+2</td>
|
||||
<td>v1, v2alpha2</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v2alpha1 is removed, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+3</td>
|
||||
<td>v1, v2beta1</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v2alpha2 is removed, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+4</td>
|
||||
<td>v1, v2beta1, v2beta2</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v2beta1 is deprecated, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+5</td>
|
||||
<td>v1, v2, v2beta2</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v2beta1 is removed, "action required" relnote</li>
|
||||
<li>v2beta2 is deprecated, "action required" relnote</li>
|
||||
<li>v1 is deprecated, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+6</td>
|
||||
<td>v1, v2</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v2beta2 is removed, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+7</td>
|
||||
<td>v1, v2</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+8</td>
|
||||
<td>v1, v2</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+9</td>
|
||||
<td>v2</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v1 is removed, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
### REST resources (aka API objects)
|
||||
|
||||
Consider a hypothetical REST resource named Widget, which was present in API v1
|
||||
in the above timeline, and which needs to be deprecated. We
|
||||
[document](http://kubernetes.io/docs/deprecated/) and
|
||||
[announce](https://groups.google.com/forum/#!forum/kubernetes-announce) the
|
||||
deprecation in sync with release X+1. The Widget resource still exists in API
|
||||
version v1 (deprecated) but not in v2alpha1. The Widget resource continues to
|
||||
exist and function in releases up to and including X+8. Only in release X+9,
|
||||
when API v1 has aged out, does the Widget resource cease to exist, and the
|
||||
behavior get removed.
|
||||
|
||||
### Fields of REST resources
|
||||
|
||||
As with whole REST resources, an individual field which was present in API v1
|
||||
must exist and function until API v1 is removed. Unlike whole resources, the
|
||||
v2 APIs may choose a different representation for the field, as long as it can
|
||||
be round-tripped. For example a v1 field named "magnitude" which was
|
||||
deprecated might be named "deprecatedMagnitude" in API v2. When v1 is
|
||||
eventually removed, the deprecated field can be removed from v2.
|
||||
|
||||
### Enumerated or constant values
|
||||
|
||||
As with whole REST resources and fields thereof, a constant value which was
|
||||
supported in API v1 must exist and function until API v1 is removed.
|
||||
|
||||
### Component config structures
|
||||
|
||||
Component configs are versioned and managed just like REST resources.
|
||||
|
||||
### Future work
|
||||
|
||||
Over time, Kubernetes will introduce more fine-grained API versions, at which
|
||||
point these rules will be adjusted as needed.
|
||||
|
||||
## Deprecating a flag or CLI
|
||||
|
||||
The Kubernetes system is comprised of several different programs cooperating.
|
||||
Sometimes, a Kubernetes release might remove flags or CLI commands
|
||||
(collectively "CLI elements") in these programs. The individual programs
|
||||
naturally sort into two main groups - user-facing and admin-facing programs,
|
||||
which vary slightly in their deprecation policies. Unless a flag is explicitly
|
||||
prefixed or documented as "alpha" or "beta", it is considered GA.
|
||||
|
||||
CLI elements are effectively part of the API to the system, but since they are
|
||||
not versioned in the same way as the REST API, the rules for deprecation are as
|
||||
follows:
|
||||
|
||||
**Rule #5a: CLI elements of user-facing components (e.g. kubectl) must function
|
||||
after their announced deprecation for no less than:**
|
||||
|
||||
* **GA: 1 year or 2 releases (whichever is longer)**
|
||||
* **Beta: 3 months or 1 release (whichever is longer)**
|
||||
* **Alpha: 0 releases**
|
||||
|
||||
**Rule #5b: CLI elements of admin-facing components (e.g. kubelet) must function
|
||||
after their announced deprecation for no less than:**
|
||||
|
||||
* **GA: 6 months or 1 release (whichever is longer)**
|
||||
* **Beta: 3 months or 1 release (whichever is longer)**
|
||||
* **Alpha: 0 releases**
|
||||
|
||||
**Rule #6: Deprecated CLI elements must emit warnings (optionally disable)
|
||||
when used.**
|
||||
|
||||
## Deprecating a feature or behavior
|
||||
|
||||
Occasionally a Kubernetes release needs to deprecate some feature or behavior
|
||||
of the system that is not controlled by the API or CLI. In this case, the
|
||||
rules for deprecation are as follows:
|
||||
|
||||
**Rule #7: Deprecated behaviors must function for no less than 1 year after their
|
||||
announced deprecation.**
|
||||
|
||||
This does not imply that all changes to the system are governed by this policy.
|
||||
This applies only to significant, user-visible behaviors which impact the
|
||||
correctness of applications running on Kubernetes or that impact the
|
||||
administration of Kubernetes clusters, and which are being removed entirely.
|
||||
|
||||
## Exceptions
|
||||
|
||||
No policy can cover every possible situation. This policy is a living
|
||||
document, and will evolve over time. In practice, there will be situations
|
||||
that do not fit neatly into this policy, or for which this policy becomes a
|
||||
serious impediment. Such situations should be discussed with SIGs and project
|
||||
leaders to find the best solutions for those specific cases, always bearing in
|
||||
mind that Kubernetes is committed to being a stable system that, as much as
|
||||
possible, never breaks users. Exceptions will always be announced in all
|
||||
relevant release notes.
|
||||
+6536
File diff suppressed because it is too large
Load Diff
+8877
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Federation API Reference
|
||||
redirect_from:
|
||||
- "/docs/federation/api-reference/"
|
||||
- "/docs/federation/api-reference/index.md"
|
||||
---
|
||||
|
||||
Federation API server supports the following group versions:
|
||||
|
||||
* federation/v1beta1: [operations](/docs/reference/federation/v1beta1/operations.html), [model definitions](/docs/reference/federation/v1beta1/definitions.html)
|
||||
* v1: [operations](/docs/reference/federation/v1/operations.html), [model definitions](/docs/reference/federation/v1/definitions.html)
|
||||
* extensions/v1beta1: [operations](/docs/reference/federation/extensions/v1beta1/operations.html), [model definitions](/docs/reference/federation/extensions/v1beta1/definitions.html)
|
||||
|
||||
|
||||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||
[]()
|
||||
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
||||
+1883
File diff suppressed because it is too large
Load Diff
Executable
+8552
File diff suppressed because it is too large
Load Diff
+1125
File diff suppressed because it is too large
Load Diff
+1446
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Reference Documentation
|
||||
assignees:
|
||||
- chenopis
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
* [Kubernetes API Overview](/docs/reference/api-overview/) - Overview of the API for Kubernetes.
|
||||
* Kubernetes API Versions
|
||||
* [1.6](/docs/api-reference/v1.6/)
|
||||
* [1.5](/docs/api-reference/v1.5/)
|
||||
* Federation API
|
||||
* [v1 Operations](docs/reference/federation/v1/operations.html)
|
||||
* [v1 Model Definitions](docs/reference/federation/v1/definitions.html)
|
||||
* [federation/v1beta1 Operations](docs/reference/federation/v1beta1/operations.html)
|
||||
* [federation/v1beta1 Model Definitions](docs/reference/federation/v1beta1/definitions.html)
|
||||
* [extensions/v1beta1 Operations](docs/reference/federation/extensions/v1beta1/operations.html)
|
||||
* [extensions/v1beta1 Model Definitions](docs/reference/federation/extensions/v1beta1/definitions.html)
|
||||
|
||||
## CLI Reference
|
||||
|
||||
* [kubectl](/docs/user-guide/kubectl-overview) - Main CLI tool for running commands and managing Kubernetes clusters.
|
||||
* [JSONPath](/docs/user-guide/jsonpath/) - Syntax guide for using [JSONPath expressions](http://goessner.net/articles/JsonPath/) with kubectl.
|
||||
* [kubeadm](/docs/admin/kubeadm/) - CLI tool to
|
||||
|
||||
## Config Reference
|
||||
|
||||
* [kubelet](/docs/admin/kubelet/) - The primary *node agent* that runs on each node. The kubelet takes a set of PodSpecs and ensures that the described containers are running and healthy.
|
||||
* [kube-apiserver](/docs/admin/kube-apiserver/) - REST API that validates and configures data for API objects such as pods, services, replication controllers.
|
||||
* [kube-controller-manager](docs/admin/kube-controller-manager/) - Daemon that embeds the core control loops shipped with Kubernetes.
|
||||
* [kube-proxy](/docs/admin/kube-proxy/) - Can do simple TCP/UDP stream forwarding or round-robin TCP/UDP forwarding across a set of back-ends.
|
||||
* [kube-scheduler](/docs/admin/kube-scheduler/) - Scheduler that manages availability, performance, and capacity.
|
||||
* [federation-apiserver](/docs/admin/federation-apiserver/) - API server for federated clusters.
|
||||
* [federation-controller-manager](/docs/admin/federation-controller-manager/) - Daemon that embeds the core control loops shipped with Kubernetes federation.
|
||||
|
||||
## Design Docs
|
||||
|
||||
An archive of the design docs for Kubernetes functionality. Good starting points are [Kubernetes Architecture](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture.md) and [Kubernetes Design Overview](https://github.com/kubernetes/kubernetes/tree/{{page.fullversion}}/docs/design).
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
title: Well-Known Labels, Annotations and Taints
|
||||
---
|
||||
|
||||
Kubernetes reserves all labels and annotations in the kubernetes.io namespace. This document describes
|
||||
the well-known kubernetes.io labels and annotations.
|
||||
|
||||
This document serves both as a reference to the values, and as a coordination point for assigning values.
|
||||
|
||||
**Table of contents:**
|
||||
<!-- BEGIN MUNGE: GENERATED_TOC -->
|
||||
|
||||
- [Well-Known Labels, Annotations and Taints](#well-known-labels-annotations-and-taints)
|
||||
- [beta.kubernetes.io/arch](#betakubernetesioarch)
|
||||
- [beta.kubernetes.io/os](#betakubernetesioos)
|
||||
- [kubernetes.io/hostname](#kubernetesiohostname)
|
||||
- [beta.kubernetes.io/instance-type](#betakubernetesioinstance-type)
|
||||
- [failure-domain.beta.kubernetes.io/region](#failure-domainbetakubernetesioregion)
|
||||
- [failure-domain.beta.kubernetes.io/zone](#failure-domainbetakubernetesiozone)
|
||||
|
||||
<!-- END MUNGE: GENERATED_TOC -->
|
||||
|
||||
|
||||
## beta.kubernetes.io/arch
|
||||
|
||||
Example: `beta.kubernetes.io/arch=amd64`
|
||||
|
||||
Used on: Node
|
||||
|
||||
Kubelet populates this with `runtime.GOARCH` as defined by Go. This can be handy if you are mixing arm and x86 nodes,
|
||||
for example.
|
||||
|
||||
## beta.kubernetes.io/os
|
||||
|
||||
Example: `beta.kubernetes.io/os=linux`
|
||||
|
||||
Used on: Node
|
||||
|
||||
Kubelet populates this with `runtime.GOOS` as defined by Go. This can be handy if you are mixing operating systems
|
||||
in your cluster (although currently Linux is the only OS supported by Kubernetes).
|
||||
|
||||
## kubernetes.io/hostname
|
||||
|
||||
Example: `kubernetes.io/hostname=ip-172-20-114-199.ec2.internal`
|
||||
|
||||
Used on: Node
|
||||
|
||||
Kubelet populates this with the hostname. Note that the hostname can be changed from the "actual" hostname
|
||||
by passing the `--hostname-override` flag to kubelet.
|
||||
|
||||
## beta.kubernetes.io/instance-type
|
||||
|
||||
Example: `beta.kubernetes.io/instance-type=m3.medium`
|
||||
|
||||
Used on: Node
|
||||
|
||||
Kubelet populates this with the instance type as defined by the `cloudprovider`. It will not be set if
|
||||
not using a cloudprovider. This can be handy if you want to target certain workloads to certain instance
|
||||
types, but typically you want to rely on the Kubernetes scheduler to perform resource-based scheduling,
|
||||
and you should aim to schedule based on properties rather than on instance types (e.g. require a GPU, instead
|
||||
of requiring a `g2.2xlarge`)
|
||||
|
||||
|
||||
## failure-domain.beta.kubernetes.io/region
|
||||
|
||||
See [failure-domain.beta.kubernetes.io/zone](#failure-domainbetakubernetesiozone)
|
||||
|
||||
## failure-domain.beta.kubernetes.io/zone
|
||||
|
||||
Example:
|
||||
|
||||
`failure-domain.beta.kubernetes.io/region=us-east-1`
|
||||
|
||||
`failure-domain.beta.kubernetes.io/zone=us-east-1c`
|
||||
|
||||
Used on: Node, PersistentVolume
|
||||
|
||||
On the Node: Kubelet populates this with the zone information as defined by the `cloudprovider`. It will not be set if
|
||||
not using a `cloudprovider`, but you should consider setting it on the nodes if it makes sense in your topology.
|
||||
|
||||
On the PersistentVolume: The `PersistentVolumeLabel` admission controller will automatically add zone labels to PersistentVolumes,
|
||||
on GCE and AWS.
|
||||
|
||||
Kubernetes will automatically spread the pods in a replication controller or service across nodes in a single-zone
|
||||
cluster (to reduce the impact of failures.) With multiple-zone clusters, this spreading behaviour is extended
|
||||
across zones (to reduce the impact of zone failures.) This is achieved via SelectorSpreadPriority.
|
||||
|
||||
This is a best-effort placement, and so if the zones in your cluster are heterogeneous (e.g. different numbers of nodes,
|
||||
different types of nodes, or different pod resource requirements), this might prevent equal spreading of
|
||||
your pods across zones. If desired, you can use homogenous zones (same number and types of nodes) to reduce
|
||||
the probability of unequal spreading.
|
||||
|
||||
The scheduler (via the VolumeZonePredicate predicate) will also ensure that pods that claim a given volume
|
||||
are only placed into the same zone as that volume, as volumes cannot be attached across zones.
|
||||
|
||||
|
||||
The actual values of zone and region don't matter, and nor is the meaning of the hierarchy rigidly defined. The expectation
|
||||
is that failures of nodes in different zones should be uncorrelated unless the entire region has failed. For example,
|
||||
zones should typically avoid sharing a single network switch. The exact mapping depends on your particular
|
||||
infrastructure - a three-rack installation will choose a very different setup to a multi-datacenter configuration.
|
||||
|
||||
If `PersistentVolumeLabel` does not support automatic labeling of your PersistentVolumes, you should consider
|
||||
adding the labels manually (or adding support to `PersistentVolumeLabel`), if you want the scheduler to prevent
|
||||
pods from mounting volumes in a different zone. If your infrastructure doesn't have this constraint, you don't
|
||||
need to add the zone labels to the volumes at all.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||
[]()
|
||||
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
layout: docwithnav
|
||||
title: Kubernetes Security and Disclosure Information
|
||||
permalink: /security/
|
||||
assignees:
|
||||
- eparis
|
||||
- erictune
|
||||
- philips
|
||||
- jessfraz
|
||||
---
|
||||
|
||||
## Security Announcements
|
||||
|
||||
Join the [kubernetes-announce](https://groups.google.com/forum/#!forum/kubernetes-announce) group for emails about security and major API announcements.
|
||||
|
||||
## Report a Vulnerability
|
||||
|
||||
We’re extremely grateful for security researchers and users that report vulnerabilities to the Kubernetes Open Source Community. All reports are thoroughly investigated by a set of community volunteers.
|
||||
|
||||
To make a report, please email the private [kubernetes-security@googlegroups.com](mailto:kubernetes-security@googlegroups.com) list with the security details and the details expected for [all Kubernetes bug reports](https://github.com/kubernetes/kubernetes/blob/master/.github/ISSUE_TEMPLATE.md).
|
||||
|
||||
You may encrypt your email to this list using the GPG keys of the [Product Security Team members](https://github.com/kubernetes/community/blob/master/contributors/devel/security-release-process.md#product-security-team-pst). Encryption using GPG is NOT required to make a disclosure.
|
||||
|
||||
### When Should I Report a Vulnerability?
|
||||
|
||||
- You think you discovered a potential security vulnerability in Kubernetes
|
||||
- You are unsure how a vulnerability affects Kubernetes
|
||||
- You think you discovered a vulnerability in another project that Kubernetes depends on (e.g. docker, rkt, etcd)
|
||||
|
||||
### When Should I NOT Report a Vulnerability?
|
||||
|
||||
- You need help tuning Kubernetes components for security
|
||||
- You need help applying security related updates
|
||||
- Your issue is not security related
|
||||
|
||||
## Security Vulnerability Response
|
||||
|
||||
Each report is acknowledged and analyzed by Product Security Team members within 3 working days. This will set off the [Security Release Process](https://github.com/kubernetes/community/blob/master/contributors/devel/security-release-process.md#product-security-team-pst).
|
||||
|
||||
Any vulnerability information shared with Product Security Team stays within Kubernetes project and will not be disseminated to other projects unless it is necessary to get the issue fixed.
|
||||
|
||||
As the security issue moves from triage, to identified fix, to release planning we will keep the reporter updated.
|
||||
|
||||
## Public Disclosure Timing
|
||||
|
||||
A public disclosure date is negotiated by the Kubernetes product security team and the bug submitter. We prefer to fully disclose the bug as soon as possible once a user mitigation is available. It is reasonable to delay disclosure when the bug or the fix is not yet fully understood, the solution is not well-tested, or for vendor coordination. The timeframe for disclosure is from immediate (especially if it's already publicly known) to a few weeks. As a basic default, we expect report date to disclosure date to be on the order of 7 days. The Kubernetes product security team holds the final say when setting a disclosure date.
|
||||
Reference in New Issue
Block a user