Merge branch 'dev-1.22' into merged-master-dev-1.22
This commit is contained in:
PI-Victor
@@ -13,15 +13,23 @@ weight: 60
|
||||
|
||||
System component traces record the latency of and relationships between operations in the cluster.
|
||||
|
||||
Kubernetes components emit traces using the [OpenTelemetry Protocol](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md#opentelemetry-protocol-specification) with the gRPC exporter and can be collected and routed to tracing backends using an [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector#-opentelemetry-collector).
|
||||
Kubernetes components emit traces using the
|
||||
[OpenTelemetry Protocol](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md#opentelemetry-protocol-specification)
|
||||
with the gRPC exporter and can be collected and routed to tracing backends using an
|
||||
[OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector#-opentelemetry-collector).
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Trace Collection
|
||||
|
||||
For a complete guide to collecting traces and using the collector, see [Getting Started with the OpenTelemetry Collector](https://opentelemetry.io/docs/collector/getting-started/). However, there are a few things to note that are specific to Kubernetes components.
|
||||
For a complete guide to collecting traces and using the collector, see
|
||||
[Getting Started with the OpenTelemetry Collector](https://opentelemetry.io/docs/collector/getting-started/).
|
||||
However, there are a few things to note that are specific to Kubernetes components.
|
||||
|
||||
By default, Kubernetes components export traces using the grpc exporter for OTLP on the [IANA OpenTelemetry port](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=opentelemetry), 4317. As an example, if the collector is running as a sidecar to a Kubernetes component, the following receiver configuration will collect spans and log them to standard output:
|
||||
By default, Kubernetes components export traces using the grpc exporter for OTLP on the
|
||||
[IANA OpenTelemetry port](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=opentelemetry), 4317.
|
||||
As an example, if the collector is running as a sidecar to a Kubernetes component,
|
||||
the following receiver configuration will collect spans and log them to standard output:
|
||||
|
||||
```yaml
|
||||
receivers:
|
||||
@@ -43,11 +51,19 @@ service:
|
||||
|
||||
### kube-apiserver traces
|
||||
|
||||
The kube-apiserver generates spans for incoming HTTP requests, and for outgoing requests to webhooks, etcd, and re-entrant requests. It propagates the [W3C Trace Context](https://www.w3.org/TR/trace-context/) with outgoing requests but does not make use of the trace context attached to incoming requests, as the kube-apiserver is often a public endpoint.
|
||||
The kube-apiserver generates spans for incoming HTTP requests, and for outgoing requests
|
||||
to webhooks, etcd, and re-entrant requests. It propagates the
|
||||
[W3C Trace Context](https://www.w3.org/TR/trace-context/) with outgoing requests
|
||||
but does not make use of the trace context attached to incoming requests,
|
||||
as the kube-apiserver is often a public endpoint.
|
||||
|
||||
#### Enabling tracing in the kube-apiserver
|
||||
|
||||
To enable tracing, enable the `APIServerTracing` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) on the kube-apiserver. Also, provide the kube-apiserver with a tracing configration file with `--tracing-config-file=<path-to-config>`. This is an example config that records spans for 1 in 10000 requests, and uses the default OpenTelemetry endpoint:
|
||||
To enable tracing, enable the `APIServerTracing`
|
||||
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
|
||||
on the kube-apiserver. Also, provide the kube-apiserver with a tracing configration file
|
||||
with `--tracing-config-file=<path-to-config>`. This is an example config that records
|
||||
spans for 1 in 10000 requests, and uses the default OpenTelemetry endpoint:
|
||||
|
||||
```yaml
|
||||
apiVersion: apiserver.config.k8s.io/v1alpha1
|
||||
@@ -57,10 +73,17 @@ kind: TracingConfiguration
|
||||
samplingRatePerMillion: 100
|
||||
```
|
||||
|
||||
For more information about the `TracingConfiguration` struct, see
|
||||
[API server config API (v1alpha1)](/docs/reference/config-api/apiserver-config.v1alpha1/#apiserver-k8s-io-v1alpha1-TracingConfiguration).
|
||||
|
||||
## Stability
|
||||
|
||||
Tracing instrumentation is still under active development, and may change in a variety of ways. This includes span names, attached attributes, instrumented endpoints, etc. Until this feature graduates to stable, there are no guarantees of backwards compatibility for tracing instrumentation.
|
||||
Tracing instrumentation is still under active development, and may change
|
||||
in a variety of ways. This includes span names, attached attributes,
|
||||
instrumented endpoints, etc. Until this feature graduates to stable,
|
||||
there are no guarantees of backwards compatibility for tracing instrumentation.
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* Read about [Getting Started with the OpenTelemetry Collector](https://opentelemetry.io/docs/collector/getting-started/)
|
||||
|
||||
|
||||
@@ -188,9 +188,10 @@ selectors and uses DNS names instead. For more information, see the
|
||||
[ExternalName](#externalname) section later in this document.
|
||||
|
||||
### Over Capacity Endpoints
|
||||
If an Endpoints resource has more than 1000 endpoints then a Kubernetes v1.21
|
||||
cluster annotates that Endpoints with `endpoints.kubernetes.io/over-capacity: warning`.
|
||||
This annotation indicates that the affected Endpoints object is over capacity.
|
||||
If an Endpoints resource has more than 1000 endpoints then a Kubernetes v1.22 (or later)
|
||||
cluster annotates that Endpoints with `endpoints.kubernetes.io/over-capacity: truncated`.
|
||||
This annotation indicates that the affected Endpoints object is over capacity and that
|
||||
the endpoints controller has truncated the number of endpoints to 1000.
|
||||
|
||||
### EndpointSlices
|
||||
|
||||
|
||||
@@ -415,37 +415,40 @@ The access modes are:
|
||||
* ReadWriteOnce -- the volume can be mounted as read-write by a single node
|
||||
* ReadOnlyMany -- the volume can be mounted read-only by many nodes
|
||||
* ReadWriteMany -- the volume can be mounted as read-write by many nodes
|
||||
* ReadWriteOncePod -- the volume can be mounted as read-write by a single Pod.
|
||||
This is only supported for CSI volumes and Kubernetes version 1.22+.
|
||||
|
||||
In the CLI, the access modes are abbreviated to:
|
||||
|
||||
* RWO - ReadWriteOnce
|
||||
* ROX - ReadOnlyMany
|
||||
* RWX - ReadWriteMany
|
||||
* RWOP - ReadWriteOncePod
|
||||
|
||||
> __Important!__ A volume can only be mounted using one access mode at a time, even if it supports many. For example, a GCEPersistentDisk can be mounted as ReadWriteOnce by a single node or ReadOnlyMany by many nodes, but not at the same time.
|
||||
|
||||
|
||||
| Volume Plugin | ReadWriteOnce | ReadOnlyMany | ReadWriteMany|
|
||||
| :--- | :---: | :---: | :---: |
|
||||
| AWSElasticBlockStore | ✓ | - | - |
|
||||
| AzureFile | ✓ | ✓ | ✓ |
|
||||
| AzureDisk | ✓ | - | - |
|
||||
| CephFS | ✓ | ✓ | ✓ |
|
||||
| Cinder | ✓ | - | - |
|
||||
| CSI | depends on the driver | depends on the driver | depends on the driver |
|
||||
| FC | ✓ | ✓ | - |
|
||||
| FlexVolume | ✓ | ✓ | depends on the driver |
|
||||
| Flocker | ✓ | - | - |
|
||||
| GCEPersistentDisk | ✓ | ✓ | - |
|
||||
| Glusterfs | ✓ | ✓ | ✓ |
|
||||
| HostPath | ✓ | - | - |
|
||||
| iSCSI | ✓ | ✓ | - |
|
||||
| Quobyte | ✓ | ✓ | ✓ |
|
||||
| NFS | ✓ | ✓ | ✓ |
|
||||
| RBD | ✓ | ✓ | - |
|
||||
| VsphereVolume | ✓ | - | - (works when Pods are collocated) |
|
||||
| PortworxVolume | ✓ | - | ✓ |
|
||||
| StorageOS | ✓ | - | - |
|
||||
| Volume Plugin | ReadWriteOnce | ReadOnlyMany | ReadWriteMany | ReadWriteOncePod |
|
||||
| :--- | :---: | :---: | :---: | - |
|
||||
| AWSElasticBlockStore | ✓ | - | - | - |
|
||||
| AzureFile | ✓ | ✓ | ✓ | - |
|
||||
| AzureDisk | ✓ | - | - | - |
|
||||
| CephFS | ✓ | ✓ | ✓ | - |
|
||||
| Cinder | ✓ | - | - | - |
|
||||
| CSI | depends on the driver | depends on the driver | depends on the driver | depends on the driver |
|
||||
| FC | ✓ | ✓ | - | - |
|
||||
| FlexVolume | ✓ | ✓ | depends on the driver | - |
|
||||
| Flocker | ✓ | - | - | - |
|
||||
| GCEPersistentDisk | ✓ | ✓ | - | - |
|
||||
| Glusterfs | ✓ | ✓ | ✓ | - |
|
||||
| HostPath | ✓ | - | - | - |
|
||||
| iSCSI | ✓ | ✓ | - | - |
|
||||
| Quobyte | ✓ | ✓ | ✓ | - |
|
||||
| NFS | ✓ | ✓ | ✓ | - |
|
||||
| RBD | ✓ | ✓ | - | - |
|
||||
| VsphereVolume | ✓ | - | - (works when Pods are collocated) | - |
|
||||
| PortworxVolume | ✓ | - | ✓ | - | - |
|
||||
| StorageOS | ✓ | - | - | - |
|
||||
|
||||
### Class
|
||||
|
||||
@@ -792,6 +795,82 @@ spec:
|
||||
storage: 10Gi
|
||||
```
|
||||
|
||||
## Volume populators and data sources
|
||||
|
||||
{{< feature-state for_k8s_version="v1.22" state="alpha" >}}
|
||||
|
||||
{{< note >}}
|
||||
Kubernetes supports custom volume populators; this alpha feature was introduced
|
||||
in Kubernetes 1.18. Kubernetes 1.22 reimplemented the mechanism with a redesigned API.
|
||||
Check that you are reading the version of the Kubernetes documentation that matches your
|
||||
cluster. {{% version-check %}}
|
||||
To use custom volume populators, you must enable the `AnyVolumeDataSource`
|
||||
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) for
|
||||
the kube-apiserver and kube-controller-manager.
|
||||
{{< /note >}}
|
||||
|
||||
Volume populators take advantage of a PVC spec field called `dataSourceRef`. Unlike the
|
||||
`dataSource` field, which can only contain either a reference to another PersistentVolumeClaim
|
||||
or to a VolumeSnapshot, the `dataSourceRef` field can contain a reference to any object in the
|
||||
same namespace, except for core objects other than PVCs. For clusters that have the feature
|
||||
gate enabled, use of the `dataSourceRef` is preferred over `dataSource`.
|
||||
|
||||
## Data source references
|
||||
|
||||
The `dataSourceRef` field behaves almost the same as the `dataSource` field. If either one is
|
||||
specified while the other is not, the API server will give both fields the same value. Neither
|
||||
field can be changed after creation, and attempting to specify different values for the two
|
||||
fields will result in a validation error. Therefore the two fields will always have the same
|
||||
contents.
|
||||
|
||||
There are two differences between the `dataSourceRef` field and the `dataSource` field that
|
||||
users should be aware of:
|
||||
* The `dataSource` field ignores invalid values (as if the field was blank) while the
|
||||
`dataSourceRef` field never ignores values and will cause an error if an invalid value is
|
||||
used. Invalid values are any core object (objects with no apiGroup) except for PVCs.
|
||||
* The `dataSourceRef` field may contain different types of objects, while the `dataSource` field
|
||||
only allows PVCs and VolumeSnapshots.
|
||||
|
||||
Users should always use `dataSourceRef` on clusters that have the feature gate enabled, and
|
||||
fall back to `dataSource` on clusters that do not. It is not necessary to look at both fields
|
||||
under any circumstance. The duplicated values with slightly different semantics exist only for
|
||||
backwards compatibility. In particular, a mixture of older and newer controllers are able to
|
||||
interoperate because the fields are the same.
|
||||
|
||||
### Using volume populators
|
||||
|
||||
Volume populators are {{< glossary_tooltip text="controllers" term_id="controller" >}} that can
|
||||
create non-empty volumes, where the contents of the volume are determined by a Custom Resource.
|
||||
Users create a populated volume by referring to a Custom Resource using the `dataSourceRef` field:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: populated-pvc
|
||||
spec:
|
||||
dataSourceRef:
|
||||
name: example-name
|
||||
kind: ExampleDataSource
|
||||
apiGroup: example.storage.k8s.io
|
||||
accessModes:
|
||||
- ReadWriteOnce
|
||||
resources:
|
||||
requests:
|
||||
storage: 10Gi
|
||||
```
|
||||
|
||||
Because volume populators are external components, attempts to create a PVC that uses one
|
||||
can fail if not all the correct components are installed. External controllers should generate
|
||||
events on the PVC to provide feedback on the status of the creation, including warnings if
|
||||
the PVC cannot be created due to some missing component.
|
||||
|
||||
You can install the alpha [volume data source validator](https://github.com/kubernetes-csi/volume-data-source-validator)
|
||||
controller into your cluster. That controller generates warning Events on a PVC in the case that no populator
|
||||
is registered to handle that kind of data source. When a suitable populator is installed for a PVC, it's the
|
||||
responsibility of that populator controller to report Events that relate to volume creation and issues during
|
||||
the process.
|
||||
|
||||
## Writing Portable Configuration
|
||||
|
||||
If you're writing configuration templates or examples that run on a wide range of clusters
|
||||
|
||||
Reference in New Issue
Block a user