From 96b9dd41b75ddbb0facbd9660d9e6af3007003d6 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Tue, 27 Jul 2021 12:51:37 +0800 Subject: [PATCH 1/2] Add API server config API v1alpha1 The `v1alpha1` API is not the *latest* version but it contains some new structures not seen in `v1beta1` or `v1`. --- .../cluster-administration/system-traces.md | 3 + content/en/docs/reference/_index.md | 1 + .../config-api/apiserver-config.v1alpha1.md | 438 ++++++++++++++++++ 3 files changed, 442 insertions(+) create mode 100644 content/en/docs/reference/config-api/apiserver-config.v1alpha1.md diff --git a/content/en/docs/concepts/cluster-administration/system-traces.md b/content/en/docs/concepts/cluster-administration/system-traces.md index 1f63b135887..114a90c32d0 100644 --- a/content/en/docs/concepts/cluster-administration/system-traces.md +++ b/content/en/docs/concepts/cluster-administration/system-traces.md @@ -57,6 +57,9 @@ 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. diff --git a/content/en/docs/reference/_index.md b/content/en/docs/reference/_index.md index ba9e93df109..3b5e02c3f96 100644 --- a/content/en/docs/reference/_index.md +++ b/content/en/docs/reference/_index.md @@ -71,6 +71,7 @@ configure kubernetes components or tools. Most of these APIs are not exposed by the API server in a RESTful way though they are essential for a user or an operator to use or manage a cluster. +* [kube-apiserver configuration (v1alpha1)](/docs/reference/config-api/apiserver-config.v1alpha1/) * [kubelet configuration (v1beta1)](/docs/reference/config-api/kubelet-config.v1beta1/) * [kube-scheduler configuration (v1beta1)](/docs/reference/config-api/kube-scheduler-config.v1beta1/) * [kube-scheduler configuration (v1beta2)](/docs/reference/config-api/kube-scheduler-config.v1beta2/) diff --git a/content/en/docs/reference/config-api/apiserver-config.v1alpha1.md b/content/en/docs/reference/config-api/apiserver-config.v1alpha1.md new file mode 100644 index 00000000000..81702355a59 --- /dev/null +++ b/content/en/docs/reference/config-api/apiserver-config.v1alpha1.md @@ -0,0 +1,438 @@ +--- +title: kube-apiserver Configuration (v1alpha1) +content_type: tool-reference +package: apiserver.k8s.io/v1alpha1 +auto_generated: true +--- +Package v1alpha1 is the v1alpha1 version of the API. + +## Resource Types + + +- [AdmissionConfiguration](#apiserver-k8s-io-v1alpha1-AdmissionConfiguration) +- [EgressSelectorConfiguration](#apiserver-k8s-io-v1alpha1-EgressSelectorConfiguration) +- [TracingConfiguration](#apiserver-k8s-io-v1alpha1-TracingConfiguration) + + + + +## `AdmissionConfiguration` {#apiserver-k8s-io-v1alpha1-AdmissionConfiguration} + + + + + +AdmissionConfiguration provides versioned configuration for admission controllers. + + + + + + + + + + + + + + + + + +
FieldDescription
apiVersion
string		apiserver.k8s.io/v1alpha1
kind
string		AdmissionConfiguration
plugins
+[]AdmissionPluginConfiguration +		 + Plugins allows specifying a configuration per admission control plugin.
+ + + +## `EgressSelectorConfiguration` {#apiserver-k8s-io-v1alpha1-EgressSelectorConfiguration} + + + + + +EgressSelectorConfiguration provides versioned configuration for egress selector clients. + + + + + + + + + + + + + + + + + +
FieldDescription
apiVersion
string		apiserver.k8s.io/v1alpha1
kind
string		EgressSelectorConfiguration
egressSelections [Required]
+[]EgressSelection +		 + connectionServices contains a list of egress selection client configurations
+ + + +## `TracingConfiguration` {#apiserver-k8s-io-v1alpha1-TracingConfiguration} + + + + + +TracingConfiguration provides versioned configuration for tracing clients. + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
apiVersion
string		apiserver.k8s.io/v1alpha1
kind
string		TracingConfiguration
endpoint
+string +		 + Endpoint of the collector that's running on the control-plane node. +The APIServer uses the egressType ControlPlane when sending data to the collector. +The syntax is defined in https://github.com/grpc/grpc/blob/master/doc/naming.md. +Defaults to the otlpgrpc default, localhost:4317 +The connection is insecure, and does not support TLS.
samplingRatePerMillion
+int32 +		 + SamplingRatePerMillion is the number of samples to collect per million spans. +Defaults to 0.
+ + + +## `AdmissionPluginConfiguration` {#apiserver-k8s-io-v1alpha1-AdmissionPluginConfiguration} + + + + +**Appears in:** + +- [AdmissionConfiguration](#apiserver-k8s-io-v1alpha1-AdmissionConfiguration) + + +AdmissionPluginConfiguration provides the configuration for a single plug-in. + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 + Name is the name of the admission controller. +It must match the registered admission plugin name.
path
+string +		 + Path is the path to a configuration file that contains the plugin's +configuration
configuration
+k8s.io/apimachinery/pkg/runtime.Unknown +		 + Configuration is an embedded configuration object to be used as the plugin's +configuration. If present, it will be used instead of the path to the configuration file.
+ + + +## `Connection` {#apiserver-k8s-io-v1alpha1-Connection} + + + + +**Appears in:** + +- [EgressSelection](#apiserver-k8s-io-v1alpha1-EgressSelection) + + +Connection provides the configuration for a single egress selection client. + + + + + + + + + + + + + + + + + + +
FieldDescription
proxyProtocol [Required]
+ProtocolType +		 + Protocol is the protocol used to connect from client to the konnectivity server.
transport
+Transport +		 + Transport defines the transport configurations we use to dial to the konnectivity server. +This is required if ProxyProtocol is HTTPConnect or GRPC.
+ + + +## `EgressSelection` {#apiserver-k8s-io-v1alpha1-EgressSelection} + + + + +**Appears in:** + +- [EgressSelectorConfiguration](#apiserver-k8s-io-v1alpha1-EgressSelectorConfiguration) + + +EgressSelection provides the configuration for a single egress selection client. + + + + + + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 + name is the name of the egress selection. +Currently supported values are "controlplane", "master", "etcd" and "cluster" +The "master" egress selector is deprecated in favor of "controlplane"
connection [Required]
+Connection +		 + connection is the exact information used to configure the egress selection
+ + + +## `ProtocolType` {#apiserver-k8s-io-v1alpha1-ProtocolType} + +(Alias of `string`) + + +**Appears in:** + +- [Connection](#apiserver-k8s-io-v1alpha1-Connection) + + +ProtocolType is a set of valid values for Connection.ProtocolType + + + + + +## `TCPTransport` {#apiserver-k8s-io-v1alpha1-TCPTransport} + + + + +**Appears in:** + +- [Transport](#apiserver-k8s-io-v1alpha1-Transport) + + +TCPTransport provides the information to connect to konnectivity server via TCP + + + + + + + + + + + + + + + + + + +
FieldDescription
url [Required]
+string +		 + URL is the location of the konnectivity server to connect to. +As an example it might be "https://127.0.0.1:8131"
tlsConfig
+TLSConfig +		 + TLSConfig is the config needed to use TLS when connecting to konnectivity server
+ + + +## `TLSConfig` {#apiserver-k8s-io-v1alpha1-TLSConfig} + + + + +**Appears in:** + +- [TCPTransport](#apiserver-k8s-io-v1alpha1-TCPTransport) + + +TLSConfig provides the authentication information to connect to konnectivity server +Only used with TCPTransport + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
caBundle
+string +		 + caBundle is the file location of the CA to be used to determine trust with the konnectivity server. +Must be absent/empty if TCPTransport.URL is prefixed with http:// +If absent while TCPTransport.URL is prefixed with https://, default to system trust roots.
clientKey
+string +		 + clientKey is the file location of the client key to be used in mtls handshakes with the konnectivity server. +Must be absent/empty if TCPTransport.URL is prefixed with http:// +Must be configured if TCPTransport.URL is prefixed with https://
clientCert
+string +		 + clientCert is the file location of the client certificate to be used in mtls handshakes with the konnectivity server. +Must be absent/empty if TCPTransport.URL is prefixed with http:// +Must be configured if TCPTransport.URL is prefixed with https://
+ + + +## `Transport` {#apiserver-k8s-io-v1alpha1-Transport} + + + + +**Appears in:** + +- [Connection](#apiserver-k8s-io-v1alpha1-Connection) + + +Transport defines the transport configurations we use to dial to the konnectivity server + + + + + + + + + + + + + + + + + + +
FieldDescription
tcp
+TCPTransport +		 + TCP is the TCP configuration for communicating with the konnectivity server via TCP +ProxyProtocol of GRPC is not supported with TCP transport at the moment +Requires at least one of TCP or UDS to be set
uds
+UDSTransport +		 + UDS is the UDS configuration for communicating with the konnectivity server via UDS +Requires at least one of TCP or UDS to be set
+ + + +## `UDSTransport` {#apiserver-k8s-io-v1alpha1-UDSTransport} + + + + +**Appears in:** + +- [Transport](#apiserver-k8s-io-v1alpha1-Transport) + + +UDSTransport provides the information to connect to konnectivity server via UDS + + + + + + + + + + + + + +
FieldDescription
udsName [Required]
+string +		 + UDSName is the name of the unix domain socket to connect to konnectivity server +This does not use a unix:// prefix. (Eg: /etc/srv/kubernetes/konnectivity-server/konnectivity-server.socket)
+ + From 683d28574d4a32fd91ab162eff7fde17ab853dde Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Tue, 27 Jul 2021 17:42:49 +0800 Subject: [PATCH 2/2] Wrap long lines for system-traces --- .../cluster-administration/system-traces.md | 32 +++++++++++++++---- 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/content/en/docs/concepts/cluster-administration/system-traces.md b/content/en/docs/concepts/cluster-administration/system-traces.md index 114a90c32d0..f324604b16b 100644 --- a/content/en/docs/concepts/cluster-administration/system-traces.md +++ b/content/en/docs/concepts/cluster-administration/system-traces.md @@ -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). ## 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=`. 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=`. 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 @@ -62,8 +78,12 @@ For more information about the `TracingConfiguration` struct, see ## 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/) +