このコンテンツは選択した言語では利用できません。
Chapter 6. Kubernetes Configuration
6.1. Overview
Procedures and software described in this chapter for manually configuring and using Kubernetes are deprecated and, therefore, no longer supported. For information on which software and documentation are impacted, see the Red Hat Enterprise Linux Atomic Host Release Notes. For information on Red Hat’s officially supported Kubernetes-based products, refer to Red Hat OpenShift Container Platform, OpenShift Online, OpenShift Dedicated, OpenShift.io, Container Development Kit or Development Suite.
Kubernetes reads YAML files to configure services, pods and replication controllers. This document describes the similarities and differences between these areas and details the names and expected data types of the various files.
6.2. Design Strategy
Kubernetes uses environment variables whose names are partially specified by the service configuration, so normally you would design the services first, followed by the pods, followed by the replication controllers. This ordering is “outside-in”, moving from the user-facing portion to the internal management portion.
Of course, you are free to design the system in any order you wish. However, you might find that you require more iterations to arrive at a good set of configuration files if you don’t start with services.
6.3. Conventions
In this document, we say field name and field value instead of key and value, respectively. For brevity and consistency with upstream Kubernetes documentation, we say map instead of mapping. As the field value can often be a complex structure, we call the combination of field name and value together a <field> tree or <field> structure, regardless of the complexity of the field value. For example, here is a map, with two top-level structures, one
and two
:
one: a: [ x, y, z ] b: [ q, r, s ] two: 42
The one
tree is a map with two elements, the a
tree and the b
tree, while the two
tree is very simple: field name is two
and field value is 42. The field values for both a
and b
are lists.
6.3.1. Extended Types
We conceptually extend the YAML type system to include some sub-types of string
and some more precise sub-types of number
:
symbol
This is a string that has no internal whitespace, comma, colon, curly-braces or square-braces. As such, it does not require double-quotes. For example, all the field names and the first two values in the following map are symbols.
a: one-is-a-lonely-number b: "two-s-company" c: 3's a crowd
Note that the field value for
b
is a symbol even though it is written with double-quotes. The double-quotes are unnecessary, but not invalid. The other way to think about it is: If you need to use double-quotes, you are not writing a symbol.enum
- This is a symbol taken from a pre-specified, finite, set.
v4addr
-
This is an IPv4 address in dots-and-numbers notatation (e.g.,
127.0.0.1
). opt-v4addr
-
This is either a
v4addr
or the symbolNone
. integer
- This is a number with neither fractional part nor decimal point.
resource-quantity
This is a number optionally followed by a scaling suffix.
Suffix Scale Example Equivalence (none)
1
19
19 (
19 * 1
)m
1e-3
200m
0.2 (
200 * 1e-3
)K
1e+3
4K
4000 (
4 * 1e+3
)Ki
2^10
4Ki
4096 (
4 * 2^10
)M
1e+6
6.5M
6500000 (
6.5 * 1e+6
)Mi
2^20
6.5Mi
6815744 (
6.5 * 2^20
)G
1e+9
0.4G
400000000 (
0.4 * 1e+9
)Gi
2^30
0.4Gi
429496729 (
0.4 * 2^30
)T
1e+12
37T
37000000000000 (
37 * 1e+12
)Ti
2^40
37Ti
40681930227712 (
37 * 2^40
)P
1e+15
9.8P
9800000000000000 (
9.8 * 1e+15
)Pi
2^50
9.8Pi
11033819087057716 (
9.8 * 2^50
)E
1e+18
0.42E
420000000000000000 (
0.42 * 1e+18
)Ei
2^60
0.42Ei
484227031934875712 (
0.42 * 2^60
)Note: The suffix is case-sensitive;
m
andM
differ.
6.3.2. Full Name
The last convention relates to the full name of a field. All field names are symbols. At the top-level, the full name of a field is identical to the field name. At each sub-level, the full name of a field is the full name of the parent structure followed by a “.
” (period, U+2E
) followed by the name of the field.
Here is a map with two top-level items, one
and two
:
one: a: x: 9 y: 10 z: 11 b: q: 19 r: 20 s: 21 two: 42
The value of one
is a sub-map, while the value of two
is a simple number. The following table shows all the field names and full names.
Name | Full Name | Depth |
---|---|---|
|
| 0 (top-level) |
|
| 0 |
|
| 1 |
|
| 1 |
|
| 2 |
|
| 2 |
|
| 2 |
|
| 2 |
|
| 2 |
|
| 2 |
6.4. Common Structures
All configuration files are maps at the top-level, with a few required fields and a series of optional ones. In most cases field values are basic data elements, but sometimes the value is a list or a sub-map. In a map, the order does not matter, although it is traditional to place the required fields first.
6.4.1. Top-Level
The top-level fields are kind
, apiVersion
, metadata
, and spec
.
kind
(enum, one of:Service
,Pod
,ReplicationController
)-
This specifies what the configuration file is trying to configure. Although Kubernetes can usually infer
kind
from context, the slight redundancy of specifying it in the configuration file ensures that type errors are caught early. apiVersion
(enum)-
This specifies which version of the API is used in the configuration file. In this document all examples use
apiVersion: v1
. metadata
(map)This is a top-level field for Service, Pod and ReplicationController files and additionally found as a member of the ReplicationController’s
template
map. Common sub-fields (all optional unless otherwise indicated) are:Field Type Comment name
symbol
Required
namespace
symbol
Default is
default
labels
map
See individual types
Strictly speaking,
metadata
is optional. However, we recommend including it along with the others, anyway, becausename
andlabels
facilitate later manipulation of the Service, Pod or ReplicationController.spec
(map)- This field is the subject of the rest of this document.
6.4.2. Elsewhere
The other fields described in this section are common, in the sense of being found in more than one context, but not at top-level.
labels
(map)This is often one of the fields in the
metadata
map. Valid label keys have two segements:[prefix/]name
The
prefix
and “/
” (slash,U+2F
) portions are optional. Thename
portion is required and must be 1-63 characters in length. It must begin and end with with an alphanumeric character (i.e.,[0-9A-Za-z]
). The internal characters ofname
may include hyphen, dot and underscore. Here are some label keys, valid and invalid:Label Keys Prefix Name Comments prefix/name
prefix
name
just-a-name
(n/a)
just-a-name
-simply-wrong!
(n/a)
(n/a)
beg and end not alphanumeric
example.org/service
example.org
service
looks like a domain!
In the following example,
labels
andname
comprise the map value of fieldmetadata
and the map value oflabels
has only one key/value pair.metadata: labels: name: rabbitmq name: rabbitmq-controller
Note that in this example
metadata.labels.name
andmetadata.name
differ.selector
(map)This is often one of the fields in the
spec
map of a Service or ReplicationController, but is also found at top-level. The map specifies field names and values that must match in order for the configured object to receive traffic. For example, the following fragment matches thelabels
example above.spec: selector: name: rabbitmq
protocol
(enum, one of:TCP
,UDP
)- This specifies an IP protocol.
port
(integer)The field value is the TCP/UDP port where the service, pod or replication controller can be contacted for administration and control purposes. Similar fields are
containerPort
,hostPort
andtargetPort
. Often,port
is found in the same map withname
andprotocol
. For example, here is a fragment that shows a list of two such maps as the value for fieldports
:ports: - name: dns port: 53 protocol: UDP - name: dns-tcp port: 53 protocol: TCP
In this example, the
port
in both maps is identical, while thename
andprotocol
differ.limits
(map)The field value is a sub-map associating resource types with resource-quantity values. For
limits
the quantities describe maximum allowable values. A similar field isrequest
, which describes desired values.Valid resource types are
cpu
andmemory
. The units forcpu
are Kubernetes Compute Unit seconds/second (i.e., CPU cores normalized to a canonical "Kubernetes CPU"). The units formemory
are bytes.In the following fragment,
cpu
is limited to 0.1 KCU andmemory
to 2GiB.resources: limits: cpu: 100m memory: 2Gi
As shown here, the
limits
field is often found as part of the map value for theresources
field.
6.5. Specific Structures
The following subsections list fields found in the various configuration files apart from those in Common Structures. A field value’s type is either one of the elemental data types, including those listed in Conventions, map or list. Each subsection also discusses pitfalls for that particular file.
6.5.1. Service
At the most basic level, Kubernetes can be configured with one Service YAML and one Pod YAML. In the service YAML, the required field kind
has value Service
. The spec
tree should include ports
, and optionally, selector
and type
. The value of type
is an enum, one of: ClusterIP
(the default if type
is unspecified), NodePort
, LoadBalancer
.
Here is an example of a basic Service YAML:
kind: Service apiVersion: v1 metadata: name: blog spec: ports: - containerPort: 4567 targetPort: 80 selector: name: blog type: LoadBalancer
Note that name: blog
is indented by two columns to signify it being part of the sub-map value of both metadata
and selector
trees.
Omitting the indentation of metadata.name
places name
at top-level and gives metadata
a nil
value.
Each container’s port 4567 is visible externally as port 80, and they are accessed in a round-robin manner because of `type: LoadBalancer'.
6.5.2. Pod
In the pod YAML, the required field kind
has value Pod
. The spec
tree should include containers
and optionally volumes
fields. Their values are both a list of maps. Each element of containers
specifies an image
, with a name
and other fields that describe how the image is to be run (e.g., privileged
, resources
), what ports it exposes, and what volume mounts it requires. Each element of volumes
specfies a hostPath
, with a name
.
apiVersion: v1 kind: Pod metadata: name: host-test spec: containers: - image: nginx name: host-test privileged: false volumeMounts: - mountPath: /usr/share/nginx/html name: srv readOnly: false volumes: - hostPath: path: /srv/my-data name: srv
This example specifies the webserver nginx
to be run unprivileged and with access to the host directory /srv/my-data
visible internally as /usr/share/nginx/html
.
6.5.3. Replication Controller
In the replication controller YAML, the required field kind
has value ReplicationController
. The spec.replicas
field specifies how the pod should be horizontally scaled, that is, how many copies of a pod should be active simultaneously. The spec
tree also has a template
tree, which in turn has a sub-spec
tree that resembles the spec
tree from a Pod
YAML.
apiVersion: v1 kind: ReplicationController metadata: name: my-nginx spec: replicas: 3 1 template: metadata: labels: app: nginx spec: 2 volumes: - name: secret-volume secret: secretName: nginxsecret containers: - name: nginxhttps image: bprashanth/nginxhttps:1.0 ports: - containerPort: 443 - containerPort: 80 volumeMounts: - mountPath: /etc/nginx/ssl name: secret-volume
6.6. Field Reference
The following table lists all fields found the files, apart from those in Common Structures. A field value’s type is either one of the elemental data types (including those listed in Conventions), map, or list. For the Context column, the code is s
for services, p
for pods, r
for replication controllers.
Field | Type | Context | Example / Comment |
---|---|---|---|
| map | ||
|
| s |
|
| map | s |
one element, key |
|
| r |
|
| map | r |
one field: |
| map | r |
two fields: |
| map | r | |
|
| r |
like |
| map | pr | |
| string | pr | |
| string | r | |
| list | s | each element is an v4addr |
| boolean | pr | |
| map | pr | |
| enum | pr |
|
| list of strings | pr |
for |