# ComponentStatus

ComponentStatusComponentStatus (and ComponentStatusList) holds the cluster validation info.apiVersion: v1import "k8s.io/api/core/v1"ComponentStatusComponentStatus (and ComponentStatusList) holds the cluster validation info. Deprecated: This API is deprecated in v1.19+apiVersion: v1kind: ComponentStatusmetadata (ObjectMeta)Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadataconditions ([]ComponentCondition)Patch strategy: merge on key typeMap: unique values on key type will be kept during a mergeList of component conditions observedInformation about the condition of a component.conditions.status (string), requiredStatus of the condition for a component. Valid values for "Healthy": "True", "False", or "Unknown".conditions.type (string), requiredType of condition for a component. Valid value: "Healthy"conditions.error (string)Condition error code for a component. For example, a health check error code.conditions.message (string)Message about the condition for a component. For example, information about a health check.ComponentStatusListStatus of all the conditions for the component as a list of ComponentStatus objects. Deprecated: This API is deprecated in v1.19+apiVersion: v1kind: ComponentStatusListmetadata (ListMeta)Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kindsitems ([]ComponentStatus), requiredList of ComponentStatus objects.Operationsget read the specified ComponentStatusHTTP RequestGET /api/v1/componentstatuses/{name}Parametersname (in path): string, requiredname of the ComponentStatuspretty (in query): stringprettyResponse200 (ComponentStatus): OK401: Unauthorizedlist list objects of kind ComponentStatusHTTP RequestGET /api/v1/componentstatusesParametersallowWatchBookmarks (in query): booleanallowWatchBookmarkscontinue (in query): stringcontinuefieldSelector (in query): stringfieldSelectorlabelSelector (in query): stringlabelSelectorlimit (in query): integerlimitpretty (in query): stringprettyresourceVersion (in query): stringresourceVersionresourceVersionMatch (in query): stringresourceVersionMatchsendInitialEvents (in query): booleansendInitialEventstimeoutSeconds (in query): integertimeoutSecondswatch (in query): booleanwatchResponse200 (ComponentStatusList): OK401: UnauthorizedThis page is automatically generated.If you plan to report an issue with this page, mention that the page is auto-generated in your issue description. The fix may need to happen elsewhere in the Kubernetes project.


# Configure Quality of Service for Pods

Configure Quality of Service for PodsThis page shows how to configure Pods so that they will be assigned particular Quality of Service (QoS) classes. Kubernetes uses QoS classes to make decisions about evicting Pods when Node resources are exceeded.When Kubernetes creates a Pod it assigns one of these QoS classes to the Pod:GuaranteedBurstableBestEffortBefore you beginYou need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. It is recommended to run this tutorial on a cluster with at least two nodes that are not acting as control plane hosts. If you do not already have a cluster, you can create one by using minikube or you can use one of these Kubernetes playgrounds:iximiuz LabsKillercodaKodeKloudPlay with KubernetesYou also need to be able to create and delete namespaces.Create a namespaceCreate a namespace so that the resources you create in this exercise are isolated from the rest of your cluster.kubectl create namespace qos-example Create a Pod that gets assigned a QoS class of GuaranteedFor a Pod to be given a QoS class of Guaranteed:Every Container in the Pod must have a memory limit and a memory request.For every Container in the Pod, the memory limit must equal the memory request.Every Container in the Pod must have a CPU limit and a CPU request.For every Container in the Pod, the CPU limit must equal the CPU request.These restrictions apply to init containers and app containers equally. Ephemeral containers cannot define resources so these restrictions do not apply.Here is a manifest for a Pod that has one Container. The Container has a memory limit and a memory request, both equal to 200 MiB. The Container has a CPU limit and a CPU request, both equal to 700 milliCPU:pods/qos/qos-pod.yaml apiVersion: v1 kind: Pod metadata: name: qos-demo namespace: qos-example spec: containers: - name: qos-demo-ctr image: nginx resources: limits: memory: "200Mi" cpu: "700m" requests: memory: "200Mi" cpu: "700m" Create the Pod:kubectl apply -f https://k8s.io/examples/pods/qos/qos-pod.yaml --namespace=qos-example View detailed information about the Pod:kubectl get pod qos-demo --namespace=qos-example --output=yaml The output shows that Kubernetes gave the Pod a QoS class of Guaranteed. The output also verifies that the Pod Container has a memory request that matches its memory limit, and it has a CPU request that matches its CPU limit.spec: containers: ... resources: limits: cpu: 700m memory: 200Mi requests: cpu: 700m memory: 200Mi ... status: qosClass: Guaranteed Note:If a Container specifies its own memory limit, but does not specify a memory request, Kubernetes automatically assigns a memory request that matches the limit. Similarly, if a Container specifies its own CPU limit, but does not specify a CPU request, Kubernetes automatically assigns a CPU request that matches the limit.Clean upDelete your Pod:kubectl delete pod qos-demo --namespace=qos-example Create a Pod that gets assigned a QoS class of BurstableA Pod is given a QoS class of Burstable if:The Pod does not meet the criteria for QoS class Guaranteed.At least one Container in the Pod has a memory or CPU request or limit.Here is a manifest for a Pod that has one Container. The Container has a memory limit of 200 MiB and a memory request of 100 MiB.pods/qos/qos-pod-2.yaml apiVersion: v1 kind: Pod metadata: name: qos-demo-2 namespace: qos-example spec: containers: - name: qos-demo-2-ctr image: nginx resources: limits: memory: "200Mi" requests: memory: "100Mi" Create the Pod:kubectl apply -f https://k8s.io/examples/pods/qos/qos-pod-2.yaml --namespace=qos-example View detailed information about the Pod:kubectl get pod qos-demo-2 --namespace=qos-example --output=yaml The output shows that Kubernetes gave the Pod a QoS class of Burstable:spec: containers: - image: nginx imagePullPolicy: Always name: qos-demo-2-ctr resources: limits: memory: 200Mi requests: memory: 100Mi ... status: qosClass: Burstable Clean upDelete your Pod:kubectl delete pod qos-demo-2 --namespace=qos-example Create a Pod that gets assigned a QoS class of BestEffortFor a Pod to be given a QoS class of BestEffort, the Containers in the Pod must not have any memory or CPU limits or requests.Here is a manifest for a Pod that has one Container. The Container has no memory or CPU limits or requests:pods/qos/qos-pod-3.yaml apiVersion: v1 kind: Pod metadata: name: qos-demo-3 namespace: qos-example spec: containers: - name: qos-demo-3-ctr image: nginx Create the Pod:kubectl apply -f https://k8s.io/examples/pods/qos/qos-pod-3.yaml --namespace=qos-example View detailed information about the Pod:kubectl get pod qos-demo-3 --namespace=qos-example --output=yaml The output shows that Kubernetes gave the Pod a QoS class of BestEffort:spec: containers: ... resources: {} ... status: qosClass: BestEffort Clean upDelete your Pod:kubectl delete pod qos-demo-3 --namespace=qos-example Create a Pod that has two ContainersHere is a manifest for a Pod that has two Containers. One container specifies a memory request of 200 MiB. The other Container does not specify any requests or limits.pods/qos/qos-pod-4.yaml apiVersion: v1 kind: Pod metadata: name: qos-demo-4 namespace: qos-example spec: containers: - name: qos-demo-4-ctr-1 image: nginx resources: requests: memory: "200Mi" - name: qos-demo-4-ctr-2 image: redis Notice that this Pod meets the criteria for QoS class Burstable. That is, it does not meet the criteria for QoS class Guaranteed, and one of its Containers has a memory request.Create the Pod:kubectl apply -f https://k8s.io/examples/pods/qos/qos-pod-4.yaml --namespace=qos-example View detailed information about the Pod:kubectl get pod qos-demo-4 --namespace=qos-example --output=yaml The output shows that Kubernetes gave the Pod a QoS class of Burstable:spec: containers: ... name: qos-demo-4-ctr-1 resources: requests: memory: 200Mi ... name: qos-demo-4-ctr-2 resources: {} ... status: qosClass: Burstable Retrieve the QoS class for a PodRather than see all the fields, you can view just the field you need:kubectl --namespace=qos-example get pod qos-demo-4 -o jsonpath='{ .status.qosClass}{"\n"}' Burstable Clean upDelete your namespace:kubectl delete namespace qos-example What's nextFor app developersAssign Memory Resources to Containers and PodsAssign CPU Resources to Containers and PodsFor cluster administratorsConfigure Default Memory Requests and Limits for a NamespaceConfigure Default CPU Requests and Limits for a NamespaceConfigure Minimum and Maximum Memory Constraints for a NamespaceConfigure Minimum and Maximum CPU Constraints for a NamespaceConfigure Memory and CPU Quotas for a NamespaceConfigure a Pod Quota for a NamespaceConfigure Quotas for API ObjectsControl Topology Management policies on a node


# Deploy and Access the Kubernetes Dashboard

Deploy and Access the Kubernetes DashboardDeploy the web UI (Kubernetes Dashboard) and access it.Dashboard is a web-based Kubernetes user interface. You can use Dashboard to deploy containerized applications to a Kubernetes cluster, troubleshoot your containerized application, and manage the cluster resources. You can use Dashboard to get an overview of applications running on your cluster, as well as for creating or modifying individual Kubernetes resources (such as Deployments, Jobs, DaemonSets, etc). For example, you can scale a Deployment, initiate a rolling update, restart a pod or deploy new applications using a deploy wizard.Dashboard also provides information on the state of Kubernetes resources in your cluster and on any errors that may have occurred.Deploying the Dashboard UINote:Kubernetes Dashboard supports only Helm-based installation currently as it is faster and gives us better control over all dependencies required by Dashboard to run.The Dashboard UI is not deployed by default. To deploy it, run the following command:# Add kubernetes-dashboard repository helm repo add kubernetes-dashboard https://kubernetes.github.io/dashboard/ # Deploy a Helm Release named "kubernetes-dashboard" using the kubernetes-dashboard chart helm upgrade --install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard --create-namespace --namespace kubernetes-dashboard Accessing the Dashboard UITo protect your cluster data, Dashboard deploys with a minimal RBAC configuration by default. Currently, Dashboard only supports logging in with a Bearer Token. To create a token for this demo, you can follow our guide on creating a sample user.Warning:The sample user created in the tutorial will have administrative privileges and is for educational purposes only.Command line proxyYou can enable access to the Dashboard using the kubectl command-line tool, by running the following command:kubectl -n kubernetes-dashboard port-forward svc/kubernetes-dashboard-kong-proxy 8443:443 Kubectl will make Dashboard available at https://localhost:8443.The UI can only be accessed from the machine where the command is executed. See kubectl port-forward --help for more options.Note:The kubeconfig authentication method does not support external identity providers or X.509 certificate-based authentication.Welcome viewWhen you access Dashboard on an empty cluster, you'll see the welcome page. This page contains a link to this document as well as a button to deploy your first application. In addition, you can view which system applications are running by default in the kube-system namespace of your cluster, for example the Dashboard itself.Deploying containerized applicationsDashboard lets you create and deploy a containerized application as a Deployment and optional Service with a simple wizard. You can either manually specify application details, or upload a YAML or JSON manifest file containing application configuration.Click the CREATE button in the upper right corner of any page to begin.Specifying application detailsThe deploy wizard expects that you provide the following information:App name (mandatory): Name for your application. A label with the name will be added to the Deployment and Service, if any, that will be deployed.The application name must be unique within the selected Kubernetes namespace. It must start with a lowercase character, and end with a lowercase character or a number, and contain only lowercase letters, numbers and dashes (-). It is limited to 24 characters. Leading and trailing spaces are ignored.Container image (mandatory): The URL of a public Docker container image on any registry, or a private image (commonly hosted on the Google Container Registry or Docker Hub). The container image specification must end with a colon.Number of pods (mandatory): The target number of Pods you want your application to be deployed in. The value must be a positive integer.A Deployment will be created to maintain the desired number of Pods across your cluster.Service (optional): For some parts of your application (e.g. frontends) you may want to expose a Service onto an external, maybe public IP address outside of your cluster (external Service).Note:For external Services, you may need to open up one or more ports to do so.Other Services that are only visible from inside the cluster are called internal Services.Irrespective of the Service type, if you choose to create a Service and your container listens on a port (incoming), you need to specify two ports. The Service will be created mapping the port (incoming) to the target port seen by the container. This Service will route to your deployed Pods. Supported protocols are TCP and UDP. The internal DNS name for this Service will be the value you specified as application name above.If needed, you can expand the Advanced options section where you can specify more settings:Description: The text you enter here will be added as an annotation to the Deployment and displayed in the application's details.Labels: Default labels to be used for your application are application name and version. You can specify additional labels to be applied to the Deployment, Service (if any), and Pods, such as release, environment, tier, partition, and release track.Example:release=1.0 tier=frontend environment=pod track=stable Namespace: Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. They let you partition resources into logically named groups.Dashboard offers all available namespaces in a dropdown list, and allows you to create a new namespace. The namespace name may contain a maximum of 63 alphanumeric characters and dashes (-) but can not contain capital letters. Namespace names should not consist of only numbers. If the name is set as a number, such as 10, the pod will be put in the default namespace.In case the creation of the namespace is successful, it is selected by default. If the creation fails, the first namespace is selected.Image Pull Secret: In case the specified Docker container image is private, it may require pull secret credentials.Dashboard offers all available secrets in a dropdown list, and allows you to create a new secret. The secret name must follow the DNS domain name syntax, for example new.image-pull.secret. The content of a secret must be base64-encoded and specified in a .dockercfg file. The secret name may consist of a maximum of 253 characters.In case the creation of the image pull secret is successful, it is selected by default. If the creation fails, no secret is applied.CPU requirement (cores) and Memory requirement (MiB): You can specify the minimum resource limits for the container. By default, Pods run with unbounded CPU and memory limits.Run command and Run command arguments: By default, your containers run the specified Docker image's default entrypoint command. You can use the command options and arguments to override the default.Run as privileged: This setting determines whether processes in privileged containers are equivalent to processes running as root on the host. Privileged containers can make use of capabilities like manipulating the network stack and accessing devices.Environment variables: Kubernetes exposes Services through environment variables. You can compose environment variable or pass arguments to your commands using the values of environment variables. They can be used in applications to find a Service. Values can reference other variables using the $(VAR_NAME) syntax.Uploading a YAML or JSON fileKubernetes supports declarative configuration. In this style, all configuration is stored in manifests (YAML or JSON configuration files). The manifests use Kubernetes API resource schemas.As an alternative to specifying application details in the deploy wizard, you can define your application in one or more manifests, and upload the files using Dashboard.Using DashboardFollowing sections describe views of the Kubernetes Dashboard UI; what they provide and how can they be used.NavigationWhen there are Kubernetes objects defined in the cluster, Dashboard shows them in the initial view. By default only objects from the default namespace are shown and this can be changed using the namespace selector located in the navigation menu.Dashboard shows most Kubernetes object kinds and groups them in a few menu categories.Admin overviewFor cluster and namespace administrators, Dashboard lists Nodes, Namespaces and PersistentVolumes and has detail views for them. Node list view contains CPU and memory usage metrics aggregated across all Nodes. The details view shows the metrics for a Node, its specification, status, allocated resources, events and pods running on the node.WorkloadsShows all applications running in the selected namespace. The view lists applications by workload kind (for example: Deployments, ReplicaSets, StatefulSets). Each workload kind can be viewed separately. The lists summarize actionable information about the workloads, such as the number of ready pods for a ReplicaSet or current memory usage for a Pod.Detail views for workloads show status and specification information and surface relationships between objects. For example, Pods that ReplicaSet is controlling or new ReplicaSets and HorizontalPodAutoscalers for Deployments.ServicesShows Kubernetes resources that allow for exposing services to external world and discovering them within a cluster. For that reason, Service and Ingress views show Pods targeted by them, internal endpoints for cluster connections and external endpoints for external users.StorageStorage view shows PersistentVolumeClaim resources which are used by applications for storing data.ConfigMaps and SecretsShows all Kubernetes resources that are used for live configuration of applications running in clusters. The view allows for editing and managing config objects and displays secrets hidden by default.Logs viewerPod lists and detail pages link to a logs viewer that is built into Dashboard. The viewer allows for drilling down logs from containers belonging to a single Pod.What's nextFor more information, see the Kubernetes Dashboard project page.


# DNS for Services and Pods

DNS for Services and PodsYour workload can discover Services within your cluster using DNS; this page explains how that works.Kubernetes creates DNS records for Services and Pods. You can contact Services with consistent DNS names instead of IP addresses.Kubernetes publishes information about Pods and Services which is used to program DNS. kubelet configures Pods' DNS so that running containers can look up Services by name rather than IP.Services defined in the cluster are assigned DNS names. By default, a client Pod's DNS search list includes the Pod's own namespace and the cluster's default domain.Namespaces of ServicesA DNS query may return different results based on the namespace of the Pod making it. DNS queries that don't specify a namespace are limited to the Pod's namespace. Access Services in other namespaces by specifying it in the DNS query.For example, consider a Pod in a test namespace. A data Service is in the prod namespace.A query for data returns no results, because it uses the Pod's test namespace.A query for data.prod returns the intended result, because it specifies the namespace.DNS queries may be expanded using the Pod's /etc/resolv.conf. kubelet configures this file for each Pod. For example, a query for just data may be expanded to data.test.svc.cluster.local. The values of the search option are used to expand queries. To learn more about DNS queries, see the resolv.conf manual page.nameserver 10.32.0.10 search <namespace>.svc.cluster.local svc.cluster.local cluster.local options ndots:5 In summary, a Pod in the test namespace can successfully resolve either data.prod or data.prod.svc.cluster.local.DNS RecordsWhat objects get DNS records?ServicesPodsThe following sections detail the supported DNS record types and layout that is supported. Any other layout or names or queries that happen to work are considered implementation details and are subject to change without warning. For more up-to-date specification, see Kubernetes DNS-Based Service Discovery.ServicesA/AAAA records"Normal" (not headless) Services are assigned DNS A and/or AAAA records, depending on the IP family or families of the Service, with a name of the form my-svc.my-namespace.svc.cluster-domain.example. This resolves to the cluster IP of the Service.Headless Services (without a cluster IP) are also assigned DNS A and/or AAAA records, with a name of the form my-svc.my-namespace.svc.cluster-domain.example. Unlike normal Services, this resolves to the set of IPs of all of the Pods selected by the Service. Clients are expected to consume the set or else use standard round-robin selection from the set.SRV recordsSRV Records are created for named ports that are part of normal or headless services.For each named port, the SRV record has the form _port-name._port-protocol.my-svc.my-namespace.svc.cluster-domain.example.For a regular Service, this resolves to the port number and the domain name: my-svc.my-namespace.svc.cluster-domain.example.For a headless Service, this resolves to multiple answers, one for each Pod that is backing the Service, and contains the port number and the domain name of the Pod of the form hostname.my-svc.my-namespace.svc.cluster-domain.example.PodsA/AAAA recordsKube-DNS versions, prior to the implementation of the DNS specification, had the following DNS resolution:<pod-IPv4-address>.<namespace>.pod.<cluster-domain> For example, if a Pod in the default namespace has the IP address 172.17.0.3, and the domain name for your cluster is cluster.local, then the Pod has a DNS name:172-17-0-3.default.pod.cluster.local Some cluster DNS mechanisms, like CoreDNS, also provide A records for:<pod-ipv4-address>.<service-name>.<my-namespace>.svc.<cluster-domain.example> For example, if a Pod in the cafe namespace has the IP address 172.17.0.3, is an endpoint of a Service named barista, and the domain name for your cluster is cluster.local, then the Pod would have this service-scoped DNS A record.172-17-0-3.barista.cafe.svc.cluster.local Pod's hostname and subdomain fieldsCurrently when a Pod is created, its hostname (as observed from within the Pod) is the Pod's metadata.name value.The Pod spec has an optional hostname field, which can be used to specify a different hostname. When specified, it takes precedence over the Pod's name to be the hostname of the Pod (again, as observed from within the Pod). For example, given a Pod with spec.hostname set to "my-host", the Pod will have its hostname set to "my-host".The Pod spec also has an optional subdomain field which can be used to indicate that the pod is part of sub-group of the namespace. For example, a Pod with spec.hostname set to "foo", and spec.subdomain set to "bar", in namespace "my-namespace", will have its hostname set to "foo" and its fully qualified domain name (FQDN) set to "foo.bar.my-namespace.svc.cluster.local" (once more, as observed from within the Pod).If there exists a headless Service in the same namespace as the Pod, with the same name as the subdomain, the cluster's DNS Server also returns A and/or AAAA records for the Pod's fully qualified hostname.Example:apiVersion: v1 kind: Service metadata: name: busybox-subdomain spec: selector: name: busybox clusterIP: None ports: - name: foo # name is not required for single-port Services port: 1234 --- apiVersion: v1 kind: Pod metadata: name: busybox1 labels: name: busybox spec: hostname: busybox-1 subdomain: busybox-subdomain containers: - image: busybox:1.28 command: - sleep - "3600" name: busybox --- apiVersion: v1 kind: Pod metadata: name: busybox2 labels: name: busybox spec: hostname: busybox-2 subdomain: busybox-subdomain containers: - image: busybox:1.28 command: - sleep - "3600" name: busybox Given the above Service "busybox-subdomain" and the Pods which set spec.subdomain to "busybox-subdomain", the first Pod will see its own FQDN as "busybox-1.busybox-subdomain.my-namespace.svc.cluster-domain.example". DNS serves A and/or AAAA records at that name, pointing to the Pod's IP. Both Pods "busybox1" and "busybox2" will have their own address records.An EndpointSlice can specify the DNS hostname for any endpoint addresses, along with its IP.Note:A and AAAA records are not created for Pod names since hostname is missing for the Pod. A Pod with no hostname but with subdomain will only create the A or AAAA record for the headless Service (busybox-subdomain.my-namespace.svc.cluster-domain.example), pointing to the Pods' IP addresses. Also, the Pod needs to be ready in order to have a record unless publishNotReadyAddresses=True is set on the Service.Pod's setHostnameAsFQDN fieldFEATURE STATE: Kubernetes v1.22 [stable]When a Pod is configured to have fully qualified domain name (FQDN), its hostname is the short hostname. For example, if you have a Pod with the fully qualified domain name busybox-1.busybox-subdomain.my-namespace.svc.cluster-domain.example, then by default the hostname command inside that Pod returns busybox-1 and the hostname --fqdn command returns the FQDN.When you set setHostnameAsFQDN: true in the Pod spec, the kubelet writes the Pod's FQDN into the hostname for that Pod's namespace. In this case, both hostname and hostname --fqdn return the Pod's FQDN.Note:In Linux, the hostname field of the kernel (the nodename field of struct utsname) is limited to 64 characters.If a Pod enables this feature and its FQDN is longer than 64 character, it will fail to start. The Pod will remain in Pending status (ContainerCreating as seen by kubectl) generating error events, such as Failed to construct FQDN from Pod hostname and cluster domain, FQDN long-FQDN is too long (64 characters is the max, 70 characters requested). One way of improving user experience for this scenario is to create an admission webhook controller to control FQDN size when users create top level objects, for example, Deployment.Pod's DNS PolicyDNS policies can be set on a per-Pod basis. Currently Kubernetes supports the following Pod-specific DNS policies. These policies are specified in the dnsPolicy field of a Pod Spec."Default": The Pod inherits the name resolution configuration from the node that the Pods run on. See related discussion for more details."ClusterFirst": Any DNS query that does not match the configured cluster domain suffix, such as "www.kubernetes.io", is forwarded to an upstream nameserver by the DNS server. Cluster administrators may have extra stub-domain and upstream DNS servers configured. See related discussion for details on how DNS queries are handled in those cases."ClusterFirstWithHostNet": For Pods running with hostNetwork, you should explicitly set its DNS policy to "ClusterFirstWithHostNet". Otherwise, Pods running with hostNetwork and "ClusterFirst" will fallback to the behavior of the "Default" policy.Note:This is not supported on Windows. See below for details."None": It allows a Pod to ignore DNS settings from the Kubernetes environment. All DNS settings are supposed to be provided using the dnsConfig field in the Pod Spec. See Pod's DNS config subsection below.Note:"Default" is not the default DNS policy. If dnsPolicy is not explicitly specified, then "ClusterFirst" is used.The example below shows a Pod with its DNS policy set to "ClusterFirstWithHostNet" because it has hostNetwork set to true.apiVersion: v1 kind: Pod metadata: name: busybox namespace: default spec: containers: - image: busybox:1.28 command: - sleep - "3600" imagePullPolicy: IfNotPresent name: busybox restartPolicy: Always hostNetwork: true dnsPolicy: ClusterFirstWithHostNet Pod's DNS ConfigFEATURE STATE: Kubernetes v1.14 [stable]Pod's DNS Config allows users more control on the DNS settings for a Pod.The dnsConfig field is optional and it can work with any dnsPolicy settings. However, when a Pod's dnsPolicy is set to "None", the dnsConfig field has to be specified.Below are the properties a user can specify in the dnsConfig field:nameservers: a list of IP addresses that will be used as DNS servers for the Pod. There can be at most 3 IP addresses specified. When the Pod's dnsPolicy is set to "None", the list must contain at least one IP address, otherwise this property is optional. The servers listed will be combined to the base nameservers generated from the specified DNS policy with duplicate addresses removed.searches: a list of DNS search domains for hostname lookup in the Pod. This property is optional. When specified, the provided list will be merged into the base search domain names generated from the chosen DNS policy. Duplicate domain names are removed. Kubernetes allows up to 32 search domains.options: an optional list of objects where each object may have a name property (required) and a value property (optional). The contents in this property will be merged to the options generated from the specified DNS policy. Duplicate entries are removed.The following is an example Pod with custom DNS settings:service/networking/custom-dns.yaml apiVersion: v1 kind: Pod metadata: namespace: default name: dns-example spec: containers: - name: test image: nginx dnsPolicy: "None" dnsConfig: nameservers: - 192.0.2.1 # this is an example searches: - ns1.svc.cluster-domain.example - my.dns.search.suffix options: - name: ndots value: "2" - name: edns0 When the Pod above is created, the container test gets the following contents in its /etc/resolv.conf file:nameserver 192.0.2.1 search ns1.svc.cluster-domain.example my.dns.search.suffix options ndots:2 edns0 For IPv6 setup, search path and name server should be set up like this:kubectl exec -it dns-example -- cat /etc/resolv.conf The output is similar to this:nameserver 2001:db8:30::a search default.svc.cluster-domain.example svc.cluster-domain.example cluster-domain.example options ndots:5 DNS search domain list limitsFEATURE STATE: Kubernetes 1.28 [stable]Kubernetes itself does not limit the DNS Config until the length of the search domain list exceeds 32 or the total length of all search domains exceeds 2048. This limit applies to the node's resolver configuration file, the Pod's DNS Config, and the merged DNS Config respectively.Note:Some container runtimes of earlier versions may have their own restrictions on the number of DNS search domains. Depending on the container runtime environment, the pods with a large number of DNS search domains may get stuck in the pending state.It is known that containerd v1.5.5 or earlier and CRI-O v1.21 or earlier have this problem.DNS resolution on Windows nodesClusterFirstWithHostNet is not supported for Pods that run on Windows nodes. Windows treats all names with a . as a FQDN and skips FQDN resolution.On Windows, there are multiple DNS resolvers that can be used. As these come with slightly different behaviors, using the Resolve-DNSName powershell cmdlet for name query resolutions is recommended.On Linux, you have a DNS suffix list, which is used after resolution of a name as fully qualified has failed. On Windows, you can only have 1 DNS suffix, which is the DNS suffix associated with that Pod's namespace (example: mydns.svc.cluster.local). Windows can resolve FQDNs, Services, or network name which can be resolved with this single suffix. For example, a Pod spawned in the default namespace, will have the DNS suffix default.svc.cluster.local. Inside a Windows Pod, you can resolve both kubernetes.default.svc.cluster.local and kubernetes, but not the partially qualified names (kubernetes.default or kubernetes.default.svc).What's nextFor guidance on administering DNS configurations, check Configure DNS Service.


# Adopting Sidecar Containers

Adopting Sidecar ContainersThis section is relevant for people adopting a new built-in sidecar containers feature for their workloads.Sidecar container is not a new concept as posted in the blog post. Kubernetes allows running multiple containers in a Pod to implement this concept. However, running a sidecar container as a regular container has a lot of limitations being fixed with the new built-in sidecar containers support.FEATURE STATE: Kubernetes v1.33 [stable] (enabled by default: true)ObjectivesUnderstand the need for sidecar containersBe able to troubleshoot issues with the sidecar containersUnderstand options to universally "inject" sidecar containers to any workloadBefore you beginYou need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. It is recommended to run this tutorial on a cluster with at least two nodes that are not acting as control plane hosts. If you do not already have a cluster, you can create one by using minikube or you can use one of these Kubernetes playgrounds:iximiuz LabsKillercodaKodeKloudPlay with KubernetesYour Kubernetes server must be at or later than version 1.29.To check the version, enter kubectl version.Sidecar containers overviewSidecar containers are secondary containers that run along with the main application container within the same Pod. These containers are used to enhance or to extend the functionality of the primary app container by providing additional services, or functionalities such as logging, monitoring, security, or data synchronization, without directly altering the primary application code. You can read more in the Sidecar containers concept page.The concept of sidecar containers is not new and there are multiple implementations of this concept. As well as sidecar containers that you, the person defining the Pod, want to run, you can also find that some addons modify Pods - before the Pods start running - so that there are extra sidecar containers. The mechanisms to inject those extra sidecars are often mutating webhooks. For example, a service mesh addon might inject a sidecar that configures mutual TLS and encryption in transit between different Pods.While the concept of sidecar containers is not new, the native implementation of this feature in Kubernetes, however, is new. And as with every new feature, adopting this feature may present certain challenges.This tutorial explores challenges and solutions that can be experienced by end users as well as by authors of sidecar containers.Benefits of a built-in sidecar containerUsing Kubernetes' native support for sidecar containers provides several benefits:You can configure a native sidecar container to start ahead of init containers.The built-in sidecar containers can be authored to guarantee that they are terminated last. Sidecar containers are terminated with a SIGTERM signal once all the regular containers are completed and terminated. If the sidecar container isn’t gracefully shut down, a SIGKILL signal will be used to terminate it.With Jobs, when Pod's restartPolicy: OnFailure or restartPolicy: Never, native sidecar containers do not block Pod completion. With legacy sidecar containers, special care is needed to handle this situation.Also, with Jobs, built-in sidecar containers would keep being restarted once they are done, even if regular containers would not with Pod's restartPolicy: Never.See differences from init containers to learn more about it.Adopting built-in sidecar containersThe SidecarContainers feature gate is in beta state starting from Kubernetes version 1.29 and is enabled by default. Some clusters may have this feature disabled or have software installed that is incompatible with the feature.When this happens, the Pod may be rejected or the sidecar containers may block Pod startup, rendering the Pod useless. This condition is easy to detect as the Pod simply gets stuck on initialization. However, it is often unclear what caused the problem.Here are the considerations and troubleshooting steps that one can take while adopting sidecar containers for their workload.Ensure the feature gate is enabledAs a very first step, make sure that both API server and Nodes are at Kubernetes version v1.29 or later. The feature will break on clusters where Nodes are running earlier versions where it is not enabled.NoteThe feature can be enabled on nodes with the version 1.28. The behavior of built-in sidecar container termination was different in version 1.28, and it is not recommended to adjust the behavior of a sidecar to that behavior. However, if the only concern is the startup order, the above statement can be changed to Nodes running version 1.28 with the feature gate enabled.You should ensure that the feature gate is enabled for the API server(s) within the control plane and for all nodes.One of the ways to check the feature gate enablement is to run a command like this:For API Server:kubectl get --raw /metrics | grep kubernetes_feature_enabled | grep SidecarContainers For the individual node:kubectl get --raw /api/v1/nodes/<node-name>/proxy/metrics | grep kubernetes_feature_enabled | grep SidecarContainers If you see something like this:kubernetes_feature_enabled{name="SidecarContainers",stage="BETA"} 1 it means that the feature is enabled.Check for 3rd party tooling and mutating webhooksIf you experience issues when validating the feature, it may be an indication that one of the 3rd party tools or mutating webhooks are broken.When the SidecarContainers feature gate is enabled, Pods gain a new field in their API. Some tools or mutating webhooks might have been built with an earlier version of Kubernetes API.If tools pass unknown fields as-is using various patching strategies to mutate a Pod object, this will not be a problem. However, there are tools that will strip out unknown fields; if you have those, they must be recompiled with the v1.28+ version of Kubernetes API client code.The way to check this is to use the kubectl describe pod command with your Pod that has passed through mutating admission. If any tools stripped out the new field (restartPolicy:Always), you will not see it in the command output.If you hit an issue like this, please advise the author of the tools or the webhooks use one of the patching strategies for modifying objects instead of a full object update.NoteMutating webhook may update Pods based on some conditions. Thus, sidecar containers may work for some Pods and fail for others.Automatic injection of sidecarsIf you are using software that injects sidecars automatically, there are a few possible strategies you may follow to ensure that native sidecar containers can be used. All strategies are generally options you may choose to decide whether the Pod the sidecar will be injected to will land on a Node supporting the feature or not.As an example, you can follow this conversation in Istio community. The discussion explores the options listed below.Mark Pods that land to nodes supporting sidecars. You can use node labels and node affinity to mark nodes supporting sidecar containers and Pods landing on those nodes.Check Nodes compatibility on injection. During sidecar injection, you may use the following strategies to check node compatibility:query node version and assume the feature gate is enabled on the version 1.29+query node prometheus metrics and check feature enablement statusassume the nodes are running with a supported version skew from the API serverthere may be other custom ways to detect nodes compatibility.Develop a universal sidecar injector. The idea of a universal sidecar injector is to inject a sidecar container as a regular container as well as a native sidecar container. And have a runtime logic to decide which one will work. The universal sidecar injector is wasteful, as it will account for requests twice, but may be considered as a workable solution for special cases.One way would be on start of a native sidecar container detect the node version and exit immediately if the version does not support the sidecar feature.Consider a runtime feature detection design:Define an empty dir so containers can communicate with each otherInject an init container, let's call it NativeSidecar with restartPolicy=Always.NativeSidecar must write a file to an empty directory indicating the first run and exit immediately with exit code 0.NativeSidecar on restart (when native sidecars are supported) checks that file already exists in the empty dir and changes it - indicating that the built-in sidecar containers are supported and running.Inject regular container, let's call it OldWaySidecar.OldWaySidecar on start checks the presence of a file in an empty dir.If the file indicates that the NativeSidecar is NOT running, it assumes that the sidecar feature is not supported and works assuming it is the sidecar.If the file indicates that the NativeSidecar is running, it either does nothing and sleeps forever (in the case when Pod’s restartPolicy=Always) or exits immediately with exit code 0 (in the case when Pod’s restartPolicy!=Always).What's nextLearn more about sidecar containers.


# StatefulSet

StatefulSetStatefulSet represents a set of pods with consistent identities.apiVersion: apps/v1import "k8s.io/api/apps/v1"StatefulSetStatefulSet represents a set of pods with consistent identities. Identities are defined as:Network: A single stable DNS and hostname.Storage: As many VolumeClaims as requested.The StatefulSet guarantees that a given network identity will always map to the same storage identity.apiVersion: apps/v1kind: StatefulSetmetadata (ObjectMeta)Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadataspec (StatefulSetSpec)Spec defines the desired identities of pods in this set.status (StatefulSetStatus)Status is the current status of Pods in this StatefulSet. This data may be out of date by some window of time.StatefulSetSpecA StatefulSetSpec is the specification of a StatefulSet.serviceName (string)serviceName is the name of the service that governs this StatefulSet. This service must exist before the StatefulSet, and is responsible for the network identity of the set. Pods get DNS/hostnames that follow the pattern: pod-specific-string.serviceName.default.svc.cluster.local where "pod-specific-string" is managed by the StatefulSet controller.selector (LabelSelector), requiredselector is a label query over pods that should match the replica count. It must match the pod template's labels. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectorstemplate (PodTemplateSpec), requiredtemplate is the object that describes the pod that will be created if insufficient replicas are detected. Each pod stamped out by the StatefulSet will fulfill this Template, but have a unique identity from the rest of the StatefulSet. Each pod will be named with the format <statefulsetname>-<podindex>. For example, a pod in a StatefulSet named "web" with index number "3" would be named "web-3". The only allowed template.spec.restartPolicy value is "Always".replicas (int32)replicas is the desired number of replicas of the given Template. These are replicas in the sense that they are instantiations of the same Template, but individual replicas also have a consistent identity. If unspecified, defaults to 1.updateStrategy (StatefulSetUpdateStrategy)updateStrategy indicates the StatefulSetUpdateStrategy that will be employed to update Pods in the StatefulSet when a revision is made to Template.StatefulSetUpdateStrategy indicates the strategy that the StatefulSet controller will use to perform updates. It includes any additional parameters necessary to perform the update for the indicated strategy.updateStrategy.type (string)Type indicates the type of the StatefulSetUpdateStrategy. Default is RollingUpdate.updateStrategy.rollingUpdate (RollingUpdateStatefulSetStrategy)RollingUpdate is used to communicate parameters when Type is RollingUpdateStatefulSetStrategyType.RollingUpdateStatefulSetStrategy is used to communicate parameter for RollingUpdateStatefulSetStrategyType.updateStrategy.rollingUpdate.maxUnavailable (IntOrString)The maximum number of pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). Absolute number is calculated from percentage by rounding up. This can not be 0. Defaults to 1. This field is alpha-level and is only honored by servers that enable the MaxUnavailableStatefulSet feature. The field applies to all pods in the range 0 to Replicas-1. That means if there is any unavailable pod in the range 0 to Replicas-1, it will be counted towards MaxUnavailable.IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.updateStrategy.rollingUpdate.partition (int32)Partition indicates the ordinal at which the StatefulSet should be partitioned for updates. During a rolling update, all pods from ordinal Replicas-1 to Partition are updated. All pods from ordinal Partition-1 to 0 remain untouched. This is helpful in being able to do a canary based deployment. The default value is 0.podManagementPolicy (string)podManagementPolicy controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down. The default policy is OrderedReady, where pods are created in increasing order (pod-0, then pod-1, etc) and the controller will wait until each pod is ready before continuing. When scaling down, the pods are removed in the opposite order. The alternative policy is Parallel which will create pods in parallel to match the desired scale without waiting, and on scale down will delete all pods at once.revisionHistoryLimit (int32)revisionHistoryLimit is the maximum number of revisions that will be maintained in the StatefulSet's revision history. The revision history consists of all revisions not represented by a currently applied StatefulSetSpec version. The default value is 10.volumeClaimTemplates ([]PersistentVolumeClaim)Atomic: will be replaced during a mergevolumeClaimTemplates is a list of claims that pods are allowed to reference. The StatefulSet controller is responsible for mapping network identities to claims in a way that maintains the identity of a pod. Every claim in this list must have at least one matching (by name) volumeMount in one container in the template. A claim in this list takes precedence over any volumes in the template, with the same name.minReadySeconds (int32)Minimum number of seconds for which a newly created pod should be ready without any of its container crashing for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready)persistentVolumeClaimRetentionPolicy (StatefulSetPersistentVolumeClaimRetentionPolicy)persistentVolumeClaimRetentionPolicy describes the lifecycle of persistent volume claims created from volumeClaimTemplates. By default, all persistent volume claims are created as needed and retained until manually deleted. This policy allows the lifecycle to be altered, for example by deleting persistent volume claims when their stateful set is deleted, or when their pod is scaled down.StatefulSetPersistentVolumeClaimRetentionPolicy describes the policy used for PVCs created from the StatefulSet VolumeClaimTemplates.persistentVolumeClaimRetentionPolicy.whenDeleted (string)WhenDeleted specifies what happens to PVCs created from StatefulSet VolumeClaimTemplates when the StatefulSet is deleted. The default policy of Retain causes PVCs to not be affected by StatefulSet deletion. The Delete policy causes those PVCs to be deleted.persistentVolumeClaimRetentionPolicy.whenScaled (string)WhenScaled specifies what happens to PVCs created from StatefulSet VolumeClaimTemplates when the StatefulSet is scaled down. The default policy of Retain causes PVCs to not be affected by a scaledown. The Delete policy causes the associated PVCs for any excess pods above the replica count to be deleted.ordinals (StatefulSetOrdinals)ordinals controls the numbering of replica indices in a StatefulSet. The default ordinals behavior assigns a "0" index to the first replica and increments the index by one for each additional replica requested.StatefulSetOrdinals describes the policy used for replica ordinal assignment in this StatefulSet.ordinals.start (int32)start is the number representing the first replica's index. It may be used to number replicas from an alternate index (eg: 1-indexed) over the default 0-indexed names, or to orchestrate progressive movement of replicas from one StatefulSet to another. If set, replica indices will be in the range: [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas). If unset, defaults to 0. Replica indices will be in the range: [0, .spec.replicas).StatefulSetStatusStatefulSetStatus represents the current state of a StatefulSet.replicas (int32), requiredreplicas is the number of Pods created by the StatefulSet controller.readyReplicas (int32)readyReplicas is the number of pods created for this StatefulSet with a Ready Condition.currentReplicas (int32)currentReplicas is the number of Pods created by the StatefulSet controller from the StatefulSet version indicated by currentRevision.updatedReplicas (int32)updatedReplicas is the number of Pods created by the StatefulSet controller from the StatefulSet version indicated by updateRevision.availableReplicas (int32)Total number of available pods (ready for at least minReadySeconds) targeted by this statefulset.collisionCount (int32)collisionCount is the count of hash collisions for the StatefulSet. The StatefulSet controller uses this field as a collision avoidance mechanism when it needs to create the name for the newest ControllerRevision.conditions ([]StatefulSetCondition)Patch strategy: merge on key typeMap: unique values on key type will be kept during a mergeRepresents the latest available observations of a statefulset's current state.StatefulSetCondition describes the state of a statefulset at a certain point.conditions.status (string), requiredStatus of the condition, one of True, False, Unknown.conditions.type (string), requiredType of statefulset condition.conditions.lastTransitionTime (Time)Last time the condition transitioned from one status to another.Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.conditions.message (string)A human readable message indicating details about the transition.conditions.reason (string)The reason for the condition's last transition.currentRevision (string)currentRevision, if not empty, indicates the version of the StatefulSet used to generate Pods in the sequence [0,currentReplicas).updateRevision (string)updateRevision, if not empty, indicates the version of the StatefulSet used to generate Pods in the sequence [replicas-updatedReplicas,replicas)observedGeneration (int64)observedGeneration is the most recent generation observed for this StatefulSet. It corresponds to the StatefulSet's generation, which is updated on mutation by the API Server.StatefulSetListStatefulSetList is a collection of StatefulSets.apiVersion: apps/v1kind: StatefulSetListmetadata (ListMeta)Standard list's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadataitems ([]StatefulSet), requiredItems is the list of stateful sets.Operationsget read the specified StatefulSetHTTP RequestGET /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}Parametersname (in path): string, requiredname of the StatefulSetnamespace (in path): string, requirednamespacepretty (in query): stringprettyResponse200 (StatefulSet): OK401: Unauthorizedget read status of the specified StatefulSetHTTP RequestGET /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}/statusParametersname (in path): string, requiredname of the StatefulSetnamespace (in path): string, requirednamespacepretty (in query): stringprettyResponse200 (StatefulSet): OK401: Unauthorizedlist list or watch objects of kind StatefulSetHTTP RequestGET /apis/apps/v1/namespaces/{namespace}/statefulsetsParametersnamespace (in path): string, requirednamespaceallowWatchBookmarks (in query): booleanallowWatchBookmarkscontinue (in query): stringcontinuefieldSelector (in query): stringfieldSelectorlabelSelector (in query): stringlabelSelectorlimit (in query): integerlimitpretty (in query): stringprettyresourceVersion (in query): stringresourceVersionresourceVersionMatch (in query): stringresourceVersionMatchsendInitialEvents (in query): booleansendInitialEventstimeoutSeconds (in query): integertimeoutSecondswatch (in query): booleanwatchResponse200 (StatefulSetList): OK401: Unauthorizedlist list or watch objects of kind StatefulSetHTTP RequestGET /apis/apps/v1/statefulsetsParametersallowWatchBookmarks (in query): booleanallowWatchBookmarkscontinue (in query): stringcontinuefieldSelector (in query): stringfieldSelectorlabelSelector (in query): stringlabelSelectorlimit (in query): integerlimitpretty (in query): stringprettyresourceVersion (in query): stringresourceVersionresourceVersionMatch (in query): stringresourceVersionMatchsendInitialEvents (in query): booleansendInitialEventstimeoutSeconds (in query): integertimeoutSecondswatch (in query): booleanwatchResponse200 (StatefulSetList): OK401: Unauthorizedcreate create a StatefulSetHTTP RequestPOST /apis/apps/v1/namespaces/{namespace}/statefulsetsParametersnamespace (in path): string, requirednamespacebody: StatefulSet, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationpretty (in query): stringprettyResponse200 (StatefulSet): OK201 (StatefulSet): Created202 (StatefulSet): Accepted401: Unauthorizedupdate replace the specified StatefulSetHTTP RequestPUT /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}Parametersname (in path): string, requiredname of the StatefulSetnamespace (in path): string, requirednamespacebody: StatefulSet, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationpretty (in query): stringprettyResponse200 (StatefulSet): OK201 (StatefulSet): Created401: Unauthorizedupdate replace status of the specified StatefulSetHTTP RequestPUT /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}/statusParametersname (in path): string, requiredname of the StatefulSetnamespace (in path): string, requirednamespacebody: StatefulSet, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationpretty (in query): stringprettyResponse200 (StatefulSet): OK201 (StatefulSet): Created401: Unauthorizedpatch partially update the specified StatefulSetHTTP RequestPATCH /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}Parametersname (in path): string, requiredname of the StatefulSetnamespace (in path): string, requirednamespacebody: Patch, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationforce (in query): booleanforcepretty (in query): stringprettyResponse200 (StatefulSet): OK201 (StatefulSet): Created401: Unauthorizedpatch partially update status of the specified StatefulSetHTTP RequestPATCH /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}/statusParametersname (in path): string, requiredname of the StatefulSetnamespace (in path): string, requirednamespacebody: Patch, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationforce (in query): booleanforcepretty (in query): stringprettyResponse200 (StatefulSet): OK201 (StatefulSet): Created401: Unauthorizeddelete delete a StatefulSetHTTP RequestDELETE /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}Parametersname (in path): string, requiredname of the StatefulSetnamespace (in path): string, requirednamespacebody: DeleteOptionsdryRun (in query): stringdryRungracePeriodSeconds (in query): integergracePeriodSecondsignoreStoreReadErrorWithClusterBreakingPotential (in query): booleanignoreStoreReadErrorWithClusterBreakingPotentialpretty (in query): stringprettypropagationPolicy (in query): stringpropagationPolicyResponse200 (Status): OK202 (Status): Accepted401: Unauthorizeddeletecollection delete collection of StatefulSetHTTP RequestDELETE /apis/apps/v1/namespaces/{namespace}/statefulsetsParametersnamespace (in path): string, requirednamespacebody: DeleteOptionscontinue (in query): stringcontinuedryRun (in query): stringdryRunfieldSelector (in query): stringfieldSelectorgracePeriodSeconds (in query): integergracePeriodSecondsignoreStoreReadErrorWithClusterBreakingPotential (in query): booleanignoreStoreReadErrorWithClusterBreakingPotentiallabelSelector (in query): stringlabelSelectorlimit (in query): integerlimitpretty (in query): stringprettypropagationPolicy (in query): stringpropagationPolicyresourceVersion (in query): stringresourceVersionresourceVersionMatch (in query): stringresourceVersionMatchsendInitialEvents (in query): booleansendInitialEventstimeoutSeconds (in query): integertimeoutSecondsResponse200 (Status): OK401: UnauthorizedThis page is automatically generated.If you plan to report an issue with this page, mention that the page is auto-generated in your issue description. The fix may need to happen elsewhere in the Kubernetes project.


# Explore Termination Behavior for Pods And Their Endpoints

Explore Termination Behavior for Pods And Their EndpointsOnce you connected your Application with Service following steps like those outlined in Connecting Applications with Services, you have a continuously running, replicated application, that is exposed on a network. This tutorial helps you look at the termination flow for Pods and to explore ways to implement graceful connection draining.Termination process for Pods and their endpointsThere are often cases when you need to terminate a Pod - be it to upgrade or scale down. In order to improve application availability, it may be important to implement a proper active connections draining.This tutorial explains the flow of Pod termination in connection with the corresponding endpoint state and removal by using a simple nginx web server to demonstrate the concept.Example flow with endpoint terminationThe following is the example flow described in the Termination of Pods document.Let's say you have a Deployment containing a single nginx replica (say just for the sake of demonstration purposes) and a Service:service/pod-with-graceful-termination.yaml apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment labels: app: nginx spec: replicas: 1 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: terminationGracePeriodSeconds: 120 # extra long grace period containers: - name: nginx image: nginx:latest ports: - containerPort: 80 lifecycle: preStop: exec: # Real life termination may take any time up to terminationGracePeriodSeconds. # In this example - just hang around for at least the duration of terminationGracePeriodSeconds, # at 120 seconds container will be forcibly terminated. # Note, all this time nginx will keep processing requests. command: [ "/bin/sh", "-c", "sleep 180" ] service/explore-graceful-termination-nginx.yaml apiVersion: v1 kind: Service metadata: name: nginx-service spec: selector: app: nginx ports: - protocol: TCP port: 80 targetPort: 80Now create the Deployment Pod and Service using the above files:kubectl apply -f pod-with-graceful-termination.yaml kubectl apply -f explore-graceful-termination-nginx.yaml Once the Pod and Service are running, you can get the name of any associated EndpointSlices:kubectl get endpointslice The output is similar to this:NAME ADDRESSTYPE PORTS ENDPOINTS AGE nginx-service-6tjbr IPv4 80 10.12.1.199,10.12.1.201 22m You can see its status, and validate that there is one endpoint registered:kubectl get endpointslices -o json -l kubernetes.io/service-name=nginx-service The output is similar to this:{ "addressType": "IPv4", "apiVersion": "discovery.k8s.io/v1", "endpoints": [ { "addresses": [ "10.12.1.201" ], "conditions": { "ready": true, "serving": true, "terminating": false Now let's terminate the Pod and validate that the Pod is being terminated respecting the graceful termination period configuration:kubectl delete pod nginx-deployment-7768647bf9-b4b9s All pods:kubectl get pods The output is similar to this:NAME READY STATUS RESTARTS AGE nginx-deployment-7768647bf9-b4b9s 1/1 Terminating 0 4m1s nginx-deployment-7768647bf9-rkxlw 1/1 Running 0 8s You can see that the new pod got scheduled.While the new endpoint is being created for the new Pod, the old endpoint is still around in the terminating state:kubectl get endpointslice -o json nginx-service-6tjbr The output is similar to this:{ "addressType": "IPv4", "apiVersion": "discovery.k8s.io/v1", "endpoints": [ { "addresses": [ "10.12.1.201" ], "conditions": { "ready": false, "serving": true, "terminating": true }, "nodeName": "gke-main-default-pool-dca1511c-d17b", "targetRef": { "kind": "Pod", "name": "nginx-deployment-7768647bf9-b4b9s", "namespace": "default", "uid": "66fa831c-7eb2-407f-bd2c-f96dfe841478" }, "zone": "us-central1-c" }, { "addresses": [ "10.12.1.202" ], "conditions": { "ready": true, "serving": true, "terminating": false }, "nodeName": "gke-main-default-pool-dca1511c-d17b", "targetRef": { "kind": "Pod", "name": "nginx-deployment-7768647bf9-rkxlw", "namespace": "default", "uid": "722b1cbe-dcd7-4ed4-8928-4a4d0e2bbe35" }, "zone": "us-central1-c" This allows applications to communicate their state during termination and clients (such as load balancers) to implement connection draining functionality. These clients may detect terminating endpoints and implement a special logic for them.In Kubernetes, endpoints that are terminating always have their ready status set as false. This needs to happen for backward compatibility, so existing load balancers will not use it for regular traffic. If traffic draining on terminating pod is needed, the actual readiness can be checked as a condition serving.When Pod is deleted, the old endpoint will also be deleted.What's nextLearn how to Connect Applications with ServicesLearn more about Using a Service to Access an Application in a ClusterLearn more about Connecting a Front End to a Back End Using a ServiceLearn more about Creating an External Load Balancer


# Command line tool (kubectl)

Command line tool (kubectl)Kubernetes provides a command line tool for communicating with a Kubernetes cluster's control plane, using the Kubernetes API.This tool is named kubectl.For configuration, kubectl looks for a file named config in the $HOME/.kube directory. You can specify other kubeconfig files by setting the KUBECONFIG environment variable or by setting the --kubeconfig flag.This overview covers kubectl syntax, describes the command operations, and provides common examples. For details about each command, including all the supported flags and subcommands, see the kubectl reference documentation.For installation instructions, see Installing kubectl; for a quick guide, see the cheat sheet. If you're used to using the docker command-line tool, kubectl for Docker Users explains some equivalent commands for Kubernetes.SyntaxUse the following syntax to run kubectl commands from your terminal window:kubectl [command] [TYPE] [NAME] [flags] where command, TYPE, NAME, and flags are:command: Specifies the operation that you want to perform on one or more resources, for example create, get, describe, delete.TYPE: Specifies the resource type. Resource types are case-insensitive and you can specify the singular, plural, or abbreviated forms. For example, the following commands produce the same output:kubectl get pod pod1 kubectl get pods pod1 kubectl get po pod1 NAME: Specifies the name of the resource. Names are case-sensitive. If the name is omitted, details for all resources are displayed, for example kubectl get pods.When performing an operation on multiple resources, you can specify each resource by type and name or specify one or more files:To specify resources by type and name:To group resources if they are all the same type: TYPE1 name1 name2 name<#>.Example: kubectl get pod example-pod1 example-pod2To specify multiple resource types individually: TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>.Example: kubectl get pod/example-pod1 replicationcontroller/example-rc1To specify resources with one or more files: -f file1 -f file2 -f file<#>Use YAML rather than JSON since YAML tends to be more user-friendly, especially for configuration files.Example: kubectl get -f ./pod.yamlflags: Specifies optional flags. For example, you can use the -s or --server flags to specify the address and port of the Kubernetes API server.Caution:Flags that you specify from the command line override default values and any corresponding environment variables.If you need help, run kubectl help from the terminal window.In-cluster authentication and namespace overridesBy default kubectl will first determine if it is running within a pod, and thus in a cluster. It starts by checking for the KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT environment variables and the existence of a service account token file at /var/run/secrets/kubernetes.io/serviceaccount/token. If all three are found in-cluster authentication is assumed.To maintain backwards compatibility, if the POD_NAMESPACE environment variable is set during in-cluster authentication it will override the default namespace from the service account token. Any manifests or tools relying on namespace defaulting will be affected by this.POD_NAMESPACE environment variableIf the POD_NAMESPACE environment variable is set, cli operations on namespaced resources will default to the variable value. For example, if the variable is set to seattle, kubectl get pods would return pods in the seattle namespace. This is because pods are a namespaced resource, and no namespace was provided in the command. Review the output of kubectl api-resources to determine if a resource is namespaced.Explicit use of --namespace <value> overrides this behavior.How kubectl handles ServiceAccount tokensIf:there is Kubernetes service account token file mounted at /var/run/secrets/kubernetes.io/serviceaccount/token, andthe KUBERNETES_SERVICE_HOST environment variable is set, andthe KUBERNETES_SERVICE_PORT environment variable is set, andyou don't explicitly specify a namespace on the kubectl command linethen kubectl assumes it is running in your cluster. The kubectl tool looks up the namespace of that ServiceAccount (this is the same as the namespace of the Pod) and acts against that namespace. This is different from what happens outside of a cluster; when kubectl runs outside a cluster and you don't specify a namespace, the kubectl command acts against the namespace set for the current context in your client configuration. To change the default namespace for your kubectl you can use the following command:kubectl config set-context --current --namespace=<namespace-name> OperationsThe following table includes short descriptions and the general syntax for all of the kubectl operations:OperationSyntaxDescriptionalphakubectl alpha SUBCOMMAND [flags]List the available commands that correspond to alpha features, which are not enabled in Kubernetes clusters by default.annotatekubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags]Add or update the annotations of one or more resources.api-resourceskubectl api-resources [flags]List the API resources that are available.api-versionskubectl api-versions [flags]List the API versions that are available.applykubectl apply -f FILENAME [flags]Apply a configuration change to a resource from a file or stdin.attachkubectl attach POD -c CONTAINER [-i] [-t] [flags]Attach to a running container either to view the output stream or interact with the container (stdin).authkubectl auth [flags] [options]Inspect authorization.autoscalekubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU] [flags]Automatically scale the set of pods that are managed by a replication controller.certificatekubectl certificate SUBCOMMAND [options]Modify certificate resources.cluster-infokubectl cluster-info [flags]Display endpoint information about the master and services in the cluster.completionkubectl completion SHELL [options]Output shell completion code for the specified shell (bash or zsh).configkubectl config SUBCOMMAND [flags]Modifies kubeconfig files. See the individual subcommands for details.convertkubectl convert -f FILENAME [options]Convert config files between different API versions. Both YAML and JSON formats are accepted. Note - requires kubectl-convert plugin to be installed.cordonkubectl cordon NODE [options]Mark node as unschedulable.cpkubectl cp <file-spec-src> <file-spec-dest> [options]Copy files and directories to and from containers.createkubectl create -f FILENAME [flags]Create one or more resources from a file or stdin.deletekubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags]Delete resources either from a file, stdin, or specifying label selectors, names, resource selectors, or resources.describekubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags]Display the detailed state of one or more resources.diffkubectl diff -f FILENAME [flags]Diff file or stdin against live configuration.drainkubectl drain NODE [options]Drain node in preparation for maintenance.editkubectl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags]Edit and update the definition of one or more resources on the server by using the default editor.eventskubectl eventsList eventsexeckubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]]Execute a command against a container in a pod.explainkubectl explain TYPE [--recursive=false] [flags]Get documentation of various resources. For instance pods, nodes, services, etc.exposekubectl expose (-f FILENAME | TYPE NAME | TYPE/NAME) [--port=port] [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [--external-ip=external-ip-of-service] [--type=type] [flags]Expose a replication controller, service, or pod as a new Kubernetes service.getkubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags]List one or more resources.kustomizekubectl kustomize <dir> [flags] [options]List a set of API resources generated from instructions in a kustomization.yaml file. The argument must be the path to the directory containing the file, or a git repository URL with a path suffix specifying same with respect to the repository root.labelkubectl label (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags]Add or update the labels of one or more resources.logskubectl logs POD [-c CONTAINER] [--follow] [flags]Print the logs for a container in a pod.optionskubectl optionsList of global command-line options, which apply to all commands.patchkubectl patch (-f FILENAME | TYPE NAME | TYPE/NAME) --patch PATCH [flags]Update one or more fields of a resource by using the strategic merge patch process.pluginkubectl plugin [flags] [options]Provides utilities for interacting with plugins.port-forwardkubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags]Forward one or more local ports to a pod.proxykubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags]Run a proxy to the Kubernetes API server.replacekubectl replace -f FILENAMEReplace a resource from a file or stdin.rolloutkubectl rollout SUBCOMMAND [options]Manage the rollout of a resource. Valid resource types include: deployments, daemonsets and statefulsets.runkubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client|none] [--overrides=inline-json] [flags]Run a specified image on the cluster.scalekubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags]Update the size of the specified replication controller.setkubectl set SUBCOMMAND [options]Configure application resources.taintkubectl taint NODE NAME KEY_1=VAL_1:TAINT_EFFECT_1 ... KEY_N=VAL_N:TAINT_EFFECT_N [options]Update the taints on one or more nodes.topkubectl top (POD | NODE) [flags] [options]Display Resource (CPU/Memory/Storage) usage of pod or node.uncordonkubectl uncordon NODE [options]Mark node as schedulable.versionkubectl version [--client] [flags]Display the Kubernetes version running on the client and server.waitkubectl wait ([-f FILENAME] | resource.group/resource.name | resource.group [(-l label | --all)]) [--for=delete|--for condition=available] [options]Experimental: Wait for a specific condition on one or many resources.To learn more about command operations, see the kubectl reference documentation.Resource typesThe following table includes a list of all the supported resource types and their abbreviated aliases.(This output can be retrieved from kubectl api-resources, and was accurate as of Kubernetes 1.25.0)NAMESHORTNAMESAPIVERSIONNAMESPACEDKINDbindingsv1trueBindingcomponentstatusescsv1falseComponentStatusconfigmapscmv1trueConfigMapendpointsepv1trueEndpointseventsevv1trueEventlimitrangeslimitsv1trueLimitRangenamespacesnsv1falseNamespacenodesnov1falseNodepersistentvolumeclaimspvcv1truePersistentVolumeClaimpersistentvolumespvv1falsePersistentVolumepodspov1truePodpodtemplatesv1truePodTemplatereplicationcontrollersrcv1trueReplicationControllerresourcequotasquotav1trueResourceQuotasecretsv1trueSecretserviceaccountssav1trueServiceAccountservicessvcv1trueServicemutatingwebhookconfigurationsadmissionregistration.k8s.io/v1falseMutatingWebhookConfigurationvalidatingwebhookconfigurationsadmissionregistration.k8s.io/v1falseValidatingWebhookConfigurationcustomresourcedefinitionscrd,crdsapiextensions.k8s.io/v1falseCustomResourceDefinitionapiservicesapiregistration.k8s.io/v1falseAPIServicecontrollerrevisionsapps/v1trueControllerRevisiondaemonsetsdsapps/v1trueDaemonSetdeploymentsdeployapps/v1trueDeploymentreplicasetsrsapps/v1trueReplicaSetstatefulsetsstsapps/v1trueStatefulSettokenreviewsauthentication.k8s.io/v1falseTokenReviewlocalsubjectaccessreviewsauthorization.k8s.io/v1trueLocalSubjectAccessReviewselfsubjectaccessreviewsauthorization.k8s.io/v1falseSelfSubjectAccessReviewselfsubjectrulesreviewsauthorization.k8s.io/v1falseSelfSubjectRulesReviewsubjectaccessreviewsauthorization.k8s.io/v1falseSubjectAccessReviewhorizontalpodautoscalershpaautoscaling/v2trueHorizontalPodAutoscalercronjobscjbatch/v1trueCronJobjobsbatch/v1trueJobcertificatesigningrequestscsrcertificates.k8s.io/v1falseCertificateSigningRequestleasescoordination.k8s.io/v1trueLeaseendpointslicesdiscovery.k8s.io/v1trueEndpointSliceeventsevevents.k8s.io/v1trueEventflowschemasflowcontrol.apiserver.k8s.io/v1beta2falseFlowSchemaprioritylevelconfigurationsflowcontrol.apiserver.k8s.io/v1beta2falsePriorityLevelConfigurationingressclassesnetworking.k8s.io/v1falseIngressClassingressesingnetworking.k8s.io/v1trueIngressnetworkpoliciesnetpolnetworking.k8s.io/v1trueNetworkPolicyruntimeclassesnode.k8s.io/v1falseRuntimeClasspoddisruptionbudgetspdbpolicy/v1truePodDisruptionBudgetpodsecuritypoliciespsppolicy/v1beta1falsePodSecurityPolicyclusterrolebindingsrbac.authorization.k8s.io/v1falseClusterRoleBindingclusterrolesrbac.authorization.k8s.io/v1falseClusterRolerolebindingsrbac.authorization.k8s.io/v1trueRoleBindingrolesrbac.authorization.k8s.io/v1trueRolepriorityclassespcscheduling.k8s.io/v1falsePriorityClasscsidriversstorage.k8s.io/v1falseCSIDrivercsinodesstorage.k8s.io/v1falseCSINodecsistoragecapacitiesstorage.k8s.io/v1trueCSIStorageCapacitystorageclassesscstorage.k8s.io/v1falseStorageClassvolumeattachmentsstorage.k8s.io/v1falseVolumeAttachmentOutput optionsUse the following sections for information about how you can format or sort the output of certain commands. For details about which commands support the various output options, see the kubectl reference documentation.Formatting outputThe default output format for all kubectl commands is the human readable plain-text format. To output details to your terminal window in a specific format, you can add either the -o or --output flags to a supported kubectl command.Syntaxkubectl [command] [TYPE] [NAME] -o <output_format> Depending on the kubectl operation, the following output formats are supported:Output formatDescription-o custom-columns=<spec>Print a table using a comma separated list of custom columns.-o custom-columns-file=<filename>Print a table using the custom columns template in the <filename> file.-o jsonOutput a JSON formatted API object.-o jsonpath=<template>Print the fields defined in a jsonpath expression.-o jsonpath-file=<filename>Print the fields defined by the jsonpath expression in the <filename> file.-o kyamlOutput a KYAML formatted API object (alpha, requires environment variable KUBECTL_KYAML="true").-o namePrint only the resource name and nothing else.-o wideOutput in the plain-text format with any additional information. For pods, the node name is included.-o yamlOutput a YAML formatted API object. KYAML is an experimental Kubernetes-specific dialect of YAML, and can be parsed as YAML.ExampleIn this example, the following command outputs the details for a single pod as a YAML formatted object:kubectl get pod web-pod-13je7 -o yaml Remember: See the kubectl reference documentation for details about which output format is supported by each command.Custom columnsTo define custom columns and output only the details that you want into a table, you can use the custom-columns option. You can choose to define the custom columns inline or use a template file: -o custom-columns=<spec> or -o custom-columns-file=<filename>.ExamplesInline:kubectl get pods <pod-name> -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion Template file:kubectl get pods <pod-name> -o custom-columns-file=template.txt where the template.txt file contains:NAME RSRC metadata.name metadata.resourceVersion The result of running either command is similar to:NAME RSRC submit-queue 610995 Server-side columnskubectl supports receiving specific column information from the server about objects. This means that for any given resource, the server will return columns and rows relevant to that resource, for the client to print. This allows for consistent human-readable output across clients used against the same cluster, by having the server encapsulate the details of printing.This feature is enabled by default. To disable it, add the --server-print=false flag to the kubectl get command.ExamplesTo print information about the status of a pod, use a command like the following:kubectl get pods <pod-name> --server-print=false The output is similar to:NAME AGE pod-name 1m Sorting list objectsTo output objects to a sorted list in your terminal window, you can add the --sort-by flag to a supported kubectl command. Sort your objects by specifying any numeric or string field with the --sort-by flag. To specify a field, use a jsonpath expression.Syntaxkubectl [command] [TYPE] [NAME] --sort-by=<jsonpath_exp> ExampleTo print a list of pods sorted by name, you run:kubectl get pods --sort-by=.metadata.name Examples: Common operationsUse the following set of examples to help you familiarize yourself with running the commonly used kubectl operations:kubectl apply - Apply or Update a resource from a file or stdin.# Create a service using the definition in example-service.yaml. kubectl apply -f example-service.yaml # Create a replication controller using the definition in example-controller.yaml. kubectl apply -f example-controller.yaml # Create the objects that are defined in any .yaml, .yml, or .json file within the <directory> directory. kubectl apply -f <directory> kubectl get - List one or more resources.# List all pods in plain-text output format. kubectl get pods # List all pods in plain-text output format and include additional information (such as node name). kubectl get pods -o wide # List the replication controller with the specified name in plain-text output format. Tip: You can shorten and replace the 'replicationcontroller' resource type with the alias 'rc'. kubectl get replicationcontroller <rc-name> # List all replication controllers and services together in plain-text output format. kubectl get rc,services # List all daemon sets in plain-text output format. kubectl get ds # List all pods running on node server01 kubectl get pods --field-selector=spec.nodeName=server01 kubectl describe - Display detailed state of one or more resources, including the uninitialized ones by default.# Display the details of the node with name <node-name>. kubectl describe nodes <node-name> # Display the details of the pod with name <pod-name>. kubectl describe pods/<pod-name> # Display the details of all the pods that are managed by the replication controller named <rc-name>. # Remember: Any pods that are created by the replication controller get prefixed with the name of the replication controller. kubectl describe pods <rc-name> # Describe all pods kubectl describe pods Note:The kubectl get command is usually used for retrieving one or more resources of the same resource type. It features a rich set of flags that allows you to customize the output format using the -o or --output flag, for example. You can specify the -w or --watch flag to start watching updates to a particular object. The kubectl describe command is more focused on describing the many related aspects of a specified resource. It may invoke several API calls to the API server to build a view for the user. For example, the kubectl describe node command retrieves not only the information about the node, but also a summary of the pods running on it, the events generated for the node etc.kubectl delete - Delete resources either from a file, stdin, or specifying label selectors, names, resource selectors, or resources.# Delete a pod using the type and name specified in the pod.yaml file. kubectl delete -f pod.yaml # Delete all the pods and services that have the label '<label-key>=<label-value>'. kubectl delete pods,services -l <label-key>=<label-value> # Delete all pods, including uninitialized ones. kubectl delete pods --all kubectl exec - Execute a command against a container in a pod.# Get output from running 'date' from pod <pod-name>. By default, output is from the first container. kubectl exec <pod-name> -- date # Get output from running 'date' in container <container-name> of pod <pod-name>. kubectl exec <pod-name> -c <container-name> -- date # Get an interactive TTY and run /bin/bash from pod <pod-name>. By default, output is from the first container. kubectl exec -ti <pod-name> -- /bin/bash kubectl logs - Print the logs for a container in a pod.# Return a snapshot of the logs from pod <pod-name>. kubectl logs <pod-name> # Start streaming the logs from pod <pod-name>. This is similar to the 'tail -f' Linux command. kubectl logs -f <pod-name> kubectl diff - View a diff of the proposed updates to a cluster.# Diff resources included in "pod.json". kubectl diff -f pod.json # Diff file read from stdin. cat service.yaml | kubectl diff -f - Examples: Creating and using pluginsUse the following set of examples to help you familiarize yourself with writing and using kubectl plugins:# create a simple plugin in any language and name the resulting executable file # so that it begins with the prefix "kubectl-" cat ./kubectl-hello #!/bin/sh # this plugin prints the words "hello world" echo "hello world" With a plugin written, let's make it executable:chmod a+x ./kubectl-hello # and move it to a location in our PATH sudo mv ./kubectl-hello /usr/local/bin sudo chown root:root /usr/local/bin # You have now created and "installed" a kubectl plugin. # You can begin using this plugin by invoking it from kubectl as if it were a regular command kubectl hello hello world # You can "uninstall" a plugin, by removing it from the folder in your # $PATH where you placed it sudo rm /usr/local/bin/kubectl-hello In order to view all of the plugins that are available to kubectl, use the kubectl plugin list subcommand:kubectl plugin list The output is similar to:The following kubectl-compatible plugins are available: /usr/local/bin/kubectl-hello /usr/local/bin/kubectl-foo /usr/local/bin/kubectl-bar kubectl plugin list also warns you about plugins that are not executable, or that are shadowed by other plugins; for example:sudo chmod -x /usr/local/bin/kubectl-foo # remove execute permission kubectl plugin list The following kubectl-compatible plugins are available: /usr/local/bin/kubectl-hello /usr/local/bin/kubectl-foo - warning: /usr/local/bin/kubectl-foo identified as a plugin, but it is not executable /usr/local/bin/kubectl-bar error: one plugin warning was found You can think of plugins as a means to build more complex functionality on top of the existing kubectl commands:cat ./kubectl-whoami The next few examples assume that you already made kubectl-whoami have the following contents:#!/bin/bash # this plugin makes use of the `kubectl config` command in order to output # information about the current user, based on the currently selected context kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ printf "%s\n" .context.user }}{{ end }}{{ end }}' Running the above command gives you an output containing the user for the current context in your KUBECONFIG file:# make the file executable sudo chmod +x ./kubectl-whoami # and move it into your PATH sudo mv ./kubectl-whoami /usr/local/bin kubectl whoami Current user: plugins-user What's nextRead the kubectl reference documentation:the kubectl command referencethe command line arguments referenceLearn about kubectl usage conventionsRead about JSONPath support in kubectlRead about how to extend kubectl with pluginsTo find out more about plugins, take a look at the example CLI plugin.


# StorageVersionMigration v1alpha1

StorageVersionMigration v1alpha1StorageVersionMigration represents a migration of stored data to the latest storage version.apiVersion: storagemigration.k8s.io/v1alpha1import "k8s.io/api/storagemigration/v1alpha1"StorageVersionMigrationStorageVersionMigration represents a migration of stored data to the latest storage version.apiVersion: storagemigration.k8s.io/v1alpha1kind: StorageVersionMigrationmetadata (ObjectMeta)Standard object metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadataspec (StorageVersionMigrationSpec)Specification of the migration.status (StorageVersionMigrationStatus)Status of the migration.StorageVersionMigrationSpecSpec of the storage version migration.continueToken (string)The token used in the list options to get the next chunk of objects to migrate. When the .status.conditions indicates the migration is "Running", users can use this token to check the progress of the migration.resource (GroupVersionResource), requiredThe resource that is being migrated. The migrator sends requests to the endpoint serving the resource. Immutable.The names of the group, the version, and the resource.resource.group (string)The name of the group.resource.resource (string)The name of the resource.resource.version (string)The name of the version.StorageVersionMigrationStatusStatus of the storage version migration.conditions ([]MigrationCondition)Patch strategy: merge on key typeMap: unique values on key type will be kept during a mergeThe latest available observations of the migration's current state.Describes the state of a migration at a certain point.conditions.status (string), requiredStatus of the condition, one of True, False, Unknown.conditions.type (string), requiredType of the condition.conditions.lastUpdateTime (Time)The last time this condition was updated.Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.conditions.message (string)A human readable message indicating details about the transition.conditions.reason (string)The reason for the condition's last transition.resourceVersion (string)ResourceVersion to compare with the GC cache for performing the migration. This is the current resource version of given group, version and resource when kube-controller-manager first observes this StorageVersionMigration resource.StorageVersionMigrationListStorageVersionMigrationList is a collection of storage version migrations.apiVersion: storagemigration.k8s.io/v1alpha1kind: StorageVersionMigrationListmetadata (ListMeta)Standard list metadata More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadataitems ([]StorageVersionMigration), requiredPatch strategy: merge on key typeMap: unique values on key type will be kept during a mergeItems is the list of StorageVersionMigrationOperationsget read the specified StorageVersionMigrationHTTP RequestGET /apis/storagemigration.k8s.io/v1alpha1/storageversionmigrations/{name}Parametersname (in path): string, requiredname of the StorageVersionMigrationpretty (in query): stringprettyResponse200 (StorageVersionMigration): OK401: Unauthorizedget read status of the specified StorageVersionMigrationHTTP RequestGET /apis/storagemigration.k8s.io/v1alpha1/storageversionmigrations/{name}/statusParametersname (in path): string, requiredname of the StorageVersionMigrationpretty (in query): stringprettyResponse200 (StorageVersionMigration): OK401: Unauthorizedlist list or watch objects of kind StorageVersionMigrationHTTP RequestGET /apis/storagemigration.k8s.io/v1alpha1/storageversionmigrationsParametersallowWatchBookmarks (in query): booleanallowWatchBookmarkscontinue (in query): stringcontinuefieldSelector (in query): stringfieldSelectorlabelSelector (in query): stringlabelSelectorlimit (in query): integerlimitpretty (in query): stringprettyresourceVersion (in query): stringresourceVersionresourceVersionMatch (in query): stringresourceVersionMatchsendInitialEvents (in query): booleansendInitialEventstimeoutSeconds (in query): integertimeoutSecondswatch (in query): booleanwatchResponse200 (StorageVersionMigrationList): OK401: Unauthorizedcreate create a StorageVersionMigrationHTTP RequestPOST /apis/storagemigration.k8s.io/v1alpha1/storageversionmigrationsParametersbody: StorageVersionMigration, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationpretty (in query): stringprettyResponse200 (StorageVersionMigration): OK201 (StorageVersionMigration): Created202 (StorageVersionMigration): Accepted401: Unauthorizedupdate replace the specified StorageVersionMigrationHTTP RequestPUT /apis/storagemigration.k8s.io/v1alpha1/storageversionmigrations/{name}Parametersname (in path): string, requiredname of the StorageVersionMigrationbody: StorageVersionMigration, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationpretty (in query): stringprettyResponse200 (StorageVersionMigration): OK201 (StorageVersionMigration): Created401: Unauthorizedupdate replace status of the specified StorageVersionMigrationHTTP RequestPUT /apis/storagemigration.k8s.io/v1alpha1/storageversionmigrations/{name}/statusParametersname (in path): string, requiredname of the StorageVersionMigrationbody: StorageVersionMigration, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationpretty (in query): stringprettyResponse200 (StorageVersionMigration): OK201 (StorageVersionMigration): Created401: Unauthorizedpatch partially update the specified StorageVersionMigrationHTTP RequestPATCH /apis/storagemigration.k8s.io/v1alpha1/storageversionmigrations/{name}Parametersname (in path): string, requiredname of the StorageVersionMigrationbody: Patch, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationforce (in query): booleanforcepretty (in query): stringprettyResponse200 (StorageVersionMigration): OK201 (StorageVersionMigration): Created401: Unauthorizedpatch partially update status of the specified StorageVersionMigrationHTTP RequestPATCH /apis/storagemigration.k8s.io/v1alpha1/storageversionmigrations/{name}/statusParametersname (in path): string, requiredname of the StorageVersionMigrationbody: Patch, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationforce (in query): booleanforcepretty (in query): stringprettyResponse200 (StorageVersionMigration): OK201 (StorageVersionMigration): Created401: Unauthorizeddelete delete a StorageVersionMigrationHTTP RequestDELETE /apis/storagemigration.k8s.io/v1alpha1/storageversionmigrations/{name}Parametersname (in path): string, requiredname of the StorageVersionMigrationbody: DeleteOptionsdryRun (in query): stringdryRungracePeriodSeconds (in query): integergracePeriodSecondsignoreStoreReadErrorWithClusterBreakingPotential (in query): booleanignoreStoreReadErrorWithClusterBreakingPotentialpretty (in query): stringprettypropagationPolicy (in query): stringpropagationPolicyResponse200 (Status): OK202 (Status): Accepted401: Unauthorizeddeletecollection delete collection of StorageVersionMigrationHTTP RequestDELETE /apis/storagemigration.k8s.io/v1alpha1/storageversionmigrationsParametersbody: DeleteOptionscontinue (in query): stringcontinuedryRun (in query): stringdryRunfieldSelector (in query): stringfieldSelectorgracePeriodSeconds (in query): integergracePeriodSecondsignoreStoreReadErrorWithClusterBreakingPotential (in query): booleanignoreStoreReadErrorWithClusterBreakingPotentiallabelSelector (in query): stringlabelSelectorlimit (in query): integerlimitpretty (in query): stringprettypropagationPolicy (in query): stringpropagationPolicyresourceVersion (in query): stringresourceVersionresourceVersionMatch (in query): stringresourceVersionMatchsendInitialEvents (in query): booleansendInitialEventstimeoutSeconds (in query): integertimeoutSecondsResponse200 (Status): OK401: UnauthorizedThis page is automatically generated.If you plan to report an issue with this page, mention that the page is auto-generated in your issue description. The fix may need to happen elsewhere in the Kubernetes project.