kube-apiserverSynopsisThe Kubernetes API server validates and configures data for the api objects which include pods, services, replicationcontrollers, and others. The API Server services REST operations and provides the frontend to the cluster's shared state through which all other components interact.kube-apiserver [flags] Options--admission-control-config-file stringFile with admission control configuration.--advertise-address stringThe IP address on which to advertise the apiserver to members of the cluster. This address must be reachable by the rest of the cluster. If blank, the --bind-address will be used. If --bind-address is unspecified, the host's default interface will be used.--aggregator-reject-forwarding-redirect Default: trueAggregator reject forwarding redirect response back to client.--allow-metric-labels stringToString Default: []The map from metric-label to value allow-list of this label. The key's format is <MetricName>,<LabelName>. The value's format is <allowed_value>,<allowed_value>...e.g. metric1,label1='v1,v2,v3', metric1,label2='v1,v2,v3' metric2,label1='v1,v2,v3'.--allow-metric-labels-manifest stringThe path to the manifest file that contains the allow-list mapping. The format of the file is the same as the flag --allow-metric-labels. Note that the flag --allow-metric-labels will override the manifest file.--allow-privilegedIf true, allow privileged containers. [default=false]--anonymous-auth Default: trueEnables anonymous requests to the secure port of the API server. Requests that are not rejected by another authentication method are treated as anonymous requests. Anonymous requests have a username of system:anonymous, and a group name of system:unauthenticated.--api-audiences stringsIdentifiers of the API. The service account token authenticator will validate that tokens used against the API are bound to at least one of these audiences. If the --service-account-issuer flag is configured and this flag is not, this field defaults to a single element list containing the issuer URL.--audit-log-batch-buffer-size int Default: 10000The size of the buffer to store events before batching and writing. Only used in batch mode.--audit-log-batch-max-size int Default: 1The maximum size of a batch. Only used in batch mode.--audit-log-batch-max-wait durationThe amount of time to wait before force writing the batch that hadn't reached the max size. Only used in batch mode.--audit-log-batch-throttle-burst intMaximum number of requests sent at the same moment if ThrottleQPS was not utilized before. Only used in batch mode.--audit-log-batch-throttle-enableWhether batching throttling is enabled. Only used in batch mode.--audit-log-batch-throttle-qps floatMaximum average number of batches per second. Only used in batch mode.--audit-log-compressIf set, the rotated log files will be compressed using gzip.--audit-log-format string Default: "json"Format of saved audits. "legacy" indicates 1-line text format for each event. "json" indicates structured json format. Known formats are legacy,json.--audit-log-maxage intThe maximum number of days to retain old audit log files based on the timestamp encoded in their filename.--audit-log-maxbackup intThe maximum number of old audit log files to retain. Setting a value of 0 will mean there's no restriction on the number of files.--audit-log-maxsize intThe maximum size in megabytes of the audit log file before it gets rotated.--audit-log-mode string Default: "blocking"Strategy for sending audit events. Blocking indicates sending events should block server responses. Batch causes the backend to buffer and write events asynchronously. Known modes are batch,blocking,blocking-strict.--audit-log-path stringIf set, all requests coming to the apiserver will be logged to this file. '-' means standard out.--audit-log-truncate-enabledWhether event and batch truncating is enabled.--audit-log-truncate-max-batch-size int Default: 10485760Maximum size of the batch sent to the underlying backend. Actual serialized size can be several hundreds of bytes greater. If a batch exceeds this limit, it is split into several batches of smaller size.--audit-log-truncate-max-event-size int Default: 102400Maximum size of the audit event sent to the underlying backend. If the size of an event is greater than this number, first request and response are removed, and if this doesn't reduce the size enough, event is discarded.--audit-log-version string Default: "audit.k8s.io/v1"API group and version used for serializing audit events written to log.--audit-policy-file stringPath to the file that defines the audit policy configuration.--audit-webhook-batch-buffer-size int Default: 10000The size of the buffer to store events before batching and writing. Only used in batch mode.--audit-webhook-batch-max-size int Default: 400The maximum size of a batch. Only used in batch mode.--audit-webhook-batch-max-wait duration Default: 30sThe amount of time to wait before force writing the batch that hadn't reached the max size. Only used in batch mode.--audit-webhook-batch-throttle-burst int Default: 15Maximum number of requests sent at the same moment if ThrottleQPS was not utilized before. Only used in batch mode.--audit-webhook-batch-throttle-enable Default: trueWhether batching throttling is enabled. Only used in batch mode.--audit-webhook-batch-throttle-qps float Default: 10Maximum average number of batches per second. Only used in batch mode.--audit-webhook-config-file stringPath to a kubeconfig formatted file that defines the audit webhook configuration.--audit-webhook-initial-backoff duration Default: 10sThe amount of time to wait before retrying the first failed request.--audit-webhook-mode string Default: "batch"Strategy for sending audit events. Blocking indicates sending events should block server responses. Batch causes the backend to buffer and write events asynchronously. Known modes are batch,blocking,blocking-strict.--audit-webhook-truncate-enabledWhether event and batch truncating is enabled.--audit-webhook-truncate-max-batch-size int Default: 10485760Maximum size of the batch sent to the underlying backend. Actual serialized size can be several hundreds of bytes greater. If a batch exceeds this limit, it is split into several batches of smaller size.--audit-webhook-truncate-max-event-size int Default: 102400Maximum size of the audit event sent to the underlying backend. If the size of an event is greater than this number, first request and response are removed, and if this doesn't reduce the size enough, event is discarded.--audit-webhook-version string Default: "audit.k8s.io/v1"API group and version used for serializing audit events written to webhook.--authentication-config stringFile with Authentication Configuration to configure the JWT Token authenticator or the anonymous authenticator. Requires the StructuredAuthenticationConfiguration feature gate. Also requires the feature gate AnonymousAuthConfigurableEndpoints to configure the anonymous authenticator in the config file. This flag is mutually exclusive with the --oidc-* flags if the file configures the JWT Token authenticator. This flag is mutually exclusive with --anonymous-auth if the file configures the Anonymous authenticator.--authentication-token-webhook-cache-ttl duration Default: 2m0sThe duration to cache responses from the webhook token authenticator.--authentication-token-webhook-config-file stringFile with webhook configuration for token authentication in kubeconfig format. The API server will query the remote service to determine authentication for bearer tokens.--authentication-token-webhook-version string Default: "v1beta1"The API version of the authentication.k8s.io TokenReview to send to and expect from the webhook.--authorization-config stringFile with Authorization Configuration to configure the authorizer chain. Requires feature gate StructuredAuthorizationConfiguration. This flag is mutually exclusive with the other --authorization-mode and --authorization-webhook-* flags.--authorization-mode stringsOrdered list of plug-ins to do authorization on secure port. Defaults to AlwaysAllow if --authorization-config is not used. Comma-delimited list of: AlwaysAllow,AlwaysDeny,ABAC,Webhook,RBAC,Node.--authorization-policy-file stringFile with authorization policy in json line by line format, used with --authorization-mode=ABAC, on the secure port.--authorization-webhook-cache-authorized-ttl duration Default: 5m0sThe duration to cache 'authorized' responses from the webhook authorizer.--authorization-webhook-cache-unauthorized-ttl duration Default: 30sThe duration to cache 'unauthorized' responses from the webhook authorizer.--authorization-webhook-config-file stringFile with webhook configuration in kubeconfig format, used with --authorization-mode=Webhook. The API server will query the remote service to determine access on the API server's secure port.--authorization-webhook-version string Default: "v1beta1"The API version of the authorization.k8s.io SubjectAccessReview to send to and expect from the webhook.--bind-address string Default: 0.0.0.0The IP address on which to listen for the --secure-port port. The associated interface(s) must be reachable by the rest of the cluster, and by CLI/web clients. If blank or an unspecified address (0.0.0.0 or ::), all interfaces and IP address families will be used.--cert-dir string Default: "/var/run/kubernetes"The directory where the TLS certs are located. If --tls-cert-file and --tls-private-key-file are provided, this flag will be ignored.--client-ca-file stringIf set, any request presenting a client certificate signed by one of the authorities in the client-ca-file is authenticated with an identity corresponding to the CommonName of the client certificate.--contention-profilingEnable block profiling, if profiling is enabled--cors-allowed-origins stringsList of allowed origins for CORS, comma separated. An allowed origin can be a regular expression to support subdomain matching. If this list is empty CORS will not be enabled. Please ensure each expression matches the entire hostname by anchoring to the start with '^' or including the '//' prefix, and by anchoring to the end with '$' or including the ':' port separator suffix. Examples of valid expressions are '//example.com(:|$)' and '^https://example.com(:|$)'--debug-socket-path stringUse an unprotected (no authn/authz) unix-domain socket for profiling with the given path--default-not-ready-toleration-seconds int Default: 300Indicates the tolerationSeconds of the toleration for notReady:NoExecute that is added by default to every pod that does not already have such a toleration.--default-unreachable-toleration-seconds int Default: 300Indicates the tolerationSeconds of the toleration for unreachable:NoExecute that is added by default to every pod that does not already have such a toleration.--delete-collection-workers int Default: 1Number of workers spawned for DeleteCollection call. These are used to speed up namespace cleanup.--disable-admission-plugins stringsadmission plugins that should be disabled although they are in the default enabled plugins list (NamespaceLifecycle, LimitRanger, ServiceAccount, TaintNodesByCondition, PodSecurity, Priority, DefaultTolerationSeconds, DefaultStorageClass, StorageObjectInUseProtection, PersistentVolumeClaimResize, RuntimeClass, CertificateApproval, CertificateSigning, ClusterTrustBundleAttest, CertificateSubjectRestriction, DefaultIngressClass, PodTopologyLabels, MutatingAdmissionPolicy, MutatingAdmissionWebhook, ValidatingAdmissionPolicy, ValidatingAdmissionWebhook, ResourceQuota). Comma-delimited list of admission plugins: AlwaysAdmit, AlwaysDeny, AlwaysPullImages, CertificateApproval, CertificateSigning, CertificateSubjectRestriction, ClusterTrustBundleAttest, DefaultIngressClass, DefaultStorageClass, DefaultTolerationSeconds, DenyServiceExternalIPs, EventRateLimit, ExtendedResourceToleration, ImagePolicyWebhook, LimitPodHardAntiAffinityTopology, LimitRanger, MutatingAdmissionPolicy, MutatingAdmissionWebhook, NamespaceAutoProvision, NamespaceExists, NamespaceLifecycle, NodeRestriction, OwnerReferencesPermissionEnforcement, PersistentVolumeClaimResize, PodNodeSelector, PodSecurity, PodTolerationRestriction, PodTopologyLabels, Priority, ResourceQuota, RuntimeClass, ServiceAccount, StorageObjectInUseProtection, TaintNodesByCondition, ValidatingAdmissionPolicy, ValidatingAdmissionWebhook. The order of plugins in this flag does not matter.--disable-http2-servingIf true, HTTP2 serving will be disabled [default=false]--disabled-metrics stringsThis flag provides an escape hatch for misbehaving metrics. You must provide the fully qualified metric name in order to disable it. Disclaimer: disabling metrics is higher in precedence than showing hidden metrics.--egress-selector-config-file stringFile with apiserver egress selector configuration.--emulated-version stringsThe versions different components emulate their capabilities (APIs, features, ...) of.If set, the component will emulate the behavior of this version instead of the underlying binary version.Version format could only be major.minor, for example: '--emulated-version=wardle=1.2,kube=1.31'.Options are: kube=1.31..1.33(default:1.33)If the component is not specified, defaults to "kube"--emulation-forward-compatibleIf true, for any beta+ APIs enabled by default or by --runtime-config at the emulation version, their future versions with higher priority/stability will be auto enabled even if they introduced after the emulation version. Can only be set to true if the emulation version is lower than the binary version.--enable-admission-plugins stringsadmission plugins that should be enabled in addition to default enabled ones (NamespaceLifecycle, LimitRanger, ServiceAccount, TaintNodesByCondition, PodSecurity, Priority, DefaultTolerationSeconds, DefaultStorageClass, StorageObjectInUseProtection, PersistentVolumeClaimResize, RuntimeClass, CertificateApproval, CertificateSigning, ClusterTrustBundleAttest, CertificateSubjectRestriction, DefaultIngressClass, PodTopologyLabels, MutatingAdmissionPolicy, MutatingAdmissionWebhook, ValidatingAdmissionPolicy, ValidatingAdmissionWebhook, ResourceQuota). Comma-delimited list of admission plugins: AlwaysAdmit, AlwaysDeny, AlwaysPullImages, CertificateApproval, CertificateSigning, CertificateSubjectRestriction, ClusterTrustBundleAttest, DefaultIngressClass, DefaultStorageClass, DefaultTolerationSeconds, DenyServiceExternalIPs, EventRateLimit, ExtendedResourceToleration, ImagePolicyWebhook, LimitPodHardAntiAffinityTopology, LimitRanger, MutatingAdmissionPolicy, MutatingAdmissionWebhook, NamespaceAutoProvision, NamespaceExists, NamespaceLifecycle, NodeRestriction, OwnerReferencesPermissionEnforcement, PersistentVolumeClaimResize, PodNodeSelector, PodSecurity, PodTolerationRestriction, PodTopologyLabels, Priority, ResourceQuota, RuntimeClass, ServiceAccount, StorageObjectInUseProtection, TaintNodesByCondition, ValidatingAdmissionPolicy, ValidatingAdmissionWebhook. The order of plugins in this flag does not matter.--enable-aggregator-routingTurns on aggregator routing requests to endpoints IP rather than cluster IP.--enable-bootstrap-token-authEnable to allow secrets of type 'bootstrap.kubernetes.io/token' in the 'kube-system' namespace to be used for TLS bootstrapping authentication.--enable-garbage-collector Default: trueEnables the generic garbage collector. MUST be synced with the corresponding flag of the kube-controller-manager.--enable-priority-and-fairness Default: trueIf true, replace the max-in-flight handler with an enhanced one that queues and dispatches with priority and fairness--encryption-provider-config stringThe file containing configuration for encryption providers to be used for storing secrets in etcd--encryption-provider-config-automatic-reloadDetermines if the file set by --encryption-provider-config should be automatically reloaded if the disk contents change. Setting this to true disables the ability to uniquely identify distinct KMS plugins via the API server healthz endpoints.--endpoint-reconciler-type string Default: "lease"Use an endpoint reconciler (master-count, lease, none) master-count is deprecated, and will be removed in a future version.--etcd-cafile stringSSL Certificate Authority file used to secure etcd communication.--etcd-certfile stringSSL certification file used to secure etcd communication.--etcd-compaction-interval duration Default: 5m0sThe interval of compaction requests. If 0, the compaction request from apiserver is disabled.--etcd-count-metric-poll-period duration Default: 1m0sFrequency of polling etcd for number of resources per type. 0 disables the metric collection.--etcd-db-metric-poll-interval duration Default: 30sThe interval of requests to poll etcd and update metric. 0 disables the metric collection--etcd-healthcheck-timeout duration Default: 2sThe timeout to use when checking etcd health.--etcd-keyfile stringSSL key file used to secure etcd communication.--etcd-prefix string Default: "/registry"The prefix to prepend to all resource paths in etcd.--etcd-readycheck-timeout duration Default: 2sThe timeout to use when checking etcd readiness--etcd-servers stringsList of etcd servers to connect with (scheme://ip:port), comma separated.--etcd-servers-overrides stringsPer-resource etcd servers overrides, comma separated. The individual override format: group/resource#servers, where servers are URLs, semicolon separated. Note that this applies only to resources compiled into this server binary.--event-ttl duration Default: 1h0m0sAmount of time to retain events.--external-hostname stringThe hostname to use when generating externalized URLs for this master (e.g. Swagger API Docs or OpenID Discovery).--feature-gates colonSeparatedMultimapStringStringComma-separated list of component:key=value pairs that describe feature gates for alpha/experimental features of different components.If the component is not specified, defaults to "kube". This flag can be repeatedly invoked. For example: --feature-gates 'wardle:featureA=true,wardle:featureB=false' --feature-gates 'kube:featureC=true'Options are:kube:APIResponseCompression=true|false (BETA - default=true)kube:APIServerIdentity=true|false (BETA - default=true)kube:APIServerTracing=true|false (BETA - default=true)kube:APIServingWithRoutine=true|false (ALPHA - default=false)kube:AllAlpha=true|false (ALPHA - default=false)kube:AllBeta=true|false (BETA - default=false)kube:AllowParsingUserUIDFromCertAuth=true|false (BETA - default=true)kube:AllowUnsafeMalformedObjectDeletion=true|false (ALPHA - default=false)kube:AnonymousAuthConfigurableEndpoints=true|false (BETA - default=true)kube:AuthorizeNodeWithSelectors=true|false (BETA - default=true)kube:AuthorizeWithSelectors=true|false (BETA - default=true)kube:CBORServingAndStorage=true|false (ALPHA - default=false)kube:CPUManagerPolicyAlphaOptions=true|false (ALPHA - default=false)kube:CPUManagerPolicyBetaOptions=true|false (BETA - default=true)kube:CSIVolumeHealth=true|false (ALPHA - default=false)kube:ClientsAllowCBOR=true|false (ALPHA - default=false)kube:ClientsPreferCBOR=true|false (ALPHA - default=false)kube:CloudControllerManagerWebhook=true|false (ALPHA - default=false)kube:ClusterTrustBundle=true|false (BETA - default=false)kube:ClusterTrustBundleProjection=true|false (BETA - default=false)kube:ComponentFlagz=true|false (ALPHA - default=false)kube:ComponentStatusz=true|false (ALPHA - default=false)kube:ConcurrentWatchObjectDecode=true|false (BETA - default=false)kube:ConsistentListFromCache=true|false (BETA - default=true)kube:ContainerCheckpoint=true|false (BETA - default=true)kube:ContainerStopSignals=true|false (ALPHA - default=false)kube:ContextualLogging=true|false (BETA - default=true)kube:CoordinatedLeaderElection=true|false (BETA - default=false)kube:CrossNamespaceVolumeDataSource=true|false (ALPHA - default=false)kube:CustomCPUCFSQuotaPeriod=true|false (ALPHA - default=false)kube:DRAAdminAccess=true|false (ALPHA - default=false)kube:DRADeviceTaints=true|false (ALPHA - default=false)kube:DRAPartitionableDevices=true|false (ALPHA - default=false)kube:DRAPrioritizedList=true|false (ALPHA - default=false)kube:DRAResourceClaimDeviceStatus=true|false (BETA - default=true)kube:DeclarativeValidation=true|false (BETA - default=true)kube:DeclarativeValidationTakeover=true|false (BETA - default=false)kube:DeploymentReplicaSetTerminatingReplicas=true|false (ALPHA - default=false)kube:DisableAllocatorDualWrite=true|false (BETA - default=false)kube:DisableCPUQuotaWithExclusiveCPUs=true|false (BETA - default=true)kube:DynamicResourceAllocation=true|false (BETA - default=false)kube:EventedPLEG=true|false (ALPHA - default=false)kube:ExternalServiceAccountTokenSigner=true|false (ALPHA - default=false)kube:GracefulNodeShutdown=true|false (BETA - default=true)kube:GracefulNodeShutdownBasedOnPodPriority=true|false (BETA - default=true)kube:HPAConfigurableTolerance=true|false (ALPHA - default=false)kube:HPAScaleToZero=true|false (ALPHA - default=false)kube:ImageMaximumGCAge=true|false (BETA - default=true)kube:ImageVolume=true|false (BETA - default=false)kube:InOrderInformers=true|false (BETA - default=true)kube:InPlacePodVerticalScaling=true|false (BETA - default=true)kube:InPlacePodVerticalScalingExclusiveCPUs=true|false (ALPHA - default=false)kube:InTreePluginPortworxUnregister=true|false (ALPHA - default=false)kube:InformerResourceVersion=true|false (ALPHA - default=false)kube:JobManagedBy=true|false (BETA - default=true)kube:JobPodReplacementPolicy=true|false (BETA - default=true)kube:KubeletCgroupDriverFromCRI=true|false (BETA - default=true)kube:KubeletCrashLoopBackOffMax=true|false (ALPHA - default=false)kube:KubeletEnsureSecretPulledImages=true|false (ALPHA - default=false)kube:KubeletFineGrainedAuthz=true|false (BETA - default=true)kube:KubeletInUserNamespace=true|false (ALPHA - default=false)kube:KubeletPSI=true|false (ALPHA - default=false)kube:KubeletPodResourcesDynamicResources=true|false (ALPHA - default=false)kube:KubeletPodResourcesGet=true|false (ALPHA - default=false)kube:KubeletSeparateDiskGC=true|false (BETA - default=true)kube:KubeletServiceAccountTokenForCredentialProviders=true|false (ALPHA - default=false)kube:KubeletTracing=true|false (BETA - default=true)kube:ListFromCacheSnapshot=true|false (ALPHA - default=false)kube:LocalStorageCapacityIsolationFSQuotaMonitoring=true|false (BETA - default=false)kube:LoggingAlphaOptions=true|false (ALPHA - default=false)kube:LoggingBetaOptions=true|false (BETA - default=true)kube:MatchLabelKeysInPodTopologySpread=true|false (BETA - default=true)kube:MaxUnavailableStatefulSet=true|false (ALPHA - default=false)kube:MemoryQoS=true|false (ALPHA - default=false)kube:MutableCSINodeAllocatableCount=true|false (ALPHA - default=false)kube:MutatingAdmissionPolicy=true|false (ALPHA - default=false)kube:NodeLogQuery=true|false (BETA - default=false)kube:NodeSwap=true|false (BETA - default=true)kube:OpenAPIEnums=true|false (BETA - default=true)kube:OrderedNamespaceDeletion=true|false (BETA - default=true)kube:PodAndContainerStatsFromCRI=true|false (ALPHA - default=false)kube:PodDeletionCost=true|false (BETA - default=true)kube:PodLevelResources=true|false (ALPHA - default=false)kube:PodLifecycleSleepAction=true|false (BETA - default=true)kube:PodLifecycleSleepActionAllowZero=true|false (BETA - default=true)kube:PodLogsQuerySplitStreams=true|false (ALPHA - default=false)kube:PodObservedGenerationTracking=true|false (ALPHA - default=false)kube:PodReadyToStartContainersCondition=true|false (BETA - default=true)kube:PodTopologyLabelsAdmission=true|false (ALPHA - default=false)kube:PortForwardWebsockets=true|false (BETA - default=true)kube:PreferSameTrafficDistribution=true|false (ALPHA - default=false)kube:ProcMountType=true|false (BETA - default=true)kube:QOSReserved=true|false (ALPHA - default=false)kube:RecoverVolumeExpansionFailure=true|false (BETA - default=true)kube:ReduceDefaultCrashLoopBackOffDecay=true|false (ALPHA - default=false)kube:RelaxedDNSSearchValidation=true|false (BETA - default=true)kube:RelaxedEnvironmentVariableValidation=true|false (BETA - default=true)kube:ReloadKubeletServerCertificateFile=true|false (BETA - default=true)kube:RemoteRequestHeaderUID=true|false (BETA - default=true)kube:ResilientWatchCacheInitialization=true|false (BETA - default=true)kube:ResourceHealthStatus=true|false (ALPHA - default=false)kube:RotateKubeletServerCertificate=true|false (BETA - default=true)kube:RuntimeClassInImageCriApi=true|false (ALPHA - default=false)kube:SELinuxChangePolicy=true|false (BETA - default=true)kube:SELinuxMount=true|false (BETA - default=false)kube:SELinuxMountReadWriteOncePod=true|false (BETA - default=true)kube:SchedulerAsyncPreemption=true|false (BETA - default=true)kube:SchedulerPopFromBackoffQ=true|false (BETA - default=true)kube:SchedulerQueueingHints=true|false (BETA - default=true)kube:SeparateTaintEvictionController=true|false (BETA - default=true)kube:ServiceAccountNodeAudienceRestriction=true|false (BETA - default=true)kube:StorageCapacityScoring=true|false (ALPHA - default=false)kube:StorageVersionAPI=true|false (ALPHA - default=false)kube:StorageVersionHash=true|false (BETA - default=true)kube:StorageVersionMigrator=true|false (ALPHA - default=false)kube:StreamingCollectionEncodingToJSON=true|false (BETA - default=true)kube:StreamingCollectionEncodingToProtobuf=true|false (BETA - default=true)kube:StrictIPCIDRValidation=true|false (ALPHA - default=false)kube:StructuredAuthenticationConfiguration=true|false (BETA - default=true)kube:SupplementalGroupsPolicy=true|false (BETA - default=true)kube:SystemdWatchdog=true|false (BETA - default=true)kube:TopologyManagerPolicyAlphaOptions=true|false (ALPHA - default=false)kube:TopologyManagerPolicyBetaOptions=true|false (BETA - default=true)kube:TranslateStreamCloseWebsocketRequests=true|false (BETA - default=true)kube:UnauthenticatedHTTP2DOSMitigation=true|false (BETA - default=true)kube:UnknownVersionInteroperabilityProxy=true|false (ALPHA - default=false)kube:UserNamespacesPodSecurityStandards=true|false (ALPHA - default=false)kube:UserNamespacesSupport=true|false (BETA - default=true)kube:VolumeAttributesClass=true|false (BETA - default=false)kube:WatchCacheInitializationPostStartHook=true|false (BETA - default=false)kube:WatchList=true|false (BETA - default=false)kube:WatchListClient=true|false (BETA - default=false)kube:WinDSR=true|false (BETA - default=true)kube:WinOverlay=true|false (BETA - default=true)kube:WindowsCPUAndMemoryAffinity=true|false (ALPHA - default=false)kube:WindowsGracefulNodeShutdown=true|false (ALPHA - default=false)--goaway-chance floatTo prevent HTTP/2 clients from getting stuck on a single apiserver, randomly close a connection (GOAWAY). The client's other in-flight requests won't be affected, and the client will reconnect, likely landing on a different apiserver after going through the load balancer again. This argument sets the fraction of requests that will be sent a GOAWAY. Clusters with single apiservers, or which don't use a load balancer, should NOT enable this. Min is 0 (off), Max is .02 (1/50 requests); .001 (1/1000) is a recommended starting point.-h, --helphelp for kube-apiserver--http2-max-streams-per-connection intThe limit that the server gives to clients for the maximum number of streams in an HTTP/2 connection. Zero means to use golang's default.--kubelet-certificate-authority stringPath to a cert file for the certificate authority.--kubelet-client-certificate stringPath to a client cert file for TLS.--kubelet-client-key stringPath to a client key file for TLS.--kubelet-preferred-address-types strings Default: "Hostname,InternalDNS,InternalIP,ExternalDNS,ExternalIP"List of the preferred NodeAddressTypes to use for kubelet connections.--kubelet-timeout duration Default: 5sTimeout for kubelet operations.--kubernetes-service-node-port intIf non-zero, the Kubernetes master service (which apiserver creates/maintains) will be of type NodePort, using this as the value of the port. If zero, the Kubernetes master service will be of type ClusterIP.--lease-reuse-duration-seconds int Default: 60The time in seconds that each lease is reused. A lower value could avoid large number of objects reusing the same lease. Notice that a too small value may cause performance problems at storage layer.--livez-grace-period durationThis option represents the maximum amount of time it should take for apiserver to complete its startup sequence and become live. From apiserver's start time to when this amount of time has elapsed, /livez will assume that unfinished post-start hooks will complete successfully and therefore return true.--log-flush-frequency duration Default: 5sMaximum number of seconds between log flushes--log-text-info-buffer-size quantity[Alpha] In text format with split output streams, the info messages can be buffered for a while to increase performance. The default value of zero bytes disables buffering. The size can be specified as number of bytes (512), multiples of 1000 (1K), multiples of 1024 (2Ki), or powers of those (3M, 4G, 5Mi, 6Gi). Enable the LoggingAlphaOptions feature gate to use this.--log-text-split-stream[Alpha] In text format, write error messages to stderr and info messages to stdout. The default is to write a single stream to stdout. Enable the LoggingAlphaOptions feature gate to use this.--logging-format string Default: "text"Sets the log format. Permitted formats: "text".--max-connection-bytes-per-sec intIf non-zero, throttle each user connection to this number of bytes/sec. Currently only applies to long-running requests.--max-mutating-requests-inflight int Default: 200This and --max-requests-inflight are summed to determine the server's total concurrency limit (which must be positive) if --enable-priority-and-fairness is true. Otherwise, this flag limits the maximum number of mutating requests in flight, or a zero value disables the limit completely.--max-requests-inflight int Default: 400This and --max-mutating-requests-inflight are summed to determine the server's total concurrency limit (which must be positive) if --enable-priority-and-fairness is true. Otherwise, this flag limits the maximum number of non-mutating requests in flight, or a zero value disables the limit completely.--min-request-timeout int Default: 1800An optional field indicating the minimum number of seconds a handler must keep a request open before timing it out. Currently only honored by the watch request handler, which picks a randomized value above this number as the connection timeout, to spread out load.--oidc-ca-file stringIf set, the OpenID server's certificate will be verified by one of the authorities in the oidc-ca-file, otherwise the host's root CA set will be used.--oidc-client-id stringThe client ID for the OpenID Connect client, must be set if oidc-issuer-url is set.--oidc-groups-claim stringIf provided, the name of a custom OpenID Connect claim for specifying user groups. The claim value is expected to be a string or array of strings. This flag is experimental, please see the authentication documentation for further details.--oidc-groups-prefix stringIf provided, all groups will be prefixed with this value to prevent conflicts with other authentication strategies.--oidc-issuer-url stringThe URL of the OpenID issuer, only HTTPS scheme will be accepted. If set, it will be used to verify the OIDC JSON Web Token (JWT).--oidc-required-claim <comma-separated 'key=value' pairs>A key=value pair that describes a required claim in the ID Token. If set, the claim is verified to be present in the ID Token with a matching value. Repeat this flag to specify multiple claims.--oidc-signing-algs strings Default: "RS256"Comma-separated list of allowed JOSE asymmetric signing algorithms. JWTs with a supported 'alg' header values are: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512. Values are defined by RFC 7518 https://tools.ietf.org/html/rfc7518#section-3.1.--oidc-username-claim string Default: "sub"The OpenID claim to use as the user name. Note that claims other than the default ('sub') is not guaranteed to be unique and immutable. This flag is experimental, please see the authentication documentation for further details.--oidc-username-prefix stringIf provided, all usernames will be prefixed with this value. If not provided, username claims other than 'email' are prefixed by the issuer URL to avoid clashes. To skip any prefixing, provide the value '-'.--peer-advertise-ip stringIf set and the UnknownVersionInteroperabilityProxy feature gate is enabled, this IP will be used by peer kube-apiservers to proxy requests to this kube-apiserver when the request cannot be handled by the peer due to version skew between the kube-apiservers. This flag is only used in clusters configured with multiple kube-apiservers for high availability.--peer-advertise-port stringIf set and the UnknownVersionInteroperabilityProxy feature gate is enabled, this port will be used by peer kube-apiservers to proxy requests to this kube-apiserver when the request cannot be handled by the peer due to version skew between the kube-apiservers. This flag is only used in clusters configured with multiple kube-apiservers for high availability.--peer-ca-file stringIf set and the UnknownVersionInteroperabilityProxy feature gate is enabled, this file will be used to verify serving certificates of peer kube-apiservers. This flag is only used in clusters configured with multiple kube-apiservers for high availability.--permit-address-sharingIf true, SO_REUSEADDR will be used when binding the port. This allows binding to wildcard IPs like 0.0.0.0 and specific IPs in parallel, and it avoids waiting for the kernel to release sockets in TIME_WAIT state. [default=false]--permit-port-sharingIf true, SO_REUSEPORT will be used when binding the port, which allows more than one instance to bind on the same address and port. [default=false]--profiling Default: trueEnable profiling via web interface host:port/debug/pprof/--proxy-client-cert-file stringClient certificate used to prove the identity of the aggregator or kube-apiserver when it must call out during a request. This includes proxying requests to a user api-server and calling out to webhook admission plugins. It is expected that this cert includes a signature from the CA in the --requestheader-client-ca-file flag. That CA is published in the 'extension-apiserver-authentication' configmap in the kube-system namespace. Components receiving calls from kube-aggregator should use that CA to perform their half of the mutual TLS verification.--proxy-client-key-file stringPrivate key for the client certificate used to prove the identity of the aggregator or kube-apiserver when it must call out during a request. This includes proxying requests to a user api-server and calling out to webhook admission plugins.--request-timeout duration Default: 1m0sAn optional field indicating the duration a handler must keep a request open before timing it out. This is the default request timeout for requests but may be overridden by flags such as --min-request-timeout for specific types of requests.--requestheader-allowed-names stringsList of client certificate common names to allow to provide usernames in headers specified by --requestheader-username-headers. If empty, any client certificate validated by the authorities in --requestheader-client-ca-file is allowed.--requestheader-client-ca-file stringRoot certificate bundle to use to verify client certificates on incoming requests before trusting usernames in headers specified by --requestheader-username-headers. WARNING: generally do not depend on authorization being already done for incoming requests.--requestheader-extra-headers-prefix stringsList of request header prefixes to inspect. X-Remote-Extra- is suggested.--requestheader-group-headers stringsList of request headers to inspect for groups. X-Remote-Group is suggested.--requestheader-uid-headers stringsList of request headers to inspect for UIDs. X-Remote-Uid is suggested. Requires the RemoteRequestHeaderUID feature to be enabled.--requestheader-username-headers stringsList of request headers to inspect for usernames. X-Remote-User is common.--runtime-config <comma-separated 'key=value' pairs>A set of key=value pairs that enable or disable built-in APIs. Supported options are:v1=true|false for the core API group<group>/<version>=true|false for a specific API group and version (e.g. apps/v1=true)api/all=true|false controls all API versionsapi/ga=true|false controls all API versions of the form v[0-9]+api/beta=true|false controls all API versions of the form v[0-9]+beta[0-9]+api/alpha=true|false controls all API versions of the form v[0-9]+alpha[0-9]+api/legacy is deprecated, and will be removed in a future version--runtime-config-emulation-forward-compatibleIf true, APIs identified by group/version that are enabled in the --runtime-config flag will be installed even if it is introduced after the emulation version. If false, server would fail to start if any APIs identified by group/version that are enabled in the --runtime-config flag are introduced after the emulation version. Can only be set to true if the emulation version is lower than the binary version.--secure-port int Default: 6443The port on which to serve HTTPS with authentication and authorization. It cannot be switched off with 0.--service-account-extend-token-expiration Default: trueTurns on projected service account expiration extension during token generation, which helps safe transition from legacy token to bound service account token feature. If this flag is enabled, admission injected tokens would be extended up to 1 year to prevent unexpected failure during transition, ignoring value of service-account-max-token-expiration.--service-account-issuer stringsIdentifier of the service account token issuer. The issuer will assert this identifier in "iss" claim of issued tokens. This value is a string or URI. If this option is not a valid URI per the OpenID Discovery 1.0 spec, the ServiceAccountIssuerDiscovery feature will remain disabled, even if the feature gate is set to true. It is highly recommended that this value comply with the OpenID spec: https://openid.net/specs/openid-connect-discovery-1_0.html. In practice, this means that service-account-issuer must be an https URL. It is also highly recommended that this URL be capable of serving OpenID discovery documents at {service-account-issuer}/.well-known/openid-configuration. When this flag is specified multiple times, the first is used to generate tokens and all are used to determine which issuers are accepted.--service-account-jwks-uri stringOverrides the URI for the JSON Web Key Set in the discovery doc served at /.well-known/openid-configuration. This flag is useful if the discovery docand key set are served to relying parties from a URL other than the API server's external (as auto-detected or overridden with external-hostname).--service-account-key-file stringsFile containing PEM-encoded x509 RSA or ECDSA private or public keys, used to verify ServiceAccount tokens. The specified file can contain multiple keys, and the flag can be specified multiple times with different files. If unspecified, --tls-private-key-file is used. Must be specified when --service-account-signing-key-file is provided--service-account-lookup Default: trueIf true, validate ServiceAccount tokens exist in etcd as part of authentication.--service-account-max-token-expiration durationThe maximum validity duration of a token created by the service account token issuer. If an otherwise valid TokenRequest with a validity duration larger than this value is requested, a token will be issued with a validity duration of this value.--service-account-signing-endpoint stringPath to socket where a external JWT signer is listening. This flag is mutually exclusive with --service-account-signing-key-file and --service-account-key-file. Requires enabling feature gate (ExternalServiceAccountTokenSigner)--service-account-signing-key-file stringPath to the file that contains the current private key of the service account token issuer. The issuer will sign issued ID tokens with this private key.--service-cluster-ip-range stringA CIDR notation IP range from which to assign service cluster IPs. This must not overlap with any IP ranges assigned to nodes or pods. Max of two dual-stack CIDRs is allowed.--service-node-port-range <a string in the form 'N1-N2'> Default: 30000-32767A port range to reserve for services with NodePort visibility. This must not overlap with the ephemeral port range on nodes. Example: '30000-32767'. Inclusive at both ends of the range.--show-hidden-metrics-for-version stringThe previous version for which you want to show hidden metrics. Only the previous minor version is meaningful, other values will not be allowed. The format is <major>.<minor>, e.g.: '1.16'. The purpose of this format is make sure you have the opportunity to notice if the next release hides additional metrics, rather than being surprised when they are permanently removed in the release after that.--shutdown-delay-duration durationTime to delay the termination. During that time the server keeps serving requests normally. The endpoints /healthz and /livez will return success, but /readyz immediately returns failure. Graceful termination starts after this delay has elapsed. This can be used to allow load balancer to stop sending traffic to this server.--shutdown-send-retry-afterIf true the HTTP Server will continue listening until all non long running request(s) in flight have been drained, during this window all incoming requests will be rejected with a status code 429 and a 'Retry-After' response header, in addition 'Connection: close' response header is set in order to tear down the TCP connection when idle.--shutdown-watch-termination-grace-period durationThis option, if set, represents the maximum amount of grace period the apiserver will wait for active watch request(s) to drain during the graceful server shutdown window.--storage-backend stringThe storage backend for persistence. Options: 'etcd3' (default).--storage-initialization-timeout duration Default: 1m0sMaximum amount of time to wait for storage initialization before declaring apiserver ready. Defaults to 1m.--storage-media-type string Default: "application/vnd.kubernetes.protobuf"The media type to use to store objects in storage. Some resources or storage backends may only support a specific media type and will ignore this setting. Supported media types: [application/json, application/yaml, application/vnd.kubernetes.protobuf]--strict-transport-security-directives stringsList of directives for HSTS, comma separated. If this list is empty, then HSTS directives will not be added. Example: 'max-age=31536000,includeSubDomains,preload'--tls-cert-file stringFile containing the default x509 Certificate for HTTPS. (CA cert, if any, concatenated after server cert). If HTTPS serving is enabled, and --tls-cert-file and --tls-private-key-file are not provided, a self-signed certificate and key are generated for the public address and saved to the directory specified by --cert-dir.--tls-cipher-suites stringsComma-separated list of cipher suites for the server. If omitted, the default Go cipher suites will be used.Preferred values: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256.Insecure values: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_128_GCM_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_AES_256_GCM_SHA384, TLS_RSA_WITH_RC4_128_SHA.--tls-min-version stringMinimum TLS version supported. Possible values: VersionTLS10, VersionTLS11, VersionTLS12, VersionTLS13--tls-private-key-file stringFile containing the default x509 private key matching --tls-cert-file.--tls-sni-cert-key stringA pair of x509 certificate and private key file paths, optionally suffixed with a list of domain patterns which are fully qualified domain names, possibly with prefixed wildcard segments. The domain patterns also allow IP addresses, but IPs should only be used if the apiserver has visibility to the IP address requested by a client. If no domain patterns are provided, the names of the certificate are extracted. Non-wildcard matches trump over wildcard matches, explicit domain patterns trump over extracted names. For multiple key/certificate pairs, use the --tls-sni-cert-key multiple times. Examples: "example.crt,example.key" or "foo.crt,foo.key:*.foo.com,foo.com".--token-auth-file stringIf set, the file that will be used to secure the secure port of the API server via token authentication.--tracing-config-file stringFile with apiserver tracing configuration.-v, --v intnumber for the log level verbosity--version version[=true]--version, --version=raw prints version information and quits; --version=vX.Y.Z... sets the reported version--vmodule pattern=N,...comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)--watch-cache Default: trueEnable watch caching in the apiserver--watch-cache-sizes stringsWatch cache size settings for some resources (pods, nodes, etc.), comma separated. The individual setting format: resource[.group]#size, where resource is lowercase plural (no version), group is omitted for resources of apiVersion v1 (the legacy core API) and included for others, and size is a number. This option is only meaningful for resources built into the apiserver, not ones defined by CRDs or aggregated from external servers, and is only consulted if the watch-cache is enabled. The only meaningful size setting to supply here is zero, which means to disable watch caching for the associated resource; all non-zero values are equivalent and mean to not disable watch caching for that resourceThis 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.

kube-apiserver


Scale a StatefulSetThis task shows how to scale a StatefulSet. Scaling a StatefulSet refers to increasing or decreasing the number of replicas.Before you beginStatefulSets are only available in Kubernetes version 1.5 or later. To check your version of Kubernetes, run kubectl version.Not all stateful applications scale nicely. If you are unsure about whether to scale your StatefulSets, see StatefulSet concepts or StatefulSet tutorial for further information.You should perform scaling only when you are confident that your stateful application cluster is completely healthy.Scaling StatefulSetsUse kubectl to scale StatefulSetsFirst, find the StatefulSet you want to scale.kubectl get statefulsets <stateful-set-name> Change the number of replicas of your StatefulSet:kubectl scale statefulsets <stateful-set-name> --replicas=<new-replicas> Make in-place updates on your StatefulSetsAlternatively, you can do in-place updates on your StatefulSets.If your StatefulSet was initially created with kubectl apply, update .spec.replicas of the StatefulSet manifests, and then do a kubectl apply:kubectl apply -f <stateful-set-file-updated> Otherwise, edit that field with kubectl edit:kubectl edit statefulsets <stateful-set-name> Or use kubectl patch:kubectl patch statefulsets <stateful-set-name> -p '{"spec":{"replicas":<new-replicas>}}' TroubleshootingScaling down does not work rightYou cannot scale down a StatefulSet when any of the stateful Pods it manages is unhealthy. Scaling down only takes place after those stateful Pods become running and ready.If spec.replicas > 1, Kubernetes cannot determine the reason for an unhealthy Pod. It might be the result of a permanent fault or of a transient fault. A transient fault can be caused by a restart required by upgrading or maintenance.If the Pod is unhealthy due to a permanent fault, scaling without correcting the fault may lead to a state where the StatefulSet membership drops below a certain minimum number of replicas that are needed to function correctly. This may cause your StatefulSet to become unavailable.If the Pod is unhealthy due to a transient fault and the Pod might become available again, the transient error may interfere with your scale-up or scale-down operation. Some distributed databases have issues when nodes join and leave at the same time. It is better to reason about scaling operations at the application level in these cases, and perform scaling only when you are sure that your stateful application cluster is completely healthy.What's nextLearn more about deleting a StatefulSet.

Scale a StatefulSet


kubectl apply set-last-appliedSynopsisSet the latest last-applied-configuration annotations by setting it to match the contents of a file. This results in the last-applied-configuration being updated as though 'kubectl apply -f<file> ' was run, without updating any other parts of the object.kubectl apply set-last-applied -f FILENAME Examples # Set the last-applied-configuration of a resource to match the contents of a file kubectl apply set-last-applied -f deploy.yaml # Execute set-last-applied against each configuration file in a directory kubectl apply set-last-applied -f path/ # Set the last-applied-configuration of a resource to match the contents of a file; will create the annotation if it does not already exist kubectl apply set-last-applied -f deploy.yaml --create-annotation=true Options--allow-missing-template-keys Default: trueIf true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats.--create-annotationWill create 'last-applied-configuration' annotations if current objects doesn't have one--dry-run string[="unchanged"] Default: "none"Must be "none", "server", or "client". If client strategy, only print the object that would be sent, without sending it. If server strategy, submit server-side request without persisting the resource.-f, --filename stringsFilename, directory, or URL to files that contains the last-applied-configuration annotations-h, --helphelp for set-last-applied-o, --output stringOutput format. One of: (json, yaml, name, go-template, go-template-file, template, templatefile, jsonpath, jsonpath-as-json, jsonpath-file).--show-managed-fieldsIf true, keep the managedFields when printing objects in JSON or YAML format.--template stringTemplate string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview].Parent Options Inherited--as stringUsername to impersonate for the operation. User could be a regular user or a service account in a namespace.--as-group stringsGroup to impersonate for the operation, this flag can be repeated to specify multiple groups.--as-uid stringUID to impersonate for the operation.--cache-dir string Default: "$HOME/.kube/cache"Default cache directory--certificate-authority stringPath to a cert file for the certificate authority--client-certificate stringPath to a client certificate file for TLS--client-key stringPath to a client key file for TLS--cluster stringThe name of the kubeconfig cluster to use--context stringThe name of the kubeconfig context to use--disable-compressionIf true, opt-out of response compression for all requests to the server--insecure-skip-tls-verifyIf true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure--kubeconfig stringPath to the kubeconfig file to use for CLI requests.--kuberc stringPath to the kuberc file to use for preferences. This can be disabled by exporting KUBECTL_KUBERC=false feature gate or turning off the feature KUBERC=off.--match-server-versionRequire server version to match client version-n, --namespace stringIf present, the namespace scope for this CLI request--password stringPassword for basic authentication to the API server--profile string Default: "none"Name of profile to capture. One of (none|cpu|heap|goroutine|threadcreate|block|mutex)--profile-output string Default: "profile.pprof"Name of the file to write the profile to--request-timeout string Default: "0"The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests.-s, --server stringThe address and port of the Kubernetes API server--storage-driver-buffer-duration duration Default: 1m0sWrites in the storage driver will be buffered for this duration, and committed to the non memory backends as a single transaction--storage-driver-db string Default: "cadvisor"database name--storage-driver-host string Default: "localhost:8086"database host:port--storage-driver-password string Default: "root"database password--storage-driver-secureuse secure connection with database--storage-driver-table string Default: "stats"table name--storage-driver-user string Default: "root"database username--tls-server-name stringServer name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used--token stringBearer token for authentication to the API server--user stringThe name of the kubeconfig user to use--username stringUsername for basic authentication to the API server--version version[=true]--version, --version=raw prints version information and quits; --version=vX.Y.Z... sets the reported version--warnings-as-errorsTreat warnings received from the server as errors and exit with a non-zero exit codeSee Alsokubectl apply - Apply a configuration to a resource by file name or stdinThis 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.

kubectl apply set-last-applied


PriorityClassPriorityClass defines mapping from a priority class name to the priority integer value.apiVersion: scheduling.k8s.io/v1import "k8s.io/api/scheduling/v1"PriorityClassPriorityClass defines mapping from a priority class name to the priority integer value. The value can be any valid integer.apiVersion: scheduling.k8s.io/v1kind: PriorityClassmetadata (ObjectMeta)Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadatavalue (int32), requiredvalue represents the integer value of this priority class. This is the actual priority that pods receive when they have the name of this class in their pod spec.description (string)description is an arbitrary string that usually provides guidelines on when this priority class should be used.globalDefault (boolean)globalDefault specifies whether this PriorityClass should be considered as the default priority for pods that do not have any priority class. Only one PriorityClass can be marked as globalDefault. However, if more than one PriorityClasses exists with their globalDefault field set to true, the smallest value of such global default PriorityClasses will be used as the default priority.preemptionPolicy (string)preemptionPolicy is the Policy for preempting pods with lower priority. One of Never, PreemptLowerPriority. Defaults to PreemptLowerPriority if unset.PriorityClassListPriorityClassList is a collection of priority classes.apiVersion: scheduling.k8s.io/v1kind: PriorityClassListmetadata (ListMeta)Standard list metadata More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadataitems ([]PriorityClass), requireditems is the list of PriorityClassesOperationsget read the specified PriorityClassHTTP RequestGET /apis/scheduling.k8s.io/v1/priorityclasses/{name}Parametersname (in path): string, requiredname of the PriorityClasspretty (in query): stringprettyResponse200 (PriorityClass): OK401: Unauthorizedlist list or watch objects of kind PriorityClassHTTP RequestGET /apis/scheduling.k8s.io/v1/priorityclassesParametersallowWatchBookmarks (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 (PriorityClassList): OK401: Unauthorizedcreate create a PriorityClassHTTP RequestPOST /apis/scheduling.k8s.io/v1/priorityclassesParametersbody: PriorityClass, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationpretty (in query): stringprettyResponse200 (PriorityClass): OK201 (PriorityClass): Created202 (PriorityClass): Accepted401: Unauthorizedupdate replace the specified PriorityClassHTTP RequestPUT /apis/scheduling.k8s.io/v1/priorityclasses/{name}Parametersname (in path): string, requiredname of the PriorityClassbody: PriorityClass, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationpretty (in query): stringprettyResponse200 (PriorityClass): OK201 (PriorityClass): Created401: Unauthorizedpatch partially update the specified PriorityClassHTTP RequestPATCH /apis/scheduling.k8s.io/v1/priorityclasses/{name}Parametersname (in path): string, requiredname of the PriorityClassbody: Patch, requireddryRun (in query): stringdryRunfieldManager (in query): stringfieldManagerfieldValidation (in query): stringfieldValidationforce (in query): booleanforcepretty (in query): stringprettyResponse200 (PriorityClass): OK201 (PriorityClass): Created401: Unauthorizeddelete delete a PriorityClassHTTP RequestDELETE /apis/scheduling.k8s.io/v1/priorityclasses/{name}Parametersname (in path): string, requiredname of the PriorityClassbody: DeleteOptionsdryRun (in query): stringdryRungracePeriodSeconds (in query): integergracePeriodSecondsignoreStoreReadErrorWithClusterBreakingPotential (in query): booleanignoreStoreReadErrorWithClusterBreakingPotentialpretty (in query): stringprettypropagationPolicy (in query): stringpropagationPolicyResponse200 (Status): OK202 (Status): Accepted401: Unauthorizeddeletecollection delete collection of PriorityClassHTTP RequestDELETE /apis/scheduling.k8s.io/v1/priorityclassesParametersbody: 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.

PriorityClass


Cluster NetworkingNetworking is a central part of Kubernetes, but it can be challenging to understand exactly how it is expected to work. There are 4 distinct networking problems to address:Highly-coupled container-to-container communications: this is solved by Pods and localhost communications.Pod-to-Pod communications: this is the primary focus of this document.Pod-to-Service communications: this is covered by Services.External-to-Service communications: this is also covered by Services.Kubernetes is all about sharing machines among applications. Typically, sharing machines requires ensuring that two applications do not try to use the same ports. Coordinating ports across multiple developers is very difficult to do at scale and exposes users to cluster-level issues outside of their control.Dynamic port allocation brings a lot of complications to the system - every application has to take ports as flags, the API servers have to know how to insert dynamic port numbers into configuration blocks, services have to know how to find each other, etc. Rather than deal with this, Kubernetes takes a different approach.To learn about the Kubernetes networking model, see here.Kubernetes IP address rangesKubernetes clusters require to allocate non-overlapping IP addresses for Pods, Services and Nodes, from a range of available addresses configured in the following components:The network plugin is configured to assign IP addresses to Pods.The kube-apiserver is configured to assign IP addresses to Services.The kubelet or the cloud-controller-manager is configured to assign IP addresses to Nodes.Cluster networking typesKubernetes clusters, attending to the IP families configured, can be categorized into:IPv4 only: The network plugin, kube-apiserver and kubelet/cloud-controller-manager are configured to assign only IPv4 addresses.IPv6 only: The network plugin, kube-apiserver and kubelet/cloud-controller-manager are configured to assign only IPv6 addresses.IPv4/IPv6 or IPv6/IPv4 dual-stack:The network plugin is configured to assign IPv4 and IPv6 addresses.The kube-apiserver is configured to assign IPv4 and IPv6 addresses.The kubelet or cloud-controller-manager is configured to assign IPv4 and IPv6 address.All components must agree on the configured primary IP family.Kubernetes clusters only consider the IP families present on the Pods, Services and Nodes objects, independently of the existing IPs of the represented objects. Per example, a server or a pod can have multiple IP addresses on its interfaces, but only the IP addresses in node.status.addresses or pod.status.ips are considered for implementing the Kubernetes network model and defining the type of the cluster.How to implement the Kubernetes network modelThe network model is implemented by the container runtime on each node. The most common container runtimes use Container Network Interface (CNI) plugins to manage their network and security capabilities. Many different CNI plugins exist from many different vendors. Some of these provide only basic features of adding and removing network interfaces, while others provide more sophisticated solutions, such as integration with other container orchestration systems, running multiple CNI plugins, advanced IPAM features etc.See this page for a non-exhaustive list of networking addons supported by Kubernetes.What's nextThe early design of the networking model and its rationale are described in more detail in the networking design document. For future plans and some on-going efforts that aim to improve Kubernetes networking, please refer to the SIG-Network KEPs.

Cluster Networking


PodsPods are the smallest deployable units of computing that you can create and manage in Kubernetes.A Pod (as in a pod of whales or pea pod) is a group of one or more containers, with shared storage and network resources, and a specification for how to run the containers. A Pod's contents are always co-located and co-scheduled, and run in a shared context. A Pod models an application-specific "logical host": it contains one or more application containers which are relatively tightly coupled. In non-cloud contexts, applications executed on the same physical or virtual machine are analogous to cloud applications executed on the same logical host.As well as application containers, a Pod can contain init containers that run during Pod startup. You can also inject ephemeral containers for debugging a running Pod.What is a Pod?Note:You need to install a container runtime into each node in the cluster so that Pods can run there.The shared context of a Pod is a set of Linux namespaces, cgroups, and potentially other facets of isolation - the same things that isolate a container. Within a Pod's context, the individual applications may have further sub-isolations applied.A Pod is similar to a set of containers with shared namespaces and shared filesystem volumes.Pods in a Kubernetes cluster are used in two main ways:Pods that run a single container. The "one-container-per-Pod" model is the most common Kubernetes use case; in this case, you can think of a Pod as a wrapper around a single container; Kubernetes manages Pods rather than managing the containers directly.Pods that run multiple containers that need to work together. A Pod can encapsulate an application composed of multiple co-located containers that are tightly coupled and need to share resources. These co-located containers form a single cohesive unit.Grouping multiple co-located and co-managed containers in a single Pod is a relatively advanced use case. You should use this pattern only in specific instances in which your containers are tightly coupled.You don't need to run multiple containers to provide replication (for resilience or capacity); if you need multiple replicas, see Workload management.Using PodsThe following is an example of a Pod which consists of a container running the image nginx:1.14.2.pods/simple-pod.yaml apiVersion: v1 kind: Pod metadata: name: nginx spec: containers: - name: nginx image: nginx:1.14.2 ports: - containerPort: 80 To create the Pod shown above, run the following command:kubectl apply -f https://k8s.io/examples/pods/simple-pod.yaml Pods are generally not created directly and are created using workload resources. See Working with Pods for more information on how Pods are used with workload resources.Workload resources for managing podsUsually you don't need to create Pods directly, even singleton Pods. Instead, create them using workload resources such as Deployment or Job. If your Pods need to track state, consider the StatefulSet resource.Each Pod is meant to run a single instance of a given application. If you want to scale your application horizontally (to provide more overall resources by running more instances), you should use multiple Pods, one for each instance. In Kubernetes, this is typically referred to as replication. Replicated Pods are usually created and managed as a group by a workload resource and its controller.See Pods and controllers for more information on how Kubernetes uses workload resources, and their controllers, to implement application scaling and auto-healing.Pods natively provide two kinds of shared resources for their constituent containers: networking and storage.Working with PodsYou'll rarely create individual Pods directly in Kubernetes—even singleton Pods. This is because Pods are designed as relatively ephemeral, disposable entities. When a Pod gets created (directly by you, or indirectly by a controller), the new Pod is scheduled to run on a Node in your cluster. The Pod remains on that node until the Pod finishes execution, the Pod object is deleted, the Pod is evicted for lack of resources, or the node fails.Note:Restarting a container in a Pod should not be confused with restarting a Pod. A Pod is not a process, but an environment for running container(s). A Pod persists until it is deleted.The name of a Pod must be a valid DNS subdomain value, but this can produce unexpected results for the Pod hostname. For best compatibility, the name should follow the more restrictive rules for a DNS label.Pod OSFEATURE STATE: Kubernetes v1.25 [stable]You should set the .spec.os.name field to either windows or linux to indicate the OS on which you want the pod to run. These two are the only operating systems supported for now by Kubernetes. In the future, this list may be expanded.In Kubernetes v1.34, the value of .spec.os.name does not affect how the kube-scheduler picks a node for the Pod to run on. In any cluster where there is more than one operating system for running nodes, you should set the kubernetes.io/os label correctly on each node, and define pods with a nodeSelector based on the operating system label. The kube-scheduler assigns your pod to a node based on other criteria and may or may not succeed in picking a suitable node placement where the node OS is right for the containers in that Pod. The Pod security standards also use this field to avoid enforcing policies that aren't relevant to the operating system.Pods and controllersYou can use workload resources to create and manage multiple Pods for you. A controller for the resource handles replication and rollout and automatic healing in case of Pod failure. For example, if a Node fails, a controller notices that Pods on that Node have stopped working and creates a replacement Pod. The scheduler places the replacement Pod onto a healthy Node.Here are some examples of workload resources that manage one or more Pods:DeploymentStatefulSetDaemonSetPod templatesControllers for workload resources create Pods from a pod template and manage those Pods on your behalf.PodTemplates are specifications for creating Pods, and are included in workload resources such as Deployments, Jobs, and DaemonSets.Each controller for a workload resource uses the PodTemplate inside the workload object to make actual Pods. The PodTemplate is part of the desired state of whatever workload resource you used to run your app.When you create a Pod, you can include environment variables in the Pod template for the containers that run in the Pod.The sample below is a manifest for a simple Job with a template that starts one container. The container in that Pod prints a message then pauses.apiVersion: batch/v1 kind: Job metadata: name: hello spec: template: # This is the pod template spec: containers: - name: hello image: busybox:1.28 command: ['sh', '-c', 'echo "Hello, Kubernetes!" && sleep 3600'] restartPolicy: OnFailure # The pod template ends here Modifying the pod template or switching to a new pod template has no direct effect on the Pods that already exist. If you change the pod template for a workload resource, that resource needs to create replacement Pods that use the updated template.For example, the StatefulSet controller ensures that the running Pods match the current pod template for each StatefulSet object. If you edit the StatefulSet to change its pod template, the StatefulSet starts to create new Pods based on the updated template. Eventually, all of the old Pods are replaced with new Pods, and the update is complete.Each workload resource implements its own rules for handling changes to the Pod template. If you want to read more about StatefulSet specifically, read Update strategy in the StatefulSet Basics tutorial.On Nodes, the kubelet does not directly observe or manage any of the details around pod templates and updates; those details are abstracted away. That abstraction and separation of concerns simplifies system semantics, and makes it feasible to extend the cluster's behavior without changing existing code.Pod update and replacementAs mentioned in the previous section, when the Pod template for a workload resource is changed, the controller creates new Pods based on the updated template instead of updating or patching the existing Pods.Kubernetes doesn't prevent you from managing Pods directly. It is possible to update some fields of a running Pod, in place. However, Pod update operations like patch, and replace have some limitations:Most of the metadata about a Pod is immutable. For example, you cannot change the namespace, name, uid, or creationTimestamp fields.If the metadata.deletionTimestamp is set, no new entry can be added to the metadata.finalizers list.Pod updates may not change fields other than spec.containers[*].image, spec.initContainers[*].image, spec.activeDeadlineSeconds, spec.terminationGracePeriodSeconds, spec.tolerations or spec.schedulingGates. For spec.tolerations, you can only add new entries.When updating the spec.activeDeadlineSeconds field, two types of updates are allowed:setting the unassigned field to a positive number;updating the field from a positive number to a smaller, non-negative number.Pod subresourcesThe above update rules apply to regular pod updates, but other pod fields can be updated through subresources.Resize: The resize subresource allows container resources (spec.containers[*].resources) to be updated. See Resize Container Resources for more details.Ephemeral Containers: The ephemeralContainers subresource allows ephemeral containers to be added to a Pod. See Ephemeral Containers for more details.Status: The status subresource allows the pod status to be updated. This is typically only used by the Kubelet and other system controllers.Binding: The binding subresource allows setting the pod's spec.nodeName via a Binding request. This is typically only used by the scheduler.Pod generationThe metadata.generation field is unique. It will be automatically set by the system such that new pods have a metadata.generation of 1, and every update to mutable fields in the pod's spec will increment the metadata.generation by 1.FEATURE STATE: Kubernetes v1.34 [beta] (enabled by default: true)observedGeneration is a field that is captured in the status section of the Pod object. If the feature gate PodObservedGenerationTracking is set, the Kubelet will set status.observedGeneration to track the pod state to the current pod status. The pod's status.observedGeneration will reflect the metadata.generation of the pod at the point that the pod status is being reported.Note:The status.observedGeneration field is managed by the kubelet and external controllers should not modify this field.Different status fields may either be associated with the metadata.generation of the current sync loop, or with the metadata.generation of the previous sync loop. The key distinction is whether a change in the spec is reflected directly in the status or is an indirect result of a running process.Direct Status UpdatesFor status fields where the allocated spec is directly reflected, the observedGeneration will be associated with the current metadata.generation (Generation N).This behavior applies to:Resize Status: The status of a resource resize operation.Allocated Resources: The resources allocated to the Pod after a resize.Ephemeral Containers: When a new ephemeral container is added, and it is in Waiting state.Indirect Status UpdatesFor status fields that are an indirect result of running the spec, the observedGeneration will be associated with the metadata.generation of the previous sync loop (Generation N-1).This behavior applies to:Container Image: The ContainerStatus.ImageID reflects the image from the previous generation until the new image is pulled and the container is updated.Actual Resources: During an in-progress resize, the actual resources in use still belong to the previous generation's request.Container state: During an in-progress resize, with require restart policy reflects the previous generation's request.activeDeadlineSeconds & terminationGracePeriodSeconds & deletionTimestamp: The effects of these fields on the Pod's status are a result of the previously observed specification.Resource sharing and communicationPods enable data sharing and communication among their constituent containers.Storage in PodsA Pod can specify a set of shared storage volumes. All containers in the Pod can access the shared volumes, allowing those containers to share data. Volumes also allow persistent data in a Pod to survive in case one of the containers within needs to be restarted. See Storage for more information on how Kubernetes implements shared storage and makes it available to Pods.Pod networkingEach Pod is assigned a unique IP address for each address family. Every container in a Pod shares the network namespace, including the IP address and network ports. Inside a Pod (and only then), the containers that belong to the Pod can communicate with one another using localhost. When containers in a Pod communicate with entities outside the Pod, they must coordinate how they use the shared network resources (such as ports). Within a Pod, containers share an IP address and port space, and can find each other via localhost. The containers in a Pod can also communicate with each other using standard inter-process communications like SystemV semaphores or POSIX shared memory. Containers in different Pods have distinct IP addresses and can not communicate by OS-level IPC without special configuration. Containers that want to interact with a container running in a different Pod can use IP networking to communicate.Containers within the Pod see the system hostname as being the same as the configured name for the Pod. There's more about this in the networking section.Pod security settingsTo set security constraints on Pods and containers, you use the securityContext field in the Pod specification. This field gives you granular control over what a Pod or individual containers can do. For example:Drop specific Linux capabilities to avoid the impact of a CVE.Force all processes in the Pod to run as a non-root user or as a specific user or group ID.Set a specific seccomp profile.Set Windows security options, such as whether containers run as HostProcess.Caution:You can also use the Pod securityContext to enable privileged mode in Linux containers. Privileged mode overrides many of the other security settings in the securityContext. Avoid using this setting unless you can't grant the equivalent permissions by using other fields in the securityContext. In Kubernetes 1.26 and later, you can run Windows containers in a similarly privileged mode by setting the windowsOptions.hostProcess flag on the security context of the Pod spec. For details and instructions, see Create a Windows HostProcess Pod.To learn about kernel-level security constraints that you can use, see Linux kernel security constraints for Pods and containers.To learn more about the Pod security context, see Configure a Security Context for a Pod or Container.Static PodsStatic Pods are managed directly by the kubelet daemon on a specific node, without the API server observing them. Whereas most Pods are managed by the control plane (for example, a Deployment), for static Pods, the kubelet directly supervises each static Pod (and restarts it if it fails).Static Pods are always bound to one Kubelet on a specific node. The main use for static Pods is to run a self-hosted control plane: in other words, using the kubelet to supervise the individual control plane components.The kubelet automatically tries to create a mirror Pod on the Kubernetes API server for each static Pod. This means that the Pods running on a node are visible on the API server, but cannot be controlled from there. See the guide Create static Pods for more information.Note:The spec of a static Pod cannot refer to other API objects (e.g., ServiceAccount, ConfigMap, Secret, etc).Pods with multiple containersPods are designed to support multiple cooperating processes (as containers) that form a cohesive unit of service. The containers in a Pod are automatically co-located and co-scheduled on the same physical or virtual machine in the cluster. The containers can share resources and dependencies, communicate with one another, and coordinate when and how they are terminated.Pods in a Kubernetes cluster are used in two main ways:Pods that run a single container. The "one-container-per-Pod" model is the most common Kubernetes use case; in this case, you can think of a Pod as a wrapper around a single container; Kubernetes manages Pods rather than managing the containers directly.Pods that run multiple containers that need to work together. A Pod can encapsulate an application composed of multiple co-located containers that are tightly coupled and need to share resources. These co-located containers form a single cohesive unit of service—for example, one container serving data stored in a shared volume to the public, while a separate sidecar container refreshes or updates those files. The Pod wraps these containers, storage resources, and an ephemeral network identity together as a single unit.For example, you might have a container that acts as a web server for files in a shared volume, and a separate sidecar container that updates those files from a remote source, as in the following diagram:Some Pods have init containers as well as app containers. By default, init containers run and complete before the app containers are started.You can also have sidecar containers that provide auxiliary services to the main application Pod (for example: a service mesh).FEATURE STATE: Kubernetes v1.33 [stable] (enabled by default: true)Enabled by default, the SidecarContainers feature gate allows you to specify restartPolicy: Always for init containers. Setting the Always restart policy ensures that the containers where you set it are treated as sidecars that are kept running during the entire lifetime of the Pod. Containers that you explicitly define as sidecar containers start up before the main application Pod and remain running until the Pod is shut down.Container probesA probe is a diagnostic performed periodically by the kubelet on a container. To perform a diagnostic, the kubelet can invoke different actions:ExecAction (performed with the help of the container runtime)TCPSocketAction (checked directly by the kubelet)HTTPGetAction (checked directly by the kubelet)You can read more about probes in the Pod Lifecycle documentation.What's nextLearn about the lifecycle of a Pod.Learn about RuntimeClass and how you can use it to configure different Pods with different container runtime configurations.Read about PodDisruptionBudget and how you can use it to manage application availability during disruptions.Pod is a top-level resource in the Kubernetes REST API. The Pod object definition describes the object in detail.The Distributed System Toolkit: Patterns for Composite Containers explains common layouts for Pods with more than one container.Read about Pod topology spread constraintsTo understand the context for why Kubernetes wraps a common Pod API in other resources (such as StatefulSets or Deployments), you can read about the prior art, including:AuroraBorgMarathonOmegaTupperware.

Pods


ReplicationControllerLegacy API for managing workloads that can scale horizontally. Superseded by the Deployment and ReplicaSet APIs.Note:A Deployment that configures a ReplicaSet is now the recommended way to set up replication.A ReplicationController ensures that a specified number of pod replicas are running at any one time. In other words, a ReplicationController makes sure that a pod or a homogeneous set of pods is always up and available.How a ReplicationController worksIf there are too many pods, the ReplicationController terminates the extra pods. If there are too few, the ReplicationController starts more pods. Unlike manually created pods, the pods maintained by a ReplicationController are automatically replaced if they fail, are deleted, or are terminated. For example, your pods are re-created on a node after disruptive maintenance such as a kernel upgrade. For this reason, you should use a ReplicationController even if your application requires only a single pod. A ReplicationController is similar to a process supervisor, but instead of supervising individual processes on a single node, the ReplicationController supervises multiple pods across multiple nodes.ReplicationController is often abbreviated to "rc" in discussion, and as a shortcut in kubectl commands.A simple case is to create one ReplicationController object to reliably run one instance of a Pod indefinitely. A more complex use case is to run several identical replicas of a replicated service, such as web servers.Running an example ReplicationControllerThis example ReplicationController config runs three copies of the nginx web server.controllers/replication.yaml apiVersion: v1 kind: ReplicationController metadata: name: nginx spec: replicas: 3 selector: app: nginx template: metadata: name: nginx labels: app: nginx spec: containers: - name: nginx image: nginx ports: - containerPort: 80 Run the example job by downloading the example file and then running this command:kubectl apply -f https://k8s.io/examples/controllers/replication.yaml The output is similar to this:replicationcontroller/nginx created Check on the status of the ReplicationController using this command:kubectl describe replicationcontrollers/nginx The output is similar to this:Name: nginx Namespace: default Selector: app=nginx Labels: app=nginx Annotations: <none> Replicas: 3 current / 3 desired Pods Status: 0 Running / 3 Waiting / 0 Succeeded / 0 Failed Pod Template: Labels: app=nginx Containers: nginx: Image: nginx Port: 80/TCP Environment: <none> Mounts: <none> Volumes: <none> Events: FirstSeen LastSeen Count From SubobjectPath Type Reason Message --------- -------- ----- ---- ------------- ---- ------ ------- 20s 20s 1 {replication-controller } Normal SuccessfulCreate Created pod: nginx-qrm3m 20s 20s 1 {replication-controller } Normal SuccessfulCreate Created pod: nginx-3ntk0 20s 20s 1 {replication-controller } Normal SuccessfulCreate Created pod: nginx-4ok8v Here, three pods are created, but none is running yet, perhaps because the image is being pulled. A little later, the same command may show:Pods Status: 3 Running / 0 Waiting / 0 Succeeded / 0 Failed To list all the pods that belong to the ReplicationController in a machine readable form, you can use a command like this:pods=$(kubectl get pods --selector=app=nginx --output=jsonpath={.items..metadata.name}) echo $pods The output is similar to this:nginx-3ntk0 nginx-4ok8v nginx-qrm3m Here, the selector is the same as the selector for the ReplicationController (seen in the kubectl describe output), and in a different form in replication.yaml. The --output=jsonpath option specifies an expression with the name from each pod in the returned list.Writing a ReplicationController ManifestAs with all other Kubernetes config, a ReplicationController needs apiVersion, kind, and metadata fields.When the control plane creates new Pods for a ReplicationController, the .metadata.name of the ReplicationController is part of the basis for naming those Pods. The name of a ReplicationController must be a valid DNS subdomain value, but this can produce unexpected results for the Pod hostnames. For best compatibility, the name should follow the more restrictive rules for a DNS label.For general information about working with configuration files, see object management.A ReplicationController also needs a .spec section.Pod TemplateThe .spec.template is the only required field of the .spec.The .spec.template is a pod template. It has exactly the same schema as a Pod, except it is nested and does not have an apiVersion or kind.In addition to required fields for a Pod, a pod template in a ReplicationController must specify appropriate labels and an appropriate restart policy. For labels, make sure not to overlap with other controllers. See pod selector.Only a .spec.template.spec.restartPolicy equal to Always is allowed, which is the default if not specified.For local container restarts, ReplicationControllers delegate to an agent on the node, for example the Kubelet.Labels on the ReplicationControllerThe ReplicationController can itself have labels (.metadata.labels). Typically, you would set these the same as the .spec.template.metadata.labels; if .metadata.labels is not specified then it defaults to .spec.template.metadata.labels. However, they are allowed to be different, and the .metadata.labels do not affect the behavior of the ReplicationController.Pod SelectorThe .spec.selector field is a label selector. A ReplicationController manages all the pods with labels that match the selector. It does not distinguish between pods that it created or deleted and pods that another person or process created or deleted. This allows the ReplicationController to be replaced without affecting the running pods.If specified, the .spec.template.metadata.labels must be equal to the .spec.selector, or it will be rejected by the API. If .spec.selector is unspecified, it will be defaulted to .spec.template.metadata.labels.Also you should not normally create any pods whose labels match this selector, either directly, with another ReplicationController, or with another controller such as Job. If you do so, the ReplicationController thinks that it created the other pods. Kubernetes does not stop you from doing this.If you do end up with multiple controllers that have overlapping selectors, you will have to manage the deletion yourself (see below).Multiple ReplicasYou can specify how many pods should run concurrently by setting .spec.replicas to the number of pods you would like to have running concurrently. The number running at any time may be higher or lower, such as if the replicas were just increased or decreased, or if a pod is gracefully shutdown, and a replacement starts early.If you do not specify .spec.replicas, then it defaults to 1.Working with ReplicationControllersDeleting a ReplicationController and its PodsTo delete a ReplicationController and all its pods, use kubectl delete. Kubectl will scale the ReplicationController to zero and wait for it to delete each pod before deleting the ReplicationController itself. If this kubectl command is interrupted, it can be restarted.When using the REST API or client library, you need to do the steps explicitly (scale replicas to 0, wait for pod deletions, then delete the ReplicationController).Deleting only a ReplicationControllerYou can delete a ReplicationController without affecting any of its pods.Using kubectl, specify the --cascade=orphan option to kubectl delete.When using the REST API or client library, you can delete the ReplicationController object.Once the original is deleted, you can create a new ReplicationController to replace it. As long as the old and new .spec.selector are the same, then the new one will adopt the old pods. However, it will not make any effort to make existing pods match a new, different pod template. To update pods to a new spec in a controlled way, use a rolling update.Isolating pods from a ReplicationControllerPods may be removed from a ReplicationController's target set by changing their labels. This technique may be used to remove pods from service for debugging and data recovery. Pods that are removed in this way will be replaced automatically (assuming that the number of replicas is not also changed).Common usage patternsReschedulingAs mentioned above, whether you have 1 pod you want to keep running, or 1000, a ReplicationController will ensure that the specified number of pods exists, even in the event of node failure or pod termination (for example, due to an action by another control agent).ScalingThe ReplicationController enables scaling the number of replicas up or down, either manually or by an auto-scaling control agent, by updating the replicas field.Rolling updatesThe ReplicationController is designed to facilitate rolling updates to a service by replacing pods one-by-one.As explained in #1353, the recommended approach is to create a new ReplicationController with 1 replica, scale the new (+1) and old (-1) controllers one by one, and then delete the old controller after it reaches 0 replicas. This predictably updates the set of pods regardless of unexpected failures.Ideally, the rolling update controller would take application readiness into account, and would ensure that a sufficient number of pods were productively serving at any given time.The two ReplicationControllers would need to create pods with at least one differentiating label, such as the image tag of the primary container of the pod, since it is typically image updates that motivate rolling updates.Multiple release tracksIn addition to running multiple releases of an application while a rolling update is in progress, it's common to run multiple releases for an extended period of time, or even continuously, using multiple release tracks. The tracks would be differentiated by labels.For instance, a service might target all pods with tier in (frontend), environment in (prod). Now say you have 10 replicated pods that make up this tier. But you want to be able to 'canary' a new version of this component. You could set up a ReplicationController with replicas set to 9 for the bulk of the replicas, with labels tier=frontend, environment=prod, track=stable, and another ReplicationController with replicas set to 1 for the canary, with labels tier=frontend, environment=prod, track=canary. Now the service is covering both the canary and non-canary pods. But you can mess with the ReplicationControllers separately to test things out, monitor the results, etc.Using ReplicationControllers with ServicesMultiple ReplicationControllers can sit behind a single service, so that, for example, some traffic goes to the old version, and some goes to the new version.A ReplicationController will never terminate on its own, but it isn't expected to be as long-lived as services. Services may be composed of pods controlled by multiple ReplicationControllers, and it is expected that many ReplicationControllers may be created and destroyed over the lifetime of a service (for instance, to perform an update of pods that run the service). Both services themselves and their clients should remain oblivious to the ReplicationControllers that maintain the pods of the services.Writing programs for ReplicationPods created by a ReplicationController are intended to be fungible and semantically identical, though their configurations may become heterogeneous over time. This is an obvious fit for replicated stateless servers, but ReplicationControllers can also be used to maintain availability of master-elected, sharded, and worker-pool applications. Such applications should use dynamic work assignment mechanisms, such as the RabbitMQ work queues, as opposed to static/one-time customization of the configuration of each pod, which is considered an anti-pattern. Any pod customization performed, such as vertical auto-sizing of resources (for example, cpu or memory), should be performed by another online controller process, not unlike the ReplicationController itself.Responsibilities of the ReplicationControllerThe ReplicationController ensures that the desired number of pods matches its label selector and are operational. Currently, only terminated pods are excluded from its count. In the future, readiness and other information available from the system may be taken into account, we may add more controls over the replacement policy, and we plan to emit events that could be used by external clients to implement arbitrarily sophisticated replacement and/or scale-down policies.The ReplicationController is forever constrained to this narrow responsibility. It itself will not perform readiness nor liveness probes. Rather than performing auto-scaling, it is intended to be controlled by an external auto-scaler (as discussed in #492), which would change its replicas field. We will not add scheduling policies (for example, spreading) to the ReplicationController. Nor should it verify that the pods controlled match the currently specified template, as that would obstruct auto-sizing and other automated processes. Similarly, completion deadlines, ordering dependencies, configuration expansion, and other features belong elsewhere. We even plan to factor out the mechanism for bulk pod creation (#170).The ReplicationController is intended to be a composable building-block primitive. We expect higher-level APIs and/or tools to be built on top of it and other complementary primitives for user convenience in the future. The "macro" operations currently supported by kubectl (run, scale) are proof-of-concept examples of this. For instance, we could imagine something like Asgard managing ReplicationControllers, auto-scalers, services, scheduling policies, canaries, etc.API ObjectReplication controller is a top-level resource in the Kubernetes REST API. More details about the API object can be found at: ReplicationController API object.Alternatives to ReplicationControllerReplicaSetReplicaSet is the next-generation ReplicationController that supports the new set-based label selector. It's mainly used by Deployment as a mechanism to orchestrate pod creation, deletion and updates. Note that we recommend using Deployments instead of directly using Replica Sets, unless you require custom update orchestration or don't require updates at all.Deployment (Recommended)Deployment is a higher-level API object that updates its underlying Replica Sets and their Pods. Deployments are recommended if you want the rolling update functionality, because they are declarative, server-side, and have additional features.Bare PodsUnlike in the case where a user directly created pods, a ReplicationController replaces pods that are deleted or terminated for any reason, such as in the case of node failure or disruptive node maintenance, such as a kernel upgrade. For this reason, we recommend that you use a ReplicationController even if your application requires only a single pod. Think of it similarly to a process supervisor, only it supervises multiple pods across multiple nodes instead of individual processes on a single node. A ReplicationController delegates local container restarts to some agent on the node, such as the kubelet.JobUse a Job instead of a ReplicationController for pods that are expected to terminate on their own (that is, batch jobs).DaemonSetUse a DaemonSet instead of a ReplicationController for pods that provide a machine-level function, such as machine monitoring or machine logging. These pods have a lifetime that is tied to a machine lifetime: the pod needs to be running on the machine before other pods start, and are safe to terminate when the machine is otherwise ready to be rebooted/shutdown.What's nextLearn about Pods.Learn about Deployment, the replacement for ReplicationController.ReplicationController is part of the Kubernetes REST API. Read the ReplicationController object definition to understand the API for replication controllers.

ReplicationController