diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 20f706a5ed..e41528d30b 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -4091,6 +4091,10 @@ Topics: File: machine-machine-openshift-io-v1beta1 - Name: 'MachineSet [machine.openshift.io/v1beta1]' File: machineset-machine-openshift-io-v1beta1 + - Name: 'MachineOSBuild [machineconfiguration.openshift.io/v1]' + File: machineosbuild-machineconfiguration-openshift-io-v1 + - Name: 'MachineOSConfig [machineconfiguration.openshift.io/v1]' + File: machineosconfig-machineconfiguration-openshift-io-v1 - Name: Metadata APIs Dir: metadata_apis Topics: @@ -4148,6 +4152,8 @@ Topics: Topics: - Name: About Network APIs File: network-apis-index + - Name: 'ClusterUserDefinedNetwork [k8s.ovn.org/v1]' + File: clusteruserdefinednetwork-k8s-ovn-org-v1 - Name: 'AdminNetworkPolicy [policy.networking.k8s.io/v1alpha1]' File: adminnetworkpolicy-policy-networking-k8s-io-v1alpha1 - Name: 'AdminPolicyBasedExternalRoute [k8s.ovn.org/v1]' @@ -4170,10 +4176,20 @@ Topics: File: endpointslice-discovery-k8s-io-v1 - Name: 'EgressRouter [network.operator.openshift.io/v1]' File: egressrouter-network-operator-openshift-io-v1 + - Name: 'GRPCRoute [gateway.networking.k8s.io/v1]' + File: grpcroute-gateway-networking-k8s-io-v1 + - Name: 'Gateway [gateway.networking.k8s.io/v1]' + File: gateway-gateway-networking-k8s-io-v1 + - Name: 'GatewayClass [gateway.networking.k8s.io/v1]' + File: gatewayclass-gateway-networking-k8s-io-v1 + - Name: 'HTTPRoute [gateway.networking.k8s.io/v1]' + File: httproute-gateway-networking-k8s-io-v1 - Name: 'Ingress [networking.k8s.io/v1]' File: ingress-networking-k8s-io-v1 - Name: 'IngressClass [networking.k8s.io/v1]' File: ingressclass-networking-k8s-io-v1 + - Name: 'IPAMClaim [k8s.cni.cncf.io/v1alpha1]' + File: ipamclaim-k8s-cni-cncf-io-v1alpha1 - Name: 'IPPool [whereabouts.cni.cncf.io/v1alpha1]' File: ippool-whereabouts-cni-cncf-io-v1alpha1 - Name: 'MultiNetworkPolicy [k8s.cni.cncf.io/v1beta1]' @@ -4182,14 +4198,20 @@ Topics: File: networkattachmentdefinition-k8s-cni-cncf-io-v1 - Name: 'NetworkPolicy [networking.k8s.io/v1]' File: networkpolicy-networking-k8s-io-v1 + - Name: 'NodeSlicePool [whereabouts.cni.cncf.io/v1alpha1]' + File: nodeslicepool-whereabouts-cni-cncf-io-v1alpha1 - Name: 'OverlappingRangeIPReservation [whereabouts.cni.cncf.io/v1alpha1]' File: overlappingrangeipreservation-whereabouts-cni-cncf-io-v1alpha1 - Name: 'PodNetworkConnectivityCheck [controlplane.operator.openshift.io/v1alpha1]' File: podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1 + - Name: 'ReferenceGrant [gateway.networking.k8s.io/v1beta1]' + File: referencegrant-gateway-networking-k8s-io-v1beta1 - Name: 'Route [route.openshift.io/v1]' File: route-route-openshift-io-v1 - Name: 'Service [undefined/v1]' File: service-v1 + - Name: 'UserDefinedNetwork [k8s.ovn.org/v1]' + File: userdefinednetwork-k8s-ovn-org-v1 - Name: Node APIs Dir: node_apis Topics: @@ -4284,6 +4306,10 @@ Topics: File: operatorhub-apis-index - Name: 'CatalogSource [operators.coreos.com/v1alpha1]' File: catalogsource-operators-coreos-com-v1alpha1 + - Name: 'ClusterCatalog [olm.operatorframework.io/v1]' + File: clustercatalog-olm-operatorframework-io-v1 + - Name: 'ClusterExtension [olm.operatorframework.io/v1]' + File: clusterextension-olm-operatorframework-io-v1 - Name: 'ClusterServiceVersion [operators.coreos.com/v1alpha1]' File: clusterserviceversion-operators-coreos-com-v1alpha1 - Name: 'InstallPlan [operators.coreos.com/v1alpha1]' @@ -4337,6 +4363,8 @@ Topics: File: hostfirmwarecomponents-metal3-io-v1alpha1 - Name: 'HostFirmwareSettings [metal3.io/v1alpha1]' File: hostfirmwaresettings-metal3-io-v1alpha1 + - Name: 'HostUpdatePolicy [metal3.io/v1alpha1]' + File: hostupdatepolicy-metal3-io-v1alpha1 - Name: 'Metal3Remediation [infrastructure.cluster.x-k8s.io/v1beta1]' File: metal3remediation-infrastructure-cluster-x-k8s-io-v1beta1 - Name: 'Metal3RemediationTemplate [infrastructure.cluster.x-k8s.io/v1beta1]' diff --git a/api-config.yaml b/api-config.yaml index def378c730..3696aca849 100644 --- a/api-config.yaml +++ b/api-config.yaml @@ -307,12 +307,12 @@ apiMap: # - kind: MachineConfigNode # group: machineconfiguration.openshift.io # version: v1alpha1 -# - kind: MachineOSBuild -# group: machineconfiguration.openshift.io -# version: v1alpha1 -# - kind: MachineOSConfig -# group: machineconfiguration.openshift.io -# version: v1alpha1 + - kind: MachineOSBuild + group: machineconfiguration.openshift.io + version: v1 + - kind: MachineOSConfig + group: machineconfiguration.openshift.io + version: v1 # - kind: PinnedImageSet # group: machineconfiguration.openshift.io # version: v1alpha1 @@ -386,10 +386,9 @@ apiMap: version: v1beta1 - name: Network APIs resources: -# OpenShift SDN -# - kind: ClusterNetwork -# group: network.openshift.io -# version: v1 + - kind: ClusterUserDefinedNetwork + group: k8s.ovn.org + version: v1 - kind: AdminNetworkPolicy group: policy.networking.k8s.io version: v1alpha1 @@ -422,33 +421,33 @@ apiMap: - kind: EndpointSlice group: discovery.k8s.io version: v1 -# OpenShift SDN -# - kind: EgressNetworkPolicy -# group: network.openshift.io -# version: v1 - kind: EgressRouter group: network.operator.openshift.io version: v1 -# OpenShift SDN -# - kind: HostSubnet -# group: network.openshift.io -# version: v1 + - kind: GRPCRoute + group: gateway.networking.k8s.io + version: v1 + - kind: Gateway + group: gateway.networking.k8s.io + version: v1 + - kind: GatewayClass + group: gateway.networking.k8s.io + version: v1 + - kind: HTTPRoute + group: gateway.networking.k8s.io + version: v1 - kind: Ingress group: networking.k8s.io version: v1 - kind: IngressClass group: networking.k8s.io version: v1 -# - kind: IPAMClaim -# group: k8s.cni.cncf.io -# version: v1alpha1 + - kind: IPAMClaim + group: k8s.cni.cncf.io + version: v1alpha1 - kind: IPPool group: whereabouts.cni.cncf.io version: v1alpha1 -# OpenShift SDN -# - kind: NetNamespace -# group: network.openshift.io -# version: v1 - kind: MultiNetworkPolicy group: k8s.cni.cncf.io version: v1beta1 @@ -458,20 +457,26 @@ apiMap: - kind: NetworkPolicy group: networking.k8s.io version: v1 + - kind: NodeSlicePool + group: whereabouts.cni.cncf.io + version: v1alpha1 - kind: OverlappingRangeIPReservation group: whereabouts.cni.cncf.io version: v1alpha1 - kind: PodNetworkConnectivityCheck group: controlplane.operator.openshift.io version: v1alpha1 + - kind: ReferenceGrant + group: gateway.networking.k8s.io + version: v1beta1 - kind: Route group: route.openshift.io version: v1 - kind: Service version: v1 -# - kind: UserDefinedNetwork -# group: k8s.ovn.org -# version: v1 + - kind: UserDefinedNetwork + group: k8s.ovn.org + version: v1 - name: Node APIs resources: - kind: Node @@ -600,12 +605,12 @@ apiMap: group: operators.coreos.com version: v1alpha1 # ERROR (objects/index.adoc): "xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`array (OLM)`]" appears to try to reference a file not included in the "openshift-enterprise" distro -# - kind: ClusterCatalog -# group: olm.operatorframework.io -# version: v1 -# - kind: ClusterExtension -# group: olm.operatorframework.io -# version: v1 + - kind: ClusterCatalog + group: olm.operatorframework.io + version: v1 + - kind: ClusterExtension + group: olm.operatorframework.io + version: v1 - kind: ClusterServiceVersion group: operators.coreos.com version: v1alpha1 @@ -678,6 +683,9 @@ apiMap: - kind: HostFirmwareSettings group: metal3.io version: v1alpha1 + - kind: HostUpdatePolicy + group: metal3.io + version: v1alpha1 - kind: Metal3Remediation group: infrastructure.cluster.x-k8s.io version: v1beta1 diff --git a/rest_api/autoscale_apis/horizontalpodautoscaler-autoscaling-v2.adoc b/rest_api/autoscale_apis/horizontalpodautoscaler-autoscaling-v2.adoc index a8429c4bb3..9b040732af 100644 --- a/rest_api/autoscale_apis/horizontalpodautoscaler-autoscaling-v2.adoc +++ b/rest_api/autoscale_apis/horizontalpodautoscaler-autoscaling-v2.adoc @@ -333,7 +333,7 @@ Required:: | `type` | `string` -| type is the type of metric source. It should be one of "ContainerResource", "External", "Object", "Pods" or "Resource", each mapping to a matching field in the object. Note: "ContainerResource" type is available on when the feature-gate HPAContainerMetrics is enabled +| type is the type of metric source. It should be one of "ContainerResource", "External", "Object", "Pods" or "Resource", each mapping to a matching field in the object. |=== === .spec.metrics[].containerResource @@ -981,7 +981,7 @@ Required:: | `type` | `string` -| type is the type of metric source. It will be one of "ContainerResource", "External", "Object", "Pods" or "Resource", each corresponds to a matching field in the object. Note: "ContainerResource" type is available on when the feature-gate HPAContainerMetrics is enabled +| type is the type of metric source. It will be one of "ContainerResource", "External", "Object", "Pods" or "Resource", each corresponds to a matching field in the object. |=== === .status.currentMetrics[].containerResource diff --git a/rest_api/cluster_apis/ipaddress-ipam-cluster-x-k8s-io-v1beta1.adoc b/rest_api/cluster_apis/ipaddress-ipam-cluster-x-k8s-io-v1beta1.adoc index cd7b1e1f52..c2bfb86410 100644 --- a/rest_api/cluster_apis/ipaddress-ipam-cluster-x-k8s-io-v1beta1.adoc +++ b/rest_api/cluster_apis/ipaddress-ipam-cluster-x-k8s-io-v1beta1.adoc @@ -66,30 +66,30 @@ Required:: | `address` | `string` -| Address is the IP address. +| address is the IP address. | `claimRef` | `object` -| ClaimRef is a reference to the claim this IPAddress was created for. +| claimRef is a reference to the claim this IPAddress was created for. | `gateway` | `string` -| Gateway is the network gateway of the network the address is from. +| gateway is the network gateway of the network the address is from. | `poolRef` | `object` -| PoolRef is a reference to the pool that this IPAddress was created from. +| poolRef is a reference to the pool that this IPAddress was created from. | `prefix` | `integer` -| Prefix is the prefix of the address. +| prefix is the prefix of the address. |=== === .spec.claimRef Description:: + -- -ClaimRef is a reference to the claim this IPAddress was created for. +claimRef is a reference to the claim this IPAddress was created for. -- Type:: @@ -108,16 +108,14 @@ Type:: This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. -TODO: Add other useful fields. apiVersion, kind, uid? More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names -TODO: Drop `kubebuilder:default` when controller-gen doesn't need it https://github.com/kubernetes-sigs/kubebuilder/issues/3896. |=== === .spec.poolRef Description:: + -- -PoolRef is a reference to the pool that this IPAddress was created from. +poolRef is a reference to the pool that this IPAddress was created from. -- Type:: diff --git a/rest_api/cluster_apis/ipaddressclaim-ipam-cluster-x-k8s-io-v1beta1.adoc b/rest_api/cluster_apis/ipaddressclaim-ipam-cluster-x-k8s-io-v1beta1.adoc index d9dcebb52f..b346b33bbb 100644 --- a/rest_api/cluster_apis/ipaddressclaim-ipam-cluster-x-k8s-io-v1beta1.adoc +++ b/rest_api/cluster_apis/ipaddressclaim-ipam-cluster-x-k8s-io-v1beta1.adoc @@ -67,18 +67,18 @@ Required:: | `clusterName` | `string` -| ClusterName is the name of the Cluster this object belongs to. +| clusterName is the name of the Cluster this object belongs to. | `poolRef` | `object` -| PoolRef is a reference to the pool from which an IP address should be created. +| poolRef is a reference to the pool from which an IP address should be created. |=== === .spec.poolRef Description:: + -- -PoolRef is a reference to the pool from which an IP address should be created. +poolRef is a reference to the pool from which an IP address should be created. -- Type:: @@ -128,11 +128,11 @@ Type:: | `addressRef` | `object` -| AddressRef is a reference to the address that was created for this claim. +| addressRef is a reference to the address that was created for this claim. | `conditions` | `array` -| Conditions summarises the current state of the IPAddressClaim +| conditions summarises the current state of the IPAddressClaim | `conditions[]` | `object` @@ -143,7 +143,7 @@ Type:: Description:: + -- -AddressRef is a reference to the address that was created for this claim. +addressRef is a reference to the address that was created for this claim. -- Type:: @@ -162,16 +162,14 @@ Type:: This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. -TODO: Add other useful fields. apiVersion, kind, uid? More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names -TODO: Drop `kubebuilder:default` when controller-gen doesn't need it https://github.com/kubernetes-sigs/kubebuilder/issues/3896. |=== === .status.conditions Description:: + -- -Conditions summarises the current state of the IPAddressClaim +conditions summarises the current state of the IPAddressClaim -- Type:: @@ -216,21 +214,21 @@ This field may be empty. | `string` | The reason for the condition's last transition in CamelCase. The specific API may choose whether or not this field is considered a guaranteed API. -This field may not be empty. +This field may be empty. | `severity` | `string` -| Severity provides an explicit classification of Reason code, so the users or machines can immediately +| severity provides an explicit classification of Reason code, so the users or machines can immediately understand the current situation and act accordingly. The Severity field MUST be set only when Status=False. | `status` | `string` -| Status of the condition, one of True, False, Unknown. +| status of the condition, one of True, False, Unknown. | `type` | `string` -| Type of condition in CamelCase or in foo.example.com/CamelCase. +| type of condition in CamelCase or in foo.example.com/CamelCase. Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. diff --git a/rest_api/config_apis/build-config-openshift-io-v1.adoc b/rest_api/config_apis/build-config-openshift-io-v1.adoc index 0aef1f0a48..7166b1ebe6 100644 --- a/rest_api/config_apis/build-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/build-config-openshift-io-v1.adoc @@ -46,14 +46,14 @@ Required:: | `spec` | `object` -| Spec holds user-settable values for the build controller configuration +| spec holds user-settable values for the build controller configuration |=== === .spec Description:: + -- -Spec holds user-settable values for the build controller configuration +spec holds user-settable values for the build controller configuration -- Type:: @@ -68,7 +68,7 @@ Type:: | `additionalTrustedCA` | `object` -| AdditionalTrustedCA is a reference to a ConfigMap containing additional CAs that +| additionalTrustedCA is a reference to a ConfigMap containing additional CAs that should be trusted for image pushes and pulls during builds. The namespace for this config map is openshift-config. @@ -77,18 +77,18 @@ image.config.openshift.io/cluster instead. | `buildDefaults` | `object` -| BuildDefaults controls the default information for Builds +| buildDefaults controls the default information for Builds | `buildOverrides` | `object` -| BuildOverrides controls override settings for builds +| buildOverrides controls override settings for builds |=== === .spec.additionalTrustedCA Description:: + -- -AdditionalTrustedCA is a reference to a ConfigMap containing additional CAs that +additionalTrustedCA is a reference to a ConfigMap containing additional CAs that should be trusted for image pushes and pulls during builds. The namespace for this config map is openshift-config. @@ -117,7 +117,7 @@ Required:: Description:: + -- -BuildDefaults controls the default information for Builds +buildDefaults controls the default information for Builds -- Type:: @@ -132,7 +132,7 @@ Type:: | `defaultProxy` | `object` -| DefaultProxy contains the default proxy settings for all build operations, including image pull/push +| defaultProxy contains the default proxy settings for all build operations, including image pull/push and source download. Values can be overrode by setting the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables @@ -140,7 +140,7 @@ in the build config's strategy. | `env` | `array` -| Env is a set of default environment variables that will be applied to the +| env is a set of default environment variables that will be applied to the build if the specified variables do not exist on the build | `env[]` @@ -149,14 +149,14 @@ build if the specified variables do not exist on the build | `gitProxy` | `object` -| GitProxy contains the proxy settings for git operations only. If set, this will override +| gitProxy contains the proxy settings for git operations only. If set, this will override any Proxy settings for all git commands, such as git clone. Values that are not set here will be inherited from DefaultProxy. | `imageLabels` | `array` -| ImageLabels is a list of docker labels that are applied to the resulting image. +| imageLabels is a list of docker labels that are applied to the resulting image. User can override a default label by providing a label with the same name in their Build/BuildConfig. @@ -166,14 +166,14 @@ Build/BuildConfig. | `resources` | `object` -| Resources defines resource requirements to execute the build. +| resources defines resource requirements to execute the build. |=== === .spec.buildDefaults.defaultProxy Description:: + -- -DefaultProxy contains the default proxy settings for all build operations, including image pull/push +defaultProxy contains the default proxy settings for all build operations, including image pull/push and source download. Values can be overrode by setting the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables @@ -284,7 +284,7 @@ Required:: Description:: + -- -Env is a set of default environment variables that will be applied to the +env is a set of default environment variables that will be applied to the build if the specified variables do not exist on the build -- @@ -508,7 +508,7 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -GitProxy contains the proxy settings for git operations only. If set, this will override +gitProxy contains the proxy settings for git operations only. If set, this will override any Proxy settings for all git commands, such as git clone. Values that are not set here will be inherited from DefaultProxy. @@ -618,7 +618,7 @@ Required:: Description:: + -- -ImageLabels is a list of docker labels that are applied to the resulting image. +imageLabels is a list of docker labels that are applied to the resulting image. User can override a default label by providing a label with the same name in their Build/BuildConfig. -- @@ -648,18 +648,18 @@ Type:: | `name` | `string` -| Name defines the name of the label. It must have non-zero length. +| name defines the name of the label. It must have non-zero length. | `value` | `string` -| Value defines the literal value of the label. +| value defines the literal value of the label. |=== === .spec.buildDefaults.resources Description:: + -- -Resources defines resource requirements to execute the build. +resources defines resource requirements to execute the build. -- Type:: @@ -754,7 +754,7 @@ only the result of this request. Description:: + -- -BuildOverrides controls override settings for builds +buildOverrides controls override settings for builds -- Type:: @@ -769,14 +769,14 @@ Type:: | `forcePull` | `boolean` -| ForcePull overrides, if set, the equivalent value in the builds, +| forcePull overrides, if set, the equivalent value in the builds, i.e. false disables force pull for all builds, true enables force pull for all builds, independently of what each build specifies itself | `imageLabels` | `array` -| ImageLabels is a list of docker labels that are applied to the resulting image. +| imageLabels is a list of docker labels that are applied to the resulting image. If user provided a label in their Build/BuildConfig with the same name as one in this list, the user's label will be overwritten. @@ -786,11 +786,11 @@ list, the user's label will be overwritten. | `nodeSelector` | `object (string)` -| NodeSelector is a selector which must be true for the build pod to fit on a node +| nodeSelector is a selector which must be true for the build pod to fit on a node | `tolerations` | `array` -| Tolerations is a list of Tolerations that will override any existing +| tolerations is a list of Tolerations that will override any existing tolerations set on a build pod. | `tolerations[]` @@ -803,7 +803,7 @@ the triple using the matching operator . Description:: + -- -ImageLabels is a list of docker labels that are applied to the resulting image. +imageLabels is a list of docker labels that are applied to the resulting image. If user provided a label in their Build/BuildConfig with the same name as one in this list, the user's label will be overwritten. -- @@ -833,18 +833,18 @@ Type:: | `name` | `string` -| Name defines the name of the label. It must have non-zero length. +| name defines the name of the label. It must have non-zero length. | `value` | `string` -| Value defines the literal value of the label. +| value defines the literal value of the label. |=== === .spec.buildOverrides.tolerations Description:: + -- -Tolerations is a list of Tolerations that will override any existing +tolerations is a list of Tolerations that will override any existing tolerations set on a build pod. -- diff --git a/rest_api/config_apis/clusterversion-config-openshift-io-v1.adoc b/rest_api/config_apis/clusterversion-config-openshift-io-v1.adoc index a9e42b7ccb..64c670a650 100644 --- a/rest_api/config_apis/clusterversion-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/clusterversion-config-openshift-io-v1.adoc @@ -726,7 +726,7 @@ Required:: | `promql` | `object` -| promQL represents a cluster condition based on PromQL. +| promql represents a cluster condition based on PromQL. | `type` | `string` @@ -738,7 +738,7 @@ the members and semantics of any additional properties. Description:: + -- -promQL represents a cluster condition based on PromQL. +promql represents a cluster condition based on PromQL. -- Type:: @@ -755,7 +755,7 @@ Required:: | `promql` | `string` -| PromQL is a PromQL query classifying clusters. This query +| promql is a PromQL query classifying clusters. This query query should return a 1 in the match case and a 0 in the does-not-match case. Queries which return no time series, or which return values besides 0 or 1, are diff --git a/rest_api/config_apis/infrastructure-config-openshift-io-v1.adoc b/rest_api/config_apis/infrastructure-config-openshift-io-v1.adoc index 9955ab177f..6146375f61 100644 --- a/rest_api/config_apis/infrastructure-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/infrastructure-config-openshift-io-v1.adoc @@ -118,7 +118,7 @@ Type:: | `key` | `string` -| Key allows pointing to a specific key/value inside of the configmap. This is useful for logical file references. +| key allows pointing to a specific key/value inside of the configmap. This is useful for logical file references. | `name` | `string` @@ -145,23 +145,23 @@ Type:: | `alibabaCloud` | `object` -| AlibabaCloud contains settings specific to the Alibaba Cloud infrastructure provider. +| alibabaCloud contains settings specific to the Alibaba Cloud infrastructure provider. | `aws` | `object` -| AWS contains settings specific to the Amazon Web Services infrastructure provider. +| aws contains settings specific to the Amazon Web Services infrastructure provider. | `azure` | `object` -| Azure contains settings specific to the Azure infrastructure provider. +| azure contains settings specific to the Azure infrastructure provider. | `baremetal` | `object` -| BareMetal contains settings specific to the BareMetal platform. +| baremetal contains settings specific to the BareMetal platform. | `equinixMetal` | `object` -| EquinixMetal contains settings specific to the Equinix Metal infrastructure provider. +| equinixMetal contains settings specific to the Equinix Metal infrastructure provider. | `external` | `object` @@ -170,31 +170,31 @@ Platform-specific components should be supplemented separately. | `gcp` | `object` -| GCP contains settings specific to the Google Cloud Platform infrastructure provider. +| gcp contains settings specific to the Google Cloud Platform infrastructure provider. | `ibmcloud` | `object` -| IBMCloud contains settings specific to the IBMCloud infrastructure provider. +| ibmcloud contains settings specific to the IBMCloud infrastructure provider. | `kubevirt` | `object` -| Kubevirt contains settings specific to the kubevirt infrastructure provider. +| kubevirt contains settings specific to the kubevirt infrastructure provider. | `nutanix` | `object` -| Nutanix contains settings specific to the Nutanix infrastructure provider. +| nutanix contains settings specific to the Nutanix infrastructure provider. | `openstack` | `object` -| OpenStack contains settings specific to the OpenStack infrastructure provider. +| openstack contains settings specific to the OpenStack infrastructure provider. | `ovirt` | `object` -| Ovirt contains settings specific to the oVirt infrastructure provider. +| ovirt contains settings specific to the oVirt infrastructure provider. | `powervs` | `object` -| PowerVS contains settings specific to the IBM Power Systems Virtual Servers infrastructure provider. +| powervs contains settings specific to the IBM Power Systems Virtual Servers infrastructure provider. | `type` | `string` @@ -209,14 +209,14 @@ and must handle unrecognized platforms as None if they do not support that platf | `vsphere` | `object` -| VSphere contains settings specific to the VSphere infrastructure provider. +| vsphere contains settings specific to the VSphere infrastructure provider. |=== === .spec.platformSpec.alibabaCloud Description:: + -- -AlibabaCloud contains settings specific to the Alibaba Cloud infrastructure provider. +alibabaCloud contains settings specific to the Alibaba Cloud infrastructure provider. -- Type:: @@ -229,7 +229,7 @@ Type:: Description:: + -- -AWS contains settings specific to the Amazon Web Services infrastructure provider. +aws contains settings specific to the Amazon Web Services infrastructure provider. -- Type:: @@ -304,7 +304,7 @@ This must be provided and cannot be empty. Description:: + -- -Azure contains settings specific to the Azure infrastructure provider. +azure contains settings specific to the Azure infrastructure provider. -- Type:: @@ -317,7 +317,7 @@ Type:: Description:: + -- -BareMetal contains settings specific to the BareMetal platform. +baremetal contains settings specific to the BareMetal platform. -- Type:: @@ -364,7 +364,7 @@ for example "10.0.0.0/8" or "fd00::/8". Description:: + -- -EquinixMetal contains settings specific to the Equinix Metal infrastructure provider. +equinixMetal contains settings specific to the Equinix Metal infrastructure provider. -- Type:: @@ -393,7 +393,7 @@ Type:: | `platformName` | `string` -| PlatformName holds the arbitrary string representing the infrastructure provider name, expected to be set at the installation time. +| platformName holds the arbitrary string representing the infrastructure provider name, expected to be set at the installation time. This field is solely for informational and reporting purposes and is not expected to be used for decision-making. |=== @@ -401,7 +401,7 @@ This field is solely for informational and reporting purposes and is not expecte Description:: + -- -GCP contains settings specific to the Google Cloud Platform infrastructure provider. +gcp contains settings specific to the Google Cloud Platform infrastructure provider. -- Type:: @@ -414,7 +414,7 @@ Type:: Description:: + -- -IBMCloud contains settings specific to the IBMCloud infrastructure provider. +ibmcloud contains settings specific to the IBMCloud infrastructure provider. -- Type:: @@ -427,7 +427,7 @@ Type:: Description:: + -- -Kubevirt contains settings specific to the kubevirt infrastructure provider. +kubevirt contains settings specific to the kubevirt infrastructure provider. -- Type:: @@ -440,7 +440,7 @@ Type:: Description:: + -- -Nutanix contains settings specific to the Nutanix infrastructure provider. +nutanix contains settings specific to the Nutanix infrastructure provider. -- Type:: @@ -748,7 +748,7 @@ Required:: Description:: + -- -OpenStack contains settings specific to the OpenStack infrastructure provider. +openstack contains settings specific to the OpenStack infrastructure provider. -- Type:: @@ -795,7 +795,7 @@ for example "10.0.0.0/8" or "fd00::/8". Description:: + -- -Ovirt contains settings specific to the oVirt infrastructure provider. +ovirt contains settings specific to the oVirt infrastructure provider. -- Type:: @@ -808,7 +808,7 @@ Type:: Description:: + -- -PowerVS contains settings specific to the IBM Power Systems Virtual Servers infrastructure provider. +powervs contains settings specific to the IBM Power Systems Virtual Servers infrastructure provider. -- Type:: @@ -886,7 +886,7 @@ This must be provided and cannot be empty. Description:: + -- -VSphere contains settings specific to the VSphere infrastructure provider. +vsphere contains settings specific to the VSphere infrastructure provider. -- Type:: @@ -918,8 +918,7 @@ If this is omitted failure domains (regions and zones) will not be used. | `failureDomains[]` | `object` -| VSpherePlatformFailureDomainSpec holds the region and zone failure domain and -the vCenter topology of that failure domain. +| VSpherePlatformFailureDomainSpec holds the region and zone failure domain and the vCenter topology of that failure domain. | `ingressIPs` | `array (string)` @@ -980,8 +979,7 @@ Type:: Description:: + -- -VSpherePlatformFailureDomainSpec holds the region and zone failure domain and -the vCenter topology of that failure domain. +VSpherePlatformFailureDomainSpec holds the region and zone failure domain and the vCenter topology of that failure domain. -- Type:: @@ -1011,13 +1009,19 @@ of a failure domain. be attached to a vCenter datacenter. The tag category in vCenter must be named openshift-region. +| `regionAffinity` +| `object` +| regionAffinity holds the type of region, Datacenter or ComputeCluster. +When set to Datacenter, this means the region is a vCenter Datacenter as defined in topology. +When set to ComputeCluster, this means the region is a vCenter Cluster as defined in topology. + | `server` | `string` | server is the fully-qualified domain name or the IP address of the vCenter server. | `topology` | `object` -| Topology describes a given failure domain using vSphere constructs +| topology describes a given failure domain using vSphere constructs | `zone` | `string` @@ -1025,12 +1029,48 @@ category in vCenter must be named openshift-region. be attached to a vCenter cluster. The tag category in vCenter must be named openshift-zone. +| `zoneAffinity` +| `object` +| zoneAffinity holds the type of the zone and the hostGroup which +vmGroup and the hostGroup names in vCenter corresponds to +a vm-host group of type Virtual Machine and Host respectively. Is also +contains the vmHostRule which is an affinity vm-host rule in vCenter. + +|=== +=== .spec.platformSpec.vsphere.failureDomains[].regionAffinity +Description:: ++ +-- +regionAffinity holds the type of region, Datacenter or ComputeCluster. +When set to Datacenter, this means the region is a vCenter Datacenter as defined in topology. +When set to ComputeCluster, this means the region is a vCenter Cluster as defined in topology. +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `type` +| `string` +| type determines the vSphere object type for a region within this failure domain. +Available types are Datacenter and ComputeCluster. +When set to Datacenter, this means the vCenter Datacenter defined is the region. +When set to ComputeCluster, this means the vCenter cluster defined is the region. + |=== === .spec.platformSpec.vsphere.failureDomains[].topology Description:: + -- -Topology describes a given failure domain using vSphere constructs +topology describes a given failure domain using vSphere constructs -- Type:: @@ -1103,6 +1143,85 @@ VSpherePlatformFailureDomainSpec. For example, for zone=zonea, region=region1, and infrastructure name=test, the template path would be calculated as //vm/test-rhcos-region1-zonea. +|=== +=== .spec.platformSpec.vsphere.failureDomains[].zoneAffinity +Description:: ++ +-- +zoneAffinity holds the type of the zone and the hostGroup which +vmGroup and the hostGroup names in vCenter corresponds to +a vm-host group of type Virtual Machine and Host respectively. Is also +contains the vmHostRule which is an affinity vm-host rule in vCenter. +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `hostGroup` +| `object` +| hostGroup holds the vmGroup and the hostGroup names in vCenter +corresponds to a vm-host group of type Virtual Machine and Host respectively. Is also +contains the vmHostRule which is an affinity vm-host rule in vCenter. + +| `type` +| `string` +| type determines the vSphere object type for a zone within this failure domain. +Available types are ComputeCluster and HostGroup. +When set to ComputeCluster, this means the vCenter cluster defined is the zone. +When set to HostGroup, hostGroup must be configured with hostGroup, vmGroup and vmHostRule and +this means the zone is defined by the grouping of those fields. + +|=== +=== .spec.platformSpec.vsphere.failureDomains[].zoneAffinity.hostGroup +Description:: ++ +-- +hostGroup holds the vmGroup and the hostGroup names in vCenter +corresponds to a vm-host group of type Virtual Machine and Host respectively. Is also +contains the vmHostRule which is an affinity vm-host rule in vCenter. +-- + +Type:: + `object` + +Required:: + - `hostGroup` + - `vmGroup` + - `vmHostRule` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `hostGroup` +| `string` +| hostGroup is the name of the vm-host group of type host within vCenter for this failure domain. +hostGroup is limited to 80 characters. +This field is required when the VSphereFailureDomain ZoneType is HostGroup + +| `vmGroup` +| `string` +| vmGroup is the name of the vm-host group of type virtual machine within vCenter for this failure domain. +vmGroup is limited to 80 characters. +This field is required when the VSphereFailureDomain ZoneType is HostGroup + +| `vmHostRule` +| `string` +| vmHostRule is the name of the affinity vm-host rule within vCenter for this failure domain. +vmHostRule is limited to 80 characters. +This field is required when the VSphereFailureDomain ZoneType is HostGroup + |=== === .spec.platformSpec.vsphere.nodeNetworking Description:: @@ -1372,55 +1491,55 @@ Type:: | `alibabaCloud` | `object` -| AlibabaCloud contains settings specific to the Alibaba Cloud infrastructure provider. +| alibabaCloud contains settings specific to the Alibaba Cloud infrastructure provider. | `aws` | `object` -| AWS contains settings specific to the Amazon Web Services infrastructure provider. +| aws contains settings specific to the Amazon Web Services infrastructure provider. | `azure` | `object` -| Azure contains settings specific to the Azure infrastructure provider. +| azure contains settings specific to the Azure infrastructure provider. | `baremetal` | `object` -| BareMetal contains settings specific to the BareMetal platform. +| baremetal contains settings specific to the BareMetal platform. | `equinixMetal` | `object` -| EquinixMetal contains settings specific to the Equinix Metal infrastructure provider. +| equinixMetal contains settings specific to the Equinix Metal infrastructure provider. | `external` | `object` -| External contains settings specific to the generic External infrastructure provider. +| external contains settings specific to the generic External infrastructure provider. | `gcp` | `object` -| GCP contains settings specific to the Google Cloud Platform infrastructure provider. +| gcp contains settings specific to the Google Cloud Platform infrastructure provider. | `ibmcloud` | `object` -| IBMCloud contains settings specific to the IBMCloud infrastructure provider. +| ibmcloud contains settings specific to the IBMCloud infrastructure provider. | `kubevirt` | `object` -| Kubevirt contains settings specific to the kubevirt infrastructure provider. +| kubevirt contains settings specific to the kubevirt infrastructure provider. | `nutanix` | `object` -| Nutanix contains settings specific to the Nutanix infrastructure provider. +| nutanix contains settings specific to the Nutanix infrastructure provider. | `openstack` | `object` -| OpenStack contains settings specific to the OpenStack infrastructure provider. +| openstack contains settings specific to the OpenStack infrastructure provider. | `ovirt` | `object` -| Ovirt contains settings specific to the oVirt infrastructure provider. +| ovirt contains settings specific to the oVirt infrastructure provider. | `powervs` | `object` -| PowerVS contains settings specific to the Power Systems Virtual Servers infrastructure provider. +| powervs contains settings specific to the Power Systems Virtual Servers infrastructure provider. | `type` | `string` @@ -1438,14 +1557,14 @@ Currently this value cannot be changed once set. | `vsphere` | `object` -| VSphere contains settings specific to the VSphere infrastructure provider. +| vsphere contains settings specific to the VSphere infrastructure provider. |=== === .status.platformStatus.alibabaCloud Description:: + -- -AlibabaCloud contains settings specific to the Alibaba Cloud infrastructure provider. +alibabaCloud contains settings specific to the Alibaba Cloud infrastructure provider. -- Type:: @@ -1523,7 +1642,7 @@ Required:: Description:: + -- -AWS contains settings specific to the Amazon Web Services infrastructure provider. +aws contains settings specific to the Amazon Web Services infrastructure provider. -- Type:: @@ -1553,7 +1672,7 @@ available for the user. | `serviceEndpoints` | `array` -| ServiceEndpoints list contains custom endpoints which will override default +| serviceEndpoints list contains custom endpoints which will override default service endpoint of AWS Services. There must be only one ServiceEndpoint for a service. @@ -1601,11 +1720,15 @@ Required:: | `key` | `string` -| key is the key of the tag +| key sets the key of the AWS resource tag key-value pair. Key is required when defining an AWS resource tag. +Key should consist of between 1 and 128 characters, and may +contain only the set of alphanumeric characters, space (' '), '_', '.', '/', '=', '+', '-', ':', and '@'. | `value` | `string` -| value is the value of the tag. +| value sets the value of the AWS resource tag key-value pair. Value is required when defining an AWS resource tag. +Value should consist of between 1 and 256 characters, and may +contain only the set of alphanumeric characters, space (' '), '_', '.', '/', '=', '+', '-', ':', and '@'. Some AWS service do not support empty values. Since tags are added to resources in many services, the length of the tag value must meet the requirements of all services. @@ -1614,7 +1737,7 @@ length of the tag value must meet the requirements of all services. Description:: + -- -ServiceEndpoints list contains custom endpoints which will override default +serviceEndpoints list contains custom endpoints which will override default service endpoint of AWS Services. There must be only one ServiceEndpoint for a service. -- @@ -1660,7 +1783,7 @@ This must be provided and cannot be empty. Description:: + -- -Azure contains settings specific to the Azure infrastructure provider. +azure contains settings specific to the Azure infrastructure provider. -- Type:: @@ -1756,7 +1879,7 @@ must contain only alphanumeric characters and the following special characters ` Description:: + -- -BareMetal contains settings specific to the BareMetal platform. +baremetal contains settings specific to the BareMetal platform. -- Type:: @@ -1852,7 +1975,7 @@ The default value is OpenShiftManagedDefault. Description:: + -- -EquinixMetal contains settings specific to the Equinix Metal infrastructure provider. +equinixMetal contains settings specific to the Equinix Metal infrastructure provider. -- Type:: @@ -1882,7 +2005,7 @@ The IP is a suitable target of a wildcard DNS record used to resolve default rou Description:: + -- -External contains settings specific to the generic External infrastructure provider. +external contains settings specific to the generic External infrastructure provider. -- Type:: @@ -1938,7 +2061,7 @@ and no extra initialization from the cloud controller manager is expected. Description:: + -- -GCP contains settings specific to the Google Cloud Platform infrastructure provider. +gcp contains settings specific to the Google Cloud Platform infrastructure provider. -- Type:: @@ -2093,7 +2216,7 @@ alphanumeric characters, and the following special characters `_-.@%=+:,*#&(){}[ Description:: + -- -IBMCloud contains settings specific to the IBMCloud infrastructure provider. +ibmcloud contains settings specific to the IBMCloud infrastructure provider. -- Type:: @@ -2108,31 +2231,34 @@ Type:: | `cisInstanceCRN` | `string` -| CISInstanceCRN is the CRN of the Cloud Internet Services instance managing +| cisInstanceCRN is the CRN of the Cloud Internet Services instance managing the DNS zone for the cluster's base domain | `dnsInstanceCRN` | `string` -| DNSInstanceCRN is the CRN of the DNS Services instance managing the DNS zone +| dnsInstanceCRN is the CRN of the DNS Services instance managing the DNS zone for the cluster's base domain | `location` | `string` -| Location is where the cluster has been deployed +| location is where the cluster has been deployed | `providerType` | `string` -| ProviderType indicates the type of cluster that was created +| providerType indicates the type of cluster that was created | `resourceGroupName` | `string` -| ResourceGroupName is the Resource Group for new IBMCloud resources created for the cluster. +| resourceGroupName is the Resource Group for new IBMCloud resources created for the cluster. | `serviceEndpoints` | `array` | serviceEndpoints is a list of custom endpoints which will override the default -service endpoints of an IBM Cloud service. These endpoints are consumed by -components within the cluster to reach the respective IBM Cloud Services. +service endpoints of an IBM service. These endpoints are used by components +within the cluster when trying to reach the IBM Cloud Services that have been +overriden. The CCCMO reads in the IBMCloudPlatformSpec and validates each +endpoint is resolvable. Once validated, the cloud config and IBMCloudPlatformStatus +are updated to reflect the same custom endpoints. | `serviceEndpoints[]` | `object` @@ -2145,8 +2271,11 @@ Description:: + -- serviceEndpoints is a list of custom endpoints which will override the default -service endpoints of an IBM Cloud service. These endpoints are consumed by -components within the cluster to reach the respective IBM Cloud Services. +service endpoints of an IBM service. These endpoints are used by components +within the cluster when trying to reach the IBM Cloud Services that have been +overriden. The CCCMO reads in the IBMCloudPlatformSpec and validates each +endpoint is resolvable. Once validated, the cloud config and IBMCloudPlatformStatus +are updated to reflect the same custom endpoints. -- Type:: @@ -2189,14 +2318,15 @@ with the service `name` of `VPC` and `url` of `https://us.south.private.iaas.clo | `string` | url is fully qualified URI with scheme https, that overrides the default generated endpoint for a client. -This must be provided and cannot be empty. +This must be provided and cannot be empty. The path must follow the pattern +/v[0,9]+ or /api/v[0,9]+ |=== === .status.platformStatus.kubevirt Description:: + -- -Kubevirt contains settings specific to the kubevirt infrastructure provider. +kubevirt contains settings specific to the kubevirt infrastructure provider. -- Type:: @@ -2226,7 +2356,7 @@ The IP is a suitable target of a wildcard DNS record used to resolve default rou Description:: + -- -Nutanix contains settings specific to the Nutanix infrastructure provider. +nutanix contains settings specific to the Nutanix infrastructure provider. -- Type:: @@ -2309,7 +2439,7 @@ The default value is OpenShiftManagedDefault. Description:: + -- -OpenStack contains settings specific to the OpenStack infrastructure provider. +openstack contains settings specific to the OpenStack infrastructure provider. -- Type:: @@ -2410,7 +2540,7 @@ The default value is OpenShiftManagedDefault. Description:: + -- -Ovirt contains settings specific to the oVirt infrastructure provider. +ovirt contains settings specific to the oVirt infrastructure provider. -- Type:: @@ -2497,7 +2627,7 @@ The default value is OpenShiftManagedDefault. Description:: + -- -PowerVS contains settings specific to the Power Systems Virtual Servers infrastructure provider. +powervs contains settings specific to the Power Systems Virtual Servers infrastructure provider. -- Type:: @@ -2512,12 +2642,12 @@ Type:: | `cisInstanceCRN` | `string` -| CISInstanceCRN is the CRN of the Cloud Internet Services instance managing +| cisInstanceCRN is the CRN of the Cloud Internet Services instance managing the DNS zone for the cluster's base domain | `dnsInstanceCRN` | `string` -| DNSInstanceCRN is the CRN of the DNS Services instance managing the DNS zone +| dnsInstanceCRN is the CRN of the DNS Services instance managing the DNS zone for the cluster's base domain | `region` @@ -2602,7 +2732,7 @@ This must be provided and cannot be empty. Description:: + -- -VSphere contains settings specific to the VSphere infrastructure provider. +vsphere contains settings specific to the VSphere infrastructure provider. -- Type:: diff --git a/rest_api/config_apis/network-config-openshift-io-v1.adoc b/rest_api/config_apis/network-config-openshift-io-v1.adoc index 7a444af5af..61892d3e14 100644 --- a/rest_api/config_apis/network-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/network-config-openshift-io-v1.adoc @@ -101,7 +101,7 @@ the network diagnostics feature will be disabled. | `networkType` | `string` -| NetworkType is the plugin that is to be deployed (e.g. OVNKubernetes). +| networkType is the plugin that is to be deployed (e.g. OVNKubernetes). This should match a value that the cluster-network-operator understands, or else no networking will be installed. Currently supported values are: @@ -512,7 +512,7 @@ are allocated. | `clusterNetworkMTU` | `integer` -| ClusterNetworkMTU is the MTU for inter-pod networking. +| clusterNetworkMTU is the MTU for inter-pod networking. | `conditions` | `array` @@ -525,11 +525,11 @@ Known .status.conditions.type are: "NetworkDiagnosticsAvailable" | `migration` | `object` -| Migration contains the cluster network migration configuration. +| migration contains the cluster network migration configuration. | `networkType` | `string` -| NetworkType is the plugin that is deployed (e.g. OVNKubernetes). +| networkType is the plugin that is deployed (e.g. OVNKubernetes). | `serviceNetwork` | `array (string)` @@ -652,7 +652,7 @@ This field may not be empty. Description:: + -- -Migration contains the cluster network migration configuration. +migration contains the cluster network migration configuration. -- Type:: @@ -667,11 +667,11 @@ Type:: | `mtu` | `object` -| MTU is the MTU configuration that is being deployed. +| mtu is the MTU configuration that is being deployed. | `networkType` | `string` -| NetworkType is the target plugin that is being deployed. +| networkType is the target plugin that is being deployed. DEPRECATED: network type migration is no longer supported, so this should always be unset. @@ -680,7 +680,7 @@ so this should always be unset. Description:: + -- -MTU is the MTU configuration that is being deployed. +mtu is the MTU configuration that is being deployed. -- Type:: @@ -695,18 +695,18 @@ Type:: | `machine` | `object` -| Machine contains MTU migration configuration for the machine's uplink. +| machine contains MTU migration configuration for the machine's uplink. | `network` | `object` -| Network contains MTU migration configuration for the default network. +| network contains MTU migration configuration for the default network. |=== === .status.migration.mtu.machine Description:: + -- -Machine contains MTU migration configuration for the machine's uplink. +machine contains MTU migration configuration for the machine's uplink. -- Type:: @@ -721,18 +721,18 @@ Type:: | `from` | `integer` -| From is the MTU to migrate from. +| from is the MTU to migrate from. | `to` | `integer` -| To is the MTU to migrate to. +| to is the MTU to migrate to. |=== === .status.migration.mtu.network Description:: + -- -Network contains MTU migration configuration for the default network. +network contains MTU migration configuration for the default network. -- Type:: @@ -747,11 +747,11 @@ Type:: | `from` | `integer` -| From is the MTU to migrate from. +| from is the MTU to migrate from. | `to` | `integer` -| To is the MTU to migrate to. +| to is the MTU to migrate to. |=== diff --git a/rest_api/config_apis/node-config-openshift-io-v1.adoc b/rest_api/config_apis/node-config-openshift-io-v1.adoc index 8648e55e3b..a5026955a3 100644 --- a/rest_api/config_apis/node-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/node-config-openshift-io-v1.adoc @@ -69,11 +69,11 @@ Type:: | `cgroupMode` | `string` -| CgroupMode determines the cgroups version on the node +| cgroupMode determines the cgroups version on the node | `workerLatencyProfile` | `string` -| WorkerLatencyProfile determins the how fast the kubelet is updating +| workerLatencyProfile determins the how fast the kubelet is updating the status and corresponding reaction of the cluster |=== diff --git a/rest_api/config_apis/proxy-config-openshift-io-v1.adoc b/rest_api/config_apis/proxy-config-openshift-io-v1.adoc index 657b403cbd..7bdf7c138d 100644 --- a/rest_api/config_apis/proxy-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/proxy-config-openshift-io-v1.adoc @@ -43,7 +43,7 @@ Required:: | `spec` | `object` -| Spec holds user-settable values for the proxy configuration +| spec holds user-settable values for the proxy configuration | `status` | `object` @@ -54,7 +54,7 @@ Required:: Description:: + -- -Spec holds user-settable values for the proxy configuration +spec holds user-settable values for the proxy configuration -- Type:: diff --git a/rest_api/config_apis/scheduler-config-openshift-io-v1.adoc b/rest_api/config_apis/scheduler-config-openshift-io-v1.adoc index 7ce5407945..877d284754 100644 --- a/rest_api/config_apis/scheduler-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/scheduler-config-openshift-io-v1.adoc @@ -93,7 +93,7 @@ would not be applied. | `mastersSchedulable` | `boolean` -| MastersSchedulable allows masters nodes to be schedulable. When this flag is +| mastersSchedulable allows masters nodes to be schedulable. When this flag is turned on, all the master nodes in the cluster will be made schedulable, so that workload pods can run on them. The default value for this field is false, meaning none of the master nodes are schedulable. diff --git a/rest_api/console_apis/consolelink-console-openshift-io-v1.adoc b/rest_api/console_apis/consolelink-console-openshift-io-v1.adoc index ede9216226..31407e5bb6 100644 --- a/rest_api/console_apis/consolelink-console-openshift-io-v1.adoc +++ b/rest_api/console_apis/consolelink-console-openshift-io-v1.adoc @@ -113,7 +113,7 @@ Required:: | `imageURL` | `string` -| imageUrl is the URL for the icon used in front of the link in the application menu. +| imageURL is the URL for the icon used in front of the link in the application menu. The URL must be an HTTPS URL or a Data URI. The image should be square and will be shown at 24x24 pixels. | `section` diff --git a/rest_api/console_apis/consoleplugin-console-openshift-io-v1.adoc b/rest_api/console_apis/consoleplugin-console-openshift-io-v1.adoc index 221e01ad58..28e7022d9f 100644 --- a/rest_api/console_apis/consoleplugin-console-openshift-io-v1.adoc +++ b/rest_api/console_apis/consoleplugin-console-openshift-io-v1.adoc @@ -45,14 +45,14 @@ Required:: | `spec` | `object` -| ConsolePluginSpec is the desired plugin configuration. +| spec contains the desired configuration for the console plugin. |=== === .spec Description:: + -- -ConsolePluginSpec is the desired plugin configuration. +spec contains the desired configuration for the console plugin. -- Type:: diff --git a/rest_api/extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc b/rest_api/extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc index 3608f17e2f..7a1c942d1c 100644 --- a/rest_api/extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc +++ b/rest_api/extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc @@ -179,8 +179,8 @@ IfNeeded: the webhook will be called at least one additional time as part of the Defaults to "Never". Possible enum values: - - `"IfNeeded"` indicates that the webhook may be called at least one additional time as part of the admission evaluation if the object being admitted is modified by other admission plugins after the initial webhook call. - - `"Never"` indicates that the webhook must not be called more than once in a single admission evaluation. + - `"IfNeeded"` indicates that the mutation may be called at least one additional time as part of the admission evaluation if the object being admitted is modified by other admission plugins after the initial mutation call. + - `"Never"` indicates that the mutation must not be called more than once in a single admission evaluation. | `rules` | `array` diff --git a/rest_api/extension_apis/validatingadmissionpolicybinding-admissionregistration-k8s-io-v1.adoc b/rest_api/extension_apis/validatingadmissionpolicybinding-admissionregistration-k8s-io-v1.adoc index d22d37b7cb..a19fbd3f71 100644 --- a/rest_api/extension_apis/validatingadmissionpolicybinding-admissionregistration-k8s-io-v1.adoc +++ b/rest_api/extension_apis/validatingadmissionpolicybinding-admissionregistration-k8s-io-v1.adoc @@ -89,7 +89,7 @@ The supported actions values are: "Warn" specifies that a validation failure is reported to the request client in HTTP Warning headers, with a warning code of 299. Warnings can be sent both for allowed or denied admission responses. -"Audit" specifies that a validation failure is included in the published audit event for the request. The audit event will contain a `validation.policy.admission.k8s.io/validation_failure` audit annotation with a value containing the details of the validation failures, formatted as a JSON list of objects, each with the following fields: - message: The validation failure message string - policy: The resource name of the ValidatingAdmissionPolicy - binding: The resource name of the ValidatingAdmissionPolicyBinding - expressionIndex: The index of the failed validations in the ValidatingAdmissionPolicy - validationActions: The enforcement actions enacted for the validation failure Example audit annotation: `"validation.policy.admission.k8s.io/validation_failure": "[{"message": "Invalid value", {"policy": "policy.example.com", {"binding": "policybinding.example.com", {"expressionIndex": "1", {"validationActions": ["Audit"]}]"` +"Audit" specifies that a validation failure is included in the published audit event for the request. The audit event will contain a `validation.policy.admission.k8s.io/validation_failure` audit annotation with a value containing the details of the validation failures, formatted as a JSON list of objects, each with the following fields: - message: The validation failure message string - policy: The resource name of the ValidatingAdmissionPolicy - binding: The resource name of the ValidatingAdmissionPolicyBinding - expressionIndex: The index of the failed validations in the ValidatingAdmissionPolicy - validationActions: The enforcement actions enacted for the validation failure Example audit annotation: `"validation.policy.admission.k8s.io/validation_failure": "[{\"message\": \"Invalid value\", {\"policy\": \"policy.example.com\", {\"binding\": \"policybinding.example.com\", {\"expressionIndex\": \"1\", {\"validationActions\": [\"Audit\"]}]"` Clients should expect to handle additional values by ignoring any values not recognized. diff --git a/rest_api/machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc index cb22ac7b5f..0ca74a4c49 100644 --- a/rest_api/machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc +++ b/rest_api/machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc @@ -43,18 +43,18 @@ Required:: | `spec` | `object` -| ContainerRuntimeConfigSpec defines the desired state of ContainerRuntimeConfig +| spec contains the desired container runtime configuration. | `status` | `object` -| ContainerRuntimeConfigStatus defines the observed state of a ContainerRuntimeConfig +| status contains observed information about the container runtime configuration. |=== === .spec Description:: + -- -ContainerRuntimeConfigSpec defines the desired state of ContainerRuntimeConfig +spec contains the desired container runtime configuration. -- Type:: @@ -71,11 +71,11 @@ Required:: | `containerRuntimeConfig` | `object` -| ContainerRuntimeConfiguration defines the tuneables of the container runtime +| containerRuntimeConfig defines the tuneables of the container runtime. | `machineConfigPoolSelector` | `object` -| MachineConfigPoolSelector selects which pools the ContainerRuntimeConfig shoud apply to. +| machineConfigPoolSelector selects which pools the ContainerRuntimeConfig shoud apply to. A nil selector will result in no pools being selected. |=== @@ -83,7 +83,7 @@ A nil selector will result in no pools being selected. Description:: + -- -ContainerRuntimeConfiguration defines the tuneables of the container runtime +containerRuntimeConfig defines the tuneables of the container runtime. -- Type:: @@ -125,7 +125,7 @@ This flag can be used to set quota on the size of container images. (default: 10 Description:: + -- -MachineConfigPoolSelector selects which pools the ContainerRuntimeConfig shoud apply to. +machineConfigPoolSelector selects which pools the ContainerRuntimeConfig shoud apply to. A nil selector will result in no pools being selected. -- @@ -210,7 +210,7 @@ merge patch. Description:: + -- -ContainerRuntimeConfigStatus defines the observed state of a ContainerRuntimeConfig +status contains observed information about the container runtime configuration. -- Type:: diff --git a/rest_api/machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc index dbe6c6d4ea..b5514c75a3 100644 --- a/rest_api/machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc +++ b/rest_api/machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc @@ -44,18 +44,18 @@ Required:: | `spec` | `object` -| ControllerConfigSpec is the spec for ControllerConfig resource. +| spec contains the desired controller config configuration. | `status` | `object` -| ControllerConfigStatus is the status for ControllerConfig +| status contains observed information about the controller config. |=== === .spec Description:: + -- -ControllerConfigSpec is the spec for ControllerConfig resource. +spec contains the desired controller config configuration. -- Type:: @@ -84,15 +84,15 @@ trusted certificate store. | `baseOSContainerImage` | `string` -| BaseOSContainerImage is the new-format container image for operating system updates. +| baseOSContainerImage is the new-format container image for operating system updates. | `baseOSExtensionsContainerImage` | `string` -| BaseOSExtensionsContainerImage is the matching extensions container for the new-format container +| baseOSExtensionsContainerImage is the matching extensions container for the new-format container | `cloudProviderCAData` | `` -| cloudProvider specifies the cloud provider CA data +| cloudProviderCAData specifies the cloud provider CA data | `cloudProviderConfig` | `string` @@ -149,7 +149,7 @@ rpm-ostree to pull images from the internal registry if present | `network` | `` -| Network contains additional network related information +| network contains additional network related information | `networkType` | `string` @@ -161,7 +161,7 @@ regeneration if this changes. | `osImageURL` | `string` -| OSImageURL is the old-format container image that contains the OS update payload. +| osImageURL is the old-format container image that contains the OS update payload. | `platform` | `string` @@ -399,7 +399,7 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -ControllerConfigStatus is the status for ControllerConfig +status contains observed information about the controller config. -- Type:: diff --git a/rest_api/machine_apis/controlplanemachineset-machine-openshift-io-v1.adoc b/rest_api/machine_apis/controlplanemachineset-machine-openshift-io-v1.adoc index 36e8f1078c..9154cef942 100644 --- a/rest_api/machine_apis/controlplanemachineset-machine-openshift-io-v1.adoc +++ b/rest_api/machine_apis/controlplanemachineset-machine-openshift-io-v1.adoc @@ -68,9 +68,23 @@ Required:: |=== | Property | Type | Description +| `machineNamePrefix` +| `string` +| machineNamePrefix is the prefix used when creating machine names. +Each machine name will consist of this prefix, followed by +a randomly generated string of 5 characters, and the index of the machine. +It must be a lowercase RFC 1123 subdomain, consisting of lowercase +alphanumeric characters, hyphens ('-'), and periods ('.'). +Each block, separated by periods, must start and end with an alphanumeric character. +Hyphens are not allowed at the start or end of a block, and consecutive periods are not permitted. +The prefix must be between 1 and 245 characters in length. +For example, if machineNamePrefix is set to 'control-plane', +and three machines are created, their names might be: +control-plane-abcde-0, control-plane-fghij-1, control-plane-klmno-2 + | `replicas` | `integer` -| Replicas defines how many Control Plane Machines should be +| replicas defines how many Control Plane Machines should be created by this ControlPlaneMachineSet. This field is immutable and cannot be changed after cluster installation. @@ -86,7 +100,7 @@ This field is considered immutable after creation of the resource. | `state` | `string` -| State defines whether the ControlPlaneMachineSet is Active or Inactive. +| state defines whether the ControlPlaneMachineSet is Active or Inactive. When Inactive, the ControlPlaneMachineSet will not take any action on the state of the Machines within the cluster. When Active, the ControlPlaneMachineSet will reconcile the Machines and @@ -96,12 +110,12 @@ further action please remove the ControlPlaneMachineSet. | `strategy` | `object` -| Strategy defines how the ControlPlaneMachineSet will update +| strategy defines how the ControlPlaneMachineSet will update Machines when it detects a change to the ProviderSpec. | `template` | `object` -| Template describes the Control Plane Machines that will be created +| template describes the Control Plane Machines that will be created by this ControlPlaneMachineSet. |=== @@ -196,7 +210,7 @@ merge patch. Description:: + -- -Strategy defines how the ControlPlaneMachineSet will update +strategy defines how the ControlPlaneMachineSet will update Machines when it detects a change to the ProviderSpec. -- @@ -212,7 +226,7 @@ Type:: | `type` | `string` -| Type defines the type of update strategy that should be +| type defines the type of update strategy that should be used when updating Machines owned by the ControlPlaneMachineSet. Valid values are "RollingUpdate" and "OnDelete". The current default value is "RollingUpdate". @@ -222,7 +236,7 @@ The current default value is "RollingUpdate". Description:: + -- -Template describes the Control Plane Machines that will be created +template describes the Control Plane Machines that will be created by this ControlPlaneMachineSet. -- @@ -240,7 +254,7 @@ Required:: | `machineType` | `string` -| MachineType determines the type of Machines that should be managed by the ControlPlaneMachineSet. +| machineType determines the type of Machines that should be managed by the ControlPlaneMachineSet. Currently, the only valid value is machines_v1beta1_machine_openshift_io. | `machines_v1beta1_machine_openshift_io` @@ -272,7 +286,7 @@ Required:: | `failureDomains` | `object` -| FailureDomains is the list of failure domains (sometimes called +| failureDomains is the list of failure domains (sometimes called availability zones) in which the ControlPlaneMachineSet should balance the Control Plane Machines. This will be merged into the ProviderSpec given in the template. @@ -286,7 +300,7 @@ Labels are required to match the ControlPlaneMachineSet selector. | `spec` | `object` -| Spec contains the desired configuration of the Control Plane Machines. +| spec contains the desired configuration of the Control Plane Machines. The ProviderSpec within contains platform specific details for creating the Control Plane Machines. The ProviderSe should be complete apart from the platform specific @@ -298,7 +312,7 @@ are created based on the FailureDomains field. Description:: + -- -FailureDomains is the list of failure domains (sometimes called +failureDomains is the list of failure domains (sometimes called availability zones) in which the ControlPlaneMachineSet should balance the Control Plane Machines. This will be merged into the ProviderSpec given in the template. @@ -319,7 +333,7 @@ Required:: | `aws` | `array` -| AWS configures failure domain information for the AWS platform. +| aws configures failure domain information for the AWS platform. | `aws[]` | `object` @@ -327,7 +341,7 @@ Required:: | `azure` | `array` -| Azure configures failure domain information for the Azure platform. +| azure configures failure domain information for the Azure platform. | `azure[]` | `object` @@ -335,7 +349,7 @@ Required:: | `gcp` | `array` -| GCP configures failure domain information for the GCP platform. +| gcp configures failure domain information for the GCP platform. | `gcp[]` | `object` @@ -351,7 +365,7 @@ Required:: | `openstack` | `array` -| OpenStack configures failure domain information for the OpenStack platform. +| openstack configures failure domain information for the OpenStack platform. | `openstack[]` | `object` @@ -359,7 +373,7 @@ Required:: | `platform` | `string` -| Platform identifies the platform for which the FailureDomain represents. +| platform identifies the platform for which the FailureDomain represents. Currently supported values are AWS, Azure, GCP, OpenStack, VSphere and Nutanix. | `vsphere` @@ -375,7 +389,7 @@ Currently supported values are AWS, Azure, GCP, OpenStack, VSphere and Nutanix. Description:: + -- -AWS configures failure domain information for the AWS platform. +aws configures failure domain information for the AWS platform. -- Type:: @@ -403,18 +417,18 @@ Type:: | `placement` | `object` -| Placement configures the placement information for this instance. +| placement configures the placement information for this instance. | `subnet` | `object` -| Subnet is a reference to the subnet to use for this instance. +| subnet is a reference to the subnet to use for this instance. |=== === .spec.template.machines_v1beta1_machine_openshift_io.failureDomains.aws[].placement Description:: + -- -Placement configures the placement information for this instance. +placement configures the placement information for this instance. -- Type:: @@ -431,14 +445,14 @@ Required:: | `availabilityZone` | `string` -| AvailabilityZone is the availability zone of the instance. +| availabilityZone is the availability zone of the instance. |=== === .spec.template.machines_v1beta1_machine_openshift_io.failureDomains.aws[].subnet Description:: + -- -Subnet is a reference to the subnet to use for this instance. +subnet is a reference to the subnet to use for this instance. -- Type:: @@ -455,11 +469,11 @@ Required:: | `arn` | `string` -| ARN of resource. +| arn of resource. | `filters` | `array` -| Filters is a set of filters used to identify a resource. +| filters is a set of filters used to identify a resource. | `filters[]` | `object` @@ -467,18 +481,18 @@ Required:: | `id` | `string` -| ID of resource. +| id of resource. | `type` | `string` -| Type determines how the reference will fetch the AWS resource. +| type determines how the reference will fetch the AWS resource. |=== === .spec.template.machines_v1beta1_machine_openshift_io.failureDomains.aws[].subnet.filters Description:: + -- -Filters is a set of filters used to identify a resource. +filters is a set of filters used to identify a resource. -- Type:: @@ -508,18 +522,18 @@ Required:: | `name` | `string` -| Name of the filter. Filter names are case-sensitive. +| name of the filter. Filter names are case-sensitive. | `values` | `array (string)` -| Values includes one or more filter values. Filter values are case-sensitive. +| values includes one or more filter values. Filter values are case-sensitive. |=== === .spec.template.machines_v1beta1_machine_openshift_io.failureDomains.azure Description:: + -- -Azure configures failure domain information for the Azure platform. +azure configures failure domain information for the Azure platform. -- Type:: @@ -562,7 +576,7 @@ If nil, the virtual machine should be deployed to no zone. Description:: + -- -GCP configures failure domain information for the GCP platform. +gcp configures failure domain information for the GCP platform. -- Type:: @@ -592,7 +606,7 @@ Required:: | `zone` | `string` -| Zone is the zone in which the GCP machine provider will create the VM. +| zone is the zone in which the GCP machine provider will create the VM. |=== === .spec.template.machines_v1beta1_machine_openshift_io.failureDomains.nutanix @@ -637,7 +651,7 @@ Failure domains are defined in a cluster's config.openshift.io/Infrastructure re Description:: + -- -OpenStack configures failure domain information for the OpenStack platform. +openstack configures failure domain information for the OpenStack platform. -- Type:: @@ -779,7 +793,7 @@ Required:: | `annotations` | `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be +| annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations @@ -798,7 +812,7 @@ It must also contain a label with the key 'machine.openshift.io/cluster-api-clus Description:: + -- -Spec contains the desired configuration of the Control Plane Machines. +spec contains the desired configuration of the Control Plane Machines. The ProviderSpec within contains platform specific details for creating the Control Plane Machines. The ProviderSe should be complete apart from the platform specific @@ -818,7 +832,7 @@ Type:: | `lifecycleHooks` | `object` -| LifecycleHooks allow users to pause operations on the machine at +| lifecycleHooks allow users to pause operations on the machine at certain predefined points within the machine lifecycle. | `metadata` @@ -829,7 +843,7 @@ when creating the Node. | `providerID` | `string` -| ProviderID is the identification ID of the machine provided by the provider. +| providerID is the identification ID of the machine provided by the provider. This field must match the provider ID as seen on the node object corresponding to this machine. This field is required by higher level consumers of cluster-api. Example use case is cluster autoscaler with cluster-api as provider. Clean-up logic in the autoscaler compares machines to nodes to find out @@ -842,7 +856,7 @@ be interfacing with cluster-api as generic provider. | `providerSpec` | `object` -| ProviderSpec details Provider-specific configuration to use during node creation. +| providerSpec details Provider-specific configuration to use during node creation. | `taints` | `array` @@ -863,7 +877,7 @@ any pod that does not tolerate the Taint. Description:: + -- -LifecycleHooks allow users to pause operations on the machine at +lifecycleHooks allow users to pause operations on the machine at certain predefined points within the machine lifecycle. -- @@ -879,7 +893,7 @@ Type:: | `preDrain` | `array` -| PreDrain hooks prevent the machine from being drained. +| preDrain hooks prevent the machine from being drained. This also blocks further lifecycle events, such as termination. | `preDrain[]` @@ -888,7 +902,7 @@ This also blocks further lifecycle events, such as termination. | `preTerminate` | `array` -| PreTerminate hooks prevent the machine from being terminated. +| preTerminate hooks prevent the machine from being terminated. PreTerminate hooks be actioned after the Machine has been drained. | `preTerminate[]` @@ -900,7 +914,7 @@ PreTerminate hooks be actioned after the Machine has been drained. Description:: + -- -PreDrain hooks prevent the machine from being drained. +preDrain hooks prevent the machine from being drained. This also blocks further lifecycle events, such as termination. -- @@ -932,14 +946,14 @@ Required:: | `name` | `string` -| Name defines a unique name for the lifcycle hook. +| name defines a unique name for the lifcycle hook. The name should be unique and descriptive, ideally 1-3 words, in CamelCase or it may be namespaced, eg. foo.example.com/CamelCase. Names must be unique and should only be managed by a single entity. | `owner` | `string` -| Owner defines the owner of the lifecycle hook. +| owner defines the owner of the lifecycle hook. This should be descriptive enough so that users can identify who/what is responsible for blocking the lifecycle. This could be the name of a controller (e.g. clusteroperator/etcd) @@ -950,7 +964,7 @@ or an administrator managing the hook. Description:: + -- -PreTerminate hooks prevent the machine from being terminated. +preTerminate hooks prevent the machine from being terminated. PreTerminate hooks be actioned after the Machine has been drained. -- @@ -982,14 +996,14 @@ Required:: | `name` | `string` -| Name defines a unique name for the lifcycle hook. +| name defines a unique name for the lifcycle hook. The name should be unique and descriptive, ideally 1-3 words, in CamelCase or it may be namespaced, eg. foo.example.com/CamelCase. Names must be unique and should only be managed by a single entity. | `owner` | `string` -| Owner defines the owner of the lifecycle hook. +| owner defines the owner of the lifecycle hook. This should be descriptive enough so that users can identify who/what is responsible for blocking the lifecycle. This could be the name of a controller (e.g. clusteroperator/etcd) @@ -1017,14 +1031,14 @@ Type:: | `annotations` | `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be +| annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations | `generateName` | `string` -| GenerateName is an optional prefix, used by the server, to generate a unique +| generateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. @@ -1049,7 +1063,7 @@ More info: http://kubernetes.io/docs/user-guide/labels | `name` | `string` -| Name must be unique within a namespace. Is required when creating resources, although +| name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. @@ -1058,7 +1072,7 @@ More info: http://kubernetes.io/docs/user-guide/identifiers#names | `namespace` | `string` -| Namespace defines the space within each name must be unique. An empty namespace is +| namespace defines the space within each name must be unique. An empty namespace is equivalent to the "default" namespace, but "default" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. @@ -1160,7 +1174,7 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -ProviderSpec details Provider-specific configuration to use during node creation. +providerSpec details Provider-specific configuration to use during node creation. -- Type:: @@ -1175,7 +1189,7 @@ Type:: | `value` | `` -| Value is an inlined, serialized representation of the resource +| value is an inlined, serialized representation of the resource configuration. It is recommended that providers maintain their own versioned API types that should be serialized/deserialized from this field, akin to component config. @@ -1259,7 +1273,7 @@ Type:: | `conditions` | `array` -| Conditions represents the observations of the ControlPlaneMachineSet's current state. +| conditions represents the observations of the ControlPlaneMachineSet's current state. Known .status.conditions.type are: Available, Degraded and Progressing. | `conditions[]` @@ -1268,34 +1282,34 @@ Known .status.conditions.type are: Available, Degraded and Progressing. | `observedGeneration` | `integer` -| ObservedGeneration is the most recent generation observed for this +| observedGeneration is the most recent generation observed for this ControlPlaneMachineSet. It corresponds to the ControlPlaneMachineSets's generation, which is updated on mutation by the API Server. | `readyReplicas` | `integer` -| ReadyReplicas is the number of Control Plane Machines created by the +| readyReplicas is the number of Control Plane Machines created by the ControlPlaneMachineSet controller which are ready. Note that this value may be higher than the desired number of replicas while rolling updates are in-progress. | `replicas` | `integer` -| Replicas is the number of Control Plane Machines created by the +| replicas is the number of Control Plane Machines created by the ControlPlaneMachineSet controller. Note that during update operations this value may differ from the desired replica count. | `unavailableReplicas` | `integer` -| UnavailableReplicas is the number of Control Plane Machines that are +| unavailableReplicas is the number of Control Plane Machines that are still required before the ControlPlaneMachineSet reaches the desired available capacity. When this value is non-zero, the number of ReadyReplicas is less than the desired Replicas. | `updatedReplicas` | `integer` -| UpdatedReplicas is the number of non-terminated Control Plane Machines +| updatedReplicas is the number of non-terminated Control Plane Machines created by the ControlPlaneMachineSet controller that have the desired provider spec and are ready. This value is set to 0 when a change is detected to the desired spec. @@ -1309,7 +1323,7 @@ a user deletes an existing replica and its replacement has become ready. Description:: + -- -Conditions represents the observations of the ControlPlaneMachineSet's current state. +conditions represents the observations of the ControlPlaneMachineSet's current state. Known .status.conditions.type are: Available, Degraded and Progressing. -- diff --git a/rest_api/machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc index 67df3ab135..2ed5b40c3e 100644 --- a/rest_api/machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc +++ b/rest_api/machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc @@ -43,18 +43,18 @@ Required:: | `spec` | `object` -| KubeletConfigSpec defines the desired state of KubeletConfig +| spec contains the desired kubelet configuration. | `status` | `object` -| KubeletConfigStatus defines the observed state of a KubeletConfig +| status contains observed information about the kubelet configuration. |=== === .spec Description:: + -- -KubeletConfigSpec defines the desired state of KubeletConfig +spec contains the desired kubelet configuration. -- Type:: @@ -84,7 +84,7 @@ for the valid values of these fields. Invalid values of the kubelet configuratio | `machineConfigPoolSelector` | `object` -| MachineConfigPoolSelector selects which pools the KubeletConfig shoud apply to. +| machineConfigPoolSelector selects which pools the KubeletConfig shoud apply to. A nil selector will result in no pools being selected. | `tlsSecurityProfile` @@ -98,7 +98,7 @@ the maximum available minTLSVersion is VersionTLS12. Description:: + -- -MachineConfigPoolSelector selects which pools the KubeletConfig shoud apply to. +machineConfigPoolSelector selects which pools the KubeletConfig shoud apply to. A nil selector will result in no pools being selected. -- @@ -358,7 +358,7 @@ yet well adopted by common software libraries. Description:: + -- -KubeletConfigStatus defines the observed state of a KubeletConfig +status contains observed information about the kubelet configuration. -- Type:: diff --git a/rest_api/machine_apis/machine-apis-index.adoc b/rest_api/machine_apis/machine-apis-index.adoc index 37ff3c2781..d1618f7301 100644 --- a/rest_api/machine_apis/machine-apis-index.adoc +++ b/rest_api/machine_apis/machine-apis-index.adoc @@ -121,3 +121,27 @@ Compatibility level 2: Stable within a major release for a minimum of 9 months o Type:: `object` +== MachineOSBuild [machineconfiguration.openshift.io/v1] + +Description:: ++ +-- +MachineOSBuild describes a build process managed and deployed by the MCO +Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). +-- + +Type:: + `object` + +== MachineOSConfig [machineconfiguration.openshift.io/v1] + +Description:: ++ +-- +MachineOSConfig describes the configuration for a build process managed by the MCO +Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). +-- + +Type:: + `object` + diff --git a/rest_api/machine_apis/machine-machine-openshift-io-v1beta1.adoc b/rest_api/machine_apis/machine-machine-openshift-io-v1beta1.adoc index 8b44dc45ea..bae563c88e 100644 --- a/rest_api/machine_apis/machine-machine-openshift-io-v1beta1.adoc +++ b/rest_api/machine_apis/machine-machine-openshift-io-v1beta1.adoc @@ -66,7 +66,7 @@ Type:: | `lifecycleHooks` | `object` -| LifecycleHooks allow users to pause operations on the machine at +| lifecycleHooks allow users to pause operations on the machine at certain predefined points within the machine lifecycle. | `metadata` @@ -77,7 +77,7 @@ when creating the Node. | `providerID` | `string` -| ProviderID is the identification ID of the machine provided by the provider. +| providerID is the identification ID of the machine provided by the provider. This field must match the provider ID as seen on the node object corresponding to this machine. This field is required by higher level consumers of cluster-api. Example use case is cluster autoscaler with cluster-api as provider. Clean-up logic in the autoscaler compares machines to nodes to find out @@ -90,7 +90,7 @@ be interfacing with cluster-api as generic provider. | `providerSpec` | `object` -| ProviderSpec details Provider-specific configuration to use during node creation. +| providerSpec details Provider-specific configuration to use during node creation. | `taints` | `array` @@ -111,7 +111,7 @@ any pod that does not tolerate the Taint. Description:: + -- -LifecycleHooks allow users to pause operations on the machine at +lifecycleHooks allow users to pause operations on the machine at certain predefined points within the machine lifecycle. -- @@ -127,7 +127,7 @@ Type:: | `preDrain` | `array` -| PreDrain hooks prevent the machine from being drained. +| preDrain hooks prevent the machine from being drained. This also blocks further lifecycle events, such as termination. | `preDrain[]` @@ -136,7 +136,7 @@ This also blocks further lifecycle events, such as termination. | `preTerminate` | `array` -| PreTerminate hooks prevent the machine from being terminated. +| preTerminate hooks prevent the machine from being terminated. PreTerminate hooks be actioned after the Machine has been drained. | `preTerminate[]` @@ -148,7 +148,7 @@ PreTerminate hooks be actioned after the Machine has been drained. Description:: + -- -PreDrain hooks prevent the machine from being drained. +preDrain hooks prevent the machine from being drained. This also blocks further lifecycle events, such as termination. -- @@ -180,14 +180,14 @@ Required:: | `name` | `string` -| Name defines a unique name for the lifcycle hook. +| name defines a unique name for the lifcycle hook. The name should be unique and descriptive, ideally 1-3 words, in CamelCase or it may be namespaced, eg. foo.example.com/CamelCase. Names must be unique and should only be managed by a single entity. | `owner` | `string` -| Owner defines the owner of the lifecycle hook. +| owner defines the owner of the lifecycle hook. This should be descriptive enough so that users can identify who/what is responsible for blocking the lifecycle. This could be the name of a controller (e.g. clusteroperator/etcd) @@ -198,7 +198,7 @@ or an administrator managing the hook. Description:: + -- -PreTerminate hooks prevent the machine from being terminated. +preTerminate hooks prevent the machine from being terminated. PreTerminate hooks be actioned after the Machine has been drained. -- @@ -230,14 +230,14 @@ Required:: | `name` | `string` -| Name defines a unique name for the lifcycle hook. +| name defines a unique name for the lifcycle hook. The name should be unique and descriptive, ideally 1-3 words, in CamelCase or it may be namespaced, eg. foo.example.com/CamelCase. Names must be unique and should only be managed by a single entity. | `owner` | `string` -| Owner defines the owner of the lifecycle hook. +| owner defines the owner of the lifecycle hook. This should be descriptive enough so that users can identify who/what is responsible for blocking the lifecycle. This could be the name of a controller (e.g. clusteroperator/etcd) @@ -265,14 +265,14 @@ Type:: | `annotations` | `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be +| annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations | `generateName` | `string` -| GenerateName is an optional prefix, used by the server, to generate a unique +| generateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. @@ -297,7 +297,7 @@ More info: http://kubernetes.io/docs/user-guide/labels | `name` | `string` -| Name must be unique within a namespace. Is required when creating resources, although +| name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. @@ -306,7 +306,7 @@ More info: http://kubernetes.io/docs/user-guide/identifiers#names | `namespace` | `string` -| Namespace defines the space within each name must be unique. An empty namespace is +| namespace defines the space within each name must be unique. An empty namespace is equivalent to the "default" namespace, but "default" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. @@ -408,7 +408,7 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -ProviderSpec details Provider-specific configuration to use during node creation. +providerSpec details Provider-specific configuration to use during node creation. -- Type:: @@ -423,7 +423,7 @@ Type:: | `value` | `` -| Value is an inlined, serialized representation of the resource +| value is an inlined, serialized representation of the resource configuration. It is recommended that providers maintain their own versioned API types that should be serialized/deserialized from this field, akin to component config. @@ -507,7 +507,7 @@ Type:: | `addresses` | `array` -| Addresses is a list of addresses assigned to the machine. Queried from cloud provider, if available. +| addresses is a list of addresses assigned to the machine. Queried from cloud provider, if available. | `addresses[]` | `object` @@ -515,7 +515,7 @@ Type:: | `conditions` | `array` -| Conditions defines the current state of the Machine +| conditions defines the current state of the Machine | `conditions[]` | `object` @@ -523,7 +523,7 @@ Type:: | `errorMessage` | `string` -| ErrorMessage will be set in the event that there is a terminal problem +| errorMessage will be set in the event that there is a terminal problem reconciling the Machine and will contain a more verbose string suitable for logging and human consumption. @@ -542,7 +542,7 @@ controller's output. | `errorReason` | `string` -| ErrorReason will be set in the event that there is a terminal problem +| errorReason will be set in the event that there is a terminal problem reconciling the Machine and will contain a succinct value suitable for machine interpretation. @@ -561,27 +561,27 @@ controller's output. | `lastOperation` | `object` -| LastOperation describes the last-operation performed by the machine-controller. +| lastOperation describes the last-operation performed by the machine-controller. This API should be useful as a history in terms of the latest operation performed on the specific machine. It should also convey the state of the latest-operation for example if it is still on-going, failed or completed successfully. | `lastUpdated` | `string` -| LastUpdated identifies when this status was last observed. +| lastUpdated identifies when this status was last observed. | `nodeRef` | `object` -| NodeRef will point to the corresponding Node if it exists. +| nodeRef will point to the corresponding Node if it exists. | `phase` | `string` -| Phase represents the current phase of machine actuation. +| phase represents the current phase of machine actuation. One of: Failed, Provisioning, Provisioned, Running, Deleting | `providerStatus` | `` -| ProviderStatus details a Provider-specific status. +| providerStatus details a Provider-specific status. It is recommended that providers maintain their own versioned API types that should be serialized/deserialized from this field. @@ -591,7 +591,7 @@ serialized/deserialized from this field. Description:: + -- -Addresses is a list of addresses assigned to the machine. Queried from cloud provider, if available. +addresses is a list of addresses assigned to the machine. Queried from cloud provider, if available. -- Type:: @@ -633,7 +633,7 @@ Required:: Description:: + -- -Conditions defines the current state of the Machine +conditions defines the current state of the Machine -- Type:: @@ -682,17 +682,17 @@ This field may not be empty. | `severity` | `string` -| Severity provides an explicit classification of Reason code, so the users or machines can immediately +| severity provides an explicit classification of Reason code, so the users or machines can immediately understand the current situation and act accordingly. The Severity field MUST be set only when Status=False. | `status` | `string` -| Status of the condition, one of True, False, Unknown. +| status of the condition, one of True, False, Unknown. | `type` | `string` -| Type of condition in CamelCase or in foo.example.com/CamelCase. +| type of condition in CamelCase or in foo.example.com/CamelCase. Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. @@ -701,7 +701,7 @@ can be useful (see .node.status.conditions), the ability to deconflict is import Description:: + -- -LastOperation describes the last-operation performed by the machine-controller. +lastOperation describes the last-operation performed by the machine-controller. This API should be useful as a history in terms of the latest operation performed on the specific machine. It should also convey the state of the latest-operation for example if it is still on-going, failed or completed successfully. @@ -719,20 +719,20 @@ Type:: | `description` | `string` -| Description is the human-readable description of the last operation. +| description is the human-readable description of the last operation. | `lastUpdated` | `string` -| LastUpdated is the timestamp at which LastOperation API was last-updated. +| lastUpdated is the timestamp at which LastOperation API was last-updated. | `state` | `string` -| State is the current status of the last performed operation. +| state is the current status of the last performed operation. E.g. Processing, Failed, Successful etc | `type` | `string` -| Type is the type of operation which was last performed. +| type is the type of operation which was last performed. E.g. Create, Delete, Update etc |=== @@ -740,7 +740,7 @@ E.g. Create, Delete, Update etc Description:: + -- -NodeRef will point to the corresponding Node if it exists. +nodeRef will point to the corresponding Node if it exists. -- Type:: diff --git a/rest_api/machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc index fd7bbf2a41..09cfe746ea 100644 --- a/rest_api/machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc +++ b/rest_api/machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc @@ -63,12 +63,12 @@ Type:: | `baseOSExtensionsContainerImage` | `string` -| BaseOSExtensionsContainerImage specifies the remote location that will be used +| baseOSExtensionsContainerImage specifies the remote location that will be used to fetch the extensions container matching a new-format OS image | `config` | `` -| Config is a Ignition Config object. +| config is a Ignition Config object. | `extensions` | `array (string)` @@ -89,7 +89,7 @@ to fetch the extensions container matching a new-format OS image | `osImageURL` | `string` -| OSImageURL specifies the remote location that will be used to +| osImageURL specifies the remote location that will be used to fetch the OS. |=== diff --git a/rest_api/machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc index 84f4b77a71..662ad2d617 100644 --- a/rest_api/machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc +++ b/rest_api/machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc @@ -43,18 +43,18 @@ Required:: | `spec` | `object` -| MachineConfigPoolSpec is the spec for MachineConfigPool resource. +| spec contains the desired machine config pool configuration. | `status` | `object` -| MachineConfigPoolStatus is the status for MachineConfigPool resource. +| status contains observed information about the machine config pool. |=== === .spec Description:: + -- -MachineConfigPoolSpec is the spec for MachineConfigPool resource. +spec contains the desired machine config pool configuration. -- Type:: @@ -408,7 +408,7 @@ merge patch. Description:: + -- -MachineConfigPoolStatus is the status for MachineConfigPool resource. +status contains observed information about the machine config pool. -- Type:: diff --git a/rest_api/machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc b/rest_api/machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc index 614090fd0c..e3ac54f488 100644 --- a/rest_api/machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc +++ b/rest_api/machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc @@ -84,7 +84,7 @@ Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". | `remediationTemplate` | `object` -| RemediationTemplate is a reference to a remediation template +| remediationTemplate is a reference to a remediation template provided by an infrastructure provider. This field is completely optional, when filled, the MachineHealthCheck controller @@ -98,7 +98,7 @@ Note: An empty selector will match all machines. | `unhealthyConditions` | `array` -| UnhealthyConditions contains a list of the conditions that determine +| unhealthyConditions contains a list of the conditions that determine whether a node is considered unhealthy. The conditions are combined in a logical OR, i.e. if any of the conditions is met, the node is unhealthy. @@ -113,7 +113,7 @@ status for at least the timeout value, a node is considered unhealthy. Description:: + -- -RemediationTemplate is a reference to a remediation template +remediationTemplate is a reference to a remediation template provided by an infrastructure provider. This field is completely optional, when filled, the MachineHealthCheck controller @@ -260,7 +260,7 @@ merge patch. Description:: + -- -UnhealthyConditions contains a list of the conditions that determine +unhealthyConditions contains a list of the conditions that determine whether a node is considered unhealthy. The conditions are combined in a logical OR, i.e. if any of the conditions is met, the node is unhealthy. -- @@ -324,7 +324,7 @@ Type:: | `conditions` | `array` -| Conditions defines the current state of the MachineHealthCheck +| conditions defines the current state of the MachineHealthCheck | `conditions[]` | `object` @@ -340,7 +340,7 @@ Type:: | `remediationsAllowed` | `integer` -| RemediationsAllowed is the number of further remediations allowed by this machine health check before +| remediationsAllowed is the number of further remediations allowed by this machine health check before maxUnhealthy short circuiting will be applied |=== @@ -348,7 +348,7 @@ maxUnhealthy short circuiting will be applied Description:: + -- -Conditions defines the current state of the MachineHealthCheck +conditions defines the current state of the MachineHealthCheck -- Type:: @@ -397,17 +397,17 @@ This field may not be empty. | `severity` | `string` -| Severity provides an explicit classification of Reason code, so the users or machines can immediately +| severity provides an explicit classification of Reason code, so the users or machines can immediately understand the current situation and act accordingly. The Severity field MUST be set only when Status=False. | `status` | `string` -| Status of the condition, one of True, False, Unknown. +| status of the condition, one of True, False, Unknown. | `type` | `string` -| Type of condition in CamelCase or in foo.example.com/CamelCase. +| type of condition in CamelCase or in foo.example.com/CamelCase. Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. diff --git a/rest_api/machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc new file mode 100644 index 0000000000..f143ce5ba3 --- /dev/null +++ b/rest_api/machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc @@ -0,0 +1,748 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="machineosbuild-machineconfiguration-openshift-io-v1"] += MachineOSBuild [machineconfiguration.openshift.io/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +MachineOSBuild describes a build process managed and deployed by the MCO +Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). +-- + +Type:: + `object` + +Required:: + - `spec` + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| spec describes the configuration of the machine os build. +It is immutable once set. + +| `status` +| `object` +| status describes the last observed state of this machine os build. + +|=== +=== .spec +Description:: ++ +-- +spec describes the configuration of the machine os build. +It is immutable once set. +-- + +Type:: + `object` + +Required:: + - `machineConfig` + - `machineOSConfig` + - `renderedImagePushSpec` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `machineConfig` +| `object` +| machineConfig points to the rendered MachineConfig resource to be included in this image build. + +| `machineOSConfig` +| `object` +| machineOSConfig references the MachineOSConfig resource that this image build extends. + +| `renderedImagePushSpec` +| `string` +| renderedImagePushSpec is set by the Machine Config Operator from the MachineOSConfig object this build is attached to. +This field describes the location of the final image, which will be pushed by the build once complete. +The format of the image push spec is: host[:port][/namespace]/name: or svc_name.namespace.svc[:port]/repository/name:. +The length of the push spec must be between 1 to 447 characters. + +|=== +=== .spec.machineConfig +Description:: ++ +-- +machineConfig points to the rendered MachineConfig resource to be included in this image build. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is the name of the rendered MachineConfig object. +This value should be between 10 and 253 characters, and must contain only lowercase +alphanumeric characters, hyphens and periods, and should start and end with an alphanumeric character. + +|=== +=== .spec.machineOSConfig +Description:: ++ +-- +machineOSConfig references the MachineOSConfig resource that this image build extends. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name of the MachineOSConfig. +The name must contain only lowercase alphanumeric characters, '-' or '.' and start/end with an alphanumeric character. + +|=== +=== .status +Description:: ++ +-- +status describes the last observed state of this machine os build. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `buildEnd` +| `string` +| buildEnd is the timestamp corresponding to completion of the builder backend. +When omitted the build has either not been started, or is in progress. +It will be populated once the build completes, fails or is interrupted. + +| `buildStart` +| `string` +| buildStart is the timestamp corresponding to the build controller initiating the build backend for this MachineOSBuild. + +| `builder` +| `object` +| builder describes the image builder backend used for this build. + +| `conditions` +| `array` +| conditions are state related conditions for the build. Valid types are: +Prepared, Building, Failed, Interrupted, and Succeeded. +Once a Build is marked as Failed, Interrupted or Succeeded, no future conditions can be set. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `digestedImagePushSpec` +| `string` +| digestedImagePushSpec describes the fully qualified push spec produced by this build. +The format of the push spec is: host[:port][/namespace]/name@sha256:, +where the digest must be 64 characters long, and consist only of lowercase hexadecimal characters, a-f and 0-9. +The length of the whole spec must be between 1 to 447 characters. + +| `relatedObjects` +| `array` +| relatedObjects is a list of references to ephemeral objects such as ConfigMaps or Secrets that are meant to be consumed while the build process runs. +After a successful build or when this MachineOSBuild is deleted, these ephemeral objects will be removed. +In the event of a failed build, the objects will remain until the build is removed to allow for inspection. + +| `relatedObjects[]` +| `object` +| ObjectReference contains enough information to let you inspect or modify the referred object. + +|=== +=== .status.builder +Description:: ++ +-- +builder describes the image builder backend used for this build. +-- + +Type:: + `object` + +Required:: + - `imageBuilderType` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `imageBuilderType` +| `string` +| imageBuilderType describes the type of image builder used to build this image. +Valid values are Job only. +When set to Job, a pod based builder, using buildah, is launched to build the specified image. + +| `job` +| `object` +| job is a reference to the job object that is managing the image build. +This is required if the imageBuilderType is Job, and forbidden otherwise. + +|=== +=== .status.builder.job +Description:: ++ +-- +job is a reference to the job object that is managing the image build. +This is required if the imageBuilderType is Job, and forbidden otherwise. +-- + +Type:: + `object` + +Required:: + - `group` + - `name` + - `resource` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| group of the referent. +The name must contain only lowercase alphanumeric characters, '-' or '.' and start/end with an alphanumeric character. +Example: "", "apps", "build.openshift.io", etc. + +| `name` +| `string` +| name of the referent. +The name must contain only lowercase alphanumeric characters, '-' or '.' and start/end with an alphanumeric character. + +| `namespace` +| `string` +| namespace of the referent. +This value should consist of at most 63 characters, and of only lowercase alphanumeric characters and hyphens, +and should start and end with an alphanumeric character. + +| `resource` +| `string` +| resource of the referent. +This value should consist of at most 63 characters, and of only lowercase alphanumeric characters and hyphens, +and should start and end with an alphanumeric character. +Example: "deployments", "deploymentconfigs", "pods", etc. + +|=== +=== .status.conditions +Description:: ++ +-- +conditions are state related conditions for the build. Valid types are: +Prepared, Building, Failed, Interrupted, and Succeeded. +Once a Build is marked as Failed, Interrupted or Succeeded, no future conditions can be set. +-- + +Type:: + `array` + + + + +=== .status.conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== +=== .status.relatedObjects +Description:: ++ +-- +relatedObjects is a list of references to ephemeral objects such as ConfigMaps or Secrets that are meant to be consumed while the build process runs. +After a successful build or when this MachineOSBuild is deleted, these ephemeral objects will be removed. +In the event of a failed build, the objects will remain until the build is removed to allow for inspection. +-- + +Type:: + `array` + + + + +=== .status.relatedObjects[] +Description:: ++ +-- +ObjectReference contains enough information to let you inspect or modify the referred object. +-- + +Type:: + `object` + +Required:: + - `group` + - `name` + - `resource` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| group of the referent. +The name must contain only lowercase alphanumeric characters, '-' or '.' and start/end with an alphanumeric character. +Example: "", "apps", "build.openshift.io", etc. + +| `name` +| `string` +| name of the referent. +The name must contain only lowercase alphanumeric characters, '-' or '.' and start/end with an alphanumeric character. + +| `namespace` +| `string` +| namespace of the referent. +This value should consist of at most 63 characters, and of only lowercase alphanumeric characters and hyphens, +and should start and end with an alphanumeric character. + +| `resource` +| `string` +| resource of the referent. +This value should consist of at most 63 characters, and of only lowercase alphanumeric characters and hyphens, +and should start and end with an alphanumeric character. +Example: "deployments", "deploymentconfigs", "pods", etc. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/machineconfiguration.openshift.io/v1/machineosbuilds` +- `DELETE`: delete collection of MachineOSBuild +- `GET`: list objects of kind MachineOSBuild +- `POST`: create a MachineOSBuild +* `/apis/machineconfiguration.openshift.io/v1/machineosbuilds/{name}` +- `DELETE`: delete a MachineOSBuild +- `GET`: read the specified MachineOSBuild +- `PATCH`: partially update the specified MachineOSBuild +- `PUT`: replace the specified MachineOSBuild +* `/apis/machineconfiguration.openshift.io/v1/machineosbuilds/{name}/status` +- `GET`: read status of the specified MachineOSBuild +- `PATCH`: partially update status of the specified MachineOSBuild +- `PUT`: replace status of the specified MachineOSBuild + + +=== /apis/machineconfiguration.openshift.io/v1/machineosbuilds + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of MachineOSBuild + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind MachineOSBuild + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-machineconfiguration-v1-MachineOSBuildList[`MachineOSBuildList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a MachineOSBuild + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 201 - Created +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 202 - Accepted +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/machineconfiguration.openshift.io/v1/machineosbuilds/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the MachineOSBuild +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a MachineOSBuild + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified MachineOSBuild + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified MachineOSBuild + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified MachineOSBuild + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 201 - Created +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/machineconfiguration.openshift.io/v1/machineosbuilds/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the MachineOSBuild +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified MachineOSBuild + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified MachineOSBuild + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified MachineOSBuild + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 201 - Created +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`MachineOSBuild`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc new file mode 100644 index 0000000000..736297163a --- /dev/null +++ b/rest_api/machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc @@ -0,0 +1,777 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="machineosconfig-machineconfiguration-openshift-io-v1"] += MachineOSConfig [machineconfiguration.openshift.io/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +MachineOSConfig describes the configuration for a build process managed by the MCO +Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). +-- + +Type:: + `object` + +Required:: + - `spec` + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| spec describes the configuration of the machineosconfig + +| `status` +| `object` +| status describes the status of the machineosconfig + +|=== +=== .spec +Description:: ++ +-- +spec describes the configuration of the machineosconfig +-- + +Type:: + `object` + +Required:: + - `imageBuilder` + - `machineConfigPool` + - `renderedImagePushSecret` + - `renderedImagePushSpec` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `baseImagePullSecret` +| `object` +| baseImagePullSecret is the secret used to pull the base image. +Must live in the openshift-machine-config-operator namespace if provided. +Defaults to using the cluster-wide pull secret if not specified. This is provided during install time of the cluster, and lives in the openshift-config namespace as a secret. + +| `containerFile` +| `array` +| containerFile describes the custom data the user has specified to build into the image. +This is also commonly called a Dockerfile and you can treat it as such. The content is the content of your Dockerfile. +See https://github.com/containers/common/blob/main/docs/Containerfile.5.md for the spec reference. +This is a list indexed by architecture name (e.g. AMD64), and allows specifying one containerFile per arch, up to 4. + +| `containerFile[]` +| `object` +| MachineOSContainerfile contains all custom content the user wants built into the image + +| `imageBuilder` +| `object` +| imageBuilder describes which image builder will be used in each build triggered by this MachineOSConfig. +Currently supported type(s): Job + +| `machineConfigPool` +| `object` +| machineConfigPool is the pool which the build is for. +The Machine Config Operator will perform the build and roll out the built image to the specified pool. + +| `renderedImagePushSecret` +| `object` +| renderedImagePushSecret is the secret used to connect to a user registry. +The final image push and pull secrets should be separate and assume the principal of least privilege. +The push secret with write privilege is only required to be present on the node hosting the MachineConfigController pod. +The pull secret with read only privileges is required on all nodes. +By separating the two secrets, the risk of write credentials becoming compromised is reduced. + +| `renderedImagePushSpec` +| `string` +| renderedImagePushSpec describes the location of the final image. +The MachineOSConfig object will use the in cluster image registry configuration. +If you wish to use a mirror or any other settings specific to registries.conf, please specify those in the cluster wide registries.conf via the cluster image.config, ImageContentSourcePolicies, ImageDigestMirrorSet, or ImageTagMirrorSet objects. +The format of the image push spec is: host[:port][/namespace]/name: or svc_name.namespace.svc[:port]/repository/name:. +The length of the push spec must be between 1 to 447 characters. + +|=== +=== .spec.baseImagePullSecret +Description:: ++ +-- +baseImagePullSecret is the secret used to pull the base image. +Must live in the openshift-machine-config-operator namespace if provided. +Defaults to using the cluster-wide pull secret if not specified. This is provided during install time of the cluster, and lives in the openshift-config namespace as a secret. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is the name of the secret used to push or pull this MachineOSConfig object. +Must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character. +This secret must be in the openshift-machine-config-operator namespace. + +|=== +=== .spec.containerFile +Description:: ++ +-- +containerFile describes the custom data the user has specified to build into the image. +This is also commonly called a Dockerfile and you can treat it as such. The content is the content of your Dockerfile. +See https://github.com/containers/common/blob/main/docs/Containerfile.5.md for the spec reference. +This is a list indexed by architecture name (e.g. AMD64), and allows specifying one containerFile per arch, up to 4. +-- + +Type:: + `array` + + + + +=== .spec.containerFile[] +Description:: ++ +-- +MachineOSContainerfile contains all custom content the user wants built into the image +-- + +Type:: + `object` + +Required:: + - `content` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `containerfileArch` +| `string` +| containerfileArch describes the architecture this containerfile is to be built for. +This arch is optional. If the user does not specify an architecture, it is assumed +that the content can be applied to all architectures, or in a single arch cluster: the only architecture. + +| `content` +| `string` +| content is an embedded Containerfile/Dockerfile that defines the contents to be built into your image. +See https://github.com/containers/common/blob/main/docs/Containerfile.5.md for the spec reference. +for example, this would add the tree package to your hosts: + FROM configs AS final + RUN rpm-ostree install tree && \ + ostree container commit +This is a required field and can have a maximum length of **4096** characters. + +|=== +=== .spec.imageBuilder +Description:: ++ +-- +imageBuilder describes which image builder will be used in each build triggered by this MachineOSConfig. +Currently supported type(s): Job +-- + +Type:: + `object` + +Required:: + - `imageBuilderType` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `imageBuilderType` +| `string` +| imageBuilderType specifies the backend to be used to build the image. +Valid options are: Job + +|=== +=== .spec.machineConfigPool +Description:: ++ +-- +machineConfigPool is the pool which the build is for. +The Machine Config Operator will perform the build and roll out the built image to the specified pool. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name of the MachineConfigPool object. +This value should be at most 253 characters, and must contain only lowercase +alphanumeric characters, hyphens and periods, and should start and end with an alphanumeric character. + +|=== +=== .spec.renderedImagePushSecret +Description:: ++ +-- +renderedImagePushSecret is the secret used to connect to a user registry. +The final image push and pull secrets should be separate and assume the principal of least privilege. +The push secret with write privilege is only required to be present on the node hosting the MachineConfigController pod. +The pull secret with read only privileges is required on all nodes. +By separating the two secrets, the risk of write credentials becoming compromised is reduced. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is the name of the secret used to push or pull this MachineOSConfig object. +Must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character. +This secret must be in the openshift-machine-config-operator namespace. + +|=== +=== .status +Description:: ++ +-- +status describes the status of the machineosconfig +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| conditions are state related conditions for the object. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `currentImagePullSpec` +| `string` +| currentImagePullSpec is the fully qualified image pull spec used by the MCO to pull down the new OSImage. This includes the sha256 image digest. +This is generated when the Machine Config Operator's build controller successfully completes the build, and is populated from the corresponding +MachineOSBuild object's FinalImagePushSpec. This may change after completion in reaction to spec changes that would cause a new image build, +but will not be removed. +The format of the image pull spec is: host[:port][/namespace]/name@sha256:, +where the digest must be 64 characters long, and consist only of lowercase hexadecimal characters, a-f and 0-9. +The length of the whole spec must be between 1 to 447 characters. + +| `machineOSBuild` +| `object` +| machineOSBuild is a reference to the MachineOSBuild object for this MachineOSConfig, which contains the status for the image build. + +| `observedGeneration` +| `integer` +| observedGeneration represents the generation of the MachineOSConfig object observed by the Machine Config Operator's build controller. + +|=== +=== .status.conditions +Description:: ++ +-- +conditions are state related conditions for the object. +-- + +Type:: + `array` + + + + +=== .status.conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== +=== .status.machineOSBuild +Description:: ++ +-- +machineOSBuild is a reference to the MachineOSBuild object for this MachineOSConfig, which contains the status for the image build. +-- + +Type:: + `object` + +Required:: + - `group` + - `name` + - `resource` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| group of the referent. +The name must contain only lowercase alphanumeric characters, '-' or '.' and start/end with an alphanumeric character. +Example: "", "apps", "build.openshift.io", etc. + +| `name` +| `string` +| name of the referent. +The name must contain only lowercase alphanumeric characters, '-' or '.' and start/end with an alphanumeric character. + +| `namespace` +| `string` +| namespace of the referent. +This value should consist of at most 63 characters, and of only lowercase alphanumeric characters and hyphens, +and should start and end with an alphanumeric character. + +| `resource` +| `string` +| resource of the referent. +This value should consist of at most 63 characters, and of only lowercase alphanumeric characters and hyphens, +and should start and end with an alphanumeric character. +Example: "deployments", "deploymentconfigs", "pods", etc. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/machineconfiguration.openshift.io/v1/machineosconfigs` +- `DELETE`: delete collection of MachineOSConfig +- `GET`: list objects of kind MachineOSConfig +- `POST`: create a MachineOSConfig +* `/apis/machineconfiguration.openshift.io/v1/machineosconfigs/{name}` +- `DELETE`: delete a MachineOSConfig +- `GET`: read the specified MachineOSConfig +- `PATCH`: partially update the specified MachineOSConfig +- `PUT`: replace the specified MachineOSConfig +* `/apis/machineconfiguration.openshift.io/v1/machineosconfigs/{name}/status` +- `GET`: read status of the specified MachineOSConfig +- `PATCH`: partially update status of the specified MachineOSConfig +- `PUT`: replace status of the specified MachineOSConfig + + +=== /apis/machineconfiguration.openshift.io/v1/machineosconfigs + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of MachineOSConfig + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind MachineOSConfig + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-machineconfiguration-v1-MachineOSConfigList[`MachineOSConfigList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a MachineOSConfig + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 201 - Created +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 202 - Accepted +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/machineconfiguration.openshift.io/v1/machineosconfigs/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the MachineOSConfig +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a MachineOSConfig + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified MachineOSConfig + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified MachineOSConfig + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified MachineOSConfig + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 201 - Created +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/machineconfiguration.openshift.io/v1/machineosconfigs/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the MachineOSConfig +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified MachineOSConfig + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified MachineOSConfig + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified MachineOSConfig + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 201 - Created +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`MachineOSConfig`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/machine_apis/machineset-machine-openshift-io-v1beta1.adoc b/rest_api/machine_apis/machineset-machine-openshift-io-v1beta1.adoc index e748a191f4..2c5919b786 100644 --- a/rest_api/machine_apis/machineset-machine-openshift-io-v1beta1.adoc +++ b/rest_api/machine_apis/machineset-machine-openshift-io-v1beta1.adoc @@ -66,30 +66,30 @@ Type:: | `deletePolicy` | `string` -| DeletePolicy defines the policy used to identify nodes to delete when downscaling. +| deletePolicy defines the policy used to identify nodes to delete when downscaling. Defaults to "Random". Valid values are "Random, "Newest", "Oldest" | `minReadySeconds` | `integer` -| MinReadySeconds is the minimum number of seconds for which a newly created machine should be ready. +| minReadySeconds is the minimum number of seconds for which a newly created machine should be ready. Defaults to 0 (machine will be considered available as soon as it is ready) | `replicas` | `integer` -| Replicas is the number of desired replicas. +| replicas is the number of desired replicas. This is a pointer to distinguish between explicit zero and unspecified. Defaults to 1. | `selector` | `object` -| Selector is a label query over machines that should match the replica count. +| selector is a label query over machines that should match the replica count. Label keys and values that must match in order to be controlled by this MachineSet. It must match the machine template's labels. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors | `template` | `object` -| Template is the object that describes the machine that will be created if +| template is the object that describes the machine that will be created if insufficient replicas are detected. |=== @@ -97,7 +97,7 @@ insufficient replicas are detected. Description:: + -- -Selector is a label query over machines that should match the replica count. +selector is a label query over machines that should match the replica count. Label keys and values that must match in order to be controlled by this MachineSet. It must match the machine template's labels. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors @@ -184,7 +184,7 @@ merge patch. Description:: + -- -Template is the object that describes the machine that will be created if +template is the object that describes the machine that will be created if insufficient replicas are detected. -- @@ -229,14 +229,14 @@ Type:: | `annotations` | `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be +| annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations | `generateName` | `string` -| GenerateName is an optional prefix, used by the server, to generate a unique +| generateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. @@ -261,7 +261,7 @@ More info: http://kubernetes.io/docs/user-guide/labels | `name` | `string` -| Name must be unique within a namespace. Is required when creating resources, although +| name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. @@ -270,7 +270,7 @@ More info: http://kubernetes.io/docs/user-guide/identifiers#names | `namespace` | `string` -| Namespace defines the space within each name must be unique. An empty namespace is +| namespace defines the space within each name must be unique. An empty namespace is equivalent to the "default" namespace, but "default" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. @@ -388,7 +388,7 @@ Type:: | `lifecycleHooks` | `object` -| LifecycleHooks allow users to pause operations on the machine at +| lifecycleHooks allow users to pause operations on the machine at certain predefined points within the machine lifecycle. | `metadata` @@ -399,7 +399,7 @@ when creating the Node. | `providerID` | `string` -| ProviderID is the identification ID of the machine provided by the provider. +| providerID is the identification ID of the machine provided by the provider. This field must match the provider ID as seen on the node object corresponding to this machine. This field is required by higher level consumers of cluster-api. Example use case is cluster autoscaler with cluster-api as provider. Clean-up logic in the autoscaler compares machines to nodes to find out @@ -412,7 +412,7 @@ be interfacing with cluster-api as generic provider. | `providerSpec` | `object` -| ProviderSpec details Provider-specific configuration to use during node creation. +| providerSpec details Provider-specific configuration to use during node creation. | `taints` | `array` @@ -433,7 +433,7 @@ any pod that does not tolerate the Taint. Description:: + -- -LifecycleHooks allow users to pause operations on the machine at +lifecycleHooks allow users to pause operations on the machine at certain predefined points within the machine lifecycle. -- @@ -449,7 +449,7 @@ Type:: | `preDrain` | `array` -| PreDrain hooks prevent the machine from being drained. +| preDrain hooks prevent the machine from being drained. This also blocks further lifecycle events, such as termination. | `preDrain[]` @@ -458,7 +458,7 @@ This also blocks further lifecycle events, such as termination. | `preTerminate` | `array` -| PreTerminate hooks prevent the machine from being terminated. +| preTerminate hooks prevent the machine from being terminated. PreTerminate hooks be actioned after the Machine has been drained. | `preTerminate[]` @@ -470,7 +470,7 @@ PreTerminate hooks be actioned after the Machine has been drained. Description:: + -- -PreDrain hooks prevent the machine from being drained. +preDrain hooks prevent the machine from being drained. This also blocks further lifecycle events, such as termination. -- @@ -502,14 +502,14 @@ Required:: | `name` | `string` -| Name defines a unique name for the lifcycle hook. +| name defines a unique name for the lifcycle hook. The name should be unique and descriptive, ideally 1-3 words, in CamelCase or it may be namespaced, eg. foo.example.com/CamelCase. Names must be unique and should only be managed by a single entity. | `owner` | `string` -| Owner defines the owner of the lifecycle hook. +| owner defines the owner of the lifecycle hook. This should be descriptive enough so that users can identify who/what is responsible for blocking the lifecycle. This could be the name of a controller (e.g. clusteroperator/etcd) @@ -520,7 +520,7 @@ or an administrator managing the hook. Description:: + -- -PreTerminate hooks prevent the machine from being terminated. +preTerminate hooks prevent the machine from being terminated. PreTerminate hooks be actioned after the Machine has been drained. -- @@ -552,14 +552,14 @@ Required:: | `name` | `string` -| Name defines a unique name for the lifcycle hook. +| name defines a unique name for the lifcycle hook. The name should be unique and descriptive, ideally 1-3 words, in CamelCase or it may be namespaced, eg. foo.example.com/CamelCase. Names must be unique and should only be managed by a single entity. | `owner` | `string` -| Owner defines the owner of the lifecycle hook. +| owner defines the owner of the lifecycle hook. This should be descriptive enough so that users can identify who/what is responsible for blocking the lifecycle. This could be the name of a controller (e.g. clusteroperator/etcd) @@ -587,14 +587,14 @@ Type:: | `annotations` | `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be +| annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations | `generateName` | `string` -| GenerateName is an optional prefix, used by the server, to generate a unique +| generateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. @@ -619,7 +619,7 @@ More info: http://kubernetes.io/docs/user-guide/labels | `name` | `string` -| Name must be unique within a namespace. Is required when creating resources, although +| name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. @@ -628,7 +628,7 @@ More info: http://kubernetes.io/docs/user-guide/identifiers#names | `namespace` | `string` -| Namespace defines the space within each name must be unique. An empty namespace is +| namespace defines the space within each name must be unique. An empty namespace is equivalent to the "default" namespace, but "default" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. @@ -730,7 +730,7 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -ProviderSpec details Provider-specific configuration to use during node creation. +providerSpec details Provider-specific configuration to use during node creation. -- Type:: @@ -745,7 +745,7 @@ Type:: | `value` | `` -| Value is an inlined, serialized representation of the resource +| value is an inlined, serialized representation of the resource configuration. It is recommended that providers maintain their own versioned API types that should be serialized/deserialized from this field, akin to component config. @@ -833,7 +833,7 @@ Type:: | `conditions` | `array` -| Conditions defines the current state of the MachineSet +| conditions defines the current state of the MachineSet | `conditions[]` | `object` @@ -870,7 +870,7 @@ controller's output. | `observedGeneration` | `integer` -| ObservedGeneration reflects the generation of the most recently observed MachineSet. +| observedGeneration reflects the generation of the most recently observed MachineSet. | `readyReplicas` | `integer` @@ -878,14 +878,14 @@ controller's output. | `replicas` | `integer` -| Replicas is the most recently observed number of replicas. +| replicas is the most recently observed number of replicas. |=== === .status.conditions Description:: + -- -Conditions defines the current state of the MachineSet +conditions defines the current state of the MachineSet -- Type:: @@ -934,17 +934,17 @@ This field may not be empty. | `severity` | `string` -| Severity provides an explicit classification of Reason code, so the users or machines can immediately +| severity provides an explicit classification of Reason code, so the users or machines can immediately understand the current situation and act accordingly. The Severity field MUST be set only when Status=False. | `status` | `string` -| Status of the condition, one of True, False, Unknown. +| status of the condition, one of True, False, Unknown. | `type` | `string` -| Type of condition in CamelCase or in foo.example.com/CamelCase. +| type of condition in CamelCase or in foo.example.com/CamelCase. Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. diff --git a/rest_api/metadata_apis/binding-v1.adoc b/rest_api/metadata_apis/binding-v1.adoc index d3ffba56c7..e7cd525a7e 100644 --- a/rest_api/metadata_apis/binding-v1.adoc +++ b/rest_api/metadata_apis/binding-v1.adoc @@ -11,7 +11,7 @@ toc::[] Description:: + -- -Binding ties one object to another; for example, a pod is bound to a node by a scheduler. Deprecated in 1.7, please use the bindings subresource of pods instead. +Binding ties one object to another; for example, a pod is bound to a node by a scheduler. -- Type:: diff --git a/rest_api/metadata_apis/metadata-apis-index.adoc b/rest_api/metadata_apis/metadata-apis-index.adoc index 8643ec26cc..3c08eb5e54 100644 --- a/rest_api/metadata_apis/metadata-apis-index.adoc +++ b/rest_api/metadata_apis/metadata-apis-index.adoc @@ -24,7 +24,7 @@ Type:: Description:: + -- -Binding ties one object to another; for example, a pod is bound to a node by a scheduler. Deprecated in 1.7, please use the bindings subresource of pods instead. +Binding ties one object to another; for example, a pod is bound to a node by a scheduler. -- Type:: diff --git a/rest_api/metadata_apis/namespace-v1.adoc b/rest_api/metadata_apis/namespace-v1.adoc index 71503eaa83..5e7d76ed8b 100644 --- a/rest_api/metadata_apis/namespace-v1.adoc +++ b/rest_api/metadata_apis/namespace-v1.adoc @@ -137,15 +137,15 @@ Required:: | `lastTransitionTime` | xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Time[`Time`] -| +| Last time the condition transitioned from one status to another. | `message` | `string` -| +| Human-readable message indicating details about last transition. | `reason` | `string` -| +| Unique, one-word, CamelCase reason for the condition's last transition. | `status` | `string` diff --git a/rest_api/monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc index 4a6810ec7b..8b52d062b3 100644 --- a/rest_api/monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc @@ -137,6 +137,12 @@ You should only set it when the Alertmanager cluster includes Alertmanager insta | `string` | Interval between pushpull attempts. +| `clusterTLS` +| `object` +| Configures the mutual TLS configuration for the Alertmanager cluster's gossip protocol. + +It requires Alertmanager >= 0.24.0. + | `configMaps` | `array (string)` | ConfigMaps is a list of ConfigMaps in the same namespace as the Alertmanager @@ -191,6 +197,10 @@ that this behaviour may break at any time without notice. It requires Alertmanager >= 0.27.0. +| `enableServiceLinks` +| `boolean` +| Indicates whether information about services should be injected into pod's environment variables + | `externalUrl` | `string` | The external URL the Alertmanager instances will be available under. This is @@ -280,6 +290,13 @@ This is an alpha field from kubernetes 1.22 until 1.24 which requires enabling t | If set to true all actions on the underlying managed objects are not goint to be performed, except for delete actions. +| `persistentVolumeClaimRetentionPolicy` +| `object` +| The field controls if and how PVCs are deleted during the lifecycle of a StatefulSet. +The default behavior is all PVCs are retained. +This is an alpha field from kubernetes 1.23 until 1.26 and a beta field from 1.26. +It requires enabling the StatefulSetAutoDeletePVC feature gate. + | `podMetadata` | `object` | PodMetadata configures labels and annotations which are propagated to the Alertmanager pods. @@ -340,6 +357,14 @@ This defaults to the default PodSecurityContext. | ServiceAccountName is the name of the ServiceAccount to use to run the Prometheus Pods. +| `serviceName` +| `string` +| The name of the service name used by the underlying StatefulSet(s) as the governing service. +If defined, the Service must be created before the Alertmanager resource in the same namespace and it must define a selector that matches the pod labels. +If empty, the operator will create and manage a headless service named `alertmanager-operated` for Alermanager resources. +When deploying multiple Alertmanager resources in the same namespace, it is recommended to specify a different value for each. +See https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#stable-network-id for more details. + | `sha` | `string` | SHA of Alertmanager container image to be deployed. Defaults to the value of `version`. @@ -3931,6 +3956,665 @@ Required:: +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key of the secret to select from. Must be a valid secret key. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the Secret or its key must be defined + +|=== +=== .spec.clusterTLS +Description:: ++ +-- +Configures the mutual TLS configuration for the Alertmanager cluster's gossip protocol. + +It requires Alertmanager >= 0.24.0. +-- + +Type:: + `object` + +Required:: + - `client` + - `server` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `client` +| `object` +| Client-side configuration for mutual TLS. + +| `server` +| `object` +| Server-side configuration for mutual TLS. + +|=== +=== .spec.clusterTLS.client +Description:: ++ +-- +Client-side configuration for mutual TLS. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `ca` +| `object` +| Certificate authority used when verifying server certificates. + +| `cert` +| `object` +| Client certificate to present when doing client-authentication. + +| `insecureSkipVerify` +| `boolean` +| Disable target certificate validation. + +| `keySecret` +| `object` +| Secret containing the client key file for the targets. + +| `maxVersion` +| `string` +| Maximum acceptable TLS version. + +It requires Prometheus >= v2.41.0. + +| `minVersion` +| `string` +| Minimum acceptable TLS version. + +It requires Prometheus >= v2.35.0. + +| `serverName` +| `string` +| Used to verify the hostname for the targets. + +|=== +=== .spec.clusterTLS.client.ca +Description:: ++ +-- +Certificate authority used when verifying server certificates. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `configMap` +| `object` +| ConfigMap containing data to use for the targets. + +| `secret` +| `object` +| Secret containing data to use for the targets. + +|=== +=== .spec.clusterTLS.client.ca.configMap +Description:: ++ +-- +ConfigMap containing data to use for the targets. +-- + +Type:: + `object` + +Required:: + - `key` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key to select. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the ConfigMap or its key must be defined + +|=== +=== .spec.clusterTLS.client.ca.secret +Description:: ++ +-- +Secret containing data to use for the targets. +-- + +Type:: + `object` + +Required:: + - `key` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key of the secret to select from. Must be a valid secret key. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the Secret or its key must be defined + +|=== +=== .spec.clusterTLS.client.cert +Description:: ++ +-- +Client certificate to present when doing client-authentication. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `configMap` +| `object` +| ConfigMap containing data to use for the targets. + +| `secret` +| `object` +| Secret containing data to use for the targets. + +|=== +=== .spec.clusterTLS.client.cert.configMap +Description:: ++ +-- +ConfigMap containing data to use for the targets. +-- + +Type:: + `object` + +Required:: + - `key` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key to select. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the ConfigMap or its key must be defined + +|=== +=== .spec.clusterTLS.client.cert.secret +Description:: ++ +-- +Secret containing data to use for the targets. +-- + +Type:: + `object` + +Required:: + - `key` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key of the secret to select from. Must be a valid secret key. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the Secret or its key must be defined + +|=== +=== .spec.clusterTLS.client.keySecret +Description:: ++ +-- +Secret containing the client key file for the targets. +-- + +Type:: + `object` + +Required:: + - `key` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key of the secret to select from. Must be a valid secret key. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the Secret or its key must be defined + +|=== +=== .spec.clusterTLS.server +Description:: ++ +-- +Server-side configuration for mutual TLS. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `cert` +| `object` +| Secret or ConfigMap containing the TLS certificate for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `certFile`. + +| `certFile` +| `string` +| Path to the TLS certificate file in the container for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `cert`. + +| `cipherSuites` +| `array (string)` +| List of supported cipher suites for TLS versions up to TLS 1.2. + +If not defined, the Go default cipher suites are used. +Available cipher suites are documented in the Go documentation: +https://golang.org/pkg/crypto/tls/#pkg-constants + +| `clientAuthType` +| `string` +| The server policy for client TLS authentication. + +For more detail on clientAuth options: +https://golang.org/pkg/crypto/tls/#ClientAuthType + +| `clientCAFile` +| `string` +| Path to the CA certificate file for client certificate authentication to +the server. + +It is mutually exclusive with `client_ca`. + +| `client_ca` +| `object` +| Secret or ConfigMap containing the CA certificate for client certificate +authentication to the server. + +It is mutually exclusive with `clientCAFile`. + +| `curvePreferences` +| `array (string)` +| Elliptic curves that will be used in an ECDHE handshake, in preference +order. + +Available curves are documented in the Go documentation: +https://golang.org/pkg/crypto/tls/#CurveID + +| `keyFile` +| `string` +| Path to the TLS private key file in the container for the web server. + +If defined, either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keySecret`. + +| `keySecret` +| `object` +| Secret containing the TLS private key for the web server. + +Either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keyFile`. + +| `maxVersion` +| `string` +| Maximum TLS version that is acceptable. + +| `minVersion` +| `string` +| Minimum TLS version that is acceptable. + +| `preferServerCipherSuites` +| `boolean` +| Controls whether the server selects the client's most preferred cipher +suite, or the server's most preferred cipher suite. + +If true then the server's preference, as expressed in +the order of elements in cipherSuites, is used. + +|=== +=== .spec.clusterTLS.server.cert +Description:: ++ +-- +Secret or ConfigMap containing the TLS certificate for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `certFile`. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `configMap` +| `object` +| ConfigMap containing data to use for the targets. + +| `secret` +| `object` +| Secret containing data to use for the targets. + +|=== +=== .spec.clusterTLS.server.cert.configMap +Description:: ++ +-- +ConfigMap containing data to use for the targets. +-- + +Type:: + `object` + +Required:: + - `key` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key to select. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the ConfigMap or its key must be defined + +|=== +=== .spec.clusterTLS.server.cert.secret +Description:: ++ +-- +Secret containing data to use for the targets. +-- + +Type:: + `object` + +Required:: + - `key` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key of the secret to select from. Must be a valid secret key. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the Secret or its key must be defined + +|=== +=== .spec.clusterTLS.server.client_ca +Description:: ++ +-- +Secret or ConfigMap containing the CA certificate for client certificate +authentication to the server. + +It is mutually exclusive with `clientCAFile`. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `configMap` +| `object` +| ConfigMap containing data to use for the targets. + +| `secret` +| `object` +| Secret containing data to use for the targets. + +|=== +=== .spec.clusterTLS.server.client_ca.configMap +Description:: ++ +-- +ConfigMap containing data to use for the targets. +-- + +Type:: + `object` + +Required:: + - `key` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key to select. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the ConfigMap or its key must be defined + +|=== +=== .spec.clusterTLS.server.client_ca.secret +Description:: ++ +-- +Secret containing data to use for the targets. +-- + +Type:: + `object` + +Required:: + - `key` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key of the secret to select from. Must be a valid secret key. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the Secret or its key must be defined + +|=== +=== .spec.clusterTLS.server.keySecret +Description:: ++ +-- +Secret containing the TLS private key for the web server. + +Either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keyFile`. +-- + +Type:: + `object` + +Required:: + - `key` + + + [cols="1,1,1",options="header"] |=== | Property | Type | Description @@ -4595,28 +5279,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.containers[].lifecycle.postStart.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -4642,7 +5326,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -4733,7 +5417,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -4758,8 +5442,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -4812,28 +5496,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.containers[].lifecycle.preStop.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -4859,7 +5543,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -4950,7 +5634,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -4975,8 +5659,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -5024,7 +5708,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -5033,11 +5717,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -5056,7 +5740,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -5082,7 +5766,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -5108,7 +5792,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -5139,7 +5823,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -5230,7 +5914,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -5344,7 +6028,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -5353,11 +6037,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -5376,7 +6060,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -5402,7 +6086,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -5428,7 +6112,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -5459,7 +6143,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -5550,7 +6234,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -6039,7 +6723,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -6048,11 +6732,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -6071,7 +6755,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -6097,7 +6781,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -6123,7 +6807,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -6154,7 +6838,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -6245,7 +6929,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -7214,28 +7898,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.initContainers[].lifecycle.postStart.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -7261,7 +7945,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -7352,7 +8036,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -7377,8 +8061,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -7431,28 +8115,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.initContainers[].lifecycle.preStop.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -7478,7 +8162,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -7569,7 +8253,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -7594,8 +8278,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -7643,7 +8327,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -7652,11 +8336,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -7675,7 +8359,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -7701,7 +8385,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -7727,7 +8411,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -7758,7 +8442,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -7849,7 +8533,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -7963,7 +8647,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -7972,11 +8656,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -7995,7 +8679,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -8021,7 +8705,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -8047,7 +8731,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -8078,7 +8762,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -8169,7 +8853,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -8658,7 +9342,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -8667,11 +9351,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -8690,7 +9374,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -8716,7 +9400,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -8742,7 +9426,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -8773,7 +9457,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -8864,7 +9548,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -9020,6 +9704,42 @@ Behaves similarly to SubPath but environment variable references $(VAR_NAME) are Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. +|=== +=== .spec.persistentVolumeClaimRetentionPolicy +Description:: ++ +-- +The field controls if and how PVCs are deleted during the lifecycle of a StatefulSet. +The default behavior is all PVCs are retained. +This is an alpha field from kubernetes 1.23 until 1.26 and a beta field from 1.26. +It requires enabling the StatefulSetAutoDeletePVC feature gate. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `whenDeleted` +| `string` +| WhenDeleted specifies what happens to PVCs created from StatefulSet +VolumeClaimTemplates when the StatefulSet is deleted. The default policy +of `Retain` causes PVCs to not be affected by StatefulSet deletion. The +`Delete` policy causes those PVCs to be deleted. + +| `whenScaled` +| `string` +| WhenScaled specifies what happens to PVCs created from StatefulSet +VolumeClaimTemplates when the StatefulSet is scaled down. The default +policy of `Retain` causes PVCs to not be affected by a scaledown. The +`Delete` policy causes the associated PVCs for any excess pods above +the replica count to be deleted. + |=== === .spec.podMetadata Description:: @@ -9238,6 +9958,32 @@ PodSecurityContext, the value specified in SecurityContext takes precedence for that container. Note that this field cannot be set when spec.os.name is windows. +| `seLinuxChangePolicy` +| `string` +| seLinuxChangePolicy defines how the container's SELinux label is applied to all volumes used by the Pod. +It has no effect on nodes that do not support SELinux or to volumes does not support SELinux. +Valid values are "MountOption" and "Recursive". + +"Recursive" means relabeling of all files on all Pod volumes by the container runtime. +This may be slow for large volumes, but allows mixing privileged and unprivileged Pods sharing the same volume on the same node. + +"MountOption" mounts all eligible Pod volumes with `-o context` mount option. +This requires all Pods that share the same volume to use the same SELinux label. +It is not possible to share the same volume among privileged and unprivileged Pods. +Eligible volumes are in-tree FibreChannel and iSCSI volumes, and all CSI volumes +whose CSI driver announces SELinux support by setting spec.seLinuxMount: true in their +CSIDriver instance. Other volumes are always re-labelled recursively. +"MountOption" value is allowed only when SELinuxMount feature gate is enabled. + +If not specified and SELinuxMount feature gate is enabled, "MountOption" is used. +If not specified and SELinuxMount feature gate is disabled, "MountOption" is used for ReadWriteOncePod volumes +and "Recursive" for all other volumes. + +This field affects only Pods that have SELinux label set, either in PodSecurityContext or in SecurityContext of all containers. + +All Pods that use the same volume should use the same seLinuxChangePolicy, otherwise some pods can get stuck in ContainerCreating state. +Note that this field cannot be set when spec.os.name is windows. + | `seLinuxOptions` | `object` | The SELinux context to be applied to all containers. @@ -10592,19 +11338,14 @@ persistent volume is being resized. | `status` | `string` -| +| Status is the status of the condition. +Can be True, False, Unknown. +More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=state%20of%20pvc-,conditions.status,-(string)%2C%20required | `type` | `string` -| PersistentVolumeClaimConditionType defines the condition of PV claim. -Valid values are: - - "Resizing", "FileSystemResizePending" - -If RecoverVolumeExpansionFailure feature gate is enabled, then following additional values can be expected: - - "ControllerResizeError", "NodeResizeError" - -If VolumeAttributesClass feature gate is enabled, then following additional values can be expected: - - "ModifyVolumeError", "ModifyingVolume" +| Type is the type of the condition. +More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=set%20to%20%27ResizeStarted%27.-,PersistentVolumeClaimCondition,-contains%20details%20about |=== === .spec.storage.volumeClaimTemplate.status.modifyVolumeStatus @@ -11072,23 +11813,32 @@ Required:: | `object` | awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree +awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore | `azureDisk` | `object` | azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type +are redirected to the disk.csi.azure.com CSI driver. | `azureFile` | `object` | azureFile represents an Azure File Service mount on the host and bind mount to the pod. +Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type +are redirected to the file.csi.azure.com CSI driver. | `cephfs` | `object` -| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. +Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. | `cinder` | `object` | cinder represents a cinder volume attached and mounted on kubelets host machine. +Deprecated: Cinder is deprecated. All operations for the in-tree cinder type +are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `configMap` @@ -11097,7 +11847,7 @@ More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `csi` | `object` -| csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). +| csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers. | `downwardAPI` | `object` @@ -11143,27 +11893,32 @@ persistent volumes at the same time. | `object` | flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. | `flocker` | `object` -| flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running +| flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running. +Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. | `gcePersistentDisk` | `object` | gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree +gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk | `gitRepo` | `object` | gitRepo represents a git repository at a particular revision. -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an +Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. | `glusterfs` | `object` | glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. +Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md | `hostPath` @@ -11216,11 +11971,15 @@ More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persis | `photonPersistentDisk` | `object` -| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. +Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. | `portworxVolume` | `object` -| portworxVolume represents a portworx volume attached and mounted on kubelets host machine +| portworxVolume represents a portworx volume attached and mounted on kubelets host machine. +Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type +are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate +is on. | `projected` | `object` @@ -11228,16 +11987,19 @@ More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persis | `quobyte` | `object` -| quobyte represents a Quobyte mount on the host that shares a pod's lifetime +| quobyte represents a Quobyte mount on the host that shares a pod's lifetime. +Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. | `rbd` | `object` | rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. +Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md | `scaleIO` | `object` | scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. | `secret` | `object` @@ -11247,10 +12009,13 @@ More info: https://kubernetes.io/docs/concepts/storage/volumes#secret | `storageos` | `object` | storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. +Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. | `vsphereVolume` | `object` -| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. +Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type +are redirected to the csi.vsphere.vmware.com CSI driver. |=== === .spec.volumes[].awsElasticBlockStore @@ -11259,6 +12024,8 @@ Description:: -- awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree +awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore -- @@ -11304,6 +12071,8 @@ Description:: + -- azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type +are redirected to the disk.csi.azure.com CSI driver. -- Type:: @@ -11352,6 +12121,8 @@ Description:: + -- azureFile represents an Azure File Service mount on the host and bind mount to the pod. +Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type +are redirected to the file.csi.azure.com CSI driver. -- Type:: @@ -11385,7 +12156,8 @@ the ReadOnly setting in VolumeMounts. Description:: + -- -cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. +Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. -- Type:: @@ -11463,6 +12235,8 @@ Description:: + -- cinder represents a cinder volume attached and mounted on kubelets host machine. +Deprecated: Cinder is deprecated. All operations for the in-tree cinder type +are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md -- @@ -11647,7 +12421,7 @@ May not start with the string '..'. Description:: + -- -csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). +csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers. -- Type:: @@ -12418,6 +13192,7 @@ Description:: -- flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. -- Type:: @@ -12494,7 +13269,8 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running +flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running. +Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. -- Type:: @@ -12523,6 +13299,8 @@ Description:: -- gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree +gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk -- @@ -12570,7 +13348,7 @@ Description:: + -- gitRepo represents a git repository at a particular revision. -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an +Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. -- @@ -12608,6 +13386,7 @@ Description:: + -- glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. +Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md -- @@ -12902,7 +13681,8 @@ Default false. Description:: + -- -photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. +Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. -- Type:: @@ -12932,7 +13712,10 @@ Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. Description:: + -- -portworxVolume represents a portworx volume attached and mounted on kubelets host machine +portworxVolume represents a portworx volume attached and mounted on kubelets host machine. +Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type +are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate +is on. -- Type:: @@ -13609,7 +14392,8 @@ token into. Description:: + -- -quobyte represents a Quobyte mount on the host that shares a pod's lifetime +quobyte represents a Quobyte mount on the host that shares a pod's lifetime. +Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. -- Type:: @@ -13661,6 +14445,7 @@ Description:: + -- rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. +Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md -- @@ -13760,6 +14545,7 @@ Description:: + -- scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. -- Type:: @@ -13968,6 +14754,7 @@ Description:: + -- storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. +Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. -- Type:: @@ -14042,7 +14829,9 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. +Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type +are redirected to the csi.vsphere.vmware.com CSI driver. -- Type:: @@ -14080,7 +14869,7 @@ Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. Description:: + -- -Defines the web command-line flags when starting Alertmanager. +Defines the web command line flags when starting Alertmanager. -- Type:: @@ -14209,62 +14998,87 @@ Type:: | `cert` | `object` -| Contains the TLS certificate for the server. +| Secret or ConfigMap containing the TLS certificate for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `certFile`. | `certFile` | `string` -| Path to the TLS certificate file in the Prometheus container for the server. -Mutually exclusive with `cert`. +| Path to the TLS certificate file in the container for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `cert`. | `cipherSuites` | `array (string)` -| List of supported cipher suites for TLS versions up to TLS 1.2. If empty, -Go default cipher suites are used. Available cipher suites are documented -in the go documentation: https://golang.org/pkg/crypto/tls/#pkg-constants +| List of supported cipher suites for TLS versions up to TLS 1.2. + +If not defined, the Go default cipher suites are used. +Available cipher suites are documented in the Go documentation: +https://golang.org/pkg/crypto/tls/#pkg-constants | `clientAuthType` | `string` -| Server policy for client authentication. Maps to ClientAuth Policies. +| The server policy for client TLS authentication. + For more detail on clientAuth options: https://golang.org/pkg/crypto/tls/#ClientAuthType | `clientCAFile` | `string` -| Path to the CA certificate file for client certificate authentication to the server. -Mutually exclusive with `client_ca`. +| Path to the CA certificate file for client certificate authentication to +the server. + +It is mutually exclusive with `client_ca`. | `client_ca` | `object` -| Contains the CA certificate for client certificate authentication to the server. +| Secret or ConfigMap containing the CA certificate for client certificate +authentication to the server. + +It is mutually exclusive with `clientCAFile`. | `curvePreferences` | `array (string)` | Elliptic curves that will be used in an ECDHE handshake, in preference -order. Available curves are documented in the go documentation: +order. + +Available curves are documented in the Go documentation: https://golang.org/pkg/crypto/tls/#CurveID | `keyFile` | `string` -| Path to the TLS key file in the Prometheus container for the server. -Mutually exclusive with `keySecret`. +| Path to the TLS private key file in the container for the web server. + +If defined, either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keySecret`. | `keySecret` | `object` -| Secret containing the TLS key for the server. +| Secret containing the TLS private key for the web server. + +Either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keyFile`. | `maxVersion` | `string` -| Maximum TLS version that is acceptable. Defaults to TLS13. +| Maximum TLS version that is acceptable. | `minVersion` | `string` -| Minimum TLS version that is acceptable. Defaults to TLS12. +| Minimum TLS version that is acceptable. | `preferServerCipherSuites` | `boolean` -| Controls whether the server selects the -client's most preferred cipher suite, or the server's most preferred -cipher suite. If true then the server's preference, as expressed in +| Controls whether the server selects the client's most preferred cipher +suite, or the server's most preferred cipher suite. + +If true then the server's preference, as expressed in the order of elements in cipherSuites, is used. |=== @@ -14272,7 +15086,11 @@ the order of elements in cipherSuites, is used. Description:: + -- -Contains the TLS certificate for the server. +Secret or ConfigMap containing the TLS certificate for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `certFile`. -- Type:: @@ -14370,7 +15188,10 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -Contains the CA certificate for client certificate authentication to the server. +Secret or ConfigMap containing the CA certificate for client certificate +authentication to the server. + +It is mutually exclusive with `clientCAFile`. -- Type:: @@ -14468,7 +15289,11 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -Secret containing the TLS key for the server. +Secret containing the TLS private key for the web server. + +Either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keyFile`. -- Type:: diff --git a/rest_api/monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1beta1.adoc b/rest_api/monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1beta1.adoc index 3f3a2e72d2..fdd8c0ae2d 100644 --- a/rest_api/monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1beta1.adoc +++ b/rest_api/monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1beta1.adoc @@ -575,6 +575,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -2315,6 +2321,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -3719,6 +3731,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -5122,6 +5140,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -6577,6 +6601,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -8162,6 +8192,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -9434,6 +9470,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -10742,6 +10784,11 @@ It requires Alertmanager >= v0.26.0. | `string` | Message template +| `messageThreadID` +| `integer` +| The Telegram Group Topic ID. +It requires Alertmanager >= 0.26.0. + | `parseMode` | `string` | Parse mode for telegram message @@ -10855,6 +10902,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -12202,6 +12255,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -13454,6 +13513,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -14707,6 +14772,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. @@ -16045,6 +16116,12 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +| `proxyURL` +| `string` +| Optional proxy URL. + +If defined, this field takes precedence over `proxyUrl`. + | `proxyUrl` | `string` | `proxyURL` defines the HTTP proxy server to use. diff --git a/rest_api/monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc index 70e34bc974..83b950c588 100644 --- a/rest_api/monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc @@ -84,6 +84,12 @@ of uncompressed response body that will be accepted by Prometheus. It requires Prometheus >= v2.28.0. +| `fallbackScrapeProtocol` +| `string` +| The protocol to use if a scrape returns blank, unparseable, or otherwise invalid Content-Type. + +It requires Prometheus >= v3.0.0. + | `jobLabel` | `string` | The label to use to retrieve the job name from. @@ -180,6 +186,15 @@ It requires Prometheus >= v2.49.0. | `object` | Label selector to select the Kubernetes `Pod` objects to scrape metrics from. +| `selectorMechanism` +| `string` +| Mechanism used to select the endpoints to scrape. +By default, the selection process relies on relabel configurations to filter the discovered targets. +Alternatively, you can opt in for role selectors, which may offer better efficiency in large clusters. +Which strategy is best for your use case needs to be carefully evaluated. + +It requires Prometheus >= v2.17.0. + | `targetLimit` | `integer` | `targetLimit` defines a limit on the number of scraped targets that will @@ -356,7 +371,7 @@ Cannot be set at the same time as `authorization`, or `basicAuth`. | `params{}` | `array (string)` -| +| | `path` | `string` @@ -366,9 +381,13 @@ If empty, Prometheus uses the default value (e.g. `/metrics`). | `port` | `string` -| Name of the Pod port which this endpoint refers to. +| The `Pod` port name which exposes the endpoint. -It takes precedence over `targetPort`. +It takes precedence over the `portNumber` and `targetPort` fields. + +| `portNumber` +| `integer` +| The `Pod` port number which exposes the endpoint. | `proxyUrl` | `string` @@ -382,7 +401,7 @@ metadata labels. The Operator automatically adds relabelings for a few standard Kubernetes fields. -The original scrape job's name is available via the `\__tmp_prometheus_job_name` label. +The original scrape job's name is available via the `__tmp_prometheus_job_name` label. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config @@ -408,13 +427,14 @@ If empty, Prometheus uses the default value `http`. If empty, Prometheus uses the global scrape timeout unless it is less than the target's scrape interval value in which the latter is used. +The value cannot be greater than the scrape interval otherwise the operator will reject the resource. | `targetPort` | `integer-or-string` | Name or number of the target port of the `Pod` object behind the Service, the port must be specified with container port property. -Deprecated: use 'port' instead. +Deprecated: use 'port' or 'portNumber' instead. | `tlsConfig` | `object` @@ -780,7 +800,7 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. | `proxyConnectHeader{}` | `array` -| +| | `proxyConnectHeader{}[]` | `object` @@ -1316,7 +1336,7 @@ metadata labels. The Operator automatically adds relabelings for a few standard Kubernetes fields. -The original scrape job's name is available via the `\__tmp_prometheus_job_name` label. +The original scrape job's name is available via the `__tmp_prometheus_job_name` label. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config -- @@ -1866,7 +1886,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor`] schema -| +| |=== .HTTP responses @@ -1999,7 +2019,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor`] schema -| +| |=== .HTTP responses diff --git a/rest_api/monitoring_apis/probe-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/probe-monitoring-coreos-com-v1.adoc index db3c6a967f..02212aa576 100644 --- a/rest_api/monitoring_apis/probe-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/probe-monitoring-coreos-com-v1.adoc @@ -82,6 +82,12 @@ More info: https://prometheus.io/docs/operating/configuration/#endpoint needs to be in the same namespace as the probe and accessible by the Prometheus Operator. +| `fallbackScrapeProtocol` +| `string` +| The protocol to use if a scrape returns blank, unparseable, or otherwise invalid Content-Type. + +It requires Prometheus >= v3.0.0. + | `interval` | `string` | Interval at which targets are probed using the configured prober. @@ -177,6 +183,7 @@ It requires Prometheus >= v2.49.0. | `string` | Timeout for scraping metrics from the Prometheus exporter. If not specified, the Prometheus global scrape timeout is used. +The value cannot be greater than the scrape interval otherwise the operator will reject the resource. | `targetLimit` | `integer` @@ -530,7 +537,7 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. | `proxyConnectHeader{}` | `array` -| +| | `proxyConnectHeader{}[]` | `object` @@ -1143,9 +1150,9 @@ Type:: | RelabelConfigs to apply to the label set of the target before it gets scraped. The original ingress address is available via the -`\__tmp_prometheus_ingress_address` label. It can be used to customize the +`__tmp_prometheus_ingress_address` label. It can be used to customize the probed URL. -The original scrape job's name is available via the `\__tmp_prometheus_job_name` label. +The original scrape job's name is available via the `__tmp_prometheus_job_name` label. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config | `relabelingConfigs[]` @@ -1194,9 +1201,9 @@ Description:: RelabelConfigs to apply to the label set of the target before it gets scraped. The original ingress address is available via the -`\__tmp_prometheus_ingress_address` label. It can be used to customize the +`__tmp_prometheus_ingress_address` label. It can be used to customize the probed URL. -The original scrape job's name is available via the `\__tmp_prometheus_job_name` label. +The original scrape job's name is available via the `__tmp_prometheus_job_name` label. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config -- @@ -1868,7 +1875,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe`] schema -| +| |=== .HTTP responses @@ -2001,7 +2008,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe`] schema -| +| |=== .HTTP responses diff --git a/rest_api/monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc index 42fbb3934b..ec75dc3885 100644 --- a/rest_api/monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc @@ -228,6 +228,8 @@ may break at any time without notice. | `disableCompaction` | `boolean` | When true, the Prometheus compaction is disabled. +When `spec.thanos.objectStorageConfig` or `spec.objectStorageConfigFile` are defined, the operator automatically +disables block compaction to avoid race conditions during block uploads (as the Thanos documentation recommends). | `dnsConfig` | `object` @@ -259,6 +261,14 @@ that this behaviour may break at any time without notice. For more information see https://prometheus.io/docs/prometheus/latest/feature_flags/ +| `enableOTLPReceiver` +| `boolean` +| Enable Prometheus to be used as a receiver for the OTLP Metrics protocol. + +Note that the OTLP receiver endpoint is automatically enabled if `.spec.otlpConfig` is defined. + +It requires Prometheus >= v2.47.0. + | `enableRemoteWriteReceiver` | `boolean` | Enable Prometheus to be used as a receiver for the Prometheus remote @@ -272,6 +282,10 @@ For more information see https://prometheus.io/docs/prometheus/latest/querying/a It requires Prometheus >= v2.33.0. +| `enableServiceLinks` +| `boolean` +| Indicates whether information about services should be injected into pod's environment variables + | `enforcedBodySizeLimit` | `string` | When defined, enforcedBodySizeLimit specifies a global limit on the size @@ -569,6 +583,10 @@ Defaults to 0 (pod will be considered available as soon as it is ready) This is an alpha field from kubernetes 1.22 until 1.24 which requires enabling the StatefulSetMinReadySeconds feature gate. +| `nameValidationScheme` +| `string` +| Specifies the validation scheme for metric and label names. + | `nodeSelector` | `object (string)` | Defines on which Nodes the Pods are scheduled. @@ -823,7 +841,7 @@ in a breaking way. | `scrapeClasses[]` | `object` -| +| | `scrapeConfigNamespaceSelector` | `object` @@ -849,6 +867,17 @@ of the custom resource definition. It is recommended to use Note that the ScrapeConfig custom resource definition is currently at Alpha level. +| `scrapeFailureLogFile` +| `string` +| File to which scrape failures are logged. +Reloading the configuration will reopen the file. + +If the filename has an empty path, e.g. 'file.log', The Prometheus Pods +will mount the file into an emptyDir volume at `/var/log/prometheus`. +If a full path is provided, e.g. '/var/log/prometheus/file.log', you +must mount a volume in the specified directory and it must be writable. +It requires Prometheus >= v2.55.0. + | `scrapeInterval` | `string` | Interval between consecutive scrapes. @@ -864,9 +893,12 @@ If unset, Prometheus uses its default value. It requires Prometheus >= v2.49.0. +`PrometheusText1.0.0` requires Prometheus >= v3.0.0. + | `scrapeTimeout` | `string` | Number of seconds to wait until a scrape request times out. +The value cannot be greater than the scrape interval otherwise the operator will reject the resource. | `secrets` | `array (string)` @@ -913,25 +945,52 @@ This behavior is *deprecated* and will be removed in the next major version of the custom resource definition. It is recommended to use `spec.additionalScrapeConfigs` instead. +| `serviceName` +| `string` +| The name of the service name used by the underlying StatefulSet(s) as the governing service. +If defined, the Service must be created before the Prometheus/PrometheusAgent resource in the same namespace and it must define a selector that matches the pod labels. +If empty, the operator will create and manage a headless service named `prometheus-operated` for Prometheus resources, +or `prometheus-agent-operated` for PrometheusAgent resources. +When deploying multiple Prometheus/PrometheusAgent resources in the same namespace, it is recommended to specify a different value for each. +See https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#stable-network-id for more details. + | `sha` | `string` | Deprecated: use 'spec.image' instead. The image's digest can be specified as part of the image name. +| `shardRetentionPolicy` +| `object` +| ShardRetentionPolicy defines the retention policy for the Prometheus shards. +(Alpha) Using this field requires the 'PrometheusShardRetentionPolicy' feature gate to be enabled. + +The final goals for this feature can be seen at https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/proposals/202310-shard-autoscaling.md#graceful-scale-down-of-prometheus-servers, +however, the feature is not yet fully implemented in this PR. The limitation being: +* Retention duration is not settable, for now, shards are retained forever. + | `shards` | `integer` -| Number of shards to distribute targets onto. `spec.replicas` -multiplied by `spec.shards` is the total number of Pods created. +| Number of shards to distribute the scraped targets onto. -Note that scaling down shards will not reshard data onto remaining +`spec.replicas` multiplied by `spec.shards` is the total number of Pods +being created. + +When not defined, the operator assumes only one shard. + +Note that scaling down shards will not reshard data onto the remaining instances, it must be manually moved. Increasing shards will not reshard data either but it will continue to be available from the same -instances. To query globally, use Thanos sidecar and Thanos querier or -remote write data to a central location. +instances. To query globally, use either +* Thanos sidecar + querier for query federation and Thanos Ruler for rules. +* Remote-write to send metrics to a central location. -Sharding is performed on the content of the `__address__` target meta-label -for PodMonitors and ServiceMonitors and `__param_target__` for Probes. +By default, the sharding of targets is performed on: +* The `__address__` target's metadata label for PodMonitor, +ServiceMonitor and ScrapeConfig resources. +* The `__param_target__` label for Probe resources. -Default: 1 +Users can define their own sharding implementation by setting the +`__tmp_hash` label during the target discovery with relabeling +configuration (either in the monitoring resources or via scrape class). | `storage` | `object` @@ -968,7 +1027,7 @@ the triple using the matching operator . | `topologySpreadConstraints[]` | `object` -| +| | `tracingConfig` | `object` @@ -2986,7 +3045,8 @@ More info: https://prometheus.io/docs/prometheus/latest/configuration/configurat | `apiVersion` | `string` | Version of the Alertmanager API that Prometheus uses to send alerts. -It can be "v1" or "v2". +It can be "V1" or "V2". +The field has no effect for Prometheus >= v3.0.0 because only the v2 API is supported. | `authorization` | `object` @@ -3023,6 +3083,14 @@ Deprecated: this will be removed in a future release. Prefer using `authorizatio If not set, the object will be discovered in the namespace of the Prometheus object. +| `noProxy` +| `string` +| `noProxy` is a comma-separated string that can contain IPs, CIDR notation, domain names +that should be excluded from proxying. IP and domain names can +contain port numbers. + +It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. + | `pathPrefix` | `string` | Prefix for the HTTP path alerts are pushed to. @@ -3031,6 +3099,31 @@ Prometheus object. | `integer-or-string` | Port on which the Alertmanager API is exposed. +| `proxyConnectHeader` +| `object` +| ProxyConnectHeader optionally specifies headers to send to +proxies during CONNECT requests. + +It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. + +| `proxyConnectHeader{}` +| `array` +| + +| `proxyConnectHeader{}[]` +| `object` +| SecretKeySelector selects a key of a Secret. + +| `proxyFromEnvironment` +| `boolean` +| Whether to use the proxy configuration defined by environment variables (HTTP_PROXY, HTTPS_PROXY, and NO_PROXY). + +It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. + +| `proxyUrl` +| `string` +| `proxyURL` defines the HTTP proxy server to use. + | `relabelings` | `array` | Relabel configuration applied to the discovered Alertmanagers. @@ -3294,6 +3387,71 @@ Required:: +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key of the secret to select from. Must be a valid secret key. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the Secret or its key must be defined + +|=== +=== .spec.alerting.alertmanagers[].proxyConnectHeader +Description:: ++ +-- +ProxyConnectHeader optionally specifies headers to send to +proxies during CONNECT requests. + +It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. +-- + +Type:: + `object` + + + + +=== .spec.alerting.alertmanagers[].proxyConnectHeader{} +Description:: ++ +-- + +-- + +Type:: + `array` + + + + +=== .spec.alerting.alertmanagers[].proxyConnectHeader{}[] +Description:: ++ +-- +SecretKeySelector selects a key of a Secret. +-- + +Type:: + `object` + +Required:: + - `key` + + + [cols="1,1,1",options="header"] |=== | Property | Type | Description @@ -4368,7 +4526,7 @@ Type:: | `deny` | `boolean` -| +| |=== === .spec.containers @@ -5021,28 +5179,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.containers[].lifecycle.postStart.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -5068,7 +5226,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -5159,7 +5317,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -5184,8 +5342,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -5238,28 +5396,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.containers[].lifecycle.preStop.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -5285,7 +5443,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -5376,7 +5534,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -5401,8 +5559,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -5450,7 +5608,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -5459,11 +5617,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -5482,7 +5640,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -5508,7 +5666,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -5534,7 +5692,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -5565,7 +5723,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -5656,7 +5814,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -5770,7 +5928,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -5779,11 +5937,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -5802,7 +5960,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -5828,7 +5986,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -5854,7 +6012,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -5885,7 +6043,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -5976,7 +6134,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -6465,7 +6623,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -6474,11 +6632,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -6497,7 +6655,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -6523,7 +6681,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -6549,7 +6707,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -6580,7 +6738,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -6671,7 +6829,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -7730,28 +7888,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.initContainers[].lifecycle.postStart.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -7777,7 +7935,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -7868,7 +8026,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -7893,8 +8051,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -7947,28 +8105,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.initContainers[].lifecycle.preStop.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -7994,7 +8152,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -8085,7 +8243,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -8110,8 +8268,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -8159,7 +8317,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -8168,11 +8326,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -8191,7 +8349,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -8217,7 +8375,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -8243,7 +8401,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -8274,7 +8432,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -8365,7 +8523,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -8479,7 +8637,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -8488,11 +8646,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -8511,7 +8669,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -8537,7 +8695,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -8563,7 +8721,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -8594,7 +8752,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -8685,7 +8843,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -9174,7 +9332,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -9183,11 +9341,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -9206,7 +9364,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -9232,7 +9390,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -9258,7 +9416,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -9289,7 +9447,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -9380,7 +9538,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -9555,10 +9713,23 @@ Type:: |=== | Property | Type | Description +| `keepIdentifyingResourceAttributes` +| `boolean` +| Enables adding `service.name`, `service.namespace` and `service.instance.id` +resource attributes to the `target_info` metric, on top of converting them into the `instance` and `job` labels. + +It requires Prometheus >= v3.1.0. + | `promoteResourceAttributes` | `array (string)` | List of OpenTelemetry Attributes that should be promoted to metric labels, defaults to none. +| `translationStrategy` +| `string` +| Configures how the OTLP receiver endpoint translates the incoming metrics. + +It requires Prometheus >= v3.0.0. + |=== === .spec.persistentVolumeClaimRetentionPolicy Description:: @@ -10201,7 +10372,7 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. | `proxyConnectHeader{}` | `array` -| +| | `proxyConnectHeader{}[]` | `object` @@ -10475,7 +10646,7 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. | `proxyConnectHeader{}` | `array` -| +| | `proxyConnectHeader{}[]` | `object` @@ -11484,7 +11655,7 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. | `proxyConnectHeader{}` | `array` -| +| | `proxyConnectHeader{}[]` | `object` @@ -11508,6 +11679,21 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. | `string` | Timeout for requests to the remote write endpoint. +| `roundRobinDNS` +| `boolean` +| When enabled: + - The remote-write mechanism will resolve the hostname via DNS. + - It will randomly select one of the resolved IP addresses and connect to it. + +When disabled (default behavior): + - The Go standard library will handle hostname resolution. + - It will attempt connections to each resolved IP address sequentially. + +Note: The connection timeout applies to the entire resolution and connection process. + If disabled, the timeout is distributed across all connection attempts. + +It requires Prometheus >= v3.1.0. + | `sendExemplars` | `boolean` | Enables sending of exemplars over remote write. Note that @@ -11982,7 +12168,7 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. | `proxyConnectHeader{}` | `array` -| +| | `proxyConnectHeader{}[]` | `object` @@ -13508,6 +13694,11 @@ Required:: When the scrape object defines its own configuration, it takes precedence over the scrape class configuration. +| `authorization` +| `object` +| Authorization section for the ScrapeClass. +It will only apply if the scrape resource doesn't specify any Authorization. + | `default` | `boolean` | Default indicates that the scrape applies to all scrape objects that @@ -13515,6 +13706,13 @@ don't configure an explicit scrape class name. Only one scrape class can be set as the default. +| `fallbackScrapeProtocol` +| `string` +| The protocol to use if a scrape returns blank, unparseable, or otherwise invalid Content-Type. +It will only apply if the scrape resource doesn't specify any FallbackScrapeProtocol + +It requires Prometheus >= v3.0.0. + | `metricRelabelings` | `array` | MetricRelabelings configures the relabeling rules to apply to all samples before ingestion. @@ -13541,7 +13739,7 @@ More info: https://prometheus.io/docs/prometheus/latest/configuration/configurat | Relabelings configures the relabeling rules to apply to all scrape targets. The Operator automatically adds relabelings for a few standard Kubernetes fields -like `\__meta_kubernetes_namespace` and `\__meta_kubernetes_service_name`. +like `__meta_kubernetes_namespace` and `__meta_kubernetes_service_name`. Then the Operator adds the scrape class relabelings defined here. Then the Operator adds the target-specific relabelings defined in the scrape object. @@ -13590,6 +13788,77 @@ targets. The Prometheus service account must have the `list` and `watch` permissions on the `Nodes` objects. +|=== +=== .spec.scrapeClasses[].authorization +Description:: ++ +-- +Authorization section for the ScrapeClass. +It will only apply if the scrape resource doesn't specify any Authorization. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `credentials` +| `object` +| Selects a key of a Secret in the namespace that contains the credentials for authentication. + +| `credentialsFile` +| `string` +| File to read a secret from, mutually exclusive with `credentials`. + +| `type` +| `string` +| Defines the authentication type. The value is case-insensitive. + +"Basic" is not a supported value. + +Default: "Bearer" + +|=== +=== .spec.scrapeClasses[].authorization.credentials +Description:: ++ +-- +Selects a key of a Secret in the namespace that contains the credentials for authentication. +-- + +Type:: + `object` + +Required:: + - `key` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| The key of the secret to select from. Must be a valid secret key. + +| `name` +| `string` +| Name of the referent. +This field is effectively required, but due to backwards compatibility is +allowed to be empty. Instances of this type with an empty value here are +almost certainly wrong. +More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +| `optional` +| `boolean` +| Specify whether the Secret or its key must be defined + |=== === .spec.scrapeClasses[].metricRelabelings Description:: @@ -13683,7 +13952,7 @@ Description:: Relabelings configures the relabeling rules to apply to all scrape targets. The Operator automatically adds relabelings for a few standard Kubernetes fields -like `\__meta_kubernetes_namespace` and `\__meta_kubernetes_service_name`. +like `__meta_kubernetes_namespace` and `__meta_kubernetes_service_name`. Then the Operator adds the scrape class relabelings defined here. Then the Operator adds the target-specific relabelings defined in the scrape object. @@ -14317,6 +14586,32 @@ PodSecurityContext, the value specified in SecurityContext takes precedence for that container. Note that this field cannot be set when spec.os.name is windows. +| `seLinuxChangePolicy` +| `string` +| seLinuxChangePolicy defines how the container's SELinux label is applied to all volumes used by the Pod. +It has no effect on nodes that do not support SELinux or to volumes does not support SELinux. +Valid values are "MountOption" and "Recursive". + +"Recursive" means relabeling of all files on all Pod volumes by the container runtime. +This may be slow for large volumes, but allows mixing privileged and unprivileged Pods sharing the same volume on the same node. + +"MountOption" mounts all eligible Pod volumes with `-o context` mount option. +This requires all Pods that share the same volume to use the same SELinux label. +It is not possible to share the same volume among privileged and unprivileged Pods. +Eligible volumes are in-tree FibreChannel and iSCSI volumes, and all CSI volumes +whose CSI driver announces SELinux support by setting spec.seLinuxMount: true in their +CSIDriver instance. Other volumes are always re-labelled recursively. +"MountOption" value is allowed only when SELinuxMount feature gate is enabled. + +If not specified and SELinuxMount feature gate is enabled, "MountOption" is used. +If not specified and SELinuxMount feature gate is disabled, "MountOption" is used for ReadWriteOncePod volumes +and "Recursive" for all other volumes. + +This field affects only Pods that have SELinux label set, either in PodSecurityContext or in SecurityContext of all containers. + +All Pods that use the same volume should use the same seLinuxChangePolicy, otherwise some pods can get stuck in ContainerCreating state. +Note that this field cannot be set when spec.os.name is windows. + | `seLinuxOptions` | `object` | The SELinux context to be applied to all containers. @@ -14749,6 +15044,37 @@ the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. +|=== +=== .spec.shardRetentionPolicy +Description:: ++ +-- +ShardRetentionPolicy defines the retention policy for the Prometheus shards. +(Alpha) Using this field requires the 'PrometheusShardRetentionPolicy' feature gate to be enabled. + +The final goals for this feature can be seen at https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/proposals/202310-shard-autoscaling.md#graceful-scale-down-of-prometheus-servers, +however, the feature is not yet fully implemented in this PR. The limitation being: +* Retention duration is not settable, for now, shards are retained forever. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `whenScaled` +| `string` +| Defines the retention policy when the Prometheus shards are scaled down. +* `Delete`, the operator will delete the pods from the scaled-down shard(s). +* `Retain`, the operator will keep the pods from the scaled-down shard(s), so the data can still be queried. + +If not defined, the operator assumes the `Delete` value. + |=== === .spec.storage Description:: @@ -15850,19 +16176,14 @@ persistent volume is being resized. | `status` | `string` -| +| Status is the status of the condition. +Can be True, False, Unknown. +More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=state%20of%20pvc-,conditions.status,-(string)%2C%20required | `type` | `string` -| PersistentVolumeClaimConditionType defines the condition of PV claim. -Valid values are: - - "Resizing", "FileSystemResizePending" - -If RecoverVolumeExpansionFailure feature gate is enabled, then following additional values can be expected: - - "ControllerResizeError", "NodeResizeError" - -If VolumeAttributesClass feature gate is enabled, then following additional values can be expected: - - "ModifyVolumeError", "ModifyingVolume" +| Type is the type of the condition. +More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=set%20to%20%27ResizeStarted%27.-,PersistentVolumeClaimCondition,-contains%20details%20about |=== === .spec.storage.volumeClaimTemplate.status.modifyVolumeStatus @@ -17506,23 +17827,32 @@ Required:: | `object` | awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree +awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore | `azureDisk` | `object` | azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type +are redirected to the disk.csi.azure.com CSI driver. | `azureFile` | `object` | azureFile represents an Azure File Service mount on the host and bind mount to the pod. +Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type +are redirected to the file.csi.azure.com CSI driver. | `cephfs` | `object` -| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. +Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. | `cinder` | `object` | cinder represents a cinder volume attached and mounted on kubelets host machine. +Deprecated: Cinder is deprecated. All operations for the in-tree cinder type +are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `configMap` @@ -17531,7 +17861,7 @@ More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `csi` | `object` -| csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). +| csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers. | `downwardAPI` | `object` @@ -17577,27 +17907,32 @@ persistent volumes at the same time. | `object` | flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. | `flocker` | `object` -| flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running +| flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running. +Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. | `gcePersistentDisk` | `object` | gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree +gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk | `gitRepo` | `object` | gitRepo represents a git repository at a particular revision. -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an +Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. | `glusterfs` | `object` | glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. +Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md | `hostPath` @@ -17650,11 +17985,15 @@ More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persis | `photonPersistentDisk` | `object` -| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. +Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. | `portworxVolume` | `object` -| portworxVolume represents a portworx volume attached and mounted on kubelets host machine +| portworxVolume represents a portworx volume attached and mounted on kubelets host machine. +Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type +are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate +is on. | `projected` | `object` @@ -17662,16 +18001,19 @@ More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persis | `quobyte` | `object` -| quobyte represents a Quobyte mount on the host that shares a pod's lifetime +| quobyte represents a Quobyte mount on the host that shares a pod's lifetime. +Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. | `rbd` | `object` | rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. +Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md | `scaleIO` | `object` | scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. | `secret` | `object` @@ -17681,10 +18023,13 @@ More info: https://kubernetes.io/docs/concepts/storage/volumes#secret | `storageos` | `object` | storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. +Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. | `vsphereVolume` | `object` -| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. +Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type +are redirected to the csi.vsphere.vmware.com CSI driver. |=== === .spec.volumes[].awsElasticBlockStore @@ -17693,6 +18038,8 @@ Description:: -- awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree +awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore -- @@ -17738,6 +18085,8 @@ Description:: + -- azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type +are redirected to the disk.csi.azure.com CSI driver. -- Type:: @@ -17786,6 +18135,8 @@ Description:: + -- azureFile represents an Azure File Service mount on the host and bind mount to the pod. +Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type +are redirected to the file.csi.azure.com CSI driver. -- Type:: @@ -17819,7 +18170,8 @@ the ReadOnly setting in VolumeMounts. Description:: + -- -cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. +Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. -- Type:: @@ -17897,6 +18249,8 @@ Description:: + -- cinder represents a cinder volume attached and mounted on kubelets host machine. +Deprecated: Cinder is deprecated. All operations for the in-tree cinder type +are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md -- @@ -18081,7 +18435,7 @@ May not start with the string '..'. Description:: + -- -csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). +csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers. -- Type:: @@ -18852,6 +19206,7 @@ Description:: -- flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. -- Type:: @@ -18928,7 +19283,8 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running +flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running. +Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. -- Type:: @@ -18957,6 +19313,8 @@ Description:: -- gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree +gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk -- @@ -19004,7 +19362,7 @@ Description:: + -- gitRepo represents a git repository at a particular revision. -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an +Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. -- @@ -19042,6 +19400,7 @@ Description:: + -- glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. +Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md -- @@ -19336,7 +19695,8 @@ Default false. Description:: + -- -photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. +Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. -- Type:: @@ -19366,7 +19726,10 @@ Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. Description:: + -- -portworxVolume represents a portworx volume attached and mounted on kubelets host machine +portworxVolume represents a portworx volume attached and mounted on kubelets host machine. +Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type +are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate +is on. -- Type:: @@ -20043,7 +20406,8 @@ token into. Description:: + -- -quobyte represents a Quobyte mount on the host that shares a pod's lifetime +quobyte represents a Quobyte mount on the host that shares a pod's lifetime. +Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. -- Type:: @@ -20095,6 +20459,7 @@ Description:: + -- rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. +Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md -- @@ -20194,6 +20559,7 @@ Description:: + -- scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. -- Type:: @@ -20402,6 +20768,7 @@ Description:: + -- storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. +Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. -- Type:: @@ -20476,7 +20843,9 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. +Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type +are redirected to the csi.vsphere.vmware.com CSI driver. -- Type:: @@ -20642,62 +21011,87 @@ Type:: | `cert` | `object` -| Contains the TLS certificate for the server. +| Secret or ConfigMap containing the TLS certificate for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `certFile`. | `certFile` | `string` -| Path to the TLS certificate file in the Prometheus container for the server. -Mutually exclusive with `cert`. +| Path to the TLS certificate file in the container for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `cert`. | `cipherSuites` | `array (string)` -| List of supported cipher suites for TLS versions up to TLS 1.2. If empty, -Go default cipher suites are used. Available cipher suites are documented -in the go documentation: https://golang.org/pkg/crypto/tls/#pkg-constants +| List of supported cipher suites for TLS versions up to TLS 1.2. + +If not defined, the Go default cipher suites are used. +Available cipher suites are documented in the Go documentation: +https://golang.org/pkg/crypto/tls/#pkg-constants | `clientAuthType` | `string` -| Server policy for client authentication. Maps to ClientAuth Policies. +| The server policy for client TLS authentication. + For more detail on clientAuth options: https://golang.org/pkg/crypto/tls/#ClientAuthType | `clientCAFile` | `string` -| Path to the CA certificate file for client certificate authentication to the server. -Mutually exclusive with `client_ca`. +| Path to the CA certificate file for client certificate authentication to +the server. + +It is mutually exclusive with `client_ca`. | `client_ca` | `object` -| Contains the CA certificate for client certificate authentication to the server. +| Secret or ConfigMap containing the CA certificate for client certificate +authentication to the server. + +It is mutually exclusive with `clientCAFile`. | `curvePreferences` | `array (string)` | Elliptic curves that will be used in an ECDHE handshake, in preference -order. Available curves are documented in the go documentation: +order. + +Available curves are documented in the Go documentation: https://golang.org/pkg/crypto/tls/#CurveID | `keyFile` | `string` -| Path to the TLS key file in the Prometheus container for the server. -Mutually exclusive with `keySecret`. +| Path to the TLS private key file in the container for the web server. + +If defined, either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keySecret`. | `keySecret` | `object` -| Secret containing the TLS key for the server. +| Secret containing the TLS private key for the web server. + +Either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keyFile`. | `maxVersion` | `string` -| Maximum TLS version that is acceptable. Defaults to TLS13. +| Maximum TLS version that is acceptable. | `minVersion` | `string` -| Minimum TLS version that is acceptable. Defaults to TLS12. +| Minimum TLS version that is acceptable. | `preferServerCipherSuites` | `boolean` -| Controls whether the server selects the -client's most preferred cipher suite, or the server's most preferred -cipher suite. If true then the server's preference, as expressed in +| Controls whether the server selects the client's most preferred cipher +suite, or the server's most preferred cipher suite. + +If true then the server's preference, as expressed in the order of elements in cipherSuites, is used. |=== @@ -20705,7 +21099,11 @@ the order of elements in cipherSuites, is used. Description:: + -- -Contains the TLS certificate for the server. +Secret or ConfigMap containing the TLS certificate for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `certFile`. -- Type:: @@ -20803,7 +21201,10 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -Contains the CA certificate for client certificate authentication to the server. +Secret or ConfigMap containing the CA certificate for client certificate +authentication to the server. + +It is mutually exclusive with `clientCAFile`. -- Type:: @@ -20901,7 +21302,11 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -Secret containing the TLS key for the server. +Secret containing the TLS private key for the web server. + +Either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keyFile`. -- Type:: @@ -20992,7 +21397,7 @@ being performed. Only delete actions will be performed. | `shardStatuses[]` | `object` -| +| | `shards` | `integer` @@ -21246,7 +21651,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus`] schema -| +| |=== .HTTP responses @@ -21379,7 +21784,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus`] schema -| +| |=== .HTTP responses @@ -21481,7 +21886,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../autoscale_apis/scale-autoscaling-v1.adoc#scale-autoscaling-v1[`Scale`] schema -| +| |=== .HTTP responses @@ -21583,7 +21988,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus`] schema -| +| |=== .HTTP responses diff --git a/rest_api/monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc index c3264bb616..e8b9427075 100644 --- a/rest_api/monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc @@ -108,6 +108,14 @@ Required:: | `string` | Interval determines how often rules in the group are evaluated. +| `labels` +| `object (string)` +| Labels to add or overwrite before storing the result for its rules. +The labels defined at the rule level take precedence. + +It requires Prometheus >= 3.0.0. +The field is ignored for Thanos Ruler. + | `limit` | `integer` | Limit the number of alerts an alerting rule and series a recording diff --git a/rest_api/monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc index 238ebd332a..6dce0d02c0 100644 --- a/rest_api/monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc @@ -98,6 +98,12 @@ In most cases, an Endpoints object is backed by a Kubernetes [Service](https://k | Endpoint defines an endpoint serving Prometheus metrics to be scraped by Prometheus. +| `fallbackScrapeProtocol` +| `string` +| The protocol to use if a scrape returns blank, unparseable, or otherwise invalid Content-Type. + +It requires Prometheus >= v3.0.0. + | `jobLabel` | `string` | `jobLabel` selects the label from the associated Kubernetes `Service` @@ -185,6 +191,15 @@ It requires Prometheus >= v2.49.0. | `object` | Label selector to select the Kubernetes `Endpoints` objects to scrape metrics from. +| `selectorMechanism` +| `string` +| Mechanism used to select the endpoints to scrape. +By default, the selection process relies on relabel configurations to filter the discovered targets. +Alternatively, you can opt in for role selectors, which may offer better efficiency in large clusters. +Which strategy is best for your use case needs to be carefully evaluated. + +It requires Prometheus >= v2.17.0. + | `targetLabels` | `array (string)` | `targetLabels` defines the labels which are transferred from the @@ -346,7 +361,7 @@ Cannot be set at the same time as `authorization`, or `basicAuth`. | `params{}` | `array (string)` -| +| | `path` | `string` @@ -372,7 +387,7 @@ metadata labels. The Operator automatically adds relabelings for a few standard Kubernetes fields. -The original scrape job's name is available via the `\__tmp_prometheus_job_name` label. +The original scrape job's name is available via the `__tmp_prometheus_job_name` label. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config @@ -398,6 +413,7 @@ If empty, Prometheus uses the default value `http`. If empty, Prometheus uses the global scrape timeout unless it is less than the target's scrape interval value in which the latter is used. +The value cannot be greater than the scrape interval otherwise the operator will reject the resource. | `targetPort` | `integer-or-string` @@ -768,7 +784,7 @@ It requires Prometheus >= v2.43.0 or Alertmanager >= 0.25.0. | `proxyConnectHeader{}` | `array` -| +| | `proxyConnectHeader{}[]` | `object` @@ -1304,7 +1320,7 @@ metadata labels. The Operator automatically adds relabelings for a few standard Kubernetes fields. -The original scrape job's name is available via the `\__tmp_prometheus_job_name` label. +The original scrape job's name is available via the `__tmp_prometheus_job_name` label. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config -- @@ -1894,7 +1910,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor`] schema -| +| |=== .HTTP responses @@ -2027,7 +2043,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor`] schema -| +| |=== .HTTP responses diff --git a/rest_api/monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc index f1b3c0a825..ba00e6b7a9 100644 --- a/rest_api/monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc @@ -94,8 +94,10 @@ fail and an error will be logged. | `alertDropLabels` | `array (string)` -| AlertDropLabels configure the label names which should be dropped in ThanosRuler alerts. -The replica label `thanos_ruler_replica` will always be dropped in alerts. +| Configures the label names which should be dropped in Thanos Ruler +alerts. + +The replica label `thanos_ruler_replica` will always be dropped from the alerts. | `alertQueryUrl` | `string` @@ -105,27 +107,47 @@ Maps to the '--alert.query-url' CLI arg. | `alertRelabelConfigFile` | `string` -| AlertRelabelConfigFile specifies the path of the alert relabeling configuration file. -When used alongside with AlertRelabelConfigs, alertRelabelConfigFile takes precedence. +| Configures the path to the alert relabeling configuration file. + +Alert relabel configuration must have the form as specified in the +official Prometheus documentation: +https://prometheus.io/docs/prometheus/latest/configuration/configuration/#alert_relabel_configs + +The operator performs no validation of the configuration file. + +This field takes precedence over `alertRelabelConfig`. | `alertRelabelConfigs` | `object` -| AlertRelabelConfigs configures alert relabeling in ThanosRuler. -Alert relabel configurations must have the form as specified in the official Prometheus documentation: +| Configures alert relabeling in Thanos Ruler. + +Alert relabel configuration must have the form as specified in the +official Prometheus documentation: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#alert_relabel_configs -Alternative to AlertRelabelConfigFile, and lower order priority. + +The operator performs no validation of the configuration. + +`alertRelabelConfigFile` takes precedence over this field. | `alertmanagersConfig` | `object` -| Define configuration for connecting to alertmanager. Only available with thanos v0.10.0 -and higher. Maps to the `alertmanagers.config` arg. +| Configures the list of Alertmanager endpoints to send alerts to. + +The configuration format is defined at https://thanos.io/tip/components/rule.md/#alertmanager. + +It requires Thanos >= v0.10.0. + +The operator performs no validation of the configuration. + +This field takes precedence over `alertmanagersUrl`. | `alertmanagersUrl` | `array (string)` -| Define URLs to send alerts to Alertmanager. For Thanos v0.10.0 and higher, -AlertManagersConfig should be used instead. Note: this field will be ignored -if AlertManagersConfig is specified. -Maps to the `alertmanagers.url` arg. +| Configures the list of Alertmanager endpoints to send alerts to. + +For Thanos >= v0.10.0, it is recommended to use `alertmanagersConfig` instead. + +`alertmanagersConfig` takes precedence over this field. | `containers` | `array` @@ -149,6 +171,10 @@ so, you accept that this behaviour may break at any time without notice. | `string` | Defines the DNS policy for the pods. +| `enableServiceLinks` +| `boolean` +| Indicates whether information about services should be injected into pod's environment variables + | `enforcedNamespaceLabel` | `string` | EnforcedNamespaceLabel enforces adding a namespace label of origin for each alert @@ -227,8 +253,10 @@ at any time without notice. | `labels` | `object (string)` -| Labels configure the external label pairs to ThanosRuler. A default replica label -`thanos_ruler_replica` will be always added as a label with the value of the pod's name and it will be dropped in the alerts. +| Configures the external label pairs of the ThanosRuler resource. + +A default replica label `thanos_ruler_replica` will be always added as a +label with the value of the pod's name. | `listenLocal` | `boolean` @@ -256,13 +284,23 @@ This is an alpha field from kubernetes 1.22 until 1.24 which requires enabling t | `objectStorageConfig` | `object` -| ObjectStorageConfig configures object storage in Thanos. -Alternative to ObjectStorageConfigFile, and lower order priority. +| Configures object storage. + +The configuration format is defined at https://thanos.io/tip/thanos/storage.md/#configuring-access-to-object-storage + +The operator performs no validation of the configuration. + +`objectStorageConfigFile` takes precedence over this field. | `objectStorageConfigFile` | `string` -| ObjectStorageConfigFile specifies the path of the object storage configuration file. -When used alongside with ObjectStorageConfig, ObjectStorageConfigFile takes precedence. +| Configures the path of the object storage configuration file. + +The configuration format is defined at https://thanos.io/tip/thanos/storage.md/#configuring-access-to-object-storage + +The operator performs no validation of the configuration file. + +This field takes precedence over `objectStorageConfig`. | `paused` | `boolean` @@ -304,15 +342,23 @@ namespace label for alerts and metrics. | `queryConfig` | `object` -| Define configuration for connecting to thanos query instances. -If this is defined, the QueryEndpoints field will be ignored. -Maps to the `query.config` CLI argument. -Only available with thanos v0.11.0 and higher. +| Configures the list of Thanos Query endpoints from which to query metrics. + +The configuration format is defined at https://thanos.io/tip/components/rule.md/#query-api + +It requires Thanos >= v0.11.0. + +The operator performs no validation of the configuration. + +This field takes precedence over `queryEndpoints`. | `queryEndpoints` | `array (string)` -| QueryEndpoints defines Thanos querier endpoints from which to query metrics. -Maps to the --query flag of thanos ruler. +| Configures the list of Thanos Query endpoints from which to query metrics. + +For Thanos >= v0.11.0, it is recommended to use `queryConfig` instead. + +`queryConfig` takes precedence over this field. | `replicas` | `integer` @@ -339,8 +385,9 @@ the same namespace as the ThanosRuler object is in is used. | `ruleSelector` | `object` -| A label selector to select which PrometheusRules to mount for alerting and -recording. +| PrometheusRule objects to be selected for rule evaluation. An empty +label selector matches all objects. A null label selector matches no +objects. | `securityContext` | `object` @@ -352,6 +399,14 @@ This defaults to the default PodSecurityContext. | ServiceAccountName is the name of the ServiceAccount to use to run the Thanos Ruler Pods. +| `serviceName` +| `string` +| The name of the service name used by the underlying StatefulSet(s) as the governing service. +If defined, the Service must be created before the ThanosRuler resource in the same namespace and it must define a selector that matches the pod labels. +If empty, the operator will create and manage a headless service named `thanos-ruler-operated` for ThanosRuler resources. +When deploying multiple ThanosRuler resources in the same namespace, it is recommended to specify a different value for each. +See https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#stable-network-id for more details. + | `storage` | `object` | Storage spec to specify how storage shall be used. @@ -375,22 +430,30 @@ the triple using the matching operator . | `tracingConfig` | `object` -| TracingConfig configures tracing in Thanos. +| Configures tracing. + +The configuration format is defined at https://thanos.io/tip/thanos/tracing.md/#configuration + +This is an *experimental feature*, it may change in any upcoming release +in a breaking way. + +The operator performs no validation of the configuration. `tracingConfigFile` takes precedence over this field. -This is an *experimental feature*, it may change in any upcoming release -in a breaking way. - | `tracingConfigFile` | `string` -| TracingConfig specifies the path of the tracing configuration file. +| Configures the path of the tracing configuration file. -This field takes precedence over `tracingConfig`. +The configuration format is defined at https://thanos.io/tip/thanos/tracing.md/#configuration This is an *experimental feature*, it may change in any upcoming release in a breaking way. +The operator performs no validation of the configuration file. + +This field takes precedence over `tracingConfig`. + | `version` | `string` | Version of Thanos to be deployed. @@ -2160,10 +2223,15 @@ merge patch. Description:: + -- -AlertRelabelConfigs configures alert relabeling in ThanosRuler. -Alert relabel configurations must have the form as specified in the official Prometheus documentation: +Configures alert relabeling in Thanos Ruler. + +Alert relabel configuration must have the form as specified in the +official Prometheus documentation: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#alert_relabel_configs -Alternative to AlertRelabelConfigFile, and lower order priority. + +The operator performs no validation of the configuration. + +`alertRelabelConfigFile` takes precedence over this field. -- Type:: @@ -2199,8 +2267,15 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -Define configuration for connecting to alertmanager. Only available with thanos v0.10.0 -and higher. Maps to the `alertmanagers.config` arg. +Configures the list of Alertmanager endpoints to send alerts to. + +The configuration format is defined at https://thanos.io/tip/components/rule.md/#alertmanager. + +It requires Thanos >= v0.10.0. + +The operator performs no validation of the configuration. + +This field takes precedence over `alertmanagersUrl`. -- Type:: @@ -2874,28 +2949,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.containers[].lifecycle.postStart.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -2921,7 +2996,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -3012,7 +3087,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -3037,8 +3112,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -3091,28 +3166,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.containers[].lifecycle.preStop.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -3138,7 +3213,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -3229,7 +3304,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -3254,8 +3329,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -3303,7 +3378,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -3312,11 +3387,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -3335,7 +3410,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -3361,7 +3436,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -3387,7 +3462,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -3418,7 +3493,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -3509,7 +3584,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -3623,7 +3698,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -3632,11 +3707,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -3655,7 +3730,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -3681,7 +3756,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -3707,7 +3782,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -3738,7 +3813,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -3829,7 +3904,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -4318,7 +4393,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -4327,11 +4402,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -4350,7 +4425,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -4376,7 +4451,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -4402,7 +4477,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -4433,7 +4508,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -4524,7 +4599,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -5841,28 +5916,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.initContainers[].lifecycle.postStart.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -5888,7 +5963,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -5979,7 +6054,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -6004,8 +6079,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -6058,28 +6133,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.initContainers[].lifecycle.preStop.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -6105,7 +6180,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -6196,7 +6271,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -6221,8 +6296,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -6270,7 +6345,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -6279,11 +6354,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -6302,7 +6377,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -6328,7 +6403,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -6354,7 +6429,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -6385,7 +6460,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -6476,7 +6551,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -6590,7 +6665,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -6599,11 +6674,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -6622,7 +6697,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -6648,7 +6723,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -6674,7 +6749,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -6705,7 +6780,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -6796,7 +6871,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -7285,7 +7360,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -7294,11 +7369,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -7317,7 +7392,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -7343,7 +7418,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -7369,7 +7444,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -7400,7 +7475,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -7491,7 +7566,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -7652,8 +7727,13 @@ SubPathExpr and SubPath are mutually exclusive. Description:: + -- -ObjectStorageConfig configures object storage in Thanos. -Alternative to ObjectStorageConfigFile, and lower order priority. +Configures object storage. + +The configuration format is defined at https://thanos.io/tip/thanos/storage.md/#configuring-access-to-object-storage + +The operator performs no validation of the configuration. + +`objectStorageConfigFile` takes precedence over this field. -- Type:: @@ -7784,10 +7864,15 @@ Required:: Description:: + -- -Define configuration for connecting to thanos query instances. -If this is defined, the QueryEndpoints field will be ignored. -Maps to the `query.config` CLI argument. -Only available with thanos v0.11.0 and higher. +Configures the list of Thanos Query endpoints from which to query metrics. + +The configuration format is defined at https://thanos.io/tip/components/rule.md/#query-api + +It requires Thanos >= v0.11.0. + +The operator performs no validation of the configuration. + +This field takes precedence over `queryEndpoints`. -- Type:: @@ -8004,8 +8089,9 @@ merge patch. Description:: + -- -A label selector to select which PrometheusRules to mount for alerting and -recording. +PrometheusRule objects to be selected for rule evaluation. An empty +label selector matches all objects. A null label selector matches no +objects. -- Type:: @@ -8158,6 +8244,32 @@ PodSecurityContext, the value specified in SecurityContext takes precedence for that container. Note that this field cannot be set when spec.os.name is windows. +| `seLinuxChangePolicy` +| `string` +| seLinuxChangePolicy defines how the container's SELinux label is applied to all volumes used by the Pod. +It has no effect on nodes that do not support SELinux or to volumes does not support SELinux. +Valid values are "MountOption" and "Recursive". + +"Recursive" means relabeling of all files on all Pod volumes by the container runtime. +This may be slow for large volumes, but allows mixing privileged and unprivileged Pods sharing the same volume on the same node. + +"MountOption" mounts all eligible Pod volumes with `-o context` mount option. +This requires all Pods that share the same volume to use the same SELinux label. +It is not possible to share the same volume among privileged and unprivileged Pods. +Eligible volumes are in-tree FibreChannel and iSCSI volumes, and all CSI volumes +whose CSI driver announces SELinux support by setting spec.seLinuxMount: true in their +CSIDriver instance. Other volumes are always re-labelled recursively. +"MountOption" value is allowed only when SELinuxMount feature gate is enabled. + +If not specified and SELinuxMount feature gate is enabled, "MountOption" is used. +If not specified and SELinuxMount feature gate is disabled, "MountOption" is used for ReadWriteOncePod volumes +and "Recursive" for all other volumes. + +This field affects only Pods that have SELinux label set, either in PodSecurityContext or in SecurityContext of all containers. + +All Pods that use the same volume should use the same seLinuxChangePolicy, otherwise some pods can get stuck in ContainerCreating state. +Note that this field cannot be set when spec.os.name is windows. + | `seLinuxOptions` | `object` | The SELinux context to be applied to all containers. @@ -9511,19 +9623,14 @@ persistent volume is being resized. | `status` | `string` -| +| Status is the status of the condition. +Can be True, False, Unknown. +More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=state%20of%20pvc-,conditions.status,-(string)%2C%20required | `type` | `string` -| PersistentVolumeClaimConditionType defines the condition of PV claim. -Valid values are: - - "Resizing", "FileSystemResizePending" - -If RecoverVolumeExpansionFailure feature gate is enabled, then following additional values can be expected: - - "ControllerResizeError", "NodeResizeError" - -If VolumeAttributesClass feature gate is enabled, then following additional values can be expected: - - "ModifyVolumeError", "ModifyingVolume" +| Type is the type of the condition. +More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=set%20to%20%27ResizeStarted%27.-,PersistentVolumeClaimCondition,-contains%20details%20about |=== === .spec.storage.volumeClaimTemplate.status.modifyVolumeStatus @@ -9867,12 +9974,16 @@ merge patch. Description:: + -- -TracingConfig configures tracing in Thanos. +Configures tracing. -`tracingConfigFile` takes precedence over this field. +The configuration format is defined at https://thanos.io/tip/thanos/tracing.md/#configuration This is an *experimental feature*, it may change in any upcoming release in a breaking way. + +The operator performs no validation of the configuration. + +`tracingConfigFile` takes precedence over this field. -- Type:: @@ -10031,23 +10142,32 @@ Required:: | `object` | awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree +awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore | `azureDisk` | `object` | azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type +are redirected to the disk.csi.azure.com CSI driver. | `azureFile` | `object` | azureFile represents an Azure File Service mount on the host and bind mount to the pod. +Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type +are redirected to the file.csi.azure.com CSI driver. | `cephfs` | `object` -| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. +Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. | `cinder` | `object` | cinder represents a cinder volume attached and mounted on kubelets host machine. +Deprecated: Cinder is deprecated. All operations for the in-tree cinder type +are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `configMap` @@ -10056,7 +10176,7 @@ More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `csi` | `object` -| csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). +| csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers. | `downwardAPI` | `object` @@ -10102,27 +10222,32 @@ persistent volumes at the same time. | `object` | flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. | `flocker` | `object` -| flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running +| flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running. +Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. | `gcePersistentDisk` | `object` | gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree +gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk | `gitRepo` | `object` | gitRepo represents a git repository at a particular revision. -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an +Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. | `glusterfs` | `object` | glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. +Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md | `hostPath` @@ -10175,11 +10300,15 @@ More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persis | `photonPersistentDisk` | `object` -| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. +Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. | `portworxVolume` | `object` -| portworxVolume represents a portworx volume attached and mounted on kubelets host machine +| portworxVolume represents a portworx volume attached and mounted on kubelets host machine. +Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type +are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate +is on. | `projected` | `object` @@ -10187,16 +10316,19 @@ More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persis | `quobyte` | `object` -| quobyte represents a Quobyte mount on the host that shares a pod's lifetime +| quobyte represents a Quobyte mount on the host that shares a pod's lifetime. +Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. | `rbd` | `object` | rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. +Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md | `scaleIO` | `object` | scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. | `secret` | `object` @@ -10206,10 +10338,13 @@ More info: https://kubernetes.io/docs/concepts/storage/volumes#secret | `storageos` | `object` | storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. +Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. | `vsphereVolume` | `object` -| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. +Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type +are redirected to the csi.vsphere.vmware.com CSI driver. |=== === .spec.volumes[].awsElasticBlockStore @@ -10218,6 +10353,8 @@ Description:: -- awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree +awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore -- @@ -10263,6 +10400,8 @@ Description:: + -- azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type +are redirected to the disk.csi.azure.com CSI driver. -- Type:: @@ -10311,6 +10450,8 @@ Description:: + -- azureFile represents an Azure File Service mount on the host and bind mount to the pod. +Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type +are redirected to the file.csi.azure.com CSI driver. -- Type:: @@ -10344,7 +10485,8 @@ the ReadOnly setting in VolumeMounts. Description:: + -- -cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. +Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. -- Type:: @@ -10422,6 +10564,8 @@ Description:: + -- cinder represents a cinder volume attached and mounted on kubelets host machine. +Deprecated: Cinder is deprecated. All operations for the in-tree cinder type +are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md -- @@ -10606,7 +10750,7 @@ May not start with the string '..'. Description:: + -- -csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). +csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers. -- Type:: @@ -11377,6 +11521,7 @@ Description:: -- flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. -- Type:: @@ -11453,7 +11598,8 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running +flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running. +Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. -- Type:: @@ -11482,6 +11628,8 @@ Description:: -- gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree +gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk -- @@ -11529,7 +11677,7 @@ Description:: + -- gitRepo represents a git repository at a particular revision. -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an +Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. -- @@ -11567,6 +11715,7 @@ Description:: + -- glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. +Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md -- @@ -11861,7 +12010,8 @@ Default false. Description:: + -- -photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. +Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. -- Type:: @@ -11891,7 +12041,10 @@ Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. Description:: + -- -portworxVolume represents a portworx volume attached and mounted on kubelets host machine +portworxVolume represents a portworx volume attached and mounted on kubelets host machine. +Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type +are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate +is on. -- Type:: @@ -12568,7 +12721,8 @@ token into. Description:: + -- -quobyte represents a Quobyte mount on the host that shares a pod's lifetime +quobyte represents a Quobyte mount on the host that shares a pod's lifetime. +Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. -- Type:: @@ -12620,6 +12774,7 @@ Description:: + -- rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. +Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md -- @@ -12719,6 +12874,7 @@ Description:: + -- scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. -- Type:: @@ -12927,6 +13083,7 @@ Description:: + -- storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. +Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. -- Type:: @@ -13001,7 +13158,9 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. +Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type +are redirected to the csi.vsphere.vmware.com CSI driver. -- Type:: @@ -13158,62 +13317,87 @@ Type:: | `cert` | `object` -| Contains the TLS certificate for the server. +| Secret or ConfigMap containing the TLS certificate for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `certFile`. | `certFile` | `string` -| Path to the TLS certificate file in the Prometheus container for the server. -Mutually exclusive with `cert`. +| Path to the TLS certificate file in the container for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `cert`. | `cipherSuites` | `array (string)` -| List of supported cipher suites for TLS versions up to TLS 1.2. If empty, -Go default cipher suites are used. Available cipher suites are documented -in the go documentation: https://golang.org/pkg/crypto/tls/#pkg-constants +| List of supported cipher suites for TLS versions up to TLS 1.2. + +If not defined, the Go default cipher suites are used. +Available cipher suites are documented in the Go documentation: +https://golang.org/pkg/crypto/tls/#pkg-constants | `clientAuthType` | `string` -| Server policy for client authentication. Maps to ClientAuth Policies. +| The server policy for client TLS authentication. + For more detail on clientAuth options: https://golang.org/pkg/crypto/tls/#ClientAuthType | `clientCAFile` | `string` -| Path to the CA certificate file for client certificate authentication to the server. -Mutually exclusive with `client_ca`. +| Path to the CA certificate file for client certificate authentication to +the server. + +It is mutually exclusive with `client_ca`. | `client_ca` | `object` -| Contains the CA certificate for client certificate authentication to the server. +| Secret or ConfigMap containing the CA certificate for client certificate +authentication to the server. + +It is mutually exclusive with `clientCAFile`. | `curvePreferences` | `array (string)` | Elliptic curves that will be used in an ECDHE handshake, in preference -order. Available curves are documented in the go documentation: +order. + +Available curves are documented in the Go documentation: https://golang.org/pkg/crypto/tls/#CurveID | `keyFile` | `string` -| Path to the TLS key file in the Prometheus container for the server. -Mutually exclusive with `keySecret`. +| Path to the TLS private key file in the container for the web server. + +If defined, either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keySecret`. | `keySecret` | `object` -| Secret containing the TLS key for the server. +| Secret containing the TLS private key for the web server. + +Either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keyFile`. | `maxVersion` | `string` -| Maximum TLS version that is acceptable. Defaults to TLS13. +| Maximum TLS version that is acceptable. | `minVersion` | `string` -| Minimum TLS version that is acceptable. Defaults to TLS12. +| Minimum TLS version that is acceptable. | `preferServerCipherSuites` | `boolean` -| Controls whether the server selects the -client's most preferred cipher suite, or the server's most preferred -cipher suite. If true then the server's preference, as expressed in +| Controls whether the server selects the client's most preferred cipher +suite, or the server's most preferred cipher suite. + +If true then the server's preference, as expressed in the order of elements in cipherSuites, is used. |=== @@ -13221,7 +13405,11 @@ the order of elements in cipherSuites, is used. Description:: + -- -Contains the TLS certificate for the server. +Secret or ConfigMap containing the TLS certificate for the web server. + +Either `keySecret` or `keyFile` must be defined. + +It is mutually exclusive with `certFile`. -- Type:: @@ -13319,7 +13507,10 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -Contains the CA certificate for client certificate authentication to the server. +Secret or ConfigMap containing the CA certificate for client certificate +authentication to the server. + +It is mutually exclusive with `clientCAFile`. -- Type:: @@ -13417,7 +13608,11 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -Secret containing the TLS key for the server. +Secret containing the TLS private key for the web server. + +Either `cert` or `certFile` must be defined. + +It is mutually exclusive with `keyFile`. -- Type:: diff --git a/rest_api/network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc b/rest_api/network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc new file mode 100644 index 0000000000..3ceb02a3e9 --- /dev/null +++ b/rest_api/network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc @@ -0,0 +1,1037 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="clusteruserdefinednetwork-k8s-ovn-org-v1"] += ClusterUserDefinedNetwork [k8s.ovn.org/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +ClusterUserDefinedNetwork describe network request for a shared network across namespaces. +-- + +Type:: + `object` + +Required:: + - `spec` + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| ClusterUserDefinedNetworkSpec defines the desired state of ClusterUserDefinedNetwork. + +| `status` +| `object` +| ClusterUserDefinedNetworkStatus contains the observed status of the ClusterUserDefinedNetwork. + +|=== +=== .spec +Description:: ++ +-- +ClusterUserDefinedNetworkSpec defines the desired state of ClusterUserDefinedNetwork. +-- + +Type:: + `object` + +Required:: + - `namespaceSelector` + - `network` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `namespaceSelector` +| `object` +| NamespaceSelector Label selector for which namespace network should be available for. + +| `network` +| `object` +| Network is the user-defined-network spec + +|=== +=== .spec.namespaceSelector +Description:: ++ +-- +NamespaceSelector Label selector for which namespace network should be available for. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `matchExpressions` +| `array` +| matchExpressions is a list of label selector requirements. The requirements are ANDed. + +| `matchExpressions[]` +| `object` +| A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. + +| `matchLabels` +| `object (string)` +| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels +map is equivalent to an element of matchExpressions, whose key field is "key", the +operator is "In", and the values array contains only "value". The requirements are ANDed. + +|=== +=== .spec.namespaceSelector.matchExpressions +Description:: ++ +-- +matchExpressions is a list of label selector requirements. The requirements are ANDed. +-- + +Type:: + `array` + + + + +=== .spec.namespaceSelector.matchExpressions[] +Description:: ++ +-- +A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. +-- + +Type:: + `object` + +Required:: + - `key` + - `operator` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| key is the label key that the selector applies to. + +| `operator` +| `string` +| operator represents a key's relationship to a set of values. +Valid operators are In, NotIn, Exists and DoesNotExist. + +| `values` +| `array (string)` +| values is an array of string values. If the operator is In or NotIn, +the values array must be non-empty. If the operator is Exists or DoesNotExist, +the values array must be empty. This array is replaced during a strategic +merge patch. + +|=== +=== .spec.network +Description:: ++ +-- +Network is the user-defined-network spec +-- + +Type:: + `object` + +Required:: + - `topology` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `layer2` +| `object` +| Layer2 is the Layer2 topology configuration. + +| `layer3` +| `object` +| Layer3 is the Layer3 topology configuration. + +| `localnet` +| `object` +| Localnet is the Localnet topology configuration. + +| `topology` +| `string` +| Topology describes network configuration. + +Allowed values are "Layer3", "Layer2" and "Localnet". +Layer3 topology creates a layer 2 segment per node, each with a different subnet. Layer 3 routing is used to interconnect node subnets. +Layer2 topology creates one logical switch shared by all nodes. +Localnet topology is based on layer 2 topology, but also allows connecting to an existent (configured) physical network to provide north-south traffic to the workloads. + +|=== +=== .spec.network.layer2 +Description:: ++ +-- +Layer2 is the Layer2 topology configuration. +-- + +Type:: + `object` + +Required:: + - `role` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `ipam` +| `object` +| IPAM section contains IPAM-related configuration for the network. + +| `joinSubnets` +| `array (string)` +| JoinSubnets are used inside the OVN network topology. + +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. +This field is only allowed for "Primary" network. +It is not recommended to set this field without explicit need and understanding of the OVN network topology. +When omitted, the platform will choose a reasonable default which is subject to change over time. + +| `mtu` +| `integer` +| MTU is the maximum transmission unit for a network. +MTU is optional, if not provided, the globally configured value in OVN-Kubernetes (defaults to 1400) is used for the network. + +| `role` +| `string` +| Role describes the network role in the pod. + +Allowed value is "Secondary". +Secondary network is only assigned to pods that use `k8s.v1.cni.cncf.io/networks` annotation to select given network. + +| `subnets` +| `array (string)` +| Subnets are used for the pod network across the cluster. +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. + +The format should match standard CIDR notation (for example, "10.128.0.0/16"). +This field must be omitted if `ipam.mode` is `Disabled`. + +|=== +=== .spec.network.layer2.ipam +Description:: ++ +-- +IPAM section contains IPAM-related configuration for the network. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lifecycle` +| `string` +| Lifecycle controls IP addresses management lifecycle. + +The only allowed value is Persistent. When set, the IP addresses assigned by OVN Kubernetes will be persisted in an +`ipamclaims.k8s.cni.cncf.io` object. These IP addresses will be reused by other pods if requested. +Only supported when mode is `Enabled`. + +| `mode` +| `string` +| Mode controls how much of the IP configuration will be managed by OVN. +`Enabled` means OVN-Kubernetes will apply IP configuration to the SDN infrastructure and it will also assign IPs +from the selected subnet to the individual pods. +`Disabled` means OVN-Kubernetes will only assign MAC addresses and provide layer 2 communication, letting users +configure IP addresses for the pods. +`Disabled` is only available for Secondary networks. +By disabling IPAM, any Kubernetes features that rely on selecting pods by IP will no longer function +(such as network policy, services, etc). Additionally, IP port security will also be disabled for interfaces attached to this network. +Defaults to `Enabled`. + +|=== +=== .spec.network.layer3 +Description:: ++ +-- +Layer3 is the Layer3 topology configuration. +-- + +Type:: + `object` + +Required:: + - `role` + - `subnets` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `joinSubnets` +| `array (string)` +| JoinSubnets are used inside the OVN network topology. + +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. +This field is only allowed for "Primary" network. +It is not recommended to set this field without explicit need and understanding of the OVN network topology. +When omitted, the platform will choose a reasonable default which is subject to change over time. + +| `mtu` +| `integer` +| MTU is the maximum transmission unit for a network. + +MTU is optional, if not provided, the globally configured value in OVN-Kubernetes (defaults to 1400) is used for the network. + +| `role` +| `string` +| Role describes the network role in the pod. + +Allowed values are "Primary" and "Secondary". +Primary network is automatically assigned to every pod created in the same namespace. +Secondary network is only assigned to pods that use `k8s.v1.cni.cncf.io/networks` annotation to select given network. + +| `subnets` +| `array` +| Subnets are used for the pod network across the cluster. + +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. +Given subnet is split into smaller subnets for every node. + +| `subnets[]` +| `object` +| + +|=== +=== .spec.network.layer3.subnets +Description:: ++ +-- +Subnets are used for the pod network across the cluster. + +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. +Given subnet is split into smaller subnets for every node. +-- + +Type:: + `array` + + + + +=== .spec.network.layer3.subnets[] +Description:: ++ +-- + +-- + +Type:: + `object` + +Required:: + - `cidr` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `cidr` +| `string` +| CIDR specifies L3Subnet, which is split into smaller subnets for every node. + +| `hostSubnet` +| `integer` +| HostSubnet specifies the subnet size for every node. + +When not set, it will be assigned automatically. + +|=== +=== .spec.network.localnet +Description:: ++ +-- +Localnet is the Localnet topology configuration. +-- + +Type:: + `object` + +Required:: + - `physicalNetworkName` + - `role` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `excludeSubnets` +| `array (string)` +| excludeSubnets is a list of CIDRs to be removed from the specified CIDRs in `subnets`. +The CIDRs in this list must be in range of at least one subnet specified in `subnets`. +excludeSubnets is optional. When omitted no IP address is excluded and all IP addresses specified in `subnets` +are subject to assignment. +The format should match standard CIDR notation (for example, "10.128.0.0/16"). +This field must be omitted if `subnets` is unset or `ipam.mode` is `Disabled`. +When `physicalNetworkName` points to OVS bridge mapping of a network with reserved IP addresses +(which shouldn't be assigned by OVN-Kubernetes), the specified CIDRs will not be assigned. For example: +Given: `subnets: "10.0.0.0/24"`, `excludeSubnets: "10.0.0.200/30", the following addresses will not be assigned +to pods: `10.0.0.201`, `10.0.0.202`. + +| `ipam` +| `object` +| ipam configurations for the network. +ipam is optional. When omitted, `subnets` must be specified. +When `ipam.mode` is `Disabled`, `subnets` must be omitted. +`ipam.mode` controls how much of the IP configuration will be managed by OVN. + When `Enabled`, OVN-Kubernetes will apply IP configuration to the SDN infra and assign IPs from the selected + subnet to the pods. + When `Disabled`, OVN-Kubernetes only assigns MAC addresses, and provides layer2 communication, and enables users + to configure IP addresses on the pods. +`ipam.lifecycle` controls IP addresses management lifecycle. + When set to 'Persistent', the assigned IP addresses will be persisted in `ipamclaims.k8s.cni.cncf.io` object. + Useful for VMs, IP address will be persistent after restarts and migrations. Supported when `ipam.mode` is `Enabled`. + +| `mtu` +| `integer` +| mtu is the maximum transmission unit for a network. +mtu is optional. When omitted, the configured value in OVN-Kubernetes (defaults to 1500 for localnet topology) +is used for the network. +Minimum value for IPv4 subnet is 576, and for IPv6 subnet is 1280. +Maximum value is 65536. +In a scenario `physicalNetworkName` points to OVS bridge mapping of a network configured with certain MTU settings, +this field enables configuring the same MTU on pod interface, having the pod MTU aligned with the network MTU. +Misaligned MTU across the stack (e.g.: pod has MTU X, node NIC has MTU Y), could result in network disruptions +and bad performance. + +| `physicalNetworkName` +| `string` +| physicalNetworkName points to the OVS bridge-mapping's network-name configured in the nodes, required. +Min length is 1, max length is 253, cannot contain `,` or `:` characters. +In case OVS bridge-mapping is defined by Kubernetes-nmstate with `NodeNetworkConfigurationPolicy` (NNCP), +this field should point to the NNCP `spec.desiredState.ovn.bridge-mappings` item's `localnet` value. + +| `role` +| `string` +| role describes the network role in the pod, required. +Controls whether the pod interface will act as primary or secondary. +Localnet topology supports `Secondary` only. +The network will be assigned to pods that have the `k8s.v1.cni.cncf.io/networks` annotation in place pointing +to subject. + +| `subnets` +| `array (string)` +| subnets is a list of subnets used for pods in this localnet network across the cluster. +The list may be either 1 IPv4 subnet, 1 IPv6 subnet, or 1 of each IP family. +When set, OVN-Kubernetes assigns an IP address from the specified CIDRs to the connected pod, +eliminating the need for manual IP assignment or reliance on an external IPAM service (e.g., a DHCP server). +subnets is optional. When omitted OVN-Kubernetes won't assign IP address automatically. +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. +The format should match standard CIDR notation (for example, "10.128.0.0/16"). +This field must be omitted if `ipam.mode` is `Disabled`. +When physicalNetworkName points to the OVS bridge mapping of a network that provides IPAM services +(e.g., a DHCP server), ipam.mode should be set to Disabled. This turns off OVN-Kubernetes IPAM and avoids +conflicts with the existing IPAM services on this localnet network. + +| `vlan` +| `object` +| vlan configuration for the network. +vlan.mode is the VLAN mode. + When "Access" is set, OVN-Kubernetes configures the network logical switch port in access mode. +vlan.access is the access VLAN configuration. +vlan.access.id is the VLAN ID (VID) to be set on the network logical switch port. +vlan is optional, when omitted the underlying network default VLAN will be used (usually `1`). +When set, OVN-Kubernetes will apply VLAN configuration to the SDN infra and to the connected pods. + +|=== +=== .spec.network.localnet.ipam +Description:: ++ +-- +ipam configurations for the network. +ipam is optional. When omitted, `subnets` must be specified. +When `ipam.mode` is `Disabled`, `subnets` must be omitted. +`ipam.mode` controls how much of the IP configuration will be managed by OVN. + When `Enabled`, OVN-Kubernetes will apply IP configuration to the SDN infra and assign IPs from the selected + subnet to the pods. + When `Disabled`, OVN-Kubernetes only assigns MAC addresses, and provides layer2 communication, and enables users + to configure IP addresses on the pods. +`ipam.lifecycle` controls IP addresses management lifecycle. + When set to 'Persistent', the assigned IP addresses will be persisted in `ipamclaims.k8s.cni.cncf.io` object. + Useful for VMs, IP address will be persistent after restarts and migrations. Supported when `ipam.mode` is `Enabled`. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lifecycle` +| `string` +| Lifecycle controls IP addresses management lifecycle. + +The only allowed value is Persistent. When set, the IP addresses assigned by OVN Kubernetes will be persisted in an +`ipamclaims.k8s.cni.cncf.io` object. These IP addresses will be reused by other pods if requested. +Only supported when mode is `Enabled`. + +| `mode` +| `string` +| Mode controls how much of the IP configuration will be managed by OVN. +`Enabled` means OVN-Kubernetes will apply IP configuration to the SDN infrastructure and it will also assign IPs +from the selected subnet to the individual pods. +`Disabled` means OVN-Kubernetes will only assign MAC addresses and provide layer 2 communication, letting users +configure IP addresses for the pods. +`Disabled` is only available for Secondary networks. +By disabling IPAM, any Kubernetes features that rely on selecting pods by IP will no longer function +(such as network policy, services, etc). Additionally, IP port security will also be disabled for interfaces attached to this network. +Defaults to `Enabled`. + +|=== +=== .spec.network.localnet.vlan +Description:: ++ +-- +vlan configuration for the network. +vlan.mode is the VLAN mode. + When "Access" is set, OVN-Kubernetes configures the network logical switch port in access mode. +vlan.access is the access VLAN configuration. +vlan.access.id is the VLAN ID (VID) to be set on the network logical switch port. +vlan is optional, when omitted the underlying network default VLAN will be used (usually `1`). +When set, OVN-Kubernetes will apply VLAN configuration to the SDN infra and to the connected pods. +-- + +Type:: + `object` + +Required:: + - `mode` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `access` +| `object` +| Access is the access VLAN configuration + +| `mode` +| `string` +| mode describe the network VLAN mode. +Allowed value is "Access". +Access sets the network logical switch port in access mode, according to the config. + +|=== +=== .spec.network.localnet.vlan.access +Description:: ++ +-- +Access is the access VLAN configuration +-- + +Type:: + `object` + +Required:: + - `id` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `id` +| `integer` +| id is the VLAN ID (VID) to be set for the network. +id should be higher than 0 and lower than 4095. + +|=== +=== .status +Description:: ++ +-- +ClusterUserDefinedNetworkStatus contains the observed status of the ClusterUserDefinedNetwork. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| Conditions slice of condition objects indicating details about ClusterUserDefineNetwork status. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +|=== +=== .status.conditions +Description:: ++ +-- +Conditions slice of condition objects indicating details about ClusterUserDefineNetwork status. +-- + +Type:: + `array` + + + + +=== .status.conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/k8s.ovn.org/v1/clusteruserdefinednetworks` +- `DELETE`: delete collection of ClusterUserDefinedNetwork +- `GET`: list objects of kind ClusterUserDefinedNetwork +- `POST`: create a ClusterUserDefinedNetwork +* `/apis/k8s.ovn.org/v1/clusteruserdefinednetworks/{name}` +- `DELETE`: delete a ClusterUserDefinedNetwork +- `GET`: read the specified ClusterUserDefinedNetwork +- `PATCH`: partially update the specified ClusterUserDefinedNetwork +- `PUT`: replace the specified ClusterUserDefinedNetwork +* `/apis/k8s.ovn.org/v1/clusteruserdefinednetworks/{name}/status` +- `GET`: read status of the specified ClusterUserDefinedNetwork +- `PATCH`: partially update status of the specified ClusterUserDefinedNetwork +- `PUT`: replace status of the specified ClusterUserDefinedNetwork + + +=== /apis/k8s.ovn.org/v1/clusteruserdefinednetworks + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of ClusterUserDefinedNetwork + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind ClusterUserDefinedNetwork + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#org-ovn-k8s-v1-ClusterUserDefinedNetworkList[`ClusterUserDefinedNetworkList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a ClusterUserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 201 - Created +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 202 - Accepted +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/k8s.ovn.org/v1/clusteruserdefinednetworks/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ClusterUserDefinedNetwork +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a ClusterUserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified ClusterUserDefinedNetwork + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified ClusterUserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified ClusterUserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 201 - Created +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/k8s.ovn.org/v1/clusteruserdefinednetworks/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ClusterUserDefinedNetwork +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified ClusterUserDefinedNetwork + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified ClusterUserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified ClusterUserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 201 - Created +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`ClusterUserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/network_apis/egressrouter-network-operator-openshift-io-v1.adoc b/rest_api/network_apis/egressrouter-network-operator-openshift-io-v1.adoc index 6bce919eec..534ec509e3 100644 --- a/rest_api/network_apis/egressrouter-network-operator-openshift-io-v1.adoc +++ b/rest_api/network_apis/egressrouter-network-operator-openshift-io-v1.adoc @@ -92,7 +92,7 @@ Required:: | `mode` | `string` -| Mode depicts the mode that is used for the egress router. The default mode is "Redirect" and is the only supported mode currently. +| mode depicts the mode that is used for the egress router. The default mode is "Redirect" and is the only supported mode currently. | `networkInterface` | `object` @@ -101,7 +101,7 @@ Currently only macvlan is supported. | `redirect` | `object` -| Redirect represents the configuration parameters specific to redirect mode. +| redirect represents the configuration parameters specific to redirect mode. |=== === .spec.addresses @@ -142,7 +142,7 @@ Required:: | `ip` | `string` -| IP is the address to configure on the router's interface. Can be IPv4 or IPv6. +| ip is the address to configure on the router's interface. Can be IPv4 or IPv6. |=== === .spec.networkInterface @@ -193,14 +193,14 @@ Required:: | `mode` | `string` -| Mode depicts the mode that is used for the macvlan interface; one of Bridge\|Private\|VEPA\|Passthru. The default mode is "Bridge". +| mode depicts the mode that is used for the macvlan interface; one of Bridge\|Private\|VEPA\|Passthru. The default mode is "Bridge". |=== === .spec.redirect Description:: + -- -Redirect represents the configuration parameters specific to redirect mode. +redirect represents the configuration parameters specific to redirect mode. -- Type:: @@ -215,7 +215,7 @@ Type:: | `fallbackIP` | `string` -| FallbackIP specifies the remote destination's IP address. Can be IPv4 or IPv6. +| fallbackIP specifies the remote destination's IP address. Can be IPv4 or IPv6. If no redirect rules are specified, all traffic from the router are redirected to this IP. If redirect rules are specified, then any connections on any other port (undefined in the rules) on the router will be redirected to this IP. If redirect rules are specified and no fallback IP is provided, connections on other ports will simply be rejected. @@ -269,15 +269,15 @@ Required:: | `port` | `integer` -| Port is the port number to which clients should send traffic to be redirected. +| port is the port number to which clients should send traffic to be redirected. | `protocol` | `string` -| Protocol can be TCP, SCTP or UDP. +| protocol can be TCP, SCTP or UDP. | `targetPort` | `integer` -| TargetPort allows specifying the port number on the remote destination to which the traffic gets redirected to. +| targetPort allows specifying the port number on the remote destination to which the traffic gets redirected to. If unspecified, the value from "Port" is used. |=== @@ -346,25 +346,25 @@ Required:: | `lastTransitionTime` | `` -| LastTransitionTime is the time of the last update to the current status property. +| lastTransitionTime is the time of the last update to the current status property. | `message` | `string` -| Message provides additional information about the current condition. +| message provides additional information about the current condition. This is only to be consumed by humans. It may contain Line Feed characters (U+000A), which should be rendered as new lines. | `reason` | `string` -| Reason is the CamelCase reason for the condition's current status. +| reason is the CamelCase reason for the condition's current status. | `status` | `string` -| Status of the condition, one of True, False, Unknown. +| status of the condition, one of True, False, Unknown. | `type` | `string` -| Type specifies the aspect reported by this condition; one of Available, Progressing, Degraded +| type specifies the aspect reported by this condition; one of Available, Progressing, Degraded |=== diff --git a/rest_api/network_apis/egressservice-k8s-ovn-org-v1.adoc b/rest_api/network_apis/egressservice-k8s-ovn-org-v1.adoc index e57fb54389..1b20bf858f 100644 --- a/rest_api/network_apis/egressservice-k8s-ovn-org-v1.adoc +++ b/rest_api/network_apis/egressservice-k8s-ovn-org-v1.adoc @@ -11,7 +11,12 @@ toc::[] Description:: + -- -EgressService is a CRD that allows the user to request that the source IP of egress packets originating from all of the pods that are endpoints of the corresponding LoadBalancer Service would be its ingress IP. In addition, it allows the user to request that egress packets originating from all of the pods that are endpoints of the LoadBalancer service would use a different network than the main one. +EgressService is a CRD that allows the user to request that the source +IP of egress packets originating from all of the pods that are endpoints +of the corresponding LoadBalancer Service would be its ingress IP. +In addition, it allows the user to request that egress packets originating from +all of the pods that are endpoints of the LoadBalancer service would use a different +network than the main one. -- Type:: @@ -65,22 +70,35 @@ Type:: | `network` | `string` -| The network which this service should send egress and corresponding ingress replies to. This is typically implemented as VRF mapping, representing a numeric id or string name of a routing table which by omission uses the default host routing. +| The network which this service should send egress and corresponding ingress replies to. +This is typically implemented as VRF mapping, representing a numeric id or string name +of a routing table which by omission uses the default host routing. | `nodeSelector` | `object` -| Allows limiting the nodes that can be selected to handle the service's traffic when sourceIPBy=LoadBalancerIP. When present only a node whose labels match the specified selectors can be selected for handling the service's traffic. When it is not specified any node in the cluster can be chosen to manage the service's traffic. +| Allows limiting the nodes that can be selected to handle the service's traffic when sourceIPBy=LoadBalancerIP. +When present only a node whose labels match the specified selectors can be selected +for handling the service's traffic. +When it is not specified any node in the cluster can be chosen to manage the service's traffic. | `sourceIPBy` | `string` -| Determines the source IP of egress traffic originating from the pods backing the LoadBalancer Service. When `LoadBalancerIP` the source IP is set to its LoadBalancer ingress IP. When `Network` the source IP is set according to the interface of the Network, leveraging the masquerade rules that are already in place. Typically these rules specify SNAT to the IP of the outgoing interface, which means the packet will typically leave with the IP of the node. +| Determines the source IP of egress traffic originating from the pods backing the LoadBalancer Service. +When `LoadBalancerIP` the source IP is set to its LoadBalancer ingress IP. +When `Network` the source IP is set according to the interface of the Network, +leveraging the masquerade rules that are already in place. +Typically these rules specify SNAT to the IP of the outgoing interface, +which means the packet will typically leave with the IP of the node. |=== === .spec.nodeSelector Description:: + -- -Allows limiting the nodes that can be selected to handle the service's traffic when sourceIPBy=LoadBalancerIP. When present only a node whose labels match the specified selectors can be selected for handling the service's traffic. When it is not specified any node in the cluster can be chosen to manage the service's traffic. +Allows limiting the nodes that can be selected to handle the service's traffic when sourceIPBy=LoadBalancerIP. +When present only a node whose labels match the specified selectors can be selected +for handling the service's traffic. +When it is not specified any node in the cluster can be chosen to manage the service's traffic. -- Type:: @@ -99,11 +117,14 @@ Type:: | `matchExpressions[]` | `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. +| A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. | `matchLabels` | `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. +| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels +map is equivalent to an element of matchExpressions, whose key field is "key", the +operator is "In", and the values array contains only "value". The requirements are ANDed. |=== === .spec.nodeSelector.matchExpressions @@ -123,7 +144,8 @@ Type:: Description:: + -- -A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. +A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. -- Type:: @@ -145,11 +167,15 @@ Required:: | `operator` | `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. +| operator represents a key's relationship to a set of values. +Valid operators are In, NotIn, Exists and DoesNotExist. | `values` | `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. +| values is an array of string values. If the operator is In or NotIn, +the values array must be non-empty. If the operator is Exists or DoesNotExist, +the values array must be empty. This array is replaced during a strategic +merge patch. |=== === .status @@ -173,7 +199,8 @@ Required:: | `host` | `string` -| The name of the node selected to handle the service's traffic. In case sourceIPBy=Network the field will be set to "ALL". +| The name of the node selected to handle the service's traffic. +In case sourceIPBy=Network the field will be set to "ALL". |=== diff --git a/rest_api/network_apis/gateway-gateway-networking-k8s-io-v1.adoc b/rest_api/network_apis/gateway-gateway-networking-k8s-io-v1.adoc new file mode 100644 index 0000000000..a0dc7ea9d9 --- /dev/null +++ b/rest_api/network_apis/gateway-gateway-networking-k8s-io-v1.adoc @@ -0,0 +1,1950 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="gateway-gateway-networking-k8s-io-v1"] += Gateway [gateway.networking.k8s.io/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +Gateway represents an instance of a service-traffic handling infrastructure +by binding Listeners to a set of IP addresses. +-- + +Type:: + `object` + +Required:: + - `spec` + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| Spec defines the desired state of Gateway. + +| `status` +| `object` +| Status defines the current state of Gateway. + +|=== +=== .spec +Description:: ++ +-- +Spec defines the desired state of Gateway. +-- + +Type:: + `object` + +Required:: + - `gatewayClassName` + - `listeners` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `addresses` +| `array` +| Addresses requested for this Gateway. This is optional and behavior can +depend on the implementation. If a value is set in the spec and the +requested address is invalid or unavailable, the implementation MUST +indicate this in the associated entry in GatewayStatus.Addresses. + +The Addresses field represents a request for the address(es) on the +"outside of the Gateway", that traffic bound for this Gateway will use. +This could be the IP address or hostname of an external load balancer or +other networking infrastructure, or some other address that traffic will +be sent to. + +If no Addresses are specified, the implementation MAY schedule the +Gateway in an implementation-specific manner, assigning an appropriate +set of Addresses. + +The implementation MUST bind all Listeners to every GatewayAddress that +it assigns to the Gateway and add a corresponding entry in +GatewayStatus.Addresses. + +Support: Extended + +| `addresses[]` +| `object` +| GatewayAddress describes an address that can be bound to a Gateway. + +| `gatewayClassName` +| `string` +| GatewayClassName used for this Gateway. This is the name of a +GatewayClass resource. + +| `infrastructure` +| `object` +| Infrastructure defines infrastructure level attributes about this Gateway instance. + +Support: Extended + +| `listeners` +| `array` +| Listeners associated with this Gateway. Listeners define +logical endpoints that are bound on this Gateway's addresses. +At least one Listener MUST be specified. + +## Distinct Listeners + +Each Listener in a set of Listeners (for example, in a single Gateway) +MUST be _distinct_, in that a traffic flow MUST be able to be assigned to +exactly one listener. (This section uses "set of Listeners" rather than +"Listeners in a single Gateway" because implementations MAY merge configuration +from multiple Gateways onto a single data plane, and these rules _also_ +apply in that case). + +Practically, this means that each listener in a set MUST have a unique +combination of Port, Protocol, and, if supported by the protocol, Hostname. + +Some combinations of port, protocol, and TLS settings are considered +Core support and MUST be supported by implementations based on the objects +they support: + +HTTPRoute + +1. HTTPRoute, Port: 80, Protocol: HTTP +2. HTTPRoute, Port: 443, Protocol: HTTPS, TLS Mode: Terminate, TLS keypair provided + +TLSRoute + +1. TLSRoute, Port: 443, Protocol: TLS, TLS Mode: Passthrough + +"Distinct" Listeners have the following property: + +**The implementation can match inbound requests to a single distinct +Listener**. + +When multiple Listeners share values for fields (for +example, two Listeners with the same Port value), the implementation +can match requests to only one of the Listeners using other +Listener fields. + +When multiple listeners have the same value for the Protocol field, then +each of the Listeners with matching Protocol values MUST have different +values for other fields. + +The set of fields that MUST be different for a Listener differs per protocol. +The following rules define the rules for what fields MUST be considered for +Listeners to be distinct with each protocol currently defined in the +Gateway API spec. + +The set of listeners that all share a protocol value MUST have _different_ +values for _at least one_ of these fields to be distinct: + +* **HTTP, HTTPS, TLS**: Port, Hostname +* **TCP, UDP**: Port + +One **very** important rule to call out involves what happens when an +implementation: + +* Supports TCP protocol Listeners, as well as HTTP, HTTPS, or TLS protocol + Listeners, and +* sees HTTP, HTTPS, or TLS protocols with the same `port` as one with TCP + Protocol. + +In this case all the Listeners that share a port with the +TCP Listener are not distinct and so MUST NOT be accepted. + +If an implementation does not support TCP Protocol Listeners, then the +previous rule does not apply, and the TCP Listeners SHOULD NOT be +accepted. + +Note that the `tls` field is not used for determining if a listener is distinct, because +Listeners that _only_ differ on TLS config will still conflict in all cases. + +### Listeners that are distinct only by Hostname + +When the Listeners are distinct based only on Hostname, inbound request +hostnames MUST match from the most specific to least specific Hostname +values to choose the correct Listener and its associated set of Routes. + +Exact matches MUST be processed before wildcard matches, and wildcard +matches MUST be processed before fallback (empty Hostname value) +matches. For example, `"foo.example.com"` takes precedence over +`"*.example.com"`, and `"*.example.com"` takes precedence over `""`. + +Additionally, if there are multiple wildcard entries, more specific +wildcard entries must be processed before less specific wildcard entries. +For example, `"*.foo.example.com"` takes precedence over `"*.example.com"`. + +The precise definition here is that the higher the number of dots in the +hostname to the right of the wildcard character, the higher the precedence. + +The wildcard character will match any number of characters _and dots_ to +the left, however, so `"*.example.com"` will match both +`"foo.bar.example.com"` _and_ `"bar.example.com"`. + +## Handling indistinct Listeners + +If a set of Listeners contains Listeners that are not distinct, then those +Listeners are _Conflicted_, and the implementation MUST set the "Conflicted" +condition in the Listener Status to "True". + +The words "indistinct" and "conflicted" are considered equivalent for the +purpose of this documentation. + +Implementations MAY choose to accept a Gateway with some Conflicted +Listeners only if they only accept the partial Listener set that contains +no Conflicted Listeners. + +Specifically, an implementation MAY accept a partial Listener set subject to +the following rules: + +* The implementation MUST NOT pick one conflicting Listener as the winner. + ALL indistinct Listeners must not be accepted for processing. +* At least one distinct Listener MUST be present, or else the Gateway effectively + contains _no_ Listeners, and must be rejected from processing as a whole. + +The implementation MUST set a "ListenersNotValid" condition on the +Gateway Status when the Gateway contains Conflicted Listeners whether or +not they accept the Gateway. That Condition SHOULD clearly +indicate in the Message which Listeners are conflicted, and which are +Accepted. Additionally, the Listener status for those listeners SHOULD +indicate which Listeners are conflicted and not Accepted. + +## General Listener behavior + +Note that, for all distinct Listeners, requests SHOULD match at most one Listener. +For example, if Listeners are defined for "foo.example.com" and "*.example.com", a +request to "foo.example.com" SHOULD only be routed using routes attached +to the "foo.example.com" Listener (and not the "*.example.com" Listener). + +This concept is known as "Listener Isolation", and it is an Extended feature +of Gateway API. Implementations that do not support Listener Isolation MUST +clearly document this, and MUST NOT claim support for the +`GatewayHTTPListenerIsolation` feature. + +Implementations that _do_ support Listener Isolation SHOULD claim support +for the Extended `GatewayHTTPListenerIsolation` feature and pass the associated +conformance tests. + +## Compatible Listeners + +A Gateway's Listeners are considered _compatible_ if: + +1. They are distinct. +2. The implementation can serve them in compliance with the Addresses + requirement that all Listeners are available on all assigned + addresses. + +Compatible combinations in Extended support are expected to vary across +implementations. A combination that is compatible for one implementation +may not be compatible for another. + +For example, an implementation that cannot serve both TCP and UDP listeners +on the same address, or cannot mix HTTPS and generic TLS listens on the same port +would not consider those cases compatible, even though they are distinct. + +Implementations MAY merge separate Gateways onto a single set of +Addresses if all Listeners across all Gateways are compatible. + +In a future release the MinItems=1 requirement MAY be dropped. + +Support: Core + +| `listeners[]` +| `object` +| Listener embodies the concept of a logical endpoint where a Gateway accepts +network connections. + +|=== +=== .spec.addresses +Description:: ++ +-- +Addresses requested for this Gateway. This is optional and behavior can +depend on the implementation. If a value is set in the spec and the +requested address is invalid or unavailable, the implementation MUST +indicate this in the associated entry in GatewayStatus.Addresses. + +The Addresses field represents a request for the address(es) on the +"outside of the Gateway", that traffic bound for this Gateway will use. +This could be the IP address or hostname of an external load balancer or +other networking infrastructure, or some other address that traffic will +be sent to. + +If no Addresses are specified, the implementation MAY schedule the +Gateway in an implementation-specific manner, assigning an appropriate +set of Addresses. + +The implementation MUST bind all Listeners to every GatewayAddress that +it assigns to the Gateway and add a corresponding entry in +GatewayStatus.Addresses. + +Support: Extended +-- + +Type:: + `array` + + + + +=== .spec.addresses[] +Description:: ++ +-- +GatewayAddress describes an address that can be bound to a Gateway. +-- + +Type:: + `object` + +Required:: + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `type` +| `string` +| Type of the address. + +| `value` +| `string` +| Value of the address. The validity of the values will depend +on the type and support by the controller. + +Examples: `1.2.3.4`, `128::1`, `my-ip-address`. + +|=== +=== .spec.infrastructure +Description:: ++ +-- +Infrastructure defines infrastructure level attributes about this Gateway instance. + +Support: Extended +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `annotations` +| `object (string)` +| Annotations that SHOULD be applied to any resources created in response to this Gateway. + +For implementations creating other Kubernetes objects, this should be the `metadata.annotations` field on resources. +For other implementations, this refers to any relevant (implementation specific) "annotations" concepts. + +An implementation may chose to add additional implementation-specific annotations as they see fit. + +Support: Extended + +| `labels` +| `object (string)` +| Labels that SHOULD be applied to any resources created in response to this Gateway. + +For implementations creating other Kubernetes objects, this should be the `metadata.labels` field on resources. +For other implementations, this refers to any relevant (implementation specific) "labels" concepts. + +An implementation may chose to add additional implementation-specific labels as they see fit. + +If an implementation maps these labels to Pods, or any other resource that would need to be recreated when labels +change, it SHOULD clearly warn about this behavior in documentation. + +Support: Extended + +| `parametersRef` +| `object` +| ParametersRef is a reference to a resource that contains the configuration +parameters corresponding to the Gateway. This is optional if the +controller does not require any additional configuration. + +This follows the same semantics as GatewayClass's `parametersRef`, but on a per-Gateway basis + +The Gateway's GatewayClass may provide its own `parametersRef`. When both are specified, +the merging behavior is implementation specific. +It is generally recommended that GatewayClass provides defaults that can be overridden by a Gateway. + +If the referent cannot be found, refers to an unsupported kind, or when +the data within that resource is malformed, the Gateway SHOULD be +rejected with the "Accepted" status condition set to "False" and an +"InvalidParameters" reason. + +Support: Implementation-specific + +|=== +=== .spec.infrastructure.parametersRef +Description:: ++ +-- +ParametersRef is a reference to a resource that contains the configuration +parameters corresponding to the Gateway. This is optional if the +controller does not require any additional configuration. + +This follows the same semantics as GatewayClass's `parametersRef`, but on a per-Gateway basis + +The Gateway's GatewayClass may provide its own `parametersRef`. When both are specified, +the merging behavior is implementation specific. +It is generally recommended that GatewayClass provides defaults that can be overridden by a Gateway. + +If the referent cannot be found, refers to an unsupported kind, or when +the data within that resource is malformed, the Gateway SHOULD be +rejected with the "Accepted" status condition set to "False" and an +"InvalidParameters" reason. + +Support: Implementation-specific +-- + +Type:: + `object` + +Required:: + - `group` + - `kind` + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. + +| `kind` +| `string` +| Kind is kind of the referent. + +| `name` +| `string` +| Name is the name of the referent. + +|=== +=== .spec.listeners +Description:: ++ +-- +Listeners associated with this Gateway. Listeners define +logical endpoints that are bound on this Gateway's addresses. +At least one Listener MUST be specified. + +## Distinct Listeners + +Each Listener in a set of Listeners (for example, in a single Gateway) +MUST be _distinct_, in that a traffic flow MUST be able to be assigned to +exactly one listener. (This section uses "set of Listeners" rather than +"Listeners in a single Gateway" because implementations MAY merge configuration +from multiple Gateways onto a single data plane, and these rules _also_ +apply in that case). + +Practically, this means that each listener in a set MUST have a unique +combination of Port, Protocol, and, if supported by the protocol, Hostname. + +Some combinations of port, protocol, and TLS settings are considered +Core support and MUST be supported by implementations based on the objects +they support: + +HTTPRoute + +1. HTTPRoute, Port: 80, Protocol: HTTP +2. HTTPRoute, Port: 443, Protocol: HTTPS, TLS Mode: Terminate, TLS keypair provided + +TLSRoute + +1. TLSRoute, Port: 443, Protocol: TLS, TLS Mode: Passthrough + +"Distinct" Listeners have the following property: + +**The implementation can match inbound requests to a single distinct +Listener**. + +When multiple Listeners share values for fields (for +example, two Listeners with the same Port value), the implementation +can match requests to only one of the Listeners using other +Listener fields. + +When multiple listeners have the same value for the Protocol field, then +each of the Listeners with matching Protocol values MUST have different +values for other fields. + +The set of fields that MUST be different for a Listener differs per protocol. +The following rules define the rules for what fields MUST be considered for +Listeners to be distinct with each protocol currently defined in the +Gateway API spec. + +The set of listeners that all share a protocol value MUST have _different_ +values for _at least one_ of these fields to be distinct: + +* **HTTP, HTTPS, TLS**: Port, Hostname +* **TCP, UDP**: Port + +One **very** important rule to call out involves what happens when an +implementation: + +* Supports TCP protocol Listeners, as well as HTTP, HTTPS, or TLS protocol + Listeners, and +* sees HTTP, HTTPS, or TLS protocols with the same `port` as one with TCP + Protocol. + +In this case all the Listeners that share a port with the +TCP Listener are not distinct and so MUST NOT be accepted. + +If an implementation does not support TCP Protocol Listeners, then the +previous rule does not apply, and the TCP Listeners SHOULD NOT be +accepted. + +Note that the `tls` field is not used for determining if a listener is distinct, because +Listeners that _only_ differ on TLS config will still conflict in all cases. + +### Listeners that are distinct only by Hostname + +When the Listeners are distinct based only on Hostname, inbound request +hostnames MUST match from the most specific to least specific Hostname +values to choose the correct Listener and its associated set of Routes. + +Exact matches MUST be processed before wildcard matches, and wildcard +matches MUST be processed before fallback (empty Hostname value) +matches. For example, `"foo.example.com"` takes precedence over +`"*.example.com"`, and `"*.example.com"` takes precedence over `""`. + +Additionally, if there are multiple wildcard entries, more specific +wildcard entries must be processed before less specific wildcard entries. +For example, `"*.foo.example.com"` takes precedence over `"*.example.com"`. + +The precise definition here is that the higher the number of dots in the +hostname to the right of the wildcard character, the higher the precedence. + +The wildcard character will match any number of characters _and dots_ to +the left, however, so `"*.example.com"` will match both +`"foo.bar.example.com"` _and_ `"bar.example.com"`. + +## Handling indistinct Listeners + +If a set of Listeners contains Listeners that are not distinct, then those +Listeners are _Conflicted_, and the implementation MUST set the "Conflicted" +condition in the Listener Status to "True". + +The words "indistinct" and "conflicted" are considered equivalent for the +purpose of this documentation. + +Implementations MAY choose to accept a Gateway with some Conflicted +Listeners only if they only accept the partial Listener set that contains +no Conflicted Listeners. + +Specifically, an implementation MAY accept a partial Listener set subject to +the following rules: + +* The implementation MUST NOT pick one conflicting Listener as the winner. + ALL indistinct Listeners must not be accepted for processing. +* At least one distinct Listener MUST be present, or else the Gateway effectively + contains _no_ Listeners, and must be rejected from processing as a whole. + +The implementation MUST set a "ListenersNotValid" condition on the +Gateway Status when the Gateway contains Conflicted Listeners whether or +not they accept the Gateway. That Condition SHOULD clearly +indicate in the Message which Listeners are conflicted, and which are +Accepted. Additionally, the Listener status for those listeners SHOULD +indicate which Listeners are conflicted and not Accepted. + +## General Listener behavior + +Note that, for all distinct Listeners, requests SHOULD match at most one Listener. +For example, if Listeners are defined for "foo.example.com" and "*.example.com", a +request to "foo.example.com" SHOULD only be routed using routes attached +to the "foo.example.com" Listener (and not the "*.example.com" Listener). + +This concept is known as "Listener Isolation", and it is an Extended feature +of Gateway API. Implementations that do not support Listener Isolation MUST +clearly document this, and MUST NOT claim support for the +`GatewayHTTPListenerIsolation` feature. + +Implementations that _do_ support Listener Isolation SHOULD claim support +for the Extended `GatewayHTTPListenerIsolation` feature and pass the associated +conformance tests. + +## Compatible Listeners + +A Gateway's Listeners are considered _compatible_ if: + +1. They are distinct. +2. The implementation can serve them in compliance with the Addresses + requirement that all Listeners are available on all assigned + addresses. + +Compatible combinations in Extended support are expected to vary across +implementations. A combination that is compatible for one implementation +may not be compatible for another. + +For example, an implementation that cannot serve both TCP and UDP listeners +on the same address, or cannot mix HTTPS and generic TLS listens on the same port +would not consider those cases compatible, even though they are distinct. + +Implementations MAY merge separate Gateways onto a single set of +Addresses if all Listeners across all Gateways are compatible. + +In a future release the MinItems=1 requirement MAY be dropped. + +Support: Core +-- + +Type:: + `array` + + + + +=== .spec.listeners[] +Description:: ++ +-- +Listener embodies the concept of a logical endpoint where a Gateway accepts +network connections. +-- + +Type:: + `object` + +Required:: + - `name` + - `port` + - `protocol` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `allowedRoutes` +| `object` +| AllowedRoutes defines the types of routes that MAY be attached to a +Listener and the trusted namespaces where those Route resources MAY be +present. + +Although a client request may match multiple route rules, only one rule +may ultimately receive the request. Matching precedence MUST be +determined in order of the following criteria: + +* The most specific match as defined by the Route type. +* The oldest Route based on creation timestamp. For example, a Route with + a creation timestamp of "2020-09-08 01:02:03" is given precedence over + a Route with a creation timestamp of "2020-09-08 01:02:04". +* If everything else is equivalent, the Route appearing first in + alphabetical order (namespace/name) should be given precedence. For + example, foo/bar is given precedence over foo/baz. + +All valid rules within a Route attached to this Listener should be +implemented. Invalid Route rules can be ignored (sometimes that will mean +the full Route). If a Route rule transitions from valid to invalid, +support for that Route rule should be dropped to ensure consistency. For +example, even if a filter specified by a Route rule is invalid, the rest +of the rules within that Route should still be supported. + +Support: Core + +| `hostname` +| `string` +| Hostname specifies the virtual hostname to match for protocol types that +define this concept. When unspecified, all hostnames are matched. This +field is ignored for protocols that don't require hostname based +matching. + +Implementations MUST apply Hostname matching appropriately for each of +the following protocols: + +* TLS: The Listener Hostname MUST match the SNI. +* HTTP: The Listener Hostname MUST match the Host header of the request. +* HTTPS: The Listener Hostname SHOULD match both the SNI and Host header. + Note that this does not require the SNI and Host header to be the same. + The semantics of this are described in more detail below. + +To ensure security, Section 11.1 of RFC-6066 emphasizes that server +implementations that rely on SNI hostname matching MUST also verify +hostnames within the application protocol. + +Section 9.1.2 of RFC-7540 provides a mechanism for servers to reject the +reuse of a connection by responding with the HTTP 421 Misdirected Request +status code. This indicates that the origin server has rejected the +request because it appears to have been misdirected. + +To detect misdirected requests, Gateways SHOULD match the authority of +the requests with all the SNI hostname(s) configured across all the +Gateway Listeners on the same port and protocol: + +* If another Listener has an exact match or more specific wildcard entry, + the Gateway SHOULD return a 421. +* If the current Listener (selected by SNI matching during ClientHello) + does not match the Host: + * If another Listener does match the Host the Gateway SHOULD return a + 421. + * If no other Listener matches the Host, the Gateway MUST return a + 404. + +For HTTPRoute and TLSRoute resources, there is an interaction with the +`spec.hostnames` array. When both listener and route specify hostnames, +there MUST be an intersection between the values for a Route to be +accepted. For more information, refer to the Route specific Hostnames +documentation. + +Hostnames that are prefixed with a wildcard label (`*.`) are interpreted +as a suffix match. That means that a match for `*.example.com` would match +both `test.example.com`, and `foo.test.example.com`, but not `example.com`. + +Support: Core + +| `name` +| `string` +| Name is the name of the Listener. This name MUST be unique within a +Gateway. + +Support: Core + +| `port` +| `integer` +| Port is the network port. Multiple listeners may use the +same port, subject to the Listener compatibility rules. + +Support: Core + +| `protocol` +| `string` +| Protocol specifies the network protocol this listener expects to receive. + +Support: Core + +| `tls` +| `object` +| TLS is the TLS configuration for the Listener. This field is required if +the Protocol field is "HTTPS" or "TLS". It is invalid to set this field +if the Protocol field is "HTTP", "TCP", or "UDP". + +The association of SNIs to Certificate defined in GatewayTLSConfig is +defined based on the Hostname field for this listener. + +The GatewayClass MUST use the longest matching SNI out of all +available certificates for any TLS handshake. + +Support: Core + +|=== +=== .spec.listeners[].allowedRoutes +Description:: ++ +-- +AllowedRoutes defines the types of routes that MAY be attached to a +Listener and the trusted namespaces where those Route resources MAY be +present. + +Although a client request may match multiple route rules, only one rule +may ultimately receive the request. Matching precedence MUST be +determined in order of the following criteria: + +* The most specific match as defined by the Route type. +* The oldest Route based on creation timestamp. For example, a Route with + a creation timestamp of "2020-09-08 01:02:03" is given precedence over + a Route with a creation timestamp of "2020-09-08 01:02:04". +* If everything else is equivalent, the Route appearing first in + alphabetical order (namespace/name) should be given precedence. For + example, foo/bar is given precedence over foo/baz. + +All valid rules within a Route attached to this Listener should be +implemented. Invalid Route rules can be ignored (sometimes that will mean +the full Route). If a Route rule transitions from valid to invalid, +support for that Route rule should be dropped to ensure consistency. For +example, even if a filter specified by a Route rule is invalid, the rest +of the rules within that Route should still be supported. + +Support: Core +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `kinds` +| `array` +| Kinds specifies the groups and kinds of Routes that are allowed to bind +to this Gateway Listener. When unspecified or empty, the kinds of Routes +selected are determined using the Listener protocol. + +A RouteGroupKind MUST correspond to kinds of Routes that are compatible +with the application protocol specified in the Listener's Protocol field. +If an implementation does not support or recognize this resource type, it +MUST set the "ResolvedRefs" condition to False for this Listener with the +"InvalidRouteKinds" reason. + +Support: Core + +| `kinds[]` +| `object` +| RouteGroupKind indicates the group and kind of a Route resource. + +| `namespaces` +| `object` +| Namespaces indicates namespaces from which Routes may be attached to this +Listener. This is restricted to the namespace of this Gateway by default. + +Support: Core + +|=== +=== .spec.listeners[].allowedRoutes.kinds +Description:: ++ +-- +Kinds specifies the groups and kinds of Routes that are allowed to bind +to this Gateway Listener. When unspecified or empty, the kinds of Routes +selected are determined using the Listener protocol. + +A RouteGroupKind MUST correspond to kinds of Routes that are compatible +with the application protocol specified in the Listener's Protocol field. +If an implementation does not support or recognize this resource type, it +MUST set the "ResolvedRefs" condition to False for this Listener with the +"InvalidRouteKinds" reason. + +Support: Core +-- + +Type:: + `array` + + + + +=== .spec.listeners[].allowedRoutes.kinds[] +Description:: ++ +-- +RouteGroupKind indicates the group and kind of a Route resource. +-- + +Type:: + `object` + +Required:: + - `kind` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the Route. + +| `kind` +| `string` +| Kind is the kind of the Route. + +|=== +=== .spec.listeners[].allowedRoutes.namespaces +Description:: ++ +-- +Namespaces indicates namespaces from which Routes may be attached to this +Listener. This is restricted to the namespace of this Gateway by default. + +Support: Core +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `from` +| `string` +| From indicates where Routes will be selected for this Gateway. Possible +values are: + +* All: Routes in all namespaces may be used by this Gateway. +* Selector: Routes in namespaces selected by the selector may be used by + this Gateway. +* Same: Only Routes in the same namespace may be used by this Gateway. + +Support: Core + +| `selector` +| `object` +| Selector must be specified when From is set to "Selector". In that case, +only Routes in Namespaces matching this Selector will be selected by this +Gateway. This field is ignored for other values of "From". + +Support: Core + +|=== +=== .spec.listeners[].allowedRoutes.namespaces.selector +Description:: ++ +-- +Selector must be specified when From is set to "Selector". In that case, +only Routes in Namespaces matching this Selector will be selected by this +Gateway. This field is ignored for other values of "From". + +Support: Core +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `matchExpressions` +| `array` +| matchExpressions is a list of label selector requirements. The requirements are ANDed. + +| `matchExpressions[]` +| `object` +| A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. + +| `matchLabels` +| `object (string)` +| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels +map is equivalent to an element of matchExpressions, whose key field is "key", the +operator is "In", and the values array contains only "value". The requirements are ANDed. + +|=== +=== .spec.listeners[].allowedRoutes.namespaces.selector.matchExpressions +Description:: ++ +-- +matchExpressions is a list of label selector requirements. The requirements are ANDed. +-- + +Type:: + `array` + + + + +=== .spec.listeners[].allowedRoutes.namespaces.selector.matchExpressions[] +Description:: ++ +-- +A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. +-- + +Type:: + `object` + +Required:: + - `key` + - `operator` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| key is the label key that the selector applies to. + +| `operator` +| `string` +| operator represents a key's relationship to a set of values. +Valid operators are In, NotIn, Exists and DoesNotExist. + +| `values` +| `array (string)` +| values is an array of string values. If the operator is In or NotIn, +the values array must be non-empty. If the operator is Exists or DoesNotExist, +the values array must be empty. This array is replaced during a strategic +merge patch. + +|=== +=== .spec.listeners[].tls +Description:: ++ +-- +TLS is the TLS configuration for the Listener. This field is required if +the Protocol field is "HTTPS" or "TLS". It is invalid to set this field +if the Protocol field is "HTTP", "TCP", or "UDP". + +The association of SNIs to Certificate defined in GatewayTLSConfig is +defined based on the Hostname field for this listener. + +The GatewayClass MUST use the longest matching SNI out of all +available certificates for any TLS handshake. + +Support: Core +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `certificateRefs` +| `array` +| CertificateRefs contains a series of references to Kubernetes objects that +contains TLS certificates and private keys. These certificates are used to +establish a TLS handshake for requests that match the hostname of the +associated listener. + +A single CertificateRef to a Kubernetes Secret has "Core" support. +Implementations MAY choose to support attaching multiple certificates to +a Listener, but this behavior is implementation-specific. + +References to a resource in different namespace are invalid UNLESS there +is a ReferenceGrant in the target namespace that allows the certificate +to be attached. If a ReferenceGrant does not allow this reference, the +"ResolvedRefs" condition MUST be set to False for this listener with the +"RefNotPermitted" reason. + +This field is required to have at least one element when the mode is set +to "Terminate" (default) and is optional otherwise. + +CertificateRefs can reference to standard Kubernetes resources, i.e. +Secret, or implementation-specific custom resources. + +Support: Core - A single reference to a Kubernetes Secret of type kubernetes.io/tls + +Support: Implementation-specific (More than one reference or other resource types) + +| `certificateRefs[]` +| `object` +| SecretObjectReference identifies an API object including its namespace, +defaulting to Secret. + +The API object must be valid in the cluster; the Group and Kind must +be registered in the cluster for this reference to be valid. + +References to objects with invalid Group and Kind are not valid, and must +be rejected by the implementation, with appropriate Conditions set +on the containing object. + +| `mode` +| `string` +| Mode defines the TLS behavior for the TLS session initiated by the client. +There are two possible modes: + +- Terminate: The TLS session between the downstream client and the + Gateway is terminated at the Gateway. This mode requires certificates + to be specified in some way, such as populating the certificateRefs + field. +- Passthrough: The TLS session is NOT terminated by the Gateway. This + implies that the Gateway can't decipher the TLS stream except for + the ClientHello message of the TLS protocol. The certificateRefs field + is ignored in this mode. + +Support: Core + +| `options` +| `object (string)` +| Options are a list of key/value pairs to enable extended TLS +configuration for each implementation. For example, configuring the +minimum TLS version or supported cipher suites. + +A set of common keys MAY be defined by the API in the future. To avoid +any ambiguity, implementation-specific definitions MUST use +domain-prefixed names, such as `example.com/my-custom-option`. +Un-prefixed names are reserved for key names defined by Gateway API. + +Support: Implementation-specific + +|=== +=== .spec.listeners[].tls.certificateRefs +Description:: ++ +-- +CertificateRefs contains a series of references to Kubernetes objects that +contains TLS certificates and private keys. These certificates are used to +establish a TLS handshake for requests that match the hostname of the +associated listener. + +A single CertificateRef to a Kubernetes Secret has "Core" support. +Implementations MAY choose to support attaching multiple certificates to +a Listener, but this behavior is implementation-specific. + +References to a resource in different namespace are invalid UNLESS there +is a ReferenceGrant in the target namespace that allows the certificate +to be attached. If a ReferenceGrant does not allow this reference, the +"ResolvedRefs" condition MUST be set to False for this listener with the +"RefNotPermitted" reason. + +This field is required to have at least one element when the mode is set +to "Terminate" (default) and is optional otherwise. + +CertificateRefs can reference to standard Kubernetes resources, i.e. +Secret, or implementation-specific custom resources. + +Support: Core - A single reference to a Kubernetes Secret of type kubernetes.io/tls + +Support: Implementation-specific (More than one reference or other resource types) +-- + +Type:: + `array` + + + + +=== .spec.listeners[].tls.certificateRefs[] +Description:: ++ +-- +SecretObjectReference identifies an API object including its namespace, +defaulting to Secret. + +The API object must be valid in the cluster; the Group and Kind must +be registered in the cluster for this reference to be valid. + +References to objects with invalid Group and Kind are not valid, and must +be rejected by the implementation, with appropriate Conditions set +on the containing object. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is kind of the referent. For example "Secret". + +| `name` +| `string` +| Name is the name of the referent. + +| `namespace` +| `string` +| Namespace is the namespace of the referenced object. When unspecified, the local +namespace is inferred. + +Note that when a namespace different than the local namespace is specified, +a ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. + +Support: Core + +|=== +=== .status +Description:: ++ +-- +Status defines the current state of Gateway. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `addresses` +| `array` +| Addresses lists the network addresses that have been bound to the +Gateway. + +This list may differ from the addresses provided in the spec under some +conditions: + + * no addresses are specified, all addresses are dynamically assigned + * a combination of specified and dynamic addresses are assigned + * a specified address was unusable (e.g. already in use) + +| `addresses[]` +| `object` +| GatewayStatusAddress describes a network address that is bound to a Gateway. + +| `conditions` +| `array` +| Conditions describe the current conditions of the Gateway. + +Implementations should prefer to express Gateway conditions +using the `GatewayConditionType` and `GatewayConditionReason` +constants so that operators and tools can converge on a common +vocabulary to describe Gateway state. + +Known condition types are: + +* "Accepted" +* "Programmed" +* "Ready" + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `listeners` +| `array` +| Listeners provide status for each unique listener port defined in the Spec. + +| `listeners[]` +| `object` +| ListenerStatus is the status associated with a Listener. + +|=== +=== .status.addresses +Description:: ++ +-- +Addresses lists the network addresses that have been bound to the +Gateway. + +This list may differ from the addresses provided in the spec under some +conditions: + + * no addresses are specified, all addresses are dynamically assigned + * a combination of specified and dynamic addresses are assigned + * a specified address was unusable (e.g. already in use) +-- + +Type:: + `array` + + + + +=== .status.addresses[] +Description:: ++ +-- +GatewayStatusAddress describes a network address that is bound to a Gateway. +-- + +Type:: + `object` + +Required:: + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `type` +| `string` +| Type of the address. + +| `value` +| `string` +| Value of the address. The validity of the values will depend +on the type and support by the controller. + +Examples: `1.2.3.4`, `128::1`, `my-ip-address`. + +|=== +=== .status.conditions +Description:: ++ +-- +Conditions describe the current conditions of the Gateway. + +Implementations should prefer to express Gateway conditions +using the `GatewayConditionType` and `GatewayConditionReason` +constants so that operators and tools can converge on a common +vocabulary to describe Gateway state. + +Known condition types are: + +* "Accepted" +* "Programmed" +* "Ready" +-- + +Type:: + `array` + + + + +=== .status.conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== +=== .status.listeners +Description:: ++ +-- +Listeners provide status for each unique listener port defined in the Spec. +-- + +Type:: + `array` + + + + +=== .status.listeners[] +Description:: ++ +-- +ListenerStatus is the status associated with a Listener. +-- + +Type:: + `object` + +Required:: + - `attachedRoutes` + - `conditions` + - `name` + - `supportedKinds` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `attachedRoutes` +| `integer` +| AttachedRoutes represents the total number of Routes that have been +successfully attached to this Listener. + +Successful attachment of a Route to a Listener is based solely on the +combination of the AllowedRoutes field on the corresponding Listener +and the Route's ParentRefs field. A Route is successfully attached to +a Listener when it is selected by the Listener's AllowedRoutes field +AND the Route has a valid ParentRef selecting the whole Gateway +resource or a specific Listener as a parent resource (more detail on +attachment semantics can be found in the documentation on the various +Route kinds ParentRefs fields). Listener or Route status does not impact +successful attachment, i.e. the AttachedRoutes field count MUST be set +for Listeners with condition Accepted: false and MUST count successfully +attached Routes that may themselves have Accepted: false conditions. + +Uses for this field include troubleshooting Route attachment and +measuring blast radius/impact of changes to a Listener. + +| `conditions` +| `array` +| Conditions describe the current condition of this listener. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `name` +| `string` +| Name is the name of the Listener that this status corresponds to. + +| `supportedKinds` +| `array` +| SupportedKinds is the list indicating the Kinds supported by this +listener. This MUST represent the kinds an implementation supports for +that Listener configuration. + +If kinds are specified in Spec that are not supported, they MUST NOT +appear in this list and an implementation MUST set the "ResolvedRefs" +condition to "False" with the "InvalidRouteKinds" reason. If both valid +and invalid Route kinds are specified, the implementation MUST +reference the valid Route kinds that have been specified. + +| `supportedKinds[]` +| `object` +| RouteGroupKind indicates the group and kind of a Route resource. + +|=== +=== .status.listeners[].conditions +Description:: ++ +-- +Conditions describe the current condition of this listener. +-- + +Type:: + `array` + + + + +=== .status.listeners[].conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== +=== .status.listeners[].supportedKinds +Description:: ++ +-- +SupportedKinds is the list indicating the Kinds supported by this +listener. This MUST represent the kinds an implementation supports for +that Listener configuration. + +If kinds are specified in Spec that are not supported, they MUST NOT +appear in this list and an implementation MUST set the "ResolvedRefs" +condition to "False" with the "InvalidRouteKinds" reason. If both valid +and invalid Route kinds are specified, the implementation MUST +reference the valid Route kinds that have been specified. +-- + +Type:: + `array` + + + + +=== .status.listeners[].supportedKinds[] +Description:: ++ +-- +RouteGroupKind indicates the group and kind of a Route resource. +-- + +Type:: + `object` + +Required:: + - `kind` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the Route. + +| `kind` +| `string` +| Kind is the kind of the Route. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/gateway.networking.k8s.io/v1/gateways` +- `GET`: list objects of kind Gateway +* `/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/gateways` +- `DELETE`: delete collection of Gateway +- `GET`: list objects of kind Gateway +- `POST`: create a Gateway +* `/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/gateways/{name}` +- `DELETE`: delete a Gateway +- `GET`: read the specified Gateway +- `PATCH`: partially update the specified Gateway +- `PUT`: replace the specified Gateway +* `/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/gateways/{name}/status` +- `GET`: read status of the specified Gateway +- `PATCH`: partially update status of the specified Gateway +- `PUT`: replace status of the specified Gateway + + +=== /apis/gateway.networking.k8s.io/v1/gateways + + + +HTTP method:: + `GET` + +Description:: + list objects of kind Gateway + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-networking-gateway-v1-GatewayList[`GatewayList`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/gateways + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of Gateway + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind Gateway + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-networking-gateway-v1-GatewayList[`GatewayList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a Gateway + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 201 - Created +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 202 - Accepted +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/gateways/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the Gateway +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a Gateway + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified Gateway + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified Gateway + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified Gateway + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 201 - Created +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/gateways/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the Gateway +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified Gateway + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified Gateway + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified Gateway + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 201 - Created +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`Gateway`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc b/rest_api/network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc new file mode 100644 index 0000000000..e568272835 --- /dev/null +++ b/rest_api/network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc @@ -0,0 +1,626 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="gatewayclass-gateway-networking-k8s-io-v1"] += GatewayClass [gateway.networking.k8s.io/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +GatewayClass describes a class of Gateways available to the user for creating +Gateway resources. + +It is recommended that this resource be used as a template for Gateways. This +means that a Gateway is based on the state of the GatewayClass at the time it +was created and changes to the GatewayClass or associated parameters are not +propagated down to existing Gateways. This recommendation is intended to +limit the blast radius of changes to GatewayClass or associated parameters. +If implementations choose to propagate GatewayClass changes to existing +Gateways, that MUST be clearly documented by the implementation. + +Whenever one or more Gateways are using a GatewayClass, implementations SHOULD +add the `gateway-exists-finalizer.gateway.networking.k8s.io` finalizer on the +associated GatewayClass. This ensures that a GatewayClass associated with a +Gateway is not deleted while in use. + +GatewayClass is a Cluster level resource. +-- + +Type:: + `object` + +Required:: + - `spec` + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| Spec defines the desired state of GatewayClass. + +| `status` +| `object` +| Status defines the current state of GatewayClass. + +Implementations MUST populate status on all GatewayClass resources which +specify their controller name. + +|=== +=== .spec +Description:: ++ +-- +Spec defines the desired state of GatewayClass. +-- + +Type:: + `object` + +Required:: + - `controllerName` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `controllerName` +| `string` +| ControllerName is the name of the controller that is managing Gateways of +this class. The value of this field MUST be a domain prefixed path. + +Example: "example.net/gateway-controller". + +This field is not mutable and cannot be empty. + +Support: Core + +| `description` +| `string` +| Description helps describe a GatewayClass with more details. + +| `parametersRef` +| `object` +| ParametersRef is a reference to a resource that contains the configuration +parameters corresponding to the GatewayClass. This is optional if the +controller does not require any additional configuration. + +ParametersRef can reference a standard Kubernetes resource, i.e. ConfigMap, +or an implementation-specific custom resource. The resource can be +cluster-scoped or namespace-scoped. + +If the referent cannot be found, refers to an unsupported kind, or when +the data within that resource is malformed, the GatewayClass SHOULD be +rejected with the "Accepted" status condition set to "False" and an +"InvalidParameters" reason. + +A Gateway for this GatewayClass may provide its own `parametersRef`. When both are specified, +the merging behavior is implementation specific. +It is generally recommended that GatewayClass provides defaults that can be overridden by a Gateway. + +Support: Implementation-specific + +|=== +=== .spec.parametersRef +Description:: ++ +-- +ParametersRef is a reference to a resource that contains the configuration +parameters corresponding to the GatewayClass. This is optional if the +controller does not require any additional configuration. + +ParametersRef can reference a standard Kubernetes resource, i.e. ConfigMap, +or an implementation-specific custom resource. The resource can be +cluster-scoped or namespace-scoped. + +If the referent cannot be found, refers to an unsupported kind, or when +the data within that resource is malformed, the GatewayClass SHOULD be +rejected with the "Accepted" status condition set to "False" and an +"InvalidParameters" reason. + +A Gateway for this GatewayClass may provide its own `parametersRef`. When both are specified, +the merging behavior is implementation specific. +It is generally recommended that GatewayClass provides defaults that can be overridden by a Gateway. + +Support: Implementation-specific +-- + +Type:: + `object` + +Required:: + - `group` + - `kind` + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. + +| `kind` +| `string` +| Kind is kind of the referent. + +| `name` +| `string` +| Name is the name of the referent. + +| `namespace` +| `string` +| Namespace is the namespace of the referent. +This field is required when referring to a Namespace-scoped resource and +MUST be unset when referring to a Cluster-scoped resource. + +|=== +=== .status +Description:: ++ +-- +Status defines the current state of GatewayClass. + +Implementations MUST populate status on all GatewayClass resources which +specify their controller name. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| Conditions is the current status from the controller for +this GatewayClass. + +Controllers should prefer to publish conditions using values +of GatewayClassConditionType for the type of each Condition. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +|=== +=== .status.conditions +Description:: ++ +-- +Conditions is the current status from the controller for +this GatewayClass. + +Controllers should prefer to publish conditions using values +of GatewayClassConditionType for the type of each Condition. +-- + +Type:: + `array` + + + + +=== .status.conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/gateway.networking.k8s.io/v1/gatewayclasses` +- `DELETE`: delete collection of GatewayClass +- `GET`: list objects of kind GatewayClass +- `POST`: create a GatewayClass +* `/apis/gateway.networking.k8s.io/v1/gatewayclasses/{name}` +- `DELETE`: delete a GatewayClass +- `GET`: read the specified GatewayClass +- `PATCH`: partially update the specified GatewayClass +- `PUT`: replace the specified GatewayClass +* `/apis/gateway.networking.k8s.io/v1/gatewayclasses/{name}/status` +- `GET`: read status of the specified GatewayClass +- `PATCH`: partially update status of the specified GatewayClass +- `PUT`: replace status of the specified GatewayClass + + +=== /apis/gateway.networking.k8s.io/v1/gatewayclasses + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of GatewayClass + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind GatewayClass + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-networking-gateway-v1-GatewayClassList[`GatewayClassList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a GatewayClass + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 201 - Created +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 202 - Accepted +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/gatewayclasses/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the GatewayClass +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a GatewayClass + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified GatewayClass + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified GatewayClass + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified GatewayClass + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 201 - Created +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/gatewayclasses/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the GatewayClass +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified GatewayClass + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified GatewayClass + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified GatewayClass + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 201 - Created +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`GatewayClass`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc b/rest_api/network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc new file mode 100644 index 0000000000..07a28e47d7 --- /dev/null +++ b/rest_api/network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc @@ -0,0 +1,3191 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="grpcroute-gateway-networking-k8s-io-v1"] += GRPCRoute [gateway.networking.k8s.io/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +GRPCRoute provides a way to route gRPC requests. This includes the capability +to match requests by hostname, gRPC service, gRPC method, or HTTP/2 header. +Filters can be used to specify additional processing steps. Backends specify +where matching requests will be routed. + +GRPCRoute falls under extended support within the Gateway API. Within the +following specification, the word "MUST" indicates that an implementation +supporting GRPCRoute must conform to the indicated requirement, but an +implementation not supporting this route type need not follow the requirement +unless explicitly indicated. + +Implementations supporting `GRPCRoute` with the `HTTPS` `ProtocolType` MUST +accept HTTP/2 connections without an initial upgrade from HTTP/1.1, i.e. via +ALPN. If the implementation does not support this, then it MUST set the +"Accepted" condition to "False" for the affected listener with a reason of +"UnsupportedProtocol". Implementations MAY also accept HTTP/2 connections +with an upgrade from HTTP/1. + +Implementations supporting `GRPCRoute` with the `HTTP` `ProtocolType` MUST +support HTTP/2 over cleartext TCP (h2c, +https://www.rfc-editor.org/rfc/rfc7540#section-3.1) without an initial +upgrade from HTTP/1.1, i.e. with prior knowledge +(https://www.rfc-editor.org/rfc/rfc7540#section-3.4). If the implementation +does not support this, then it MUST set the "Accepted" condition to "False" +for the affected listener with a reason of "UnsupportedProtocol". +Implementations MAY also accept HTTP/2 connections with an upgrade from +HTTP/1, i.e. without prior knowledge. +-- + +Type:: + `object` + + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| Spec defines the desired state of GRPCRoute. + +| `status` +| `object` +| Status defines the current state of GRPCRoute. + +|=== +=== .spec +Description:: ++ +-- +Spec defines the desired state of GRPCRoute. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `hostnames` +| `array (string)` +| Hostnames defines a set of hostnames to match against the GRPC +Host header to select a GRPCRoute to process the request. This matches +the RFC 1123 definition of a hostname with 2 notable exceptions: + +1. IPs are not allowed. +2. A hostname may be prefixed with a wildcard label (`*.`). The wildcard + label MUST appear by itself as the first label. + +If a hostname is specified by both the Listener and GRPCRoute, there +MUST be at least one intersecting hostname for the GRPCRoute to be +attached to the Listener. For example: + +* A Listener with `test.example.com` as the hostname matches GRPCRoutes + that have either not specified any hostnames, or have specified at + least one of `test.example.com` or `*.example.com`. +* A Listener with `*.example.com` as the hostname matches GRPCRoutes + that have either not specified any hostnames or have specified at least + one hostname that matches the Listener hostname. For example, + `test.example.com` and `*.example.com` would both match. On the other + hand, `example.com` and `test.example.net` would not match. + +Hostnames that are prefixed with a wildcard label (`*.`) are interpreted +as a suffix match. That means that a match for `*.example.com` would match +both `test.example.com`, and `foo.test.example.com`, but not `example.com`. + +If both the Listener and GRPCRoute have specified hostnames, any +GRPCRoute hostnames that do not match the Listener hostname MUST be +ignored. For example, if a Listener specified `*.example.com`, and the +GRPCRoute specified `test.example.com` and `test.example.net`, +`test.example.net` MUST NOT be considered for a match. + +If both the Listener and GRPCRoute have specified hostnames, and none +match with the criteria above, then the GRPCRoute MUST NOT be accepted by +the implementation. The implementation MUST raise an 'Accepted' Condition +with a status of `False` in the corresponding RouteParentStatus. + +If a Route (A) of type HTTPRoute or GRPCRoute is attached to a +Listener and that listener already has another Route (B) of the other +type attached and the intersection of the hostnames of A and B is +non-empty, then the implementation MUST accept exactly one of these two +routes, determined by the following criteria, in order: + +* The oldest Route based on creation timestamp. +* The Route appearing first in alphabetical order by + "{namespace}/{name}". + +The rejected Route MUST raise an 'Accepted' condition with a status of +'False' in the corresponding RouteParentStatus. + +Support: Core + +| `parentRefs` +| `array` +| ParentRefs references the resources (usually Gateways) that a Route wants +to be attached to. Note that the referenced parent resource needs to +allow this for the attachment to be complete. For Gateways, that means +the Gateway needs to allow attachment from Routes of this kind and +namespace. For Services, that means the Service must either be in the same +namespace for a "producer" route, or the mesh implementation must support +and allow "consumer" routes for the referenced Service. ReferenceGrant is +not applicable for governing ParentRefs to Services - it is not possible to +create a "producer" route for a Service in a different namespace from the +Route. + +There are two kinds of parent resources with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +This API may be extended in the future to support additional kinds of parent +resources. + +ParentRefs must be _distinct_. This means either that: + +* They select different objects. If this is the case, then parentRef + entries are distinct. In terms of fields, this means that the + multi-part key defined by `group`, `kind`, `namespace`, and `name` must + be unique across all parentRef entries in the Route. +* They do not select different objects, but for each optional field used, + each ParentRef that selects the same object must set the same set of + optional fields to different values. If one ParentRef sets a + combination of optional fields, all must set the same combination. + +Some examples: + +* If one ParentRef sets `sectionName`, all ParentRefs referencing the + same object must also set `sectionName`. +* If one ParentRef sets `port`, all ParentRefs referencing the same + object must also set `port`. +* If one ParentRef sets `sectionName` and `port`, all ParentRefs + referencing the same object must also set `sectionName` and `port`. + +It is possible to separately reference multiple distinct objects that may +be collapsed by an implementation. For example, some implementations may +choose to merge compatible Gateway Listeners together. If that is the +case, the list of routes attached to those resources should also be +merged. + +Note that for ParentRefs that cross namespace boundaries, there are specific +rules. Cross-namespace references are only valid if they are explicitly +allowed by something in the namespace they are referring to. For example, +Gateway has the AllowedRoutes field, and ReferenceGrant provides a +generic way to enable other kinds of cross-namespace reference. + +| `parentRefs[]` +| `object` +| ParentReference identifies an API object (usually a Gateway) that can be considered +a parent of this resource (usually a route). There are two kinds of parent resources +with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +This API may be extended in the future to support additional kinds of parent +resources. + +The API object must be valid in the cluster; the Group and Kind must +be registered in the cluster for this reference to be valid. + +| `rules` +| `array` +| Rules are a list of GRPC matchers, filters and actions. + +| `rules[]` +| `object` +| GRPCRouteRule defines the semantics for matching a gRPC request based on +conditions (matches), processing it (filters), and forwarding the request to +an API object (backendRefs). + +|=== +=== .spec.parentRefs +Description:: ++ +-- +ParentRefs references the resources (usually Gateways) that a Route wants +to be attached to. Note that the referenced parent resource needs to +allow this for the attachment to be complete. For Gateways, that means +the Gateway needs to allow attachment from Routes of this kind and +namespace. For Services, that means the Service must either be in the same +namespace for a "producer" route, or the mesh implementation must support +and allow "consumer" routes for the referenced Service. ReferenceGrant is +not applicable for governing ParentRefs to Services - it is not possible to +create a "producer" route for a Service in a different namespace from the +Route. + +There are two kinds of parent resources with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +This API may be extended in the future to support additional kinds of parent +resources. + +ParentRefs must be _distinct_. This means either that: + +* They select different objects. If this is the case, then parentRef + entries are distinct. In terms of fields, this means that the + multi-part key defined by `group`, `kind`, `namespace`, and `name` must + be unique across all parentRef entries in the Route. +* They do not select different objects, but for each optional field used, + each ParentRef that selects the same object must set the same set of + optional fields to different values. If one ParentRef sets a + combination of optional fields, all must set the same combination. + +Some examples: + +* If one ParentRef sets `sectionName`, all ParentRefs referencing the + same object must also set `sectionName`. +* If one ParentRef sets `port`, all ParentRefs referencing the same + object must also set `port`. +* If one ParentRef sets `sectionName` and `port`, all ParentRefs + referencing the same object must also set `sectionName` and `port`. + +It is possible to separately reference multiple distinct objects that may +be collapsed by an implementation. For example, some implementations may +choose to merge compatible Gateway Listeners together. If that is the +case, the list of routes attached to those resources should also be +merged. + +Note that for ParentRefs that cross namespace boundaries, there are specific +rules. Cross-namespace references are only valid if they are explicitly +allowed by something in the namespace they are referring to. For example, +Gateway has the AllowedRoutes field, and ReferenceGrant provides a +generic way to enable other kinds of cross-namespace reference. +-- + +Type:: + `array` + + + + +=== .spec.parentRefs[] +Description:: ++ +-- +ParentReference identifies an API object (usually a Gateway) that can be considered +a parent of this resource (usually a route). There are two kinds of parent resources +with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +This API may be extended in the future to support additional kinds of parent +resources. + +The API object must be valid in the cluster; the Group and Kind must +be registered in the cluster for this reference to be valid. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. +When unspecified, "gateway.networking.k8s.io" is inferred. +To set the core API group (such as for a "Service" kind referent), +Group must be explicitly set to "" (empty string). + +Support: Core + +| `kind` +| `string` +| Kind is kind of the referent. + +There are two kinds of parent resources with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +Support for other resources is Implementation-Specific. + +| `name` +| `string` +| Name is the name of the referent. + +Support: Core + +| `namespace` +| `string` +| Namespace is the namespace of the referent. When unspecified, this refers +to the local namespace of the Route. + +Note that there are specific rules for ParentRefs which cross namespace +boundaries. Cross-namespace references are only valid if they are explicitly +allowed by something in the namespace they are referring to. For example: +Gateway has the AllowedRoutes field, and ReferenceGrant provides a +generic way to enable any other kind of cross-namespace reference. + +Support: Core + +| `port` +| `integer` +| Port is the network port this Route targets. It can be interpreted +differently based on the type of parent resource. + +When the parent resource is a Gateway, this targets all listeners +listening on the specified port that also support this kind of Route(and +select this Route). It's not recommended to set `Port` unless the +networking behaviors specified in a Route must apply to a specific port +as opposed to a listener(s) whose port(s) may be changed. When both Port +and SectionName are specified, the name and port of the selected listener +must match both specified values. + +Implementations MAY choose to support other parent resources. +Implementations supporting other types of parent resources MUST clearly +document how/if Port is interpreted. + +For the purpose of status, an attachment is considered successful as +long as the parent resource accepts it partially. For example, Gateway +listeners can restrict which Routes can attach to them by Route kind, +namespace, or hostname. If 1 of 2 Gateway listeners accept attachment +from the referencing Route, the Route MUST be considered successfully +attached. If no Gateway listeners accept attachment from this Route, +the Route MUST be considered detached from the Gateway. + +Support: Extended + +| `sectionName` +| `string` +| SectionName is the name of a section within the target resource. In the +following resources, SectionName is interpreted as the following: + +* Gateway: Listener name. When both Port (experimental) and SectionName +are specified, the name and port of the selected listener must match +both specified values. +* Service: Port name. When both Port (experimental) and SectionName +are specified, the name and port of the selected listener must match +both specified values. + +Implementations MAY choose to support attaching Routes to other resources. +If that is the case, they MUST clearly document how SectionName is +interpreted. + +When unspecified (empty string), this will reference the entire resource. +For the purpose of status, an attachment is considered successful if at +least one section in the parent resource accepts it. For example, Gateway +listeners can restrict which Routes can attach to them by Route kind, +namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from +the referencing Route, the Route MUST be considered successfully +attached. If no Gateway listeners accept attachment from this Route, the +Route MUST be considered detached from the Gateway. + +Support: Core + +|=== +=== .spec.rules +Description:: ++ +-- +Rules are a list of GRPC matchers, filters and actions. +-- + +Type:: + `array` + + + + +=== .spec.rules[] +Description:: ++ +-- +GRPCRouteRule defines the semantics for matching a gRPC request based on +conditions (matches), processing it (filters), and forwarding the request to +an API object (backendRefs). +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `backendRefs` +| `array` +| BackendRefs defines the backend(s) where matching requests should be +sent. + +Failure behavior here depends on how many BackendRefs are specified and +how many are invalid. + +If *all* entries in BackendRefs are invalid, and there are also no filters +specified in this route rule, *all* traffic which matches this rule MUST +receive an `UNAVAILABLE` status. + +See the GRPCBackendRef definition for the rules about what makes a single +GRPCBackendRef invalid. + +When a GRPCBackendRef is invalid, `UNAVAILABLE` statuses MUST be returned for +requests that would have otherwise been routed to an invalid backend. If +multiple backends are specified, and some are invalid, the proportion of +requests that would otherwise have been routed to an invalid backend +MUST receive an `UNAVAILABLE` status. + +For example, if two backends are specified with equal weights, and one is +invalid, 50 percent of traffic MUST receive an `UNAVAILABLE` status. +Implementations may choose how that 50 percent is determined. + +Support: Core for Kubernetes Service + +Support: Implementation-specific for any other resource + +Support for weight: Core + +| `backendRefs[]` +| `object` +| GRPCBackendRef defines how a GRPCRoute forwards a gRPC request. + +Note that when a namespace different than the local namespace is specified, a +ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. + +| `filters` +| `array` +| Filters define the filters that are applied to requests that match +this rule. + +The effects of ordering of multiple behaviors are currently unspecified. +This can change in the future based on feedback during the alpha stage. + +Conformance-levels at this level are defined based on the type of filter: + +- ALL core filters MUST be supported by all implementations that support + GRPCRoute. +- Implementers are encouraged to support extended filters. +- Implementation-specific custom filters have no API guarantees across + implementations. + +Specifying the same filter multiple times is not supported unless explicitly +indicated in the filter. + +If an implementation cannot support a combination of filters, it must clearly +document that limitation. In cases where incompatible or unsupported +filters are specified and cause the `Accepted` condition to be set to status +`False`, implementations may use the `IncompatibleFilters` reason to specify +this configuration error. + +Support: Core + +| `filters[]` +| `object` +| GRPCRouteFilter defines processing steps that must be completed during the +request or response lifecycle. GRPCRouteFilters are meant as an extension +point to express processing that may be done in Gateway implementations. Some +examples include request or response modification, implementing +authentication strategies, rate-limiting, and traffic shaping. API +guarantee/conformance is defined based on the type of the filter. + +| `matches` +| `array` +| Matches define conditions used for matching the rule against incoming +gRPC requests. Each match is independent, i.e. this rule will be matched +if **any** one of the matches is satisfied. + +For example, take the following matches configuration: + + +matches: +- method: + service: foo.bar + headers: + values: + version: 2 +- method: + service: foo.bar.v2 + + +For a request to match against this rule, it MUST satisfy +EITHER of the two conditions: + +- service of foo.bar AND contains the header `version: 2` +- service of foo.bar.v2 + +See the documentation for GRPCRouteMatch on how to specify multiple +match conditions to be ANDed together. + +If no matches are specified, the implementation MUST match every gRPC request. + +Proxy or Load Balancer routing configuration generated from GRPCRoutes +MUST prioritize rules based on the following criteria, continuing on +ties. Merging MUST not be done between GRPCRoutes and HTTPRoutes. +Precedence MUST be given to the rule with the largest number of: + +* Characters in a matching non-wildcard hostname. +* Characters in a matching hostname. +* Characters in a matching service. +* Characters in a matching method. +* Header matches. + +If ties still exist across multiple Routes, matching precedence MUST be +determined in order of the following criteria, continuing on ties: + +* The oldest Route based on creation timestamp. +* The Route appearing first in alphabetical order by + "{namespace}/{name}". + +If ties still exist within the Route that has been given precedence, +matching precedence MUST be granted to the first matching rule meeting +the above criteria. + +| `matches[]` +| `object` +| GRPCRouteMatch defines the predicate used to match requests to a given +action. Multiple match types are ANDed together, i.e. the match will +evaluate to true only if all conditions are satisfied. + +For example, the match below will match a gRPC request only if its service +is `foo` AND it contains the `version: v1` header: + + +matches: + - method: + type: Exact + service: "foo" + headers: + - name: "version" + value "v1" + + + +|=== +=== .spec.rules[].backendRefs +Description:: ++ +-- +BackendRefs defines the backend(s) where matching requests should be +sent. + +Failure behavior here depends on how many BackendRefs are specified and +how many are invalid. + +If *all* entries in BackendRefs are invalid, and there are also no filters +specified in this route rule, *all* traffic which matches this rule MUST +receive an `UNAVAILABLE` status. + +See the GRPCBackendRef definition for the rules about what makes a single +GRPCBackendRef invalid. + +When a GRPCBackendRef is invalid, `UNAVAILABLE` statuses MUST be returned for +requests that would have otherwise been routed to an invalid backend. If +multiple backends are specified, and some are invalid, the proportion of +requests that would otherwise have been routed to an invalid backend +MUST receive an `UNAVAILABLE` status. + +For example, if two backends are specified with equal weights, and one is +invalid, 50 percent of traffic MUST receive an `UNAVAILABLE` status. +Implementations may choose how that 50 percent is determined. + +Support: Core for Kubernetes Service + +Support: Implementation-specific for any other resource + +Support for weight: Core +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[] +Description:: ++ +-- +GRPCBackendRef defines how a GRPCRoute forwards a gRPC request. + +Note that when a namespace different than the local namespace is specified, a +ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `filters` +| `array` +| Filters defined at this level MUST be executed if and only if the +request is being forwarded to the backend defined here. + +Support: Implementation-specific (For broader support of filters, use the +Filters field in GRPCRouteRule.) + +| `filters[]` +| `object` +| GRPCRouteFilter defines processing steps that must be completed during the +request or response lifecycle. GRPCRouteFilters are meant as an extension +point to express processing that may be done in Gateway implementations. Some +examples include request or response modification, implementing +authentication strategies, rate-limiting, and traffic shaping. API +guarantee/conformance is defined based on the type of the filter. + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is the Kubernetes resource kind of the referent. For example +"Service". + +Defaults to "Service" when not specified. + +ExternalName services can refer to CNAME DNS records that may live +outside of the cluster and as such are difficult to reason about in +terms of conformance. They also may not be safe to forward to (see +CVE-2021-25740 for more information). Implementations SHOULD NOT +support ExternalName Services. + +Support: Core (Services with a type other than ExternalName) + +Support: Implementation-specific (Services with type ExternalName) + +| `name` +| `string` +| Name is the name of the referent. + +| `namespace` +| `string` +| Namespace is the namespace of the backend. When unspecified, the local +namespace is inferred. + +Note that when a namespace different than the local namespace is specified, +a ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. + +Support: Core + +| `port` +| `integer` +| Port specifies the destination port number to use for this resource. +Port is required when the referent is a Kubernetes Service. In this +case, the port number is the service port number, not the target port. +For other resources, destination port might be derived from the referent +resource or this field. + +| `weight` +| `integer` +| Weight specifies the proportion of requests forwarded to the referenced +backend. This is computed as weight/(sum of all weights in this +BackendRefs list). For non-zero values, there may be some epsilon from +the exact proportion defined here depending on the precision an +implementation supports. Weight is not a percentage and the sum of +weights does not need to equal 100. + +If only one backend is specified and it has a weight greater than 0, 100% +of the traffic is forwarded to that backend. If weight is set to 0, no +traffic should be forwarded for this entry. If unspecified, weight +defaults to 1. + +Support for this field varies based on the context where used. + +|=== +=== .spec.rules[].backendRefs[].filters +Description:: ++ +-- +Filters defined at this level MUST be executed if and only if the +request is being forwarded to the backend defined here. + +Support: Implementation-specific (For broader support of filters, use the +Filters field in GRPCRouteRule.) +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[].filters[] +Description:: ++ +-- +GRPCRouteFilter defines processing steps that must be completed during the +request or response lifecycle. GRPCRouteFilters are meant as an extension +point to express processing that may be done in Gateway implementations. Some +examples include request or response modification, implementing +authentication strategies, rate-limiting, and traffic shaping. API +guarantee/conformance is defined based on the type of the filter. +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `extensionRef` +| `object` +| ExtensionRef is an optional, implementation-specific extension to the +"filter" behavior. For example, resource "myroutefilter" in group +"networking.example.net"). ExtensionRef MUST NOT be used for core and +extended filters. + +Support: Implementation-specific + +This filter can be used multiple times within the same rule. + +| `requestHeaderModifier` +| `object` +| RequestHeaderModifier defines a schema for a filter that modifies request +headers. + +Support: Core + +| `requestMirror` +| `object` +| RequestMirror defines a schema for a filter that mirrors requests. +Requests are sent to the specified destination, but responses from +that destination are ignored. + +This filter can be used multiple times within the same rule. Note that +not all implementations will be able to support mirroring to multiple +backends. + +Support: Extended + +| `responseHeaderModifier` +| `object` +| ResponseHeaderModifier defines a schema for a filter that modifies response +headers. + +Support: Extended + +| `type` +| `string` +| Type identifies the type of filter to apply. As with other API fields, +types are classified into three conformance levels: + +- Core: Filter types and their corresponding configuration defined by + "Support: Core" in this package, e.g. "RequestHeaderModifier". All + implementations supporting GRPCRoute MUST support core filters. + +- Extended: Filter types and their corresponding configuration defined by + "Support: Extended" in this package, e.g. "RequestMirror". Implementers + are encouraged to support extended filters. + +- Implementation-specific: Filters that are defined and supported by specific vendors. + In the future, filters showing convergence in behavior across multiple + implementations will be considered for inclusion in extended or core + conformance levels. Filter-specific configuration for such filters + is specified using the ExtensionRef field. `Type` MUST be set to + "ExtensionRef" for custom filters. + +Implementers are encouraged to define custom implementation types to +extend the core API with implementation-specific behavior. + +If a reference to a custom filter type cannot be resolved, the filter +MUST NOT be skipped. Instead, requests that would have been processed by +that filter MUST receive a HTTP error response. + +|=== +=== .spec.rules[].backendRefs[].filters[].extensionRef +Description:: ++ +-- +ExtensionRef is an optional, implementation-specific extension to the +"filter" behavior. For example, resource "myroutefilter" in group +"networking.example.net"). ExtensionRef MUST NOT be used for core and +extended filters. + +Support: Implementation-specific + +This filter can be used multiple times within the same rule. +-- + +Type:: + `object` + +Required:: + - `group` + - `kind` + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is kind of the referent. For example "HTTPRoute" or "Service". + +| `name` +| `string` +| Name is the name of the referent. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestHeaderModifier +Description:: ++ +-- +RequestHeaderModifier defines a schema for a filter that modifies request +headers. + +Support: Core +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `add` +| `array` +| Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz + +| `add[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +| `remove` +| `array (string)` +| Remove the given header(s) from the HTTP request before the action. The +value of Remove is a list of HTTP header names. Note that the header +names are case-insensitive (see +https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). + +Input: + GET /foo HTTP/1.1 + my-header1: foo + my-header2: bar + my-header3: baz + +Config: + remove: ["my-header1", "my-header3"] + +Output: + GET /foo HTTP/1.1 + my-header2: bar + +| `set` +| `array` +| Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar + +| `set[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestHeaderModifier.add +Description:: ++ +-- +Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[].filters[].requestHeaderModifier.add[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestHeaderModifier.set +Description:: ++ +-- +Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[].filters[].requestHeaderModifier.set[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestMirror +Description:: ++ +-- +RequestMirror defines a schema for a filter that mirrors requests. +Requests are sent to the specified destination, but responses from +that destination are ignored. + +This filter can be used multiple times within the same rule. Note that +not all implementations will be able to support mirroring to multiple +backends. + +Support: Extended +-- + +Type:: + `object` + +Required:: + - `backendRef` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `backendRef` +| `object` +| BackendRef references a resource where mirrored requests are sent. + +Mirrored requests must be sent only to a single destination endpoint +within this BackendRef, irrespective of how many endpoints are present +within this BackendRef. + +If the referent cannot be found, this BackendRef is invalid and must be +dropped from the Gateway. The controller must ensure the "ResolvedRefs" +condition on the Route status is set to `status: False` and not configure +this backend in the underlying implementation. + +If there is a cross-namespace reference to an *existing* object +that is not allowed by a ReferenceGrant, the controller must ensure the +"ResolvedRefs" condition on the Route is set to `status: False`, +with the "RefNotPermitted" reason and not configure this backend in the +underlying implementation. + +In either error case, the Message of the `ResolvedRefs` Condition +should be used to provide more detail about the problem. + +Support: Extended for Kubernetes Service + +Support: Implementation-specific for any other resource + +| `fraction` +| `object` +| Fraction represents the fraction of requests that should be +mirrored to BackendRef. + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. + +| `percent` +| `integer` +| Percent represents the percentage of requests that should be +mirrored to BackendRef. Its minimum value is 0 (indicating 0% of +requests) and its maximum value is 100 (indicating 100% of requests). + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestMirror.backendRef +Description:: ++ +-- +BackendRef references a resource where mirrored requests are sent. + +Mirrored requests must be sent only to a single destination endpoint +within this BackendRef, irrespective of how many endpoints are present +within this BackendRef. + +If the referent cannot be found, this BackendRef is invalid and must be +dropped from the Gateway. The controller must ensure the "ResolvedRefs" +condition on the Route status is set to `status: False` and not configure +this backend in the underlying implementation. + +If there is a cross-namespace reference to an *existing* object +that is not allowed by a ReferenceGrant, the controller must ensure the +"ResolvedRefs" condition on the Route is set to `status: False`, +with the "RefNotPermitted" reason and not configure this backend in the +underlying implementation. + +In either error case, the Message of the `ResolvedRefs` Condition +should be used to provide more detail about the problem. + +Support: Extended for Kubernetes Service + +Support: Implementation-specific for any other resource +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is the Kubernetes resource kind of the referent. For example +"Service". + +Defaults to "Service" when not specified. + +ExternalName services can refer to CNAME DNS records that may live +outside of the cluster and as such are difficult to reason about in +terms of conformance. They also may not be safe to forward to (see +CVE-2021-25740 for more information). Implementations SHOULD NOT +support ExternalName Services. + +Support: Core (Services with a type other than ExternalName) + +Support: Implementation-specific (Services with type ExternalName) + +| `name` +| `string` +| Name is the name of the referent. + +| `namespace` +| `string` +| Namespace is the namespace of the backend. When unspecified, the local +namespace is inferred. + +Note that when a namespace different than the local namespace is specified, +a ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. + +Support: Core + +| `port` +| `integer` +| Port specifies the destination port number to use for this resource. +Port is required when the referent is a Kubernetes Service. In this +case, the port number is the service port number, not the target port. +For other resources, destination port might be derived from the referent +resource or this field. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestMirror.fraction +Description:: ++ +-- +Fraction represents the fraction of requests that should be +mirrored to BackendRef. + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. +-- + +Type:: + `object` + +Required:: + - `numerator` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `denominator` +| `integer` +| + +| `numerator` +| `integer` +| + +|=== +=== .spec.rules[].backendRefs[].filters[].responseHeaderModifier +Description:: ++ +-- +ResponseHeaderModifier defines a schema for a filter that modifies response +headers. + +Support: Extended +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `add` +| `array` +| Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz + +| `add[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +| `remove` +| `array (string)` +| Remove the given header(s) from the HTTP request before the action. The +value of Remove is a list of HTTP header names. Note that the header +names are case-insensitive (see +https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). + +Input: + GET /foo HTTP/1.1 + my-header1: foo + my-header2: bar + my-header3: baz + +Config: + remove: ["my-header1", "my-header3"] + +Output: + GET /foo HTTP/1.1 + my-header2: bar + +| `set` +| `array` +| Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar + +| `set[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +|=== +=== .spec.rules[].backendRefs[].filters[].responseHeaderModifier.add +Description:: ++ +-- +Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[].filters[].responseHeaderModifier.add[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].backendRefs[].filters[].responseHeaderModifier.set +Description:: ++ +-- +Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[].filters[].responseHeaderModifier.set[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].filters +Description:: ++ +-- +Filters define the filters that are applied to requests that match +this rule. + +The effects of ordering of multiple behaviors are currently unspecified. +This can change in the future based on feedback during the alpha stage. + +Conformance-levels at this level are defined based on the type of filter: + +- ALL core filters MUST be supported by all implementations that support + GRPCRoute. +- Implementers are encouraged to support extended filters. +- Implementation-specific custom filters have no API guarantees across + implementations. + +Specifying the same filter multiple times is not supported unless explicitly +indicated in the filter. + +If an implementation cannot support a combination of filters, it must clearly +document that limitation. In cases where incompatible or unsupported +filters are specified and cause the `Accepted` condition to be set to status +`False`, implementations may use the `IncompatibleFilters` reason to specify +this configuration error. + +Support: Core +-- + +Type:: + `array` + + + + +=== .spec.rules[].filters[] +Description:: ++ +-- +GRPCRouteFilter defines processing steps that must be completed during the +request or response lifecycle. GRPCRouteFilters are meant as an extension +point to express processing that may be done in Gateway implementations. Some +examples include request or response modification, implementing +authentication strategies, rate-limiting, and traffic shaping. API +guarantee/conformance is defined based on the type of the filter. +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `extensionRef` +| `object` +| ExtensionRef is an optional, implementation-specific extension to the +"filter" behavior. For example, resource "myroutefilter" in group +"networking.example.net"). ExtensionRef MUST NOT be used for core and +extended filters. + +Support: Implementation-specific + +This filter can be used multiple times within the same rule. + +| `requestHeaderModifier` +| `object` +| RequestHeaderModifier defines a schema for a filter that modifies request +headers. + +Support: Core + +| `requestMirror` +| `object` +| RequestMirror defines a schema for a filter that mirrors requests. +Requests are sent to the specified destination, but responses from +that destination are ignored. + +This filter can be used multiple times within the same rule. Note that +not all implementations will be able to support mirroring to multiple +backends. + +Support: Extended + +| `responseHeaderModifier` +| `object` +| ResponseHeaderModifier defines a schema for a filter that modifies response +headers. + +Support: Extended + +| `type` +| `string` +| Type identifies the type of filter to apply. As with other API fields, +types are classified into three conformance levels: + +- Core: Filter types and their corresponding configuration defined by + "Support: Core" in this package, e.g. "RequestHeaderModifier". All + implementations supporting GRPCRoute MUST support core filters. + +- Extended: Filter types and their corresponding configuration defined by + "Support: Extended" in this package, e.g. "RequestMirror". Implementers + are encouraged to support extended filters. + +- Implementation-specific: Filters that are defined and supported by specific vendors. + In the future, filters showing convergence in behavior across multiple + implementations will be considered for inclusion in extended or core + conformance levels. Filter-specific configuration for such filters + is specified using the ExtensionRef field. `Type` MUST be set to + "ExtensionRef" for custom filters. + +Implementers are encouraged to define custom implementation types to +extend the core API with implementation-specific behavior. + +If a reference to a custom filter type cannot be resolved, the filter +MUST NOT be skipped. Instead, requests that would have been processed by +that filter MUST receive a HTTP error response. + +|=== +=== .spec.rules[].filters[].extensionRef +Description:: ++ +-- +ExtensionRef is an optional, implementation-specific extension to the +"filter" behavior. For example, resource "myroutefilter" in group +"networking.example.net"). ExtensionRef MUST NOT be used for core and +extended filters. + +Support: Implementation-specific + +This filter can be used multiple times within the same rule. +-- + +Type:: + `object` + +Required:: + - `group` + - `kind` + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is kind of the referent. For example "HTTPRoute" or "Service". + +| `name` +| `string` +| Name is the name of the referent. + +|=== +=== .spec.rules[].filters[].requestHeaderModifier +Description:: ++ +-- +RequestHeaderModifier defines a schema for a filter that modifies request +headers. + +Support: Core +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `add` +| `array` +| Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz + +| `add[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +| `remove` +| `array (string)` +| Remove the given header(s) from the HTTP request before the action. The +value of Remove is a list of HTTP header names. Note that the header +names are case-insensitive (see +https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). + +Input: + GET /foo HTTP/1.1 + my-header1: foo + my-header2: bar + my-header3: baz + +Config: + remove: ["my-header1", "my-header3"] + +Output: + GET /foo HTTP/1.1 + my-header2: bar + +| `set` +| `array` +| Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar + +| `set[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +|=== +=== .spec.rules[].filters[].requestHeaderModifier.add +Description:: ++ +-- +Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz +-- + +Type:: + `array` + + + + +=== .spec.rules[].filters[].requestHeaderModifier.add[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].filters[].requestHeaderModifier.set +Description:: ++ +-- +Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar +-- + +Type:: + `array` + + + + +=== .spec.rules[].filters[].requestHeaderModifier.set[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].filters[].requestMirror +Description:: ++ +-- +RequestMirror defines a schema for a filter that mirrors requests. +Requests are sent to the specified destination, but responses from +that destination are ignored. + +This filter can be used multiple times within the same rule. Note that +not all implementations will be able to support mirroring to multiple +backends. + +Support: Extended +-- + +Type:: + `object` + +Required:: + - `backendRef` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `backendRef` +| `object` +| BackendRef references a resource where mirrored requests are sent. + +Mirrored requests must be sent only to a single destination endpoint +within this BackendRef, irrespective of how many endpoints are present +within this BackendRef. + +If the referent cannot be found, this BackendRef is invalid and must be +dropped from the Gateway. The controller must ensure the "ResolvedRefs" +condition on the Route status is set to `status: False` and not configure +this backend in the underlying implementation. + +If there is a cross-namespace reference to an *existing* object +that is not allowed by a ReferenceGrant, the controller must ensure the +"ResolvedRefs" condition on the Route is set to `status: False`, +with the "RefNotPermitted" reason and not configure this backend in the +underlying implementation. + +In either error case, the Message of the `ResolvedRefs` Condition +should be used to provide more detail about the problem. + +Support: Extended for Kubernetes Service + +Support: Implementation-specific for any other resource + +| `fraction` +| `object` +| Fraction represents the fraction of requests that should be +mirrored to BackendRef. + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. + +| `percent` +| `integer` +| Percent represents the percentage of requests that should be +mirrored to BackendRef. Its minimum value is 0 (indicating 0% of +requests) and its maximum value is 100 (indicating 100% of requests). + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. + +|=== +=== .spec.rules[].filters[].requestMirror.backendRef +Description:: ++ +-- +BackendRef references a resource where mirrored requests are sent. + +Mirrored requests must be sent only to a single destination endpoint +within this BackendRef, irrespective of how many endpoints are present +within this BackendRef. + +If the referent cannot be found, this BackendRef is invalid and must be +dropped from the Gateway. The controller must ensure the "ResolvedRefs" +condition on the Route status is set to `status: False` and not configure +this backend in the underlying implementation. + +If there is a cross-namespace reference to an *existing* object +that is not allowed by a ReferenceGrant, the controller must ensure the +"ResolvedRefs" condition on the Route is set to `status: False`, +with the "RefNotPermitted" reason and not configure this backend in the +underlying implementation. + +In either error case, the Message of the `ResolvedRefs` Condition +should be used to provide more detail about the problem. + +Support: Extended for Kubernetes Service + +Support: Implementation-specific for any other resource +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is the Kubernetes resource kind of the referent. For example +"Service". + +Defaults to "Service" when not specified. + +ExternalName services can refer to CNAME DNS records that may live +outside of the cluster and as such are difficult to reason about in +terms of conformance. They also may not be safe to forward to (see +CVE-2021-25740 for more information). Implementations SHOULD NOT +support ExternalName Services. + +Support: Core (Services with a type other than ExternalName) + +Support: Implementation-specific (Services with type ExternalName) + +| `name` +| `string` +| Name is the name of the referent. + +| `namespace` +| `string` +| Namespace is the namespace of the backend. When unspecified, the local +namespace is inferred. + +Note that when a namespace different than the local namespace is specified, +a ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. + +Support: Core + +| `port` +| `integer` +| Port specifies the destination port number to use for this resource. +Port is required when the referent is a Kubernetes Service. In this +case, the port number is the service port number, not the target port. +For other resources, destination port might be derived from the referent +resource or this field. + +|=== +=== .spec.rules[].filters[].requestMirror.fraction +Description:: ++ +-- +Fraction represents the fraction of requests that should be +mirrored to BackendRef. + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. +-- + +Type:: + `object` + +Required:: + - `numerator` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `denominator` +| `integer` +| + +| `numerator` +| `integer` +| + +|=== +=== .spec.rules[].filters[].responseHeaderModifier +Description:: ++ +-- +ResponseHeaderModifier defines a schema for a filter that modifies response +headers. + +Support: Extended +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `add` +| `array` +| Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz + +| `add[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +| `remove` +| `array (string)` +| Remove the given header(s) from the HTTP request before the action. The +value of Remove is a list of HTTP header names. Note that the header +names are case-insensitive (see +https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). + +Input: + GET /foo HTTP/1.1 + my-header1: foo + my-header2: bar + my-header3: baz + +Config: + remove: ["my-header1", "my-header3"] + +Output: + GET /foo HTTP/1.1 + my-header2: bar + +| `set` +| `array` +| Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar + +| `set[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +|=== +=== .spec.rules[].filters[].responseHeaderModifier.add +Description:: ++ +-- +Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz +-- + +Type:: + `array` + + + + +=== .spec.rules[].filters[].responseHeaderModifier.add[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].filters[].responseHeaderModifier.set +Description:: ++ +-- +Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar +-- + +Type:: + `array` + + + + +=== .spec.rules[].filters[].responseHeaderModifier.set[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].matches +Description:: ++ +-- +Matches define conditions used for matching the rule against incoming +gRPC requests. Each match is independent, i.e. this rule will be matched +if **any** one of the matches is satisfied. + +For example, take the following matches configuration: + + +matches: +- method: + service: foo.bar + headers: + values: + version: 2 +- method: + service: foo.bar.v2 + + +For a request to match against this rule, it MUST satisfy +EITHER of the two conditions: + +- service of foo.bar AND contains the header `version: 2` +- service of foo.bar.v2 + +See the documentation for GRPCRouteMatch on how to specify multiple +match conditions to be ANDed together. + +If no matches are specified, the implementation MUST match every gRPC request. + +Proxy or Load Balancer routing configuration generated from GRPCRoutes +MUST prioritize rules based on the following criteria, continuing on +ties. Merging MUST not be done between GRPCRoutes and HTTPRoutes. +Precedence MUST be given to the rule with the largest number of: + +* Characters in a matching non-wildcard hostname. +* Characters in a matching hostname. +* Characters in a matching service. +* Characters in a matching method. +* Header matches. + +If ties still exist across multiple Routes, matching precedence MUST be +determined in order of the following criteria, continuing on ties: + +* The oldest Route based on creation timestamp. +* The Route appearing first in alphabetical order by + "{namespace}/{name}". + +If ties still exist within the Route that has been given precedence, +matching precedence MUST be granted to the first matching rule meeting +the above criteria. +-- + +Type:: + `array` + + + + +=== .spec.rules[].matches[] +Description:: ++ +-- +GRPCRouteMatch defines the predicate used to match requests to a given +action. Multiple match types are ANDed together, i.e. the match will +evaluate to true only if all conditions are satisfied. + +For example, the match below will match a gRPC request only if its service +is `foo` AND it contains the `version: v1` header: + + +matches: + - method: + type: Exact + service: "foo" + headers: + - name: "version" + value "v1" + + +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `headers` +| `array` +| Headers specifies gRPC request header matchers. Multiple match values are +ANDed together, meaning, a request MUST match all the specified headers +to select the route. + +| `headers[]` +| `object` +| GRPCHeaderMatch describes how to select a gRPC route by matching gRPC request +headers. + +| `method` +| `object` +| Method specifies a gRPC request service/method matcher. If this field is +not specified, all services and methods will match. + +|=== +=== .spec.rules[].matches[].headers +Description:: ++ +-- +Headers specifies gRPC request header matchers. Multiple match values are +ANDed together, meaning, a request MUST match all the specified headers +to select the route. +-- + +Type:: + `array` + + + + +=== .spec.rules[].matches[].headers[] +Description:: ++ +-- +GRPCHeaderMatch describes how to select a gRPC route by matching gRPC request +headers. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the gRPC Header to be matched. + +If multiple entries specify equivalent header names, only the first +entry with an equivalent name MUST be considered for a match. Subsequent +entries with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `type` +| `string` +| Type specifies how to match against the value of the header. + +| `value` +| `string` +| Value is the value of the gRPC Header to be matched. + +|=== +=== .spec.rules[].matches[].method +Description:: ++ +-- +Method specifies a gRPC request service/method matcher. If this field is +not specified, all services and methods will match. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `method` +| `string` +| Value of the method to match against. If left empty or omitted, will +match all services. + +At least one of Service and Method MUST be a non-empty string. + +| `service` +| `string` +| Value of the service to match against. If left empty or omitted, will +match any service. + +At least one of Service and Method MUST be a non-empty string. + +| `type` +| `string` +| Type specifies how to match against the service and/or method. +Support: Core (Exact with service and method specified) + +Support: Implementation-specific (Exact with method specified but no service specified) + +Support: Implementation-specific (RegularExpression) + +|=== +=== .status +Description:: ++ +-- +Status defines the current state of GRPCRoute. +-- + +Type:: + `object` + +Required:: + - `parents` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `parents` +| `array` +| Parents is a list of parent resources (usually Gateways) that are +associated with the route, and the status of the route with respect to +each parent. When this route attaches to a parent, the controller that +manages the parent must add an entry to this list when the controller +first sees the route and should update the entry as appropriate when the +route or gateway is modified. + +Note that parent references that cannot be resolved by an implementation +of this API will not be added to this list. Implementations of this API +can only populate Route status for the Gateways/parent resources they are +responsible for. + +A maximum of 32 Gateways will be represented in this list. An empty list +means the route has not been attached to any Gateway. + +| `parents[]` +| `object` +| RouteParentStatus describes the status of a route with respect to an +associated Parent. + +|=== +=== .status.parents +Description:: ++ +-- +Parents is a list of parent resources (usually Gateways) that are +associated with the route, and the status of the route with respect to +each parent. When this route attaches to a parent, the controller that +manages the parent must add an entry to this list when the controller +first sees the route and should update the entry as appropriate when the +route or gateway is modified. + +Note that parent references that cannot be resolved by an implementation +of this API will not be added to this list. Implementations of this API +can only populate Route status for the Gateways/parent resources they are +responsible for. + +A maximum of 32 Gateways will be represented in this list. An empty list +means the route has not been attached to any Gateway. +-- + +Type:: + `array` + + + + +=== .status.parents[] +Description:: ++ +-- +RouteParentStatus describes the status of a route with respect to an +associated Parent. +-- + +Type:: + `object` + +Required:: + - `controllerName` + - `parentRef` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| Conditions describes the status of the route with respect to the Gateway. +Note that the route's availability is also subject to the Gateway's own +status conditions and listener status. + +If the Route's ParentRef specifies an existing Gateway that supports +Routes of this kind AND that Gateway's controller has sufficient access, +then that Gateway's controller MUST set the "Accepted" condition on the +Route, to indicate whether the route has been accepted or rejected by the +Gateway, and why. + +A Route MUST be considered "Accepted" if at least one of the Route's +rules is implemented by the Gateway. + +There are a number of cases where the "Accepted" condition may not be set +due to lack of controller visibility, that includes when: + +* The Route refers to a nonexistent parent. +* The Route is of a type that the controller does not support. +* The Route is in a namespace the controller does not have access to. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `controllerName` +| `string` +| ControllerName is a domain/path string that indicates the name of the +controller that wrote this status. This corresponds with the +controllerName field on GatewayClass. + +Example: "example.net/gateway-controller". + +The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are +valid Kubernetes names +(https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). + +Controllers MUST populate this field when writing status. Controllers should ensure that +entries to status populated with their ControllerName are cleaned up when they are no +longer necessary. + +| `parentRef` +| `object` +| ParentRef corresponds with a ParentRef in the spec that this +RouteParentStatus struct describes the status of. + +|=== +=== .status.parents[].conditions +Description:: ++ +-- +Conditions describes the status of the route with respect to the Gateway. +Note that the route's availability is also subject to the Gateway's own +status conditions and listener status. + +If the Route's ParentRef specifies an existing Gateway that supports +Routes of this kind AND that Gateway's controller has sufficient access, +then that Gateway's controller MUST set the "Accepted" condition on the +Route, to indicate whether the route has been accepted or rejected by the +Gateway, and why. + +A Route MUST be considered "Accepted" if at least one of the Route's +rules is implemented by the Gateway. + +There are a number of cases where the "Accepted" condition may not be set +due to lack of controller visibility, that includes when: + +* The Route refers to a nonexistent parent. +* The Route is of a type that the controller does not support. +* The Route is in a namespace the controller does not have access to. +-- + +Type:: + `array` + + + + +=== .status.parents[].conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== +=== .status.parents[].parentRef +Description:: ++ +-- +ParentRef corresponds with a ParentRef in the spec that this +RouteParentStatus struct describes the status of. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. +When unspecified, "gateway.networking.k8s.io" is inferred. +To set the core API group (such as for a "Service" kind referent), +Group must be explicitly set to "" (empty string). + +Support: Core + +| `kind` +| `string` +| Kind is kind of the referent. + +There are two kinds of parent resources with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +Support for other resources is Implementation-Specific. + +| `name` +| `string` +| Name is the name of the referent. + +Support: Core + +| `namespace` +| `string` +| Namespace is the namespace of the referent. When unspecified, this refers +to the local namespace of the Route. + +Note that there are specific rules for ParentRefs which cross namespace +boundaries. Cross-namespace references are only valid if they are explicitly +allowed by something in the namespace they are referring to. For example: +Gateway has the AllowedRoutes field, and ReferenceGrant provides a +generic way to enable any other kind of cross-namespace reference. + +Support: Core + +| `port` +| `integer` +| Port is the network port this Route targets. It can be interpreted +differently based on the type of parent resource. + +When the parent resource is a Gateway, this targets all listeners +listening on the specified port that also support this kind of Route(and +select this Route). It's not recommended to set `Port` unless the +networking behaviors specified in a Route must apply to a specific port +as opposed to a listener(s) whose port(s) may be changed. When both Port +and SectionName are specified, the name and port of the selected listener +must match both specified values. + +Implementations MAY choose to support other parent resources. +Implementations supporting other types of parent resources MUST clearly +document how/if Port is interpreted. + +For the purpose of status, an attachment is considered successful as +long as the parent resource accepts it partially. For example, Gateway +listeners can restrict which Routes can attach to them by Route kind, +namespace, or hostname. If 1 of 2 Gateway listeners accept attachment +from the referencing Route, the Route MUST be considered successfully +attached. If no Gateway listeners accept attachment from this Route, +the Route MUST be considered detached from the Gateway. + +Support: Extended + +| `sectionName` +| `string` +| SectionName is the name of a section within the target resource. In the +following resources, SectionName is interpreted as the following: + +* Gateway: Listener name. When both Port (experimental) and SectionName +are specified, the name and port of the selected listener must match +both specified values. +* Service: Port name. When both Port (experimental) and SectionName +are specified, the name and port of the selected listener must match +both specified values. + +Implementations MAY choose to support attaching Routes to other resources. +If that is the case, they MUST clearly document how SectionName is +interpreted. + +When unspecified (empty string), this will reference the entire resource. +For the purpose of status, an attachment is considered successful if at +least one section in the parent resource accepts it. For example, Gateway +listeners can restrict which Routes can attach to them by Route kind, +namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from +the referencing Route, the Route MUST be considered successfully +attached. If no Gateway listeners accept attachment from this Route, the +Route MUST be considered detached from the Gateway. + +Support: Core + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/gateway.networking.k8s.io/v1/grpcroutes` +- `GET`: list objects of kind GRPCRoute +* `/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/grpcroutes` +- `DELETE`: delete collection of GRPCRoute +- `GET`: list objects of kind GRPCRoute +- `POST`: create a GRPCRoute +* `/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/grpcroutes/{name}` +- `DELETE`: delete a GRPCRoute +- `GET`: read the specified GRPCRoute +- `PATCH`: partially update the specified GRPCRoute +- `PUT`: replace the specified GRPCRoute +* `/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/grpcroutes/{name}/status` +- `GET`: read status of the specified GRPCRoute +- `PATCH`: partially update status of the specified GRPCRoute +- `PUT`: replace status of the specified GRPCRoute + + +=== /apis/gateway.networking.k8s.io/v1/grpcroutes + + + +HTTP method:: + `GET` + +Description:: + list objects of kind GRPCRoute + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-networking-gateway-v1-GRPCRouteList[`GRPCRouteList`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/grpcroutes + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of GRPCRoute + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind GRPCRoute + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-networking-gateway-v1-GRPCRouteList[`GRPCRouteList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a GRPCRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 201 - Created +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 202 - Accepted +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/grpcroutes/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the GRPCRoute +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a GRPCRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified GRPCRoute + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified GRPCRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified GRPCRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 201 - Created +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/grpcroutes/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the GRPCRoute +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified GRPCRoute + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified GRPCRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified GRPCRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 201 - Created +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`GRPCRoute`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/network_apis/httproute-gateway-networking-k8s-io-v1.adoc b/rest_api/network_apis/httproute-gateway-networking-k8s-io-v1.adoc new file mode 100644 index 0000000000..4c1c08b807 --- /dev/null +++ b/rest_api/network_apis/httproute-gateway-networking-k8s-io-v1.adoc @@ -0,0 +1,3928 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="httproute-gateway-networking-k8s-io-v1"] += HTTPRoute [gateway.networking.k8s.io/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +HTTPRoute provides a way to route HTTP requests. This includes the capability +to match requests by hostname, path, header, or query param. Filters can be +used to specify additional processing steps. Backends specify where matching +requests should be routed. +-- + +Type:: + `object` + +Required:: + - `spec` + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| Spec defines the desired state of HTTPRoute. + +| `status` +| `object` +| Status defines the current state of HTTPRoute. + +|=== +=== .spec +Description:: ++ +-- +Spec defines the desired state of HTTPRoute. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `hostnames` +| `array (string)` +| Hostnames defines a set of hostnames that should match against the HTTP Host +header to select a HTTPRoute used to process the request. Implementations +MUST ignore any port value specified in the HTTP Host header while +performing a match and (absent of any applicable header modification +configuration) MUST forward this header unmodified to the backend. + +Valid values for Hostnames are determined by RFC 1123 definition of a +hostname with 2 notable exceptions: + +1. IPs are not allowed. +2. A hostname may be prefixed with a wildcard label (`*.`). The wildcard + label must appear by itself as the first label. + +If a hostname is specified by both the Listener and HTTPRoute, there +must be at least one intersecting hostname for the HTTPRoute to be +attached to the Listener. For example: + +* A Listener with `test.example.com` as the hostname matches HTTPRoutes + that have either not specified any hostnames, or have specified at + least one of `test.example.com` or `*.example.com`. +* A Listener with `*.example.com` as the hostname matches HTTPRoutes + that have either not specified any hostnames or have specified at least + one hostname that matches the Listener hostname. For example, + `*.example.com`, `test.example.com`, and `foo.test.example.com` would + all match. On the other hand, `example.com` and `test.example.net` would + not match. + +Hostnames that are prefixed with a wildcard label (`*.`) are interpreted +as a suffix match. That means that a match for `*.example.com` would match +both `test.example.com`, and `foo.test.example.com`, but not `example.com`. + +If both the Listener and HTTPRoute have specified hostnames, any +HTTPRoute hostnames that do not match the Listener hostname MUST be +ignored. For example, if a Listener specified `*.example.com`, and the +HTTPRoute specified `test.example.com` and `test.example.net`, +`test.example.net` must not be considered for a match. + +If both the Listener and HTTPRoute have specified hostnames, and none +match with the criteria above, then the HTTPRoute is not accepted. The +implementation must raise an 'Accepted' Condition with a status of +`False` in the corresponding RouteParentStatus. + +In the event that multiple HTTPRoutes specify intersecting hostnames (e.g. +overlapping wildcard matching and exact matching hostnames), precedence must +be given to rules from the HTTPRoute with the largest number of: + +* Characters in a matching non-wildcard hostname. +* Characters in a matching hostname. + +If ties exist across multiple Routes, the matching precedence rules for +HTTPRouteMatches takes over. + +Support: Core + +| `parentRefs` +| `array` +| ParentRefs references the resources (usually Gateways) that a Route wants +to be attached to. Note that the referenced parent resource needs to +allow this for the attachment to be complete. For Gateways, that means +the Gateway needs to allow attachment from Routes of this kind and +namespace. For Services, that means the Service must either be in the same +namespace for a "producer" route, or the mesh implementation must support +and allow "consumer" routes for the referenced Service. ReferenceGrant is +not applicable for governing ParentRefs to Services - it is not possible to +create a "producer" route for a Service in a different namespace from the +Route. + +There are two kinds of parent resources with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +This API may be extended in the future to support additional kinds of parent +resources. + +ParentRefs must be _distinct_. This means either that: + +* They select different objects. If this is the case, then parentRef + entries are distinct. In terms of fields, this means that the + multi-part key defined by `group`, `kind`, `namespace`, and `name` must + be unique across all parentRef entries in the Route. +* They do not select different objects, but for each optional field used, + each ParentRef that selects the same object must set the same set of + optional fields to different values. If one ParentRef sets a + combination of optional fields, all must set the same combination. + +Some examples: + +* If one ParentRef sets `sectionName`, all ParentRefs referencing the + same object must also set `sectionName`. +* If one ParentRef sets `port`, all ParentRefs referencing the same + object must also set `port`. +* If one ParentRef sets `sectionName` and `port`, all ParentRefs + referencing the same object must also set `sectionName` and `port`. + +It is possible to separately reference multiple distinct objects that may +be collapsed by an implementation. For example, some implementations may +choose to merge compatible Gateway Listeners together. If that is the +case, the list of routes attached to those resources should also be +merged. + +Note that for ParentRefs that cross namespace boundaries, there are specific +rules. Cross-namespace references are only valid if they are explicitly +allowed by something in the namespace they are referring to. For example, +Gateway has the AllowedRoutes field, and ReferenceGrant provides a +generic way to enable other kinds of cross-namespace reference. + +| `parentRefs[]` +| `object` +| ParentReference identifies an API object (usually a Gateway) that can be considered +a parent of this resource (usually a route). There are two kinds of parent resources +with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +This API may be extended in the future to support additional kinds of parent +resources. + +The API object must be valid in the cluster; the Group and Kind must +be registered in the cluster for this reference to be valid. + +| `rules` +| `array` +| Rules are a list of HTTP matchers, filters and actions. + +| `rules[]` +| `object` +| HTTPRouteRule defines semantics for matching an HTTP request based on +conditions (matches), processing it (filters), and forwarding the request to +an API object (backendRefs). + +|=== +=== .spec.parentRefs +Description:: ++ +-- +ParentRefs references the resources (usually Gateways) that a Route wants +to be attached to. Note that the referenced parent resource needs to +allow this for the attachment to be complete. For Gateways, that means +the Gateway needs to allow attachment from Routes of this kind and +namespace. For Services, that means the Service must either be in the same +namespace for a "producer" route, or the mesh implementation must support +and allow "consumer" routes for the referenced Service. ReferenceGrant is +not applicable for governing ParentRefs to Services - it is not possible to +create a "producer" route for a Service in a different namespace from the +Route. + +There are two kinds of parent resources with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +This API may be extended in the future to support additional kinds of parent +resources. + +ParentRefs must be _distinct_. This means either that: + +* They select different objects. If this is the case, then parentRef + entries are distinct. In terms of fields, this means that the + multi-part key defined by `group`, `kind`, `namespace`, and `name` must + be unique across all parentRef entries in the Route. +* They do not select different objects, but for each optional field used, + each ParentRef that selects the same object must set the same set of + optional fields to different values. If one ParentRef sets a + combination of optional fields, all must set the same combination. + +Some examples: + +* If one ParentRef sets `sectionName`, all ParentRefs referencing the + same object must also set `sectionName`. +* If one ParentRef sets `port`, all ParentRefs referencing the same + object must also set `port`. +* If one ParentRef sets `sectionName` and `port`, all ParentRefs + referencing the same object must also set `sectionName` and `port`. + +It is possible to separately reference multiple distinct objects that may +be collapsed by an implementation. For example, some implementations may +choose to merge compatible Gateway Listeners together. If that is the +case, the list of routes attached to those resources should also be +merged. + +Note that for ParentRefs that cross namespace boundaries, there are specific +rules. Cross-namespace references are only valid if they are explicitly +allowed by something in the namespace they are referring to. For example, +Gateway has the AllowedRoutes field, and ReferenceGrant provides a +generic way to enable other kinds of cross-namespace reference. +-- + +Type:: + `array` + + + + +=== .spec.parentRefs[] +Description:: ++ +-- +ParentReference identifies an API object (usually a Gateway) that can be considered +a parent of this resource (usually a route). There are two kinds of parent resources +with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +This API may be extended in the future to support additional kinds of parent +resources. + +The API object must be valid in the cluster; the Group and Kind must +be registered in the cluster for this reference to be valid. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. +When unspecified, "gateway.networking.k8s.io" is inferred. +To set the core API group (such as for a "Service" kind referent), +Group must be explicitly set to "" (empty string). + +Support: Core + +| `kind` +| `string` +| Kind is kind of the referent. + +There are two kinds of parent resources with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +Support for other resources is Implementation-Specific. + +| `name` +| `string` +| Name is the name of the referent. + +Support: Core + +| `namespace` +| `string` +| Namespace is the namespace of the referent. When unspecified, this refers +to the local namespace of the Route. + +Note that there are specific rules for ParentRefs which cross namespace +boundaries. Cross-namespace references are only valid if they are explicitly +allowed by something in the namespace they are referring to. For example: +Gateway has the AllowedRoutes field, and ReferenceGrant provides a +generic way to enable any other kind of cross-namespace reference. + +Support: Core + +| `port` +| `integer` +| Port is the network port this Route targets. It can be interpreted +differently based on the type of parent resource. + +When the parent resource is a Gateway, this targets all listeners +listening on the specified port that also support this kind of Route(and +select this Route). It's not recommended to set `Port` unless the +networking behaviors specified in a Route must apply to a specific port +as opposed to a listener(s) whose port(s) may be changed. When both Port +and SectionName are specified, the name and port of the selected listener +must match both specified values. + +Implementations MAY choose to support other parent resources. +Implementations supporting other types of parent resources MUST clearly +document how/if Port is interpreted. + +For the purpose of status, an attachment is considered successful as +long as the parent resource accepts it partially. For example, Gateway +listeners can restrict which Routes can attach to them by Route kind, +namespace, or hostname. If 1 of 2 Gateway listeners accept attachment +from the referencing Route, the Route MUST be considered successfully +attached. If no Gateway listeners accept attachment from this Route, +the Route MUST be considered detached from the Gateway. + +Support: Extended + +| `sectionName` +| `string` +| SectionName is the name of a section within the target resource. In the +following resources, SectionName is interpreted as the following: + +* Gateway: Listener name. When both Port (experimental) and SectionName +are specified, the name and port of the selected listener must match +both specified values. +* Service: Port name. When both Port (experimental) and SectionName +are specified, the name and port of the selected listener must match +both specified values. + +Implementations MAY choose to support attaching Routes to other resources. +If that is the case, they MUST clearly document how SectionName is +interpreted. + +When unspecified (empty string), this will reference the entire resource. +For the purpose of status, an attachment is considered successful if at +least one section in the parent resource accepts it. For example, Gateway +listeners can restrict which Routes can attach to them by Route kind, +namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from +the referencing Route, the Route MUST be considered successfully +attached. If no Gateway listeners accept attachment from this Route, the +Route MUST be considered detached from the Gateway. + +Support: Core + +|=== +=== .spec.rules +Description:: ++ +-- +Rules are a list of HTTP matchers, filters and actions. +-- + +Type:: + `array` + + + + +=== .spec.rules[] +Description:: ++ +-- +HTTPRouteRule defines semantics for matching an HTTP request based on +conditions (matches), processing it (filters), and forwarding the request to +an API object (backendRefs). +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `backendRefs` +| `array` +| BackendRefs defines the backend(s) where matching requests should be +sent. + +Failure behavior here depends on how many BackendRefs are specified and +how many are invalid. + +If *all* entries in BackendRefs are invalid, and there are also no filters +specified in this route rule, *all* traffic which matches this rule MUST +receive a 500 status code. + +See the HTTPBackendRef definition for the rules about what makes a single +HTTPBackendRef invalid. + +When a HTTPBackendRef is invalid, 500 status codes MUST be returned for +requests that would have otherwise been routed to an invalid backend. If +multiple backends are specified, and some are invalid, the proportion of +requests that would otherwise have been routed to an invalid backend +MUST receive a 500 status code. + +For example, if two backends are specified with equal weights, and one is +invalid, 50 percent of traffic must receive a 500. Implementations may +choose how that 50 percent is determined. + +When a HTTPBackendRef refers to a Service that has no ready endpoints, +implementations SHOULD return a 503 for requests to that backend instead. +If an implementation chooses to do this, all of the above rules for 500 responses +MUST also apply for responses that return a 503. + +Support: Core for Kubernetes Service + +Support: Extended for Kubernetes ServiceImport + +Support: Implementation-specific for any other resource + +Support for weight: Core + +| `backendRefs[]` +| `object` +| HTTPBackendRef defines how a HTTPRoute forwards a HTTP request. + +Note that when a namespace different than the local namespace is specified, a +ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. + +| `filters` +| `array` +| Filters define the filters that are applied to requests that match +this rule. + +Wherever possible, implementations SHOULD implement filters in the order +they are specified. + +Implementations MAY choose to implement this ordering strictly, rejecting +any combination or order of filters that cannot be supported. If implementations +choose a strict interpretation of filter ordering, they MUST clearly document +that behavior. + +To reject an invalid combination or order of filters, implementations SHOULD +consider the Route Rules with this configuration invalid. If all Route Rules +in a Route are invalid, the entire Route would be considered invalid. If only +a portion of Route Rules are invalid, implementations MUST set the +"PartiallyInvalid" condition for the Route. + +Conformance-levels at this level are defined based on the type of filter: + +- ALL core filters MUST be supported by all implementations. +- Implementers are encouraged to support extended filters. +- Implementation-specific custom filters have no API guarantees across + implementations. + +Specifying the same filter multiple times is not supported unless explicitly +indicated in the filter. + +All filters are expected to be compatible with each other except for the +URLRewrite and RequestRedirect filters, which may not be combined. If an +implementation cannot support other combinations of filters, they must clearly +document that limitation. In cases where incompatible or unsupported +filters are specified and cause the `Accepted` condition to be set to status +`False`, implementations may use the `IncompatibleFilters` reason to specify +this configuration error. + +Support: Core + +| `filters[]` +| `object` +| HTTPRouteFilter defines processing steps that must be completed during the +request or response lifecycle. HTTPRouteFilters are meant as an extension +point to express processing that may be done in Gateway implementations. Some +examples include request or response modification, implementing +authentication strategies, rate-limiting, and traffic shaping. API +guarantee/conformance is defined based on the type of the filter. + +| `matches` +| `array` +| Matches define conditions used for matching the rule against incoming +HTTP requests. Each match is independent, i.e. this rule will be matched +if **any** one of the matches is satisfied. + +For example, take the following matches configuration: + + +matches: +- path: + value: "/foo" + headers: + - name: "version" + value: "v2" +- path: + value: "/v2/foo" + + +For a request to match against this rule, a request must satisfy +EITHER of the two conditions: + +- path prefixed with `/foo` AND contains the header `version: v2` +- path prefix of `/v2/foo` + +See the documentation for HTTPRouteMatch on how to specify multiple +match conditions that should be ANDed together. + +If no matches are specified, the default is a prefix +path match on "/", which has the effect of matching every +HTTP request. + +Proxy or Load Balancer routing configuration generated from HTTPRoutes +MUST prioritize matches based on the following criteria, continuing on +ties. Across all rules specified on applicable Routes, precedence must be +given to the match having: + +* "Exact" path match. +* "Prefix" path match with largest number of characters. +* Method match. +* Largest number of header matches. +* Largest number of query param matches. + +Note: The precedence of RegularExpression path matches are implementation-specific. + +If ties still exist across multiple Routes, matching precedence MUST be +determined in order of the following criteria, continuing on ties: + +* The oldest Route based on creation timestamp. +* The Route appearing first in alphabetical order by + "{namespace}/{name}". + +If ties still exist within an HTTPRoute, matching precedence MUST be granted +to the FIRST matching rule (in list order) with a match meeting the above +criteria. + +When no rules matching a request have been successfully attached to the +parent a request is coming from, a HTTP 404 status code MUST be returned. + +| `matches[]` +| `object` +| HTTPRouteMatch defines the predicate used to match requests to a given +action. Multiple match types are ANDed together, i.e. the match will +evaluate to true only if all conditions are satisfied. + +For example, the match below will match a HTTP request only if its path +starts with `/foo` AND it contains the `version: v1` header: + + +match: + + path: + value: "/foo" + headers: + - name: "version" + value "v1" + + + +| `timeouts` +| `object` +| Timeouts defines the timeouts that can be configured for an HTTP request. + +Support: Extended + +|=== +=== .spec.rules[].backendRefs +Description:: ++ +-- +BackendRefs defines the backend(s) where matching requests should be +sent. + +Failure behavior here depends on how many BackendRefs are specified and +how many are invalid. + +If *all* entries in BackendRefs are invalid, and there are also no filters +specified in this route rule, *all* traffic which matches this rule MUST +receive a 500 status code. + +See the HTTPBackendRef definition for the rules about what makes a single +HTTPBackendRef invalid. + +When a HTTPBackendRef is invalid, 500 status codes MUST be returned for +requests that would have otherwise been routed to an invalid backend. If +multiple backends are specified, and some are invalid, the proportion of +requests that would otherwise have been routed to an invalid backend +MUST receive a 500 status code. + +For example, if two backends are specified with equal weights, and one is +invalid, 50 percent of traffic must receive a 500. Implementations may +choose how that 50 percent is determined. + +When a HTTPBackendRef refers to a Service that has no ready endpoints, +implementations SHOULD return a 503 for requests to that backend instead. +If an implementation chooses to do this, all of the above rules for 500 responses +MUST also apply for responses that return a 503. + +Support: Core for Kubernetes Service + +Support: Extended for Kubernetes ServiceImport + +Support: Implementation-specific for any other resource + +Support for weight: Core +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[] +Description:: ++ +-- +HTTPBackendRef defines how a HTTPRoute forwards a HTTP request. + +Note that when a namespace different than the local namespace is specified, a +ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `filters` +| `array` +| Filters defined at this level should be executed if and only if the +request is being forwarded to the backend defined here. + +Support: Implementation-specific (For broader support of filters, use the +Filters field in HTTPRouteRule.) + +| `filters[]` +| `object` +| HTTPRouteFilter defines processing steps that must be completed during the +request or response lifecycle. HTTPRouteFilters are meant as an extension +point to express processing that may be done in Gateway implementations. Some +examples include request or response modification, implementing +authentication strategies, rate-limiting, and traffic shaping. API +guarantee/conformance is defined based on the type of the filter. + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is the Kubernetes resource kind of the referent. For example +"Service". + +Defaults to "Service" when not specified. + +ExternalName services can refer to CNAME DNS records that may live +outside of the cluster and as such are difficult to reason about in +terms of conformance. They also may not be safe to forward to (see +CVE-2021-25740 for more information). Implementations SHOULD NOT +support ExternalName Services. + +Support: Core (Services with a type other than ExternalName) + +Support: Implementation-specific (Services with type ExternalName) + +| `name` +| `string` +| Name is the name of the referent. + +| `namespace` +| `string` +| Namespace is the namespace of the backend. When unspecified, the local +namespace is inferred. + +Note that when a namespace different than the local namespace is specified, +a ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. + +Support: Core + +| `port` +| `integer` +| Port specifies the destination port number to use for this resource. +Port is required when the referent is a Kubernetes Service. In this +case, the port number is the service port number, not the target port. +For other resources, destination port might be derived from the referent +resource or this field. + +| `weight` +| `integer` +| Weight specifies the proportion of requests forwarded to the referenced +backend. This is computed as weight/(sum of all weights in this +BackendRefs list). For non-zero values, there may be some epsilon from +the exact proportion defined here depending on the precision an +implementation supports. Weight is not a percentage and the sum of +weights does not need to equal 100. + +If only one backend is specified and it has a weight greater than 0, 100% +of the traffic is forwarded to that backend. If weight is set to 0, no +traffic should be forwarded for this entry. If unspecified, weight +defaults to 1. + +Support for this field varies based on the context where used. + +|=== +=== .spec.rules[].backendRefs[].filters +Description:: ++ +-- +Filters defined at this level should be executed if and only if the +request is being forwarded to the backend defined here. + +Support: Implementation-specific (For broader support of filters, use the +Filters field in HTTPRouteRule.) +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[].filters[] +Description:: ++ +-- +HTTPRouteFilter defines processing steps that must be completed during the +request or response lifecycle. HTTPRouteFilters are meant as an extension +point to express processing that may be done in Gateway implementations. Some +examples include request or response modification, implementing +authentication strategies, rate-limiting, and traffic shaping. API +guarantee/conformance is defined based on the type of the filter. +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `extensionRef` +| `object` +| ExtensionRef is an optional, implementation-specific extension to the +"filter" behavior. For example, resource "myroutefilter" in group +"networking.example.net"). ExtensionRef MUST NOT be used for core and +extended filters. + +This filter can be used multiple times within the same rule. + +Support: Implementation-specific + +| `requestHeaderModifier` +| `object` +| RequestHeaderModifier defines a schema for a filter that modifies request +headers. + +Support: Core + +| `requestMirror` +| `object` +| RequestMirror defines a schema for a filter that mirrors requests. +Requests are sent to the specified destination, but responses from +that destination are ignored. + +This filter can be used multiple times within the same rule. Note that +not all implementations will be able to support mirroring to multiple +backends. + +Support: Extended + +| `requestRedirect` +| `object` +| RequestRedirect defines a schema for a filter that responds to the +request with an HTTP redirection. + +Support: Core + +| `responseHeaderModifier` +| `object` +| ResponseHeaderModifier defines a schema for a filter that modifies response +headers. + +Support: Extended + +| `type` +| `string` +| Type identifies the type of filter to apply. As with other API fields, +types are classified into three conformance levels: + +- Core: Filter types and their corresponding configuration defined by + "Support: Core" in this package, e.g. "RequestHeaderModifier". All + implementations must support core filters. + +- Extended: Filter types and their corresponding configuration defined by + "Support: Extended" in this package, e.g. "RequestMirror". Implementers + are encouraged to support extended filters. + +- Implementation-specific: Filters that are defined and supported by + specific vendors. + In the future, filters showing convergence in behavior across multiple + implementations will be considered for inclusion in extended or core + conformance levels. Filter-specific configuration for such filters + is specified using the ExtensionRef field. `Type` should be set to + "ExtensionRef" for custom filters. + +Implementers are encouraged to define custom implementation types to +extend the core API with implementation-specific behavior. + +If a reference to a custom filter type cannot be resolved, the filter +MUST NOT be skipped. Instead, requests that would have been processed by +that filter MUST receive a HTTP error response. + +Note that values may be added to this enum, implementations +must ensure that unknown values will not cause a crash. + +Unknown values here must result in the implementation setting the +Accepted Condition for the Route to `status: False`, with a +Reason of `UnsupportedValue`. + +| `urlRewrite` +| `object` +| URLRewrite defines a schema for a filter that modifies a request during forwarding. + +Support: Extended + +|=== +=== .spec.rules[].backendRefs[].filters[].extensionRef +Description:: ++ +-- +ExtensionRef is an optional, implementation-specific extension to the +"filter" behavior. For example, resource "myroutefilter" in group +"networking.example.net"). ExtensionRef MUST NOT be used for core and +extended filters. + +This filter can be used multiple times within the same rule. + +Support: Implementation-specific +-- + +Type:: + `object` + +Required:: + - `group` + - `kind` + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is kind of the referent. For example "HTTPRoute" or "Service". + +| `name` +| `string` +| Name is the name of the referent. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestHeaderModifier +Description:: ++ +-- +RequestHeaderModifier defines a schema for a filter that modifies request +headers. + +Support: Core +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `add` +| `array` +| Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz + +| `add[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +| `remove` +| `array (string)` +| Remove the given header(s) from the HTTP request before the action. The +value of Remove is a list of HTTP header names. Note that the header +names are case-insensitive (see +https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). + +Input: + GET /foo HTTP/1.1 + my-header1: foo + my-header2: bar + my-header3: baz + +Config: + remove: ["my-header1", "my-header3"] + +Output: + GET /foo HTTP/1.1 + my-header2: bar + +| `set` +| `array` +| Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar + +| `set[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestHeaderModifier.add +Description:: ++ +-- +Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[].filters[].requestHeaderModifier.add[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestHeaderModifier.set +Description:: ++ +-- +Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[].filters[].requestHeaderModifier.set[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestMirror +Description:: ++ +-- +RequestMirror defines a schema for a filter that mirrors requests. +Requests are sent to the specified destination, but responses from +that destination are ignored. + +This filter can be used multiple times within the same rule. Note that +not all implementations will be able to support mirroring to multiple +backends. + +Support: Extended +-- + +Type:: + `object` + +Required:: + - `backendRef` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `backendRef` +| `object` +| BackendRef references a resource where mirrored requests are sent. + +Mirrored requests must be sent only to a single destination endpoint +within this BackendRef, irrespective of how many endpoints are present +within this BackendRef. + +If the referent cannot be found, this BackendRef is invalid and must be +dropped from the Gateway. The controller must ensure the "ResolvedRefs" +condition on the Route status is set to `status: False` and not configure +this backend in the underlying implementation. + +If there is a cross-namespace reference to an *existing* object +that is not allowed by a ReferenceGrant, the controller must ensure the +"ResolvedRefs" condition on the Route is set to `status: False`, +with the "RefNotPermitted" reason and not configure this backend in the +underlying implementation. + +In either error case, the Message of the `ResolvedRefs` Condition +should be used to provide more detail about the problem. + +Support: Extended for Kubernetes Service + +Support: Implementation-specific for any other resource + +| `fraction` +| `object` +| Fraction represents the fraction of requests that should be +mirrored to BackendRef. + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. + +| `percent` +| `integer` +| Percent represents the percentage of requests that should be +mirrored to BackendRef. Its minimum value is 0 (indicating 0% of +requests) and its maximum value is 100 (indicating 100% of requests). + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestMirror.backendRef +Description:: ++ +-- +BackendRef references a resource where mirrored requests are sent. + +Mirrored requests must be sent only to a single destination endpoint +within this BackendRef, irrespective of how many endpoints are present +within this BackendRef. + +If the referent cannot be found, this BackendRef is invalid and must be +dropped from the Gateway. The controller must ensure the "ResolvedRefs" +condition on the Route status is set to `status: False` and not configure +this backend in the underlying implementation. + +If there is a cross-namespace reference to an *existing* object +that is not allowed by a ReferenceGrant, the controller must ensure the +"ResolvedRefs" condition on the Route is set to `status: False`, +with the "RefNotPermitted" reason and not configure this backend in the +underlying implementation. + +In either error case, the Message of the `ResolvedRefs` Condition +should be used to provide more detail about the problem. + +Support: Extended for Kubernetes Service + +Support: Implementation-specific for any other resource +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is the Kubernetes resource kind of the referent. For example +"Service". + +Defaults to "Service" when not specified. + +ExternalName services can refer to CNAME DNS records that may live +outside of the cluster and as such are difficult to reason about in +terms of conformance. They also may not be safe to forward to (see +CVE-2021-25740 for more information). Implementations SHOULD NOT +support ExternalName Services. + +Support: Core (Services with a type other than ExternalName) + +Support: Implementation-specific (Services with type ExternalName) + +| `name` +| `string` +| Name is the name of the referent. + +| `namespace` +| `string` +| Namespace is the namespace of the backend. When unspecified, the local +namespace is inferred. + +Note that when a namespace different than the local namespace is specified, +a ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. + +Support: Core + +| `port` +| `integer` +| Port specifies the destination port number to use for this resource. +Port is required when the referent is a Kubernetes Service. In this +case, the port number is the service port number, not the target port. +For other resources, destination port might be derived from the referent +resource or this field. + +|=== +=== .spec.rules[].backendRefs[].filters[].requestMirror.fraction +Description:: ++ +-- +Fraction represents the fraction of requests that should be +mirrored to BackendRef. + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. +-- + +Type:: + `object` + +Required:: + - `numerator` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `denominator` +| `integer` +| + +| `numerator` +| `integer` +| + +|=== +=== .spec.rules[].backendRefs[].filters[].requestRedirect +Description:: ++ +-- +RequestRedirect defines a schema for a filter that responds to the +request with an HTTP redirection. + +Support: Core +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `hostname` +| `string` +| Hostname is the hostname to be used in the value of the `Location` +header in the response. +When empty, the hostname in the `Host` header of the request is used. + +Support: Core + +| `path` +| `object` +| Path defines parameters used to modify the path of the incoming request. +The modified path is then used to construct the `Location` header. When +empty, the request path is used as-is. + +Support: Extended + +| `port` +| `integer` +| Port is the port to be used in the value of the `Location` +header in the response. + +If no port is specified, the redirect port MUST be derived using the +following rules: + +* If redirect scheme is not-empty, the redirect port MUST be the well-known + port associated with the redirect scheme. Specifically "http" to port 80 + and "https" to port 443. If the redirect scheme does not have a + well-known port, the listener port of the Gateway SHOULD be used. +* If redirect scheme is empty, the redirect port MUST be the Gateway + Listener port. + +Implementations SHOULD NOT add the port number in the 'Location' +header in the following cases: + +* A Location header that will use HTTP (whether that is determined via + the Listener protocol or the Scheme field) _and_ use port 80. +* A Location header that will use HTTPS (whether that is determined via + the Listener protocol or the Scheme field) _and_ use port 443. + +Support: Extended + +| `scheme` +| `string` +| Scheme is the scheme to be used in the value of the `Location` header in +the response. When empty, the scheme of the request is used. + +Scheme redirects can affect the port of the redirect, for more information, +refer to the documentation for the port field of this filter. + +Note that values may be added to this enum, implementations +must ensure that unknown values will not cause a crash. + +Unknown values here must result in the implementation setting the +Accepted Condition for the Route to `status: False`, with a +Reason of `UnsupportedValue`. + +Support: Extended + +| `statusCode` +| `integer` +| StatusCode is the HTTP status code to be used in response. + +Note that values may be added to this enum, implementations +must ensure that unknown values will not cause a crash. + +Unknown values here must result in the implementation setting the +Accepted Condition for the Route to `status: False`, with a +Reason of `UnsupportedValue`. + +Support: Core + +|=== +=== .spec.rules[].backendRefs[].filters[].requestRedirect.path +Description:: ++ +-- +Path defines parameters used to modify the path of the incoming request. +The modified path is then used to construct the `Location` header. When +empty, the request path is used as-is. + +Support: Extended +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `replaceFullPath` +| `string` +| ReplaceFullPath specifies the value with which to replace the full path +of a request during a rewrite or redirect. + +| `replacePrefixMatch` +| `string` +| ReplacePrefixMatch specifies the value with which to replace the prefix +match of a request during a rewrite or redirect. For example, a request +to "/foo/bar" with a prefix match of "/foo" and a ReplacePrefixMatch +of "/xyz" would be modified to "/xyz/bar". + +Note that this matches the behavior of the PathPrefix match type. This +matches full path elements. A path element refers to the list of labels +in the path split by the `/` separator. When specified, a trailing `/` is +ignored. For example, the paths `/abc`, `/abc/`, and `/abc/def` would all +match the prefix `/abc`, but the path `/abcd` would not. + +ReplacePrefixMatch is only compatible with a `PathPrefix` HTTPRouteMatch. +Using any other HTTPRouteMatch type on the same HTTPRouteRule will result in +the implementation setting the Accepted Condition for the Route to `status: False`. + +Request Path \| Prefix Match \| Replace Prefix \| Modified Path + +| `type` +| `string` +| Type defines the type of path modifier. Additional types may be +added in a future release of the API. + +Note that values may be added to this enum, implementations +must ensure that unknown values will not cause a crash. + +Unknown values here must result in the implementation setting the +Accepted Condition for the Route to `status: False`, with a +Reason of `UnsupportedValue`. + +|=== +=== .spec.rules[].backendRefs[].filters[].responseHeaderModifier +Description:: ++ +-- +ResponseHeaderModifier defines a schema for a filter that modifies response +headers. + +Support: Extended +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `add` +| `array` +| Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz + +| `add[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +| `remove` +| `array (string)` +| Remove the given header(s) from the HTTP request before the action. The +value of Remove is a list of HTTP header names. Note that the header +names are case-insensitive (see +https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). + +Input: + GET /foo HTTP/1.1 + my-header1: foo + my-header2: bar + my-header3: baz + +Config: + remove: ["my-header1", "my-header3"] + +Output: + GET /foo HTTP/1.1 + my-header2: bar + +| `set` +| `array` +| Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar + +| `set[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +|=== +=== .spec.rules[].backendRefs[].filters[].responseHeaderModifier.add +Description:: ++ +-- +Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[].filters[].responseHeaderModifier.add[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].backendRefs[].filters[].responseHeaderModifier.set +Description:: ++ +-- +Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar +-- + +Type:: + `array` + + + + +=== .spec.rules[].backendRefs[].filters[].responseHeaderModifier.set[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].backendRefs[].filters[].urlRewrite +Description:: ++ +-- +URLRewrite defines a schema for a filter that modifies a request during forwarding. + +Support: Extended +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `hostname` +| `string` +| Hostname is the value to be used to replace the Host header value during +forwarding. + +Support: Extended + +| `path` +| `object` +| Path defines a path rewrite. + +Support: Extended + +|=== +=== .spec.rules[].backendRefs[].filters[].urlRewrite.path +Description:: ++ +-- +Path defines a path rewrite. + +Support: Extended +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `replaceFullPath` +| `string` +| ReplaceFullPath specifies the value with which to replace the full path +of a request during a rewrite or redirect. + +| `replacePrefixMatch` +| `string` +| ReplacePrefixMatch specifies the value with which to replace the prefix +match of a request during a rewrite or redirect. For example, a request +to "/foo/bar" with a prefix match of "/foo" and a ReplacePrefixMatch +of "/xyz" would be modified to "/xyz/bar". + +Note that this matches the behavior of the PathPrefix match type. This +matches full path elements. A path element refers to the list of labels +in the path split by the `/` separator. When specified, a trailing `/` is +ignored. For example, the paths `/abc`, `/abc/`, and `/abc/def` would all +match the prefix `/abc`, but the path `/abcd` would not. + +ReplacePrefixMatch is only compatible with a `PathPrefix` HTTPRouteMatch. +Using any other HTTPRouteMatch type on the same HTTPRouteRule will result in +the implementation setting the Accepted Condition for the Route to `status: False`. + +Request Path \| Prefix Match \| Replace Prefix \| Modified Path + +| `type` +| `string` +| Type defines the type of path modifier. Additional types may be +added in a future release of the API. + +Note that values may be added to this enum, implementations +must ensure that unknown values will not cause a crash. + +Unknown values here must result in the implementation setting the +Accepted Condition for the Route to `status: False`, with a +Reason of `UnsupportedValue`. + +|=== +=== .spec.rules[].filters +Description:: ++ +-- +Filters define the filters that are applied to requests that match +this rule. + +Wherever possible, implementations SHOULD implement filters in the order +they are specified. + +Implementations MAY choose to implement this ordering strictly, rejecting +any combination or order of filters that cannot be supported. If implementations +choose a strict interpretation of filter ordering, they MUST clearly document +that behavior. + +To reject an invalid combination or order of filters, implementations SHOULD +consider the Route Rules with this configuration invalid. If all Route Rules +in a Route are invalid, the entire Route would be considered invalid. If only +a portion of Route Rules are invalid, implementations MUST set the +"PartiallyInvalid" condition for the Route. + +Conformance-levels at this level are defined based on the type of filter: + +- ALL core filters MUST be supported by all implementations. +- Implementers are encouraged to support extended filters. +- Implementation-specific custom filters have no API guarantees across + implementations. + +Specifying the same filter multiple times is not supported unless explicitly +indicated in the filter. + +All filters are expected to be compatible with each other except for the +URLRewrite and RequestRedirect filters, which may not be combined. If an +implementation cannot support other combinations of filters, they must clearly +document that limitation. In cases where incompatible or unsupported +filters are specified and cause the `Accepted` condition to be set to status +`False`, implementations may use the `IncompatibleFilters` reason to specify +this configuration error. + +Support: Core +-- + +Type:: + `array` + + + + +=== .spec.rules[].filters[] +Description:: ++ +-- +HTTPRouteFilter defines processing steps that must be completed during the +request or response lifecycle. HTTPRouteFilters are meant as an extension +point to express processing that may be done in Gateway implementations. Some +examples include request or response modification, implementing +authentication strategies, rate-limiting, and traffic shaping. API +guarantee/conformance is defined based on the type of the filter. +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `extensionRef` +| `object` +| ExtensionRef is an optional, implementation-specific extension to the +"filter" behavior. For example, resource "myroutefilter" in group +"networking.example.net"). ExtensionRef MUST NOT be used for core and +extended filters. + +This filter can be used multiple times within the same rule. + +Support: Implementation-specific + +| `requestHeaderModifier` +| `object` +| RequestHeaderModifier defines a schema for a filter that modifies request +headers. + +Support: Core + +| `requestMirror` +| `object` +| RequestMirror defines a schema for a filter that mirrors requests. +Requests are sent to the specified destination, but responses from +that destination are ignored. + +This filter can be used multiple times within the same rule. Note that +not all implementations will be able to support mirroring to multiple +backends. + +Support: Extended + +| `requestRedirect` +| `object` +| RequestRedirect defines a schema for a filter that responds to the +request with an HTTP redirection. + +Support: Core + +| `responseHeaderModifier` +| `object` +| ResponseHeaderModifier defines a schema for a filter that modifies response +headers. + +Support: Extended + +| `type` +| `string` +| Type identifies the type of filter to apply. As with other API fields, +types are classified into three conformance levels: + +- Core: Filter types and their corresponding configuration defined by + "Support: Core" in this package, e.g. "RequestHeaderModifier". All + implementations must support core filters. + +- Extended: Filter types and their corresponding configuration defined by + "Support: Extended" in this package, e.g. "RequestMirror". Implementers + are encouraged to support extended filters. + +- Implementation-specific: Filters that are defined and supported by + specific vendors. + In the future, filters showing convergence in behavior across multiple + implementations will be considered for inclusion in extended or core + conformance levels. Filter-specific configuration for such filters + is specified using the ExtensionRef field. `Type` should be set to + "ExtensionRef" for custom filters. + +Implementers are encouraged to define custom implementation types to +extend the core API with implementation-specific behavior. + +If a reference to a custom filter type cannot be resolved, the filter +MUST NOT be skipped. Instead, requests that would have been processed by +that filter MUST receive a HTTP error response. + +Note that values may be added to this enum, implementations +must ensure that unknown values will not cause a crash. + +Unknown values here must result in the implementation setting the +Accepted Condition for the Route to `status: False`, with a +Reason of `UnsupportedValue`. + +| `urlRewrite` +| `object` +| URLRewrite defines a schema for a filter that modifies a request during forwarding. + +Support: Extended + +|=== +=== .spec.rules[].filters[].extensionRef +Description:: ++ +-- +ExtensionRef is an optional, implementation-specific extension to the +"filter" behavior. For example, resource "myroutefilter" in group +"networking.example.net"). ExtensionRef MUST NOT be used for core and +extended filters. + +This filter can be used multiple times within the same rule. + +Support: Implementation-specific +-- + +Type:: + `object` + +Required:: + - `group` + - `kind` + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is kind of the referent. For example "HTTPRoute" or "Service". + +| `name` +| `string` +| Name is the name of the referent. + +|=== +=== .spec.rules[].filters[].requestHeaderModifier +Description:: ++ +-- +RequestHeaderModifier defines a schema for a filter that modifies request +headers. + +Support: Core +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `add` +| `array` +| Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz + +| `add[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +| `remove` +| `array (string)` +| Remove the given header(s) from the HTTP request before the action. The +value of Remove is a list of HTTP header names. Note that the header +names are case-insensitive (see +https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). + +Input: + GET /foo HTTP/1.1 + my-header1: foo + my-header2: bar + my-header3: baz + +Config: + remove: ["my-header1", "my-header3"] + +Output: + GET /foo HTTP/1.1 + my-header2: bar + +| `set` +| `array` +| Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar + +| `set[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +|=== +=== .spec.rules[].filters[].requestHeaderModifier.add +Description:: ++ +-- +Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz +-- + +Type:: + `array` + + + + +=== .spec.rules[].filters[].requestHeaderModifier.add[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].filters[].requestHeaderModifier.set +Description:: ++ +-- +Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar +-- + +Type:: + `array` + + + + +=== .spec.rules[].filters[].requestHeaderModifier.set[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].filters[].requestMirror +Description:: ++ +-- +RequestMirror defines a schema for a filter that mirrors requests. +Requests are sent to the specified destination, but responses from +that destination are ignored. + +This filter can be used multiple times within the same rule. Note that +not all implementations will be able to support mirroring to multiple +backends. + +Support: Extended +-- + +Type:: + `object` + +Required:: + - `backendRef` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `backendRef` +| `object` +| BackendRef references a resource where mirrored requests are sent. + +Mirrored requests must be sent only to a single destination endpoint +within this BackendRef, irrespective of how many endpoints are present +within this BackendRef. + +If the referent cannot be found, this BackendRef is invalid and must be +dropped from the Gateway. The controller must ensure the "ResolvedRefs" +condition on the Route status is set to `status: False` and not configure +this backend in the underlying implementation. + +If there is a cross-namespace reference to an *existing* object +that is not allowed by a ReferenceGrant, the controller must ensure the +"ResolvedRefs" condition on the Route is set to `status: False`, +with the "RefNotPermitted" reason and not configure this backend in the +underlying implementation. + +In either error case, the Message of the `ResolvedRefs` Condition +should be used to provide more detail about the problem. + +Support: Extended for Kubernetes Service + +Support: Implementation-specific for any other resource + +| `fraction` +| `object` +| Fraction represents the fraction of requests that should be +mirrored to BackendRef. + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. + +| `percent` +| `integer` +| Percent represents the percentage of requests that should be +mirrored to BackendRef. Its minimum value is 0 (indicating 0% of +requests) and its maximum value is 100 (indicating 100% of requests). + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. + +|=== +=== .spec.rules[].filters[].requestMirror.backendRef +Description:: ++ +-- +BackendRef references a resource where mirrored requests are sent. + +Mirrored requests must be sent only to a single destination endpoint +within this BackendRef, irrespective of how many endpoints are present +within this BackendRef. + +If the referent cannot be found, this BackendRef is invalid and must be +dropped from the Gateway. The controller must ensure the "ResolvedRefs" +condition on the Route status is set to `status: False` and not configure +this backend in the underlying implementation. + +If there is a cross-namespace reference to an *existing* object +that is not allowed by a ReferenceGrant, the controller must ensure the +"ResolvedRefs" condition on the Route is set to `status: False`, +with the "RefNotPermitted" reason and not configure this backend in the +underlying implementation. + +In either error case, the Message of the `ResolvedRefs` Condition +should be used to provide more detail about the problem. + +Support: Extended for Kubernetes Service + +Support: Implementation-specific for any other resource +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. For example, "gateway.networking.k8s.io". +When unspecified or empty string, core API group is inferred. + +| `kind` +| `string` +| Kind is the Kubernetes resource kind of the referent. For example +"Service". + +Defaults to "Service" when not specified. + +ExternalName services can refer to CNAME DNS records that may live +outside of the cluster and as such are difficult to reason about in +terms of conformance. They also may not be safe to forward to (see +CVE-2021-25740 for more information). Implementations SHOULD NOT +support ExternalName Services. + +Support: Core (Services with a type other than ExternalName) + +Support: Implementation-specific (Services with type ExternalName) + +| `name` +| `string` +| Name is the name of the referent. + +| `namespace` +| `string` +| Namespace is the namespace of the backend. When unspecified, the local +namespace is inferred. + +Note that when a namespace different than the local namespace is specified, +a ReferenceGrant object is required in the referent namespace to allow that +namespace's owner to accept the reference. See the ReferenceGrant +documentation for details. + +Support: Core + +| `port` +| `integer` +| Port specifies the destination port number to use for this resource. +Port is required when the referent is a Kubernetes Service. In this +case, the port number is the service port number, not the target port. +For other resources, destination port might be derived from the referent +resource or this field. + +|=== +=== .spec.rules[].filters[].requestMirror.fraction +Description:: ++ +-- +Fraction represents the fraction of requests that should be +mirrored to BackendRef. + +Only one of Fraction or Percent may be specified. If neither field +is specified, 100% of requests will be mirrored. +-- + +Type:: + `object` + +Required:: + - `numerator` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `denominator` +| `integer` +| + +| `numerator` +| `integer` +| + +|=== +=== .spec.rules[].filters[].requestRedirect +Description:: ++ +-- +RequestRedirect defines a schema for a filter that responds to the +request with an HTTP redirection. + +Support: Core +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `hostname` +| `string` +| Hostname is the hostname to be used in the value of the `Location` +header in the response. +When empty, the hostname in the `Host` header of the request is used. + +Support: Core + +| `path` +| `object` +| Path defines parameters used to modify the path of the incoming request. +The modified path is then used to construct the `Location` header. When +empty, the request path is used as-is. + +Support: Extended + +| `port` +| `integer` +| Port is the port to be used in the value of the `Location` +header in the response. + +If no port is specified, the redirect port MUST be derived using the +following rules: + +* If redirect scheme is not-empty, the redirect port MUST be the well-known + port associated with the redirect scheme. Specifically "http" to port 80 + and "https" to port 443. If the redirect scheme does not have a + well-known port, the listener port of the Gateway SHOULD be used. +* If redirect scheme is empty, the redirect port MUST be the Gateway + Listener port. + +Implementations SHOULD NOT add the port number in the 'Location' +header in the following cases: + +* A Location header that will use HTTP (whether that is determined via + the Listener protocol or the Scheme field) _and_ use port 80. +* A Location header that will use HTTPS (whether that is determined via + the Listener protocol or the Scheme field) _and_ use port 443. + +Support: Extended + +| `scheme` +| `string` +| Scheme is the scheme to be used in the value of the `Location` header in +the response. When empty, the scheme of the request is used. + +Scheme redirects can affect the port of the redirect, for more information, +refer to the documentation for the port field of this filter. + +Note that values may be added to this enum, implementations +must ensure that unknown values will not cause a crash. + +Unknown values here must result in the implementation setting the +Accepted Condition for the Route to `status: False`, with a +Reason of `UnsupportedValue`. + +Support: Extended + +| `statusCode` +| `integer` +| StatusCode is the HTTP status code to be used in response. + +Note that values may be added to this enum, implementations +must ensure that unknown values will not cause a crash. + +Unknown values here must result in the implementation setting the +Accepted Condition for the Route to `status: False`, with a +Reason of `UnsupportedValue`. + +Support: Core + +|=== +=== .spec.rules[].filters[].requestRedirect.path +Description:: ++ +-- +Path defines parameters used to modify the path of the incoming request. +The modified path is then used to construct the `Location` header. When +empty, the request path is used as-is. + +Support: Extended +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `replaceFullPath` +| `string` +| ReplaceFullPath specifies the value with which to replace the full path +of a request during a rewrite or redirect. + +| `replacePrefixMatch` +| `string` +| ReplacePrefixMatch specifies the value with which to replace the prefix +match of a request during a rewrite or redirect. For example, a request +to "/foo/bar" with a prefix match of "/foo" and a ReplacePrefixMatch +of "/xyz" would be modified to "/xyz/bar". + +Note that this matches the behavior of the PathPrefix match type. This +matches full path elements. A path element refers to the list of labels +in the path split by the `/` separator. When specified, a trailing `/` is +ignored. For example, the paths `/abc`, `/abc/`, and `/abc/def` would all +match the prefix `/abc`, but the path `/abcd` would not. + +ReplacePrefixMatch is only compatible with a `PathPrefix` HTTPRouteMatch. +Using any other HTTPRouteMatch type on the same HTTPRouteRule will result in +the implementation setting the Accepted Condition for the Route to `status: False`. + +Request Path \| Prefix Match \| Replace Prefix \| Modified Path + +| `type` +| `string` +| Type defines the type of path modifier. Additional types may be +added in a future release of the API. + +Note that values may be added to this enum, implementations +must ensure that unknown values will not cause a crash. + +Unknown values here must result in the implementation setting the +Accepted Condition for the Route to `status: False`, with a +Reason of `UnsupportedValue`. + +|=== +=== .spec.rules[].filters[].responseHeaderModifier +Description:: ++ +-- +ResponseHeaderModifier defines a schema for a filter that modifies response +headers. + +Support: Extended +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `add` +| `array` +| Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz + +| `add[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +| `remove` +| `array (string)` +| Remove the given header(s) from the HTTP request before the action. The +value of Remove is a list of HTTP header names. Note that the header +names are case-insensitive (see +https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). + +Input: + GET /foo HTTP/1.1 + my-header1: foo + my-header2: bar + my-header3: baz + +Config: + remove: ["my-header1", "my-header3"] + +Output: + GET /foo HTTP/1.1 + my-header2: bar + +| `set` +| `array` +| Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar + +| `set[]` +| `object` +| HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. + +|=== +=== .spec.rules[].filters[].responseHeaderModifier.add +Description:: ++ +-- +Add adds the given header(s) (name, value) to the request +before the action. It appends to any existing values associated +with the header name. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + add: + - name: "my-header" + value: "bar,baz" + +Output: + GET /foo HTTP/1.1 + my-header: foo,bar,baz +-- + +Type:: + `array` + + + + +=== .spec.rules[].filters[].responseHeaderModifier.add[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].filters[].responseHeaderModifier.set +Description:: ++ +-- +Set overwrites the request with the given header (name, value) +before the action. + +Input: + GET /foo HTTP/1.1 + my-header: foo + +Config: + set: + - name: "my-header" + value: "bar" + +Output: + GET /foo HTTP/1.1 + my-header: bar +-- + +Type:: + `array` + + + + +=== .spec.rules[].filters[].responseHeaderModifier.set[] +Description:: ++ +-- +HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, the first entry with +an equivalent name MUST be considered for a match. Subsequent entries +with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].filters[].urlRewrite +Description:: ++ +-- +URLRewrite defines a schema for a filter that modifies a request during forwarding. + +Support: Extended +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `hostname` +| `string` +| Hostname is the value to be used to replace the Host header value during +forwarding. + +Support: Extended + +| `path` +| `object` +| Path defines a path rewrite. + +Support: Extended + +|=== +=== .spec.rules[].filters[].urlRewrite.path +Description:: ++ +-- +Path defines a path rewrite. + +Support: Extended +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `replaceFullPath` +| `string` +| ReplaceFullPath specifies the value with which to replace the full path +of a request during a rewrite or redirect. + +| `replacePrefixMatch` +| `string` +| ReplacePrefixMatch specifies the value with which to replace the prefix +match of a request during a rewrite or redirect. For example, a request +to "/foo/bar" with a prefix match of "/foo" and a ReplacePrefixMatch +of "/xyz" would be modified to "/xyz/bar". + +Note that this matches the behavior of the PathPrefix match type. This +matches full path elements. A path element refers to the list of labels +in the path split by the `/` separator. When specified, a trailing `/` is +ignored. For example, the paths `/abc`, `/abc/`, and `/abc/def` would all +match the prefix `/abc`, but the path `/abcd` would not. + +ReplacePrefixMatch is only compatible with a `PathPrefix` HTTPRouteMatch. +Using any other HTTPRouteMatch type on the same HTTPRouteRule will result in +the implementation setting the Accepted Condition for the Route to `status: False`. + +Request Path \| Prefix Match \| Replace Prefix \| Modified Path + +| `type` +| `string` +| Type defines the type of path modifier. Additional types may be +added in a future release of the API. + +Note that values may be added to this enum, implementations +must ensure that unknown values will not cause a crash. + +Unknown values here must result in the implementation setting the +Accepted Condition for the Route to `status: False`, with a +Reason of `UnsupportedValue`. + +|=== +=== .spec.rules[].matches +Description:: ++ +-- +Matches define conditions used for matching the rule against incoming +HTTP requests. Each match is independent, i.e. this rule will be matched +if **any** one of the matches is satisfied. + +For example, take the following matches configuration: + + +matches: +- path: + value: "/foo" + headers: + - name: "version" + value: "v2" +- path: + value: "/v2/foo" + + +For a request to match against this rule, a request must satisfy +EITHER of the two conditions: + +- path prefixed with `/foo` AND contains the header `version: v2` +- path prefix of `/v2/foo` + +See the documentation for HTTPRouteMatch on how to specify multiple +match conditions that should be ANDed together. + +If no matches are specified, the default is a prefix +path match on "/", which has the effect of matching every +HTTP request. + +Proxy or Load Balancer routing configuration generated from HTTPRoutes +MUST prioritize matches based on the following criteria, continuing on +ties. Across all rules specified on applicable Routes, precedence must be +given to the match having: + +* "Exact" path match. +* "Prefix" path match with largest number of characters. +* Method match. +* Largest number of header matches. +* Largest number of query param matches. + +Note: The precedence of RegularExpression path matches are implementation-specific. + +If ties still exist across multiple Routes, matching precedence MUST be +determined in order of the following criteria, continuing on ties: + +* The oldest Route based on creation timestamp. +* The Route appearing first in alphabetical order by + "{namespace}/{name}". + +If ties still exist within an HTTPRoute, matching precedence MUST be granted +to the FIRST matching rule (in list order) with a match meeting the above +criteria. + +When no rules matching a request have been successfully attached to the +parent a request is coming from, a HTTP 404 status code MUST be returned. +-- + +Type:: + `array` + + + + +=== .spec.rules[].matches[] +Description:: ++ +-- +HTTPRouteMatch defines the predicate used to match requests to a given +action. Multiple match types are ANDed together, i.e. the match will +evaluate to true only if all conditions are satisfied. + +For example, the match below will match a HTTP request only if its path +starts with `/foo` AND it contains the `version: v1` header: + + +match: + + path: + value: "/foo" + headers: + - name: "version" + value "v1" + + +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `headers` +| `array` +| Headers specifies HTTP request header matchers. Multiple match values are +ANDed together, meaning, a request must match all the specified headers +to select the route. + +| `headers[]` +| `object` +| HTTPHeaderMatch describes how to select a HTTP route by matching HTTP request +headers. + +| `method` +| `string` +| Method specifies HTTP method matcher. +When specified, this route will be matched only if the request has the +specified method. + +Support: Extended + +| `path` +| `object` +| Path specifies a HTTP request path matcher. If this field is not +specified, a default prefix match on the "/" path is provided. + +| `queryParams` +| `array` +| QueryParams specifies HTTP query parameter matchers. Multiple match +values are ANDed together, meaning, a request must match all the +specified query parameters to select the route. + +Support: Extended + +| `queryParams[]` +| `object` +| HTTPQueryParamMatch describes how to select a HTTP route by matching HTTP +query parameters. + +|=== +=== .spec.rules[].matches[].headers +Description:: ++ +-- +Headers specifies HTTP request header matchers. Multiple match values are +ANDed together, meaning, a request must match all the specified headers +to select the route. +-- + +Type:: + `array` + + + + +=== .spec.rules[].matches[].headers[] +Description:: ++ +-- +HTTPHeaderMatch describes how to select a HTTP route by matching HTTP request +headers. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP Header to be matched. Name matching MUST be +case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). + +If multiple entries specify equivalent header names, only the first +entry with an equivalent name MUST be considered for a match. Subsequent +entries with an equivalent header name MUST be ignored. Due to the +case-insensitivity of header names, "foo" and "Foo" are considered +equivalent. + +When a header is repeated in an HTTP request, it is +implementation-specific behavior as to how this is represented. +Generally, proxies should follow the guidance from the RFC: +https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2.2 regarding +processing a repeated header, with special handling for "Set-Cookie". + +| `type` +| `string` +| Type specifies how to match against the value of the header. + +Support: Core (Exact) + +Support: Implementation-specific (RegularExpression) + +Since RegularExpression HeaderMatchType has implementation-specific +conformance, implementations can support POSIX, PCRE or any other dialects +of regular expressions. Please read the implementation's documentation to +determine the supported dialect. + +| `value` +| `string` +| Value is the value of HTTP Header to be matched. + +|=== +=== .spec.rules[].matches[].path +Description:: ++ +-- +Path specifies a HTTP request path matcher. If this field is not +specified, a default prefix match on the "/" path is provided. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `type` +| `string` +| Type specifies how to match against the path Value. + +Support: Core (Exact, PathPrefix) + +Support: Implementation-specific (RegularExpression) + +| `value` +| `string` +| Value of the HTTP path to match against. + +|=== +=== .spec.rules[].matches[].queryParams +Description:: ++ +-- +QueryParams specifies HTTP query parameter matchers. Multiple match +values are ANDed together, meaning, a request must match all the +specified query parameters to select the route. + +Support: Extended +-- + +Type:: + `array` + + + + +=== .spec.rules[].matches[].queryParams[] +Description:: ++ +-- +HTTPQueryParamMatch describes how to select a HTTP route by matching HTTP +query parameters. +-- + +Type:: + `object` + +Required:: + - `name` + - `value` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name is the name of the HTTP query param to be matched. This must be an +exact string match. (See +https://tools.ietf.org/html/rfc7230#section-2.7.3). + +If multiple entries specify equivalent query param names, only the first +entry with an equivalent name MUST be considered for a match. Subsequent +entries with an equivalent query param name MUST be ignored. + +If a query param is repeated in an HTTP request, the behavior is +purposely left undefined, since different data planes have different +capabilities. However, it is *recommended* that implementations should +match against the first value of the param if the data plane supports it, +as this behavior is expected in other load balancing contexts outside of +the Gateway API. + +Users SHOULD NOT route traffic based on repeated query params to guard +themselves against potential differences in the implementations. + +| `type` +| `string` +| Type specifies how to match against the value of the query parameter. + +Support: Extended (Exact) + +Support: Implementation-specific (RegularExpression) + +Since RegularExpression QueryParamMatchType has Implementation-specific +conformance, implementations can support POSIX, PCRE or any other +dialects of regular expressions. Please read the implementation's +documentation to determine the supported dialect. + +| `value` +| `string` +| Value is the value of HTTP query param to be matched. + +|=== +=== .spec.rules[].timeouts +Description:: ++ +-- +Timeouts defines the timeouts that can be configured for an HTTP request. + +Support: Extended +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `backendRequest` +| `string` +| BackendRequest specifies a timeout for an individual request from the gateway +to a backend. This covers the time from when the request first starts being +sent from the gateway to when the full response has been received from the backend. + +Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout +completely. Implementations that cannot completely disable the timeout MUST +instead interpret the zero duration as the longest possible value to which +the timeout can be set. + +An entire client HTTP transaction with a gateway, covered by the Request timeout, +may result in more than one call from the gateway to the destination backend, +for example, if automatic retries are supported. + +The value of BackendRequest must be a Gateway API Duration string as defined by +GEP-2257. When this field is unspecified, its behavior is implementation-specific; +when specified, the value of BackendRequest must be no more than the value of the +Request timeout (since the Request timeout encompasses the BackendRequest timeout). + +Support: Extended + +| `request` +| `string` +| Request specifies the maximum duration for a gateway to respond to an HTTP request. +If the gateway has not been able to respond before this deadline is met, the gateway +MUST return a timeout error. + +For example, setting the `rules.timeouts.request` field to the value `10s` in an +`HTTPRoute` will cause a timeout if a client request is taking longer than 10 seconds +to complete. + +Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout +completely. Implementations that cannot completely disable the timeout MUST +instead interpret the zero duration as the longest possible value to which +the timeout can be set. + +This timeout is intended to cover as close to the whole request-response transaction +as possible although an implementation MAY choose to start the timeout after the entire +request stream has been received instead of immediately after the transaction is +initiated by the client. + +The value of Request is a Gateway API Duration string as defined by GEP-2257. When this +field is unspecified, request timeout behavior is implementation-specific. + +Support: Extended + +|=== +=== .status +Description:: ++ +-- +Status defines the current state of HTTPRoute. +-- + +Type:: + `object` + +Required:: + - `parents` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `parents` +| `array` +| Parents is a list of parent resources (usually Gateways) that are +associated with the route, and the status of the route with respect to +each parent. When this route attaches to a parent, the controller that +manages the parent must add an entry to this list when the controller +first sees the route and should update the entry as appropriate when the +route or gateway is modified. + +Note that parent references that cannot be resolved by an implementation +of this API will not be added to this list. Implementations of this API +can only populate Route status for the Gateways/parent resources they are +responsible for. + +A maximum of 32 Gateways will be represented in this list. An empty list +means the route has not been attached to any Gateway. + +| `parents[]` +| `object` +| RouteParentStatus describes the status of a route with respect to an +associated Parent. + +|=== +=== .status.parents +Description:: ++ +-- +Parents is a list of parent resources (usually Gateways) that are +associated with the route, and the status of the route with respect to +each parent. When this route attaches to a parent, the controller that +manages the parent must add an entry to this list when the controller +first sees the route and should update the entry as appropriate when the +route or gateway is modified. + +Note that parent references that cannot be resolved by an implementation +of this API will not be added to this list. Implementations of this API +can only populate Route status for the Gateways/parent resources they are +responsible for. + +A maximum of 32 Gateways will be represented in this list. An empty list +means the route has not been attached to any Gateway. +-- + +Type:: + `array` + + + + +=== .status.parents[] +Description:: ++ +-- +RouteParentStatus describes the status of a route with respect to an +associated Parent. +-- + +Type:: + `object` + +Required:: + - `controllerName` + - `parentRef` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| Conditions describes the status of the route with respect to the Gateway. +Note that the route's availability is also subject to the Gateway's own +status conditions and listener status. + +If the Route's ParentRef specifies an existing Gateway that supports +Routes of this kind AND that Gateway's controller has sufficient access, +then that Gateway's controller MUST set the "Accepted" condition on the +Route, to indicate whether the route has been accepted or rejected by the +Gateway, and why. + +A Route MUST be considered "Accepted" if at least one of the Route's +rules is implemented by the Gateway. + +There are a number of cases where the "Accepted" condition may not be set +due to lack of controller visibility, that includes when: + +* The Route refers to a nonexistent parent. +* The Route is of a type that the controller does not support. +* The Route is in a namespace the controller does not have access to. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `controllerName` +| `string` +| ControllerName is a domain/path string that indicates the name of the +controller that wrote this status. This corresponds with the +controllerName field on GatewayClass. + +Example: "example.net/gateway-controller". + +The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are +valid Kubernetes names +(https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). + +Controllers MUST populate this field when writing status. Controllers should ensure that +entries to status populated with their ControllerName are cleaned up when they are no +longer necessary. + +| `parentRef` +| `object` +| ParentRef corresponds with a ParentRef in the spec that this +RouteParentStatus struct describes the status of. + +|=== +=== .status.parents[].conditions +Description:: ++ +-- +Conditions describes the status of the route with respect to the Gateway. +Note that the route's availability is also subject to the Gateway's own +status conditions and listener status. + +If the Route's ParentRef specifies an existing Gateway that supports +Routes of this kind AND that Gateway's controller has sufficient access, +then that Gateway's controller MUST set the "Accepted" condition on the +Route, to indicate whether the route has been accepted or rejected by the +Gateway, and why. + +A Route MUST be considered "Accepted" if at least one of the Route's +rules is implemented by the Gateway. + +There are a number of cases where the "Accepted" condition may not be set +due to lack of controller visibility, that includes when: + +* The Route refers to a nonexistent parent. +* The Route is of a type that the controller does not support. +* The Route is in a namespace the controller does not have access to. +-- + +Type:: + `array` + + + + +=== .status.parents[].conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== +=== .status.parents[].parentRef +Description:: ++ +-- +ParentRef corresponds with a ParentRef in the spec that this +RouteParentStatus struct describes the status of. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. +When unspecified, "gateway.networking.k8s.io" is inferred. +To set the core API group (such as for a "Service" kind referent), +Group must be explicitly set to "" (empty string). + +Support: Core + +| `kind` +| `string` +| Kind is kind of the referent. + +There are two kinds of parent resources with "Core" support: + +* Gateway (Gateway conformance profile) +* Service (Mesh conformance profile, ClusterIP Services only) + +Support for other resources is Implementation-Specific. + +| `name` +| `string` +| Name is the name of the referent. + +Support: Core + +| `namespace` +| `string` +| Namespace is the namespace of the referent. When unspecified, this refers +to the local namespace of the Route. + +Note that there are specific rules for ParentRefs which cross namespace +boundaries. Cross-namespace references are only valid if they are explicitly +allowed by something in the namespace they are referring to. For example: +Gateway has the AllowedRoutes field, and ReferenceGrant provides a +generic way to enable any other kind of cross-namespace reference. + +Support: Core + +| `port` +| `integer` +| Port is the network port this Route targets. It can be interpreted +differently based on the type of parent resource. + +When the parent resource is a Gateway, this targets all listeners +listening on the specified port that also support this kind of Route(and +select this Route). It's not recommended to set `Port` unless the +networking behaviors specified in a Route must apply to a specific port +as opposed to a listener(s) whose port(s) may be changed. When both Port +and SectionName are specified, the name and port of the selected listener +must match both specified values. + +Implementations MAY choose to support other parent resources. +Implementations supporting other types of parent resources MUST clearly +document how/if Port is interpreted. + +For the purpose of status, an attachment is considered successful as +long as the parent resource accepts it partially. For example, Gateway +listeners can restrict which Routes can attach to them by Route kind, +namespace, or hostname. If 1 of 2 Gateway listeners accept attachment +from the referencing Route, the Route MUST be considered successfully +attached. If no Gateway listeners accept attachment from this Route, +the Route MUST be considered detached from the Gateway. + +Support: Extended + +| `sectionName` +| `string` +| SectionName is the name of a section within the target resource. In the +following resources, SectionName is interpreted as the following: + +* Gateway: Listener name. When both Port (experimental) and SectionName +are specified, the name and port of the selected listener must match +both specified values. +* Service: Port name. When both Port (experimental) and SectionName +are specified, the name and port of the selected listener must match +both specified values. + +Implementations MAY choose to support attaching Routes to other resources. +If that is the case, they MUST clearly document how SectionName is +interpreted. + +When unspecified (empty string), this will reference the entire resource. +For the purpose of status, an attachment is considered successful if at +least one section in the parent resource accepts it. For example, Gateway +listeners can restrict which Routes can attach to them by Route kind, +namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from +the referencing Route, the Route MUST be considered successfully +attached. If no Gateway listeners accept attachment from this Route, the +Route MUST be considered detached from the Gateway. + +Support: Core + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/gateway.networking.k8s.io/v1/httproutes` +- `GET`: list objects of kind HTTPRoute +* `/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/httproutes` +- `DELETE`: delete collection of HTTPRoute +- `GET`: list objects of kind HTTPRoute +- `POST`: create a HTTPRoute +* `/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/httproutes/{name}` +- `DELETE`: delete a HTTPRoute +- `GET`: read the specified HTTPRoute +- `PATCH`: partially update the specified HTTPRoute +- `PUT`: replace the specified HTTPRoute +* `/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/httproutes/{name}/status` +- `GET`: read status of the specified HTTPRoute +- `PATCH`: partially update status of the specified HTTPRoute +- `PUT`: replace status of the specified HTTPRoute + + +=== /apis/gateway.networking.k8s.io/v1/httproutes + + + +HTTP method:: + `GET` + +Description:: + list objects of kind HTTPRoute + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-networking-gateway-v1-HTTPRouteList[`HTTPRouteList`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/httproutes + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of HTTPRoute + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind HTTPRoute + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-networking-gateway-v1-HTTPRouteList[`HTTPRouteList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a HTTPRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 201 - Created +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 202 - Accepted +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/httproutes/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the HTTPRoute +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a HTTPRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified HTTPRoute + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified HTTPRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified HTTPRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 201 - Created +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/httproutes/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the HTTPRoute +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified HTTPRoute + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified HTTPRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified HTTPRoute + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 201 - Created +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`HTTPRoute`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc b/rest_api/network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc new file mode 100644 index 0000000000..3ddaf5568e --- /dev/null +++ b/rest_api/network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc @@ -0,0 +1,463 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ipamclaim-k8s-cni-cncf-io-v1alpha1"] += IPAMClaim [k8s.cni.cncf.io/v1alpha1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +IPAMClaim is the Schema for the IPAMClaim API +-- + +Type:: + `object` + + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| + +| `status` +| `object` +| + +|=== +=== .spec +Description:: ++ +-- + +-- + +Type:: + `object` + +Required:: + - `interface` + - `network` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `interface` +| `string` +| The pod interface name for which this allocation was created + +| `network` +| `string` +| The network name for which this persistent allocation was created + +|=== +=== .status +Description:: ++ +-- + +-- + +Type:: + `object` + +Required:: + - `ips` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `ips` +| `array (string)` +| The list of IP addresses (v4, v6) that were allocated for the pod interface + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/k8s.cni.cncf.io/v1alpha1/ipamclaims` +- `GET`: list objects of kind IPAMClaim +* `/apis/k8s.cni.cncf.io/v1alpha1/namespaces/{namespace}/ipamclaims` +- `DELETE`: delete collection of IPAMClaim +- `GET`: list objects of kind IPAMClaim +- `POST`: create an IPAMClaim +* `/apis/k8s.cni.cncf.io/v1alpha1/namespaces/{namespace}/ipamclaims/{name}` +- `DELETE`: delete an IPAMClaim +- `GET`: read the specified IPAMClaim +- `PATCH`: partially update the specified IPAMClaim +- `PUT`: replace the specified IPAMClaim +* `/apis/k8s.cni.cncf.io/v1alpha1/namespaces/{namespace}/ipamclaims/{name}/status` +- `GET`: read status of the specified IPAMClaim +- `PATCH`: partially update status of the specified IPAMClaim +- `PUT`: replace status of the specified IPAMClaim + + +=== /apis/k8s.cni.cncf.io/v1alpha1/ipamclaims + + + +HTTP method:: + `GET` + +Description:: + list objects of kind IPAMClaim + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-cncf-cni-k8s-v1alpha1-IPAMClaimList[`IPAMClaimList`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/k8s.cni.cncf.io/v1alpha1/namespaces/{namespace}/ipamclaims + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of IPAMClaim + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind IPAMClaim + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-cncf-cni-k8s-v1alpha1-IPAMClaimList[`IPAMClaimList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create an IPAMClaim + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 201 - Created +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 202 - Accepted +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/k8s.cni.cncf.io/v1alpha1/namespaces/{namespace}/ipamclaims/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the IPAMClaim +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete an IPAMClaim + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified IPAMClaim + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified IPAMClaim + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified IPAMClaim + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 201 - Created +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/k8s.cni.cncf.io/v1alpha1/namespaces/{namespace}/ipamclaims/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the IPAMClaim +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified IPAMClaim + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified IPAMClaim + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified IPAMClaim + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 201 - Created +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`IPAMClaim`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/network_apis/multinetworkpolicy-k8s-cni-cncf-io-v1beta1.adoc b/rest_api/network_apis/multinetworkpolicy-k8s-cni-cncf-io-v1beta1.adoc index b78d950dac..f1e36a4053 100644 --- a/rest_api/network_apis/multinetworkpolicy-k8s-cni-cncf-io-v1beta1.adoc +++ b/rest_api/network_apis/multinetworkpolicy-k8s-cni-cncf-io-v1beta1.adoc @@ -164,6 +164,10 @@ Type:: |=== | Property | Type | Description +| `endPort` +| `integer` +| If set, indicates that the range of ports from port to endPort, inclusive, should be allowed by the policy. This field cannot be defined if the port field is not defined or if the port field is defined as a named (string) port. The endPort must be equal or greater than port. + | `port` | `integer-or-string` | The port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. @@ -704,6 +708,10 @@ Type:: |=== | Property | Type | Description +| `endPort` +| `integer` +| If set, indicates that the range of ports from port to endPort, inclusive, should be allowed by the policy. This field cannot be defined if the port field is not defined or if the port field is defined as a named (string) port. The endPort must be equal or greater than port. + | `port` | `integer-or-string` | The port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. diff --git a/rest_api/network_apis/network-apis-index.adoc b/rest_api/network_apis/network-apis-index.adoc index 5561b64ab1..137349ca85 100644 --- a/rest_api/network_apis/network-apis-index.adoc +++ b/rest_api/network_apis/network-apis-index.adoc @@ -7,6 +7,17 @@ toc::[] +== ClusterUserDefinedNetwork [k8s.ovn.org/v1] + +Description:: ++ +-- +ClusterUserDefinedNetwork describe network request for a shared network across namespaces. +-- + +Type:: + `object` + == AdminNetworkPolicy [policy.networking.k8s.io/v1alpha1] Description:: @@ -110,7 +121,12 @@ Type:: Description:: + -- -EgressService is a CRD that allows the user to request that the source IP of egress packets originating from all of the pods that are endpoints of the corresponding LoadBalancer Service would be its ingress IP. In addition, it allows the user to request that egress packets originating from all of the pods that are endpoints of the LoadBalancer service would use a different network than the main one. +EgressService is a CRD that allows the user to request that the source +IP of egress packets originating from all of the pods that are endpoints +of the corresponding LoadBalancer Service would be its ingress IP. +In addition, it allows the user to request that egress packets originating from +all of the pods that are endpoints of the LoadBalancer service would use a different +network than the main one. -- Type:: @@ -171,6 +187,96 @@ Compatibility level 1: Stable within a major release for a minimum of 12 months EgressRouter is a single egressrouter pod configuration object. -- +Type:: + `object` + +== GRPCRoute [gateway.networking.k8s.io/v1] + +Description:: ++ +-- +GRPCRoute provides a way to route gRPC requests. This includes the capability +to match requests by hostname, gRPC service, gRPC method, or HTTP/2 header. +Filters can be used to specify additional processing steps. Backends specify +where matching requests will be routed. + +GRPCRoute falls under extended support within the Gateway API. Within the +following specification, the word "MUST" indicates that an implementation +supporting GRPCRoute must conform to the indicated requirement, but an +implementation not supporting this route type need not follow the requirement +unless explicitly indicated. + +Implementations supporting `GRPCRoute` with the `HTTPS` `ProtocolType` MUST +accept HTTP/2 connections without an initial upgrade from HTTP/1.1, i.e. via +ALPN. If the implementation does not support this, then it MUST set the +"Accepted" condition to "False" for the affected listener with a reason of +"UnsupportedProtocol". Implementations MAY also accept HTTP/2 connections +with an upgrade from HTTP/1. + +Implementations supporting `GRPCRoute` with the `HTTP` `ProtocolType` MUST +support HTTP/2 over cleartext TCP (h2c, +https://www.rfc-editor.org/rfc/rfc7540#section-3.1) without an initial +upgrade from HTTP/1.1, i.e. with prior knowledge +(https://www.rfc-editor.org/rfc/rfc7540#section-3.4). If the implementation +does not support this, then it MUST set the "Accepted" condition to "False" +for the affected listener with a reason of "UnsupportedProtocol". +Implementations MAY also accept HTTP/2 connections with an upgrade from +HTTP/1, i.e. without prior knowledge. +-- + +Type:: + `object` + +== Gateway [gateway.networking.k8s.io/v1] + +Description:: ++ +-- +Gateway represents an instance of a service-traffic handling infrastructure +by binding Listeners to a set of IP addresses. +-- + +Type:: + `object` + +== GatewayClass [gateway.networking.k8s.io/v1] + +Description:: ++ +-- +GatewayClass describes a class of Gateways available to the user for creating +Gateway resources. + +It is recommended that this resource be used as a template for Gateways. This +means that a Gateway is based on the state of the GatewayClass at the time it +was created and changes to the GatewayClass or associated parameters are not +propagated down to existing Gateways. This recommendation is intended to +limit the blast radius of changes to GatewayClass or associated parameters. +If implementations choose to propagate GatewayClass changes to existing +Gateways, that MUST be clearly documented by the implementation. + +Whenever one or more Gateways are using a GatewayClass, implementations SHOULD +add the `gateway-exists-finalizer.gateway.networking.k8s.io` finalizer on the +associated GatewayClass. This ensures that a GatewayClass associated with a +Gateway is not deleted while in use. + +GatewayClass is a Cluster level resource. +-- + +Type:: + `object` + +== HTTPRoute [gateway.networking.k8s.io/v1] + +Description:: ++ +-- +HTTPRoute provides a way to route HTTP requests. This includes the capability +to match requests by hostname, path, header, or query param. Filters can be +used to specify additional processing steps. Backends specify where matching +requests should be routed. +-- + Type:: `object` @@ -193,6 +299,17 @@ Description:: IngressClass represents the class of the Ingress, referenced by the Ingress Spec. The `ingressclass.kubernetes.io/is-default-class` annotation can be used to indicate that an IngressClass should be considered default. When a single IngressClass resource has this annotation set to true, new Ingress resources without a class specified will be assigned this default class. -- +Type:: + `object` + +== IPAMClaim [k8s.cni.cncf.io/v1alpha1] + +Description:: ++ +-- +IPAMClaim is the Schema for the IPAMClaim API +-- + Type:: `object` @@ -237,6 +354,17 @@ Description:: NetworkPolicy describes what network traffic is allowed for a set of Pods -- +Type:: + `object` + +== NodeSlicePool [whereabouts.cni.cncf.io/v1alpha1] + +Description:: ++ +-- +NodeSlicePool is the Schema for the nodesliceippools API +-- + Type:: `object` @@ -261,6 +389,32 @@ PodNetworkConnectivityCheck Compatibility level 4: No compatibility is provided, the API can change at any point for any reason. These capabilities should not be used by applications needing long term support. -- +Type:: + `object` + +== ReferenceGrant [gateway.networking.k8s.io/v1beta1] + +Description:: ++ +-- +ReferenceGrant identifies kinds of resources in other namespaces that are +trusted to reference the specified kinds of resources in the same namespace +as the policy. + +Each ReferenceGrant can be used to represent a unique trust relationship. +Additional Reference Grants can be used to add to the set of trusted +sources of inbound references for the namespace they are defined within. + +All cross-namespace references in Gateway API (with the exception of cross-namespace +Gateway-route attachment) require a ReferenceGrant. + +ReferenceGrant is a form of runtime verification allowing users to assert +which cross-namespace object references are permitted. Implementations that +support ReferenceGrant MUST NOT permit cross-namespace references which have +no grant, and MUST respond to the removal of a grant by revoking the access +that the grant allowed. +-- + Type:: `object` @@ -296,3 +450,14 @@ Service is a named abstraction of software service (for example, mysql) consisti Type:: `object` +== UserDefinedNetwork [k8s.ovn.org/v1] + +Description:: ++ +-- +UserDefinedNetwork describe network request for a Namespace. +-- + +Type:: + `object` + diff --git a/rest_api/network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc b/rest_api/network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc new file mode 100644 index 0000000000..dab5fd6dee --- /dev/null +++ b/rest_api/network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc @@ -0,0 +1,404 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="nodeslicepool-whereabouts-cni-cncf-io-v1alpha1"] += NodeSlicePool [whereabouts.cni.cncf.io/v1alpha1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +NodeSlicePool is the Schema for the nodesliceippools API +-- + +Type:: + `object` + + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| NodeSlicePoolSpec defines the desired state of NodeSlicePool + +| `status` +| `object` +| NodeSlicePoolStatus defines the desired state of NodeSlicePool + +|=== +=== .spec +Description:: ++ +-- +NodeSlicePoolSpec defines the desired state of NodeSlicePool +-- + +Type:: + `object` + +Required:: + - `range` + - `sliceSize` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `range` +| `string` +| Range is a RFC 4632/4291-style string that represents an IP address and prefix length in CIDR notation +this refers to the entire range where the node is allocated a subset + +| `sliceSize` +| `string` +| SliceSize is the size of subnets or slices of the range that each node will be assigned + +|=== +=== .status +Description:: ++ +-- +NodeSlicePoolStatus defines the desired state of NodeSlicePool +-- + +Type:: + `object` + +Required:: + - `allocations` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `allocations` +| `array` +| Allocations holds the allocations of nodes to slices + +| `allocations[]` +| `object` +| + +|=== +=== .status.allocations +Description:: ++ +-- +Allocations holds the allocations of nodes to slices +-- + +Type:: + `array` + + + + +=== .status.allocations[] +Description:: ++ +-- + +-- + +Type:: + `object` + +Required:: + - `nodeName` + - `sliceRange` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `nodeName` +| `string` +| NodeName is the name of the node assigned to this slice, empty node name is an available slice for assignment + +| `sliceRange` +| `string` +| SliceRange is the subnet of this slice + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/whereabouts.cni.cncf.io/v1alpha1/nodeslicepools` +- `GET`: list objects of kind NodeSlicePool +* `/apis/whereabouts.cni.cncf.io/v1alpha1/namespaces/{namespace}/nodeslicepools` +- `DELETE`: delete collection of NodeSlicePool +- `GET`: list objects of kind NodeSlicePool +- `POST`: create a NodeSlicePool +* `/apis/whereabouts.cni.cncf.io/v1alpha1/namespaces/{namespace}/nodeslicepools/{name}` +- `DELETE`: delete a NodeSlicePool +- `GET`: read the specified NodeSlicePool +- `PATCH`: partially update the specified NodeSlicePool +- `PUT`: replace the specified NodeSlicePool + + +=== /apis/whereabouts.cni.cncf.io/v1alpha1/nodeslicepools + + + +HTTP method:: + `GET` + +Description:: + list objects of kind NodeSlicePool + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-cncf-cni-whereabouts-v1alpha1-NodeSlicePoolList[`NodeSlicePoolList`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/whereabouts.cni.cncf.io/v1alpha1/namespaces/{namespace}/nodeslicepools + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of NodeSlicePool + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind NodeSlicePool + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-cncf-cni-whereabouts-v1alpha1-NodeSlicePoolList[`NodeSlicePoolList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a NodeSlicePool + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[`NodeSlicePool`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[`NodeSlicePool`] schema +| 201 - Created +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[`NodeSlicePool`] schema +| 202 - Accepted +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[`NodeSlicePool`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/whereabouts.cni.cncf.io/v1alpha1/namespaces/{namespace}/nodeslicepools/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the NodeSlicePool +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a NodeSlicePool + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified NodeSlicePool + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[`NodeSlicePool`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified NodeSlicePool + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[`NodeSlicePool`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified NodeSlicePool + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[`NodeSlicePool`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[`NodeSlicePool`] schema +| 201 - Created +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[`NodeSlicePool`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc b/rest_api/network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc index 6ab72cacae..5921c1add2 100644 --- a/rest_api/network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc +++ b/rest_api/network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc @@ -43,18 +43,18 @@ Required:: | `spec` | `object` -| Spec defines the source and target of the connectivity check +| spec defines the source and target of the connectivity check | `status` | `object` -| Status contains the observed status of the connectivity check +| status contains the observed status of the connectivity check |=== === .spec Description:: + -- -Spec defines the source and target of the connectivity check +spec defines the source and target of the connectivity check -- Type:: @@ -72,7 +72,7 @@ Required:: | `sourcePod` | `string` -| SourcePod names the pod from which the condition will be checked +| sourcePod names the pod from which the condition will be checked | `targetEndpoint` | `string` @@ -121,7 +121,7 @@ Required:: Description:: + -- -Status contains the observed status of the connectivity check +status contains the observed status of the connectivity check -- Type:: @@ -136,7 +136,7 @@ Type:: | `conditions` | `array` -| Conditions summarize the status of the check +| conditions summarize the status of the check | `conditions[]` | `object` @@ -144,7 +144,7 @@ Type:: | `failures` | `array` -| Failures contains logs of unsuccessful check actions +| failures contains logs of unsuccessful check actions | `failures[]` | `object` @@ -152,7 +152,7 @@ Type:: | `outages` | `array` -| Outages contains logs of time periods of outages +| outages contains logs of time periods of outages | `outages[]` | `object` @@ -160,7 +160,7 @@ Type:: | `successes` | `array` -| Successes contains logs successful check actions +| successes contains logs successful check actions | `successes[]` | `object` @@ -171,7 +171,7 @@ Type:: Description:: + -- -Conditions summarize the status of the check +conditions summarize the status of the check -- Type:: @@ -206,26 +206,26 @@ Required:: | `message` | `string` -| Message indicating details about last transition in a human readable format. +| message indicating details about last transition in a human readable format. | `reason` | `string` -| Reason for the condition's last status transition in a machine readable format. +| reason for the condition's last status transition in a machine readable format. | `status` | `string` -| Status of the condition +| status of the condition | `type` | `string` -| Type of the condition +| type of the condition |=== === .status.failures Description:: + -- -Failures contains logs of unsuccessful check actions +failures contains logs of unsuccessful check actions -- Type:: @@ -255,19 +255,19 @@ Required:: | `latency` | `` -| Latency records how long the action mentioned in the entry took. +| latency records how long the action mentioned in the entry took. | `message` | `string` -| Message explaining status in a human readable format. +| message explaining status in a human readable format. | `reason` | `string` -| Reason for status in a machine readable format. +| reason for status in a machine readable format. | `success` | `boolean` -| Success indicates if the log entry indicates a success or failure. +| success indicates if the log entry indicates a success or failure. | `time` | `` @@ -278,7 +278,7 @@ Required:: Description:: + -- -Outages contains logs of time periods of outages +outages contains logs of time periods of outages -- Type:: @@ -306,11 +306,11 @@ Type:: | `end` | `` -| End of outage detected +| end of outage detected | `endLogs` | `array` -| EndLogs contains log entries related to the end of this outage. Should contain the success +| endLogs contains log entries related to the end of this outage. Should contain the success entry that resolved the outage and possibly a few of the failure log entries that preceded it. | `endLogs[]` @@ -319,15 +319,15 @@ entry that resolved the outage and possibly a few of the failure log entries tha | `message` | `string` -| Message summarizes outage details in a human readable format. +| message summarizes outage details in a human readable format. | `start` | `` -| Start of outage detected +| start of outage detected | `startLogs` | `array` -| StartLogs contains log entries related to the start of this outage. Should contain +| startLogs contains log entries related to the start of this outage. Should contain the original failure, any entries where the failure mode changed. | `startLogs[]` @@ -339,7 +339,7 @@ the original failure, any entries where the failure mode changed. Description:: + -- -EndLogs contains log entries related to the end of this outage. Should contain the success +endLogs contains log entries related to the end of this outage. Should contain the success entry that resolved the outage and possibly a few of the failure log entries that preceded it. -- @@ -370,19 +370,19 @@ Required:: | `latency` | `` -| Latency records how long the action mentioned in the entry took. +| latency records how long the action mentioned in the entry took. | `message` | `string` -| Message explaining status in a human readable format. +| message explaining status in a human readable format. | `reason` | `string` -| Reason for status in a machine readable format. +| reason for status in a machine readable format. | `success` | `boolean` -| Success indicates if the log entry indicates a success or failure. +| success indicates if the log entry indicates a success or failure. | `time` | `` @@ -393,7 +393,7 @@ Required:: Description:: + -- -StartLogs contains log entries related to the start of this outage. Should contain +startLogs contains log entries related to the start of this outage. Should contain the original failure, any entries where the failure mode changed. -- @@ -424,19 +424,19 @@ Required:: | `latency` | `` -| Latency records how long the action mentioned in the entry took. +| latency records how long the action mentioned in the entry took. | `message` | `string` -| Message explaining status in a human readable format. +| message explaining status in a human readable format. | `reason` | `string` -| Reason for status in a machine readable format. +| reason for status in a machine readable format. | `success` | `boolean` -| Success indicates if the log entry indicates a success or failure. +| success indicates if the log entry indicates a success or failure. | `time` | `` @@ -447,7 +447,7 @@ Required:: Description:: + -- -Successes contains logs successful check actions +successes contains logs successful check actions -- Type:: @@ -477,19 +477,19 @@ Required:: | `latency` | `` -| Latency records how long the action mentioned in the entry took. +| latency records how long the action mentioned in the entry took. | `message` | `string` -| Message explaining status in a human readable format. +| message explaining status in a human readable format. | `reason` | `string` -| Reason for status in a machine readable format. +| reason for status in a machine readable format. | `success` | `boolean` -| Success indicates if the log entry indicates a success or failure. +| success indicates if the log entry indicates a success or failure. | `time` | `` diff --git a/rest_api/network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc b/rest_api/network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc new file mode 100644 index 0000000000..e570d653aa --- /dev/null +++ b/rest_api/network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc @@ -0,0 +1,496 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="referencegrant-gateway-networking-k8s-io-v1beta1"] += ReferenceGrant [gateway.networking.k8s.io/v1beta1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +ReferenceGrant identifies kinds of resources in other namespaces that are +trusted to reference the specified kinds of resources in the same namespace +as the policy. + +Each ReferenceGrant can be used to represent a unique trust relationship. +Additional Reference Grants can be used to add to the set of trusted +sources of inbound references for the namespace they are defined within. + +All cross-namespace references in Gateway API (with the exception of cross-namespace +Gateway-route attachment) require a ReferenceGrant. + +ReferenceGrant is a form of runtime verification allowing users to assert +which cross-namespace object references are permitted. Implementations that +support ReferenceGrant MUST NOT permit cross-namespace references which have +no grant, and MUST respond to the removal of a grant by revoking the access +that the grant allowed. +-- + +Type:: + `object` + + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| Spec defines the desired state of ReferenceGrant. + +|=== +=== .spec +Description:: ++ +-- +Spec defines the desired state of ReferenceGrant. +-- + +Type:: + `object` + +Required:: + - `from` + - `to` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `from` +| `array` +| From describes the trusted namespaces and kinds that can reference the +resources described in "To". Each entry in this list MUST be considered +to be an additional place that references can be valid from, or to put +this another way, entries MUST be combined using OR. + +Support: Core + +| `from[]` +| `object` +| ReferenceGrantFrom describes trusted namespaces and kinds. + +| `to` +| `array` +| To describes the resources that may be referenced by the resources +described in "From". Each entry in this list MUST be considered to be an +additional place that references can be valid to, or to put this another +way, entries MUST be combined using OR. + +Support: Core + +| `to[]` +| `object` +| ReferenceGrantTo describes what Kinds are allowed as targets of the +references. + +|=== +=== .spec.from +Description:: ++ +-- +From describes the trusted namespaces and kinds that can reference the +resources described in "To". Each entry in this list MUST be considered +to be an additional place that references can be valid from, or to put +this another way, entries MUST be combined using OR. + +Support: Core +-- + +Type:: + `array` + + + + +=== .spec.from[] +Description:: ++ +-- +ReferenceGrantFrom describes trusted namespaces and kinds. +-- + +Type:: + `object` + +Required:: + - `group` + - `kind` + - `namespace` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. +When empty, the Kubernetes core API group is inferred. + +Support: Core + +| `kind` +| `string` +| Kind is the kind of the referent. Although implementations may support +additional resources, the following types are part of the "Core" +support level for this field. + +When used to permit a SecretObjectReference: + +* Gateway + +When used to permit a BackendObjectReference: + +* GRPCRoute +* HTTPRoute +* TCPRoute +* TLSRoute +* UDPRoute + +| `namespace` +| `string` +| Namespace is the namespace of the referent. + +Support: Core + +|=== +=== .spec.to +Description:: ++ +-- +To describes the resources that may be referenced by the resources +described in "From". Each entry in this list MUST be considered to be an +additional place that references can be valid to, or to put this another +way, entries MUST be combined using OR. + +Support: Core +-- + +Type:: + `array` + + + + +=== .spec.to[] +Description:: ++ +-- +ReferenceGrantTo describes what Kinds are allowed as targets of the +references. +-- + +Type:: + `object` + +Required:: + - `group` + - `kind` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| Group is the group of the referent. +When empty, the Kubernetes core API group is inferred. + +Support: Core + +| `kind` +| `string` +| Kind is the kind of the referent. Although implementations may support +additional resources, the following types are part of the "Core" +support level for this field: + +* Secret when used to permit a SecretObjectReference +* Service when used to permit a BackendObjectReference + +| `name` +| `string` +| Name is the name of the referent. When unspecified, this policy +refers to all resources of the specified Group and Kind in the local +namespace. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/gateway.networking.k8s.io/v1beta1/referencegrants` +- `GET`: list objects of kind ReferenceGrant +* `/apis/gateway.networking.k8s.io/v1beta1/namespaces/{namespace}/referencegrants` +- `DELETE`: delete collection of ReferenceGrant +- `GET`: list objects of kind ReferenceGrant +- `POST`: create a ReferenceGrant +* `/apis/gateway.networking.k8s.io/v1beta1/namespaces/{namespace}/referencegrants/{name}` +- `DELETE`: delete a ReferenceGrant +- `GET`: read the specified ReferenceGrant +- `PATCH`: partially update the specified ReferenceGrant +- `PUT`: replace the specified ReferenceGrant + + +=== /apis/gateway.networking.k8s.io/v1beta1/referencegrants + + + +HTTP method:: + `GET` + +Description:: + list objects of kind ReferenceGrant + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-networking-gateway-v1beta1-ReferenceGrantList[`ReferenceGrantList`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1beta1/namespaces/{namespace}/referencegrants + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of ReferenceGrant + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind ReferenceGrant + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-networking-gateway-v1beta1-ReferenceGrantList[`ReferenceGrantList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a ReferenceGrant + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[`ReferenceGrant`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[`ReferenceGrant`] schema +| 201 - Created +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[`ReferenceGrant`] schema +| 202 - Accepted +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[`ReferenceGrant`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/gateway.networking.k8s.io/v1beta1/namespaces/{namespace}/referencegrants/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ReferenceGrant +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a ReferenceGrant + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified ReferenceGrant + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[`ReferenceGrant`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified ReferenceGrant + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[`ReferenceGrant`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified ReferenceGrant + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[`ReferenceGrant`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[`ReferenceGrant`] schema +| 201 - Created +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[`ReferenceGrant`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/network_apis/service-v1.adoc b/rest_api/network_apis/service-v1.adoc index 74767a588b..84d7d0a36a 100644 --- a/rest_api/network_apis/service-v1.adoc +++ b/rest_api/network_apis/service-v1.adoc @@ -162,7 +162,7 @@ Possible enum values: | `trafficDistribution` | `string` -| TrafficDistribution offers a way to express preferences for how traffic is distributed to Service endpoints. Implementations can use this field as a hint, but are not required to guarantee strict adherence. If the field is not set, the implementation will apply its default routing strategy. If set to "PreferClose", implementations should prioritize endpoints that are topologically close (e.g., same zone). This is an alpha field and requires enabling ServiceTrafficDistribution feature. +| TrafficDistribution offers a way to express preferences for how traffic is distributed to Service endpoints. Implementations can use this field as a hint, but are not required to guarantee strict adherence. If the field is not set, the implementation will apply its default routing strategy. If set to "PreferClose", implementations should prioritize endpoints that are topologically close (e.g., same zone). This is a beta field and requires enabling ServiceTrafficDistribution feature. | `type` | `string` @@ -390,7 +390,7 @@ Type:: | `ports[]` | `object` -| +| PortStatus represents the error condition of a service port |=== === .status.loadBalancer.ingress[].ports @@ -410,7 +410,7 @@ Type:: Description:: + -- - +PortStatus represents the error condition of a service port -- Type:: diff --git a/rest_api/network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc b/rest_api/network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc new file mode 100644 index 0000000000..ffffe17e2d --- /dev/null +++ b/rest_api/network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc @@ -0,0 +1,735 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="userdefinednetwork-k8s-ovn-org-v1"] += UserDefinedNetwork [k8s.ovn.org/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +UserDefinedNetwork describe network request for a Namespace. +-- + +Type:: + `object` + +Required:: + - `spec` + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| UserDefinedNetworkSpec defines the desired state of UserDefinedNetworkSpec. + +| `status` +| `object` +| UserDefinedNetworkStatus contains the observed status of the UserDefinedNetwork. + +|=== +=== .spec +Description:: ++ +-- +UserDefinedNetworkSpec defines the desired state of UserDefinedNetworkSpec. +-- + +Type:: + `object` + +Required:: + - `topology` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `layer2` +| `object` +| Layer2 is the Layer2 topology configuration. + +| `layer3` +| `object` +| Layer3 is the Layer3 topology configuration. + +| `topology` +| `string` +| Topology describes network configuration. + +Allowed values are "Layer3", "Layer2". +Layer3 topology creates a layer 2 segment per node, each with a different subnet. Layer 3 routing is used to interconnect node subnets. +Layer2 topology creates one logical switch shared by all nodes. + +|=== +=== .spec.layer2 +Description:: ++ +-- +Layer2 is the Layer2 topology configuration. +-- + +Type:: + `object` + +Required:: + - `role` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `ipam` +| `object` +| IPAM section contains IPAM-related configuration for the network. + +| `joinSubnets` +| `array (string)` +| JoinSubnets are used inside the OVN network topology. + +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. +This field is only allowed for "Primary" network. +It is not recommended to set this field without explicit need and understanding of the OVN network topology. +When omitted, the platform will choose a reasonable default which is subject to change over time. + +| `mtu` +| `integer` +| MTU is the maximum transmission unit for a network. +MTU is optional, if not provided, the globally configured value in OVN-Kubernetes (defaults to 1400) is used for the network. + +| `role` +| `string` +| Role describes the network role in the pod. + +Allowed value is "Secondary". +Secondary network is only assigned to pods that use `k8s.v1.cni.cncf.io/networks` annotation to select given network. + +| `subnets` +| `array (string)` +| Subnets are used for the pod network across the cluster. +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. + +The format should match standard CIDR notation (for example, "10.128.0.0/16"). +This field must be omitted if `ipam.mode` is `Disabled`. + +|=== +=== .spec.layer2.ipam +Description:: ++ +-- +IPAM section contains IPAM-related configuration for the network. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lifecycle` +| `string` +| Lifecycle controls IP addresses management lifecycle. + +The only allowed value is Persistent. When set, OVN Kubernetes assigned IP addresses will be persisted in an +`ipamclaims.k8s.cni.cncf.io` object. These IP addresses will be reused by other pods if requested. +Only supported when mode is `Enabled`. + +| `mode` +| `string` +| Mode controls how much of the IP configuration will be managed by OVN. +`Enabled` means OVN-Kubernetes will apply IP configuration to the SDN infrastructure and it will also assign IPs +from the selected subnet to the individual pods. +`Disabled` means OVN-Kubernetes will only assign MAC addresses and provide layer 2 communication, letting users +configure IP addresses for the pods. +`Disabled` is only available for Secondary networks. +By disabling IPAM, any Kubernetes features that rely on selecting pods by IP will no longer function +(such as network policy, services, etc). Additionally, IP port security will also be disabled for interfaces attached to this network. +Defaults to `Enabled`. + +|=== +=== .spec.layer3 +Description:: ++ +-- +Layer3 is the Layer3 topology configuration. +-- + +Type:: + `object` + +Required:: + - `role` + - `subnets` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `joinSubnets` +| `array (string)` +| JoinSubnets are used inside the OVN network topology. + +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. +This field is only allowed for "Primary" network. +It is not recommended to set this field without explicit need and understanding of the OVN network topology. +When omitted, the platform will choose a reasonable default which is subject to change over time. + +| `mtu` +| `integer` +| MTU is the maximum transmission unit for a network. + +MTU is optional, if not provided, the globally configured value in OVN-Kubernetes (defaults to 1400) is used for the network. + +| `role` +| `string` +| Role describes the network role in the pod. + +Allowed values are "Primary" and "Secondary". +Primary network is automatically assigned to every pod created in the same namespace. +Secondary network is only assigned to pods that use `k8s.v1.cni.cncf.io/networks` annotation to select given network. + +| `subnets` +| `array` +| Subnets are used for the pod network across the cluster. + +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. +Given subnet is split into smaller subnets for every node. + +| `subnets[]` +| `object` +| + +|=== +=== .spec.layer3.subnets +Description:: ++ +-- +Subnets are used for the pod network across the cluster. + +Dual-stack clusters may set 2 subnets (one for each IP family), otherwise only 1 subnet is allowed. +Given subnet is split into smaller subnets for every node. +-- + +Type:: + `array` + + + + +=== .spec.layer3.subnets[] +Description:: ++ +-- + +-- + +Type:: + `object` + +Required:: + - `cidr` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `cidr` +| `string` +| CIDR specifies L3Subnet, which is split into smaller subnets for every node. + +| `hostSubnet` +| `integer` +| HostSubnet specifies the subnet size for every node. + +When not set, it will be assigned automatically. + +|=== +=== .status +Description:: ++ +-- +UserDefinedNetworkStatus contains the observed status of the UserDefinedNetwork. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +|=== +=== .status.conditions +Description:: ++ +-- + +-- + +Type:: + `array` + + + + +=== .status.conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/k8s.ovn.org/v1/userdefinednetworks` +- `GET`: list objects of kind UserDefinedNetwork +* `/apis/k8s.ovn.org/v1/namespaces/{namespace}/userdefinednetworks` +- `DELETE`: delete collection of UserDefinedNetwork +- `GET`: list objects of kind UserDefinedNetwork +- `POST`: create an UserDefinedNetwork +* `/apis/k8s.ovn.org/v1/namespaces/{namespace}/userdefinednetworks/{name}` +- `DELETE`: delete an UserDefinedNetwork +- `GET`: read the specified UserDefinedNetwork +- `PATCH`: partially update the specified UserDefinedNetwork +- `PUT`: replace the specified UserDefinedNetwork +* `/apis/k8s.ovn.org/v1/namespaces/{namespace}/userdefinednetworks/{name}/status` +- `GET`: read status of the specified UserDefinedNetwork +- `PATCH`: partially update status of the specified UserDefinedNetwork +- `PUT`: replace status of the specified UserDefinedNetwork + + +=== /apis/k8s.ovn.org/v1/userdefinednetworks + + + +HTTP method:: + `GET` + +Description:: + list objects of kind UserDefinedNetwork + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#org-ovn-k8s-v1-UserDefinedNetworkList[`UserDefinedNetworkList`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/k8s.ovn.org/v1/namespaces/{namespace}/userdefinednetworks + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of UserDefinedNetwork + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind UserDefinedNetwork + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#org-ovn-k8s-v1-UserDefinedNetworkList[`UserDefinedNetworkList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create an UserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 201 - Created +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 202 - Accepted +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/k8s.ovn.org/v1/namespaces/{namespace}/userdefinednetworks/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the UserDefinedNetwork +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete an UserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified UserDefinedNetwork + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified UserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified UserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 201 - Created +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/k8s.ovn.org/v1/namespaces/{namespace}/userdefinednetworks/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the UserDefinedNetwork +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified UserDefinedNetwork + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified UserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified UserDefinedNetwork + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 201 - Created +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`UserDefinedNetwork`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/node_apis/node-v1.adoc b/rest_api/node_apis/node-v1.adoc index 4a9c01c63d..5631682e76 100644 --- a/rest_api/node_apis/node-v1.adoc +++ b/rest_api/node_apis/node-v1.adoc @@ -234,7 +234,7 @@ Type:: | `addresses` | `array` -| List of addresses reachable to the node. Queried from cloud provider, if available. More info: https://kubernetes.io/docs/concepts/nodes/node/#addresses Note: This field is declared as mergeable, but the merge key is not sufficiently unique, which can cause data corruption when it is merged. Callers should instead use a full-replacement patch. See https://pr.k8s.io/79391 for an example. Consumers should assume that addresses can change during the lifetime of a Node. However, there are some exceptions where this may not be possible, such as Pods that inherit a Node's address in its own status or consumers of the downward API (status.hostIP). +| List of addresses reachable to the node. Queried from cloud provider, if available. More info: https://kubernetes.io/docs/reference/node/node-status/#addresses Note: This field is declared as mergeable, but the merge key is not sufficiently unique, which can cause data corruption when it is merged. Callers should instead use a full-replacement patch. See https://pr.k8s.io/79391 for an example. Consumers should assume that addresses can change during the lifetime of a Node. However, there are some exceptions where this may not be possible, such as Pods that inherit a Node's address in its own status or consumers of the downward API (status.hostIP). | `addresses[]` | `object` @@ -250,7 +250,7 @@ Type:: | `conditions` | `array` -| Conditions is an array of current observed node conditions. More info: https://kubernetes.io/docs/concepts/nodes/node/#condition +| Conditions is an array of current observed node conditions. More info: https://kubernetes.io/docs/reference/node/node-status/#condition | `conditions[]` | `object` @@ -314,7 +314,7 @@ Possible enum values: Description:: + -- -List of addresses reachable to the node. Queried from cloud provider, if available. More info: https://kubernetes.io/docs/concepts/nodes/node/#addresses Note: This field is declared as mergeable, but the merge key is not sufficiently unique, which can cause data corruption when it is merged. Callers should instead use a full-replacement patch. See https://pr.k8s.io/79391 for an example. Consumers should assume that addresses can change during the lifetime of a Node. However, there are some exceptions where this may not be possible, such as Pods that inherit a Node's address in its own status or consumers of the downward API (status.hostIP). +List of addresses reachable to the node. Queried from cloud provider, if available. More info: https://kubernetes.io/docs/reference/node/node-status/#addresses Note: This field is declared as mergeable, but the merge key is not sufficiently unique, which can cause data corruption when it is merged. Callers should instead use a full-replacement patch. See https://pr.k8s.io/79391 for an example. Consumers should assume that addresses can change during the lifetime of a Node. However, there are some exceptions where this may not be possible, such as Pods that inherit a Node's address in its own status or consumers of the downward API (status.hostIP). -- Type:: @@ -356,7 +356,7 @@ Required:: Description:: + -- -Conditions is an array of current observed node conditions. More info: https://kubernetes.io/docs/concepts/nodes/node/#condition +Conditions is an array of current observed node conditions. More info: https://kubernetes.io/docs/reference/node/node-status/#condition -- Type:: diff --git a/rest_api/node_apis/performanceprofile-performance-openshift-io-v2.adoc b/rest_api/node_apis/performanceprofile-performance-openshift-io-v2.adoc index ede741d3f8..e21d2c42dc 100644 --- a/rest_api/node_apis/performanceprofile-performance-openshift-io-v2.adoc +++ b/rest_api/node_apis/performanceprofile-performance-openshift-io-v2.adoc @@ -94,6 +94,10 @@ For example, hugepages can be set with 1G and 2M, both values will be set on the It is important to notice that setting hugepages default size to 1G will remove all 2M related folders from the node and it will be impossible to configure 2M hugepages under the node. +| `kernelPageSize` +| `string` +| KernelPageSize defines the kernel page size. 4k is the default, 64k is only supported on aarch64 + | `machineConfigLabel` | `object (string)` | MachineConfigLabel defines the label to add to the MachineConfigs the operator creates. It has to be diff --git a/rest_api/node_apis/profile-tuned-openshift-io-v1.adoc b/rest_api/node_apis/profile-tuned-openshift-io-v1.adoc index 0f1b1951ce..2bb7232e27 100644 --- a/rest_api/node_apis/profile-tuned-openshift-io-v1.adoc +++ b/rest_api/node_apis/profile-tuned-openshift-io-v1.adoc @@ -209,7 +209,11 @@ Required:: | `conditions[]` | `object` -| ProfileStatusCondition represents a partial state of the per-node Profile application. +| StatusCondition represents a partial state of the per-node Profile application. + +| `observedGeneration` +| `integer` +| If set, this represents the .metadata.generation that the conditions were set based upon. | `tunedProfile` | `string` @@ -233,7 +237,7 @@ Type:: Description:: + -- -ProfileStatusCondition represents a partial state of the per-node Profile application. +StatusCondition represents a partial state of the per-node Profile application. -- Type:: diff --git a/rest_api/node_apis/tuned-tuned-openshift-io-v1.adoc b/rest_api/node_apis/tuned-tuned-openshift-io-v1.adoc index 3f894f211c..0f576a8417 100644 --- a/rest_api/node_apis/tuned-tuned-openshift-io-v1.adoc +++ b/rest_api/node_apis/tuned-tuned-openshift-io-v1.adoc @@ -312,6 +312,75 @@ Type:: +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| conditions represents the state of the Tuned profile + +| `conditions[]` +| `object` +| StatusCondition represents a partial state of the per-node Profile application. + +|=== +=== .status.conditions +Description:: ++ +-- +conditions represents the state of the Tuned profile +-- + +Type:: + `array` + + + + +=== .status.conditions[] +Description:: ++ +-- +StatusCondition represents a partial state of the per-node Profile application. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the time of the last update to the current status property. + +| `message` +| `string` +| message provides additional information about the current condition. +This is only to be consumed by humans. + +| `reason` +| `string` +| reason is the CamelCase reason for the condition's current status. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type specifies the aspect reported by this condition. + +|=== == API endpoints @@ -328,6 +397,10 @@ The following API endpoints are available: - `GET`: read the specified Tuned - `PATCH`: partially update the specified Tuned - `PUT`: replace the specified Tuned +* `/apis/tuned.openshift.io/v1/namespaces/{namespace}/tuneds/{name}/status` +- `GET`: read status of the specified Tuned +- `PATCH`: partially update status of the specified Tuned +- `PUT`: replace status of the specified Tuned === /apis/tuned.openshift.io/v1/tuneds @@ -568,3 +641,105 @@ Description:: |=== +=== /apis/tuned.openshift.io/v1/namespaces/{namespace}/tuneds/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the Tuned +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified Tuned + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified Tuned + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified Tuned + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned`] schema +| 201 - Created +| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/objects/index.adoc b/rest_api/objects/index.adoc index abba6dbb08..1927e04aa7 100644 --- a/rest_api/objects/index.adoc +++ b/rest_api/objects/index.adoc @@ -1339,7 +1339,7 @@ Required:: | `items` | xref:../oauth_apis/useroauthaccesstoken-oauth-openshift-io-v1.adoc#useroauthaccesstoken-oauth-openshift-io-v1[`array (UserOAuthAccessToken)`] -| +| | `kind` | `string` @@ -1818,12 +1818,12 @@ Type:: | Property | Type | Description | `owned` -| `array (APIServiceDescription)` -| +| xref:../objects/index.adoc#com-github-operator-framework-api-pkg-operators-v1alpha1-APIServiceDescription[`array (APIServiceDescription)`] +| | `required` -| `array (APIServiceDescription)` -| +| xref:../objects/index.adoc#com-github-operator-framework-api-pkg-operators-v1alpha1-APIServiceDescription[`array (APIServiceDescription)`] +| |=== @@ -1851,12 +1851,12 @@ Type:: | Property | Type | Description | `owned` -| `array (CRDDescription)` -| +| xref:../objects/index.adoc#com-github-operator-framework-api-pkg-operators-v1alpha1-CRDDescription[`array (CRDDescription)`] +| | `required` -| `array (CRDDescription)` -| +| xref:../objects/index.adoc#com-github-operator-framework-api-pkg-operators-v1alpha1-CRDDescription[`array (CRDDescription)`] +| |=== @@ -1886,11 +1886,11 @@ Required:: | `supported` | `boolean` -| +| | `type` | `string` -| +| |=== @@ -1923,7 +1923,7 @@ Required:: | `items` | xref:../operatorhub_apis/packagemanifest-packages-operators-coreos-com-v1.adoc#packagemanifest-packages-operators-coreos-com-v1[`array (PackageManifest)`] -| +| | `kind` | `string` @@ -1931,7 +1931,7 @@ Required:: | `metadata` | xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] -| +| |=== @@ -1976,6 +1976,47 @@ Required:: |=== +[id="io-cncf-cni-k8s-v1alpha1-IPAMClaimList"] +== io.cncf.cni.k8s.v1alpha1.IPAMClaimList schema + + +Description:: ++ +-- +IPAMClaimList is a list of IPAMClaim +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[`array (IPAMClaim)`] +| List of ipamclaims. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + [id="io-cncf-cni-k8s-v1beta1-MultiNetworkPolicyList"] == io.cncf.cni.k8s.v1beta1.MultiNetworkPolicyList schema @@ -2058,6 +2099,47 @@ Required:: |=== +[id="io-cncf-cni-whereabouts-v1alpha1-NodeSlicePoolList"] +== io.cncf.cni.whereabouts.v1alpha1.NodeSlicePoolList schema + + +Description:: ++ +-- +NodeSlicePoolList is a list of NodeSlicePool +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[`array (NodeSlicePool)`] +| List of nodeslicepools. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + [id="io-cncf-cni-whereabouts-v1alpha1-OverlappingRangeIPReservationList"] == io.cncf.cni.whereabouts.v1alpha1.OverlappingRangeIPReservationList schema @@ -2628,7 +2710,7 @@ Required:: | `metadata` | xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] -| +| |=== @@ -2783,7 +2865,7 @@ Type:: | defaultMode is optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. | `items` -| `array (KeyToPath)` +| xref:../objects/index.adoc#io-k8s-api-core-v1-KeyToPath[`array (KeyToPath)`] | items if unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. | `name` @@ -2828,7 +2910,7 @@ Required:: | fsType to mount. Ex. "ext4", "xfs", "ntfs". If not provided, the empty value is passed to the associated CSI driver which will determine the default filesystem to apply. | `nodePublishSecretRef` -| `LocalObjectReference` +| xref:../objects/index.adoc#io-k8s-api-core-v1-LocalObjectReference[`LocalObjectReference`] | nodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. | `readOnly` @@ -2914,7 +2996,7 @@ Required:: | Variable references $(VAR_NAME) are expanded using the previously defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. "$$(VAR_NAME)" will produce the string literal "$(VAR_NAME)". Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". | `valueFrom` -| `EnvVarSource` +| xref:../objects/index.adoc#io-k8s-api-core-v1-EnvVarSource[`EnvVarSource`] | Source for the environment variable's value. Cannot be used if value is not empty. |=== @@ -3059,8 +3141,8 @@ Type:: |=== -[id="io-k8s-api-core-v1-NamespaceCondition"] -== io.k8s.api.core.v1.NamespaceCondition schema +[id="io-k8s-api-core-v1-NamespaceCondition_v2"] +== io.k8s.api.core.v1.NamespaceCondition_v2 schema Description:: @@ -3085,15 +3167,15 @@ Required:: | `lastTransitionTime` | xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Time[`Time`] -| +| | `message` | `string` -| +| | `reason` | `string` -| +| | `status` | `string` @@ -3306,14 +3388,7 @@ Type:: | `dataSourceRef` | `object` -| dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn't specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn't set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef: * While dataSource only allows two specific types of objects, dataSourceRef - allows any non-core object, as well as PersistentVolumeClaim objects. -* While dataSource ignores disallowed values (dropping them), dataSourceRef - preserves all values, and generates an error if a disallowed value is - specified. -* While dataSource only allows local objects, dataSourceRef allows objects - in any namespaces. -(Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled. +| TypedObjectReference contains enough information to let you locate the typed referenced object | `resources` | `object` @@ -3380,14 +3455,7 @@ Required:: Description:: + -- -dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn't specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn't set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef: * While dataSource only allows two specific types of objects, dataSourceRef - allows any non-core object, as well as PersistentVolumeClaim objects. -* While dataSource ignores disallowed values (dropping them), dataSourceRef - preserves all values, and generates an error if a disallowed value is - specified. -* While dataSource only allows local objects, dataSourceRef allows objects - in any namespaces. -(Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled. +TypedObjectReference contains enough information to let you locate the typed referenced object -- Type:: @@ -3589,11 +3657,11 @@ Required:: | `status` | `string` -| +| Status is the status of the condition. Can be True, False, Unknown. More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=state%20of%20pvc-,conditions.status,-(string)%2C%20required | `type` | `string` -| +| Type is the type of the condition. More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=set%20to%20%27ResizeStarted%27.-,PersistentVolumeClaimCondition,-contains%20details%20about |=== ..status.modifyVolumeStatus @@ -3746,67 +3814,67 @@ Type:: | accessModes contains all ways the volume can be mounted. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes | `awsElasticBlockStore` -| `AWSElasticBlockStoreVolumeSource` -| awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore +| xref:../objects/index.adoc#io-k8s-api-core-v1-AWSElasticBlockStoreVolumeSource[`AWSElasticBlockStoreVolumeSource`] +| awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore | `azureDisk` -| `AzureDiskVolumeSource` -| azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +| xref:../objects/index.adoc#io-k8s-api-core-v1-AzureDiskVolumeSource[`AzureDiskVolumeSource`] +| azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type are redirected to the disk.csi.azure.com CSI driver. | `azureFile` -| `AzureFilePersistentVolumeSource` -| azureFile represents an Azure File Service mount on the host and bind mount to the pod. +| xref:../objects/index.adoc#io-k8s-api-core-v1-AzureFilePersistentVolumeSource[`AzureFilePersistentVolumeSource`] +| azureFile represents an Azure File Service mount on the host and bind mount to the pod. Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type are redirected to the file.csi.azure.com CSI driver. | `capacity` | xref:../objects/index.adoc#io-k8s-apimachinery-pkg-api-resource-Quantity[`object (Quantity)`] | capacity is the description of the persistent volume's resources and capacity. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#capacity | `cephfs` -| `CephFSPersistentVolumeSource` -| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +| xref:../objects/index.adoc#io-k8s-api-core-v1-CephFSPersistentVolumeSource[`CephFSPersistentVolumeSource`] +| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. | `cinder` -| `CinderPersistentVolumeSource` -| cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md +| xref:../objects/index.adoc#io-k8s-api-core-v1-CinderPersistentVolumeSource[`CinderPersistentVolumeSource`] +| cinder represents a cinder volume attached and mounted on kubelets host machine. Deprecated: Cinder is deprecated. All operations for the in-tree cinder type are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `claimRef` | xref:../objects/index.adoc#io-k8s-api-core-v1-ObjectReference[`ObjectReference`] | claimRef is part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound. claim.VolumeName is the authoritative bind between PV and PVC. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#binding | `csi` -| `CSIPersistentVolumeSource` -| csi represents storage that is handled by an external CSI driver (Beta feature). +| xref:../objects/index.adoc#io-k8s-api-core-v1-CSIPersistentVolumeSource[`CSIPersistentVolumeSource`] +| csi represents storage that is handled by an external CSI driver. | `fc` -| `FCVolumeSource` +| xref:../objects/index.adoc#io-k8s-api-core-v1-FCVolumeSource[`FCVolumeSource`] | fc represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. | `flexVolume` -| `FlexPersistentVolumeSource` -| flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +| xref:../objects/index.adoc#io-k8s-api-core-v1-FlexPersistentVolumeSource[`FlexPersistentVolumeSource`] +| flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. | `flocker` -| `FlockerVolumeSource` -| flocker represents a Flocker volume attached to a kubelet's host machine and exposed to the pod for its usage. This depends on the Flocker control service being running +| xref:../objects/index.adoc#io-k8s-api-core-v1-FlockerVolumeSource[`FlockerVolumeSource`] +| flocker represents a Flocker volume attached to a kubelet's host machine and exposed to the pod for its usage. This depends on the Flocker control service being running. Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. | `gcePersistentDisk` -| `GCEPersistentDiskVolumeSource` -| gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. Provisioned by an admin. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk +| xref:../objects/index.adoc#io-k8s-api-core-v1-GCEPersistentDiskVolumeSource[`GCEPersistentDiskVolumeSource`] +| gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. Provisioned by an admin. Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk | `glusterfs` -| `GlusterfsPersistentVolumeSource` -| glusterfs represents a Glusterfs volume that is attached to a host and exposed to the pod. Provisioned by an admin. More info: https://examples.k8s.io/volumes/glusterfs/README.md +| xref:../objects/index.adoc#io-k8s-api-core-v1-GlusterfsPersistentVolumeSource[`GlusterfsPersistentVolumeSource`] +| glusterfs represents a Glusterfs volume that is attached to a host and exposed to the pod. Provisioned by an admin. Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md | `hostPath` -| `HostPathVolumeSource` +| xref:../objects/index.adoc#io-k8s-api-core-v1-HostPathVolumeSource[`HostPathVolumeSource`] | hostPath represents a directory on the host. Provisioned by a developer or tester. This is useful for single-node development and testing only! On-host storage is not supported in any way and WILL NOT WORK in a multi-node cluster. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath | `iscsi` -| `ISCSIPersistentVolumeSource` +| xref:../objects/index.adoc#io-k8s-api-core-v1-ISCSIPersistentVolumeSource[`ISCSIPersistentVolumeSource`] | iscsi represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. Provisioned by an admin. | `local` -| `LocalVolumeSource` +| xref:../objects/index.adoc#io-k8s-api-core-v1-LocalVolumeSource[`LocalVolumeSource`] | local represents directly-attached storage with node affinity | `mountOptions` @@ -3814,11 +3882,11 @@ Type:: | mountOptions is the list of mount options, e.g. ["ro", "soft"]. Not validated - mount will simply fail if one is invalid. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#mount-options | `nfs` -| `NFSVolumeSource` +| xref:../objects/index.adoc#io-k8s-api-core-v1-NFSVolumeSource[`NFSVolumeSource`] | nfs represents an NFS mount on the host. Provisioned by an admin. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs | `nodeAffinity` -| `VolumeNodeAffinity` +| xref:../objects/index.adoc#io-k8s-api-core-v1-VolumeNodeAffinity[`VolumeNodeAffinity`] | nodeAffinity defines constraints that limit what nodes this volume can be accessed from. This field influences the scheduling of pods that use this volume. | `persistentVolumeReclaimPolicy` @@ -3831,32 +3899,32 @@ Possible enum values: - `"Retain"` means the volume will be left in its current phase (Released) for manual reclamation by the administrator. The default policy is Retain. | `photonPersistentDisk` -| `PhotonPersistentDiskVolumeSource` -| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +| xref:../objects/index.adoc#io-k8s-api-core-v1-PhotonPersistentDiskVolumeSource[`PhotonPersistentDiskVolumeSource`] +| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. | `portworxVolume` -| `PortworxVolumeSource` -| portworxVolume represents a portworx volume attached and mounted on kubelets host machine +| xref:../objects/index.adoc#io-k8s-api-core-v1-PortworxVolumeSource[`PortworxVolumeSource`] +| portworxVolume represents a portworx volume attached and mounted on kubelets host machine. Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate is on. | `quobyte` -| `QuobyteVolumeSource` -| quobyte represents a Quobyte mount on the host that shares a pod's lifetime +| xref:../objects/index.adoc#io-k8s-api-core-v1-QuobyteVolumeSource[`QuobyteVolumeSource`] +| quobyte represents a Quobyte mount on the host that shares a pod's lifetime. Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. | `rbd` -| `RBDPersistentVolumeSource` -| rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md +| xref:../objects/index.adoc#io-k8s-api-core-v1-RBDPersistentVolumeSource[`RBDPersistentVolumeSource`] +| rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md | `scaleIO` -| `ScaleIOPersistentVolumeSource` -| scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +| xref:../objects/index.adoc#io-k8s-api-core-v1-ScaleIOPersistentVolumeSource[`ScaleIOPersistentVolumeSource`] +| scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. | `storageClassName` | `string` | storageClassName is the name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass. | `storageos` -| `StorageOSPersistentVolumeSource` -| storageOS represents a StorageOS volume that is attached to the kubelet's host machine and mounted into the pod More info: https://examples.k8s.io/volumes/storageos/README.md +| xref:../objects/index.adoc#io-k8s-api-core-v1-StorageOSPersistentVolumeSource[`StorageOSPersistentVolumeSource`] +| storageOS represents a StorageOS volume that is attached to the kubelet's host machine and mounted into the pod. Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. More info: https://examples.k8s.io/volumes/storageos/README.md | `volumeAttributesClassName` | `string` @@ -3871,8 +3939,8 @@ Possible enum values: - `"Filesystem"` means the volume will be or is formatted with a filesystem. | `vsphereVolume` -| `VsphereVirtualDiskVolumeSource` -| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +| xref:../objects/index.adoc#io-k8s-api-core-v1-VsphereVirtualDiskVolumeSource[`VsphereVirtualDiskVolumeSource`] +| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type are redirected to the csi.vsphere.vmware.com CSI driver. |=== @@ -3984,7 +4052,7 @@ Type:: | Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata | `spec` -| `PodSpec` +| xref:../objects/index.adoc#io-k8s-api-core-v1-PodSpec[`PodSpec`] | Specification of the desired behavior of the pod. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status |=== @@ -4097,7 +4165,7 @@ Type:: | hard is the set of desired hard limits for each named resource. More info: https://kubernetes.io/docs/concepts/policy/resource-quotas/ | `scopeSelector` -| `ScopeSelector_v2` +| xref:../objects/index.adoc#io-k8s-api-core-v1-ScopeSelector_v2[`ScopeSelector_v2`] | scopeSelector is also a collection of filters like scopes that must match each object tracked by a quota but expressed using ScopeSelectorOperator in combination with possible values. For a resource to match, both scopes AND scopeSelector (if specified in spec), must be matched. | `scopes` @@ -4159,7 +4227,7 @@ Type:: | Property | Type | Description | `claims` -| `array (ResourceClaim)` +| xref:../objects/index.adoc#io-k8s-api-core-v1-ResourceClaim[`array (ResourceClaim)`] | Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. This is an alpha field and requires enabling the DynamicResourceAllocation feature gate. @@ -4296,7 +4364,7 @@ Type:: | defaultMode is Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. | `items` -| `array (KeyToPath)` +| xref:../objects/index.adoc#io-k8s-api-core-v1-KeyToPath[`array (KeyToPath)`] | items If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. | `optional` @@ -4465,7 +4533,7 @@ Type:: | Property | Type | Description | `matchLabelExpressions` -| `array (TopologySelectorLabelRequirement)` +| xref:../objects/index.adoc#io-k8s-api-core-v1-TopologySelectorLabelRequirement[`array (TopologySelectorLabelRequirement)`] | A list of topology selector requirements by labels. |=== @@ -4899,7 +4967,7 @@ Type:: | Property | Type | Description | `clusterRoleSelectors` -| `array (LabelSelector_v3)` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-LabelSelector_v3[`array (LabelSelector_v3)`] | ClusterRoleSelectors holds a list of selectors which will be used to find ClusterRoles and create the rules. If any of the selectors match, then the ClusterRole's permissions will be added |=== @@ -5378,153 +5446,153 @@ Type:: | `$ref` | `string` -| +| | `$schema` | `string` -| +| | `additionalItems` -| `` -| +| xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaPropsOrBool[``] +| | `additionalProperties` -| `` -| +| xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaPropsOrBool[``] +| | `allOf` | xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaProps[`array (undefined)`] -| +| | `anyOf` | xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaProps[`array (undefined)`] -| +| | `default` -| `JSON` +| xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSON[`JSON`] | default is a default value for undefined object fields. Defaulting is a beta feature under the CustomResourceDefaulting feature gate. Defaulting requires spec.preserveUnknownFields to be false. | `definitions` | xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaProps[`object (undefined)`] -| +| | `dependencies` -| `object (undefined)` -| +| xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaPropsOrStringArray[`object (undefined)`] +| | `description` | `string` -| +| | `enum` -| `array (JSON)` -| +| xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSON[`array (JSON)`] +| | `example` -| `JSON` -| +| xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSON[`JSON`] +| | `exclusiveMaximum` | `boolean` -| +| | `exclusiveMinimum` | `boolean` -| +| | `externalDocs` -| `ExternalDocumentation` -| +| xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-ExternalDocumentation[`ExternalDocumentation`] +| | `format` | `string` | format is an OpenAPI v3 format string. Unknown formats are ignored. The following formats are validated: -- bsonobjectid: a bson object ID, i.e. a 24 characters hex string - uri: an URI as parsed by Golang net/url.ParseRequestURI - email: an email address as parsed by Golang net/mail.ParseAddress - hostname: a valid representation for an Internet host name, as defined by RFC 1034, section 3.1 [RFC1034]. - ipv4: an IPv4 IP as parsed by Golang net.ParseIP - ipv6: an IPv6 IP as parsed by Golang net.ParseIP - cidr: a CIDR as parsed by Golang net.ParseCIDR - mac: a MAC address as parsed by Golang net.ParseMAC - uuid: an UUID that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$ - uuid3: an UUID3 that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?3[0-9a-f]{3}-?[0-9a-f]{4}-?[0-9a-f]{12}$ - uuid4: an UUID4 that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89ab][0-9a-f]{3}-?[0-9a-f]{12}$ - uuid5: an UUID5 that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?5[0-9a-f]{3}-?[89ab][0-9a-f]{3}-?[0-9a-f]{12}$ - isbn: an ISBN10 or ISBN13 number string like "0321751043" or "978-0321751041" - isbn10: an ISBN10 number string like "0321751043" - isbn13: an ISBN13 number string like "978-0321751041" - creditcard: a credit card number defined by the regex ^(?:4[0-9]{12}(?:[0-9]{3})?\|5[1-5][0-9]{14}\|6(?:011\|5[0-9][0-9])[0-9]{12}\|3[47][0-9]{13}\|3(?:0[0-5]\|[68][0-9])[0-9]{11}\|(?:2131\|1800\|35\d{3})\d{11})$ with any non digit characters mixed in - ssn: a U.S. social security number following the regex ^\d{3}[- ]?\d{2}[- ]?\d{4}$ - hexcolor: an hexadecimal color code like "#FFFFFF: following the regex ^#?([0-9a-fA-F]{3}\|[0-9a-fA-F]{6})$ - rgbcolor: an RGB color code like rgb like "rgb(255,255,2559" - byte: base64 encoded binary data - password: any kind of string - date: a date string like "2006-01-02" as defined by full-date in RFC3339 - duration: a duration string like "22 ns" as parsed by Golang time.ParseDuration or compatible with Scala duration format - datetime: a date time string like "2014-12-15T19:30:20.000Z" as defined by date-time in RFC3339. +- bsonobjectid: a bson object ID, i.e. a 24 characters hex string - uri: an URI as parsed by Golang net/url.ParseRequestURI - email: an email address as parsed by Golang net/mail.ParseAddress - hostname: a valid representation for an Internet host name, as defined by RFC 1034, section 3.1 [RFC1034]. - ipv4: an IPv4 IP as parsed by Golang net.ParseIP - ipv6: an IPv6 IP as parsed by Golang net.ParseIP - cidr: a CIDR as parsed by Golang net.ParseCIDR - mac: a MAC address as parsed by Golang net.ParseMAC - uuid: an UUID that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$ - uuid3: an UUID3 that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?3[0-9a-f]{3}-?[0-9a-f]{4}-?[0-9a-f]{12}$ - uuid4: an UUID4 that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89ab][0-9a-f]{3}-?[0-9a-f]{12}$ - uuid5: an UUID5 that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?5[0-9a-f]{3}-?[89ab][0-9a-f]{3}-?[0-9a-f]{12}$ - isbn: an ISBN10 or ISBN13 number string like "0321751043" or "978-0321751041" - isbn10: an ISBN10 number string like "0321751043" - isbn13: an ISBN13 number string like "978-0321751041" - creditcard: a credit card number defined by the regex ^(?:4[0-9]{12}(?:[0-9]{3})?\|5[1-5][0-9]{14}\|6(?:011\|5[0-9][0-9])[0-9]{12}\|3[47][0-9]{13}\|3(?:0[0-5]\|[68][0-9])[0-9]{11}\|(?:2131\|1800\|35\\d{3})\\d{11})$ with any non digit characters mixed in - ssn: a U.S. social security number following the regex ^\\d{3}[- ]?\\d{2}[- ]?\\d{4}$ - hexcolor: an hexadecimal color code like "#FFFFFF: following the regex ^#?([0-9a-fA-F]{3}\|[0-9a-fA-F]{6})$ - rgbcolor: an RGB color code like rgb like "rgb(255,255,2559" - byte: base64 encoded binary data - password: any kind of string - date: a date string like "2006-01-02" as defined by full-date in RFC3339 - duration: a duration string like "22 ns" as parsed by Golang time.ParseDuration or compatible with Scala duration format - datetime: a date time string like "2014-12-15T19:30:20.000Z" as defined by date-time in RFC3339. | `id` | `string` -| +| | `items` -| `` -| +| xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaPropsOrArray[``] +| | `maxItems` | `integer` -| +| | `maxLength` | `integer` -| +| | `maxProperties` | `integer` -| +| | `maximum` | `number` -| +| | `minItems` | `integer` -| +| | `minLength` | `integer` -| +| | `minProperties` | `integer` -| +| | `minimum` | `number` -| +| | `multipleOf` | `number` -| +| | `not` | xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaProps[``] -| +| | `nullable` | `boolean` -| +| | `oneOf` | xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaProps[`array (undefined)`] -| +| | `pattern` | `string` -| +| | `patternProperties` | xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaProps[`object (undefined)`] -| +| | `properties` | xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-JSONSchemaProps[`object (undefined)`] -| +| | `required` | `array (string)` -| +| | `title` | `string` -| +| | `type` | `string` -| +| | `uniqueItems` | `boolean` -| +| | `x-kubernetes-embedded-resource` | `boolean` @@ -5584,7 +5652,7 @@ Defaults to atomic for arrays. | x-kubernetes-preserve-unknown-fields stops the API server decoding step from pruning fields which are not specified in the validation schema. This affects fields recursively, but switches back to normal pruning behaviour if nested properties or additionalProperties are specified in the schema. This can either be true or undefined. False is forbidden. | `x-kubernetes-validations` -| `array (ValidationRule)` +| xref:../objects/index.adoc#io-k8s-apiextensions-apiserver-pkg-apis-apiextensions-v1-ValidationRule[`array (ValidationRule)`] | x-kubernetes-validations describes a list of validation rules written in the CEL expression language. |=== @@ -5612,7 +5680,7 @@ The serialization format is: (Note that 1024 = 1Ki but 1000 = 1k; I didn't choose the capitalization.) - ::= "e" \| "E" + ::= "e" \| "E" No matter which of the three exponent forms is used, no quantity may represent a number greater than 2^63-1 in magnitude, nor may it have more than 3 decimal places. Numbers larger or more precise will be capped or rounded up. (E.g.: 0.1m will rounded up to 1m.) This may be extended in the future if we require larger or smaller quantities. @@ -5726,6 +5794,10 @@ Type:: | `integer` | The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. +| `ignoreStoreReadErrorWithClusterBreakingPotential` +| `boolean` +| if set to true, it will trigger an unsafe deletion of the resource in case the normal deletion flow fails with a corrupt object error. A resource is considered corrupt if it can not be retrieved from the underlying storage successfully because of a) its data can not be transformed e.g. decryption failure, or b) it fails to decode into an object. NOTE: unsafe deletion ignores finalizer constraints, skips precondition checks, and removes the object from the storage. WARNING: This may potentially break the cluster if the workload associated with the resource being unsafe-deleted relies on normal deletion flow. Use only if you REALLY know what you are doing. The default value is false, and the user must opt in to enable it + | `kind` | `string` | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds @@ -5735,7 +5807,7 @@ Type:: | Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object's finalizers list. Either this field or PropagationPolicy may be set, but not both. | `preconditions` -| `Preconditions` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Preconditions[`Preconditions`] | Must be fulfilled before a deletion is carried out. If not possible, a 409 Conflict status will be returned. | `propagationPolicy` @@ -5824,15 +5896,15 @@ Required:: | `group` | `string` -| +| | `kind` | `string` -| +| | `version` | `string` -| +| |=== @@ -5889,7 +5961,7 @@ Type:: | Property | Type | Description | `matchExpressions` -| `array (LabelSelectorRequirement_v2)` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-LabelSelectorRequirement_v2[`array (LabelSelectorRequirement_v2)`] | matchExpressions is a list of label selector requirements. The requirements are ANDed. | `matchLabels` @@ -6052,7 +6124,7 @@ Applied only if Name is not specified. More info: https://git.k8s.io/community/c | Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels | `managedFields` -| `array (ManagedFieldsEntry)` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ManagedFieldsEntry[`array (ManagedFieldsEntry)`] | ManagedFields maps workflow-id and version to the set of fields that are managed by that workflow. This is mostly for internal housekeeping, and users typically shouldn't need to set or understand this field. A workflow can be the user's name, a controller's name, or the name of a specific apply path like "ci-cd". The set of fields is always in the version that the workflow used when modifying the object. | `name` @@ -6066,7 +6138,7 @@ Applied only if Name is not specified. More info: https://git.k8s.io/community/c Must be a DNS_LABEL. Cannot be updated. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces | `ownerReferences` -| `array (OwnerReference)` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-OwnerReference[`array (OwnerReference)`] | List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller. | `resourceVersion` @@ -6149,7 +6221,7 @@ Applied only if Name is not specified. More info: https://git.k8s.io/community/c | Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels | `managedFields` -| `array (ManagedFieldsEntry)` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ManagedFieldsEntry[`array (ManagedFieldsEntry)`] | ManagedFields maps workflow-id and version to the set of fields that are managed by that workflow. This is mostly for internal housekeeping, and users typically shouldn't need to set or understand this field. A workflow can be the user's name, a controller's name, or the name of a specific apply path like "ci-cd". The set of fields is always in the version that the workflow used when modifying the object. | `name` @@ -6163,7 +6235,7 @@ Applied only if Name is not specified. More info: https://git.k8s.io/community/c Must be a DNS_LABEL. Cannot be updated. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces | `ownerReferences` -| `array (OwnerReference)` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-OwnerReference[`array (OwnerReference)`] | List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller. | `resourceVersion` @@ -6214,7 +6286,7 @@ Type:: | Suggested HTTP return code for this status, 0 if not set. | `details` -| `StatusDetails` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-StatusDetails[`StatusDetails`] | Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. | `kind` @@ -6269,7 +6341,7 @@ Type:: | Suggested HTTP return code for this status, 0 if not set. | `details` -| `StatusDetails_v2` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-StatusDetails_v2[`StatusDetails_v2`] | Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. | `kind` @@ -6324,7 +6396,7 @@ Type:: | Suggested HTTP return code for this status, 0 if not set. | `details` -| `StatusDetails_v2` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-StatusDetails_v2[`StatusDetails_v2`] | Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. | `kind` @@ -6379,7 +6451,7 @@ Type:: | Suggested HTTP return code for this status, 0 if not set. | `details` -| `StatusDetails_v2` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-StatusDetails_v2[`StatusDetails_v2`] | Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. | `kind` @@ -6434,7 +6506,7 @@ Type:: | Suggested HTTP return code for this status, 0 if not set. | `details` -| `StatusDetails_v2` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-StatusDetails_v2[`StatusDetails_v2`] | Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. | `kind` @@ -6489,7 +6561,7 @@ Type:: | Suggested HTTP return code for this status, 0 if not set. | `details` -| `StatusDetails_v2` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-StatusDetails_v2[`StatusDetails_v2`] | Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. | `kind` @@ -6544,7 +6616,7 @@ Type:: | Suggested HTTP return code for this status, 0 if not set. | `details` -| `StatusDetails_v2` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-StatusDetails_v2[`StatusDetails_v2`] | Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. | `kind` @@ -6599,7 +6671,7 @@ Type:: | Suggested HTTP return code for this status, 0 if not set. | `details` -| `StatusDetails_v2` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-StatusDetails_v2[`StatusDetails_v2`] | Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. | `kind` @@ -6654,7 +6726,7 @@ Type:: | Suggested HTTP return code for this status, 0 if not set. | `details` -| `StatusDetails_v2` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-StatusDetails_v2[`StatusDetails_v2`] | Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. | `kind` @@ -6728,7 +6800,7 @@ Required:: | `type` | `string` -| +| |=== @@ -7004,6 +7076,211 @@ Required:: |=== +[id="io-k8s-networking-gateway-v1-GatewayClassList"] +== io.k8s.networking.gateway.v1.GatewayClassList schema + + +Description:: ++ +-- +GatewayClassList is a list of GatewayClass +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[`array (GatewayClass)`] +| List of gatewayclasses. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + +[id="io-k8s-networking-gateway-v1-GatewayList"] +== io.k8s.networking.gateway.v1.GatewayList schema + + +Description:: ++ +-- +GatewayList is a list of Gateway +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[`array (Gateway)`] +| List of gateways. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + +[id="io-k8s-networking-gateway-v1-GRPCRouteList"] +== io.k8s.networking.gateway.v1.GRPCRouteList schema + + +Description:: ++ +-- +GRPCRouteList is a list of GRPCRoute +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[`array (GRPCRoute)`] +| List of grpcroutes. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + +[id="io-k8s-networking-gateway-v1-HTTPRouteList"] +== io.k8s.networking.gateway.v1.HTTPRouteList schema + + +Description:: ++ +-- +HTTPRouteList is a list of HTTPRoute +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[`array (HTTPRoute)`] +| List of httproutes. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + +[id="io-k8s-networking-gateway-v1beta1-ReferenceGrantList"] +== io.k8s.networking.gateway.v1beta1.ReferenceGrantList schema + + +Description:: ++ +-- +ReferenceGrantList is a list of ReferenceGrant +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[`array (ReferenceGrant)`] +| List of referencegrants. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + [id="io-k8s-networking-policy-v1alpha1-AdminNetworkPolicyList"] == io.k8s.networking.policy.v1alpha1.AdminNetworkPolicyList schema @@ -7496,6 +7773,47 @@ Required:: |=== +[id="io-metal3-v1alpha1-HostUpdatePolicyList"] +== io.metal3.v1alpha1.HostUpdatePolicyList schema + + +Description:: ++ +-- +HostUpdatePolicyList is a list of HostUpdatePolicy +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[`array (HostUpdatePolicy)`] +| List of hostupdatepolicies. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + [id="io-metal3-v1alpha1-PreprovisioningImageList"] == io.metal3.v1alpha1.PreprovisioningImageList schema @@ -9423,6 +9741,88 @@ Required:: |=== +[id="io-openshift-machineconfiguration-v1-MachineOSBuildList"] +== io.openshift.machineconfiguration.v1.MachineOSBuildList schema + + +Description:: ++ +-- +MachineOSBuildList is a list of MachineOSBuild +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[`array (MachineOSBuild)`] +| List of machineosbuilds. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + +[id="io-openshift-machineconfiguration-v1-MachineOSConfigList"] +== io.openshift.machineconfiguration.v1.MachineOSConfigList schema + + +Description:: ++ +-- +MachineOSConfigList is a list of MachineOSConfig +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[`array (MachineOSConfig)`] +| List of machineosconfigs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + [id="io-openshift-monitoring-v1-AlertingRuleList"] == io.openshift.monitoring.v1.AlertingRuleList schema @@ -10899,6 +11299,88 @@ Required:: |=== +[id="io-operatorframework-olm-v1-ClusterCatalogList"] +== io.operatorframework.olm.v1.ClusterCatalogList schema + + +Description:: ++ +-- +ClusterCatalogList is a list of ClusterCatalog +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`array (ClusterCatalog)`] +| List of clustercatalogs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + +[id="io-operatorframework-olm-v1-ClusterExtensionList"] +== io.operatorframework.olm.v1.ClusterExtensionList schema + + +Description:: ++ +-- +ClusterExtensionList is a list of ClusterExtension +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`array (ClusterExtension)`] +| List of clusterextensions. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + [id="io-x-k8s-cluster-infrastructure-v1beta1-Metal3RemediationList"] == io.x-k8s.cluster.infrastructure.v1beta1.Metal3RemediationList schema @@ -11104,6 +11586,47 @@ Required:: |=== +[id="org-ovn-k8s-v1-ClusterUserDefinedNetworkList"] +== org.ovn.k8s.v1.ClusterUserDefinedNetworkList schema + + +Description:: ++ +-- +ClusterUserDefinedNetworkList is a list of ClusterUserDefinedNetwork +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[`array (ClusterUserDefinedNetwork)`] +| List of clusteruserdefinednetworks. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + [id="org-ovn-k8s-v1-EgressFirewallList"] == org.ovn.k8s.v1.EgressFirewallList schema @@ -11268,3 +11791,44 @@ Required:: |=== +[id="org-ovn-k8s-v1-UserDefinedNetworkList"] +== org.ovn.k8s.v1.UserDefinedNetworkList schema + + +Description:: ++ +-- +UserDefinedNetworkList is a list of UserDefinedNetwork +-- + +Type:: + `object` + +Required:: + - `items` + +[discrete] +=== Schema + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `items` +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[`array (UserDefinedNetwork)`] +| List of userdefinednetworks. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ListMeta[`ListMeta`] +| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +|=== + diff --git a/rest_api/operator_apis/authentication-operator-openshift-io-v1.adoc b/rest_api/operator_apis/authentication-operator-openshift-io-v1.adoc index 53d8706742..f70eaa9849 100644 --- a/rest_api/operator_apis/authentication-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/authentication-operator-openshift-io-v1.adoc @@ -140,7 +140,7 @@ Type:: | `oauthAPIServer` | `object` -| OAuthAPIServer holds status specific only to oauth-apiserver +| oauthAPIServer holds status specific only to oauth-apiserver | `observedGeneration` | `integer` @@ -275,7 +275,7 @@ Required:: Description:: + -- -OAuthAPIServer holds status specific only to oauth-apiserver +oauthAPIServer holds status specific only to oauth-apiserver -- Type:: @@ -290,7 +290,7 @@ Type:: | `latestAvailableRevision` | `integer` -| LatestAvailableRevision is the latest revision used as suffix of revisioned +| latestAvailableRevision is the latest revision used as suffix of revisioned secrets like encryption-config. A new revision causes a new deployment of pods. |=== diff --git a/rest_api/operator_apis/cloudcredential-operator-openshift-io-v1.adoc b/rest_api/operator_apis/cloudcredential-operator-openshift-io-v1.adoc index 06bafe3dd9..406dafa126 100644 --- a/rest_api/operator_apis/cloudcredential-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/cloudcredential-operator-openshift-io-v1.adoc @@ -11,8 +11,9 @@ toc::[] Description:: + -- -CloudCredential provides a means to configure an operator to manage CredentialsRequests. - Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). +CloudCredential provides a means to configure an operator to manage CredentialsRequests. + +Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- Type:: @@ -68,12 +69,23 @@ Type:: | `credentialsMode` | `string` -| CredentialsMode allows informing CCO that it should not attempt to dynamically determine the root cloud credentials capabilities, and it should just run in the specified mode. It also allows putting the operator into "manual" mode if desired. Leaving the field in default mode runs CCO so that the cluster's cloud credentials will be dynamically probed for capabilities (on supported clouds/platforms). Supported modes: AWS/Azure/GCP: "" (Default), "Mint", "Passthrough", "Manual" Others: Do not set value as other platforms only support running in "Passthrough" +| credentialsMode allows informing CCO that it should not attempt to dynamically +determine the root cloud credentials capabilities, and it should just run in +the specified mode. +It also allows putting the operator into "manual" mode if desired. +Leaving the field in default mode runs CCO so that the cluster's cloud credentials +will be dynamically probed for capabilities (on supported clouds/platforms). +Supported modes: + AWS/Azure/GCP: "" (Default), "Mint", "Passthrough", "Manual" + Others: Do not set value as other platforms only support running in "Passthrough" | `logLevel` | `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". +| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a +simple way to manage coarse grained logging choices that operators have to interpret for their operands. + +Valid values are: "Normal", "Debug", "Trace", "TraceAll". +Defaults to "Normal". | `managementState` | `string` @@ -81,16 +93,24 @@ Type:: | `observedConfig` | `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator +| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because +it is an input to the level for the operator | `operatorLogLevel` | `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". +| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a +simple way to manage coarse grained logging choices that operators have to interpret for themselves. + +Valid values are: "Normal", "Debug", "Trace", "TraceAll". +Defaults to "Normal". | `unsupportedConfigOverrides` | `` -| unsupportedConfigOverrides overrides the final configuration that was computed by the operator. Red Hat does not support the use of this field. Misuse of this field could lead to unexpected behavior or conflict with other configuration options. Seek guidance from the Red Hat support before using this field. Use of this property blocks cluster upgrades, it must be removed before upgrading your cluster. +| unsupportedConfigOverrides overrides the final configuration that was computed by the operator. +Red Hat does not support the use of this field. +Misuse of this field could lead to unexpected behavior or conflict with other configuration options. +Seek guidance from the Red Hat support before using this field. +Use of this property blocks cluster upgrades, it must be removed before upgrading your cluster. |=== === .status @@ -126,6 +146,10 @@ Type:: | `object` | GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. +| `latestAvailableRevision` +| `integer` +| latestAvailableRevision is the deploymentID of the most recent deployment + | `observedGeneration` | `integer` | observedGeneration is the last generation change you've dealt with @@ -163,6 +187,8 @@ Type:: `object` Required:: + - `lastTransitionTime` + - `status` - `type` @@ -173,7 +199,8 @@ Required:: | `lastTransitionTime` | `string` -| +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. | `message` | `string` @@ -185,11 +212,11 @@ Required:: | `status` | `string` -| +| status of the condition, one of True, False, Unknown. | `type` | `string` -| +| type of condition in CamelCase or in foo.example.com/CamelCase. |=== === .status.generations diff --git a/rest_api/operator_apis/clustercsidriver-operator-openshift-io-v1.adoc b/rest_api/operator_apis/clustercsidriver-operator-openshift-io-v1.adoc index 09baee2a58..b66851b130 100644 --- a/rest_api/operator_apis/clustercsidriver-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/clustercsidriver-operator-openshift-io-v1.adoc @@ -102,7 +102,7 @@ Defaults to "Normal". | `storageClassState` | `string` -| StorageClassState determines if CSI operator should create and manage storage classes. +| storageClassState determines if CSI operator should create and manage storage classes. If this field value is empty or Managed - CSI operator will continuously reconcile storage class and create if necessary. If this field value is Unmanaged - CSI operator will not reconcile any previously created @@ -167,7 +167,7 @@ Consumers should treat unknown values as a NO-OP. | `vSphere` | `object` -| vsphere is used to configure the vsphere CSI driver. +| vSphere is used to configure the vsphere CSI driver. |=== === .spec.driverConfig.aws @@ -437,7 +437,7 @@ for disk encryption of volumes for the default storage classes. Description:: + -- -vsphere is used to configure the vsphere CSI driver. +vSphere is used to configure the vsphere CSI driver. -- Type:: diff --git a/rest_api/operator_apis/console-operator-openshift-io-v1.adoc b/rest_api/operator_apis/console-operator-openshift-io-v1.adoc index 1d8367a3d3..537a7fe446 100644 --- a/rest_api/operator_apis/console-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/console-operator-openshift-io-v1.adoc @@ -176,14 +176,14 @@ Each of the available capabilities may appear only once in the list. | `customLogoFile` | `object` | customLogoFile replaces the default OpenShift logo in the masthead and about dialog. It is a reference to a +Only one of customLogoFile or logos can be set at a time. ConfigMap in the openshift-config namespace. This can be created with a command like 'oc create configmap custom-logo --from-file=/path/to/file -n openshift-config'. Image size must be less than 1 MB due to constraints on the ConfigMap size. The ConfigMap key should include a file extension so that the console serves the file with the correct MIME type. -Recommended logo specifications: -Dimensions: Max height of 68px and max width of 200px -SVG format preferred +The recommended file format for the logo is SVG, but other file formats are allowed if supported by the browser. +Deprecated: Use logos instead. | `customProductName` | `string` @@ -201,6 +201,19 @@ of the web console. Providing documentationBaseURL will override the default documentation URL. Invalid value will prevent a console rollout. +| `logos` +| `array` +| logos is used to replace the OpenShift Masthead and Favicon logos in the console UI with custom logos. +logos is an optional field that allows a list of logos. +Only one of logos or customLogoFile can be set at a time. +If logos is set, customLogoFile must be unset. +When specified, there must be at least one entry and no more than 2 entries. +Each type must appear only once in the list. + +| `logos[]` +| `object` +| Logo defines a configuration based on theme modes for the console UI logo. + | `perspectives` | `array` | perspectives allows enabling/disabling of perspective(s) that user can see in the Perspective switcher dropdown. @@ -320,14 +333,14 @@ Description:: + -- customLogoFile replaces the default OpenShift logo in the masthead and about dialog. It is a reference to a +Only one of customLogoFile or logos can be set at a time. ConfigMap in the openshift-config namespace. This can be created with a command like 'oc create configmap custom-logo --from-file=/path/to/file -n openshift-config'. Image size must be less than 1 MB due to constraints on the ConfigMap size. The ConfigMap key should include a file extension so that the console serves the file with the correct MIME type. -Recommended logo specifications: -Dimensions: Max height of 68px and max width of 200px -SVG format preferred +The recommended file format for the logo is SVG, but other file formats are allowed if supported by the browser. +Deprecated: Use logos instead. -- Type:: @@ -342,7 +355,7 @@ Type:: | `key` | `string` -| Key allows pointing to a specific key/value inside of the configmap. This is useful for logical file references. +| key allows pointing to a specific key/value inside of the configmap. This is useful for logical file references. | `name` | `string` @@ -415,7 +428,7 @@ Required:: | `id` | `string` -| ID is an identifier used in the URL to enable deep linking in console. +| id is an identifier used in the URL to enable deep linking in console. ID is required and must have 1-32 URL safe (A-Z, a-z, 0-9, - and _) characters. | `label` @@ -471,7 +484,7 @@ Required:: | `id` | `string` -| ID is an identifier used in the URL to enable deep linking in console. +| id is an identifier used in the URL to enable deep linking in console. ID is required and must have 1-32 URL safe (A-Z, a-z, 0-9, - and _) characters. | `label` @@ -525,6 +538,197 @@ If the list is empty the complete developer catalog will be shown. | `string` | state defines if a list of catalog types should be enabled or disabled. +|=== +=== .spec.customization.logos +Description:: ++ +-- +logos is used to replace the OpenShift Masthead and Favicon logos in the console UI with custom logos. +logos is an optional field that allows a list of logos. +Only one of logos or customLogoFile can be set at a time. +If logos is set, customLogoFile must be unset. +When specified, there must be at least one entry and no more than 2 entries. +Each type must appear only once in the list. +-- + +Type:: + `array` + + + + +=== .spec.customization.logos[] +Description:: ++ +-- +Logo defines a configuration based on theme modes for the console UI logo. +-- + +Type:: + `object` + +Required:: + - `themes` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `themes` +| `array` +| themes specifies the themes for the console UI logo. +themes is a required field that allows a list of themes. Each item in the themes list must have a unique mode and a source field. +Each mode determines whether the logo is for the dark or light mode of the console UI. +If a theme is not specified, the default OpenShift logo will be displayed for that theme. +There must be at least one entry and no more than 2 entries. + +| `themes[]` +| `object` +| Theme defines a theme mode for the console UI. + +| `type` +| `string` +| type specifies the type of the logo for the console UI. It determines whether the logo is for the masthead or favicon. +type is a required field that allows values of Masthead and Favicon. +When set to "Masthead", the logo will be used in the masthead and about modal of the console UI. +When set to "Favicon", the logo will be used as the favicon of the console UI. + +|=== +=== .spec.customization.logos[].themes +Description:: ++ +-- +themes specifies the themes for the console UI logo. +themes is a required field that allows a list of themes. Each item in the themes list must have a unique mode and a source field. +Each mode determines whether the logo is for the dark or light mode of the console UI. +If a theme is not specified, the default OpenShift logo will be displayed for that theme. +There must be at least one entry and no more than 2 entries. +-- + +Type:: + `array` + + + + +=== .spec.customization.logos[].themes[] +Description:: ++ +-- +Theme defines a theme mode for the console UI. +-- + +Type:: + `object` + +Required:: + - `mode` + - `source` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `mode` +| `string` +| mode is used to specify what theme mode a logo will apply to in the console UI. +mode is a required field that allows values of Dark and Light. +When set to Dark, the logo file referenced in the 'file' field will be used when an end-user of the console UI enables the Dark mode. +When set to Light, the logo file referenced in the 'file' field will be used when an end-user of the console UI enables the Light mode. + +| `source` +| `object` +| source is used by the console to locate the specified file containing a custom logo. +source is a required field that references a ConfigMap name and key that contains the custom logo file in the openshift-config namespace. +You can create it with a command like: +- 'oc create configmap custom-logos-config --namespace=openshift-config --from-file=/path/to/file' +The ConfigMap key must include the file extension so that the console serves the file with the correct MIME type. +The recommended file format for the Masthead and Favicon logos is SVG, but other file formats are allowed if supported by the browser. +The logo image size must be less than 1 MB due to constraints on the ConfigMap size. +For more information, see the documentation: https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html/web_console/customizing-web-console#customizing-web-console + +|=== +=== .spec.customization.logos[].themes[].source +Description:: ++ +-- +source is used by the console to locate the specified file containing a custom logo. +source is a required field that references a ConfigMap name and key that contains the custom logo file in the openshift-config namespace. +You can create it with a command like: +- 'oc create configmap custom-logos-config --namespace=openshift-config --from-file=/path/to/file' +The ConfigMap key must include the file extension so that the console serves the file with the correct MIME type. +The recommended file format for the Masthead and Favicon logos is SVG, but other file formats are allowed if supported by the browser. +The logo image size must be less than 1 MB due to constraints on the ConfigMap size. +For more information, see the documentation: https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html/web_console/customizing-web-console#customizing-web-console +-- + +Type:: + `object` + +Required:: + - `from` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `configMap` +| `object` +| configMap specifies the ConfigMap sourcing details such as the name of the ConfigMap and the key for the file. +The ConfigMap must exist in the openshift-config namespace. +Required when from is "ConfigMap", and forbidden otherwise. + +| `from` +| `string` +| from is a required field to specify the source type of the file reference. +Allowed values are ConfigMap. +When set to ConfigMap, the file will be sourced from a ConfigMap in the openshift-config namespace. The configMap field must be set when from is set to ConfigMap. + +|=== +=== .spec.customization.logos[].themes[].source.configMap +Description:: ++ +-- +configMap specifies the ConfigMap sourcing details such as the name of the ConfigMap and the key for the file. +The ConfigMap must exist in the openshift-config namespace. +Required when from is "ConfigMap", and forbidden otherwise. +-- + +Type:: + `object` + +Required:: + - `key` + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| key is the logo key inside the referenced ConfigMap. +Must consist only of alphanumeric characters, dashes (-), underscores (_), and periods (.). +Must be at most 253 characters in length. +Must end in a valid file extension. +A valid file extension must consist of a period followed by 2 to 5 alpha characters. + +| `name` +| `string` +| name is the name of the ConfigMap. +name is a required field. +Must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character. +Must be at most 253 characters in length. + |=== === .spec.customization.perspectives Description:: diff --git a/rest_api/operator_apis/etcd-operator-openshift-io-v1.adoc b/rest_api/operator_apis/etcd-operator-openshift-io-v1.adoc index 67306fcde6..d086468103 100644 --- a/rest_api/operator_apis/etcd-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/etcd-operator-openshift-io-v1.adoc @@ -342,7 +342,8 @@ Required:: | `currentRevision` | `integer` -| currentRevision is the generation of the most recently successful deployment +| currentRevision is the generation of the most recently successful deployment. +Can not be set on creation of a nodeStatus. Updates must only increase the value. | `lastFailedCount` | `integer` @@ -374,7 +375,8 @@ Required:: | `targetRevision` | `integer` -| targetRevision is the generation of the deployment we're trying to apply +| targetRevision is the generation of the deployment we're trying to apply. +Can not be set on creation of a nodeStatus. |=== diff --git a/rest_api/operator_apis/ingresscontroller-operator-openshift-io-v1.adoc b/rest_api/operator_apis/ingresscontroller-operator-openshift-io-v1.adoc index e1cd522bfb..548ee1d84b 100644 --- a/rest_api/operator_apis/ingresscontroller-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/ingresscontroller-operator-openshift-io-v1.adoc @@ -190,6 +190,72 @@ If this field is empty, the ingress controller uses the default error pages. If this field is empty, the default values are used. +| `idleConnectionTerminationPolicy` +| `string` +| idleConnectionTerminationPolicy maps directly to HAProxy's +idle-close-on-response option and controls whether HAProxy +keeps idle frontend connections open during a soft stop +(router reload). + +Allowed values for this field are "Immediate" and +"Deferred". The default value is "Immediate". + +When set to "Immediate", idle connections are closed +immediately during router reloads. This ensures immediate +propagation of route changes but may impact clients +sensitive to connection resets. + +When set to "Deferred", HAProxy will maintain idle +connections during a soft reload instead of closing them +immediately. These connections remain open until any of the +following occurs: + + - A new request is received on the connection, in which + case HAProxy handles it in the old process and closes + the connection after sending the response. + + - HAProxy's `timeout http-keep-alive` duration expires + (300 seconds in OpenShift's configuration, not + configurable). + + - The client's keep-alive timeout expires, causing the + client to close the connection. + +Setting Deferred can help prevent errors in clients or load +balancers that do not properly handle connection resets. +Additionally, this option allows you to retain the pre-2.4 +HAProxy behaviour: in HAProxy version 2.2 (OpenShift +versions < 4.14), maintaining idle connections during a +soft reload was the default behaviour, but starting with +HAProxy 2.4, the default changed to closing idle +connections immediately. + +Important Consideration: + + - Using Deferred will result in temporary inconsistencies + for the first request on each persistent connection + after a route update and router reload. This request + will be processed by the old HAProxy process using its + old configuration. Subsequent requests will use the + updated configuration. + +Operational Considerations: + + - Keeping idle connections open during reloads may lead + to an accumulation of old HAProxy processes if + connections remain idle for extended periods, + especially in environments where frequent reloads + occur. + + - Consider monitoring the number of HAProxy processes in + the router pods when Deferred is set. + + - You may need to enable or adjust the + `ingress.operator.openshift.io/hard-stop-after` + duration (configured via an annotation on the + IngressController resource) in environments with + frequent reloads to prevent resource exhaustion. + | `logging` | `object` | logging defines parameters for what should be logged where. If this @@ -993,7 +1059,7 @@ Type:: | `string` | protocol specifies whether the load balancer uses PROXY protocol to forward connections to the IngressController. See "service.kubernetes.io/ibm-load-balancer-cloud-provider-enable-features: -"proxy-protocol"" at https://cloud.ibm.com/docs/containers?topic=containers-vpc-lbaas +"proxy-protocol"" at https://cloud.ibm.com/docs/containers?topic=containers-vpc-lbaas" PROXY protocol can be used with load balancers that support it to communicate the source addresses of client connections when @@ -2598,7 +2664,7 @@ If unset, the default timeout is 30s | `connectTimeout` | `string` -| ConnectTimeout defines the maximum time to wait for +| connectTimeout defines the maximum time to wait for a connection attempt to a server/backend to succeed. This field expects an unsigned duration string of decimal numbers, each with optional @@ -2948,11 +3014,11 @@ This should be when the underlying condition changed. If that is not known, the | `message` | `string` -| +| | `reason` | `string` -| +| | `status` | `string` @@ -3548,7 +3614,7 @@ Type:: | `string` | protocol specifies whether the load balancer uses PROXY protocol to forward connections to the IngressController. See "service.kubernetes.io/ibm-load-balancer-cloud-provider-enable-features: -"proxy-protocol"" at https://cloud.ibm.com/docs/containers?topic=containers-vpc-lbaas +"proxy-protocol"" at https://cloud.ibm.com/docs/containers?topic=containers-vpc-lbaas" PROXY protocol can be used with load balancers that support it to communicate the source addresses of client connections when @@ -4012,7 +4078,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController`] schema -| +| |=== .HTTP responses @@ -4145,7 +4211,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController`] schema -| +| |=== .HTTP responses @@ -4247,7 +4313,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../autoscale_apis/scale-autoscaling-v1.adoc#scale-autoscaling-v1[`Scale`] schema -| +| |=== .HTTP responses @@ -4349,7 +4415,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController`] schema -| +| |=== .HTTP responses diff --git a/rest_api/operator_apis/insightsoperator-operator-openshift-io-v1.adoc b/rest_api/operator_apis/insightsoperator-operator-openshift-io-v1.adoc index 3fb9a468f4..eed7d53a63 100644 --- a/rest_api/operator_apis/insightsoperator-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/insightsoperator-operator-openshift-io-v1.adoc @@ -472,7 +472,7 @@ Required:: | `state` | `string` -| state determines what the current state of the health check is. Health check is enabled by default and can be disabled by the user in the Insights advisor service's user interface. +| state determines what the current state of the health check is. Health check is enabled by default and can be disabled by the user in the Insights advisor user interface. | `totalRisk` | `integer` diff --git a/rest_api/operator_apis/kubeapiserver-operator-openshift-io-v1.adoc b/rest_api/operator_apis/kubeapiserver-operator-openshift-io-v1.adoc index 159a9bde68..dc1dd20a25 100644 --- a/rest_api/operator_apis/kubeapiserver-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/kubeapiserver-operator-openshift-io-v1.adoc @@ -341,7 +341,8 @@ Required:: | `currentRevision` | `integer` -| currentRevision is the generation of the most recently successful deployment +| currentRevision is the generation of the most recently successful deployment. +Can not be set on creation of a nodeStatus. Updates must only increase the value. | `lastFailedCount` | `integer` @@ -373,7 +374,8 @@ Required:: | `targetRevision` | `integer` -| targetRevision is the generation of the deployment we're trying to apply +| targetRevision is the generation of the deployment we're trying to apply. +Can not be set on creation of a nodeStatus. |=== === .status.serviceAccountIssuers diff --git a/rest_api/operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc b/rest_api/operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc index 426bf8c6f5..3bd0cbfe05 100644 --- a/rest_api/operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc @@ -337,7 +337,8 @@ Required:: | `currentRevision` | `integer` -| currentRevision is the generation of the most recently successful deployment +| currentRevision is the generation of the most recently successful deployment. +Can not be set on creation of a nodeStatus. Updates must only increase the value. | `lastFailedCount` | `integer` @@ -369,7 +370,8 @@ Required:: | `targetRevision` | `integer` -| targetRevision is the generation of the deployment we're trying to apply +| targetRevision is the generation of the deployment we're trying to apply. +Can not be set on creation of a nodeStatus. |=== diff --git a/rest_api/operator_apis/kubescheduler-operator-openshift-io-v1.adoc b/rest_api/operator_apis/kubescheduler-operator-openshift-io-v1.adoc index 7b2e8b76eb..d015dbdac7 100644 --- a/rest_api/operator_apis/kubescheduler-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/kubescheduler-operator-openshift-io-v1.adoc @@ -329,7 +329,8 @@ Required:: | `currentRevision` | `integer` -| currentRevision is the generation of the most recently successful deployment +| currentRevision is the generation of the most recently successful deployment. +Can not be set on creation of a nodeStatus. Updates must only increase the value. | `lastFailedCount` | `integer` @@ -361,7 +362,8 @@ Required:: | `targetRevision` | `integer` -| targetRevision is the generation of the deployment we're trying to apply +| targetRevision is the generation of the deployment we're trying to apply. +Can not be set on creation of a nodeStatus. |=== diff --git a/rest_api/operator_apis/machineconfiguration-operator-openshift-io-v1.adoc b/rest_api/operator_apis/machineconfiguration-operator-openshift-io-v1.adoc index 1ea4d5f188..c326273efc 100644 --- a/rest_api/operator_apis/machineconfiguration-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/machineconfiguration-operator-openshift-io-v1.adoc @@ -91,8 +91,10 @@ Defaults to "Normal". | managedBootImages allows configuration for the management of boot images for machine resources within the cluster. This configuration allows users to select resources that should be updated to the latest boot images during cluster upgrades, ensuring that new machines -always boot with the current cluster version's boot image. When omitted, no boot images -will be updated. +always boot with the current cluster version's boot image. When omitted, this means no opinion +and the platform is left to choose a reasonable default, which is subject to change over time. +The default for each machine manager mode is All for GCP and AWS platforms, and None for all +other platforms. | `managementState` | `string` @@ -139,8 +141,10 @@ Description:: managedBootImages allows configuration for the management of boot images for machine resources within the cluster. This configuration allows users to select resources that should be updated to the latest boot images during cluster upgrades, ensuring that new machines -always boot with the current cluster version's boot image. When omitted, no boot images -will be updated. +always boot with the current cluster version's boot image. When omitted, this means no opinion +and the platform is left to choose a reasonable default, which is subject to change over time. +The default for each machine manager mode is All for GCP and AWS platforms, and None for all +other platforms. -- Type:: @@ -242,6 +246,7 @@ Required:: Valid values are All and Partial. All means that every resource matched by the machine manager will be updated. Partial requires specified selector(s) and allows customisation of which resources matched by the machine manager will be updated. +None means that every resource matched by the machine manager will not be updated. | `partial` | `object` @@ -897,6 +902,11 @@ Type:: | `object` | Condition contains details for one aspect of the current state of this API Resource. +| `managedBootImagesStatus` +| `object` +| managedBootImagesStatus reflects what the latest cluster-validated boot image configuration is +and will be used by Machine Config Controller while performing boot image updates. + | `nodeDisruptionPolicyStatus` | `object` | nodeDisruptionPolicyStatus status reflects what the latest cluster-validated policies are, @@ -975,6 +985,230 @@ This field may not be empty. | `string` | type of condition in CamelCase or in foo.example.com/CamelCase. +|=== +=== .status.managedBootImagesStatus +Description:: ++ +-- +managedBootImagesStatus reflects what the latest cluster-validated boot image configuration is +and will be used by Machine Config Controller while performing boot image updates. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `machineManagers` +| `array` +| machineManagers can be used to register machine management resources for boot image updates. The Machine Config Operator +will watch for changes to this list. Only one entry is permitted per type of machine management resource. + +| `machineManagers[]` +| `object` +| MachineManager describes a target machine resource that is registered for boot image updates. It stores identifying information +such as the resource type and the API Group of the resource. It also provides granular control via the selection field. + +|=== +=== .status.managedBootImagesStatus.machineManagers +Description:: ++ +-- +machineManagers can be used to register machine management resources for boot image updates. The Machine Config Operator +will watch for changes to this list. Only one entry is permitted per type of machine management resource. +-- + +Type:: + `array` + + + + +=== .status.managedBootImagesStatus.machineManagers[] +Description:: ++ +-- +MachineManager describes a target machine resource that is registered for boot image updates. It stores identifying information +such as the resource type and the API Group of the resource. It also provides granular control via the selection field. +-- + +Type:: + `object` + +Required:: + - `apiGroup` + - `resource` + - `selection` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiGroup` +| `string` +| apiGroup is name of the APIGroup that the machine management resource belongs to. +The only current valid value is machine.openshift.io. +machine.openshift.io means that the machine manager will only register resources that belong to OpenShift machine API group. + +| `resource` +| `string` +| resource is the machine management resource's type. +The only current valid value is machinesets. +machinesets means that the machine manager will only register resources of the kind MachineSet. + +| `selection` +| `object` +| selection allows granular control of the machine management resources that will be registered for boot image updates. + +|=== +=== .status.managedBootImagesStatus.machineManagers[].selection +Description:: ++ +-- +selection allows granular control of the machine management resources that will be registered for boot image updates. +-- + +Type:: + `object` + +Required:: + - `mode` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `mode` +| `string` +| mode determines how machine managers will be selected for updates. +Valid values are All and Partial. +All means that every resource matched by the machine manager will be updated. +Partial requires specified selector(s) and allows customisation of which resources matched by the machine manager will be updated. +None means that every resource matched by the machine manager will not be updated. + +| `partial` +| `object` +| partial provides label selector(s) that can be used to match machine management resources. +Only permitted when mode is set to "Partial". + +|=== +=== .status.managedBootImagesStatus.machineManagers[].selection.partial +Description:: ++ +-- +partial provides label selector(s) that can be used to match machine management resources. +Only permitted when mode is set to "Partial". +-- + +Type:: + `object` + +Required:: + - `machineResourceSelector` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `machineResourceSelector` +| `object` +| machineResourceSelector is a label selector that can be used to select machine resources like MachineSets. + +|=== +=== .status.managedBootImagesStatus.machineManagers[].selection.partial.machineResourceSelector +Description:: ++ +-- +machineResourceSelector is a label selector that can be used to select machine resources like MachineSets. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `matchExpressions` +| `array` +| matchExpressions is a list of label selector requirements. The requirements are ANDed. + +| `matchExpressions[]` +| `object` +| A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. + +| `matchLabels` +| `object (string)` +| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels +map is equivalent to an element of matchExpressions, whose key field is "key", the +operator is "In", and the values array contains only "value". The requirements are ANDed. + +|=== +=== .status.managedBootImagesStatus.machineManagers[].selection.partial.machineResourceSelector.matchExpressions +Description:: ++ +-- +matchExpressions is a list of label selector requirements. The requirements are ANDed. +-- + +Type:: + `array` + + + + +=== .status.managedBootImagesStatus.machineManagers[].selection.partial.machineResourceSelector.matchExpressions[] +Description:: ++ +-- +A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. +-- + +Type:: + `object` + +Required:: + - `key` + - `operator` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| key is the label key that the selector applies to. + +| `operator` +| `string` +| operator represents a key's relationship to a set of values. +Valid operators are In, NotIn, Exists and DoesNotExist. + +| `values` +| `array (string)` +| values is an array of string values. If the operator is In or NotIn, +the values array must be non-empty. If the operator is Exists or DoesNotExist, +the values array must be empty. This array is replaced during a strategic +merge patch. + |=== === .status.nodeDisruptionPolicyStatus Description:: diff --git a/rest_api/operator_apis/network-operator-openshift-io-v1.adoc b/rest_api/operator_apis/network-operator-openshift-io-v1.adoc index fa0f8c53ad..05209687d8 100644 --- a/rest_api/operator_apis/network-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/network-operator-openshift-io-v1.adoc @@ -78,6 +78,18 @@ when multiple networks are enabled. created by default. Instead, pods must request them by name. type must be specified, along with exactly one "Config" that matches the type. +| `additionalRoutingCapabilities` +| `object` +| additionalRoutingCapabilities describes components and relevant +configuration providing additional routing capabilities. When set, it +enables such components and the usage of the routing capabilities they +provide for the machine network. Upstream operators, like MetalLB +operator, requiring these capabilities may rely on, or automatically set +this attribute. Network plugins may leverage advanced routing +capabilities acquired through the enablement of these components but may +require specific configuration on their side to do so; refer to their +respective documentation and configuration options. + | `clusterNetwork` | `array` | clusterNetwork is the IP address pool to use for pod IPs. @@ -105,9 +117,10 @@ otherwise. | `disableMultiNetwork` | `boolean` -| disableMultiNetwork specifies whether or not multiple pod network -support should be disabled. If unset, this property defaults to -'false' and multiple network support is enabled. +| disableMultiNetwork defaults to 'false' and this setting enables the pod multi-networking capability. +disableMultiNetwork when set to 'true' at cluster install time does not install the components, typically the Multus CNI and the network-attachment-definition CRD, +that enable the pod multi-networking capability. Setting the parameter to 'true' might be useful when you need install third-party CNI plugins, +but these plugins are not supported by Red Hat. Changing the parameter value as a postinstallation cluster task has no effect. | `disableNetworkDiagnostics` | `boolean` @@ -236,7 +249,7 @@ NetworkAttachmentDefinition CRD | `simpleMacvlanConfig` | `object` -| SimpleMacvlanConfig configures the macvlan interface in case of type:NetworkTypeSimpleMacvlan +| simpleMacvlanConfig configures the macvlan interface in case of type:NetworkTypeSimpleMacvlan | `type` | `string` @@ -248,7 +261,7 @@ The supported values are NetworkTypeRaw, NetworkTypeSimpleMacvlan Description:: + -- -SimpleMacvlanConfig configures the macvlan interface in case of type:NetworkTypeSimpleMacvlan +simpleMacvlanConfig configures the macvlan interface in case of type:NetworkTypeSimpleMacvlan -- Type:: @@ -263,7 +276,7 @@ Type:: | `ipamConfig` | `object` -| IPAMConfig configures IPAM module will be used for IP Address Management (IPAM). +| ipamConfig configures IPAM module will be used for IP Address Management (IPAM). | `master` | `string` @@ -284,7 +297,7 @@ kernel will select the value. Description:: + -- -IPAMConfig configures IPAM module will be used for IP Address Management (IPAM). +ipamConfig configures IPAM module will be used for IP Address Management (IPAM). -- Type:: @@ -299,11 +312,11 @@ Type:: | `staticIPAMConfig` | `object` -| StaticIPAMConfig configures the static IP address in case of type:IPAMTypeStatic +| staticIPAMConfig configures the static IP address in case of type:IPAMTypeStatic | `type` | `string` -| Type is the type of IPAM module will be used for IP Address Management(IPAM). +| type is the type of IPAM module will be used for IP Address Management(IPAM). The supported values are IPAMTypeDHCP, IPAMTypeStatic |=== @@ -311,7 +324,7 @@ The supported values are IPAMTypeDHCP, IPAMTypeStatic Description:: + -- -StaticIPAMConfig configures the static IP address in case of type:IPAMTypeStatic +staticIPAMConfig configures the static IP address in case of type:IPAMTypeStatic -- Type:: @@ -326,7 +339,7 @@ Type:: | `addresses` | `array` -| Addresses configures IP address for the interface +| addresses configures IP address for the interface | `addresses[]` | `object` @@ -334,11 +347,11 @@ Type:: | `dns` | `object` -| DNS configures DNS for the interface +| dns configures DNS for the interface | `routes` | `array` -| Routes configures IP routes for the interface +| routes configures IP routes for the interface | `routes[]` | `object` @@ -349,7 +362,7 @@ Type:: Description:: + -- -Addresses configures IP address for the interface +addresses configures IP address for the interface -- Type:: @@ -377,18 +390,18 @@ Type:: | `address` | `string` -| Address is the IP address in CIDR format +| address is the IP address in CIDR format | `gateway` | `string` -| Gateway is IP inside of subnet to designate as the gateway +| gateway is IP inside of subnet to designate as the gateway |=== === .spec.additionalNetworks[].simpleMacvlanConfig.ipamConfig.staticIPAMConfig.dns Description:: + -- -DNS configures DNS for the interface +dns configures DNS for the interface -- Type:: @@ -403,22 +416,22 @@ Type:: | `domain` | `string` -| Domain configures the domainname the local domain used for short hostname lookups +| domain configures the domainname the local domain used for short hostname lookups | `nameservers` | `array (string)` -| Nameservers points DNS servers for IP lookup +| nameservers points DNS servers for IP lookup | `search` | `array (string)` -| Search configures priority ordered search domains for short hostname lookups +| search configures priority ordered search domains for short hostname lookups |=== === .spec.additionalNetworks[].simpleMacvlanConfig.ipamConfig.staticIPAMConfig.routes Description:: + -- -Routes configures IP routes for the interface +routes configures IP routes for the interface -- Type:: @@ -446,13 +459,48 @@ Type:: | `destination` | `string` -| Destination points the IP route destination +| destination points the IP route destination | `gateway` | `string` -| Gateway is the route's next-hop IP address +| gateway is the route's next-hop IP address If unset, a default gateway is assumed (as determined by the CNI plugin). +|=== +=== .spec.additionalRoutingCapabilities +Description:: ++ +-- +additionalRoutingCapabilities describes components and relevant +configuration providing additional routing capabilities. When set, it +enables such components and the usage of the routing capabilities they +provide for the machine network. Upstream operators, like MetalLB +operator, requiring these capabilities may rely on, or automatically set +this attribute. Network plugins may leverage advanced routing +capabilities acquired through the enablement of these components but may +require specific configuration on their side to do so; refer to their +respective documentation and configuration options. +-- + +Type:: + `object` + +Required:: + - `providers` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `providers` +| `array (string)` +| providers is a set of enabled components that provide additional routing +capabilities. Entries on this list must be unique. The only valid value +is currrently "FRR" which provides FRR routing capabilities through the +deployment of FRR. + |=== === .spec.clusterNetwork Description:: @@ -517,7 +565,7 @@ Type:: | `openshiftSDNConfig` | `object` -| openShiftSDNConfig was previously used to configure the openshift-sdn plugin. +| openshiftSDNConfig was previously used to configure the openshift-sdn plugin. DEPRECATED: OpenShift SDN is no longer supported. | `ovnKubernetesConfig` @@ -534,7 +582,7 @@ All NetworkTypes are supported except for NetworkTypeRaw Description:: + -- -openShiftSDNConfig was previously used to configure the openshift-sdn plugin. +openshiftSDNConfig was previously used to configure the openshift-sdn plugin. DEPRECATED: OpenShift SDN is no longer supported. -- @@ -605,7 +653,7 @@ Default is 6081 | `hybridOverlayConfig` | `object` -| HybridOverlayConfig configures an additional overlay network for peers that are +| hybridOverlayConfig configures an additional overlay network for peers that are not using OVN. | `ipsecConfig` @@ -652,7 +700,7 @@ default one is being already used by something else. It must not overlap with any other subnet being used by OpenShift or by the node network. The size of the subnet must be larger than the number of nodes. The value cannot be changed after installation. -Default is fd98::/48 +Default is fd98::/64 |=== === .spec.defaultNetwork.ovnKubernetesConfig.egressIPConfig @@ -702,7 +750,7 @@ Type:: | `ipForwarding` | `string` -| IPForwarding controls IP forwarding for all traffic on OVN-Kubernetes managed interfaces (such as br-ex). +| ipForwarding controls IP forwarding for all traffic on OVN-Kubernetes managed interfaces (such as br-ex). By default this is set to Restricted, and Kubernetes related traffic is still forwarded appropriately, but other IP traffic will not be routed by the OCP node. If there is a desire to allow the host to forward traffic across OVN-Kubernetes managed interfaces, then set this field to "Global". @@ -720,7 +768,7 @@ configuration is used. Check individual members fields within ipv6 for details o | `routingViaHost` | `boolean` -| RoutingViaHost allows pod egress traffic to exit via the ovn-k8s-mp0 management port +| routingViaHost allows pod egress traffic to exit via the ovn-k8s-mp0 management port into the host before sending it out. If this is not set, traffic will always egress directly from OVN to outside without touching the host stack. Setting this to true means hardware offload will not be supported. Default is false if GatewayConfig is specified. @@ -792,7 +840,7 @@ Note that IPV6 dual addresses are not permitted Description:: + -- -HybridOverlayConfig configures an additional overlay network for peers that are +hybridOverlayConfig configures an additional overlay network for peers that are not using OVN. -- @@ -808,7 +856,7 @@ Type:: | `hybridClusterNetwork` | `array` -| HybridClusterNetwork defines a network space given to nodes on an additional overlay network. +| hybridClusterNetwork defines a network space given to nodes on an additional overlay network. | `hybridClusterNetwork[]` | `object` @@ -819,7 +867,7 @@ Not all network providers support multiple ClusterNetworks | `hybridOverlayVXLANPort` | `integer` -| HybridOverlayVXLANPort defines the VXLAN port number to be used by the additional overlay network. +| hybridOverlayVXLANPort defines the VXLAN port number to be used by the additional overlay network. Default is 4789 |=== @@ -827,7 +875,7 @@ Default is 4789 Description:: + -- -HybridClusterNetwork defines a network space given to nodes on an additional overlay network. +hybridClusterNetwork defines a network space given to nodes on an additional overlay network. -- Type:: @@ -883,6 +931,12 @@ Type:: |=== | Property | Type | Description +| `full` +| `object` +| full defines configuration parameters for the IPsec `Full` mode. +This is permitted only when mode is configured with `Full`, +and forbidden otherwise. + | `mode` | `string` | mode defines the behaviour of the ipsec configuration within the platform. @@ -894,6 +948,37 @@ When 'Full', ipsec is configured on the node level and inter-pod secure communic Note with `Full`, if ipsec is desired for communication with external (to the cluster) entities (such as storage arrays), this is left to the user to configure. +|=== +=== .spec.defaultNetwork.ovnKubernetesConfig.ipsecConfig.full +Description:: ++ +-- +full defines configuration parameters for the IPsec `Full` mode. +This is permitted only when mode is configured with `Full`, +and forbidden otherwise. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `encapsulation` +| `string` +| encapsulation option to configure libreswan on how inter-pod traffic across nodes +are encapsulated to handle NAT traversal. When configured it uses UDP port 4500 +for the encapsulation. +Valid values are Always, Auto and omitted. +Always means enable UDP encapsulation regardless of whether NAT is detected. +Auto means enable UDP encapsulation based on the detection of NAT. +When omitted, this means no opinion and the platform is left to choose a reasonable +default, which is subject to change over time. The current default is Auto. + |=== === .spec.defaultNetwork.ovnKubernetesConfig.ipv4 Description:: @@ -967,7 +1052,7 @@ any other subnet being used by OpenShift or by the node network. The size of the subnet must be larger than the number of nodes. The value cannot be changed after installation. The subnet must be large enough to accomadate one IP per node in your cluster -The current default value is fd98::/48 +The current default value is fd98::/64 The value must be in proper IPV6 CIDR format Note that IPV6 dual addresses are not permitted diff --git a/rest_api/operator_apis/operator-apis-index.adoc b/rest_api/operator_apis/operator-apis-index.adoc index 56fb6dc6b0..f629fed267 100644 --- a/rest_api/operator_apis/operator-apis-index.adoc +++ b/rest_api/operator_apis/operator-apis-index.adoc @@ -25,8 +25,9 @@ Type:: Description:: + -- -CloudCredential provides a means to configure an operator to manage CredentialsRequests. - Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). +CloudCredential provides a means to configure an operator to manage CredentialsRequests. + +Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- Type:: @@ -368,8 +369,9 @@ Type:: Description:: + -- -ServiceCA provides information to configure an operator to manage the service cert controllers - Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). +ServiceCA provides information to configure an operator to manage the service cert controllers + +Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- Type:: diff --git a/rest_api/operator_apis/serviceca-operator-openshift-io-v1.adoc b/rest_api/operator_apis/serviceca-operator-openshift-io-v1.adoc index 546be66f5b..ae14ef1874 100644 --- a/rest_api/operator_apis/serviceca-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/serviceca-operator-openshift-io-v1.adoc @@ -11,8 +11,9 @@ toc::[] Description:: + -- -ServiceCA provides information to configure an operator to manage the service cert controllers - Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). +ServiceCA provides information to configure an operator to manage the service cert controllers + +Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- Type:: @@ -68,8 +69,11 @@ Type:: | `logLevel` | `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". +| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a +simple way to manage coarse grained logging choices that operators have to interpret for their operands. + +Valid values are: "Normal", "Debug", "Trace", "TraceAll". +Defaults to "Normal". | `managementState` | `string` @@ -77,16 +81,24 @@ Type:: | `observedConfig` | `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator +| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because +it is an input to the level for the operator | `operatorLogLevel` | `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". +| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a +simple way to manage coarse grained logging choices that operators have to interpret for themselves. + +Valid values are: "Normal", "Debug", "Trace", "TraceAll". +Defaults to "Normal". | `unsupportedConfigOverrides` | `` -| unsupportedConfigOverrides overrides the final configuration that was computed by the operator. Red Hat does not support the use of this field. Misuse of this field could lead to unexpected behavior or conflict with other configuration options. Seek guidance from the Red Hat support before using this field. Use of this property blocks cluster upgrades, it must be removed before upgrading your cluster. +| unsupportedConfigOverrides overrides the final configuration that was computed by the operator. +Red Hat does not support the use of this field. +Misuse of this field could lead to unexpected behavior or conflict with other configuration options. +Seek guidance from the Red Hat support before using this field. +Use of this property blocks cluster upgrades, it must be removed before upgrading your cluster. |=== === .status @@ -122,6 +134,10 @@ Type:: | `object` | GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. +| `latestAvailableRevision` +| `integer` +| latestAvailableRevision is the deploymentID of the most recent deployment + | `observedGeneration` | `integer` | observedGeneration is the last generation change you've dealt with @@ -158,6 +174,10 @@ OperatorCondition is just the standard condition fields. Type:: `object` +Required:: + - `lastTransitionTime` + - `status` + - `type` @@ -167,7 +187,8 @@ Type:: | `lastTransitionTime` | `string` -| +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. | `message` | `string` @@ -179,11 +200,11 @@ Type:: | `status` | `string` -| +| status of the condition, one of True, False, Unknown. | `type` | `string` -| +| type of condition in CamelCase or in foo.example.com/CamelCase. |=== === .status.generations @@ -209,6 +230,11 @@ GenerationStatus keeps track of the generation for a given resource so that deci Type:: `object` +Required:: + - `group` + - `name` + - `namespace` + - `resource` diff --git a/rest_api/operator_apis/storage-operator-openshift-io-v1.adoc b/rest_api/operator_apis/storage-operator-openshift-io-v1.adoc index b1dd77ee30..53fdb570ab 100644 --- a/rest_api/operator_apis/storage-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/storage-operator-openshift-io-v1.adoc @@ -102,7 +102,7 @@ Use of this property blocks cluster upgrades, it must be removed before upgradin | `vsphereStorageDriver` | `string` -| VSphereStorageDriver indicates the storage driver to use on VSphere clusters. +| vsphereStorageDriver indicates the storage driver to use on VSphere clusters. Once this field is set to CSIWithMigrationDriver, it can not be changed. If this is empty, the platform will choose a good default, which may change over time without notice. diff --git a/rest_api/operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc b/rest_api/operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc index 9820aaf63b..5aa2e79df6 100644 --- a/rest_api/operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc +++ b/rest_api/operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc @@ -201,7 +201,7 @@ will be configured as if `restricted` was specified. Otherwise, it will be confi specified. Specifying a value other than `legacy` or `restricted` result in a validation error. When using older catalog images, which can not run in `restricted` mode, the SecurityContextConfig should be set to `legacy`. -More information about PSA can be found here: https://kubernetes.io/docs/concepts/security/pod-security-admission/' +More information about PSA can be found here: https://kubernetes.io/docs/concepts/security/pod-security-admission/ | `tolerations` | `array` diff --git a/rest_api/operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc b/rest_api/operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc new file mode 100644 index 0000000000..eaf1cab211 --- /dev/null +++ b/rest_api/operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc @@ -0,0 +1,840 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="clustercatalog-olm-operatorframework-io-v1"] += ClusterCatalog [olm.operatorframework.io/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster. +For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs +-- + +Type:: + `object` + +Required:: + - `metadata` + - `spec` + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| spec is the desired state of the ClusterCatalog. +spec is required. +The controller will work to ensure that the desired +catalog is unpacked and served over the catalog content HTTP server. + +| `status` +| `object` +| status contains information about the state of the ClusterCatalog such as: + - Whether or not the catalog contents are being served via the catalog content HTTP server + - Whether or not the ClusterCatalog is progressing to a new state + - A reference to the source from which the catalog contents were retrieved + +|=== +=== .spec +Description:: ++ +-- +spec is the desired state of the ClusterCatalog. +spec is required. +The controller will work to ensure that the desired +catalog is unpacked and served over the catalog content HTTP server. +-- + +Type:: + `object` + +Required:: + - `source` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `availabilityMode` +| `string` +| availabilityMode allows users to define how the ClusterCatalog is made available to clients on the cluster. +availabilityMode is optional. + +Allowed values are "Available" and "Unavailable" and omitted. + +When omitted, the default value is "Available". + +When set to "Available", the catalog contents will be unpacked and served over the catalog content HTTP server. +Setting the availabilityMode to "Available" tells clients that they should consider this ClusterCatalog +and its contents as usable. + +When set to "Unavailable", the catalog contents will no longer be served over the catalog content HTTP server. +When set to this availabilityMode it should be interpreted the same as the ClusterCatalog not existing. +Setting the availabilityMode to "Unavailable" can be useful in scenarios where a user may not want +to delete the ClusterCatalog all together, but would still like it to be treated as if it doesn't exist. + +| `priority` +| `integer` +| priority allows the user to define a priority for a ClusterCatalog. +priority is optional. + +A ClusterCatalog's priority is used by clients as a tie-breaker between ClusterCatalogs that meet the client's requirements. +A higher number means higher priority. + +It is up to clients to decide how to handle scenarios where multiple ClusterCatalogs with the same priority meet their requirements. +When deciding how to break the tie in this scenario, it is recommended that clients prompt their users for additional input. + +When omitted, the default priority is 0 because that is the zero value of integers. + +Negative numbers can be used to specify a priority lower than the default. +Positive numbers can be used to specify a priority higher than the default. + +The lowest possible value is -2147483648. +The highest possible value is 2147483647. + +| `source` +| `object` +| source allows a user to define the source of a catalog. +A "catalog" contains information on content that can be installed on a cluster. +Providing a catalog source makes the contents of the catalog discoverable and usable by +other on-cluster components. +These on-cluster components may do a variety of things with this information, such as +presenting the content in a GUI dashboard or installing content from the catalog on the cluster. +The catalog source must contain catalog metadata in the File-Based Catalog (FBC) format. +For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs. +source is a required field. + +Below is a minimal example of a ClusterCatalogSpec that sources a catalog from an image: + + source: + type: Image + image: + ref: quay.io/operatorhubio/catalog:latest + +|=== +=== .spec.source +Description:: ++ +-- +source allows a user to define the source of a catalog. +A "catalog" contains information on content that can be installed on a cluster. +Providing a catalog source makes the contents of the catalog discoverable and usable by +other on-cluster components. +These on-cluster components may do a variety of things with this information, such as +presenting the content in a GUI dashboard or installing content from the catalog on the cluster. +The catalog source must contain catalog metadata in the File-Based Catalog (FBC) format. +For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs. +source is a required field. + +Below is a minimal example of a ClusterCatalogSpec that sources a catalog from an image: + + source: + type: Image + image: + ref: quay.io/operatorhubio/catalog:latest +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `image` +| `object` +| image is used to configure how catalog contents are sourced from an OCI image. +This field is required when type is Image, and forbidden otherwise. + +| `type` +| `string` +| type is a reference to the type of source the catalog is sourced from. +type is required. + +The only allowed value is "Image". + +When set to "Image", the ClusterCatalog content will be sourced from an OCI image. +When using an image source, the image field must be set and must be the only field defined for this type. + +|=== +=== .spec.source.image +Description:: ++ +-- +image is used to configure how catalog contents are sourced from an OCI image. +This field is required when type is Image, and forbidden otherwise. +-- + +Type:: + `object` + +Required:: + - `ref` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `pollIntervalMinutes` +| `integer` +| pollIntervalMinutes allows the user to set the interval, in minutes, at which the image source should be polled for new content. +pollIntervalMinutes is optional. +pollIntervalMinutes can not be specified when ref is a digest-based reference. + +When omitted, the image will not be polled for new content. + +| `ref` +| `string` +| ref allows users to define the reference to a container image containing Catalog contents. +ref is required. +ref can not be more than 1000 characters. + +A reference can be broken down into 3 parts - the domain, name, and identifier. + +The domain is typically the registry where an image is located. +It must be alphanumeric characters (lowercase and uppercase) separated by the "." character. +Hyphenation is allowed, but the domain must start and end with alphanumeric characters. +Specifying a port to use is also allowed by adding the ":" character followed by numeric values. +The port must be the last value in the domain. +Some examples of valid domain values are "registry.mydomain.io", "quay.io", "my-registry.io:8080". + +The name is typically the repository in the registry where an image is located. +It must contain lowercase alphanumeric characters separated only by the ".", "_", "__", "-" characters. +Multiple names can be concatenated with the "/" character. +The domain and name are combined using the "/" character. +Some examples of valid name values are "operatorhubio/catalog", "catalog", "my-catalog.prod". +An example of the domain and name parts of a reference being combined is "quay.io/operatorhubio/catalog". + +The identifier is typically the tag or digest for an image reference and is present at the end of the reference. +It starts with a separator character used to distinguish the end of the name and beginning of the identifier. +For a digest-based reference, the "@" character is the separator. +For a tag-based reference, the ":" character is the separator. +An identifier is required in the reference. + +Digest-based references must contain an algorithm reference immediately after the "@" separator. +The algorithm reference must be followed by the ":" character and an encoded string. +The algorithm must start with an uppercase or lowercase alpha character followed by alphanumeric characters and may contain the "-", "_", "+", and "." characters. +Some examples of valid algorithm values are "sha256", "sha256+b64u", "multihash+base58". +The encoded string following the algorithm must be hex digits (a-f, A-F, 0-9) and must be a minimum of 32 characters. + +Tag-based references must begin with a word character (alphanumeric + "_") followed by word characters or ".", and "-" characters. +The tag must not be longer than 127 characters. + +An example of a valid digest-based image reference is "quay.io/operatorhubio/catalog@sha256:200d4ddb2a73594b91358fe6397424e975205bfbe44614f5846033cad64b3f05" +An example of a valid tag-based image reference is "quay.io/operatorhubio/catalog:latest" + +|=== +=== .status +Description:: ++ +-- +status contains information about the state of the ClusterCatalog such as: + - Whether or not the catalog contents are being served via the catalog content HTTP server + - Whether or not the ClusterCatalog is progressing to a new state + - A reference to the source from which the catalog contents were retrieved +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| conditions is a representation of the current state for this ClusterCatalog. + +The current condition types are Serving and Progressing. + +The Serving condition is used to represent whether or not the contents of the catalog is being served via the HTTP(S) web server. +When it has a status of True and a reason of Available, the contents of the catalog are being served. +When it has a status of False and a reason of Unavailable, the contents of the catalog are not being served because the contents are not yet available. +When it has a status of False and a reason of UserSpecifiedUnavailable, the contents of the catalog are not being served because the catalog has been intentionally marked as unavailable. + +The Progressing condition is used to represent whether or not the ClusterCatalog is progressing or is ready to progress towards a new state. +When it has a status of True and a reason of Retrying, there was an error in the progression of the ClusterCatalog that may be resolved on subsequent reconciliation attempts. +When it has a status of True and a reason of Succeeded, the ClusterCatalog has successfully progressed to a new state and is ready to continue progressing. +When it has a status of False and a reason of Blocked, there was an error in the progression of the ClusterCatalog that requires manual intervention for recovery. + +In the case that the Serving condition is True with reason Available and Progressing is True with reason Retrying, the previously fetched +catalog contents are still being served via the HTTP(S) web server while we are progressing towards serving a new version of the catalog +contents. This could occur when we've initially fetched the latest contents from the source for this catalog and when polling for changes +to the contents we identify that there are updates to the contents. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `lastUnpacked` +| `string` +| lastUnpacked represents the last time the contents of the +catalog were extracted from their source format. As an example, +when using an Image source, the OCI image will be pulled and the +image layers written to a file-system backed cache. We refer to the +act of this extraction from the source format as "unpacking". + +| `resolvedSource` +| `object` +| resolvedSource contains information about the resolved source based on the source type. + +| `urls` +| `object` +| urls contains the URLs that can be used to access the catalog. + +|=== +=== .status.conditions +Description:: ++ +-- +conditions is a representation of the current state for this ClusterCatalog. + +The current condition types are Serving and Progressing. + +The Serving condition is used to represent whether or not the contents of the catalog is being served via the HTTP(S) web server. +When it has a status of True and a reason of Available, the contents of the catalog are being served. +When it has a status of False and a reason of Unavailable, the contents of the catalog are not being served because the contents are not yet available. +When it has a status of False and a reason of UserSpecifiedUnavailable, the contents of the catalog are not being served because the catalog has been intentionally marked as unavailable. + +The Progressing condition is used to represent whether or not the ClusterCatalog is progressing or is ready to progress towards a new state. +When it has a status of True and a reason of Retrying, there was an error in the progression of the ClusterCatalog that may be resolved on subsequent reconciliation attempts. +When it has a status of True and a reason of Succeeded, the ClusterCatalog has successfully progressed to a new state and is ready to continue progressing. +When it has a status of False and a reason of Blocked, there was an error in the progression of the ClusterCatalog that requires manual intervention for recovery. + +In the case that the Serving condition is True with reason Available and Progressing is True with reason Retrying, the previously fetched +catalog contents are still being served via the HTTP(S) web server while we are progressing towards serving a new version of the catalog +contents. This could occur when we've initially fetched the latest contents from the source for this catalog and when polling for changes +to the contents we identify that there are updates to the contents. +-- + +Type:: + `array` + + + + +=== .status.conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== +=== .status.resolvedSource +Description:: ++ +-- +resolvedSource contains information about the resolved source based on the source type. +-- + +Type:: + `object` + +Required:: + - `image` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `image` +| `object` +| image is a field containing resolution information for a catalog sourced from an image. +This field must be set when type is Image, and forbidden otherwise. + +| `type` +| `string` +| type is a reference to the type of source the catalog is sourced from. +type is required. + +The only allowed value is "Image". + +When set to "Image", information about the resolved image source will be set in the 'image' field. + +|=== +=== .status.resolvedSource.image +Description:: ++ +-- +image is a field containing resolution information for a catalog sourced from an image. +This field must be set when type is Image, and forbidden otherwise. +-- + +Type:: + `object` + +Required:: + - `ref` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `ref` +| `string` +| ref contains the resolved image digest-based reference. +The digest format is used so users can use other tooling to fetch the exact +OCI manifests that were used to extract the catalog contents. + +|=== +=== .status.urls +Description:: ++ +-- +urls contains the URLs that can be used to access the catalog. +-- + +Type:: + `object` + +Required:: + - `base` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `base` +| `string` +| base is a cluster-internal URL that provides endpoints for +accessing the content of the catalog. + +It is expected that clients append the path for the endpoint they wish +to access. + +Currently, only a single endpoint is served and is accessible at the path +/api/v1. + +The endpoints served for the v1 API are: + - /all - this endpoint returns the entirety of the catalog contents in the FBC format + +As the needs of users and clients of the evolve, new endpoints may be added. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/olm.operatorframework.io/v1/clustercatalogs` +- `DELETE`: delete collection of ClusterCatalog +- `GET`: list objects of kind ClusterCatalog +- `POST`: create a ClusterCatalog +* `/apis/olm.operatorframework.io/v1/clustercatalogs/{name}` +- `DELETE`: delete a ClusterCatalog +- `GET`: read the specified ClusterCatalog +- `PATCH`: partially update the specified ClusterCatalog +- `PUT`: replace the specified ClusterCatalog +* `/apis/olm.operatorframework.io/v1/clustercatalogs/{name}/status` +- `GET`: read status of the specified ClusterCatalog +- `PATCH`: partially update status of the specified ClusterCatalog +- `PUT`: replace status of the specified ClusterCatalog + + +=== /apis/olm.operatorframework.io/v1/clustercatalogs + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of ClusterCatalog + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind ClusterCatalog + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-operatorframework-olm-v1-ClusterCatalogList[`ClusterCatalogList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a ClusterCatalog + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 201 - Created +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 202 - Accepted +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/olm.operatorframework.io/v1/clustercatalogs/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ClusterCatalog +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a ClusterCatalog + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified ClusterCatalog + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified ClusterCatalog + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified ClusterCatalog + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 201 - Created +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/olm.operatorframework.io/v1/clustercatalogs/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ClusterCatalog +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified ClusterCatalog + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified ClusterCatalog + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified ClusterCatalog + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 201 - Created +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[`ClusterCatalog`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc b/rest_api/operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc new file mode 100644 index 0000000000..1e25dc470a --- /dev/null +++ b/rest_api/operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc @@ -0,0 +1,1118 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="clusterextension-olm-operatorframework-io-v1"] += ClusterExtension [olm.operatorframework.io/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +ClusterExtension is the Schema for the clusterextensions API +-- + +Type:: + `object` + + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| spec is an optional field that defines the desired state of the ClusterExtension. + +| `status` +| `object` +| status is an optional field that defines the observed state of the ClusterExtension. + +|=== +=== .spec +Description:: ++ +-- +spec is an optional field that defines the desired state of the ClusterExtension. +-- + +Type:: + `object` + +Required:: + - `namespace` + - `serviceAccount` + - `source` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `install` +| `object` +| install is an optional field used to configure the installation options +for the ClusterExtension such as the pre-flight check configuration. + +| `namespace` +| `string` +| namespace is a reference to a Kubernetes namespace. +This is the namespace in which the provided ServiceAccount must exist. +It also designates the default namespace where namespace-scoped resources +for the extension are applied to the cluster. +Some extensions may contain namespace-scoped resources to be applied in other namespaces. +This namespace must exist. + +namespace is required, immutable, and follows the DNS label standard +as defined in [RFC 1123]. It must contain only lowercase alphanumeric characters or hyphens (-), +start and end with an alphanumeric character, and be no longer than 63 characters + +[RFC 1123]: https://tools.ietf.org/html/rfc1123 + +| `serviceAccount` +| `object` +| serviceAccount is a reference to a ServiceAccount used to perform all interactions +with the cluster that are required to manage the extension. +The ServiceAccount must be configured with the necessary permissions to perform these interactions. +The ServiceAccount must exist in the namespace referenced in the spec. +serviceAccount is required. + +| `source` +| `object` +| source is a required field which selects the installation source of content +for this ClusterExtension. Selection is performed by setting the sourceType. + +Catalog is currently the only implemented sourceType, and setting the +sourcetype to "Catalog" requires the catalog field to also be defined. + +Below is a minimal example of a source definition (in yaml): + +source: + sourceType: Catalog + catalog: + packageName: example-package + +|=== +=== .spec.install +Description:: ++ +-- +install is an optional field used to configure the installation options +for the ClusterExtension such as the pre-flight check configuration. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `preflight` +| `object` +| preflight is an optional field that can be used to configure the checks that are +run before installation or upgrade of the content for the package specified in the packageName field. + +When specified, it replaces the default preflight configuration for install/upgrade actions. +When not specified, the default configuration will be used. + +|=== +=== .spec.install.preflight +Description:: ++ +-- +preflight is an optional field that can be used to configure the checks that are +run before installation or upgrade of the content for the package specified in the packageName field. + +When specified, it replaces the default preflight configuration for install/upgrade actions. +When not specified, the default configuration will be used. +-- + +Type:: + `object` + +Required:: + - `crdUpgradeSafety` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `crdUpgradeSafety` +| `object` +| crdUpgradeSafety is used to configure the CRD Upgrade Safety pre-flight +checks that run prior to upgrades of installed content. + +The CRD Upgrade Safety pre-flight check safeguards from unintended +consequences of upgrading a CRD, such as data loss. + +|=== +=== .spec.install.preflight.crdUpgradeSafety +Description:: ++ +-- +crdUpgradeSafety is used to configure the CRD Upgrade Safety pre-flight +checks that run prior to upgrades of installed content. + +The CRD Upgrade Safety pre-flight check safeguards from unintended +consequences of upgrading a CRD, such as data loss. +-- + +Type:: + `object` + +Required:: + - `enforcement` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `enforcement` +| `string` +| enforcement is a required field, used to configure the state of the CRD Upgrade Safety pre-flight check. + +Allowed values are "None" or "Strict". The default value is "Strict". + +When set to "None", the CRD Upgrade Safety pre-flight check will be skipped +when performing an upgrade operation. This should be used with caution as +unintended consequences such as data loss can occur. + +When set to "Strict", the CRD Upgrade Safety pre-flight check will be run when +performing an upgrade operation. + +|=== +=== .spec.serviceAccount +Description:: ++ +-- +serviceAccount is a reference to a ServiceAccount used to perform all interactions +with the cluster that are required to manage the extension. +The ServiceAccount must be configured with the necessary permissions to perform these interactions. +The ServiceAccount must exist in the namespace referenced in the spec. +serviceAccount is required. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is a required, immutable reference to the name of the ServiceAccount +to be used for installation and management of the content for the package +specified in the packageName field. + +This ServiceAccount must exist in the installNamespace. + +name follows the DNS subdomain standard as defined in [RFC 1123]. +It must contain only lowercase alphanumeric characters, +hyphens (-) or periods (.), start and end with an alphanumeric character, +and be no longer than 253 characters. + +Some examples of valid values are: + - some-serviceaccount + - 123-serviceaccount + - 1-serviceaccount-2 + - someserviceaccount + - some.serviceaccount + +Some examples of invalid values are: + - -some-serviceaccount + - some-serviceaccount- + +[RFC 1123]: https://tools.ietf.org/html/rfc1123 + +|=== +=== .spec.source +Description:: ++ +-- +source is a required field which selects the installation source of content +for this ClusterExtension. Selection is performed by setting the sourceType. + +Catalog is currently the only implemented sourceType, and setting the +sourcetype to "Catalog" requires the catalog field to also be defined. + +Below is a minimal example of a source definition (in yaml): + +source: + sourceType: Catalog + catalog: + packageName: example-package +-- + +Type:: + `object` + +Required:: + - `sourceType` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `catalog` +| `object` +| catalog is used to configure how information is sourced from a catalog. +This field is required when sourceType is "Catalog", and forbidden otherwise. + +| `sourceType` +| `string` +| sourceType is a required reference to the type of install source. + +Allowed values are "Catalog" + +When this field is set to "Catalog", information for determining the +appropriate bundle of content to install will be fetched from +ClusterCatalog resources existing on the cluster. +When using the Catalog sourceType, the catalog field must also be set. + +|=== +=== .spec.source.catalog +Description:: ++ +-- +catalog is used to configure how information is sourced from a catalog. +This field is required when sourceType is "Catalog", and forbidden otherwise. +-- + +Type:: + `object` + +Required:: + - `packageName` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `channels` +| `array (string)` +| channels is an optional reference to a set of channels belonging to +the package specified in the packageName field. + +A "channel" is a package-author-defined stream of updates for an extension. + +Each channel in the list must follow the DNS subdomain standard +as defined in [RFC 1123]. It must contain only lowercase alphanumeric characters, +hyphens (-) or periods (.), start and end with an alphanumeric character, +and be no longer than 253 characters. No more than 256 channels can be specified. + +When specified, it is used to constrain the set of installable bundles and +the automated upgrade path. This constraint is an AND operation with the +version field. For example: + - Given channel is set to "foo" + - Given version is set to ">=1.0.0, <1.5.0" + - Only bundles that exist in channel "foo" AND satisfy the version range comparison will be considered installable + - Automatic upgrades will be constrained to upgrade edges defined by the selected channel + +When unspecified, upgrade edges across all channels will be used to identify valid automatic upgrade paths. + +Some examples of valid values are: + - 1.1.x + - alpha + - stable + - stable-v1 + - v1-stable + - dev-preview + - preview + - community + +Some examples of invalid values are: + - -some-channel + - some-channel- + - thisisareallylongchannelnamethatisgreaterthanthemaximumlength + - original_40 + - --default-channel + +[RFC 1123]: https://tools.ietf.org/html/rfc1123 + +| `packageName` +| `string` +| packageName is a reference to the name of the package to be installed +and is used to filter the content from catalogs. + +packageName is required, immutable, and follows the DNS subdomain standard +as defined in [RFC 1123]. It must contain only lowercase alphanumeric characters, +hyphens (-) or periods (.), start and end with an alphanumeric character, +and be no longer than 253 characters. + +Some examples of valid values are: + - some-package + - 123-package + - 1-package-2 + - somepackage + +Some examples of invalid values are: + - -some-package + - some-package- + - thisisareallylongpackagenamethatisgreaterthanthemaximumlength + - some.package + +[RFC 1123]: https://tools.ietf.org/html/rfc1123 + +| `selector` +| `object` +| selector is an optional field that can be used +to filter the set of ClusterCatalogs used in the bundle +selection process. + +When unspecified, all ClusterCatalogs will be used in +the bundle selection process. + +| `upgradeConstraintPolicy` +| `string` +| upgradeConstraintPolicy is an optional field that controls whether +the upgrade path(s) defined in the catalog are enforced for the package +referenced in the packageName field. + +Allowed values are: "CatalogProvided" or "SelfCertified", or omitted. + +When this field is set to "CatalogProvided", automatic upgrades will only occur +when upgrade constraints specified by the package author are met. + +When this field is set to "SelfCertified", the upgrade constraints specified by +the package author are ignored. This allows for upgrades and downgrades to +any version of the package. This is considered a dangerous operation as it +can lead to unknown and potentially disastrous outcomes, such as data +loss. It is assumed that users have independently verified changes when +using this option. + +When this field is omitted, the default value is "CatalogProvided". + +| `version` +| `string` +| version is an optional semver constraint (a specific version or range of versions). When unspecified, the latest version available will be installed. + +Acceptable version ranges are no longer than 64 characters. +Version ranges are composed of comma- or space-delimited values and one or +more comparison operators, known as comparison strings. Additional +comparison strings can be added using the OR operator (\|\|). + +# Range Comparisons + +To specify a version range, you can use a comparison string like ">=3.0, +<3.6". When specifying a range, automatic updates will occur within that +range. The example comparison string means "install any version greater than +or equal to 3.0.0 but less than 3.6.0.". It also states intent that if any +upgrades are available within the version range after initial installation, +those upgrades should be automatically performed. + +# Pinned Versions + +To specify an exact version to install you can use a version range that +"pins" to a specific version. When pinning to a specific version, no +automatic updates will occur. An example of a pinned version range is +"0.6.0", which means "only install version 0.6.0 and never +upgrade from this version". + +# Basic Comparison Operators + +The basic comparison operators and their meanings are: + - "=", equal (not aliased to an operator) + - "!=", not equal + - "<", less than + - ">", greater than + - ">=", greater than OR equal to + - "<=", less than OR equal to + +# Wildcard Comparisons + +You can use the "x", "X", and "*" characters as wildcard characters in all +comparison operations. Some examples of using the wildcard characters: + - "1.2.x", "1.2.X", and "1.2.*" is equivalent to ">=1.2.0, < 1.3.0" + - ">= 1.2.x", ">= 1.2.X", and ">= 1.2.*" is equivalent to ">= 1.2.0" + - "<= 2.x", "<= 2.X", and "<= 2.*" is equivalent to "< 3" + - "x", "X", and "*" is equivalent to ">= 0.0.0" + +# Patch Release Comparisons + +When you want to specify a minor version up to the next major version you +can use the "~" character to perform patch comparisons. Some examples: + - "~1.2.3" is equivalent to ">=1.2.3, <1.3.0" + - "~1" and "~1.x" is equivalent to ">=1, <2" + - "~2.3" is equivalent to ">=2.3, <2.4" + - "~1.2.x" is equivalent to ">=1.2.0, <1.3.0" + +# Major Release Comparisons + +You can use the "^" character to make major release comparisons after a +stable 1.0.0 version is published. If there is no stable version published, // minor versions define the stability level. Some examples: + - "^1.2.3" is equivalent to ">=1.2.3, <2.0.0" + - "^1.2.x" is equivalent to ">=1.2.0, <2.0.0" + - "^2.3" is equivalent to ">=2.3, <3" + - "^2.x" is equivalent to ">=2.0.0, <3" + - "^0.2.3" is equivalent to ">=0.2.3, <0.3.0" + - "^0.2" is equivalent to ">=0.2.0, <0.3.0" + - "^0.0.3" is equvalent to ">=0.0.3, <0.0.4" + - "^0.0" is equivalent to ">=0.0.0, <0.1.0" + - "^0" is equivalent to ">=0.0.0, <1.0.0" + +# OR Comparisons +You can use the "\|\|" character to represent an OR operation in the version +range. Some examples: + - ">=1.2.3, <2.0.0 \|\| >3.0.0" + - "^0 \|\| ^3 \|\| ^5" + +For more information on semver, please see https://semver.org/ + +|=== +=== .spec.source.catalog.selector +Description:: ++ +-- +selector is an optional field that can be used +to filter the set of ClusterCatalogs used in the bundle +selection process. + +When unspecified, all ClusterCatalogs will be used in +the bundle selection process. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `matchExpressions` +| `array` +| matchExpressions is a list of label selector requirements. The requirements are ANDed. + +| `matchExpressions[]` +| `object` +| A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. + +| `matchLabels` +| `object (string)` +| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels +map is equivalent to an element of matchExpressions, whose key field is "key", the +operator is "In", and the values array contains only "value". The requirements are ANDed. + +|=== +=== .spec.source.catalog.selector.matchExpressions +Description:: ++ +-- +matchExpressions is a list of label selector requirements. The requirements are ANDed. +-- + +Type:: + `array` + + + + +=== .spec.source.catalog.selector.matchExpressions[] +Description:: ++ +-- +A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. +-- + +Type:: + `object` + +Required:: + - `key` + - `operator` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `key` +| `string` +| key is the label key that the selector applies to. + +| `operator` +| `string` +| operator represents a key's relationship to a set of values. +Valid operators are In, NotIn, Exists and DoesNotExist. + +| `values` +| `array (string)` +| values is an array of string values. If the operator is In or NotIn, +the values array must be non-empty. If the operator is Exists or DoesNotExist, +the values array must be empty. This array is replaced during a strategic +merge patch. + +|=== +=== .status +Description:: ++ +-- +status is an optional field that defines the observed state of the ClusterExtension. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| The set of condition types which apply to all spec.source variations are Installed and Progressing. + +The Installed condition represents whether or not the bundle has been installed for this ClusterExtension. +When Installed is True and the Reason is Succeeded, the bundle has been successfully installed. +When Installed is False and the Reason is Failed, the bundle has failed to install. + +The Progressing condition represents whether or not the ClusterExtension is advancing towards a new state. +When Progressing is True and the Reason is Succeeded, the ClusterExtension is making progress towards a new state. +When Progressing is True and the Reason is Retrying, the ClusterExtension has encountered an error that could be resolved on subsequent reconciliation attempts. +When Progressing is False and the Reason is Blocked, the ClusterExtension has encountered an error that requires manual intervention for recovery. + +When the ClusterExtension is sourced from a catalog, if may also communicate a deprecation condition. +These are indications from a package owner to guide users away from a particular package, channel, or bundle. +BundleDeprecated is set if the requested bundle version is marked deprecated in the catalog. +ChannelDeprecated is set if the requested channel is marked deprecated in the catalog. +PackageDeprecated is set if the requested package is marked deprecated in the catalog. +Deprecated is a rollup condition that is present when any of the deprecated conditions are present. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `install` +| `object` +| install is a representation of the current installation status for this ClusterExtension. + +|=== +=== .status.conditions +Description:: ++ +-- +The set of condition types which apply to all spec.source variations are Installed and Progressing. + +The Installed condition represents whether or not the bundle has been installed for this ClusterExtension. +When Installed is True and the Reason is Succeeded, the bundle has been successfully installed. +When Installed is False and the Reason is Failed, the bundle has failed to install. + +The Progressing condition represents whether or not the ClusterExtension is advancing towards a new state. +When Progressing is True and the Reason is Succeeded, the ClusterExtension is making progress towards a new state. +When Progressing is True and the Reason is Retrying, the ClusterExtension has encountered an error that could be resolved on subsequent reconciliation attempts. +When Progressing is False and the Reason is Blocked, the ClusterExtension has encountered an error that requires manual intervention for recovery. + +When the ClusterExtension is sourced from a catalog, if may also communicate a deprecation condition. +These are indications from a package owner to guide users away from a particular package, channel, or bundle. +BundleDeprecated is set if the requested bundle version is marked deprecated in the catalog. +ChannelDeprecated is set if the requested channel is marked deprecated in the catalog. +PackageDeprecated is set if the requested package is marked deprecated in the catalog. +Deprecated is a rollup condition that is present when any of the deprecated conditions are present. +-- + +Type:: + `array` + + + + +=== .status.conditions[] +Description:: ++ +-- +Condition contains details for one aspect of the current state of this API Resource. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `message` + - `reason` + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + +| `message` +| `string` +| message is a human readable message indicating details about the transition. +This may be an empty string. + +| `observedGeneration` +| `integer` +| observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + +| `reason` +| `string` +| reason contains a programmatic identifier indicating the reason for the condition's last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + +| `status` +| `string` +| status of the condition, one of True, False, Unknown. + +| `type` +| `string` +| type of condition in CamelCase or in foo.example.com/CamelCase. + +|=== +=== .status.install +Description:: ++ +-- +install is a representation of the current installation status for this ClusterExtension. +-- + +Type:: + `object` + +Required:: + - `bundle` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `bundle` +| `object` +| bundle is a required field which represents the identifying attributes of a bundle. + +A "bundle" is a versioned set of content that represents the resources that +need to be applied to a cluster to install a package. + +|=== +=== .status.install.bundle +Description:: ++ +-- +bundle is a required field which represents the identifying attributes of a bundle. + +A "bundle" is a versioned set of content that represents the resources that +need to be applied to a cluster to install a package. +-- + +Type:: + `object` + +Required:: + - `name` + - `version` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is required and follows the DNS subdomain standard +as defined in [RFC 1123]. It must contain only lowercase alphanumeric characters, +hyphens (-) or periods (.), start and end with an alphanumeric character, +and be no longer than 253 characters. + +| `version` +| `string` +| version is a required field and is a reference to the version that this bundle represents +version follows the semantic versioning standard as defined in https://semver.org/. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/olm.operatorframework.io/v1/clusterextensions` +- `DELETE`: delete collection of ClusterExtension +- `GET`: list objects of kind ClusterExtension +- `POST`: create a ClusterExtension +* `/apis/olm.operatorframework.io/v1/clusterextensions/{name}` +- `DELETE`: delete a ClusterExtension +- `GET`: read the specified ClusterExtension +- `PATCH`: partially update the specified ClusterExtension +- `PUT`: replace the specified ClusterExtension +* `/apis/olm.operatorframework.io/v1/clusterextensions/{name}/status` +- `GET`: read status of the specified ClusterExtension +- `PATCH`: partially update status of the specified ClusterExtension +- `PUT`: replace status of the specified ClusterExtension + + +=== /apis/olm.operatorframework.io/v1/clusterextensions + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of ClusterExtension + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind ClusterExtension + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-operatorframework-olm-v1-ClusterExtensionList[`ClusterExtensionList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a ClusterExtension + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 201 - Created +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 202 - Accepted +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/olm.operatorframework.io/v1/clusterextensions/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ClusterExtension +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a ClusterExtension + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified ClusterExtension + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified ClusterExtension + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified ClusterExtension + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 201 - Created +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/olm.operatorframework.io/v1/clusterextensions/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ClusterExtension +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified ClusterExtension + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified ClusterExtension + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified ClusterExtension + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 201 - Created +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[`ClusterExtension`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc b/rest_api/operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc index 617b178add..d22f8dc160 100644 --- a/rest_api/operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc +++ b/rest_api/operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc @@ -2315,6 +2315,18 @@ for the pod. It adds a name to it that uniquely identifies the ResourceClaim inside the Pod. Containers that need access to the ResourceClaim reference it with this name. +| `resources` +| `object` +| Resources is the total amount of CPU and Memory resources required by all +containers in the pod. It supports specifying Requests and Limits for +"cpu" and "memory" resource names only. ResourceClaims are not supported. + +This field enables fine-grained control over resource allocation for the +entire pod, allowing resource sharing among containers in a pod. + +This is an alpha field and requires enabling the PodLevelResources feature +gate. + | `restartPolicy` | `string` | Restart policy for all containers within the pod. @@ -4751,28 +4763,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.postStart.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -4798,7 +4810,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -4889,7 +4901,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -4914,8 +4926,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -4968,28 +4980,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.preStop.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -5015,7 +5027,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -5106,7 +5118,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -5131,8 +5143,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -5180,7 +5192,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -5189,11 +5201,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -5212,7 +5224,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -5238,7 +5250,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -5264,7 +5276,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -5295,7 +5307,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -5386,7 +5398,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -5500,7 +5512,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -5509,11 +5521,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -5532,7 +5544,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -5558,7 +5570,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -5584,7 +5596,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -5615,7 +5627,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -5706,7 +5718,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -6195,7 +6207,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -6204,11 +6216,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -6227,7 +6239,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -6253,7 +6265,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -6279,7 +6291,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -6310,7 +6322,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -6401,7 +6413,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -6636,11 +6648,12 @@ Type:: | `name` | `string` -| Required. +| Name is this DNS resolver option's name. +Required. | `value` | `string` -| +| Value is this DNS resolver option's value. |=== === .spec.install.spec.deployments[].spec.template.spec.ephemeralContainers @@ -7262,28 +7275,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.postStart.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -7309,7 +7322,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -7400,7 +7413,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -7425,8 +7438,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -7479,28 +7492,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.preStop.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -7526,7 +7539,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -7617,7 +7630,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -7642,8 +7655,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -7688,7 +7701,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -7697,11 +7710,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -7720,7 +7733,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -7746,7 +7759,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -7772,7 +7785,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -7803,7 +7816,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -7894,7 +7907,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -7999,7 +8012,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -8008,11 +8021,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -8031,7 +8044,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -8057,7 +8070,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -8083,7 +8096,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -8114,7 +8127,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -8205,7 +8218,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -8686,7 +8699,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -8695,11 +8708,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -8718,7 +8731,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -8744,7 +8757,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -8770,7 +8783,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -8801,7 +8814,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -8892,7 +8905,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -9782,28 +9795,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.postStart.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -9829,7 +9842,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -9920,7 +9933,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -9945,8 +9958,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -9999,28 +10012,28 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `sleep` | `object` -| Sleep represents the duration that the container should sleep before being terminated. +| Sleep represents a duration that the container should sleep. | `tcpSocket` | `object` | Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. |=== === .spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.preStop.exec Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -10046,7 +10059,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -10137,7 +10150,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -Sleep represents the duration that the container should sleep before being terminated. +Sleep represents a duration that the container should sleep. -- Type:: @@ -10162,8 +10175,8 @@ Description:: + -- Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept -for the backward compatibility. There are no validation of this field and -lifecycle hooks will fail in runtime when tcp handler is specified. +for backward compatibility. There is no validation of this field and +lifecycle hooks will fail at runtime when it is specified. -- Type:: @@ -10211,7 +10224,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -10220,11 +10233,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -10243,7 +10256,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -10269,7 +10282,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -10295,7 +10308,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -10326,7 +10339,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -10417,7 +10430,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -10531,7 +10544,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -10540,11 +10553,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -10563,7 +10576,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -10589,7 +10602,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -10615,7 +10628,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -10646,7 +10659,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -10737,7 +10750,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -11226,7 +11239,7 @@ Type:: | `exec` | `object` -| Exec specifies the action to take. +| Exec specifies a command to execute in the container. | `failureThreshold` | `integer` @@ -11235,11 +11248,11 @@ Defaults to 3. Minimum value is 1. | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPC specifies a GRPC HealthCheckRequest. | `httpGet` | `object` -| HTTPGet specifies the http request to perform. +| HTTPGet specifies an HTTP GET request to perform. | `initialDelaySeconds` | `integer` @@ -11258,7 +11271,7 @@ Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | `tcpSocket` | `object` -| TCPSocket specifies an action involving a TCP port. +| TCPSocket specifies a connection to a TCP port. | `terminationGracePeriodSeconds` | `integer` @@ -11284,7 +11297,7 @@ More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#cont Description:: + -- -Exec specifies the action to take. +Exec specifies a command to execute in the container. -- Type:: @@ -11310,7 +11323,7 @@ Exit status of 0 is treated as live/healthy and non-zero is unhealthy. Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPC specifies a GRPC HealthCheckRequest. -- Type:: @@ -11341,7 +11354,7 @@ If this is not specified, the default behavior is defined by gRPC. Description:: + -- -HTTPGet specifies the http request to perform. +HTTPGet specifies an HTTP GET request to perform. -- Type:: @@ -11432,7 +11445,7 @@ This will be canonicalized upon output, so case-variant names will be understood Description:: + -- -TCPSocket specifies an action involving a TCP port. +TCPSocket specifies a connection to a TCP port. -- Type:: @@ -11762,6 +11775,109 @@ ResourceClaim. Exactly one of ResourceClaimName and ResourceClaimTemplateName must be set. +|=== +=== .spec.install.spec.deployments[].spec.template.spec.resources +Description:: ++ +-- +Resources is the total amount of CPU and Memory resources required by all +containers in the pod. It supports specifying Requests and Limits for +"cpu" and "memory" resource names only. ResourceClaims are not supported. + +This field enables fine-grained control over resource allocation for the +entire pod, allowing resource sharing among containers in a pod. + +This is an alpha field and requires enabling the PodLevelResources feature +gate. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `claims` +| `array` +| Claims lists the names of resources, defined in spec.resourceClaims, +that are used by this container. + +This is an alpha field and requires enabling the +DynamicResourceAllocation feature gate. + +This field is immutable. It can only be set for containers. + +| `claims[]` +| `object` +| ResourceClaim references one entry in PodSpec.ResourceClaims. + +| `limits` +| `integer-or-string` +| Limits describes the maximum amount of compute resources allowed. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +| `requests` +| `integer-or-string` +| Requests describes the minimum amount of compute resources required. +If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, +otherwise to an implementation-defined value. Requests cannot exceed Limits. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +|=== +=== .spec.install.spec.deployments[].spec.template.spec.resources.claims +Description:: ++ +-- +Claims lists the names of resources, defined in spec.resourceClaims, +that are used by this container. + +This is an alpha field and requires enabling the +DynamicResourceAllocation feature gate. + +This field is immutable. It can only be set for containers. +-- + +Type:: + `array` + + + + +=== .spec.install.spec.deployments[].spec.template.spec.resources.claims[] +Description:: ++ +-- +ResourceClaim references one entry in PodSpec.ResourceClaims. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name must match the name of one entry in pod.spec.resourceClaims of +the Pod where this field is used. It makes that resource available +inside a container. + +| `request` +| `string` +| Request is the name chosen for a request in the referenced claim. +If empty, everything from the claim is made available, otherwise +only the result of this request. + |=== === .spec.install.spec.deployments[].spec.template.spec.schedulingGates Description:: @@ -11878,6 +11994,32 @@ PodSecurityContext, the value specified in SecurityContext takes precedence for that container. Note that this field cannot be set when spec.os.name is windows. +| `seLinuxChangePolicy` +| `string` +| seLinuxChangePolicy defines how the container's SELinux label is applied to all volumes used by the Pod. +It has no effect on nodes that do not support SELinux or to volumes does not support SELinux. +Valid values are "MountOption" and "Recursive". + +"Recursive" means relabeling of all files on all Pod volumes by the container runtime. +This may be slow for large volumes, but allows mixing privileged and unprivileged Pods sharing the same volume on the same node. + +"MountOption" mounts all eligible Pod volumes with `-o context` mount option. +This requires all Pods that share the same volume to use the same SELinux label. +It is not possible to share the same volume among privileged and unprivileged Pods. +Eligible volumes are in-tree FibreChannel and iSCSI volumes, and all CSI volumes +whose CSI driver announces SELinux support by setting spec.seLinuxMount: true in their +CSIDriver instance. Other volumes are always re-labelled recursively. +"MountOption" value is allowed only when SELinuxMount feature gate is enabled. + +If not specified and SELinuxMount feature gate is enabled, "MountOption" is used. +If not specified and SELinuxMount feature gate is disabled, "MountOption" is used for ReadWriteOncePod volumes +and "Recursive" for all other volumes. + +This field affects only Pods that have SELinux label set, either in PodSecurityContext or in SecurityContext of all containers. + +All Pods that use the same volume should use the same seLinuxChangePolicy, otherwise some pods can get stuck in ContainerCreating state. +Note that this field cannot be set when spec.os.name is windows. + | `seLinuxOptions` | `object` | The SELinux context to be applied to all containers. @@ -12468,23 +12610,32 @@ Required:: | `object` | awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree +awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore | `azureDisk` | `object` | azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type +are redirected to the disk.csi.azure.com CSI driver. | `azureFile` | `object` | azureFile represents an Azure File Service mount on the host and bind mount to the pod. +Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type +are redirected to the file.csi.azure.com CSI driver. | `cephfs` | `object` -| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. +Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. | `cinder` | `object` | cinder represents a cinder volume attached and mounted on kubelets host machine. +Deprecated: Cinder is deprecated. All operations for the in-tree cinder type +are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `configMap` @@ -12493,7 +12644,7 @@ More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `csi` | `object` -| csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). +| csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers. | `downwardAPI` | `object` @@ -12539,27 +12690,32 @@ persistent volumes at the same time. | `object` | flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. | `flocker` | `object` -| flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running +| flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running. +Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. | `gcePersistentDisk` | `object` | gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree +gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk | `gitRepo` | `object` | gitRepo represents a git repository at a particular revision. -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an +Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. | `glusterfs` | `object` | glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. +Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md | `hostPath` @@ -12612,11 +12768,15 @@ More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persis | `photonPersistentDisk` | `object` -| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. +Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. | `portworxVolume` | `object` -| portworxVolume represents a portworx volume attached and mounted on kubelets host machine +| portworxVolume represents a portworx volume attached and mounted on kubelets host machine. +Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type +are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate +is on. | `projected` | `object` @@ -12624,16 +12784,19 @@ More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persis | `quobyte` | `object` -| quobyte represents a Quobyte mount on the host that shares a pod's lifetime +| quobyte represents a Quobyte mount on the host that shares a pod's lifetime. +Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. | `rbd` | `object` | rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. +Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md | `scaleIO` | `object` | scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. | `secret` | `object` @@ -12643,10 +12806,13 @@ More info: https://kubernetes.io/docs/concepts/storage/volumes#secret | `storageos` | `object` | storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. +Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. | `vsphereVolume` | `object` -| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. +Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type +are redirected to the csi.vsphere.vmware.com CSI driver. |=== === .spec.install.spec.deployments[].spec.template.spec.volumes[].awsElasticBlockStore @@ -12655,6 +12821,8 @@ Description:: -- awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree +awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore -- @@ -12700,6 +12868,8 @@ Description:: + -- azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type +are redirected to the disk.csi.azure.com CSI driver. -- Type:: @@ -12748,6 +12918,8 @@ Description:: + -- azureFile represents an Azure File Service mount on the host and bind mount to the pod. +Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type +are redirected to the file.csi.azure.com CSI driver. -- Type:: @@ -12781,7 +12953,8 @@ the ReadOnly setting in VolumeMounts. Description:: + -- -cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. +Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. -- Type:: @@ -12859,6 +13032,8 @@ Description:: + -- cinder represents a cinder volume attached and mounted on kubelets host machine. +Deprecated: Cinder is deprecated. All operations for the in-tree cinder type +are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md -- @@ -13043,7 +13218,7 @@ May not start with the string '..'. Description:: + -- -csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). +csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers. -- Type:: @@ -13814,6 +13989,7 @@ Description:: -- flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. -- Type:: @@ -13890,7 +14066,8 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running +flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running. +Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. -- Type:: @@ -13919,6 +14096,8 @@ Description:: -- gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree +gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk -- @@ -13966,7 +14145,7 @@ Description:: + -- gitRepo represents a git repository at a particular revision. -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an +Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. -- @@ -14004,6 +14183,7 @@ Description:: + -- glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. +Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md -- @@ -14298,7 +14478,8 @@ Default false. Description:: + -- -photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. +Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. -- Type:: @@ -14328,7 +14509,10 @@ Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. Description:: + -- -portworxVolume represents a portworx volume attached and mounted on kubelets host machine +portworxVolume represents a portworx volume attached and mounted on kubelets host machine. +Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type +are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate +is on. -- Type:: @@ -15005,7 +15189,8 @@ token into. Description:: + -- -quobyte represents a Quobyte mount on the host that shares a pod's lifetime +quobyte represents a Quobyte mount on the host that shares a pod's lifetime. +Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. -- Type:: @@ -15057,6 +15242,7 @@ Description:: + -- rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. +Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md -- @@ -15156,6 +15342,7 @@ Description:: + -- scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. -- Type:: @@ -15364,6 +15551,7 @@ Description:: + -- storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. +Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. -- Type:: @@ -15438,7 +15626,9 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. +Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type +are redirected to the csi.vsphere.vmware.com CSI driver. -- Type:: diff --git a/rest_api/operatorhub_apis/operatorhub-apis-index.adoc b/rest_api/operatorhub_apis/operatorhub-apis-index.adoc index c93c4b584f..1725374968 100644 --- a/rest_api/operatorhub_apis/operatorhub-apis-index.adoc +++ b/rest_api/operatorhub_apis/operatorhub-apis-index.adoc @@ -15,6 +15,29 @@ Description:: CatalogSource is a repository of CSVs, CRDs, and operator packages. -- +Type:: + `object` + +== ClusterCatalog [olm.operatorframework.io/v1] + +Description:: ++ +-- +ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster. +For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs +-- + +Type:: + `object` + +== ClusterExtension [olm.operatorframework.io/v1] + +Description:: ++ +-- +ClusterExtension is the Schema for the clusterextensions API +-- + Type:: `object` diff --git a/rest_api/operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc b/rest_api/operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc index 30d963f91e..476ab863f0 100644 --- a/rest_api/operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc +++ b/rest_api/operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc @@ -2589,23 +2589,32 @@ Required:: | `object` | awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree +awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore | `azureDisk` | `object` | azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type +are redirected to the disk.csi.azure.com CSI driver. | `azureFile` | `object` | azureFile represents an Azure File Service mount on the host and bind mount to the pod. +Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type +are redirected to the file.csi.azure.com CSI driver. | `cephfs` | `object` -| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +| cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. +Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. | `cinder` | `object` | cinder represents a cinder volume attached and mounted on kubelets host machine. +Deprecated: Cinder is deprecated. All operations for the in-tree cinder type +are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `configMap` @@ -2614,7 +2623,7 @@ More info: https://examples.k8s.io/mysql-cinder-pd/README.md | `csi` | `object` -| csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). +| csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers. | `downwardAPI` | `object` @@ -2660,27 +2669,32 @@ persistent volumes at the same time. | `object` | flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. | `flocker` | `object` -| flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running +| flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running. +Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. | `gcePersistentDisk` | `object` | gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree +gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk | `gitRepo` | `object` | gitRepo represents a git repository at a particular revision. -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an +Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. | `glusterfs` | `object` | glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. +Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md | `hostPath` @@ -2733,11 +2747,15 @@ More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persis | `photonPersistentDisk` | `object` -| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +| photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. +Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. | `portworxVolume` | `object` -| portworxVolume represents a portworx volume attached and mounted on kubelets host machine +| portworxVolume represents a portworx volume attached and mounted on kubelets host machine. +Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type +are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate +is on. | `projected` | `object` @@ -2745,16 +2763,19 @@ More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persis | `quobyte` | `object` -| quobyte represents a Quobyte mount on the host that shares a pod's lifetime +| quobyte represents a Quobyte mount on the host that shares a pod's lifetime. +Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. | `rbd` | `object` | rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. +Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md | `scaleIO` | `object` | scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. | `secret` | `object` @@ -2764,10 +2785,13 @@ More info: https://kubernetes.io/docs/concepts/storage/volumes#secret | `storageos` | `object` | storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. +Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. | `vsphereVolume` | `object` -| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +| vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. +Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type +are redirected to the csi.vsphere.vmware.com CSI driver. |=== === .spec.config.volumes[].awsElasticBlockStore @@ -2776,6 +2800,8 @@ Description:: -- awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree +awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore -- @@ -2821,6 +2847,8 @@ Description:: + -- azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. +Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type +are redirected to the disk.csi.azure.com CSI driver. -- Type:: @@ -2869,6 +2897,8 @@ Description:: + -- azureFile represents an Azure File Service mount on the host and bind mount to the pod. +Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type +are redirected to the file.csi.azure.com CSI driver. -- Type:: @@ -2902,7 +2932,8 @@ the ReadOnly setting in VolumeMounts. Description:: + -- -cephFS represents a Ceph FS mount on the host that shares a pod's lifetime +cephFS represents a Ceph FS mount on the host that shares a pod's lifetime. +Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported. -- Type:: @@ -2980,6 +3011,8 @@ Description:: + -- cinder represents a cinder volume attached and mounted on kubelets host machine. +Deprecated: Cinder is deprecated. All operations for the in-tree cinder type +are redirected to the cinder.csi.openstack.org CSI driver. More info: https://examples.k8s.io/mysql-cinder-pd/README.md -- @@ -3164,7 +3197,7 @@ May not start with the string '..'. Description:: + -- -csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). +csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers. -- Type:: @@ -3935,6 +3968,7 @@ Description:: -- flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. +Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead. -- Type:: @@ -4011,7 +4045,8 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running +flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running. +Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported. -- Type:: @@ -4040,6 +4075,8 @@ Description:: -- gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. +Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree +gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk -- @@ -4087,7 +4124,7 @@ Description:: + -- gitRepo represents a git repository at a particular revision. -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an +Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. -- @@ -4125,6 +4162,7 @@ Description:: + -- glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. +Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported. More info: https://examples.k8s.io/volumes/glusterfs/README.md -- @@ -4419,7 +4457,8 @@ Default false. Description:: + -- -photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine +photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine. +Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported. -- Type:: @@ -4449,7 +4488,10 @@ Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. Description:: + -- -portworxVolume represents a portworx volume attached and mounted on kubelets host machine +portworxVolume represents a portworx volume attached and mounted on kubelets host machine. +Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type +are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate +is on. -- Type:: @@ -5126,7 +5168,8 @@ token into. Description:: + -- -quobyte represents a Quobyte mount on the host that shares a pod's lifetime +quobyte represents a Quobyte mount on the host that shares a pod's lifetime. +Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported. -- Type:: @@ -5178,6 +5221,7 @@ Description:: + -- rbd represents a Rados Block Device mount on the host that shares a pod's lifetime. +Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported. More info: https://examples.k8s.io/volumes/rbd/README.md -- @@ -5277,6 +5321,7 @@ Description:: + -- scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. +Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported. -- Type:: @@ -5485,6 +5530,7 @@ Description:: + -- storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. +Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported. -- Type:: @@ -5559,7 +5605,9 @@ More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/nam Description:: + -- -vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine +vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine. +Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type +are redirected to the csi.vsphere.vmware.com CSI driver. -- Type:: diff --git a/rest_api/overview/index.adoc b/rest_api/overview/index.adoc index 302dfc645a..9effdb230f 100644 --- a/rest_api/overview/index.adoc +++ b/rest_api/overview/index.adoc @@ -60,8 +60,12 @@ | cloud.network.openshift.io/v1 | xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[ClusterAutoscaler] | autoscaling.openshift.io/v1 +| xref:../operatorhub_apis/clustercatalog-olm-operatorframework-io-v1.adoc#clustercatalog-olm-operatorframework-io-v1[ClusterCatalog] +| olm.operatorframework.io/v1 | xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[ClusterCSIDriver] | operator.openshift.io/v1 +| xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[ClusterExtension] +| olm.operatorframework.io/v1 | xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[ClusterOperator] | config.openshift.io/v1 | xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[ClusterResourceQuota] @@ -76,6 +80,8 @@ | rbac.authorization.k8s.io/v1 | xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[ClusterServiceVersion] | operators.coreos.com/v1alpha1 +| xref:../network_apis/clusteruserdefinednetwork-k8s-ovn-org-v1.adoc#clusteruserdefinednetwork-k8s-ovn-org-v1[ClusterUserDefinedNetwork] +| k8s.ovn.org/v1 | xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[ClusterVersion] | config.openshift.io/v1 | xref:../metadata_apis/componentstatus-v1.adoc#componentstatus-v1[ComponentStatus] @@ -178,8 +184,14 @@ | metal3.io/v1alpha1 | xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1[FlowSchema] | flowcontrol.apiserver.k8s.io/v1 +| xref:../network_apis/gateway-gateway-networking-k8s-io-v1.adoc#gateway-gateway-networking-k8s-io-v1[Gateway] +| gateway.networking.k8s.io/v1 +| xref:../network_apis/gatewayclass-gateway-networking-k8s-io-v1.adoc#gatewayclass-gateway-networking-k8s-io-v1[GatewayClass] +| gateway.networking.k8s.io/v1 | xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[Group] | user.openshift.io/v1 +| xref:../network_apis/grpcroute-gateway-networking-k8s-io-v1.adoc#grpcroute-gateway-networking-k8s-io-v1[GRPCRoute] +| gateway.networking.k8s.io/v1 | xref:../provisioning_apis/hardwaredata-metal3-io-v1alpha1.adoc#hardwaredata-metal3-io-v1alpha1[HardwareData] | metal3.io/v1alpha1 | xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[HelmChartRepository] @@ -190,6 +202,10 @@ | metal3.io/v1alpha1 | xref:../provisioning_apis/hostfirmwaresettings-metal3-io-v1alpha1.adoc#hostfirmwaresettings-metal3-io-v1alpha1[HostFirmwareSettings] | metal3.io/v1alpha1 +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[HostUpdatePolicy] +| metal3.io/v1alpha1 +| xref:../network_apis/httproute-gateway-networking-k8s-io-v1.adoc#httproute-gateway-networking-k8s-io-v1[HTTPRoute] +| gateway.networking.k8s.io/v1 | xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[Identity] | user.openshift.io/v1 | xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[Image] @@ -240,6 +256,8 @@ | ipam.cluster.x-k8s.io/v1beta1 | xref:../cluster_apis/ipaddressclaim-ipam-cluster-x-k8s-io-v1beta1.adoc#ipaddressclaim-ipam-cluster-x-k8s-io-v1beta1[IPAddressClaim] | ipam.cluster.x-k8s.io/v1beta1 +| xref:../network_apis/ipamclaim-k8s-cni-cncf-io-v1alpha1.adoc#ipamclaim-k8s-cni-cncf-io-v1alpha1[IPAMClaim] +| k8s.cni.cncf.io/v1alpha1 | xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[IPPool] | whereabouts.cni.cncf.io/v1alpha1 | xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[Job] @@ -276,6 +294,10 @@ | operator.openshift.io/v1 | xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[MachineHealthCheck] | machine.openshift.io/v1beta1 +| xref:../machine_apis/machineosbuild-machineconfiguration-openshift-io-v1.adoc#machineosbuild-machineconfiguration-openshift-io-v1[MachineOSBuild] +| machineconfiguration.openshift.io/v1 +| xref:../machine_apis/machineosconfig-machineconfiguration-openshift-io-v1.adoc#machineosconfig-machineconfiguration-openshift-io-v1[MachineOSConfig] +| machineconfiguration.openshift.io/v1 | xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[MachineSet] | machine.openshift.io/v1beta1 | xref:../provisioning_apis/metal3remediation-infrastructure-cluster-x-k8s-io-v1beta1.adoc#metal3remediation-infrastructure-cluster-x-k8s-io-v1beta1[Metal3Remediation] @@ -302,6 +324,8 @@ | config.openshift.io/v1 | xref:../monitoring_apis/nodemetrics-metrics-k8s-io-v1beta1.adoc#nodemetrics-metrics-k8s-io-v1beta1[NodeMetrics] | metrics.k8s.io/v1beta1 +| xref:../network_apis/nodeslicepool-whereabouts-cni-cncf-io-v1alpha1.adoc#nodeslicepool-whereabouts-cni-cncf-io-v1alpha1[NodeSlicePool] +| whereabouts.cni.cncf.io/v1alpha1 | xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[OAuth] | config.openshift.io/v1 | xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[OAuthAccessToken] @@ -384,6 +408,8 @@ | config.openshift.io/v1 | xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[RangeAllocation] | security.openshift.io/v1 +| xref:../network_apis/referencegrant-gateway-networking-k8s-io-v1beta1.adoc#referencegrant-gateway-networking-k8s-io-v1beta1[ReferenceGrant] +| gateway.networking.k8s.io/v1beta1 | xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[ReplicaSet] | apps/v1 | xref:../workloads_apis/replicationcontroller-v1.adoc#replicationcontroller-v1[ReplicationController] @@ -464,6 +490,8 @@ | tuned.openshift.io/v1 | xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[User] | user.openshift.io/v1 +| xref:../network_apis/userdefinednetwork-k8s-ovn-org-v1.adoc#userdefinednetwork-k8s-ovn-org-v1[UserDefinedNetwork] +| k8s.ovn.org/v1 | xref:../user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[UserIdentityMapping] | user.openshift.io/v1 | xref:../oauth_apis/useroauthaccesstoken-oauth-openshift-io-v1.adoc#useroauthaccesstoken-oauth-openshift-io-v1[UserOAuthAccessToken] diff --git a/rest_api/project_apis/project-project-openshift-io-v1.adoc b/rest_api/project_apis/project-project-openshift-io-v1.adoc index b884ae52eb..04d247a01f 100644 --- a/rest_api/project_apis/project-project-openshift-io-v1.adoc +++ b/rest_api/project_apis/project-project-openshift-io-v1.adoc @@ -92,7 +92,7 @@ Type:: | Property | Type | Description | `conditions` -| xref:../objects/index.adoc#io-k8s-api-core-v1-NamespaceCondition[`array (NamespaceCondition)`] +| xref:../objects/index.adoc#io-k8s-api-core-v1-NamespaceCondition_v2[`array (NamespaceCondition_v2)`] | Represents the latest available observations of the project current state. | `phase` diff --git a/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc b/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc index 44a1dda292..07fe67ae13 100644 --- a/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc +++ b/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc @@ -111,6 +111,11 @@ field triggers provisioning. | `string` | Description is a human-entered text used to help identify the host. +| `disablePowerOff` +| `boolean` +| When set to true, power off of the node will be disabled, +instead, a reboot will be used in place of power on/off + | `externallyProvisioned` | `boolean` | ExternallyProvisioned means something else has provisioned the diff --git a/rest_api/provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc b/rest_api/provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc new file mode 100644 index 0000000000..dbe9b977a7 --- /dev/null +++ b/rest_api/provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc @@ -0,0 +1,343 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="hostupdatepolicy-metal3-io-v1alpha1"] += HostUpdatePolicy [metal3.io/v1alpha1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +HostUpdatePolicy is the Schema for the hostupdatepolicy API. +-- + +Type:: + `object` + + + +== Specification + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-ObjectMeta[`ObjectMeta`] +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| HostUpdatePolicySpec defines the desired state of HostUpdatePolicy. + +| `status` +| `object` +| HostUpdatePolicyStatus defines the observed state of HostUpdatePolicy. + +|=== +=== .spec +Description:: ++ +-- +HostUpdatePolicySpec defines the desired state of HostUpdatePolicy. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `firmwareSettings` +| `string` +| Defines policy for changing firmware settings + +| `firmwareUpdates` +| `string` +| Defines policy for updating firmware + +|=== +=== .status +Description:: ++ +-- +HostUpdatePolicyStatus defines the observed state of HostUpdatePolicy. +-- + +Type:: + `object` + + + + + +== API endpoints + +The following API endpoints are available: + +* `/apis/metal3.io/v1alpha1/hostupdatepolicies` +- `GET`: list objects of kind HostUpdatePolicy +* `/apis/metal3.io/v1alpha1/namespaces/{namespace}/hostupdatepolicies` +- `DELETE`: delete collection of HostUpdatePolicy +- `GET`: list objects of kind HostUpdatePolicy +- `POST`: create a HostUpdatePolicy +* `/apis/metal3.io/v1alpha1/namespaces/{namespace}/hostupdatepolicies/{name}` +- `DELETE`: delete a HostUpdatePolicy +- `GET`: read the specified HostUpdatePolicy +- `PATCH`: partially update the specified HostUpdatePolicy +- `PUT`: replace the specified HostUpdatePolicy + + +=== /apis/metal3.io/v1alpha1/hostupdatepolicies + + + +HTTP method:: + `GET` + +Description:: + list objects of kind HostUpdatePolicy + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-metal3-v1alpha1-HostUpdatePolicyList[`HostUpdatePolicyList`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/metal3.io/v1alpha1/namespaces/{namespace}/hostupdatepolicies + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of HostUpdatePolicy + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + list objects of kind HostUpdatePolicy + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-metal3-v1alpha1-HostUpdatePolicyList[`HostUpdatePolicyList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a HostUpdatePolicy + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[`HostUpdatePolicy`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[`HostUpdatePolicy`] schema +| 201 - Created +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[`HostUpdatePolicy`] schema +| 202 - Accepted +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[`HostUpdatePolicy`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/metal3.io/v1alpha1/namespaces/{namespace}/hostupdatepolicies/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the HostUpdatePolicy +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a HostUpdatePolicy + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 202 - Accepted +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-apis-meta-v1-Status[`Status`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `GET` + +Description:: + read the specified HostUpdatePolicy + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[`HostUpdatePolicy`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified HostUpdatePolicy + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[`HostUpdatePolicy`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified HostUpdatePolicy + + +.Query parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `dryRun` +| `string` +| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed +| `fieldValidation` +| `string` +| fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered. +|=== + +.Body parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `body` +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[`HostUpdatePolicy`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[`HostUpdatePolicy`] schema +| 201 - Created +| xref:../provisioning_apis/hostupdatepolicy-metal3-io-v1alpha1.adoc#hostupdatepolicy-metal3-io-v1alpha1[`HostUpdatePolicy`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/provisioning_apis/provisioning-apis-index.adoc b/rest_api/provisioning_apis/provisioning-apis-index.adoc index 03ba0901be..359f85ce43 100644 --- a/rest_api/provisioning_apis/provisioning-apis-index.adoc +++ b/rest_api/provisioning_apis/provisioning-apis-index.adoc @@ -81,6 +81,17 @@ Description:: HostFirmwareSettings is the Schema for the hostfirmwaresettings API. -- +Type:: + `object` + +== HostUpdatePolicy [metal3.io/v1alpha1] + +Description:: ++ +-- +HostUpdatePolicy is the Schema for the hostupdatepolicy API. +-- + Type:: `object` diff --git a/rest_api/role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc b/rest_api/role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc index 088b59ecdb..935c6c69de 100644 --- a/rest_api/role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc +++ b/rest_api/role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc @@ -45,14 +45,14 @@ Type:: | `spec` | `object` -| Spec defines the matcher. +| spec defines the matcher. |=== === .spec Description:: + -- -Spec defines the matcher. +spec defines the matcher. -- Type:: @@ -67,15 +67,15 @@ Type:: | `grouprestriction` | `` -| GroupRestriction matches against group subjects. +| grouprestriction matches against group subjects. | `serviceaccountrestriction` | `` -| ServiceAccountRestriction matches against service-account subjects. +| serviceaccountrestriction matches against service-account subjects. | `userrestriction` | `` -| UserRestriction matches against user subjects. +| userrestriction matches against user subjects. |=== diff --git a/rest_api/schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc b/rest_api/schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc index d45513ef0e..9f084967e2 100644 --- a/rest_api/schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc +++ b/rest_api/schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc @@ -45,18 +45,18 @@ Required:: | `spec` | `object` -| Spec defines the desired quota +| spec defines the desired quota | `status` | `object` -| Status defines the actual enforced quota and its current usage +| status defines the actual enforced quota and its current usage |=== === .spec Description:: + -- -Spec defines the desired quota +spec defines the desired quota -- Type:: @@ -74,11 +74,11 @@ Required:: | `quota` | `object` -| Quota defines the desired quota +| quota defines the desired quota | `selector` | `object` -| Selector is the selector used to match projects. +| selector is the selector used to match projects. It should only select active projects on the scale of dozens (though it can select many more less active projects). These projects will contend on object creation through this resource. @@ -88,7 +88,7 @@ this resource. Description:: + -- -Quota defines the desired quota +quota defines the desired quota -- Type:: @@ -202,7 +202,7 @@ This array is replaced during a strategic merge patch. Description:: + -- -Selector is the selector used to match projects. +selector is the selector used to match projects. It should only select active projects on the scale of dozens (though it can select many more less active projects). These projects will contend on object creation through this resource. @@ -231,7 +231,7 @@ Type:: Description:: + -- -Status defines the actual enforced quota and its current usage +status defines the actual enforced quota and its current usage -- Type:: @@ -248,20 +248,20 @@ Required:: | `namespaces` | `` -| Namespaces slices the usage by project. This division allows for quick resolution of +| namespaces slices the usage by project. This division allows for quick resolution of deletion reconciliation inside of a single project without requiring a recalculation across all projects. This can be used to pull the deltas for a given project. | `total` | `object` -| Total defines the actual enforced quota and its current usage across all projects +| total defines the actual enforced quota and its current usage across all projects |=== === .status.total Description:: + -- -Total defines the actual enforced quota and its current usage across all projects +total defines the actual enforced quota and its current usage across all projects -- Type:: diff --git a/rest_api/security_apis/securitycontextconstraints-security-openshift-io-v1.adoc b/rest_api/security_apis/securitycontextconstraints-security-openshift-io-v1.adoc index de76d838f5..b32a31a478 100644 --- a/rest_api/security_apis/securitycontextconstraints-security-openshift-io-v1.adoc +++ b/rest_api/security_apis/securitycontextconstraints-security-openshift-io-v1.adoc @@ -42,55 +42,55 @@ Required:: | `allowHostDirVolumePlugin` | `boolean` -| AllowHostDirVolumePlugin determines if the policy allow containers to use the HostDir volume plugin +| allowHostDirVolumePlugin determines if the policy allow containers to use the HostDir volume plugin | `allowHostIPC` | `boolean` -| AllowHostIPC determines if the policy allows host ipc in the containers. +| allowHostIPC determines if the policy allows host ipc in the containers. | `allowHostNetwork` | `boolean` -| AllowHostNetwork determines if the policy allows the use of HostNetwork in the pod spec. +| allowHostNetwork determines if the policy allows the use of HostNetwork in the pod spec. | `allowHostPID` | `boolean` -| AllowHostPID determines if the policy allows host pid in the containers. +| allowHostPID determines if the policy allows host pid in the containers. | `allowHostPorts` | `boolean` -| AllowHostPorts determines if the policy allows host ports in the containers. +| allowHostPorts determines if the policy allows host ports in the containers. | `allowPrivilegeEscalation` | `` -| AllowPrivilegeEscalation determines if a pod can request to allow +| allowPrivilegeEscalation determines if a pod can request to allow privilege escalation. If unspecified, defaults to true. | `allowPrivilegedContainer` | `boolean` -| AllowPrivilegedContainer determines if a container can request to be run as privileged. +| allowPrivilegedContainer determines if a container can request to be run as privileged. | `allowedCapabilities` | `` -| AllowedCapabilities is a list of capabilities that can be requested to add to the container. +| allowedCapabilities is a list of capabilities that can be requested to add to the container. Capabilities in this field maybe added at the pod author's discretion. You must not list a capability in both AllowedCapabilities and RequiredDropCapabilities. To allow all capabilities you may use '*'. | `allowedFlexVolumes` | `` -| AllowedFlexVolumes is a whitelist of allowed Flexvolumes. Empty or nil indicates that all +| allowedFlexVolumes is a whitelist of allowed Flexvolumes. Empty or nil indicates that all Flexvolumes may be used. This parameter is effective only when the usage of the Flexvolumes is allowed in the "Volumes" field. | `allowedUnsafeSysctls` | `` -| AllowedUnsafeSysctls is a list of explicitly allowed unsafe sysctls, defaults to none. -Each entry is either a plain sysctl name or ends in "\*" in which case it is considered +| allowedUnsafeSysctls is a list of explicitly allowed unsafe sysctls, defaults to none. +Each entry is either a plain sysctl name or ends in "*" in which case it is considered as a prefix of allowed sysctls. Single * means all unsafe sysctls are allowed. Kubelet has to whitelist all allowed unsafe sysctls explicitly to avoid rejection. Examples: -e.g. "foo/\*" allows "foo/bar", "foo/baz", etc. +e.g. "foo/*" allows "foo/bar", "foo/baz", etc. e.g. "foo.*" allows "foo.bar", "foo.baz", etc. | `apiVersion` @@ -99,28 +99,28 @@ e.g. "foo.*" allows "foo.bar", "foo.baz", etc. | `defaultAddCapabilities` | `` -| DefaultAddCapabilities is the default set of capabilities that will be added to the container +| defaultAddCapabilities is the default set of capabilities that will be added to the container unless the pod spec specifically drops the capability. You may not list a capabiility in both DefaultAddCapabilities and RequiredDropCapabilities. | `defaultAllowPrivilegeEscalation` | `` -| DefaultAllowPrivilegeEscalation controls the default setting for whether a +| defaultAllowPrivilegeEscalation controls the default setting for whether a process can gain more privileges than its parent process. | `forbiddenSysctls` | `` -| ForbiddenSysctls is a list of explicitly forbidden sysctls, defaults to none. -Each entry is either a plain sysctl name or ends in "\*" in which case it is considered +| forbiddenSysctls is a list of explicitly forbidden sysctls, defaults to none. +Each entry is either a plain sysctl name or ends in "*" in which case it is considered as a prefix of forbidden sysctls. Single * means all sysctls are forbidden. Examples: -e.g. "foo/\*" forbids "foo/bar", "foo/baz", etc. +e.g. "foo/*" forbids "foo/bar", "foo/baz", etc. e.g. "foo.*" forbids "foo.bar", "foo.baz", etc. | `fsGroup` | `` -| FSGroup is the strategy that will dictate what fs group is used by the SecurityContext. +| fsGroup is the strategy that will dictate what fs group is used by the SecurityContext. | `groups` | `` @@ -136,7 +136,7 @@ e.g. "foo.*" forbids "foo.bar", "foo.baz", etc. | `priority` | `` -| Priority influences the sort order of SCCs when evaluating which SCCs to try first for +| priority influences the sort order of SCCs when evaluating which SCCs to try first for a given pod request based on access in the Users and Groups fields. The higher the int, the higher priority. An unset value is considered a 0 priority. If scores for multiple SCCs are equal they will be sorted from most restrictive to @@ -145,7 +145,7 @@ SCCs will be sorted by name. | `readOnlyRootFilesystem` | `boolean` -| ReadOnlyRootFilesystem when set to true will force containers to run with a read only root file +| readOnlyRootFilesystem when set to true will force containers to run with a read only root file system. If the container specifically requests to run with a non-read only root file system the SCC should deny the pod. If set to false the container may run with a read only root file system if it wishes but it @@ -153,20 +153,20 @@ will not be forced to. | `requiredDropCapabilities` | `` -| RequiredDropCapabilities are the capabilities that will be dropped from the container. These +| requiredDropCapabilities are the capabilities that will be dropped from the container. These are required to be dropped and cannot be added. | `runAsUser` | `` -| RunAsUser is the strategy that will dictate what RunAsUser is used in the SecurityContext. +| runAsUser is the strategy that will dictate what RunAsUser is used in the SecurityContext. | `seLinuxContext` | `` -| SELinuxContext is the strategy that will dictate what labels will be set in the SecurityContext. +| seLinuxContext is the strategy that will dictate what labels will be set in the SecurityContext. | `seccompProfiles` | `` -| SeccompProfiles lists the allowed profiles that may be set for the pod or +| seccompProfiles lists the allowed profiles that may be set for the pod or container's seccomp annotations. An unset (nil) or empty value means that no profiles may be specifid by the pod or container. The wildcard '*' may be used to allow all profiles. When used to generate a value for a pod the first non-wildcard profile will be used as @@ -174,7 +174,7 @@ the default. | `supplementalGroups` | `` -| SupplementalGroups is the strategy that will dictate what supplemental groups are used by the SecurityContext. +| supplementalGroups is the strategy that will dictate what supplemental groups are used by the SecurityContext. | `users` | `` @@ -182,7 +182,7 @@ the default. | `volumes` | `` -| Volumes is a white list of allowed volume plugins. FSType corresponds directly with the field names +| volumes is a white list of allowed volume plugins. FSType corresponds directly with the field names of a VolumeSource (azureFile, configMap, emptyDir). To allow all volumes you may use "*". To allow no volumes, set to ["none"]. @@ -274,7 +274,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints`] schema -| +| |=== .HTTP responses @@ -429,7 +429,7 @@ Description:: | Parameter | Type | Description | `body` | xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints`] schema -| +| |=== .HTTP responses diff --git a/rest_api/security_apis/serviceaccount-v1.adoc b/rest_api/security_apis/serviceaccount-v1.adoc index 4ff3273cc1..4e4d14f83f 100644 --- a/rest_api/security_apis/serviceaccount-v1.adoc +++ b/rest_api/security_apis/serviceaccount-v1.adoc @@ -51,7 +51,7 @@ Type:: | `secrets` | `array` -| Secrets is a list of the secrets in the same namespace that pods running using this ServiceAccount are allowed to use. Pods are only limited to this list if this service account has a "kubernetes.io/enforce-mountable-secrets" annotation set to "true". This field should not be used to find auto-generated service account token secrets for use outside of pods. Instead, tokens can be requested directly using the TokenRequest API, or service account token secrets can be manually created. More info: https://kubernetes.io/docs/concepts/configuration/secret +| Secrets is a list of the secrets in the same namespace that pods running using this ServiceAccount are allowed to use. Pods are only limited to this list if this service account has a "kubernetes.io/enforce-mountable-secrets" annotation set to "true". The "kubernetes.io/enforce-mountable-secrets" annotation is deprecated since v1.32. Prefer separate namespaces to isolate access to mounted secrets. This field should not be used to find auto-generated service account token secrets for use outside of pods. Instead, tokens can be requested directly using the TokenRequest API, or service account token secrets can be manually created. More info: https://kubernetes.io/docs/concepts/configuration/secret | `secrets[]` | `object` @@ -97,7 +97,7 @@ Type:: Description:: + -- -Secrets is a list of the secrets in the same namespace that pods running using this ServiceAccount are allowed to use. Pods are only limited to this list if this service account has a "kubernetes.io/enforce-mountable-secrets" annotation set to "true". This field should not be used to find auto-generated service account token secrets for use outside of pods. Instead, tokens can be requested directly using the TokenRequest API, or service account token secrets can be manually created. More info: https://kubernetes.io/docs/concepts/configuration/secret +Secrets is a list of the secrets in the same namespace that pods running using this ServiceAccount are allowed to use. Pods are only limited to this list if this service account has a "kubernetes.io/enforce-mountable-secrets" annotation set to "true". The "kubernetes.io/enforce-mountable-secrets" annotation is deprecated since v1.32. Prefer separate namespaces to isolate access to mounted secrets. This field should not be used to find auto-generated service account token secrets for use outside of pods. Instead, tokens can be requested directly using the TokenRequest API, or service account token secrets can be manually created. More info: https://kubernetes.io/docs/concepts/configuration/secret -- Type:: diff --git a/rest_api/storage_apis/persistentvolume-v1.adoc b/rest_api/storage_apis/persistentvolume-v1.adoc index 041e221bcd..f70cec8390 100644 --- a/rest_api/storage_apis/persistentvolume-v1.adoc +++ b/rest_api/storage_apis/persistentvolume-v1.adoc @@ -99,7 +99,7 @@ An AWS EBS disk must exist before mounting to a container. The disk must also be | `csi` | `object` -| Represents storage that is managed by an external CSI volume driver (Beta feature) +| Represents storage that is managed by an external CSI volume driver | `fc` | `object` @@ -133,7 +133,7 @@ A GCE PD must exist before mounting to a container. The disk must also be in the | `local` | `object` -| Local represents directly-attached storage with node affinity (Beta feature) +| Local represents directly-attached storage with node affinity | `mountOptions` | `array (string)` @@ -513,7 +513,7 @@ Type:: Description:: + -- -Represents storage that is managed by an external CSI volume driver (Beta feature) +Represents storage that is managed by an external CSI volume driver -- Type:: @@ -1039,7 +1039,7 @@ Type:: Description:: + -- -Local represents directly-attached storage with node affinity (Beta feature) +Local represents directly-attached storage with node affinity -- Type:: diff --git a/rest_api/storage_apis/persistentvolumeclaim-v1.adoc b/rest_api/storage_apis/persistentvolumeclaim-v1.adoc index 4b65d0882a..9e98a91828 100644 --- a/rest_api/storage_apis/persistentvolumeclaim-v1.adoc +++ b/rest_api/storage_apis/persistentvolumeclaim-v1.adoc @@ -73,14 +73,7 @@ Type:: | `dataSourceRef` | `object` -| dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn't specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn't set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef: * While dataSource only allows two specific types of objects, dataSourceRef - allows any non-core object, as well as PersistentVolumeClaim objects. -* While dataSource ignores disallowed values (dropping them), dataSourceRef - preserves all values, and generates an error if a disallowed value is - specified. -* While dataSource only allows local objects, dataSourceRef allows objects - in any namespaces. -(Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled. +| TypedObjectReference contains enough information to let you locate the typed referenced object | `resources` | `object` @@ -148,14 +141,7 @@ Required:: Description:: + -- -dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn't specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn't set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef: * While dataSource only allows two specific types of objects, dataSourceRef - allows any non-core object, as well as PersistentVolumeClaim objects. -* While dataSource ignores disallowed values (dropping them), dataSourceRef - preserves all values, and generates an error if a disallowed value is - specified. -* While dataSource only allows local objects, dataSourceRef allows objects - in any namespaces. -(Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled. +TypedObjectReference contains enough information to let you locate the typed referenced object -- Type:: @@ -363,11 +349,11 @@ Required:: | `status` | `string` -| +| Status is the status of the condition. Can be True, False, Unknown. More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=state%20of%20pvc-,conditions.status,-(string)%2C%20required | `type` | `string` -| +| Type is the type of the condition. More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=set%20to%20%27ResizeStarted%27.-,PersistentVolumeClaimCondition,-contains%20details%20about |=== === .status.modifyVolumeStatus diff --git a/rest_api/storage_apis/volumeattachment-storage-k8s-io-v1.adoc b/rest_api/storage_apis/volumeattachment-storage-k8s-io-v1.adoc index f84d88dbb2..f784f59cba 100644 --- a/rest_api/storage_apis/volumeattachment-storage-k8s-io-v1.adoc +++ b/rest_api/storage_apis/volumeattachment-storage-k8s-io-v1.adoc @@ -81,14 +81,14 @@ Required:: | `source` | `object` -| VolumeAttachmentSource represents a volume that should be attached. Right now only PersistenVolumes can be attached via external attacher, in future we may allow also inline volumes in pods. Exactly one member can be set. +| VolumeAttachmentSource represents a volume that should be attached. Right now only PersistentVolumes can be attached via external attacher, in the future we may allow also inline volumes in pods. Exactly one member can be set. |=== === .spec.source Description:: + -- -VolumeAttachmentSource represents a volume that should be attached. Right now only PersistenVolumes can be attached via external attacher, in future we may allow also inline volumes in pods. Exactly one member can be set. +VolumeAttachmentSource represents a volume that should be attached. Right now only PersistentVolumes can be attached via external attacher, in the future we may allow also inline volumes in pods. Exactly one member can be set. -- Type:: diff --git a/rest_api/template_apis/podtemplate-v1.adoc b/rest_api/template_apis/podtemplate-v1.adoc index e62b618d1b..78a4d0f4a1 100644 --- a/rest_api/template_apis/podtemplate-v1.adoc +++ b/rest_api/template_apis/podtemplate-v1.adoc @@ -233,6 +233,10 @@ This field is immutable. It adds a name to it that uniquely identifies the ResourceClaim inside the Pod. Containers that need access to the ResourceClaim reference it with this name. +| `resources` +| `object` +| ResourceRequirements describes the compute resource requirements. + | `restartPolicy` | `string` | Restart policy for all containers within the pod. One of Always, OnFailure, Never. In some contexts, only a subset of those values may be permitted. Default to Always. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy @@ -274,7 +278,7 @@ SchedulingGates can only be set at pod creation time, and be removed only afterw | `setHostnameAsFQDN` | `boolean` -| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. +| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\Tcpip\\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. | `shareProcessNamespace` | `boolean` @@ -2011,7 +2015,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -2068,7 +2072,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -2297,7 +2301,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -2354,7 +2358,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -2885,7 +2889,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -2942,7 +2946,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -3269,11 +3273,11 @@ Type:: | `name` | `string` -| Required. +| Name is this DNS resolver option's name. Required. | `value` | `string` -| +| Value is this DNS resolver option's value. |=== === .template.spec.ephemeralContainers @@ -4201,7 +4205,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -4258,7 +4262,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -4487,7 +4491,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -4544,7 +4548,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -5075,7 +5079,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -5132,7 +5136,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -6386,7 +6390,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -6443,7 +6447,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -6672,7 +6676,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -6729,7 +6733,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -7260,7 +7264,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -7317,7 +7321,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -7697,6 +7701,89 @@ This field is immutable and no changes will be made to the corresponding Resourc Exactly one of ResourceClaimName and ResourceClaimTemplateName must be set. +|=== +=== .template.spec.resources +Description:: ++ +-- +ResourceRequirements describes the compute resource requirements. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `claims` +| `array` +| Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. + +This is an alpha field and requires enabling the DynamicResourceAllocation feature gate. + +This field is immutable. It can only be set for containers. + +| `claims[]` +| `object` +| ResourceClaim references one entry in PodSpec.ResourceClaims. + +| `limits` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-api-resource-Quantity[`object (Quantity)`] +| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +| `requests` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-api-resource-Quantity[`object (Quantity)`] +| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +|=== +=== .template.spec.resources.claims +Description:: ++ +-- +Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. + +This is an alpha field and requires enabling the DynamicResourceAllocation feature gate. + +This field is immutable. It can only be set for containers. +-- + +Type:: + `array` + + + + +=== .template.spec.resources.claims[] +Description:: ++ +-- +ResourceClaim references one entry in PodSpec.ResourceClaims. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container. + +| `request` +| `string` +| Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request. + |=== === .template.spec.schedulingGates Description:: @@ -7786,6 +7873,20 @@ Possible enum values: | `integer` | The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. Note that this field cannot be set when spec.os.name is windows. +| `seLinuxChangePolicy` +| `string` +| seLinuxChangePolicy defines how the container's SELinux label is applied to all volumes used by the Pod. It has no effect on nodes that do not support SELinux or to volumes does not support SELinux. Valid values are "MountOption" and "Recursive". + +"Recursive" means relabeling of all files on all Pod volumes by the container runtime. This may be slow for large volumes, but allows mixing privileged and unprivileged Pods sharing the same volume on the same node. + +"MountOption" mounts all eligible Pod volumes with `-o context` mount option. This requires all Pods that share the same volume to use the same SELinux label. It is not possible to share the same volume among privileged and unprivileged Pods. Eligible volumes are in-tree FibreChannel and iSCSI volumes, and all CSI volumes whose CSI driver announces SELinux support by setting spec.seLinuxMount: true in their CSIDriver instance. Other volumes are always re-labelled recursively. "MountOption" value is allowed only when SELinuxMount feature gate is enabled. + +If not specified and SELinuxMount feature gate is enabled, "MountOption" is used. If not specified and SELinuxMount feature gate is disabled, "MountOption" is used for ReadWriteOncePod volumes and "Recursive" for all other volumes. + +This field affects only Pods that have SELinux label set, either in PodSecurityContext or in SecurityContext of all containers. + +All Pods that use the same volume should use the same seLinuxChangePolicy, otherwise some pods can get stuck in ContainerCreating state. Note that this field cannot be set when spec.os.name is windows. + | `seLinuxOptions` | `object` | SELinuxOptions are the labels to be applied to the container @@ -8957,14 +9058,7 @@ Type:: | `dataSourceRef` | `object` -| dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn't specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn't set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef: * While dataSource only allows two specific types of objects, dataSourceRef - allows any non-core object, as well as PersistentVolumeClaim objects. -* While dataSource ignores disallowed values (dropping them), dataSourceRef - preserves all values, and generates an error if a disallowed value is - specified. -* While dataSource only allows local objects, dataSourceRef allows objects - in any namespaces. -(Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled. +| TypedObjectReference contains enough information to let you locate the typed referenced object | `resources` | `object` @@ -9032,14 +9126,7 @@ Required:: Description:: + -- -dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn't specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn't set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef: * While dataSource only allows two specific types of objects, dataSourceRef - allows any non-core object, as well as PersistentVolumeClaim objects. -* While dataSource ignores disallowed values (dropping them), dataSourceRef - preserves all values, and generates an error if a disallowed value is - specified. -* While dataSource only allows local objects, dataSourceRef allows objects - in any namespaces. -(Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled. +TypedObjectReference contains enough information to let you locate the typed referenced object -- Type:: diff --git a/rest_api/workloads_apis/cronjob-batch-v1.adoc b/rest_api/workloads_apis/cronjob-batch-v1.adoc index 7c309161bc..bcd55cff3e 100644 --- a/rest_api/workloads_apis/cronjob-batch-v1.adoc +++ b/rest_api/workloads_apis/cronjob-batch-v1.adoc @@ -185,7 +185,7 @@ Possible enum values: | `string` | ManagedBy field indicates the controller that manages a Job. The k8s Job controller reconciles jobs which don't have this field at all or the field value is the reserved string `kubernetes.io/job-controller`, but skips reconciling Jobs with a custom value for this field. The value must be a valid domain-prefixed path (e.g. acme.io/foo) - all characters before the first "/" must be a valid subdomain as defined by RFC 1123. All characters trailing the first "/" must be valid HTTP Path characters as defined by RFC 3986. The value cannot exceed 63 characters. This field is immutable. -This field is alpha-level. The job controller accepts setting the field when the feature gate JobManagedBy is enabled (disabled by default). +This field is beta-level. The job controller accepts setting the field when the feature gate JobManagedBy is enabled (enabled by default). | `manualSelector` | `boolean` diff --git a/rest_api/workloads_apis/job-batch-v1.adoc b/rest_api/workloads_apis/job-batch-v1.adoc index 47c4f61d50..a46913a63f 100644 --- a/rest_api/workloads_apis/job-batch-v1.adoc +++ b/rest_api/workloads_apis/job-batch-v1.adoc @@ -99,7 +99,7 @@ Possible enum values: | `string` | ManagedBy field indicates the controller that manages a Job. The k8s Job controller reconciles jobs which don't have this field at all or the field value is the reserved string `kubernetes.io/job-controller`, but skips reconciling Jobs with a custom value for this field. The value must be a valid domain-prefixed path (e.g. acme.io/foo) - all characters before the first "/" must be a valid subdomain as defined by RFC 1123. All characters trailing the first "/" must be valid HTTP Path characters as defined by RFC 3986. The value cannot exceed 63 characters. This field is immutable. -This field is alpha-level. The job controller accepts setting the field when the feature gate JobManagedBy is enabled (disabled by default). +This field is beta-level. The job controller accepts setting the field when the feature gate JobManagedBy is enabled (enabled by default). | `manualSelector` | `boolean` diff --git a/rest_api/workloads_apis/pod-v1.adoc b/rest_api/workloads_apis/pod-v1.adoc index 4496db1608..3410ae09a7 100644 --- a/rest_api/workloads_apis/pod-v1.adoc +++ b/rest_api/workloads_apis/pod-v1.adoc @@ -211,6 +211,10 @@ This field is immutable. It adds a name to it that uniquely identifies the ResourceClaim inside the Pod. Containers that need access to the ResourceClaim reference it with this name. +| `resources` +| `object` +| ResourceRequirements describes the compute resource requirements. + | `restartPolicy` | `string` | Restart policy for all containers within the pod. One of Always, OnFailure, Never. In some contexts, only a subset of those values may be permitted. Default to Always. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy @@ -252,7 +256,7 @@ SchedulingGates can only be set at pod creation time, and be removed only afterw | `setHostnameAsFQDN` | `boolean` -| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. +| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\Tcpip\\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. | `shareProcessNamespace` | `boolean` @@ -1989,7 +1993,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -2046,7 +2050,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -2275,7 +2279,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -2332,7 +2336,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -2863,7 +2867,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -2920,7 +2924,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -3247,11 +3251,11 @@ Type:: | `name` | `string` -| Required. +| Name is this DNS resolver option's name. Required. | `value` | `string` -| +| Value is this DNS resolver option's value. |=== === .spec.ephemeralContainers @@ -4179,7 +4183,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -4236,7 +4240,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -4465,7 +4469,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -4522,7 +4526,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -5053,7 +5057,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -5110,7 +5114,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -6364,7 +6368,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -6421,7 +6425,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -6650,7 +6654,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -6707,7 +6711,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -7238,7 +7242,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -7295,7 +7299,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -7675,6 +7679,89 @@ This field is immutable and no changes will be made to the corresponding Resourc Exactly one of ResourceClaimName and ResourceClaimTemplateName must be set. +|=== +=== .spec.resources +Description:: ++ +-- +ResourceRequirements describes the compute resource requirements. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `claims` +| `array` +| Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. + +This is an alpha field and requires enabling the DynamicResourceAllocation feature gate. + +This field is immutable. It can only be set for containers. + +| `claims[]` +| `object` +| ResourceClaim references one entry in PodSpec.ResourceClaims. + +| `limits` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-api-resource-Quantity[`object (Quantity)`] +| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +| `requests` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-api-resource-Quantity[`object (Quantity)`] +| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +|=== +=== .spec.resources.claims +Description:: ++ +-- +Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. + +This is an alpha field and requires enabling the DynamicResourceAllocation feature gate. + +This field is immutable. It can only be set for containers. +-- + +Type:: + `array` + + + + +=== .spec.resources.claims[] +Description:: ++ +-- +ResourceClaim references one entry in PodSpec.ResourceClaims. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container. + +| `request` +| `string` +| Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request. + |=== === .spec.schedulingGates Description:: @@ -7764,6 +7851,20 @@ Possible enum values: | `integer` | The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. Note that this field cannot be set when spec.os.name is windows. +| `seLinuxChangePolicy` +| `string` +| seLinuxChangePolicy defines how the container's SELinux label is applied to all volumes used by the Pod. It has no effect on nodes that do not support SELinux or to volumes does not support SELinux. Valid values are "MountOption" and "Recursive". + +"Recursive" means relabeling of all files on all Pod volumes by the container runtime. This may be slow for large volumes, but allows mixing privileged and unprivileged Pods sharing the same volume on the same node. + +"MountOption" mounts all eligible Pod volumes with `-o context` mount option. This requires all Pods that share the same volume to use the same SELinux label. It is not possible to share the same volume among privileged and unprivileged Pods. Eligible volumes are in-tree FibreChannel and iSCSI volumes, and all CSI volumes whose CSI driver announces SELinux support by setting spec.seLinuxMount: true in their CSIDriver instance. Other volumes are always re-labelled recursively. "MountOption" value is allowed only when SELinuxMount feature gate is enabled. + +If not specified and SELinuxMount feature gate is enabled, "MountOption" is used. If not specified and SELinuxMount feature gate is disabled, "MountOption" is used for ReadWriteOncePod volumes and "Recursive" for all other volumes. + +This field affects only Pods that have SELinux label set, either in PodSecurityContext or in SecurityContext of all containers. + +All Pods that use the same volume should use the same seLinuxChangePolicy, otherwise some pods can get stuck in ContainerCreating state. Note that this field cannot be set when spec.os.name is windows. + | `seLinuxOptions` | `object` | SELinuxOptions are the labels to be applied to the container @@ -8935,14 +9036,7 @@ Type:: | `dataSourceRef` | `object` -| dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn't specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn't set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef: * While dataSource only allows two specific types of objects, dataSourceRef - allows any non-core object, as well as PersistentVolumeClaim objects. -* While dataSource ignores disallowed values (dropping them), dataSourceRef - preserves all values, and generates an error if a disallowed value is - specified. -* While dataSource only allows local objects, dataSourceRef allows objects - in any namespaces. -(Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled. +| TypedObjectReference contains enough information to let you locate the typed referenced object | `resources` | `object` @@ -9010,14 +9104,7 @@ Required:: Description:: + -- -dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn't specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn't set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef: * While dataSource only allows two specific types of objects, dataSourceRef - allows any non-core object, as well as PersistentVolumeClaim objects. -* While dataSource ignores disallowed values (dropping them), dataSourceRef - preserves all values, and generates an error if a disallowed value is - specified. -* While dataSource only allows local objects, dataSourceRef allows objects - in any namespaces. -(Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled. +TypedObjectReference contains enough information to let you locate the typed referenced object -- Type:: @@ -10454,7 +10541,7 @@ Type:: | `containerStatuses` | `array` -| The list has one entry per container in the manifest. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status +| Statuses of containers in this pod. Each container in the pod should have at most one status in this list, and all statuses should be for containers in the pod. However this is not enforced. If a status for a non-existent container is present in the list, or the list has duplicate names, the behavior of various Kubernetes components is not defined and those statuses might be ignored. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status | `containerStatuses[]` | `object` @@ -10462,7 +10549,7 @@ Type:: | `ephemeralContainerStatuses` | `array` -| Status for any ephemeral containers that have run in this pod. +| Statuses for any ephemeral containers that have run in this pod. Each ephemeral container in the pod should have at most one status in this list, and all statuses should be for containers in the pod. However this is not enforced. If a status for a non-existent container is present in the list, or the list has duplicate names, the behavior of various Kubernetes components is not defined and those statuses might be ignored. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status | `ephemeralContainerStatuses[]` | `object` @@ -10482,7 +10569,7 @@ Type:: | `initContainerStatuses` | `array` -| The list has one entry per init container in the manifest. The most recent successful init container will have ready = true, the most recently started container will have startTime set. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status +| Statuses of init containers in this pod. The most recent successful non-restartable init container will have ready = true, the most recently started container will have startTime set. Each init container in the pod should have at most one status in this list, and all statuses should be for containers in the pod. However this is not enforced. If a status for a non-existent container is present in the list, or the list has duplicate names, the behavior of various Kubernetes components is not defined and those statuses might be ignored. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-and-container-status | `initContainerStatuses[]` | `object` @@ -10615,7 +10702,7 @@ Required:: Description:: + -- -The list has one entry per container in the manifest. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status +Statuses of containers in this pod. Each container in the pod should have at most one status in this list, and all statuses should be for containers in the pod. However this is not enforced. If a status for a non-existent container is present in the list, or the list has duplicate names, the behavior of various Kubernetes components is not defined and those statuses might be ignored. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status -- Type:: @@ -10657,7 +10744,7 @@ Required:: | `allocatedResourcesStatus[]` | `object` -| +| ResourceStatus represents the status of a single resource allocated to a Pod. | `containerID` | `string` @@ -10731,7 +10818,7 @@ Type:: Description:: + -- - +ResourceStatus represents the status of a single resource allocated to a Pod. -- Type:: @@ -10748,22 +10835,22 @@ Required:: | `name` | `string` -| Name of the resource. Must be unique within the pod and match one of the resources from the pod spec. +| Name of the resource. Must be unique within the pod and in case of non-DRA resource, match one of the resources from the pod spec. For DRA resources, the value must be "claim:/". When this status is reported about a container, the "claim_name" and "request" must match one of the claims of this container. | `resources` | `array` -| List of unique Resources health. Each element in the list contains an unique resource ID and resource health. At a minimum, ResourceID must uniquely identify the Resource allocated to the Pod on the Node for the lifetime of a Pod. See ResourceID type for it's definition. +| List of unique resources health. Each element in the list contains an unique resource ID and its health. At a minimum, for the lifetime of a Pod, resource ID must uniquely identify the resource allocated to the Pod on the Node. If other Pod on the same Node reports the status with the same resource ID, it must be the same resource they share. See ResourceID type definition for a specific format it has in various use cases. | `resources[]` | `object` -| ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680 and historical health changes are planned to be added in future iterations of a KEP. +| ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680. |=== === .status.containerStatuses[].allocatedResourcesStatus[].resources Description:: + -- -List of unique Resources health. Each element in the list contains an unique resource ID and resource health. At a minimum, ResourceID must uniquely identify the Resource allocated to the Pod on the Node for the lifetime of a Pod. See ResourceID type for it's definition. +List of unique resources health. Each element in the list contains an unique resource ID and its health. At a minimum, for the lifetime of a Pod, resource ID must uniquely identify the resource allocated to the Pod on the Node. If other Pod on the same Node reports the status with the same resource ID, it must be the same resource they share. See ResourceID type definition for a specific format it has in various use cases. -- Type:: @@ -10776,7 +10863,7 @@ Type:: Description:: + -- -ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680 and historical health changes are planned to be added in future iterations of a KEP. +ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680. -- Type:: @@ -11252,7 +11339,7 @@ Required:: Description:: + -- -Status for any ephemeral containers that have run in this pod. +Statuses for any ephemeral containers that have run in this pod. Each ephemeral container in the pod should have at most one status in this list, and all statuses should be for containers in the pod. However this is not enforced. If a status for a non-existent container is present in the list, or the list has duplicate names, the behavior of various Kubernetes components is not defined and those statuses might be ignored. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status -- Type:: @@ -11294,7 +11381,7 @@ Required:: | `allocatedResourcesStatus[]` | `object` -| +| ResourceStatus represents the status of a single resource allocated to a Pod. | `containerID` | `string` @@ -11368,7 +11455,7 @@ Type:: Description:: + -- - +ResourceStatus represents the status of a single resource allocated to a Pod. -- Type:: @@ -11385,22 +11472,22 @@ Required:: | `name` | `string` -| Name of the resource. Must be unique within the pod and match one of the resources from the pod spec. +| Name of the resource. Must be unique within the pod and in case of non-DRA resource, match one of the resources from the pod spec. For DRA resources, the value must be "claim:/". When this status is reported about a container, the "claim_name" and "request" must match one of the claims of this container. | `resources` | `array` -| List of unique Resources health. Each element in the list contains an unique resource ID and resource health. At a minimum, ResourceID must uniquely identify the Resource allocated to the Pod on the Node for the lifetime of a Pod. See ResourceID type for it's definition. +| List of unique resources health. Each element in the list contains an unique resource ID and its health. At a minimum, for the lifetime of a Pod, resource ID must uniquely identify the resource allocated to the Pod on the Node. If other Pod on the same Node reports the status with the same resource ID, it must be the same resource they share. See ResourceID type definition for a specific format it has in various use cases. | `resources[]` | `object` -| ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680 and historical health changes are planned to be added in future iterations of a KEP. +| ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680. |=== === .status.ephemeralContainerStatuses[].allocatedResourcesStatus[].resources Description:: + -- -List of unique Resources health. Each element in the list contains an unique resource ID and resource health. At a minimum, ResourceID must uniquely identify the Resource allocated to the Pod on the Node for the lifetime of a Pod. See ResourceID type for it's definition. +List of unique resources health. Each element in the list contains an unique resource ID and its health. At a minimum, for the lifetime of a Pod, resource ID must uniquely identify the resource allocated to the Pod on the Node. If other Pod on the same Node reports the status with the same resource ID, it must be the same resource they share. See ResourceID type definition for a specific format it has in various use cases. -- Type:: @@ -11413,7 +11500,7 @@ Type:: Description:: + -- -ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680 and historical health changes are planned to be added in future iterations of a KEP. +ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680. -- Type:: @@ -11926,7 +12013,7 @@ Required:: Description:: + -- -The list has one entry per init container in the manifest. The most recent successful init container will have ready = true, the most recently started container will have startTime set. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status +Statuses of init containers in this pod. The most recent successful non-restartable init container will have ready = true, the most recently started container will have startTime set. Each init container in the pod should have at most one status in this list, and all statuses should be for containers in the pod. However this is not enforced. If a status for a non-existent container is present in the list, or the list has duplicate names, the behavior of various Kubernetes components is not defined and those statuses might be ignored. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-and-container-status -- Type:: @@ -11968,7 +12055,7 @@ Required:: | `allocatedResourcesStatus[]` | `object` -| +| ResourceStatus represents the status of a single resource allocated to a Pod. | `containerID` | `string` @@ -12042,7 +12129,7 @@ Type:: Description:: + -- - +ResourceStatus represents the status of a single resource allocated to a Pod. -- Type:: @@ -12059,22 +12146,22 @@ Required:: | `name` | `string` -| Name of the resource. Must be unique within the pod and match one of the resources from the pod spec. +| Name of the resource. Must be unique within the pod and in case of non-DRA resource, match one of the resources from the pod spec. For DRA resources, the value must be "claim:/". When this status is reported about a container, the "claim_name" and "request" must match one of the claims of this container. | `resources` | `array` -| List of unique Resources health. Each element in the list contains an unique resource ID and resource health. At a minimum, ResourceID must uniquely identify the Resource allocated to the Pod on the Node for the lifetime of a Pod. See ResourceID type for it's definition. +| List of unique resources health. Each element in the list contains an unique resource ID and its health. At a minimum, for the lifetime of a Pod, resource ID must uniquely identify the resource allocated to the Pod on the Node. If other Pod on the same Node reports the status with the same resource ID, it must be the same resource they share. See ResourceID type definition for a specific format it has in various use cases. | `resources[]` | `object` -| ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680 and historical health changes are planned to be added in future iterations of a KEP. +| ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680. |=== === .status.initContainerStatuses[].allocatedResourcesStatus[].resources Description:: + -- -List of unique Resources health. Each element in the list contains an unique resource ID and resource health. At a minimum, ResourceID must uniquely identify the Resource allocated to the Pod on the Node for the lifetime of a Pod. See ResourceID type for it's definition. +List of unique resources health. Each element in the list contains an unique resource ID and its health. At a minimum, for the lifetime of a Pod, resource ID must uniquely identify the resource allocated to the Pod on the Node. If other Pod on the same Node reports the status with the same resource ID, it must be the same resource they share. See ResourceID type definition for a specific format it has in various use cases. -- Type:: @@ -12087,7 +12174,7 @@ Type:: Description:: + -- -ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680 and historical health changes are planned to be added in future iterations of a KEP. +ResourceHealth represents the health of a resource. It has the latest device health information. This is a part of KEP https://kep.k8s.io/4680. -- Type:: diff --git a/rest_api/workloads_apis/replicationcontroller-v1.adoc b/rest_api/workloads_apis/replicationcontroller-v1.adoc index b3d7356ed0..92a123b36b 100644 --- a/rest_api/workloads_apis/replicationcontroller-v1.adoc +++ b/rest_api/workloads_apis/replicationcontroller-v1.adoc @@ -271,6 +271,10 @@ This field is immutable. It adds a name to it that uniquely identifies the ResourceClaim inside the Pod. Containers that need access to the ResourceClaim reference it with this name. +| `resources` +| `object` +| ResourceRequirements describes the compute resource requirements. + | `restartPolicy` | `string` | Restart policy for all containers within the pod. One of Always, OnFailure, Never. In some contexts, only a subset of those values may be permitted. Default to Always. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy @@ -312,7 +316,7 @@ SchedulingGates can only be set at pod creation time, and be removed only afterw | `setHostnameAsFQDN` | `boolean` -| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. +| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\Tcpip\\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. | `shareProcessNamespace` | `boolean` @@ -2049,7 +2053,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -2106,7 +2110,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -2335,7 +2339,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -2392,7 +2396,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -2923,7 +2927,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -2980,7 +2984,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -3307,11 +3311,11 @@ Type:: | `name` | `string` -| Required. +| Name is this DNS resolver option's name. Required. | `value` | `string` -| +| Value is this DNS resolver option's value. |=== === .spec.template.spec.ephemeralContainers @@ -4239,7 +4243,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -4296,7 +4300,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -4525,7 +4529,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -4582,7 +4586,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -5113,7 +5117,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -5170,7 +5174,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -6424,7 +6428,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -6481,7 +6485,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -6710,7 +6714,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -6767,7 +6771,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -7298,7 +7302,7 @@ Type:: | `grpc` | `object` -| GRPC specifies an action involving a GRPC port. +| GRPCAction specifies an action involving a GRPC service. | `httpGet` | `object` @@ -7355,7 +7359,7 @@ Type:: Description:: + -- -GRPC specifies an action involving a GRPC port. +GRPCAction specifies an action involving a GRPC service. -- Type:: @@ -7735,6 +7739,89 @@ This field is immutable and no changes will be made to the corresponding Resourc Exactly one of ResourceClaimName and ResourceClaimTemplateName must be set. +|=== +=== .spec.template.spec.resources +Description:: ++ +-- +ResourceRequirements describes the compute resource requirements. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `claims` +| `array` +| Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. + +This is an alpha field and requires enabling the DynamicResourceAllocation feature gate. + +This field is immutable. It can only be set for containers. + +| `claims[]` +| `object` +| ResourceClaim references one entry in PodSpec.ResourceClaims. + +| `limits` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-api-resource-Quantity[`object (Quantity)`] +| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +| `requests` +| xref:../objects/index.adoc#io-k8s-apimachinery-pkg-api-resource-Quantity[`object (Quantity)`] +| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +|=== +=== .spec.template.spec.resources.claims +Description:: ++ +-- +Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. + +This is an alpha field and requires enabling the DynamicResourceAllocation feature gate. + +This field is immutable. It can only be set for containers. +-- + +Type:: + `array` + + + + +=== .spec.template.spec.resources.claims[] +Description:: ++ +-- +ResourceClaim references one entry in PodSpec.ResourceClaims. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container. + +| `request` +| `string` +| Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request. + |=== === .spec.template.spec.schedulingGates Description:: @@ -7824,6 +7911,20 @@ Possible enum values: | `integer` | The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. Note that this field cannot be set when spec.os.name is windows. +| `seLinuxChangePolicy` +| `string` +| seLinuxChangePolicy defines how the container's SELinux label is applied to all volumes used by the Pod. It has no effect on nodes that do not support SELinux or to volumes does not support SELinux. Valid values are "MountOption" and "Recursive". + +"Recursive" means relabeling of all files on all Pod volumes by the container runtime. This may be slow for large volumes, but allows mixing privileged and unprivileged Pods sharing the same volume on the same node. + +"MountOption" mounts all eligible Pod volumes with `-o context` mount option. This requires all Pods that share the same volume to use the same SELinux label. It is not possible to share the same volume among privileged and unprivileged Pods. Eligible volumes are in-tree FibreChannel and iSCSI volumes, and all CSI volumes whose CSI driver announces SELinux support by setting spec.seLinuxMount: true in their CSIDriver instance. Other volumes are always re-labelled recursively. "MountOption" value is allowed only when SELinuxMount feature gate is enabled. + +If not specified and SELinuxMount feature gate is enabled, "MountOption" is used. If not specified and SELinuxMount feature gate is disabled, "MountOption" is used for ReadWriteOncePod volumes and "Recursive" for all other volumes. + +This field affects only Pods that have SELinux label set, either in PodSecurityContext or in SecurityContext of all containers. + +All Pods that use the same volume should use the same seLinuxChangePolicy, otherwise some pods can get stuck in ContainerCreating state. Note that this field cannot be set when spec.os.name is windows. + | `seLinuxOptions` | `object` | SELinuxOptions are the labels to be applied to the container @@ -8995,14 +9096,7 @@ Type:: | `dataSourceRef` | `object` -| dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn't specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn't set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef: * While dataSource only allows two specific types of objects, dataSourceRef - allows any non-core object, as well as PersistentVolumeClaim objects. -* While dataSource ignores disallowed values (dropping them), dataSourceRef - preserves all values, and generates an error if a disallowed value is - specified. -* While dataSource only allows local objects, dataSourceRef allows objects - in any namespaces. -(Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled. +| TypedObjectReference contains enough information to let you locate the typed referenced object | `resources` | `object` @@ -9070,14 +9164,7 @@ Required:: Description:: + -- -dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn't specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn't set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef: * While dataSource only allows two specific types of objects, dataSourceRef - allows any non-core object, as well as PersistentVolumeClaim objects. -* While dataSource ignores disallowed values (dropping them), dataSourceRef - preserves all values, and generates an error if a disallowed value is - specified. -* While dataSource only allows local objects, dataSourceRef allows objects - in any namespaces. -(Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled. +TypedObjectReference contains enough information to let you locate the typed referenced object -- Type::