From e59b22b53442f1ecc9d9ac3a784360a7023cf4d8 Mon Sep 17 00:00:00 2001 From: JoeAldinger Date: Tue, 27 Jan 2026 14:30:22 -0500 Subject: [PATCH] OSDOCS-15079: update rest_api docs for 4.21 --- _topic_maps/_topic_map.yml | 23 + api-config.yaml | 54 +- .../apiserver-config-openshift-io-v1.adoc | 84 + .../backup-config-openshift-io-v1alpha1.adoc | 558 +++++ ...terimagepolicy-config-openshift-io-v1.adoc | 71 +- ...nitoring-config-openshift-io-v1alpha1.adoc | 2149 +++++++++++++++++ ...clusterversion-config-openshift-io-v1.adoc | 123 + rest_api/config_apis/config-apis-index.adoc | 40 + .../image-config-openshift-io-v1.adoc | 27 + .../imagepolicy-config-openshift-io-v1.adoc | 71 +- ...infrastructure-config-openshift-io-v1.adoc | 270 +++ ...tagather-config-openshift-io-v1alpha2.adoc | 681 ++++++ .../node-config-openshift-io-v1.adoc | 16 + .../consolelink-console-openshift-io-v1.adoc | 2 +- ...enotification-console-openshift-io-v1.adoc | 2 +- ...olequickstart-console-openshift-io-v1.adoc | 12 - ...anemachineset-machine-openshift-io-v1.adoc | 10 + ...neconfiguration-openshift-io-v1alpha1.adoc | 729 ++++++ rest_api/machine_apis/machine-apis-index.adoc | 31 + .../machine-machine-openshift-io-v1beta1.adoc | 23 + ...-machineconfiguration-openshift-io-v1.adoc | 335 +++ ...-machineconfiguration-openshift-io-v1.adoc | 84 + ...chineset-machine-openshift-io-v1beta1.adoc | 33 + ...neconfiguration-openshift-io-v1alpha1.adoc | 521 ++++ ...rconfig-monitoring-coreos-com-v1beta1.adoc | 7 +- ...gather-insights-openshift-io-v1alpha2.adoc | 1142 +++++++++ .../monitoring-apis-index.adoc | 13 + .../podmonitor-monitoring-coreos-com-v1.adoc | 23 +- .../probe-monitoring-coreos-com-v1.adoc | 10 +- .../prometheus-monitoring-coreos-com-v1.adoc | 18 +- ...rvicemonitor-monitoring-coreos-com-v1.adoc | 7 +- .../thanosruler-monitoring-coreos-com-v1.adoc | 14 +- ...esolver-network-openshift-io-v1alpha1.adoc | 674 ++++++ .../gateway-gateway-networking-k8s-io-v1.adoc | 13 +- rest_api/network_apis/network-apis-index.adoc | 14 + rest_api/objects/index.adoc | 492 +++- ...tercsidriver-operator-openshift-io-v1.adoc | 12 + ...erator-operator-openshift-io-v1alpha1.adoc | 440 ++++ .../console-operator-openshift-io-v1.adoc | 24 - .../etcd-operator-openshift-io-v1.adoc | 6 + ...backup-operator-openshift-io-v1alpha1.adoc | 550 +++++ ...sscontroller-operator-openshift-io-v1.adoc | 80 +- ...ubeapiserver-operator-openshift-io-v1.adoc | 11 + ...onfiguration-operator-openshift-io-v1.adoc | 292 +++ .../operator_apis/operator-apis-index.adoc | 26 + ...nrevision-olm-operatorframework-io-v1.adoc | 647 ----- .../olm-operator-openshift-io-v1.adoc | 607 +++++ .../operatorhub-apis-index.adoc | 17 +- rest_api/overview/index.adoc | 26 +- .../baremetalhost-metal3-io-v1alpha1.adoc | 35 +- .../hardwaredata-metal3-io-v1alpha1.adoc | 34 + .../provisioning-metal3-io-v1alpha1.adoc | 6 + 52 files changed, 10352 insertions(+), 837 deletions(-) create mode 100644 rest_api/config_apis/backup-config-openshift-io-v1alpha1.adoc create mode 100644 rest_api/config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc create mode 100644 rest_api/config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc create mode 100644 rest_api/machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc create mode 100644 rest_api/machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc create mode 100644 rest_api/monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc create mode 100644 rest_api/network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc create mode 100644 rest_api/operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc create mode 100644 rest_api/operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc create mode 100644 rest_api/operatorhub_apis/olm-operator-openshift-io-v1.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index a06909731e..55f85cdd1c 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -3191,6 +3191,7 @@ Topics: File: otel-installing - Name: Configuring the Collector Dir: otel-collector + Distros: openshift-enterprise Topics: - Name: Collector options File: otel-collector-configuration-intro @@ -3232,6 +3233,7 @@ Topics: File: network-observability-operator-release-notes - Name: Network Observability Operator release notes archive Dir: release_notes_archive + Distros: openshift-enterprise Topics: - Name: Network Observability Operator release notes archive File: network-observability-operator-release-notes-archive @@ -3259,6 +3261,7 @@ Topics: File: network-observability-secondary-networks - Name: Network Observability CLI Dir: netobserv_cli + Distros: openshift-enterprise Topics: - Name: Installing the Network Observability CLI File: netobserv-cli-install @@ -4003,12 +4006,16 @@ Topics: File: apiserver-config-openshift-io-v1 - Name: 'Authentication [config.openshift.io/v1]' File: authentication-config-openshift-io-v1 + - Name: 'Backup [config.openshift.io/v1alpha1]' + File: backup-config-openshift-io-v1alpha1 - Name: 'Build [config.openshift.io/v1]' File: build-config-openshift-io-v1 - Name: 'ClusterImagePolicy [config.openshift.io/v1]' File: clusterimagepolicy-config-openshift-io-v1 - Name: 'ClusterOperator [config.openshift.io/v1]' File: clusteroperator-config-openshift-io-v1 + - Name: 'ClusterMonitoring [config.openshift.io/v1alpha1]' + File: clustermonitoring-config-openshift-io-v1alpha1 - Name: 'ClusterVersion [config.openshift.io/v1]' File: clusterversion-config-openshift-io-v1 - Name: 'Console [config.openshift.io/v1]' @@ -4029,6 +4036,8 @@ Topics: File: imagepolicy-config-openshift-io-v1 - Name: 'ImageTagMirrorSet [config.openshift.io/v1]' File: imagetagmirrorset-config-openshift-io-v1 + - Name: 'InsightsDataGather [config.openshift.io/v1alpha2]' + File: insightsdatagather-config-openshift-io-v1alpha2 - Name: 'Infrastructure [config.openshift.io/v1]' File: infrastructure-config-openshift-io-v1 - Name: 'Ingress [config.openshift.io/v1]' @@ -4141,6 +4150,10 @@ Topics: File: machineosbuild-machineconfiguration-openshift-io-v1 - Name: 'MachineOSConfig [machineconfiguration.openshift.io/v1]' File: machineosconfig-machineconfiguration-openshift-io-v1 + - Name: 'InternalReleaseImage [machineconfiguration.openshift.io/v1alpha1]' + File: internalreleaseimage-machineconfiguration-openshift-io-v1alpha1 + - Name: 'OSImageStream [machineconfiguration.openshift.io/v1alpha1]' + File: osimagestream-machineconfiguration-openshift-io-v1alpha1 - Name: 'PinnedImageSet [machineconfiguration.openshift.io/v1]' File: pinnedimageset-machineconfiguration-openshift-io-v1 - Name: Metadata APIs @@ -4179,6 +4192,8 @@ Topics: File: alertrelabelconfig-monitoring-openshift-io-v1 - Name: 'AlertingRule [monitoring.openshift.io/v1]' File: alertingrule-monitoring-openshift-io-v1 + - Name: 'DataGather [insights.openshift.io/v1alpha2]' + File: datagather-insights-openshift-io-v1alpha2 - Name: 'PodMonitor [monitoring.coreos.com/v1]' File: podmonitor-monitoring-coreos-com-v1 - Name: 'Probe [monitoring.coreos.com/v1]' @@ -4210,6 +4225,8 @@ Topics: File: baselineadminnetworkpolicy-policy-networking-k8s-io-v1alpha1 - Name: 'CloudPrivateIPConfig [cloud.network.openshift.io/v1]' File: cloudprivateipconfig-cloud-network-openshift-io-v1 + - Name: 'DNSNameResolver [network.openshift.io/v1alpha1]' + File: dnsnameresolver-network-openshift-io-v1alpha1 - Name: 'EgressFirewall [k8s.ovn.org/v1]' File: egressfirewall-k8s-ovn-org-v1 - Name: 'EgressIP [k8s.ovn.org/v1]' @@ -4305,6 +4322,8 @@ Topics: File: authentication-operator-openshift-io-v1 - Name: 'CloudCredential [operator.openshift.io/v1]' File: cloudcredential-operator-openshift-io-v1 + - Name: 'ClusterVersionOperator [operator.openshift.io/v1alpha1]' + File: clusterversionoperator-operator-openshift-io-v1alpha1 - Name: 'ClusterCSIDriver [operator.openshift.io/v1]' File: clustercsidriver-operator-openshift-io-v1 - Name: 'Console [operator.openshift.io/v1]' @@ -4323,6 +4342,8 @@ Topics: File: dnsrecord-ingress-operator-openshift-io-v1 - Name: 'Etcd [operator.openshift.io/v1]' File: etcd-operator-openshift-io-v1 + - Name: 'EtcdBackup [operator.openshift.io/v1alpha1]' + File: etcdbackup-operator-openshift-io-v1alpha1 - Name: 'ImageContentSourcePolicy [operator.openshift.io/v1alpha1]' File: imagecontentsourcepolicy-operator-openshift-io-v1alpha1 - Name: 'ImagePruner [imageregistry.operator.openshift.io/v1]' @@ -4370,6 +4391,8 @@ Topics: File: clusterserviceversion-operators-coreos-com-v1alpha1 - Name: 'InstallPlan [operators.coreos.com/v1alpha1]' File: installplan-operators-coreos-com-v1alpha1 + - Name: 'OLM [operator.openshift.io/v1]' + File: olm-operator-openshift-io-v1 - Name: 'OLMConfig [operators.coreos.com/v1]' File: olmconfig-operators-coreos-com-v1 - Name: 'Operator [operators.coreos.com/v1]' diff --git a/api-config.yaml b/api-config.yaml index 359a805a9f..ba95ef456f 100644 --- a/api-config.yaml +++ b/api-config.yaml @@ -111,12 +111,6 @@ apiMap: # - kind: GCPManagedMachinePool # group: infrastructure.cluster.x-k8s.io # version: v1beta1 - - kind: IPAddress - group: ipam.cluster.x-k8s.io - version: v1beta1 - - kind: IPAddressClaim - group: ipam.cluster.x-k8s.io - version: v1beta1 - name: Config APIs resources: - kind: APIServer @@ -125,9 +119,9 @@ apiMap: - kind: Authentication group: config.openshift.io version: v1 -# - kind: Backup -# group: config.openshift.io -# version: v1alpha1 + - kind: Backup + group: config.openshift.io + version: v1alpha1 - kind: Build group: config.openshift.io version: v1 @@ -137,6 +131,9 @@ apiMap: - kind: ClusterOperator group: config.openshift.io version: v1 + - kind: ClusterMonitoring + group: config.openshift.io + version: v1alpha1 - kind: ClusterVersion group: config.openshift.io version: v1 @@ -167,9 +164,9 @@ apiMap: - kind: ImageTagMirrorSet group: config.openshift.io version: v1 -# - kind: InsightsDataGather -# group: config.openshift.io -# version: v1alpha1 + - kind: InsightsDataGather + group: config.openshift.io + version: v1alpha2 - kind: Infrastructure group: config.openshift.io version: v1 @@ -316,6 +313,12 @@ apiMap: - kind: MachineOSConfig group: machineconfiguration.openshift.io version: v1 + - kind: InternalReleaseImage + group: machineconfiguration.openshift.io + version: v1alpha1 + - kind: OSImageStream + group: machineconfiguration.openshift.io + version: v1alpha1 - kind: PinnedImageSet group: machineconfiguration.openshift.io version: v1 @@ -360,9 +363,9 @@ apiMap: - kind: AlertingRule group: monitoring.openshift.io version: v1 -# - kind: DataGather -# group: insights.openshift.io -# version: v1alpha1 + - kind: DataGather + group: insights.openshift.io + version: v1alpha2 - kind: PodMonitor group: monitoring.coreos.com version: v1 @@ -404,9 +407,9 @@ apiMap: - kind: CloudPrivateIPConfig group: cloud.network.openshift.io version: v1 -# - kind: DNSNameResolver -# group: network.openshift.io -# version: v1alpha1 + - kind: DNSNameResolver + group: network.openshift.io + version: v1alpha1 - kind: EgressFirewall group: k8s.ovn.org version: v1 @@ -536,6 +539,9 @@ apiMap: - kind: CloudCredential group: operator.openshift.io version: v1 + - kind: ClusterVersionOperator + group: operator.openshift.io + version: v1alpha1 - kind: ClusterCSIDriver group: operator.openshift.io version: v1 @@ -563,9 +569,9 @@ apiMap: - kind: Etcd group: operator.openshift.io version: v1 -# - kind: EtcdBackup -# group: operator.openshift.io -# version: v1alpha1 + - kind: EtcdBackup + group: operator.openshift.io + version: v1alpha1 - kind: ImageContentSourcePolicy group: operator.openshift.io version: v1alpha1 @@ -631,9 +637,9 @@ apiMap: - kind: InstallPlan group: operators.coreos.com version: v1alpha1 -# - kind: OLM -# group: operator.openshift.io -# version: v1 + - kind: OLM + group: operator.openshift.io + version: v1 - kind: OLMConfig group: operators.coreos.com version: v1 diff --git a/rest_api/config_apis/apiserver-config-openshift-io-v1.adoc b/rest_api/config_apis/apiserver-config-openshift-io-v1.adoc index 8a18509541..e262e9b974 100644 --- a/rest_api/config_apis/apiserver-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/apiserver-config-openshift-io-v1.adoc @@ -261,6 +261,16 @@ Type:: |=== | Property | Type | Description +| `kms` +| `object` +| kms defines the configuration for the external KMS instance that manages the encryption keys, +when KMS encryption is enabled sensitive resources will be encrypted using keys managed by an +externally configured KMS instance. + +The Key Management Service (KMS) instance provides symmetric encryption and is responsible for +managing the lifecyle of the encryption keys outside of the control plane. +This allows integration with an external provider to manage the data encryption keys securely. + | `type` | `string` | type defines what encryption type should be used to encrypt resources at the datastore layer. @@ -277,6 +287,80 @@ This list of sensitive resources can and will change over time. The current aut 4. oauthaccesstokens.oauth.openshift.io 5. oauthauthorizetokens.oauth.openshift.io +|=== +=== .spec.encryption.kms +Description:: ++ +-- +kms defines the configuration for the external KMS instance that manages the encryption keys, +when KMS encryption is enabled sensitive resources will be encrypted using keys managed by an +externally configured KMS instance. + +The Key Management Service (KMS) instance provides symmetric encryption and is responsible for +managing the lifecyle of the encryption keys outside of the control plane. +This allows integration with an external provider to manage the data encryption keys securely. +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `aws` +| `object` +| aws defines the key config for using an AWS KMS instance +for the encryption. The AWS KMS instance is managed +by the user outside the purview of the control plane. + +| `type` +| `string` +| type defines the kind of platform for the KMS provider. +Available provider types are AWS only. + +|=== +=== .spec.encryption.kms.aws +Description:: ++ +-- +aws defines the key config for using an AWS KMS instance +for the encryption. The AWS KMS instance is managed +by the user outside the purview of the control plane. +-- + +Type:: + `object` + +Required:: + - `keyARN` + - `region` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `keyARN` +| `string` +| keyARN specifies the Amazon Resource Name (ARN) of the AWS KMS key used for encryption. +The value must adhere to the format `arn:aws:kms:::key/`, where: +- `` is the AWS region consisting of lowercase letters and hyphens followed by a number. +- `` is a 12-digit numeric identifier for the AWS account. +- `` is a unique identifier for the KMS key, consisting of lowercase hexadecimal characters and hyphens. + +| `region` +| `string` +| region specifies the AWS region where the KMS instance exists, and follows the format +`--`, e.g.: `us-east-1`. +Only lowercase letters and hyphens followed by numbers are allowed. + |=== === .spec.servingCerts Description:: diff --git a/rest_api/config_apis/backup-config-openshift-io-v1alpha1.adoc b/rest_api/config_apis/backup-config-openshift-io-v1alpha1.adoc new file mode 100644 index 0000000000..8394176630 --- /dev/null +++ b/rest_api/config_apis/backup-config-openshift-io-v1alpha1.adoc @@ -0,0 +1,558 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="backup-config-openshift-io-v1alpha1"] += Backup [config.openshift.io/v1alpha1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +Backup provides configuration for performing backups of the openshift cluster. + +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` + +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 holds user settable values for configuration + +| `status` +| `object` +| status holds observed values from the cluster. They may not be overridden. + +|=== +=== .spec +Description:: ++ +-- +spec holds user settable values for configuration +-- + +Type:: + `object` + +Required:: + - `etcd` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `etcd` +| `object` +| etcd specifies the configuration for periodic backups of the etcd cluster + +|=== +=== .spec.etcd +Description:: ++ +-- +etcd specifies the configuration for periodic backups of the etcd cluster +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `pvcName` +| `string` +| pvcName specifies the name of the PersistentVolumeClaim (PVC) which binds a PersistentVolume where the +etcd backup files would be saved +The PVC itself must always be created in the "openshift-etcd" namespace +If the PVC is left unspecified "" then the platform will choose a reasonable default location to save the backup. +In the future this would be backups saved across the control-plane master nodes. + +| `retentionPolicy` +| `object` +| retentionPolicy defines the retention policy for retaining and deleting existing backups. + +| `schedule` +| `string` +| schedule defines the recurring backup schedule in Cron format +every 2 hours: 0 */2 * * * +every day at 3am: 0 3 * * * +Empty string means no opinion and the platform is left to choose a reasonable default which is subject to change without notice. +The current default is "no backups", but will change in the future. + +| `timeZone` +| `string` +| The time zone name for the given schedule, see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. +If not specified, this will default to the time zone of the kube-controller-manager process. +See https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#time-zones + +|=== +=== .spec.etcd.retentionPolicy +Description:: ++ +-- +retentionPolicy defines the retention policy for retaining and deleting existing backups. +-- + +Type:: + `object` + +Required:: + - `retentionType` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `retentionNumber` +| `object` +| retentionNumber configures the retention policy based on the number of backups + +| `retentionSize` +| `object` +| retentionSize configures the retention policy based on the size of backups + +| `retentionType` +| `string` +| retentionType sets the type of retention policy. +Currently, the only valid policies are retention by number of backups (RetentionNumber), by the size of backups (RetentionSize). More policies or types may be added in the future. +Empty string means no opinion and the platform is left to choose a reasonable default which is subject to change without notice. +The current default is RetentionNumber with 15 backups kept. + +|=== +=== .spec.etcd.retentionPolicy.retentionNumber +Description:: ++ +-- +retentionNumber configures the retention policy based on the number of backups +-- + +Type:: + `object` + +Required:: + - `maxNumberOfBackups` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `maxNumberOfBackups` +| `integer` +| maxNumberOfBackups defines the maximum number of backups to retain. +If the existing number of backups saved is equal to MaxNumberOfBackups then +the oldest backup will be removed before a new backup is initiated. + +|=== +=== .spec.etcd.retentionPolicy.retentionSize +Description:: ++ +-- +retentionSize configures the retention policy based on the size of backups +-- + +Type:: + `object` + +Required:: + - `maxSizeOfBackupsGb` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `maxSizeOfBackupsGb` +| `integer` +| maxSizeOfBackupsGb defines the total size in GB of backups to retain. +If the current total size backups exceeds MaxSizeOfBackupsGb then +the oldest backup will be removed before a new backup is initiated. + +|=== +=== .status +Description:: ++ +-- +status holds observed values from the cluster. They may not be overridden. +-- + +Type:: + `object` + + + + + +== API endpoints + +The following API endpoints are available: + +* `/apis/config.openshift.io/v1alpha1/backups` +- `DELETE`: delete collection of Backup +- `GET`: list objects of kind Backup +- `POST`: create a Backup +* `/apis/config.openshift.io/v1alpha1/backups/{name}` +- `DELETE`: delete a Backup +- `GET`: read the specified Backup +- `PATCH`: partially update the specified Backup +- `PUT`: replace the specified Backup +* `/apis/config.openshift.io/v1alpha1/backups/{name}/status` +- `GET`: read status of the specified Backup +- `PATCH`: partially update status of the specified Backup +- `PUT`: replace status of the specified Backup + + +=== /apis/config.openshift.io/v1alpha1/backups + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of Backup + + + + +.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 Backup + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-config-v1alpha1-BackupList[`BackupList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a Backup + + +.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:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 201 - Created +| xref:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 202 - Accepted +| xref:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/config.openshift.io/v1alpha1/backups/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the Backup +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a Backup + + +.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 Backup + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified Backup + + +.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:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified Backup + + +.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:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 201 - Created +| xref:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/config.openshift.io/v1alpha1/backups/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the Backup +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified Backup + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified Backup + + +.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:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified Backup + + +.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:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 201 - Created +| xref:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`Backup`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/config_apis/clusterimagepolicy-config-openshift-io-v1.adoc b/rest_api/config_apis/clusterimagepolicy-config-openshift-io-v1.adoc index 1d32cf7f3e..0d4f8ce78c 100644 --- a/rest_api/config_apis/clusterimagepolicy-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/clusterimagepolicy-config-openshift-io-v1.adoc @@ -148,13 +148,18 @@ fulcioCAWithRekor is required when policyType is FulcioCAWithRekor, and forbidde For more information about Fulcio and Rekor, please refer to the document at: https://github.com/sigstore/fulcio and https://github.com/sigstore/rekor +| `pki` +| `object` +| pki defines the root of trust configuration based on Bring Your Own Public Key Infrastructure (BYOPKI) Root CA(s) and corresponding intermediate certificates. +pki is required when policyType is PKI, and forbidden otherwise. + | `policyType` | `string` | policyType is a required field specifies the type of the policy for verification. This field must correspond to how the policy was generated. Allowed values are "PublicKey", "FulcioCAWithRekor", and "PKI". When set to "PublicKey", the policy relies on a sigstore publicKey and may optionally use a Rekor verification. When set to "FulcioCAWithRekor", the policy is based on the Fulcio certification and incorporates a Rekor verification. -When set to "PKI", the policy is based on the certificates from Bring Your Own Public Key Infrastructure (BYOPKI). This value is enabled by turning on the SigstoreImageVerificationPKI feature gate. +When set to "PKI", the policy is based on the certificates from Bring Your Own Public Key Infrastructure (BYOPKI). | `publicKey` | `object` @@ -234,6 +239,70 @@ Example: "https://expected.OIDC.issuer/" The signedEmail must be a valid email address and at most 320 characters in length. Example: "expected-signing-user@example.com" +|=== +=== .spec.policy.rootOfTrust.pki +Description:: ++ +-- +pki defines the root of trust configuration based on Bring Your Own Public Key Infrastructure (BYOPKI) Root CA(s) and corresponding intermediate certificates. +pki is required when policyType is PKI, and forbidden otherwise. +-- + +Type:: + `object` + +Required:: + - `caRootsData` + - `pkiCertificateSubject` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `caIntermediatesData` +| `string` +| caIntermediatesData contains base64-encoded data of a certificate bundle PEM file, which contains one or more intermediate certificates in the PEM format. The total length of the data must not exceed 8192 characters. +caIntermediatesData requires caRootsData to be set. + +| `caRootsData` +| `string` +| caRootsData contains base64-encoded data of a certificate bundle PEM file, which contains one or more CA roots in the PEM format. The total length of the data must not exceed 8192 characters. + +| `pkiCertificateSubject` +| `object` +| pkiCertificateSubject defines the requirements imposed on the subject to which the certificate was issued. + +|=== +=== .spec.policy.rootOfTrust.pki.pkiCertificateSubject +Description:: ++ +-- +pkiCertificateSubject defines the requirements imposed on the subject to which the certificate was issued. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `email` +| `string` +| email specifies the expected email address imposed on the subject to which the certificate was issued, and must match the email address listed in the Subject Alternative Name (SAN) field of the certificate. +The email must be a valid email address and at most 320 characters in length. + +| `hostname` +| `string` +| hostname specifies the expected hostname imposed on the subject to which the certificate was issued, and it must match the hostname listed in the Subject Alternative Name (SAN) DNS field of the certificate. +The hostname must be a valid dns 1123 subdomain name, optionally prefixed by '*.', and at most 253 characters in length. +It must consist only of lowercase alphanumeric characters, hyphens, periods and the optional preceding asterisk. + |=== === .spec.policy.rootOfTrust.publicKey Description:: diff --git a/rest_api/config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc b/rest_api/config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc new file mode 100644 index 0000000000..3805833d98 --- /dev/null +++ b/rest_api/config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc @@ -0,0 +1,2149 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="clustermonitoring-config-openshift-io-v1alpha1"] += ClusterMonitoring [config.openshift.io/v1alpha1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +ClusterMonitoring is the Custom Resource object which holds the current status of Cluster Monitoring Operator. CMO is a central component of the monitoring stack. + +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. +ClusterMonitoring is the Schema for the Cluster Monitoring Operators API +-- + +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 holds user configuration for the Cluster Monitoring Operator + +| `status` +| `object` +| status holds observed values from the cluster. They may not be overridden. + +|=== +=== .spec +Description:: ++ +-- +spec holds user configuration for the Cluster Monitoring Operator +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `alertmanagerConfig` +| `object` +| alertmanagerConfig allows users to configure how the default Alertmanager instance +should be deployed in the `openshift-monitoring` namespace. +alertmanagerConfig is optional. +When omitted, this means no opinion and the platform is left to choose a reasonable default, that is subject to change over time. +The current default value is `DefaultConfig`. + +| `metricsServerConfig` +| `object` +| metricsServerConfig is an optional field that can be used to configure the Kubernetes Metrics Server that runs in the openshift-monitoring namespace. +Specifically, it can configure how the Metrics Server instance is deployed, pod scheduling, its audit policy and log verbosity. +When omitted, this means no opinion and the platform is left to choose a reasonable default, which is subject to change over time. + +| `userDefined` +| `object` +| userDefined set the deployment mode for user-defined monitoring in addition to the default platform monitoring. +userDefined is optional. +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 value is `Disabled`. + +|=== +=== .spec.alertmanagerConfig +Description:: ++ +-- +alertmanagerConfig allows users to configure how the default Alertmanager instance +should be deployed in the `openshift-monitoring` namespace. +alertmanagerConfig is optional. +When omitted, this means no opinion and the platform is left to choose a reasonable default, that is subject to change over time. +The current default value is `DefaultConfig`. +-- + +Type:: + `object` + +Required:: + - `deploymentMode` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `customConfig` +| `object` +| customConfig must be set when deploymentMode is CustomConfig, and must be unset otherwise. +When set to CustomConfig, the Alertmanager will be deployed with custom configuration. + +| `deploymentMode` +| `string` +| deploymentMode determines whether the default Alertmanager instance should be deployed +as part of the monitoring stack. +Allowed values are Disabled, DefaultConfig, and CustomConfig. +When set to Disabled, the Alertmanager instance will not be deployed. +When set to DefaultConfig, the platform will deploy Alertmanager with default settings. +When set to CustomConfig, the Alertmanager will be deployed with custom configuration. + +|=== +=== .spec.alertmanagerConfig.customConfig +Description:: ++ +-- +customConfig must be set when deploymentMode is CustomConfig, and must be unset otherwise. +When set to CustomConfig, the Alertmanager will be deployed with custom configuration. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `logLevel` +| `string` +| logLevel defines the verbosity of logs emitted by Alertmanager. +This field allows users to control the amount and severity of logs generated, which can be useful +for debugging issues or reducing noise in production environments. +Allowed values are Error, Warn, Info, and Debug. +When set to Error, only errors will be logged. +When set to Warn, both warnings and errors will be logged. +When set to Info, general information, warnings, and errors will all be logged. +When set to Debug, detailed debugging information will be logged. +When omitted, this means no opinion and the platform is left to choose a reasonable default, that is subject to change over time. +The current default value is `Info`. + +| `nodeSelector` +| `object (string)` +| nodeSelector defines the nodes on which the Pods are scheduled +nodeSelector is optional. + +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +The current default value is `kubernetes.io/os: linux`. + +| `resources` +| `array` +| resources defines the compute resource requests and limits for the Alertmanager container. +This includes CPU, memory and HugePages constraints to help control scheduling and resource usage. +When not specified, defaults are used by the platform. Requests cannot exceed limits. +This field is optional. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +This is a simplified API that maps to Kubernetes ResourceRequirements. +The current default values are: + resources: + - name: cpu + request: 4m + limit: null + - name: memory + request: 40Mi + limit: null +Maximum length for this list is 10. +Minimum length for this list is 1. + +| `resources[]` +| `object` +| ContainerResource defines a single resource requirement for a container. + +| `secrets` +| `array (string)` +| secrets defines a list of secrets that need to be mounted into the Alertmanager. +The secrets must reside within the same namespace as the Alertmanager object. +They will be added as volumes named secret- and mounted at +/etc/alertmanager/secrets/ within the 'alertmanager' container of +the Alertmanager Pods. + +These secrets can be used to authenticate Alertmanager with endpoint receivers. +For example, you can use secrets to: +- Provide certificates for TLS authentication with receivers that require private CA certificates +- Store credentials for Basic HTTP authentication with receivers that require password-based auth +- Store any other authentication credentials needed by your alert receivers + +This field is optional. +Maximum length for this list is 10. +Minimum length for this list is 1. +Entries in this list must be unique. + +| `tolerations` +| `array` +| tolerations defines tolerations for the pods. +tolerations is optional. + +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +Defaults are empty/unset. +Maximum length for this list is 10 +Minimum length for this list is 1 + +| `tolerations[]` +| `object` +| The pod this Toleration is attached to tolerates any taint that matches +the triple using the matching operator . + +| `topologySpreadConstraints` +| `array` +| topologySpreadConstraints defines rules for how Alertmanager Pods should be distributed +across topology domains such as zones, nodes, or other user-defined labels. +topologySpreadConstraints is optional. +This helps improve high availability and resource efficiency by avoiding placing +too many replicas in the same failure domain. + +When omitted, this means no opinion and the platform is left to choose a default, which is subject to change over time. +This field maps directly to the `topologySpreadConstraints` field in the Pod spec. +Default is empty list. +Maximum length for this list is 10. +Minimum length for this list is 1 +Entries must have unique topologyKey and whenUnsatisfiable pairs. + +| `topologySpreadConstraints[]` +| `object` +| TopologySpreadConstraint specifies how to spread matching pods among the given topology. + +| `volumeClaimTemplate` +| `object` +| volumeClaimTemplate Defines persistent storage for Alertmanager. Use this setting to +configure the persistent volume claim, including storage class, volume +size, and name. +If omitted, the Pod uses ephemeral storage and alert data will not persist +across restarts. +This field is optional. + +|=== +=== .spec.alertmanagerConfig.customConfig.resources +Description:: ++ +-- +resources defines the compute resource requests and limits for the Alertmanager container. +This includes CPU, memory and HugePages constraints to help control scheduling and resource usage. +When not specified, defaults are used by the platform. Requests cannot exceed limits. +This field is optional. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +This is a simplified API that maps to Kubernetes ResourceRequirements. +The current default values are: + resources: + - name: cpu + request: 4m + limit: null + - name: memory + request: 40Mi + limit: null +Maximum length for this list is 10. +Minimum length for this list is 1. +-- + +Type:: + `array` + + + + +=== .spec.alertmanagerConfig.customConfig.resources[] +Description:: ++ +-- +ContainerResource defines a single resource requirement for a container. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `limit` +| `integer-or-string` +| limit is the maximum amount of the resource allowed (e.g. "2Mi", "1Gi"). +This field is optional. +When request is specified, limit cannot be less than request. +The value must be greater than 0 when specified. + +| `name` +| `string` +| name of the resource (e.g. "cpu", "memory", "hugepages-2Mi"). +This field is required. +name must consist only of alphanumeric characters, `-`, `_` and `.` and must start and end with an alphanumeric character. + +| `request` +| `integer-or-string` +| request is the minimum amount of the resource required (e.g. "2Mi", "1Gi"). +This field is optional. +When limit is specified, request cannot be greater than limit. + +|=== +=== .spec.alertmanagerConfig.customConfig.tolerations +Description:: ++ +-- +tolerations defines tolerations for the pods. +tolerations is optional. + +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +Defaults are empty/unset. +Maximum length for this list is 10 +Minimum length for this list is 1 +-- + +Type:: + `array` + + + + +=== .spec.alertmanagerConfig.customConfig.tolerations[] +Description:: ++ +-- +The pod this Toleration is attached to tolerates any taint that matches +the triple using the matching operator . +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `effect` +| `string` +| Effect indicates the taint effect to match. Empty means match all taint effects. +When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. + +| `key` +| `string` +| Key is the taint key that the toleration applies to. Empty means match all taint keys. +If the key is empty, operator must be Exists; this combination means to match all values and all keys. + +| `operator` +| `string` +| Operator represents a key's relationship to the value. +Valid operators are Exists and Equal. Defaults to Equal. +Exists is equivalent to wildcard for value, so that a pod can +tolerate all taints of a particular category. + +| `tolerationSeconds` +| `integer` +| TolerationSeconds represents the period of time the toleration (which must be +of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, +it is not set, which means tolerate the taint forever (do not evict). Zero and +negative values will be treated as 0 (evict immediately) by the system. + +| `value` +| `string` +| Value is the taint value the toleration matches to. +If the operator is Exists, the value should be empty, otherwise just a regular string. + +|=== +=== .spec.alertmanagerConfig.customConfig.topologySpreadConstraints +Description:: ++ +-- +topologySpreadConstraints defines rules for how Alertmanager Pods should be distributed +across topology domains such as zones, nodes, or other user-defined labels. +topologySpreadConstraints is optional. +This helps improve high availability and resource efficiency by avoiding placing +too many replicas in the same failure domain. + +When omitted, this means no opinion and the platform is left to choose a default, which is subject to change over time. +This field maps directly to the `topologySpreadConstraints` field in the Pod spec. +Default is empty list. +Maximum length for this list is 10. +Minimum length for this list is 1 +Entries must have unique topologyKey and whenUnsatisfiable pairs. +-- + +Type:: + `array` + + + + +=== .spec.alertmanagerConfig.customConfig.topologySpreadConstraints[] +Description:: ++ +-- +TopologySpreadConstraint specifies how to spread matching pods among the given topology. +-- + +Type:: + `object` + +Required:: + - `maxSkew` + - `topologyKey` + - `whenUnsatisfiable` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `labelSelector` +| `object` +| LabelSelector is used to find matching pods. +Pods that match this label selector are counted to determine the number of pods +in their corresponding topology domain. + +| `matchLabelKeys` +| `array (string)` +| MatchLabelKeys is a set of pod label keys to select the pods over which +spreading will be calculated. The keys are used to lookup values from the +incoming pod labels, those key-value labels are ANDed with labelSelector +to select the group of existing pods over which spreading will be calculated +for the incoming pod. The same key is forbidden to exist in both MatchLabelKeys and LabelSelector. +MatchLabelKeys cannot be set when LabelSelector isn't set. +Keys that don't exist in the incoming pod labels will +be ignored. A null or empty list means only match against labelSelector. + +This is a beta field and requires the MatchLabelKeysInPodTopologySpread feature gate to be enabled (enabled by default). + +| `maxSkew` +| `integer` +| MaxSkew describes the degree to which pods may be unevenly distributed. +When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference +between the number of matching pods in the target topology and the global minimum. +The global minimum is the minimum number of matching pods in an eligible domain +or zero if the number of eligible domains is less than MinDomains. +For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same +labelSelector spread as 2/2/1: +In this case, the global minimum is 1. +\| zone1 \| zone2 \| zone3 \| +\| P P \| P P \| P \| +- if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 2/2/2; +scheduling it onto zone1(zone2) would make the ActualSkew(3-1) on zone1(zone2) +violate MaxSkew(1). +- if MaxSkew is 2, incoming pod can be scheduled onto any zone. +When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence +to topologies that satisfy it. +It's a required field. Default value is 1 and 0 is not allowed. + +| `minDomains` +| `integer` +| MinDomains indicates a minimum number of eligible domains. +When the number of eligible domains with matching topology keys is less than minDomains, +Pod Topology Spread treats "global minimum" as 0, and then the calculation of Skew is performed. +And when the number of eligible domains with matching topology keys equals or greater than minDomains, +this value has no effect on scheduling. +As a result, when the number of eligible domains is less than minDomains, +scheduler won't schedule more than maxSkew Pods to those domains. +If value is nil, the constraint behaves as if MinDomains is equal to 1. +Valid values are integers greater than 0. +When value is not nil, WhenUnsatisfiable must be DoNotSchedule. + +For example, in a 3-zone cluster, MaxSkew is set to 2, MinDomains is set to 5 and pods with the same +labelSelector spread as 2/2/2: +\| zone1 \| zone2 \| zone3 \| +\| P P \| P P \| P P \| +The number of domains is less than 5(MinDomains), so "global minimum" is treated as 0. +In this situation, new pod with the same labelSelector cannot be scheduled, +because computed skew will be 3(3 - 0) if new Pod is scheduled to any of the three zones, +it will violate MaxSkew. + +| `nodeAffinityPolicy` +| `string` +| NodeAffinityPolicy indicates how we will treat Pod's nodeAffinity/nodeSelector +when calculating pod topology spread skew. Options are: +- Honor: only nodes matching nodeAffinity/nodeSelector are included in the calculations. +- Ignore: nodeAffinity/nodeSelector are ignored. All nodes are included in the calculations. + +If this value is nil, the behavior is equivalent to the Honor policy. + +| `nodeTaintsPolicy` +| `string` +| NodeTaintsPolicy indicates how we will treat node taints when calculating +pod topology spread skew. Options are: +- Honor: nodes without taints, along with tainted nodes for which the incoming pod +has a toleration, are included. +- Ignore: node taints are ignored. All nodes are included. + +If this value is nil, the behavior is equivalent to the Ignore policy. + +| `topologyKey` +| `string` +| TopologyKey is the key of node labels. Nodes that have a label with this key +and identical values are considered to be in the same topology. +We consider each as a "bucket", and try to put balanced number +of pods into each bucket. +We define a domain as a particular instance of a topology. +Also, we define an eligible domain as a domain whose nodes meet the requirements of +nodeAffinityPolicy and nodeTaintsPolicy. +e.g. If TopologyKey is "kubernetes.io/hostname", each Node is a domain of that topology. +And, if TopologyKey is "topology.kubernetes.io/zone", each zone is a domain of that topology. +It's a required field. + +| `whenUnsatisfiable` +| `string` +| WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy +the spread constraint. +- DoNotSchedule (default) tells the scheduler not to schedule it. +- ScheduleAnyway tells the scheduler to schedule the pod in any location, + but giving higher precedence to topologies that would help reduce the + skew. +A constraint is considered "Unsatisfiable" for an incoming pod +if and only if every possible node assignment for that pod would violate +"MaxSkew" on some topology. +For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same +labelSelector spread as 3/1/1: +\| zone1 \| zone2 \| zone3 \| +\| P P P \| P \| P \| +If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled +to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies +MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler +won't make it *more* imbalanced. +It's a required field. + +|=== +=== .spec.alertmanagerConfig.customConfig.topologySpreadConstraints[].labelSelector +Description:: ++ +-- +LabelSelector is used to find matching pods. +Pods that match this label selector are counted to determine the number of pods +in their corresponding topology domain. +-- + +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.alertmanagerConfig.customConfig.topologySpreadConstraints[].labelSelector.matchExpressions +Description:: ++ +-- +matchExpressions is a list of label selector requirements. The requirements are ANDed. +-- + +Type:: + `array` + + + + +=== .spec.alertmanagerConfig.customConfig.topologySpreadConstraints[].labelSelector.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.alertmanagerConfig.customConfig.volumeClaimTemplate +Description:: ++ +-- +volumeClaimTemplate Defines persistent storage for Alertmanager. Use this setting to +configure the persistent volume claim, including storage class, volume +size, and name. +If omitted, the Pod uses ephemeral storage and alert data will not persist +across restarts. +This field is optional. +-- + +Type:: + `object` + + + + +[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` +| `object` +| 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 characteristics of a volume requested by a pod author. +More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims + +| `status` +| `object` +| status represents the current information/status of a persistent volume claim. +Read-only. +More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims + +|=== +=== .spec.alertmanagerConfig.customConfig.volumeClaimTemplate.metadata +Description:: ++ +-- +Standard object's metadata. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata +-- + +Type:: + `object` + + + + +=== .spec.alertmanagerConfig.customConfig.volumeClaimTemplate.spec +Description:: ++ +-- +spec defines the desired characteristics of a volume requested by a pod author. +More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `accessModes` +| `array (string)` +| accessModes contains the desired access modes the volume should have. +More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 + +| `dataSource` +| `object` +| dataSource field can be used to specify either: +* An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot) +* An existing PVC (PersistentVolumeClaim) +If the provisioner or an external controller can support the specified data source, +it will create a new volume based on the contents of the specified data source. +When the AnyVolumeDataSource feature gate is enabled, dataSource contents will be copied to dataSourceRef, +and dataSourceRef contents will be copied to dataSource when dataSourceRef.namespace is not specified. +If the namespace is specified, then dataSourceRef will not be copied to dataSource. + +| `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. + +| `resources` +| `object` +| resources represents the minimum resources the volume should have. +If RecoverVolumeExpansionFailure feature is enabled users are allowed to specify resource requirements +that are lower than previous value but must still be higher than capacity recorded in the +status field of the claim. +More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources + +| `selector` +| `object` +| selector is a label query over volumes to consider for binding. + +| `storageClassName` +| `string` +| storageClassName is the name of the StorageClass required by the claim. +More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1 + +| `volumeAttributesClassName` +| `string` +| volumeAttributesClassName may be used to set the VolumeAttributesClass used by this claim. +If specified, the CSI driver will create or update the volume with the attributes defined +in the corresponding VolumeAttributesClass. This has a different purpose than storageClassName, +it can be changed after the claim is created. An empty string or nil value indicates that no +VolumeAttributesClass will be applied to the claim. If the claim enters an Infeasible error state, +this field can be reset to its previous value (including nil) to cancel the modification. +If the resource referred to by volumeAttributesClass does not exist, this PersistentVolumeClaim will be +set to a Pending state, as reflected by the modifyVolumeStatus field, until such as a resource +exists. +More info: https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/ + +| `volumeMode` +| `string` +| volumeMode defines what type of volume is required by the claim. +Value of Filesystem is implied when not included in claim spec. + +| `volumeName` +| `string` +| volumeName is the binding reference to the PersistentVolume backing this claim. + +|=== +=== .spec.alertmanagerConfig.customConfig.volumeClaimTemplate.spec.dataSource +Description:: ++ +-- +dataSource field can be used to specify either: +* An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot) +* An existing PVC (PersistentVolumeClaim) +If the provisioner or an external controller can support the specified data source, +it will create a new volume based on the contents of the specified data source. +When the AnyVolumeDataSource feature gate is enabled, dataSource contents will be copied to dataSourceRef, +and dataSourceRef contents will be copied to dataSource when dataSourceRef.namespace is not specified. +If the namespace is specified, then dataSourceRef will not be copied to dataSource. +-- + +Type:: + `object` + +Required:: + - `kind` + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiGroup` +| `string` +| APIGroup is the group for the resource being referenced. +If APIGroup is not specified, the specified Kind must be in the core API group. +For any other third-party types, APIGroup is required. + +| `kind` +| `string` +| Kind is the type of resource being referenced + +| `name` +| `string` +| Name is the name of resource being referenced + +|=== +=== .spec.alertmanagerConfig.customConfig.volumeClaimTemplate.spec.dataSourceRef +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. +-- + +Type:: + `object` + +Required:: + - `kind` + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiGroup` +| `string` +| APIGroup is the group for the resource being referenced. +If APIGroup is not specified, the specified Kind must be in the core API group. +For any other third-party types, APIGroup is required. + +| `kind` +| `string` +| Kind is the type of resource being referenced + +| `name` +| `string` +| Name is the name of resource being referenced + +| `namespace` +| `string` +| Namespace is the namespace of resource being referenced +Note that when a namespace is specified, a gateway.networking.k8s.io/ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. +(Alpha) This field requires the CrossNamespaceVolumeDataSource feature gate to be enabled. + +|=== +=== .spec.alertmanagerConfig.customConfig.volumeClaimTemplate.spec.resources +Description:: ++ +-- +resources represents the minimum resources the volume should have. +If RecoverVolumeExpansionFailure feature is enabled users are allowed to specify resource requirements +that are lower than previous value but must still be higher than capacity recorded in the +status field of the claim. +More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `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.alertmanagerConfig.customConfig.volumeClaimTemplate.spec.selector +Description:: ++ +-- +selector is a label query over volumes to consider for binding. +-- + +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.alertmanagerConfig.customConfig.volumeClaimTemplate.spec.selector.matchExpressions +Description:: ++ +-- +matchExpressions is a list of label selector requirements. The requirements are ANDed. +-- + +Type:: + `array` + + + + +=== .spec.alertmanagerConfig.customConfig.volumeClaimTemplate.spec.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.alertmanagerConfig.customConfig.volumeClaimTemplate.status +Description:: ++ +-- +status represents the current information/status of a persistent volume claim. +Read-only. +More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `accessModes` +| `array (string)` +| accessModes contains the actual access modes the volume backing the PVC has. +More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 + +| `allocatedResourceStatuses` +| `object (string)` +| allocatedResourceStatuses stores status of resource being resized for the given PVC. +Key names follow standard Kubernetes label syntax. Valid values are either: + * Un-prefixed keys: + - storage - the capacity of the volume. + * Custom resources must use implementation-defined prefixed names such as "example.com/my-custom-resource" +Apart from above values - keys that are unprefixed or have kubernetes.io prefix are considered +reserved and hence may not be used. + +ClaimResourceStatus can be in any of following states: + - ControllerResizeInProgress: + State set when resize controller starts resizing the volume in control-plane. + - ControllerResizeFailed: + State set when resize has failed in resize controller with a terminal error. + - NodeResizePending: + State set when resize controller has finished resizing the volume but further resizing of + volume is needed on the node. + - NodeResizeInProgress: + State set when kubelet starts resizing the volume. + - NodeResizeFailed: + State set when resizing has failed in kubelet with a terminal error. Transient errors don't set + NodeResizeFailed. +For example: if expanding a PVC for more capacity - this field can be one of the following states: + - pvc.status.allocatedResourceStatus['storage'] = "ControllerResizeInProgress" + - pvc.status.allocatedResourceStatus['storage'] = "ControllerResizeFailed" + - pvc.status.allocatedResourceStatus['storage'] = "NodeResizePending" + - pvc.status.allocatedResourceStatus['storage'] = "NodeResizeInProgress" + - pvc.status.allocatedResourceStatus['storage'] = "NodeResizeFailed" +When this field is not set, it means that no resize operation is in progress for the given PVC. + +A controller that receives PVC update with previously unknown resourceName or ClaimResourceStatus +should ignore the update for the purpose it was designed. For example - a controller that +only is responsible for resizing capacity of the volume, should ignore PVC updates that change other valid +resources associated with PVC. + +This is an alpha field and requires enabling RecoverVolumeExpansionFailure feature. + +| `allocatedResources` +| `integer-or-string` +| allocatedResources tracks the resources allocated to a PVC including its capacity. +Key names follow standard Kubernetes label syntax. Valid values are either: + * Un-prefixed keys: + - storage - the capacity of the volume. + * Custom resources must use implementation-defined prefixed names such as "example.com/my-custom-resource" +Apart from above values - keys that are unprefixed or have kubernetes.io prefix are considered +reserved and hence may not be used. + +Capacity reported here may be larger than the actual capacity when a volume expansion operation +is requested. +For storage quota, the larger value from allocatedResources and PVC.spec.resources is used. +If allocatedResources is not set, PVC.spec.resources alone is used for quota calculation. +If a volume expansion capacity request is lowered, allocatedResources is only +lowered if there are no expansion operations in progress and if the actual volume capacity +is equal or lower than the requested capacity. + +A controller that receives PVC update with previously unknown resourceName +should ignore the update for the purpose it was designed. For example - a controller that +only is responsible for resizing capacity of the volume, should ignore PVC updates that change other valid +resources associated with PVC. + +This is an alpha field and requires enabling RecoverVolumeExpansionFailure feature. + +| `capacity` +| `integer-or-string` +| capacity represents the actual resources of the underlying volume. + +| `conditions` +| `array` +| conditions is the current Condition of persistent volume claim. If underlying persistent volume is being +resized then the Condition will be set to 'Resizing'. + +| `conditions[]` +| `object` +| PersistentVolumeClaimCondition contains details about state of pvc + +| `currentVolumeAttributesClassName` +| `string` +| currentVolumeAttributesClassName is the current name of the VolumeAttributesClass the PVC is using. +When unset, there is no VolumeAttributeClass applied to this PersistentVolumeClaim + +| `modifyVolumeStatus` +| `object` +| ModifyVolumeStatus represents the status object of ControllerModifyVolume operation. +When this is unset, there is no ModifyVolume operation being attempted. + +| `phase` +| `string` +| phase represents the current phase of PersistentVolumeClaim. + +|=== +=== .spec.alertmanagerConfig.customConfig.volumeClaimTemplate.status.conditions +Description:: ++ +-- +conditions is the current Condition of persistent volume claim. If underlying persistent volume is being +resized then the Condition will be set to 'Resizing'. +-- + +Type:: + `array` + + + + +=== .spec.alertmanagerConfig.customConfig.volumeClaimTemplate.status.conditions[] +Description:: ++ +-- +PersistentVolumeClaimCondition contains details about state of pvc +-- + +Type:: + `object` + +Required:: + - `status` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `lastProbeTime` +| `string` +| lastProbeTime is the time we probed the condition. + +| `lastTransitionTime` +| `string` +| lastTransitionTime is the time the condition transitioned from one status to another. + +| `message` +| `string` +| message is the human-readable message indicating details about last transition. + +| `reason` +| `string` +| reason is a unique, this should be a short, machine understandable string that gives the reason +for condition's last transition. If it reports "Resizing" that means the underlying +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` +| 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.alertmanagerConfig.customConfig.volumeClaimTemplate.status.modifyVolumeStatus +Description:: ++ +-- +ModifyVolumeStatus represents the status object of ControllerModifyVolume operation. +When this is unset, there is no ModifyVolume operation being attempted. +-- + +Type:: + `object` + +Required:: + - `status` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `status` +| `string` +| status is the status of the ControllerModifyVolume operation. It can be in any of following states: + - Pending + Pending indicates that the PersistentVolumeClaim cannot be modified due to unmet requirements, such as + the specified VolumeAttributesClass not existing. + - InProgress + InProgress indicates that the volume is being modified. + - Infeasible + Infeasible indicates that the request has been rejected as invalid by the CSI driver. To + resolve the error, a valid VolumeAttributesClass needs to be specified. +Note: New statuses can be added in the future. Consumers should check for unknown statuses and fail appropriately. + +| `targetVolumeAttributesClassName` +| `string` +| targetVolumeAttributesClassName is the name of the VolumeAttributesClass the PVC currently being reconciled + +|=== +=== .spec.metricsServerConfig +Description:: ++ +-- +metricsServerConfig is an optional field that can be used to configure the Kubernetes Metrics Server that runs in the openshift-monitoring namespace. +Specifically, it can configure how the Metrics Server instance is deployed, pod scheduling, its audit policy and log verbosity. +When omitted, this means no opinion and the platform is left to choose a reasonable default, which is subject to change over time. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `audit` +| `object` +| audit defines the audit configuration used by the Metrics Server instance. +audit is optional. +When omitted, this means no opinion and the platform is left to choose a reasonable default, that is subject to change over time. +The current default sets audit.profile to Metadata + +| `nodeSelector` +| `object (string)` +| nodeSelector defines the nodes on which the Pods are scheduled +nodeSelector is optional. + +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +The current default value is `kubernetes.io/os: linux`. + +| `resources` +| `array` +| resources defines the compute resource requests and limits for the Metrics Server container. +This includes CPU, memory and HugePages constraints to help control scheduling and resource usage. +When not specified, defaults are used by the platform. Requests cannot exceed limits. +This field is optional. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +This is a simplified API that maps to Kubernetes ResourceRequirements. +The current default values are: + resources: + - name: cpu + request: 4m + limit: null + - name: memory + request: 40Mi + limit: null +Maximum length for this list is 10. +Minimum length for this list is 1. + +| `resources[]` +| `object` +| ContainerResource defines a single resource requirement for a container. + +| `tolerations` +| `array` +| tolerations defines tolerations for the pods. +tolerations is optional. + +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +Defaults are empty/unset. +Maximum length for this list is 10 +Minimum length for this list is 1 + +| `tolerations[]` +| `object` +| The pod this Toleration is attached to tolerates any taint that matches +the triple using the matching operator . + +| `topologySpreadConstraints` +| `array` +| topologySpreadConstraints defines rules for how Metrics Server Pods should be distributed +across topology domains such as zones, nodes, or other user-defined labels. +topologySpreadConstraints is optional. +This helps improve high availability and resource efficiency by avoiding placing +too many replicas in the same failure domain. + +When omitted, this means no opinion and the platform is left to choose a default, which is subject to change over time. +This field maps directly to the `topologySpreadConstraints` field in the Pod spec. +Default is empty list. +Maximum length for this list is 10. +Minimum length for this list is 1 +Entries must have unique topologyKey and whenUnsatisfiable pairs. + +| `topologySpreadConstraints[]` +| `object` +| TopologySpreadConstraint specifies how to spread matching pods among the given topology. + +| `verbosity` +| `string` +| verbosity defines the verbosity of log messages for Metrics Server. +Valid values are Errors, Info, Trace, TraceAll and omitted. +When set to Errors, only critical messages and errors are logged. +When set to Info, only basic information messages are logged. +When set to Trace, information useful for general debugging is logged. +When set to TraceAll, detailed information about metric scraping is logged. +When omitted, this means no opinion and the platform is left to choose a reasonable default, that is subject to change over time. +The current default value is `Errors` + +|=== +=== .spec.metricsServerConfig.audit +Description:: ++ +-- +audit defines the audit configuration used by the Metrics Server instance. +audit is optional. +When omitted, this means no opinion and the platform is left to choose a reasonable default, that is subject to change over time. +The current default sets audit.profile to Metadata +-- + +Type:: + `object` + +Required:: + - `profile` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `profile` +| `string` +| profile is a required field for configuring the audit log level of the Kubernetes Metrics Server. +Allowed values are None, Metadata, Request, or RequestResponse. +When set to None, audit logging is disabled and no audit events are recorded. +When set to Metadata, only request metadata (such as requesting user, timestamp, resource, verb, etc.) is logged, but not the request or response body. +When set to Request, event metadata and the request body are logged, but not the response body. +When set to RequestResponse, event metadata, request body, and response body are all logged, providing the most detailed audit information. + +See: https://kubernetes.io/docs/tasks/debug-application-cluster/audit/#audit-policy +for more information about auditing and log levels. + +|=== +=== .spec.metricsServerConfig.resources +Description:: ++ +-- +resources defines the compute resource requests and limits for the Metrics Server container. +This includes CPU, memory and HugePages constraints to help control scheduling and resource usage. +When not specified, defaults are used by the platform. Requests cannot exceed limits. +This field is optional. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +This is a simplified API that maps to Kubernetes ResourceRequirements. +The current default values are: + resources: + - name: cpu + request: 4m + limit: null + - name: memory + request: 40Mi + limit: null +Maximum length for this list is 10. +Minimum length for this list is 1. +-- + +Type:: + `array` + + + + +=== .spec.metricsServerConfig.resources[] +Description:: ++ +-- +ContainerResource defines a single resource requirement for a container. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `limit` +| `integer-or-string` +| limit is the maximum amount of the resource allowed (e.g. "2Mi", "1Gi"). +This field is optional. +When request is specified, limit cannot be less than request. +The value must be greater than 0 when specified. + +| `name` +| `string` +| name of the resource (e.g. "cpu", "memory", "hugepages-2Mi"). +This field is required. +name must consist only of alphanumeric characters, `-`, `_` and `.` and must start and end with an alphanumeric character. + +| `request` +| `integer-or-string` +| request is the minimum amount of the resource required (e.g. "2Mi", "1Gi"). +This field is optional. +When limit is specified, request cannot be greater than limit. + +|=== +=== .spec.metricsServerConfig.tolerations +Description:: ++ +-- +tolerations defines tolerations for the pods. +tolerations is optional. + +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +Defaults are empty/unset. +Maximum length for this list is 10 +Minimum length for this list is 1 +-- + +Type:: + `array` + + + + +=== .spec.metricsServerConfig.tolerations[] +Description:: ++ +-- +The pod this Toleration is attached to tolerates any taint that matches +the triple using the matching operator . +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `effect` +| `string` +| Effect indicates the taint effect to match. Empty means match all taint effects. +When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. + +| `key` +| `string` +| Key is the taint key that the toleration applies to. Empty means match all taint keys. +If the key is empty, operator must be Exists; this combination means to match all values and all keys. + +| `operator` +| `string` +| Operator represents a key's relationship to the value. +Valid operators are Exists and Equal. Defaults to Equal. +Exists is equivalent to wildcard for value, so that a pod can +tolerate all taints of a particular category. + +| `tolerationSeconds` +| `integer` +| TolerationSeconds represents the period of time the toleration (which must be +of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, +it is not set, which means tolerate the taint forever (do not evict). Zero and +negative values will be treated as 0 (evict immediately) by the system. + +| `value` +| `string` +| Value is the taint value the toleration matches to. +If the operator is Exists, the value should be empty, otherwise just a regular string. + +|=== +=== .spec.metricsServerConfig.topologySpreadConstraints +Description:: ++ +-- +topologySpreadConstraints defines rules for how Metrics Server Pods should be distributed +across topology domains such as zones, nodes, or other user-defined labels. +topologySpreadConstraints is optional. +This helps improve high availability and resource efficiency by avoiding placing +too many replicas in the same failure domain. + +When omitted, this means no opinion and the platform is left to choose a default, which is subject to change over time. +This field maps directly to the `topologySpreadConstraints` field in the Pod spec. +Default is empty list. +Maximum length for this list is 10. +Minimum length for this list is 1 +Entries must have unique topologyKey and whenUnsatisfiable pairs. +-- + +Type:: + `array` + + + + +=== .spec.metricsServerConfig.topologySpreadConstraints[] +Description:: ++ +-- +TopologySpreadConstraint specifies how to spread matching pods among the given topology. +-- + +Type:: + `object` + +Required:: + - `maxSkew` + - `topologyKey` + - `whenUnsatisfiable` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `labelSelector` +| `object` +| LabelSelector is used to find matching pods. +Pods that match this label selector are counted to determine the number of pods +in their corresponding topology domain. + +| `matchLabelKeys` +| `array (string)` +| MatchLabelKeys is a set of pod label keys to select the pods over which +spreading will be calculated. The keys are used to lookup values from the +incoming pod labels, those key-value labels are ANDed with labelSelector +to select the group of existing pods over which spreading will be calculated +for the incoming pod. The same key is forbidden to exist in both MatchLabelKeys and LabelSelector. +MatchLabelKeys cannot be set when LabelSelector isn't set. +Keys that don't exist in the incoming pod labels will +be ignored. A null or empty list means only match against labelSelector. + +This is a beta field and requires the MatchLabelKeysInPodTopologySpread feature gate to be enabled (enabled by default). + +| `maxSkew` +| `integer` +| MaxSkew describes the degree to which pods may be unevenly distributed. +When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference +between the number of matching pods in the target topology and the global minimum. +The global minimum is the minimum number of matching pods in an eligible domain +or zero if the number of eligible domains is less than MinDomains. +For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same +labelSelector spread as 2/2/1: +In this case, the global minimum is 1. +\| zone1 \| zone2 \| zone3 \| +\| P P \| P P \| P \| +- if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 2/2/2; +scheduling it onto zone1(zone2) would make the ActualSkew(3-1) on zone1(zone2) +violate MaxSkew(1). +- if MaxSkew is 2, incoming pod can be scheduled onto any zone. +When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence +to topologies that satisfy it. +It's a required field. Default value is 1 and 0 is not allowed. + +| `minDomains` +| `integer` +| MinDomains indicates a minimum number of eligible domains. +When the number of eligible domains with matching topology keys is less than minDomains, +Pod Topology Spread treats "global minimum" as 0, and then the calculation of Skew is performed. +And when the number of eligible domains with matching topology keys equals or greater than minDomains, +this value has no effect on scheduling. +As a result, when the number of eligible domains is less than minDomains, +scheduler won't schedule more than maxSkew Pods to those domains. +If value is nil, the constraint behaves as if MinDomains is equal to 1. +Valid values are integers greater than 0. +When value is not nil, WhenUnsatisfiable must be DoNotSchedule. + +For example, in a 3-zone cluster, MaxSkew is set to 2, MinDomains is set to 5 and pods with the same +labelSelector spread as 2/2/2: +\| zone1 \| zone2 \| zone3 \| +\| P P \| P P \| P P \| +The number of domains is less than 5(MinDomains), so "global minimum" is treated as 0. +In this situation, new pod with the same labelSelector cannot be scheduled, +because computed skew will be 3(3 - 0) if new Pod is scheduled to any of the three zones, +it will violate MaxSkew. + +| `nodeAffinityPolicy` +| `string` +| NodeAffinityPolicy indicates how we will treat Pod's nodeAffinity/nodeSelector +when calculating pod topology spread skew. Options are: +- Honor: only nodes matching nodeAffinity/nodeSelector are included in the calculations. +- Ignore: nodeAffinity/nodeSelector are ignored. All nodes are included in the calculations. + +If this value is nil, the behavior is equivalent to the Honor policy. + +| `nodeTaintsPolicy` +| `string` +| NodeTaintsPolicy indicates how we will treat node taints when calculating +pod topology spread skew. Options are: +- Honor: nodes without taints, along with tainted nodes for which the incoming pod +has a toleration, are included. +- Ignore: node taints are ignored. All nodes are included. + +If this value is nil, the behavior is equivalent to the Ignore policy. + +| `topologyKey` +| `string` +| TopologyKey is the key of node labels. Nodes that have a label with this key +and identical values are considered to be in the same topology. +We consider each as a "bucket", and try to put balanced number +of pods into each bucket. +We define a domain as a particular instance of a topology. +Also, we define an eligible domain as a domain whose nodes meet the requirements of +nodeAffinityPolicy and nodeTaintsPolicy. +e.g. If TopologyKey is "kubernetes.io/hostname", each Node is a domain of that topology. +And, if TopologyKey is "topology.kubernetes.io/zone", each zone is a domain of that topology. +It's a required field. + +| `whenUnsatisfiable` +| `string` +| WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy +the spread constraint. +- DoNotSchedule (default) tells the scheduler not to schedule it. +- ScheduleAnyway tells the scheduler to schedule the pod in any location, + but giving higher precedence to topologies that would help reduce the + skew. +A constraint is considered "Unsatisfiable" for an incoming pod +if and only if every possible node assignment for that pod would violate +"MaxSkew" on some topology. +For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same +labelSelector spread as 3/1/1: +\| zone1 \| zone2 \| zone3 \| +\| P P P \| P \| P \| +If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled +to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies +MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler +won't make it *more* imbalanced. +It's a required field. + +|=== +=== .spec.metricsServerConfig.topologySpreadConstraints[].labelSelector +Description:: ++ +-- +LabelSelector is used to find matching pods. +Pods that match this label selector are counted to determine the number of pods +in their corresponding topology domain. +-- + +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.metricsServerConfig.topologySpreadConstraints[].labelSelector.matchExpressions +Description:: ++ +-- +matchExpressions is a list of label selector requirements. The requirements are ANDed. +-- + +Type:: + `array` + + + + +=== .spec.metricsServerConfig.topologySpreadConstraints[].labelSelector.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.userDefined +Description:: ++ +-- +userDefined set the deployment mode for user-defined monitoring in addition to the default platform monitoring. +userDefined is optional. +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 value is `Disabled`. +-- + +Type:: + `object` + +Required:: + - `mode` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `mode` +| `string` +| mode defines the different configurations of UserDefinedMonitoring +Valid values are Disabled and NamespaceIsolated +Disabled disables monitoring for user-defined projects. This restricts the default monitoring stack, installed in the openshift-monitoring project, to monitor only platform namespaces, which prevents any custom monitoring configurations or resources from being applied to user-defined namespaces. +NamespaceIsolated enables monitoring for user-defined projects with namespace-scoped tenancy. This ensures that metrics, alerts, and monitoring data are isolated at the namespace level. +The current default value is `Disabled`. + +|=== +=== .status +Description:: ++ +-- +status holds observed values from the cluster. They may not be overridden. +-- + +Type:: + `object` + + + + + +== API endpoints + +The following API endpoints are available: + +* `/apis/config.openshift.io/v1alpha1/clustermonitorings` +- `DELETE`: delete collection of ClusterMonitoring +- `GET`: list objects of kind ClusterMonitoring +- `POST`: create a ClusterMonitoring +* `/apis/config.openshift.io/v1alpha1/clustermonitorings/{name}` +- `DELETE`: delete a ClusterMonitoring +- `GET`: read the specified ClusterMonitoring +- `PATCH`: partially update the specified ClusterMonitoring +- `PUT`: replace the specified ClusterMonitoring +* `/apis/config.openshift.io/v1alpha1/clustermonitorings/{name}/status` +- `GET`: read status of the specified ClusterMonitoring +- `PATCH`: partially update status of the specified ClusterMonitoring +- `PUT`: replace status of the specified ClusterMonitoring + + +=== /apis/config.openshift.io/v1alpha1/clustermonitorings + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of ClusterMonitoring + + + + +.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 ClusterMonitoring + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-config-v1alpha1-ClusterMonitoringList[`ClusterMonitoringList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a ClusterMonitoring + + +.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:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 201 - Created +| xref:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 202 - Accepted +| xref:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/config.openshift.io/v1alpha1/clustermonitorings/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ClusterMonitoring +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a ClusterMonitoring + + +.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 ClusterMonitoring + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified ClusterMonitoring + + +.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:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified ClusterMonitoring + + +.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:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 201 - Created +| xref:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/config.openshift.io/v1alpha1/clustermonitorings/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ClusterMonitoring +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified ClusterMonitoring + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified ClusterMonitoring + + +.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:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified ClusterMonitoring + + +.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:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 201 - Created +| xref:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`ClusterMonitoring`] schema +| 401 - Unauthorized +| Empty +|=== + + 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 d2f3adbd04..8fb72a1c7d 100644 --- a/rest_api/config_apis/clusterversion-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/clusterversion-config-openshift-io-v1.adoc @@ -128,6 +128,24 @@ the operator from creating or updating the object. | ComponentOverride allows overriding cluster version operator's behavior for a component. +| `signatureStores` +| `array` +| signatureStores contains the upstream URIs to verify release signatures and optional +reference to a config map by name containing the PEM-encoded CA bundle. + +By default, CVO will use existing signature stores if this property is empty. +The CVO will check the release signatures in the local ConfigMaps first. It will search for a valid signature +in these stores in parallel only when local ConfigMaps did not include a valid signature. +Validation will fail if none of the signature stores reply with valid signature before timeout. +Setting signatureStores will replace the default signature stores with custom signature stores. +Default stores can be used with custom signature stores by adding them manually. + +A maximum of 32 signature stores may be configured. + +| `signatureStores[]` +| `object` +| SignatureStore represents the URL of custom Signature Store + | `upstream` | `string` | upstream may be used to specify the preferred update server. By default @@ -307,6 +325,95 @@ scoped, the namespace should be empty. resources in this cluster. Default: false +|=== +=== .spec.signatureStores +Description:: ++ +-- +signatureStores contains the upstream URIs to verify release signatures and optional +reference to a config map by name containing the PEM-encoded CA bundle. + +By default, CVO will use existing signature stores if this property is empty. +The CVO will check the release signatures in the local ConfigMaps first. It will search for a valid signature +in these stores in parallel only when local ConfigMaps did not include a valid signature. +Validation will fail if none of the signature stores reply with valid signature before timeout. +Setting signatureStores will replace the default signature stores with custom signature stores. +Default stores can be used with custom signature stores by adding them manually. + +A maximum of 32 signature stores may be configured. +-- + +Type:: + `array` + + + + +=== .spec.signatureStores[] +Description:: ++ +-- +SignatureStore represents the URL of custom Signature Store +-- + +Type:: + `object` + +Required:: + - `url` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `ca` +| `object` +| ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. +It is used as a trust anchor to validate the TLS certificate presented by the remote server. +The key "ca.crt" is used to locate the data. +If specified and the config map or expected key is not found, the signature store is not honored. +If the specified ca data is not valid, the signature store is not honored. +If empty, we fall back to the CA configured via Proxy, which is appended to the default system roots. +The namespace for this config map is openshift-config. + +| `url` +| `string` +| url contains the upstream custom signature store URL. +url should be a valid absolute http/https URI of an upstream signature store as per rfc1738. +This must be provided and cannot be empty. + +|=== +=== .spec.signatureStores[].ca +Description:: ++ +-- +ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. +It is used as a trust anchor to validate the TLS certificate presented by the remote server. +The key "ca.crt" is used to locate the data. +If specified and the config map or expected key is not found, the signature store is not honored. +If the specified ca data is not valid, the signature store is not honored. +If empty, we fall back to the CA configured via Proxy, which is appended to the default system roots. +The namespace for this config map is openshift-config. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is the metadata.name of the referenced config map + |=== === .status Description:: @@ -592,6 +699,14 @@ Required:: |=== | Property | Type | Description +| `architecture` +| `string` +| architecture is an optional field that indicates the +value of the cluster architecture. In this context cluster +architecture means either a single architecture or a multi +architecture. +Valid values are 'Multi' and empty. + | `channels` | `array (string)` | channels is the set of Cincinnati channels to which the release @@ -856,6 +971,14 @@ Required:: |=== | Property | Type | Description +| `architecture` +| `string` +| architecture is an optional field that indicates the +value of the cluster architecture. In this context cluster +architecture means either a single architecture or a multi +architecture. +Valid values are 'Multi' and empty. + | `channels` | `array (string)` | channels is the set of Cincinnati channels to which the release diff --git a/rest_api/config_apis/config-apis-index.adoc b/rest_api/config_apis/config-apis-index.adoc index 89f0f5b9e0..f4392bc62e 100644 --- a/rest_api/config_apis/config-apis-index.adoc +++ b/rest_api/config_apis/config-apis-index.adoc @@ -33,6 +33,19 @@ webhook token authenticators). The canonical name of an instance is `cluster`. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- +Type:: + `object` + +== Backup [config.openshift.io/v1alpha1] + +Description:: ++ +-- +Backup provides configuration for performing backups of the openshift cluster. + +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` @@ -76,6 +89,20 @@ operators to convey their state to the rest of the cluster. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- +Type:: + `object` + +== ClusterMonitoring [config.openshift.io/v1alpha1] + +Description:: ++ +-- +ClusterMonitoring is the Custom Resource object which holds the current status of Cluster Monitoring Operator. CMO is a central component of the monitoring stack. + +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. +ClusterMonitoring is the Schema for the Cluster Monitoring Operators API +-- + Type:: `object` @@ -217,6 +244,19 @@ When multiple policies are defined, the outcome of the behavior is defined on ea Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- +Type:: + `object` + +== InsightsDataGather [config.openshift.io/v1alpha2] + +Description:: ++ +-- +InsightsDataGather provides data gather configuration options for the the Insights Operator. + +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` diff --git a/rest_api/config_apis/image-config-openshift-io-v1.adoc b/rest_api/config_apis/image-config-openshift-io-v1.adoc index e9d8544a95..9435f580b8 100644 --- a/rest_api/config_apis/image-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/image-config-openshift-io-v1.adoc @@ -100,6 +100,20 @@ registry. The external hostname should be set only when the image registry is exposed externally. The first value is used in 'publicDockerImageRepository' field in ImageStreams. The value must be in "hostname[:port]" format. +| `imageStreamImportMode` +| `string` +| imageStreamImportMode controls the import mode behaviour of imagestreams. +It can be set to `Legacy` or `PreserveOriginal` or the empty string. If this value +is specified, this setting is applied to all newly created imagestreams which do not have the +value set. `Legacy` indicates that the legacy behaviour should be used. +For manifest lists, the legacy behaviour will discard the manifest list and import a single +sub-manifest. In this case, the platform is chosen in the following order of priority: +1. tag annotations; 2. control plane arch/os; 3. linux/amd64; 4. the first manifest in the list. +`PreserveOriginal` indicates that the original manifest will be preserved. For manifest lists, +the manifest list and all its sub-manifests will be imported. When empty, the behaviour will be +decided based on the payload type advertised by the ClusterVersion status, i.e single arch payload +implies the import mode is Legacy and multi payload implies PreserveOriginal. + | `registrySources` | `object` | registrySources contains configuration that determines how the container runtime @@ -250,6 +264,19 @@ registry. The external hostname should be set only when the image registry is exposed externally. The first value is used in 'publicDockerImageRepository' field in ImageStreams. The value must be in "hostname[:port]" format. +| `imageStreamImportMode` +| `string` +| imageStreamImportMode controls the import mode behaviour of imagestreams. It can be +`Legacy` or `PreserveOriginal`. `Legacy` indicates that the legacy behaviour should be used. +For manifest lists, the legacy behaviour will discard the manifest list and import a single +sub-manifest. In this case, the platform is chosen in the following order of priority: +1. tag annotations; 2. control plane arch/os; 3. linux/amd64; 4. the first manifest in the list. +`PreserveOriginal` indicates that the original manifest will be preserved. For manifest lists, +the manifest list and all its sub-manifests will be imported. This value will be reconciled based +on either the spec value or if no spec value is specified, the image registry operator would look +at the ClusterVersion status to determine the payload type and set the import mode accordingly, +i.e single arch payload implies the import mode is Legacy and multi payload implies PreserveOriginal. + | `internalRegistryHostname` | `string` | internalRegistryHostname sets the hostname for the default internal image diff --git a/rest_api/config_apis/imagepolicy-config-openshift-io-v1.adoc b/rest_api/config_apis/imagepolicy-config-openshift-io-v1.adoc index 398f177662..787b9c7d49 100644 --- a/rest_api/config_apis/imagepolicy-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/imagepolicy-config-openshift-io-v1.adoc @@ -148,13 +148,18 @@ fulcioCAWithRekor is required when policyType is FulcioCAWithRekor, and forbidde For more information about Fulcio and Rekor, please refer to the document at: https://github.com/sigstore/fulcio and https://github.com/sigstore/rekor +| `pki` +| `object` +| pki defines the root of trust configuration based on Bring Your Own Public Key Infrastructure (BYOPKI) Root CA(s) and corresponding intermediate certificates. +pki is required when policyType is PKI, and forbidden otherwise. + | `policyType` | `string` | policyType is a required field specifies the type of the policy for verification. This field must correspond to how the policy was generated. Allowed values are "PublicKey", "FulcioCAWithRekor", and "PKI". When set to "PublicKey", the policy relies on a sigstore publicKey and may optionally use a Rekor verification. When set to "FulcioCAWithRekor", the policy is based on the Fulcio certification and incorporates a Rekor verification. -When set to "PKI", the policy is based on the certificates from Bring Your Own Public Key Infrastructure (BYOPKI). This value is enabled by turning on the SigstoreImageVerificationPKI feature gate. +When set to "PKI", the policy is based on the certificates from Bring Your Own Public Key Infrastructure (BYOPKI). | `publicKey` | `object` @@ -234,6 +239,70 @@ Example: "https://expected.OIDC.issuer/" The signedEmail must be a valid email address and at most 320 characters in length. Example: "expected-signing-user@example.com" +|=== +=== .spec.policy.rootOfTrust.pki +Description:: ++ +-- +pki defines the root of trust configuration based on Bring Your Own Public Key Infrastructure (BYOPKI) Root CA(s) and corresponding intermediate certificates. +pki is required when policyType is PKI, and forbidden otherwise. +-- + +Type:: + `object` + +Required:: + - `caRootsData` + - `pkiCertificateSubject` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `caIntermediatesData` +| `string` +| caIntermediatesData contains base64-encoded data of a certificate bundle PEM file, which contains one or more intermediate certificates in the PEM format. The total length of the data must not exceed 8192 characters. +caIntermediatesData requires caRootsData to be set. + +| `caRootsData` +| `string` +| caRootsData contains base64-encoded data of a certificate bundle PEM file, which contains one or more CA roots in the PEM format. The total length of the data must not exceed 8192 characters. + +| `pkiCertificateSubject` +| `object` +| pkiCertificateSubject defines the requirements imposed on the subject to which the certificate was issued. + +|=== +=== .spec.policy.rootOfTrust.pki.pkiCertificateSubject +Description:: ++ +-- +pkiCertificateSubject defines the requirements imposed on the subject to which the certificate was issued. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `email` +| `string` +| email specifies the expected email address imposed on the subject to which the certificate was issued, and must match the email address listed in the Subject Alternative Name (SAN) field of the certificate. +The email must be a valid email address and at most 320 characters in length. + +| `hostname` +| `string` +| hostname specifies the expected hostname imposed on the subject to which the certificate was issued, and it must match the hostname listed in the Subject Alternative Name (SAN) DNS field of the certificate. +The hostname must be a valid dns 1123 subdomain name, optionally prefixed by '*.', and at most 253 characters in length. +It must consist only of lowercase alphanumeric characters, hyphens, periods and the optional preceding asterisk. + |=== === .spec.policy.rootOfTrust.publicKey Description:: 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 5b93d5abbd..edf635a827 100644 --- a/rest_api/config_apis/infrastructure-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/infrastructure-config-openshift-io-v1.adoc @@ -423,6 +423,83 @@ Type:: +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `serviceEndpoints` +| `array` +| serviceEndpoints is a list of custom endpoints which will override the default +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 +overridden. 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. +A maximum of 13 service endpoints overrides are supported. + +| `serviceEndpoints[]` +| `object` +| IBMCloudServiceEndpoint stores the configuration of a custom url to +override existing defaults of IBM Cloud Services. + +|=== +=== .spec.platformSpec.ibmcloud.serviceEndpoints +Description:: ++ +-- +serviceEndpoints is a list of custom endpoints which will override the default +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 +overridden. 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. +A maximum of 13 service endpoints overrides are supported. +-- + +Type:: + `array` + + + + +=== .spec.platformSpec.ibmcloud.serviceEndpoints[] +Description:: ++ +-- +IBMCloudServiceEndpoint stores the configuration of a custom url to +override existing defaults of IBM Cloud Services. +-- + +Type:: + `object` + +Required:: + - `name` + - `url` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is the name of the IBM Cloud service. +Possible values are: CIS, COS, COSConfig, DNSServices, GlobalCatalog, GlobalSearch, GlobalTagging, HyperProtect, IAM, KeyProtect, ResourceController, ResourceManager, or VPC. +For example, the IBM Cloud Private IAM service could be configured with the +service `name` of `IAM` and `url` of `https://private.iam.cloud.ibm.com` +Whereas the IBM Cloud Private VPC service for US South (Dallas) could be configured +with the service `name` of `VPC` and `url` of `https://us.south.private.iaas.cloud.ibm.com` + +| `url` +| `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. The path must follow the pattern +/v[0,9]+ or /api/v[0,9]+ + +|=== === .spec.platformSpec.kubevirt Description:: + @@ -1655,6 +1732,22 @@ Type:: |=== | Property | Type | Description +| `cloudLoadBalancerConfig` +| `` +| cloudLoadBalancerConfig holds configuration related to DNS and cloud +load balancers. It allows configuration of in-cluster DNS as an alternative +to the platform default DNS implementation. +When using the ClusterHosted DNS type, Load Balancer IP addresses +must be provided for the API and internal API load balancers as well as the +ingress load balancer. + +| `ipFamily` +| `string` +| ipFamily specifies the IP protocol family that should be used for AWS +network resources. This controls whether AWS resources are created with +IPv4-only, or dual-stack networking with IPv4 or IPv6 as the primary +protocol family. + | `region` | `string` | region holds the default AWS region for new AWS resources created by the cluster. @@ -1800,12 +1893,28 @@ Type:: | `string` | armEndpoint specifies a URL to use for resource management in non-soverign clouds such as Azure Stack. +| `cloudLoadBalancerConfig` +| `object` +| cloudLoadBalancerConfig holds configuration related to DNS and cloud +load balancers. It allows configuration of in-cluster DNS as an alternative +to the platform default DNS implementation. +When using the ClusterHosted DNS type, Load Balancer IP addresses +must be provided for the API and internal API load balancers as well as the +ingress load balancer. + | `cloudName` | `string` | cloudName is the name of the Azure cloud environment which can be used to configure the Azure SDK with the appropriate Azure API endpoints. If empty, the value is equal to `AzurePublicCloud`. +| `ipFamily` +| `string` +| ipFamily specifies the IP protocol family that should be used for Azure +network resources. This controls whether Azure resources are created with +IPv4-only, or dual-stack networking with IPv4 or IPv6 as the primary +protocol family. + | `networkResourceGroupName` | `string` | networkResourceGroupName is the Resource Group for network resources like the Virtual Network and Subnets used by the cluster. @@ -1826,6 +1935,92 @@ may be applied. OpenShift reserves 5 tags for internal use, allowing 10 tags for | `object` | AzureResourceTag is a tag to apply to Azure resources created for the cluster. +|=== +=== .status.platformStatus.azure.cloudLoadBalancerConfig +Description:: ++ +-- +cloudLoadBalancerConfig holds configuration related to DNS and cloud +load balancers. It allows configuration of in-cluster DNS as an alternative +to the platform default DNS implementation. +When using the ClusterHosted DNS type, Load Balancer IP addresses +must be provided for the API and internal API load balancers as well as the +ingress load balancer. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `clusterHosted` +| `object` +| clusterHosted holds the IP addresses of API, API-Int and Ingress Load +Balancers on Cloud Platforms. The DNS solution hosted within the cluster +use these IP addresses to provide resolution for API, API-Int and Ingress +services. + +| `dnsType` +| `string` +| dnsType indicates the type of DNS solution in use within the cluster. Its default value of +`PlatformDefault` indicates that the cluster's DNS is the default provided by the cloud platform. +It can be set to `ClusterHosted` to bypass the configuration of the cloud default DNS. In this mode, +the cluster needs to provide a self-hosted DNS solution for the cluster's installation to succeed. +The cluster's use of the cloud's Load Balancers is unaffected by this setting. +The value is immutable after it has been set at install time. +Currently, there is no way for the customer to add additional DNS entries into the cluster hosted DNS. +Enabling this functionality allows the user to start their own DNS solution outside the cluster after +installation is complete. The customer would be responsible for configuring this custom DNS solution, +and it can be run in addition to the in-cluster DNS solution. + +|=== +=== .status.platformStatus.azure.cloudLoadBalancerConfig.clusterHosted +Description:: ++ +-- +clusterHosted holds the IP addresses of API, API-Int and Ingress Load +Balancers on Cloud Platforms. The DNS solution hosted within the cluster +use these IP addresses to provide resolution for API, API-Int and Ingress +services. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiIntLoadBalancerIPs` +| `array (string)` +| apiIntLoadBalancerIPs holds Load Balancer IPs for the internal API service. +These Load Balancer IP addresses can be IPv4 and/or IPv6 addresses. +Entries in the apiIntLoadBalancerIPs must be unique. +A maximum of 16 IP addresses are permitted. + +| `apiLoadBalancerIPs` +| `array (string)` +| apiLoadBalancerIPs holds Load Balancer IPs for the API service. +These Load Balancer IP addresses can be IPv4 and/or IPv6 addresses. +Could be empty for private clusters. +Entries in the apiLoadBalancerIPs must be unique. +A maximum of 16 IP addresses are permitted. + +| `ingressLoadBalancerIPs` +| `array (string)` +| ingressLoadBalancerIPs holds IPs for Ingress Load Balancers. +These Load Balancer IP addresses can be IPv4 and/or IPv6 addresses. +Entries in the ingressLoadBalancerIPs must be unique. +A maximum of 16 IP addresses are permitted. + |=== === .status.platformStatus.azure.resourceTags Description:: @@ -1909,6 +2104,21 @@ using the infrastructure rather than Kubernetes networking. These are the IPs for a self-hosted load balancer in front of the API servers. In dual stack clusters this list contains two IPs otherwise only one. +| `dnsRecordsType` +| `string` +| dnsRecordsType determines whether records for api, api-int, and ingress +are provided by the internal DNS service or externally. +Allowed values are `Internal`, `External`, and omitted. +When set to `Internal`, records are provided by the internal infrastructure and +no additional user configuration is required for the cluster to function. +When set to `External`, records are not provided by the internal infrastructure +and must be configured by the user on a DNS server outside the cluster. +Cluster nodes must use this external server for their upstream DNS requests. +This value may only be set when loadBalancer.type is set to UserManaged. +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +The current default is `Internal`. + | `ingressIP` | `string` | ingressIP is an external IP which routes to the default ingress controller. @@ -2395,6 +2605,21 @@ using the infrastructure rather than Kubernetes networking. These are the IPs for a self-hosted load balancer in front of the API servers. In dual stack clusters this list contains two IPs otherwise only one. +| `dnsRecordsType` +| `string` +| dnsRecordsType determines whether records for api, api-int, and ingress +are provided by the internal DNS service or externally. +Allowed values are `Internal`, `External`, and omitted. +When set to `Internal`, records are provided by the internal infrastructure and +no additional user configuration is required for the cluster to function. +When set to `External`, records are not provided by the internal infrastructure +and must be configured by the user on a DNS server outside the cluster. +Cluster nodes must use this external server for their upstream DNS requests. +This value may only be set when loadBalancer.type is set to UserManaged. +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +The current default is `Internal`. + | `ingressIP` | `string` | ingressIP is an external IP which routes to the default ingress controller. @@ -2483,6 +2708,21 @@ stack clusters this list contains two IPs otherwise only one. | cloudName is the name of the desired OpenStack cloud in the client configuration file (`clouds.yaml`). +| `dnsRecordsType` +| `string` +| dnsRecordsType determines whether records for api, api-int, and ingress +are provided by the internal DNS service or externally. +Allowed values are `Internal`, `External`, and omitted. +When set to `Internal`, records are provided by the internal infrastructure and +no additional user configuration is required for the cluster to function. +When set to `External`, records are not provided by the internal infrastructure +and must be configured by the user on a DNS server outside the cluster. +Cluster nodes must use this external server for their upstream DNS requests. +This value may only be set when loadBalancer.type is set to UserManaged. +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +The current default is `Internal`. + | `ingressIP` | `string` | ingressIP is an external IP which routes to the default ingress controller. @@ -2579,6 +2819,21 @@ using the infrastructure rather than Kubernetes networking. These are the IPs for a self-hosted load balancer in front of the API servers. In dual stack clusters this list contains two IPs otherwise only one. +| `dnsRecordsType` +| `string` +| dnsRecordsType determines whether records for api, api-int, and ingress +are provided by the internal DNS service or externally. +Allowed values are `Internal`, `External`, and omitted. +When set to `Internal`, records are provided by the internal infrastructure and +no additional user configuration is required for the cluster to function. +When set to `External`, records are not provided by the internal infrastructure +and must be configured by the user on a DNS server outside the cluster. +Cluster nodes must use this external server for their upstream DNS requests. +This value may only be set when loadBalancer.type is set to UserManaged. +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +The current default is `Internal`. + | `ingressIP` | `string` | ingressIP is an external IP which routes to the default ingress controller. @@ -2771,6 +3026,21 @@ using the infrastructure rather than Kubernetes networking. These are the IPs for a self-hosted load balancer in front of the API servers. In dual stack clusters this list contains two IPs otherwise only one. +| `dnsRecordsType` +| `string` +| dnsRecordsType determines whether records for api, api-int, and ingress +are provided by the internal DNS service or externally. +Allowed values are `Internal`, `External`, and omitted. +When set to `Internal`, records are provided by the internal infrastructure and +no additional user configuration is required for the cluster to function. +When set to `External`, records are not provided by the internal infrastructure +and must be configured by the user on a DNS server outside the cluster. +Cluster nodes must use this external server for their upstream DNS requests. +This value may only be set when loadBalancer.type is set to UserManaged. +When omitted, this means the user has no opinion and the platform is left +to choose reasonable defaults. These defaults are subject to change over time. +The current default is `Internal`. + | `ingressIP` | `string` | ingressIP is an external IP which routes to the default ingress controller. diff --git a/rest_api/config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc b/rest_api/config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc new file mode 100644 index 0000000000..2785252dc3 --- /dev/null +++ b/rest_api/config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc @@ -0,0 +1,681 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="insightsdatagather-config-openshift-io-v1alpha2"] += InsightsDataGather [config.openshift.io/v1alpha2] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +InsightsDataGather provides data gather configuration options for the the Insights Operator. + +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` + +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 holds user settable values for configuration + +| `status` +| `object` +| status holds observed values from the cluster. They may not be overridden. + +|=== +=== .spec +Description:: ++ +-- +spec holds user settable values for configuration +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `gatherConfig` +| `object` +| gatherConfig is an optional spec attribute that includes all the configuration options related to gathering of the Insights data and its uploading to the ingress. + +|=== +=== .spec.gatherConfig +Description:: ++ +-- +gatherConfig is an optional spec attribute that includes all the configuration options related to gathering of the Insights data and its uploading to the ingress. +-- + +Type:: + `object` + +Required:: + - `gatherers` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `dataPolicy` +| `array (string)` +| dataPolicy is an optional list of DataPolicyOptions that allows user to enable additional obfuscation of the Insights archive data. +It may not exceed 2 items and must not contain duplicates. +Valid values are ObfuscateNetworking and WorkloadNames. +When set to ObfuscateNetworking the IP addresses and the cluster domain name are obfuscated. +When set to WorkloadNames, the gathered data about cluster resources will not contain the workload names for your deployments. Resources UIDs will be used instead. +When omitted no obfuscation is applied. + +| `gatherers` +| `object` +| gatherers is a required field that specifies the configuration of the gatherers. + +| `storage` +| `object` +| storage is an optional field that allows user to define persistent storage for gathering jobs to store the Insights data archive. +If omitted, the gathering job will use ephemeral storage. + +|=== +=== .spec.gatherConfig.gatherers +Description:: ++ +-- +gatherers is a required field that specifies the configuration of the gatherers. +-- + +Type:: + `object` + +Required:: + - `mode` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `custom` +| `object` +| custom provides gathering configuration. +It is required when mode is Custom, and forbidden otherwise. +Custom configuration allows user to disable only a subset of gatherers. +Gatherers that are not explicitly disabled in custom configuration will run. + +| `mode` +| `string` +| mode is a required field that specifies the mode for gatherers. Allowed values are All, None, and Custom. +When set to All, all gatherers wil run and gather data. +When set to None, all gatherers will be disabled and no data will be gathered. +When set to Custom, the custom configuration from the custom field will be applied. + +|=== +=== .spec.gatherConfig.gatherers.custom +Description:: ++ +-- +custom provides gathering configuration. +It is required when mode is Custom, and forbidden otherwise. +Custom configuration allows user to disable only a subset of gatherers. +Gatherers that are not explicitly disabled in custom configuration will run. +-- + +Type:: + `object` + +Required:: + - `configs` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `configs` +| `array` +| configs is a required list of gatherers configurations that can be used to enable or disable specific gatherers. +It may not exceed 100 items and each gatherer can be present only once. +It is possible to disable an entire set of gatherers while allowing a specific function within that set. +The particular gatherers IDs can be found at https://github.com/openshift/insights-operator/blob/master/docs/gathered-data.md. +Run the following command to get the names of last active gatherers: +"oc get insightsoperators.operator.openshift.io cluster -o json \| jq '.status.gatherStatus.gatherers[].name'" + +| `configs[]` +| `object` +| gathererConfig allows to configure specific gatherers + +|=== +=== .spec.gatherConfig.gatherers.custom.configs +Description:: ++ +-- +configs is a required list of gatherers configurations that can be used to enable or disable specific gatherers. +It may not exceed 100 items and each gatherer can be present only once. +It is possible to disable an entire set of gatherers while allowing a specific function within that set. +The particular gatherers IDs can be found at https://github.com/openshift/insights-operator/blob/master/docs/gathered-data.md. +Run the following command to get the names of last active gatherers: +"oc get insightsoperators.operator.openshift.io cluster -o json \| jq '.status.gatherStatus.gatherers[].name'" +-- + +Type:: + `array` + + + + +=== .spec.gatherConfig.gatherers.custom.configs[] +Description:: ++ +-- +gathererConfig allows to configure specific gatherers +-- + +Type:: + `object` + +Required:: + - `name` + - `state` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is the required name of a specific gatherer +It may not exceed 256 characters. +The format for a gatherer name is: {gatherer}/{function} where the function is optional. +Gatherer consists of a lowercase letters only that may include underscores (_). +Function consists of a lowercase letters only that may include underscores (_) and is separated from the gatherer by a forward slash (/). +The particular gatherers can be found at https://github.com/openshift/insights-operator/blob/master/docs/gathered-data.md. +Run the following command to get the names of last active gatherers: +"oc get insightsoperators.operator.openshift.io cluster -o json \| jq '.status.gatherStatus.gatherers[].name'" + +| `state` +| `string` +| state is a required field that allows you to configure specific gatherer. Valid values are "Enabled" and "Disabled". +When set to Enabled the gatherer will run. +When set to Disabled the gatherer will not run. + +|=== +=== .spec.gatherConfig.storage +Description:: ++ +-- +storage is an optional field that allows user to define persistent storage for gathering jobs to store the Insights data archive. +If omitted, the gathering job will use ephemeral storage. +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `persistentVolume` +| `object` +| persistentVolume is an optional field that specifies the PersistentVolume that will be used to store the Insights data archive. +The PersistentVolume must be created in the openshift-insights namespace. + +| `type` +| `string` +| type is a required field that specifies the type of storage that will be used to store the Insights data archive. +Valid values are "PersistentVolume" and "Ephemeral". +When set to Ephemeral, the Insights data archive is stored in the ephemeral storage of the gathering job. +When set to PersistentVolume, the Insights data archive is stored in the PersistentVolume that is defined by the persistentVolume field. + +|=== +=== .spec.gatherConfig.storage.persistentVolume +Description:: ++ +-- +persistentVolume is an optional field that specifies the PersistentVolume that will be used to store the Insights data archive. +The PersistentVolume must be created in the openshift-insights namespace. +-- + +Type:: + `object` + +Required:: + - `claim` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `claim` +| `object` +| claim is a required field that specifies the configuration of the PersistentVolumeClaim that will be used to store the Insights data archive. +The PersistentVolumeClaim must be created in the openshift-insights namespace. + +| `mountPath` +| `string` +| mountPath is an optional field specifying the directory where the PVC will be mounted inside the Insights data gathering Pod. +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 mount path is /var/lib/insights-operator +The path may not exceed 1024 characters and must not contain a colon. + +|=== +=== .spec.gatherConfig.storage.persistentVolume.claim +Description:: ++ +-- +claim is a required field that specifies the configuration of the PersistentVolumeClaim that will be used to store the Insights data archive. +The PersistentVolumeClaim must be created in the openshift-insights namespace. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is a string that follows the DNS1123 subdomain format. +It must be at most 253 characters in length, and must consist only of lower case alphanumeric characters, '-' and '.', and must start and end with an alphanumeric character. + +|=== +=== .status +Description:: ++ +-- +status holds observed values from the cluster. They may not be overridden. +-- + +Type:: + `object` + + + + + +== API endpoints + +The following API endpoints are available: + +* `/apis/config.openshift.io/v1alpha2/insightsdatagathers` +- `DELETE`: delete collection of InsightsDataGather +- `GET`: list objects of kind InsightsDataGather +- `POST`: create an InsightsDataGather +* `/apis/config.openshift.io/v1alpha2/insightsdatagathers/{name}` +- `DELETE`: delete an InsightsDataGather +- `GET`: read the specified InsightsDataGather +- `PATCH`: partially update the specified InsightsDataGather +- `PUT`: replace the specified InsightsDataGather +* `/apis/config.openshift.io/v1alpha2/insightsdatagathers/{name}/status` +- `GET`: read status of the specified InsightsDataGather +- `PATCH`: partially update status of the specified InsightsDataGather +- `PUT`: replace status of the specified InsightsDataGather + + +=== /apis/config.openshift.io/v1alpha2/insightsdatagathers + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of InsightsDataGather + + + + +.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 InsightsDataGather + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-config-v1alpha2-InsightsDataGatherList[`InsightsDataGatherList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create an InsightsDataGather + + +.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:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 201 - Created +| xref:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 202 - Accepted +| xref:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/config.openshift.io/v1alpha2/insightsdatagathers/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the InsightsDataGather +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete an InsightsDataGather + + +.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 InsightsDataGather + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified InsightsDataGather + + +.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:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified InsightsDataGather + + +.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:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 201 - Created +| xref:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/config.openshift.io/v1alpha2/insightsdatagathers/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the InsightsDataGather +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified InsightsDataGather + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified InsightsDataGather + + +.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:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified InsightsDataGather + + +.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:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 201 - Created +| xref:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`InsightsDataGather`] schema +| 401 - Unauthorized +| Empty +|=== + + 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 a5026955a3..7e1121a1a5 100644 --- a/rest_api/config_apis/node-config-openshift-io-v1.adoc +++ b/rest_api/config_apis/node-config-openshift-io-v1.adoc @@ -71,6 +71,22 @@ Type:: | `string` | cgroupMode determines the cgroups version on the node +| `minimumKubeletVersion` +| `string` +| minimumKubeletVersion is the lowest version of a kubelet that can join the cluster. +Specifically, the apiserver will deny most authorization requests of kubelets that are older +than the specified version, only allowing the kubelet to get and update its node object, and perform +subjectaccessreviews. +This means any kubelet that attempts to join the cluster will not be able to run any assigned workloads, +and will eventually be marked as not ready. +Its max length is 8, so maximum version allowed is either "9.999.99" or "99.99.99". +Since the kubelet reports the version of the kubernetes release, not Openshift, this field references +the underlying kubernetes version this version of Openshift is based off of. +In other words: if an admin wishes to ensure no nodes run an older version than Openshift 4.17, then +they should set the minimumKubeletVersion to 1.30.0. +When comparing versions, the kubelet's version is stripped of any contents outside of major.minor.patch version. +Thus, a kubelet with version "1.0.0-ec.0" will be compatible with minimumKubeletVersion "1.0.0" or earlier. + | `workerLatencyProfile` | `string` | workerLatencyProfile determins the how fast the kubelet is updating 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 31407e5bb6..d67209f5ea 100644 --- a/rest_api/console_apis/consolelink-console-openshift-io-v1.adoc +++ b/rest_api/console_apis/consolelink-console-openshift-io-v1.adoc @@ -74,7 +74,7 @@ application menu, and it is applicable only when location is set to ApplicationM | `href` | `string` -| href is the absolute secure URL for the link (must use https) +| href is the absolute URL for the link. Must use https:// for web URLs or mailto: for email links. | `location` | `string` diff --git a/rest_api/console_apis/consolenotification-console-openshift-io-v1.adoc b/rest_api/console_apis/consolenotification-console-openshift-io-v1.adoc index 5cce9acd88..f117173143 100644 --- a/rest_api/console_apis/consolenotification-console-openshift-io-v1.adoc +++ b/rest_api/console_apis/consolenotification-console-openshift-io-v1.adoc @@ -109,7 +109,7 @@ Required:: | `href` | `string` -| href is the absolute secure URL for the link (must use https) +| href is the absolute URL for the link. Must use https:// for web URLs or mailto: for email links. | `text` | `string` diff --git a/rest_api/console_apis/consolequickstart-console-openshift-io-v1.adoc b/rest_api/console_apis/consolequickstart-console-openshift-io-v1.adoc index 6a20099186..f27c022b35 100644 --- a/rest_api/console_apis/consolequickstart-console-openshift-io-v1.adoc +++ b/rest_api/console_apis/consolequickstart-console-openshift-io-v1.adoc @@ -162,9 +162,6 @@ Type:: | `object` | fieldSelector describes the limitation on access based on field. It can only limit access, not broaden it. -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). - | `group` | `string` | Group is the API Group of the Resource. "*" means all. @@ -173,9 +170,6 @@ This field is alpha-level. To use this field, you must enable the | `object` | labelSelector describes the limitation on access based on labels. It can only limit access, not broaden it. -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). - | `name` | `string` | Name is the name of the resource being requested for a "get" or deleted for a "delete". "" (empty) means all. @@ -209,9 +203,6 @@ Description:: + -- fieldSelector describes the limitation on access based on field. It can only limit access, not broaden it. - -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). -- Type:: @@ -304,9 +295,6 @@ Description:: + -- labelSelector describes the limitation on access based on labels. It can only limit access, not broaden it. - -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). -- 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 df31a43a82..a22e60651c 100644 --- a/rest_api/machine_apis/controlplanemachineset-machine-openshift-io-v1.adoc +++ b/rest_api/machine_apis/controlplanemachineset-machine-openshift-io-v1.adoc @@ -830,6 +830,16 @@ Type:: |=== | Property | Type | Description +| `authoritativeAPI` +| `string` +| authoritativeAPI is the API that is authoritative for this resource. +Valid values are MachineAPI and ClusterAPI. +When set to MachineAPI, writes to the spec of the machine.openshift.io copy of this resource will be reflected into the cluster.x-k8s.io copy. +When set to ClusterAPI, writes to the spec of the cluster.x-k8s.io copy of this resource will be reflected into the machine.openshift.io copy. +Updates to the status will be reflected in both copies of the resource, based on the controller implementing the functionality of the API. +Currently the authoritative API determines which controller will manage the resource, this will change in a future release. +To ensure the change has been accepted, please verify that the `status.authoritativeAPI` field has been updated to the desired value and that the `Synchronized` condition is present and set to `True`. + | `lifecycleHooks` | `object` | lifecycleHooks allow users to pause operations on the machine at diff --git a/rest_api/machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc b/rest_api/machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc new file mode 100644 index 0000000000..afc6731bc7 --- /dev/null +++ b/rest_api/machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc @@ -0,0 +1,729 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="internalreleaseimage-machineconfiguration-openshift-io-v1alpha1"] += InternalReleaseImage [machineconfiguration.openshift.io/v1alpha1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +InternalReleaseImage is used to keep track and manage a set +of release bundles (OCP and OLM operators images) that are stored +into the control planes nodes. + +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` + +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 describes the configuration of this internal release image. + +| `status` +| `object` +| status describes the last observed state of this internal release image. + +|=== +=== .spec +Description:: ++ +-- +spec describes the configuration of this internal release image. +-- + +Type:: + `object` + +Required:: + - `releases` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `releases` +| `array` +| releases is a list of release bundle identifiers that the user wants to +add/remove to/from the control plane nodes. +Entries must be unique, keyed on the name field. +releases must contain at least one entry and must not exceed 16 entries. + +| `releases[]` +| `object` +| InternalReleaseImageRef is used to provide a simple reference for a release +bundle. Currently it contains only the name field. + +|=== +=== .spec.releases +Description:: ++ +-- +releases is a list of release bundle identifiers that the user wants to +add/remove to/from the control plane nodes. +Entries must be unique, keyed on the name field. +releases must contain at least one entry and must not exceed 16 entries. +-- + +Type:: + `array` + + + + +=== .spec.releases[] +Description:: ++ +-- +InternalReleaseImageRef is used to provide a simple reference for a release +bundle. Currently it contains only the name field. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name indicates the desired release bundle identifier. This field is required and must be between 1 and 64 characters long. +The expected name format is ocp-release-bundle--. + +|=== +=== .status +Description:: ++ +-- +status describes the last observed state of this internal release image. +-- + +Type:: + `object` + +Required:: + - `releases` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| conditions represent the observations of the InternalReleaseImage controller current state. +Valid types are: Degraded. +If Degraded is true, that means something has gone wrong in the controller. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `releases` +| `array` +| releases is a list of the release bundles currently owned and managed by the +cluster. +A release bundle content could be safely pulled only when its Conditions field +contains at least an Available entry set to "True" and Degraded to "False". +Entries must be unique, keyed on the name field. +releases must contain at least one entry and must not exceed 32 entries. + +| `releases[]` +| `object` +| + +|=== +=== .status.conditions +Description:: ++ +-- +conditions represent the observations of the InternalReleaseImage controller current state. +Valid types are: Degraded. +If Degraded is true, that means something has gone wrong in the controller. +-- + +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.releases +Description:: ++ +-- +releases is a list of the release bundles currently owned and managed by the +cluster. +A release bundle content could be safely pulled only when its Conditions field +contains at least an Available entry set to "True" and Degraded to "False". +Entries must be unique, keyed on the name field. +releases must contain at least one entry and must not exceed 32 entries. +-- + +Type:: + `array` + + + + +=== .status.releases[] +Description:: ++ +-- + +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| conditions represent the observations of an internal release image current state. Valid types are: +Mounted, Installing, Available, Removing and Degraded. + +If Mounted is true, that means that a valid ISO has been discovered and mounted on one of the cluster nodes. +If Installing is true, that means that a new release bundle is currently being copied on one (or more) cluster nodes, and not yet completed. +If Available is true, it means that the release has been previously installed on all the cluster nodes, and it can be used. +If Removing is true, it means that a release deletion is in progress on one (or more) cluster nodes, and not yet completed. +If Degraded is true, that means something has gone wrong (possibly on one or more cluster nodes). + +In general, after installing a new release bundle, it is required to wait for the Conditions "Available" to become "True" (and all +the other conditions to be equal to "False") before being able to pull its content. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `image` +| `string` +| image is an OCP release image referenced by digest. +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. +The field is optional, and it will be provided after a release will be successfully installed. + +| `name` +| `string` +| name indicates the desired release bundle identifier. This field is required and must be between 1 and 64 characters long. +The expected name format is ocp-release-bundle--. + +|=== +=== .status.releases[].conditions +Description:: ++ +-- +conditions represent the observations of an internal release image current state. Valid types are: +Mounted, Installing, Available, Removing and Degraded. + +If Mounted is true, that means that a valid ISO has been discovered and mounted on one of the cluster nodes. +If Installing is true, that means that a new release bundle is currently being copied on one (or more) cluster nodes, and not yet completed. +If Available is true, it means that the release has been previously installed on all the cluster nodes, and it can be used. +If Removing is true, it means that a release deletion is in progress on one (or more) cluster nodes, and not yet completed. +If Degraded is true, that means something has gone wrong (possibly on one or more cluster nodes). + +In general, after installing a new release bundle, it is required to wait for the Conditions "Available" to become "True" (and all +the other conditions to be equal to "False") before being able to pull its content. +-- + +Type:: + `array` + + + + +=== .status.releases[].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/machineconfiguration.openshift.io/v1alpha1/internalreleaseimages` +- `DELETE`: delete collection of InternalReleaseImage +- `GET`: list objects of kind InternalReleaseImage +- `POST`: create an InternalReleaseImage +* `/apis/machineconfiguration.openshift.io/v1alpha1/internalreleaseimages/{name}` +- `DELETE`: delete an InternalReleaseImage +- `GET`: read the specified InternalReleaseImage +- `PATCH`: partially update the specified InternalReleaseImage +- `PUT`: replace the specified InternalReleaseImage +* `/apis/machineconfiguration.openshift.io/v1alpha1/internalreleaseimages/{name}/status` +- `GET`: read status of the specified InternalReleaseImage +- `PATCH`: partially update status of the specified InternalReleaseImage +- `PUT`: replace status of the specified InternalReleaseImage + + +=== /apis/machineconfiguration.openshift.io/v1alpha1/internalreleaseimages + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of InternalReleaseImage + + + + +.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 InternalReleaseImage + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-machineconfiguration-v1alpha1-InternalReleaseImageList[`InternalReleaseImageList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create an InternalReleaseImage + + +.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/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 201 - Created +| xref:../machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 202 - Accepted +| xref:../machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/machineconfiguration.openshift.io/v1alpha1/internalreleaseimages/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the InternalReleaseImage +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete an InternalReleaseImage + + +.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 InternalReleaseImage + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified InternalReleaseImage + + +.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/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified InternalReleaseImage + + +.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/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 201 - Created +| xref:../machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/machineconfiguration.openshift.io/v1alpha1/internalreleaseimages/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the InternalReleaseImage +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified InternalReleaseImage + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified InternalReleaseImage + + +.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/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified InternalReleaseImage + + +.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/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 201 - Created +| xref:../machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`InternalReleaseImage`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/machine_apis/machine-apis-index.adoc b/rest_api/machine_apis/machine-apis-index.adoc index 206676e2fd..5c74f21a5c 100644 --- a/rest_api/machine_apis/machine-apis-index.adoc +++ b/rest_api/machine_apis/machine-apis-index.adoc @@ -154,6 +154,37 @@ MachineOSConfig describes the configuration for a build process managed by the M Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- +Type:: + `object` + +== InternalReleaseImage [machineconfiguration.openshift.io/v1alpha1] + +Description:: ++ +-- +InternalReleaseImage is used to keep track and manage a set +of release bundles (OCP and OLM operators images) that are stored +into the control planes nodes. + +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` + +== OSImageStream [machineconfiguration.openshift.io/v1alpha1] + +Description:: ++ +-- +OSImageStream describes a set of streams and associated images available +for the MachineConfigPools to be used as base OS images. + +The resource is a singleton named "cluster". + +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` 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 398b4a02f9..1ff4b80479 100644 --- a/rest_api/machine_apis/machine-machine-openshift-io-v1beta1.adoc +++ b/rest_api/machine_apis/machine-machine-openshift-io-v1beta1.adoc @@ -64,6 +64,16 @@ Type:: |=== | Property | Type | Description +| `authoritativeAPI` +| `string` +| authoritativeAPI is the API that is authoritative for this resource. +Valid values are MachineAPI and ClusterAPI. +When set to MachineAPI, writes to the spec of the machine.openshift.io copy of this resource will be reflected into the cluster.x-k8s.io copy. +When set to ClusterAPI, writes to the spec of the cluster.x-k8s.io copy of this resource will be reflected into the machine.openshift.io copy. +Updates to the status will be reflected in both copies of the resource, based on the controller implementing the functionality of the API. +Currently the authoritative API determines which controller will manage the resource, this will change in a future release. +To ensure the change has been accepted, please verify that the `status.authoritativeAPI` field has been updated to the desired value and that the `Synchronized` condition is present and set to `True`. + | `lifecycleHooks` | `object` | lifecycleHooks allow users to pause operations on the machine at @@ -512,6 +522,14 @@ Type:: | `object` | NodeAddress contains information for the node's address. +| `authoritativeAPI` +| `string` +| authoritativeAPI is the API that is authoritative for this resource. +Valid values are MachineAPI, ClusterAPI and Migrating. +This value is updated by the migration controller to reflect the authoritative API. +Machine API and Cluster API controllers use this value to determine whether or not to reconcile the resource. +When set to Migrating, the migration controller is currently performing the handover of authority from one API to the other. + | `conditions` | `array` | conditions defines the current state of the Machine @@ -585,6 +603,11 @@ It is recommended that providers maintain their own versioned API types that should be serialized/deserialized from this field. +| `synchronizedGeneration` +| `integer` +| synchronizedGeneration is the generation of the authoritative resource that the non-authoritative resource is synchronised with. +This field is set when the authoritative resource is updated and the sync controller has updated the non-authoritative resource to match. + |=== === .status.addresses Description:: diff --git a/rest_api/machine_apis/machineconfignode-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/machineconfignode-machineconfiguration-openshift-io-v1.adoc index 06d76e9e88..e5b52cec57 100644 --- a/rest_api/machine_apis/machineconfignode-machineconfiguration-openshift-io-v1.adoc +++ b/rest_api/machine_apis/machineconfignode-machineconfiguration-openshift-io-v1.adoc @@ -70,6 +70,12 @@ Required:: |=== | Property | Type | Description +| `configImage` +| `object` +| configImage is an optional field for configuring the OS image to be used for this node. This field will only exist if the node belongs to a pool opted into on-cluster image builds, and will override any MachineConfig referenced OSImageURL fields +When omitted, Image Mode is not be enabled and the node will follow the standard update process of creating a rendered MachineConfig and updating to its specifications. +When specified, Image Mode is enabled and will attempt to update the node to use the desired image. Following this, the node will follow the standard update process of creating a rendered MachineConfig and updating to its specifications. + | `configVersion` | `object` | configVersion holds the desired config version for the node targeted by this machine config node resource. @@ -85,6 +91,34 @@ the new machine config against the current machine config. | pool contains a reference to the machine config pool that this machine config node's referenced node belongs to. +|=== +=== .spec.configImage +Description:: ++ +-- +configImage is an optional field for configuring the OS image to be used for this node. This field will only exist if the node belongs to a pool opted into on-cluster image builds, and will override any MachineConfig referenced OSImageURL fields +When omitted, Image Mode is not be enabled and the node will follow the standard update process of creating a rendered MachineConfig and updating to its specifications. +When specified, Image Mode is enabled and will attempt to update the node to use the desired image. Following this, the node will follow the standard update process of creating a rendered MachineConfig and updating to its specifications. +-- + +Type:: + `object` + +Required:: + - `desiredImage` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `desiredImage` +| `string` +| desiredImage is a required field that configures the image that the node should be updated to use. +It must be a fully qualified OCI image pull spec of the format host[:port][/namespace]/name@sha256:, where the digest must be exactly 64 characters in length and consist only of lowercase hexadecimal characters, a-f and 0-9. +desiredImage must not be an empty string and must not exceed 447 characters in length. + |=== === .spec.configVersion Description:: @@ -205,10 +239,39 @@ AppliedOSImage, AppliedFiles | `object` | Condition contains details for one aspect of the current state of this API Resource. +| `configImage` +| `object` +| configImage is an optional field for configuring the OS image to be used for this node. This field will only exist if the node belongs to a pool opted into on-cluster image builds, and will override any MachineConfig referenced OSImageURL fields. +When omitted, this means that the Image Mode feature is not being used and the node will be up to date with the specific current rendered config version for the nodes MachinePool. +When specified, the Image Mode feature is enabled and the contents of this field show the observed state of the node image. +When Image Mode is enabled and a new MachineConfig is applied such that a new OS image build is not created, only the configVersion field will change. +When Image Mode is enabled and a new MachineConfig is applied such that a new OS image build is created, then only the configImage field will change. It is also possible that both the configImage +and configVersion change during the same update. + | `configVersion` | `object` | configVersion describes the current and desired machine config version for this node. +| `internalReleaseImage` +| `object` +| internalReleaseImage describes the status of the release payloads stored in the node. +When specified, an internalReleaseImage custom resource exists on the cluster, and the specified images will be made available on the control plane nodes. +This field will reflect the actual on-disk state of those release images. + +| `irreconcilableChanges` +| `array` +| irreconcilableChanges is an optional field that contains the observed differences between this nodes +configuration and the target rendered MachineConfig. +This field will be set when there are changes to the target rendered MachineConfig that can only be applied to +new nodes joining the cluster. +Entries must be unique, keyed on the fieldPath field. +Must not exceed 32 entries. + +| `irreconcilableChanges[]` +| `object` +| IrreconcilableChangeDiff holds an individual diff between the initial install-time MachineConfig +and the latest applied one caused by the presence of irreconcilable changes. + | `observedGeneration` | `integer` | observedGeneration represents the generation of the MachineConfigNode object observed by the Machine Config Operator's controller. @@ -296,6 +359,46 @@ This field may not be empty. | `string` | type of condition in CamelCase or in foo.example.com/CamelCase. +|=== +=== .status.configImage +Description:: ++ +-- +configImage is an optional field for configuring the OS image to be used for this node. This field will only exist if the node belongs to a pool opted into on-cluster image builds, and will override any MachineConfig referenced OSImageURL fields. +When omitted, this means that the Image Mode feature is not being used and the node will be up to date with the specific current rendered config version for the nodes MachinePool. +When specified, the Image Mode feature is enabled and the contents of this field show the observed state of the node image. +When Image Mode is enabled and a new MachineConfig is applied such that a new OS image build is not created, only the configVersion field will change. +When Image Mode is enabled and a new MachineConfig is applied such that a new OS image build is created, then only the configImage field will change. It is also possible that both the configImage +and configVersion change during the same update. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `currentImage` +| `string` +| currentImage is an optional field that represents the current image that is applied to the node. +When omitted, this means that no image updates have been applied to the node and it will be up to date with the specific current rendered config version. +When specified, this means that the node is currently using this image. +currentImage must be a fully qualified OCI image pull spec of the format host[:port][/namespace]/name@sha256:, where the digest must be exactly 64 characters in length and consist only of lowercase hexadecimal characters, a-f and 0-9. +currentImage must not be an empty string and must not exceed 447 characters in length. + +| `desiredImage` +| `string` +| desiredImage is an optional field that represents the currently observed state of image that the node should be updated to use. +When not specified, this means that Image Mode has been disabled and the node will up to date with the specific current rendered config version. +When specified, this means that Image Mode has been enabled and the node is actively progressing to update the node to this image. +If currentImage and desiredImage match, the node has been successfully updated to use the desired image. +desiredImage must be a fully qualified OCI image pull spec of the format host[:port][/namespace]/name@sha256:, where the digest must be exactly 64 characters in length and consist only of lowercase hexadecimal characters, a-f and 0-9. +desiredImage must not be an empty string and must not exceed 447 characters in length. + |=== === .status.configVersion Description:: @@ -334,6 +437,238 @@ Must be a lowercase RFC-1123 subdomain name (https://tools.ietf.org/html/rfc1123 of only lowercase alphanumeric characters, hyphens (-), and periods (.), and must start and end with an alphanumeric character, and be at most 253 characters in length. +|=== +=== .status.internalReleaseImage +Description:: ++ +-- +internalReleaseImage describes the status of the release payloads stored in the node. +When specified, an internalReleaseImage custom resource exists on the cluster, and the specified images will be made available on the control plane nodes. +This field will reflect the actual on-disk state of those release images. +-- + +Type:: + `object` + +Required:: + - `releases` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `releases` +| `array` +| releases is a list of the release bundles currently owned and managed by the +cluster. +A release bundle content could be safely pulled only when its Conditions field +contains at least an Available entry set to "True" and Degraded to "False". +Entries must be unique, keyed on the name field. +releases must contain at least one entry and must not exceed 32 entries. + +| `releases[]` +| `object` +| MachineConfigNodeStatusInternalReleaseImageRef is used to provide a more detailed reference for +a release bundle. + +|=== +=== .status.internalReleaseImage.releases +Description:: ++ +-- +releases is a list of the release bundles currently owned and managed by the +cluster. +A release bundle content could be safely pulled only when its Conditions field +contains at least an Available entry set to "True" and Degraded to "False". +Entries must be unique, keyed on the name field. +releases must contain at least one entry and must not exceed 32 entries. +-- + +Type:: + `array` + + + + +=== .status.internalReleaseImage.releases[] +Description:: ++ +-- +MachineConfigNodeStatusInternalReleaseImageRef is used to provide a more detailed reference for +a release bundle. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| conditions represent the observations of an internal release image current state. Valid types are: +Mounted, Installing, Available, Removing and Degraded. + +If Mounted is true, that means that a valid ISO has been mounted on the current node. +If Installing is true, that means that a new release bundle is currently being copied on the current node, and not yet completed. +If Available is true, it means that the release has been previously installed on the current node, and it can be used. +If Removing is true, it means that a release deletion is in progress on the current node, and not yet completed. +If Degraded is true, that means something has gone wrong in the current node. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `image` +| `string` +| image is an OCP release image referenced by digest. +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. +The field is optional, and it will be provided after a release will be successfully installed. + +| `name` +| `string` +| name indicates the desired release bundle identifier. This field is required and must be between 1 and 64 characters long. +The expected name format is ocp-release-bundle--. + +|=== +=== .status.internalReleaseImage.releases[].conditions +Description:: ++ +-- +conditions represent the observations of an internal release image current state. Valid types are: +Mounted, Installing, Available, Removing and Degraded. + +If Mounted is true, that means that a valid ISO has been mounted on the current node. +If Installing is true, that means that a new release bundle is currently being copied on the current node, and not yet completed. +If Available is true, it means that the release has been previously installed on the current node, and it can be used. +If Removing is true, it means that a release deletion is in progress on the current node, and not yet completed. +If Degraded is true, that means something has gone wrong in the current node. +-- + +Type:: + `array` + + + + +=== .status.internalReleaseImage.releases[].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.irreconcilableChanges +Description:: ++ +-- +irreconcilableChanges is an optional field that contains the observed differences between this nodes +configuration and the target rendered MachineConfig. +This field will be set when there are changes to the target rendered MachineConfig that can only be applied to +new nodes joining the cluster. +Entries must be unique, keyed on the fieldPath field. +Must not exceed 32 entries. +-- + +Type:: + `array` + + + + +=== .status.irreconcilableChanges[] +Description:: ++ +-- +IrreconcilableChangeDiff holds an individual diff between the initial install-time MachineConfig +and the latest applied one caused by the presence of irreconcilable changes. +-- + +Type:: + `object` + +Required:: + - `diff` + - `fieldPath` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `diff` +| `string` +| diff is a required field containing the difference between the nodes current configuration and the latest +rendered MachineConfig for the field specified in fieldPath. +Must not be an empty string and must not exceed 4096 characters in length. + +| `fieldPath` +| `string` +| fieldPath is a required reference to the path in the latest rendered MachineConfig that differs from this nodes +configuration. +Must not be empty and must not exceed 70 characters in length. +Must begin with the prefix 'spec.' and only contain alphanumeric characters, square brackets ('[]'), or dots ('.'). + |=== === .status.pinnedImageSets Description:: 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 c5a4d23ade..38cb9a416d 100644 --- a/rest_api/machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc +++ b/rest_api/machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc @@ -94,6 +94,19 @@ maxUnavailable is greater than one. | `object` | nodeSelector specifies a label selector for Machines +| `osImageStream` +| `object` +| osImageStream specifies an OS stream to be used for the pool. + +This field can be optionally set to a known OSImageStream name to change the +OS and Extension images with a well-known, tested, release-provided set of images. +This enables a streamlined way of switching the pool's node OS to a different version +than the cluster default, such as transitioning to a major RHEL version. + +When set, the referenced stream overrides the cluster-wide OS +images for the pool with the OS and Extensions associated to stream. +When omitted, the pool uses the cluster-wide default OS images. + | `paused` | `boolean` | paused specifies whether or not changes to this machine config pool should be stopped. @@ -427,6 +440,42 @@ 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.osImageStream +Description:: ++ +-- +osImageStream specifies an OS stream to be used for the pool. + +This field can be optionally set to a known OSImageStream name to change the +OS and Extension images with a well-known, tested, release-provided set of images. +This enables a streamlined way of switching the pool's node OS to a different version +than the cluster default, such as transitioning to a major RHEL version. + +When set, the referenced stream overrides the cluster-wide OS +images for the pool with the OS and Extensions associated to stream. +When omitted, the pool uses the cluster-wide default OS images. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is a required reference to an OSImageStream to be used for the pool. + +It must be a valid RFC 1123 subdomain between 1 and 253 characters in length, +consisting of lowercase alphanumeric characters, hyphens ('-'), and periods ('.'). + |=== === .spec.pinnedImageSets Description:: @@ -536,6 +585,12 @@ A node is marked degraded if applying a configuration failed.. | `integer` | observedGeneration represents the generation observed by the controller. +| `osImageStream` +| `object` +| osImageStream specifies the last updated OSImageStream for the pool. + +When omitted, the pool is using the cluster-wide default OS images. + | `poolSynchronizersStatus` | `array` | poolSynchronizersStatus is the status of the machines managed by the pool synchronizers. @@ -792,6 +847,35 @@ More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api- | UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids +|=== +=== .status.osImageStream +Description:: ++ +-- +osImageStream specifies the last updated OSImageStream for the pool. + +When omitted, the pool is using the cluster-wide default OS images. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is a required reference to an OSImageStream to be used for the pool. + +It must be a valid RFC 1123 subdomain between 1 and 253 characters in length, +consisting of lowercase alphanumeric characters, hyphens ('-'), and periods ('.'). + |=== === .status.poolSynchronizersStatus Description:: 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 b47611075e..ba45f6150b 100644 --- a/rest_api/machine_apis/machineset-machine-openshift-io-v1beta1.adoc +++ b/rest_api/machine_apis/machineset-machine-openshift-io-v1beta1.adoc @@ -64,6 +64,16 @@ Type:: |=== | Property | Type | Description +| `authoritativeAPI` +| `string` +| authoritativeAPI is the API that is authoritative for this resource. +Valid values are MachineAPI and ClusterAPI. +When set to MachineAPI, writes to the spec of the machine.openshift.io copy of this resource will be reflected into the cluster.x-k8s.io copy. +When set to ClusterAPI, writes to the spec of the cluster.x-k8s.io copy of this resource will be reflected into the machine.openshift.io copy. +Updates to the status will be reflected in both copies of the resource, based on the controller implementing the functionality of the API. +Currently the authoritative API determines which controller will manage the resource, this will change in a future release. +To ensure the change has been accepted, please verify that the `status.authoritativeAPI` field has been updated to the desired value and that the `Synchronized` condition is present and set to `True`. + | `deletePolicy` | `string` | deletePolicy defines the policy used to identify nodes to delete when downscaling. @@ -386,6 +396,16 @@ Type:: |=== | Property | Type | Description +| `authoritativeAPI` +| `string` +| authoritativeAPI is the API that is authoritative for this resource. +Valid values are MachineAPI and ClusterAPI. +When set to MachineAPI, writes to the spec of the machine.openshift.io copy of this resource will be reflected into the cluster.x-k8s.io copy. +When set to ClusterAPI, writes to the spec of the cluster.x-k8s.io copy of this resource will be reflected into the machine.openshift.io copy. +Updates to the status will be reflected in both copies of the resource, based on the controller implementing the functionality of the API. +Currently the authoritative API determines which controller will manage the resource, this will change in a future release. +To ensure the change has been accepted, please verify that the `status.authoritativeAPI` field has been updated to the desired value and that the `Synchronized` condition is present and set to `True`. + | `lifecycleHooks` | `object` | lifecycleHooks allow users to pause operations on the machine at @@ -826,6 +846,14 @@ Type:: |=== | Property | Type | Description +| `authoritativeAPI` +| `string` +| authoritativeAPI is the API that is authoritative for this resource. +Valid values are MachineAPI, ClusterAPI and Migrating. +This value is updated by the migration controller to reflect the authoritative API. +Machine API and Cluster API controllers use this value to determine whether or not to reconcile the resource. +When set to Migrating, the migration controller is currently performing the handover of authority from one API to the other. + | `availableReplicas` | `integer` | The number of available replicas (ready for at least minReadySeconds) for this MachineSet. @@ -879,6 +907,11 @@ controller's output. | `integer` | replicas is the most recently observed number of replicas. +| `synchronizedGeneration` +| `integer` +| synchronizedGeneration is the generation of the authoritative resource that the non-authoritative resource is synchronised with. +This field is set when the authoritative resource is updated and the sync controller has updated the non-authoritative resource to match. + |=== === .status.conditions Description:: diff --git a/rest_api/machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc b/rest_api/machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc new file mode 100644 index 0000000000..ae8f02c9ab --- /dev/null +++ b/rest_api/machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc @@ -0,0 +1,521 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="osimagestream-machineconfiguration-openshift-io-v1alpha1"] += OSImageStream [machineconfiguration.openshift.io/v1alpha1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +OSImageStream describes a set of streams and associated images available +for the MachineConfigPools to be used as base OS images. + +The resource is a singleton named "cluster". + +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` + +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 contains the desired OSImageStream config configuration. + +| `status` +| `object` +| status describes the last observed state of this OSImageStream. +Populated by the MachineConfigOperator after reading release metadata. +When not present, the controller has not yet reconciled this resource. + +|=== +=== .spec +Description:: ++ +-- +spec contains the desired OSImageStream config configuration. +-- + +Type:: + `object` + + + + +=== .status +Description:: ++ +-- +status describes the last observed state of this OSImageStream. +Populated by the MachineConfigOperator after reading release metadata. +When not present, the controller has not yet reconciled this resource. +-- + +Type:: + `object` + +Required:: + - `availableStreams` + - `defaultStream` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `availableStreams` +| `array` +| availableStreams is a list of the available OS Image Streams that can be +used as the base image for MachineConfigPools. +availableStreams is required, must have at least one item, must not exceed +100 items, and must have unique entries keyed on the name field. + +| `availableStreams[]` +| `object` +| + +| `defaultStream` +| `string` +| defaultStream is the name of the stream that should be used as the default +when no specific stream is requested by a MachineConfigPool. + +It must be a valid RFC 1123 subdomain between 1 and 253 characters in length, +consisting of lowercase alphanumeric characters, hyphens ('-'), and periods ('.'), +and must reference the name of one of the streams in availableStreams. + +|=== +=== .status.availableStreams +Description:: ++ +-- +availableStreams is a list of the available OS Image Streams that can be +used as the base image for MachineConfigPools. +availableStreams is required, must have at least one item, must not exceed +100 items, and must have unique entries keyed on the name field. +-- + +Type:: + `array` + + + + +=== .status.availableStreams[] +Description:: ++ +-- + +-- + +Type:: + `object` + +Required:: + - `name` + - `osExtensionsImage` + - `osImage` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is the required identifier of the stream. + +name is determined by the operator based on the OCI label of the +discovered OS or Extension Image. + +Must be a valid RFC 1123 subdomain between 1 and 253 characters in length, +consisting of lowercase alphanumeric characters, hyphens ('-'), and periods ('.'). + +| `osExtensionsImage` +| `string` +| osExtensionsImage is a required OS Extensions Image referenced by digest. + +osExtensionsImage bundles the extra repositories used to enable extensions, augmenting +the base operating system without modifying the underlying immutable osImage. + +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. + +| `osImage` +| `string` +| osImage is a required OS Image referenced by digest. + +osImage contains the immutable, fundamental operating system components, including the kernel +and base utilities, that define the core environment for the node's host operating system. + +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. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/machineconfiguration.openshift.io/v1alpha1/osimagestreams` +- `DELETE`: delete collection of OSImageStream +- `GET`: list objects of kind OSImageStream +- `POST`: create an OSImageStream +* `/apis/machineconfiguration.openshift.io/v1alpha1/osimagestreams/{name}` +- `DELETE`: delete an OSImageStream +- `GET`: read the specified OSImageStream +- `PATCH`: partially update the specified OSImageStream +- `PUT`: replace the specified OSImageStream +* `/apis/machineconfiguration.openshift.io/v1alpha1/osimagestreams/{name}/status` +- `GET`: read status of the specified OSImageStream +- `PATCH`: partially update status of the specified OSImageStream +- `PUT`: replace status of the specified OSImageStream + + +=== /apis/machineconfiguration.openshift.io/v1alpha1/osimagestreams + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of OSImageStream + + + + +.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 OSImageStream + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-machineconfiguration-v1alpha1-OSImageStreamList[`OSImageStreamList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create an OSImageStream + + +.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/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 201 - Created +| xref:../machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 202 - Accepted +| xref:../machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/machineconfiguration.openshift.io/v1alpha1/osimagestreams/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the OSImageStream +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete an OSImageStream + + +.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 OSImageStream + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified OSImageStream + + +.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/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified OSImageStream + + +.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/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 201 - Created +| xref:../machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/machineconfiguration.openshift.io/v1alpha1/osimagestreams/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the OSImageStream +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified OSImageStream + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified OSImageStream + + +.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/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified OSImageStream + + +.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/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 201 - Created +| xref:../machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`OSImageStream`] schema +| 401 - Unauthorized +| Empty +|=== + + 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 e0403d9aef..da8efe8033 100644 --- a/rest_api/monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1beta1.adoc +++ b/rest_api/monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1beta1.adoc @@ -7885,6 +7885,11 @@ When true, the message can include HTML formatting tags. | message defines the notification message content. This is the main body text of the Pushover notification. +| `monospace` +| `boolean` +| monospace optional HTML/monospace formatting for the message, see https://pushover.net/api#html +html and monospace formatting are mutually exclusive. + | `priority` | `string` | priority defines the notification priority level. @@ -13618,7 +13623,7 @@ variable `AWS_SECRET_ACCESS_KEY` is used. | `useFIPSSTSEndpoint` | `boolean` -| useFIPSSTSEndpoint defines FIPS mode for AWS STS endpoint. +| useFIPSSTSEndpoint defines the FIPS mode for the AWS STS endpoint. It requires Prometheus >= v2.54.0. |=== diff --git a/rest_api/monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc b/rest_api/monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc new file mode 100644 index 0000000000..7cf749cfea --- /dev/null +++ b/rest_api/monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc @@ -0,0 +1,1142 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="datagather-insights-openshift-io-v1alpha2"] += DataGather [insights.openshift.io/v1alpha2] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +DataGather provides data gather configuration options and status for the particular Insights data gathering. + +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` + +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 holds user settable values for configuration + +| `status` +| `object` +| status holds observed values from the cluster. They may not be overridden. + +|=== +=== .spec +Description:: ++ +-- +spec holds user settable values for configuration +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `dataPolicy` +| `array (string)` +| dataPolicy is an optional list of DataPolicyOptions that allows user to enable additional obfuscation of the Insights archive data. +It may not exceed 2 items and must not contain duplicates. +Valid values are ObfuscateNetworking and WorkloadNames. +When set to ObfuscateNetworking the IP addresses and the cluster domain name are obfuscated. +When set to WorkloadNames, the gathered data about cluster resources will not contain the workload names for your deployments. Resources UIDs will be used instead. +When omitted no obfuscation is applied. + +| `gatherers` +| `object` +| gatherers is an optional field that specifies the configuration of the gatherers. +If omitted, all gatherers will be run. + +| `storage` +| `object` +| storage is an optional field that allows user to define persistent storage for gathering jobs to store the Insights data archive. +If omitted, the gathering job will use ephemeral storage. + +|=== +=== .spec.gatherers +Description:: ++ +-- +gatherers is an optional field that specifies the configuration of the gatherers. +If omitted, all gatherers will be run. +-- + +Type:: + `object` + +Required:: + - `mode` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `custom` +| `object` +| custom provides gathering configuration. +It is required when mode is Custom, and forbidden otherwise. +Custom configuration allows user to disable only a subset of gatherers. +Gatherers that are not explicitly disabled in custom configuration will run. + +| `mode` +| `string` +| mode is a required field that specifies the mode for gatherers. Allowed values are All and Custom. +When set to All, all gatherers wil run and gather data. +When set to Custom, the custom configuration from the custom field will be applied. + +|=== +=== .spec.gatherers.custom +Description:: ++ +-- +custom provides gathering configuration. +It is required when mode is Custom, and forbidden otherwise. +Custom configuration allows user to disable only a subset of gatherers. +Gatherers that are not explicitly disabled in custom configuration will run. +-- + +Type:: + `object` + +Required:: + - `configs` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `configs` +| `array` +| configs is a required list of gatherers configurations that can be used to enable or disable specific gatherers. +It may not exceed 100 items and each gatherer can be present only once. +It is possible to disable an entire set of gatherers while allowing a specific function within that set. +The particular gatherers IDs can be found at https://github.com/openshift/insights-operator/blob/master/docs/gathered-data.md. +Run the following command to get the names of last active gatherers: +"oc get insightsoperators.operator.openshift.io cluster -o json \| jq '.status.gatherStatus.gatherers[].name'" + +| `configs[]` +| `object` +| gathererConfig allows to configure specific gatherers + +|=== +=== .spec.gatherers.custom.configs +Description:: ++ +-- +configs is a required list of gatherers configurations that can be used to enable or disable specific gatherers. +It may not exceed 100 items and each gatherer can be present only once. +It is possible to disable an entire set of gatherers while allowing a specific function within that set. +The particular gatherers IDs can be found at https://github.com/openshift/insights-operator/blob/master/docs/gathered-data.md. +Run the following command to get the names of last active gatherers: +"oc get insightsoperators.operator.openshift.io cluster -o json \| jq '.status.gatherStatus.gatherers[].name'" +-- + +Type:: + `array` + + + + +=== .spec.gatherers.custom.configs[] +Description:: ++ +-- +gathererConfig allows to configure specific gatherers +-- + +Type:: + `object` + +Required:: + - `name` + - `state` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is the required name of a specific gatherer +It may not exceed 256 characters. +The format for a gatherer name is: {gatherer}/{function} where the function is optional. +Gatherer consists of a lowercase letters only that may include underscores (_). +Function consists of a lowercase letters only that may include underscores (_) and is separated from the gatherer by a forward slash (/). +The particular gatherers can be found at https://github.com/openshift/insights-operator/blob/master/docs/gathered-data.md. +Run the following command to get the names of last active gatherers: +"oc get insightsoperators.operator.openshift.io cluster -o json \| jq '.status.gatherStatus.gatherers[].name'" + +| `state` +| `string` +| state is a required field that allows you to configure specific gatherer. Valid values are "Enabled" and "Disabled". +When set to Enabled the gatherer will run. +When set to Disabled the gatherer will not run. + +|=== +=== .spec.storage +Description:: ++ +-- +storage is an optional field that allows user to define persistent storage for gathering jobs to store the Insights data archive. +If omitted, the gathering job will use ephemeral storage. +-- + +Type:: + `object` + +Required:: + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `persistentVolume` +| `object` +| persistentVolume is an optional field that specifies the PersistentVolume that will be used to store the Insights data archive. +The PersistentVolume must be created in the openshift-insights namespace. + +| `type` +| `string` +| type is a required field that specifies the type of storage that will be used to store the Insights data archive. +Valid values are "PersistentVolume" and "Ephemeral". +When set to Ephemeral, the Insights data archive is stored in the ephemeral storage of the gathering job. +When set to PersistentVolume, the Insights data archive is stored in the PersistentVolume that is +defined by the PersistentVolume field. + +|=== +=== .spec.storage.persistentVolume +Description:: ++ +-- +persistentVolume is an optional field that specifies the PersistentVolume that will be used to store the Insights data archive. +The PersistentVolume must be created in the openshift-insights namespace. +-- + +Type:: + `object` + +Required:: + - `claim` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `claim` +| `object` +| claim is a required field that specifies the configuration of the PersistentVolumeClaim that will be used to store the Insights data archive. +The PersistentVolumeClaim must be created in the openshift-insights namespace. + +| `mountPath` +| `string` +| mountPath is an optional field specifying the directory where the PVC will be mounted inside the Insights data gathering Pod. +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 mount path is /var/lib/insights-operator +The path may not exceed 1024 characters and must not contain a colon. + +|=== +=== .spec.storage.persistentVolume.claim +Description:: ++ +-- +claim is a required field that specifies the configuration of the PersistentVolumeClaim that will be used to store the Insights data archive. +The PersistentVolumeClaim must be created in the openshift-insights namespace. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is a string that follows the DNS1123 subdomain format. +It must be at most 253 characters in length, and must consist only of lower case alphanumeric characters, '-' and '.', and must start and end with an alphanumeric character. + +|=== +=== .status +Description:: ++ +-- +status holds observed values from the cluster. They may not be overridden. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| conditions is an optional field that provides details on the status of the gatherer job. +It may not exceed 100 items and must not contain duplicates. + +The current condition types are DataUploaded, DataRecorded, DataProcessed, RemoteConfigurationNotAvailable, RemoteConfigurationInvalid + +The DataUploaded condition is used to represent whether or not the archive was successfully uploaded for further processing. +When it has a status of True and a reason of Succeeded, the archive was successfully uploaded. +When it has a status of Unknown and a reason of NoUploadYet, the upload has not occurred, or there was no data to upload. +When it has a status of False and a reason Failed, the upload failed. The accompanying message will include the specific error encountered. + +The DataRecorded condition is used to represent whether or not the archive was successfully recorded. +When it has a status of True and a reason of Succeeded, the archive was recorded successfully. +When it has a status of Unknown and a reason of NoDataGatheringYet, the data gathering process has not started yet. +When it has a status of False and a reason of RecordingFailed, the recording failed and a message will include the specific error encountered. + +The DataProcessed condition is used to represent whether or not the archive was processed by the processing service. +When it has a status of True and a reason of Processed, the data was processed successfully. +When it has a status of Unknown and a reason of NothingToProcessYet, there is no data to process at the moment. +When it has a status of False and a reason of Failure, processing failed and a message will include the specific error encountered. + +The RemoteConfigurationAvailable condition is used to represent whether the remote configuration is available. +When it has a status of Unknown and a reason of Unknown or RemoteConfigNotRequestedYet, the state of the remote configuration is unknown—typically at startup. +When it has a status of True and a reason of Succeeded, the configuration is available. +When it has a status of False and a reason of NoToken, the configuration was disabled by removing the cloud.openshift.com field from the pull secret. +When it has a status of False and a reason of DisabledByConfiguration, the configuration was disabled in insightsdatagather.config.openshift.io. + +The RemoteConfigurationValid condition is used to represent whether the remote configuration is valid. +When it has a status of Unknown and a reason of Unknown or NoValidationYet, the validity of the remote configuration is unknown—typically at startup. +When it has a status of True and a reason of Succeeded, the configuration is valid. +When it has a status of False and a reason of Invalid, the configuration is invalid. + +The Progressing condition is used to represent the phase of gathering +When it has a status of False and the reason is DataGatherPending, the gathering has not started yet. +When it has a status of True and reason is Gathering, the gathering is running. +When it has a status of False and reason is GatheringSucceeded, the gathering succesfully finished. +When it has a status of False and reason is GatheringFailed, the gathering failed. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `finishTime` +| `string` +| finishTime is the time when Insights data gathering finished. + +| `gatherers` +| `array` +| gatherers is a list of active gatherers (and their statuses) in the last gathering. + +| `gatherers[]` +| `object` +| gathererStatus represents information about a particular +data gatherer. + +| `insightsReport` +| `object` +| insightsReport provides general Insights analysis results. +When omitted, this means no data gathering has taken place yet or the +corresponding Insights analysis (identified by "insightsRequestID") is not available. + +| `insightsRequestID` +| `string` +| insightsRequestID is an optional Insights request ID to track the status of the Insights analysis (in console.redhat.com processing pipeline) for the corresponding Insights data archive. +It may not exceed 256 characters and is immutable once set. + +| `relatedObjects` +| `array` +| relatedObjects is an optional list of resources which are useful when debugging or inspecting the data gathering Pod +It may not exceed 100 items and must not contain duplicates. + +| `relatedObjects[]` +| `object` +| ObjectReference contains enough information to let you inspect or modify the referred object. + +| `startTime` +| `string` +| startTime is the time when Insights data gathering started. + +|=== +=== .status.conditions +Description:: ++ +-- +conditions is an optional field that provides details on the status of the gatherer job. +It may not exceed 100 items and must not contain duplicates. + +The current condition types are DataUploaded, DataRecorded, DataProcessed, RemoteConfigurationNotAvailable, RemoteConfigurationInvalid + +The DataUploaded condition is used to represent whether or not the archive was successfully uploaded for further processing. +When it has a status of True and a reason of Succeeded, the archive was successfully uploaded. +When it has a status of Unknown and a reason of NoUploadYet, the upload has not occurred, or there was no data to upload. +When it has a status of False and a reason Failed, the upload failed. The accompanying message will include the specific error encountered. + +The DataRecorded condition is used to represent whether or not the archive was successfully recorded. +When it has a status of True and a reason of Succeeded, the archive was recorded successfully. +When it has a status of Unknown and a reason of NoDataGatheringYet, the data gathering process has not started yet. +When it has a status of False and a reason of RecordingFailed, the recording failed and a message will include the specific error encountered. + +The DataProcessed condition is used to represent whether or not the archive was processed by the processing service. +When it has a status of True and a reason of Processed, the data was processed successfully. +When it has a status of Unknown and a reason of NothingToProcessYet, there is no data to process at the moment. +When it has a status of False and a reason of Failure, processing failed and a message will include the specific error encountered. + +The RemoteConfigurationAvailable condition is used to represent whether the remote configuration is available. +When it has a status of Unknown and a reason of Unknown or RemoteConfigNotRequestedYet, the state of the remote configuration is unknown—typically at startup. +When it has a status of True and a reason of Succeeded, the configuration is available. +When it has a status of False and a reason of NoToken, the configuration was disabled by removing the cloud.openshift.com field from the pull secret. +When it has a status of False and a reason of DisabledByConfiguration, the configuration was disabled in insightsdatagather.config.openshift.io. + +The RemoteConfigurationValid condition is used to represent whether the remote configuration is valid. +When it has a status of Unknown and a reason of Unknown or NoValidationYet, the validity of the remote configuration is unknown—typically at startup. +When it has a status of True and a reason of Succeeded, the configuration is valid. +When it has a status of False and a reason of Invalid, the configuration is invalid. + +The Progressing condition is used to represent the phase of gathering +When it has a status of False and the reason is DataGatherPending, the gathering has not started yet. +When it has a status of True and reason is Gathering, the gathering is running. +When it has a status of False and reason is GatheringSucceeded, the gathering succesfully finished. +When it has a status of False and reason is GatheringFailed, the gathering failed. +-- + +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.gatherers +Description:: ++ +-- +gatherers is a list of active gatherers (and their statuses) in the last gathering. +-- + +Type:: + `array` + + + + +=== .status.gatherers[] +Description:: ++ +-- +gathererStatus represents information about a particular +data gatherer. +-- + +Type:: + `object` + +Required:: + - `lastGatherSeconds` + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| conditions provide details on the status of each gatherer. + +The current condition type is DataGathered + +The DataGathered condition is used to represent whether or not the data was gathered by a gatherer specified by name. +When it has a status of True and a reason of GatheredOK, the data has been successfully gathered as expected. +When it has a status of False and a reason of NoData, no data was gathered—for example, when the resource is not present in the cluster. +When it has a status of False and a reason of GatherError, an error occurred and no data was gathered. +When it has a status of False and a reason of GatherPanic, a panic occurred during gathering and no data was collected. +When it has a status of False and a reason of GatherWithErrorReason, data was partially gathered or gathered with an error message. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `lastGatherSeconds` +| `integer` +| lastGatherSeconds is required field that represents the time spent gathering in seconds + +| `name` +| `string` +| name is the required name of the gatherer. +It must contain at least 5 characters and may not exceed 256 characters. + +|=== +=== .status.gatherers[].conditions +Description:: ++ +-- +conditions provide details on the status of each gatherer. + +The current condition type is DataGathered + +The DataGathered condition is used to represent whether or not the data was gathered by a gatherer specified by name. +When it has a status of True and a reason of GatheredOK, the data has been successfully gathered as expected. +When it has a status of False and a reason of NoData, no data was gathered—for example, when the resource is not present in the cluster. +When it has a status of False and a reason of GatherError, an error occurred and no data was gathered. +When it has a status of False and a reason of GatherPanic, a panic occurred during gathering and no data was collected. +When it has a status of False and a reason of GatherWithErrorReason, data was partially gathered or gathered with an error message. +-- + +Type:: + `array` + + + + +=== .status.gatherers[].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.insightsReport +Description:: ++ +-- +insightsReport provides general Insights analysis results. +When omitted, this means no data gathering has taken place yet or the +corresponding Insights analysis (identified by "insightsRequestID") is not available. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `downloadedTime` +| `string` +| downloadedTime is an optional time when the last Insights report was downloaded. +An empty value means that there has not been any Insights report downloaded yet and +it usually appears in disconnected clusters (or clusters when the Insights data gathering is disabled). + +| `healthChecks` +| `array` +| healthChecks provides basic information about active Insights health checks +in a cluster. + +| `healthChecks[]` +| `object` +| healthCheck represents an Insights health check attributes. + +| `uri` +| `string` +| uri is optional field that provides the URL link from which the report was downloaded. +The link must be a valid HTTPS URL and the maximum length is 2048 characters. + +|=== +=== .status.insightsReport.healthChecks +Description:: ++ +-- +healthChecks provides basic information about active Insights health checks +in a cluster. +-- + +Type:: + `array` + + + + +=== .status.insightsReport.healthChecks[] +Description:: ++ +-- +healthCheck represents an Insights health check attributes. +-- + +Type:: + `object` + +Required:: + - `advisorURI` + - `description` + - `totalRisk` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `advisorURI` +| `string` +| advisorURI is required field that provides the URL link to the Insights Advisor. +The link must be a valid HTTPS URL and the maximum length is 2048 characters. + +| `description` +| `string` +| description is required field that provides basic description of the healtcheck. +It must contain at least 10 characters and may not exceed 2048 characters. + +| `totalRisk` +| `string` +| totalRisk is the required field of the healthcheck. +It is indicator of the total risk posed by the detected issue; combination of impact and likelihood. +Allowed values are Low, Medium, Important and Critical. +The value represents the severity of the issue. + +|=== +=== .status.relatedObjects +Description:: ++ +-- +relatedObjects is an optional list of resources which are useful when debugging or inspecting the data gathering Pod +It may not exceed 100 items and must not contain duplicates. +-- + +Type:: + `array` + + + + +=== .status.relatedObjects[] +Description:: ++ +-- +ObjectReference contains enough information to let you inspect or modify the referred object. +-- + +Type:: + `object` + +Required:: + - `group` + - `name` + - `namespace` + - `resource` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| group is required field that specifies the API Group of the Resource. +Enter empty string for the core group. +This value is empty or it should follow the DNS1123 subdomain format. +It must be at most 253 characters in length, and must consist only of lower case alphanumeric characters, '-' and '.', and must start with an alphabetic character and end with an alphanumeric character. +Example: "", "apps", "build.openshift.io", etc. + +| `name` +| `string` +| name is required field that specifies the referent that follows the DNS1123 subdomain format. +It must be at most 253 characters in length, and must consist only of lower case alphanumeric characters, '-' and '.', and must start with an alphabetic character and end with an alphanumeric character.. + +| `namespace` +| `string` +| namespace if required field of the referent that follows the DNS1123 labels format. +It must be at most 63 characters in length, and must must consist of only lowercase alphanumeric characters and hyphens, and must start with an alphabetic character and end with an alphanumeric character. + +| `resource` +| `string` +| resource is required field of the type that is being referenced and follows the DNS1035 format. +It is normally the plural form of the resource kind in lowercase. +It must be at most 63 characters in length, and must must consist of only lowercase alphanumeric characters and hyphens, and must start with an alphabetic character and end with an alphanumeric character. +Example: "deployments", "deploymentconfigs", "pods", etc. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/insights.openshift.io/v1alpha2/datagathers` +- `DELETE`: delete collection of DataGather +- `GET`: list objects of kind DataGather +- `POST`: create a DataGather +* `/apis/insights.openshift.io/v1alpha2/datagathers/{name}` +- `DELETE`: delete a DataGather +- `GET`: read the specified DataGather +- `PATCH`: partially update the specified DataGather +- `PUT`: replace the specified DataGather +* `/apis/insights.openshift.io/v1alpha2/datagathers/{name}/status` +- `GET`: read status of the specified DataGather +- `PATCH`: partially update status of the specified DataGather +- `PUT`: replace status of the specified DataGather + + +=== /apis/insights.openshift.io/v1alpha2/datagathers + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of DataGather + + + + +.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 DataGather + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-insights-v1alpha2-DataGatherList[`DataGatherList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a DataGather + + +.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:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 201 - Created +| xref:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 202 - Accepted +| xref:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/insights.openshift.io/v1alpha2/datagathers/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the DataGather +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a DataGather + + +.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 DataGather + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified DataGather + + +.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:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified DataGather + + +.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:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 201 - Created +| xref:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/insights.openshift.io/v1alpha2/datagathers/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the DataGather +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified DataGather + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified DataGather + + +.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:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified DataGather + + +.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:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 201 - Created +| xref:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`DataGather`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/monitoring_apis/monitoring-apis-index.adoc b/rest_api/monitoring_apis/monitoring-apis-index.adoc index f74b80b423..a418118b09 100644 --- a/rest_api/monitoring_apis/monitoring-apis-index.adoc +++ b/rest_api/monitoring_apis/monitoring-apis-index.adoc @@ -77,6 +77,19 @@ https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentati Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- +Type:: + `object` + +== DataGather [insights.openshift.io/v1alpha2] + +Description:: ++ +-- +DataGather provides data gather configuration options and status for the particular Insights data gathering. + +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` 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 d403b1a7c6..01225f2de8 100644 --- a/rest_api/monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc @@ -410,12 +410,30 @@ If empty, Prometheus uses the default value (e.g. `/metrics`). | `string` | port defines the `Pod` port name which exposes the endpoint. +If the pod doesn't expose a port with the same name, it will result +in no targets being discovered. + +If a `Pod` has multiple `Port`s with the same name (which is not +recommended), one target instance per unique port number will be +generated. + It takes precedence over the `portNumber` and `targetPort` fields. | `portNumber` | `integer` | portNumber defines the `Pod` port number which exposes the endpoint. +The `Pod` must declare the specified `Port` in its spec or the +target will be dropped by Prometheus. + +This cannot be used to enable scraping of an undeclared port. +To scrape targets on a port which isn't exposed, you need to use +relabeling to override the `__address__` label (but beware of +duplicate targets if the `Pod` has other declared ports). + +In practice Prometheus will select targets for which the +matches the target's __meta_kubernetes_pod_container_port_number. + | `proxyConnectHeader` | `object` | proxyConnectHeader optionally specifies headers to send to @@ -463,11 +481,6 @@ More info: https://prometheus.io/docs/prometheus/latest/configuration/configurat | `string` | scheme defines the HTTP scheme to use for scraping. -`http` and `https` are the expected values unless you rewrite the -`__scheme__` label via relabeling. - -If empty, Prometheus uses the default value `http`. - | `scrapeTimeout` | `string` | scrapeTimeout defines the timeout after which Prometheus considers the scrape to be failed. 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 c5837632c2..35fed6591f 100644 --- a/rest_api/monitoring_apis/probe-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/probe-monitoring-coreos-com-v1.adoc @@ -1180,13 +1180,15 @@ It requires Prometheus >= v2.43.0, Alertmanager >= v0.25.0 or Thanos >= v0.32.0. | `scheme` | `string` -| scheme defines the HTTP scheme to use for scraping. -`http` and `https` are the expected values unless you rewrite the `__scheme__` label via relabeling. -If empty, Prometheus uses the default value `http`. +| scheme defines the HTTP scheme to use when scraping the prober. | `url` | `string` -| url defines the mandatory URL of the prober. +| url defines the address of the prober. + +Unlike what the name indicates, the value should be in the form of +`address:port` without any scheme which should be specified in the +`scheme` field. |=== === .spec.prober.proxyConnectHeader 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 2e0e02e4c6..981d6f3b96 100644 --- a/rest_api/monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc @@ -3173,7 +3173,7 @@ More info: https://prometheus.io/docs/prometheus/latest/configuration/configurat | `scheme` | `string` -| scheme to use when firing alerts. +| scheme defines the HTTP scheme to use when sending alerts. | `sigv4` | `object` @@ -3633,7 +3633,7 @@ variable `AWS_SECRET_ACCESS_KEY` is used. | `useFIPSSTSEndpoint` | `boolean` -| useFIPSSTSEndpoint defines FIPS mode for AWS STS endpoint. +| useFIPSSTSEndpoint defines the FIPS mode for the AWS STS endpoint. It requires Prometheus >= v2.54.0. |=== @@ -12120,6 +12120,9 @@ It requires Prometheus >= v2.54.0 or Thanos >= v0.37.0. | `object` | metadataConfig defines how to send a series metadata to the remote storage. +When the field is empty, **no metadata** is sent. But when the field is +null, metadata is sent. + | `name` | `string` | name of the remote write queue, it must be unique if specified. The @@ -12367,8 +12370,6 @@ Cannot be set at the same time as `oauth` or `sdk`. Type:: `object` -Required:: - - `clientId` @@ -12378,7 +12379,9 @@ Required:: | `clientId` | `string` -| clientId defines defines the Azure User-assigned Managed identity. +| clientId defines the Azure User-assigned Managed identity. + +For Prometheus >= 3.5.0 and Thanos >= 0.40.0, this field is allowed to be empty to support system-assigned managed identities. |=== === .spec.remoteWrite[].azureAd.oauth @@ -12589,6 +12592,9 @@ Description:: + -- metadataConfig defines how to send a series metadata to the remote storage. + +When the field is empty, **no metadata** is sent. But when the field is +null, metadata is sent. -- Type:: @@ -13360,7 +13366,7 @@ variable `AWS_SECRET_ACCESS_KEY` is used. | `useFIPSSTSEndpoint` | `boolean` -| useFIPSSTSEndpoint defines FIPS mode for AWS STS endpoint. +| useFIPSSTSEndpoint defines the FIPS mode for the AWS STS endpoint. It requires Prometheus >= v2.54.0. |=== 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 abbbe44526..6ba665db60 100644 --- a/rest_api/monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc @@ -452,12 +452,7 @@ More info: https://prometheus.io/docs/prometheus/latest/configuration/configurat | `scheme` | `string` -| scheme defines the HTTP scheme to use for scraping. - -`http` and `https` are the expected values unless you rewrite the -`__scheme__` label via relabeling. - -If empty, Prometheus uses the default value `http`. +| scheme defines the HTTP scheme to use when scraping the metrics. | `scrapeTimeout` | `string` 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 339b4e8b44..1048614155 100644 --- a/rest_api/monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc +++ b/rest_api/monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc @@ -8402,6 +8402,9 @@ It requires Prometheus >= v2.54.0 or Thanos >= v0.37.0. | `object` | metadataConfig defines how to send a series metadata to the remote storage. +When the field is empty, **no metadata** is sent. But when the field is +null, metadata is sent. + | `name` | `string` | name of the remote write queue, it must be unique if specified. The @@ -8649,8 +8652,6 @@ Cannot be set at the same time as `oauth` or `sdk`. Type:: `object` -Required:: - - `clientId` @@ -8660,7 +8661,9 @@ Required:: | `clientId` | `string` -| clientId defines defines the Azure User-assigned Managed identity. +| clientId defines the Azure User-assigned Managed identity. + +For Prometheus >= 3.5.0 and Thanos >= 0.40.0, this field is allowed to be empty to support system-assigned managed identities. |=== === .spec.remoteWrite[].azureAd.oauth @@ -8871,6 +8874,9 @@ Description:: + -- metadataConfig defines how to send a series metadata to the remote storage. + +When the field is empty, **no metadata** is sent. But when the field is +null, metadata is sent. -- Type:: @@ -9642,7 +9648,7 @@ variable `AWS_SECRET_ACCESS_KEY` is used. | `useFIPSSTSEndpoint` | `boolean` -| useFIPSSTSEndpoint defines FIPS mode for AWS STS endpoint. +| useFIPSSTSEndpoint defines the FIPS mode for the AWS STS endpoint. It requires Prometheus >= v2.54.0. |=== diff --git a/rest_api/network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc b/rest_api/network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc new file mode 100644 index 0000000000..5e22a059c3 --- /dev/null +++ b/rest_api/network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc @@ -0,0 +1,674 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="dnsnameresolver-network-openshift-io-v1alpha1"] += DNSNameResolver [network.openshift.io/v1alpha1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +DNSNameResolver stores the DNS name resolution information of a DNS name. It can be enabled by the TechPreviewNoUpgrade feature set. +It can also be enabled by the feature gate DNSNameResolver when using CustomNoUpgrade feature set. + +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` + +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 is the specification of the desired behavior of the DNSNameResolver. + +| `status` +| `object` +| status is the most recently observed status of the DNSNameResolver. + +|=== +=== .spec +Description:: ++ +-- +spec is the specification of the desired behavior of the DNSNameResolver. +-- + +Type:: + `object` + +Required:: + - `name` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is the DNS name for which the DNS name resolution information will be stored. +For a regular DNS name, only the DNS name resolution information of the regular DNS +name will be stored. For a wildcard DNS name, the DNS name resolution information +of all the DNS names that match the wildcard DNS name will be stored. +For a wildcard DNS name, the '*' will match only one label. Additionally, only a single +'*' can be used at the beginning of the wildcard DNS name. For example, '*.example.com.' +will match 'sub1.example.com.' but won't match 'sub2.sub1.example.com.' + +|=== +=== .status +Description:: ++ +-- +status is the most recently observed status of the DNSNameResolver. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `resolvedNames` +| `array` +| resolvedNames contains a list of matching DNS names and their corresponding IP addresses +along with their TTL and last DNS lookup times. + +| `resolvedNames[]` +| `object` +| DNSNameResolverResolvedName describes the details of a resolved DNS name. + +|=== +=== .status.resolvedNames +Description:: ++ +-- +resolvedNames contains a list of matching DNS names and their corresponding IP addresses +along with their TTL and last DNS lookup times. +-- + +Type:: + `array` + + + + +=== .status.resolvedNames[] +Description:: ++ +-- +DNSNameResolverResolvedName describes the details of a resolved DNS name. +-- + +Type:: + `object` + +Required:: + - `dnsName` + - `resolvedAddresses` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| conditions provide information about the state of the DNS name. +Known .status.conditions.type is: "Degraded". +"Degraded" is true when the last resolution failed for the DNS name, +and false otherwise. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +| `dnsName` +| `string` +| dnsName is the resolved DNS name matching the name field of DNSNameResolverSpec. This field can +store both regular and wildcard DNS names which match the spec.name field. When the spec.name +field contains a regular DNS name, this field will store the same regular DNS name after it is +successfully resolved. When the spec.name field contains a wildcard DNS name, each resolvedName.dnsName +will store the regular DNS names which match the wildcard DNS name and have been successfully resolved. +If the wildcard DNS name can also be successfully resolved, then this field will store the wildcard +DNS name as well. + +| `resolutionFailures` +| `integer` +| resolutionFailures keeps the count of how many consecutive times the DNS resolution failed +for the dnsName. If the DNS resolution succeeds then the field will be set to zero. Upon +every failure, the value of the field will be incremented by one. The details about the DNS +name will be removed, if the value of resolutionFailures reaches 5 and the TTL of all the +associated IP addresses have expired. + +| `resolvedAddresses` +| `array` +| resolvedAddresses gives the list of associated IP addresses and their corresponding TTLs and last +lookup times for the dnsName. + +| `resolvedAddresses[]` +| `object` +| DNSNameResolverResolvedAddress describes the details of an IP address for a resolved DNS name. + +|=== +=== .status.resolvedNames[].conditions +Description:: ++ +-- +conditions provide information about the state of the DNS name. +Known .status.conditions.type is: "Degraded". +"Degraded" is true when the last resolution failed for the DNS name, +and false otherwise. +-- + +Type:: + `array` + + + + +=== .status.resolvedNames[].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.resolvedNames[].resolvedAddresses +Description:: ++ +-- +resolvedAddresses gives the list of associated IP addresses and their corresponding TTLs and last +lookup times for the dnsName. +-- + +Type:: + `array` + + + + +=== .status.resolvedNames[].resolvedAddresses[] +Description:: ++ +-- +DNSNameResolverResolvedAddress describes the details of an IP address for a resolved DNS name. +-- + +Type:: + `object` + +Required:: + - `ip` + - `lastLookupTime` + - `ttlSeconds` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `ip` +| `string` +| ip is an IP address associated with the dnsName. The validity of the IP address expires after +lastLookupTime + ttlSeconds. To refresh the information, a DNS lookup will be performed upon +the expiration of the IP address's validity. If the information is not refreshed then it will +be removed with a grace period after the expiration of the IP address's validity. + +| `lastLookupTime` +| `string` +| lastLookupTime is the timestamp when the last DNS lookup was completed successfully. The validity of +the IP address expires after lastLookupTime + ttlSeconds. The value of this field will be updated to +the current time on a successful DNS lookup. If the information is not refreshed then it will be +removed with a grace period after the expiration of the IP address's validity. + +| `ttlSeconds` +| `integer` +| ttlSeconds is the time-to-live value of the IP address. The validity of the IP address expires after +lastLookupTime + ttlSeconds. On a successful DNS lookup the value of this field will be updated with +the current time-to-live value. If the information is not refreshed then it will be removed with a +grace period after the expiration of the IP address's validity. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/network.openshift.io/v1alpha1/dnsnameresolvers` +- `GET`: list objects of kind DNSNameResolver +* `/apis/network.openshift.io/v1alpha1/namespaces/{namespace}/dnsnameresolvers` +- `DELETE`: delete collection of DNSNameResolver +- `GET`: list objects of kind DNSNameResolver +- `POST`: create a DNSNameResolver +* `/apis/network.openshift.io/v1alpha1/namespaces/{namespace}/dnsnameresolvers/{name}` +- `DELETE`: delete a DNSNameResolver +- `GET`: read the specified DNSNameResolver +- `PATCH`: partially update the specified DNSNameResolver +- `PUT`: replace the specified DNSNameResolver +* `/apis/network.openshift.io/v1alpha1/namespaces/{namespace}/dnsnameresolvers/{name}/status` +- `GET`: read status of the specified DNSNameResolver +- `PATCH`: partially update status of the specified DNSNameResolver +- `PUT`: replace status of the specified DNSNameResolver + + +=== /apis/network.openshift.io/v1alpha1/dnsnameresolvers + + + +HTTP method:: + `GET` + +Description:: + list objects of kind DNSNameResolver + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-network-v1alpha1-DNSNameResolverList[`DNSNameResolverList`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/network.openshift.io/v1alpha1/namespaces/{namespace}/dnsnameresolvers + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of DNSNameResolver + + + + +.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 DNSNameResolver + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-network-v1alpha1-DNSNameResolverList[`DNSNameResolverList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a DNSNameResolver + + +.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/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 201 - Created +| xref:../network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 202 - Accepted +| xref:../network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/network.openshift.io/v1alpha1/namespaces/{namespace}/dnsnameresolvers/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the DNSNameResolver +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a DNSNameResolver + + +.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 DNSNameResolver + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified DNSNameResolver + + +.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/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified DNSNameResolver + + +.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/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 201 - Created +| xref:../network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/network.openshift.io/v1alpha1/namespaces/{namespace}/dnsnameresolvers/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the DNSNameResolver +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified DNSNameResolver + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified DNSNameResolver + + +.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/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified DNSNameResolver + + +.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/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 201 - Created +| xref:../network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`DNSNameResolver`] schema +| 401 - Unauthorized +| Empty +|=== + + 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 index a0dc7ea9d9..54614b5381 100644 --- a/rest_api/network_apis/gateway-gateway-networking-k8s-io-v1.adoc +++ b/rest_api/network_apis/gateway-gateway-networking-k8s-io-v1.adoc @@ -94,7 +94,7 @@ Support: Extended | `addresses[]` | `object` -| GatewayAddress describes an address that can be bound to a Gateway. +| GatewaySpecAddress describes an address that can be bound to a Gateway. | `gatewayClassName` | `string` @@ -313,14 +313,12 @@ Type:: Description:: + -- -GatewayAddress describes an address that can be bound to a Gateway. +GatewaySpecAddress describes an address that can be bound to a Gateway. -- Type:: `object` -Required:: - - `value` @@ -334,8 +332,11 @@ Required:: | `value` | `string` -| Value of the address. The validity of the values will depend -on the type and support by the controller. +| When a value is unspecified, an implementation SHOULD automatically +assign an address matching the requested type if possible. + +If an implementation does not support an empty value, they MUST set the +"Programmed" condition in status to False with a reason of "AddressNotAssigned". Examples: `1.2.3.4`, `128::1`, `my-ip-address`. diff --git a/rest_api/network_apis/network-apis-index.adoc b/rest_api/network_apis/network-apis-index.adoc index 4da36f4373..bdfbd410e1 100644 --- a/rest_api/network_apis/network-apis-index.adoc +++ b/rest_api/network_apis/network-apis-index.adoc @@ -72,6 +72,20 @@ must specify the requested private IP address (can be IPv4 or IPv6). Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- +Type:: + `object` + +== DNSNameResolver [network.openshift.io/v1alpha1] + +Description:: ++ +-- +DNSNameResolver stores the DNS name resolution information of a DNS name. It can be enabled by the TechPreviewNoUpgrade feature set. +It can also be enabled by the feature gate DNSNameResolver when using CustomNoUpgrade feature set. + +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` diff --git a/rest_api/objects/index.adoc b/rest_api/objects/index.adoc index 4ca103c8cc..f0cfdd8dff 100644 --- a/rest_api/objects/index.adoc +++ b/rest_api/objects/index.adoc @@ -9284,6 +9284,129 @@ Required:: |=== +[id="io-openshift-config-v1alpha1-BackupList"] +== io.openshift.config.v1alpha1.BackupList schema + + +Description:: ++ +-- +BackupList is a list of Backup +-- + +Type:: + `object` + +Required:: + - `items` + + +=== 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:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[`array (Backup)`] +| List of backups. 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-config-v1alpha1-ClusterMonitoringList"] +== io.openshift.config.v1alpha1.ClusterMonitoringList schema + + +Description:: ++ +-- +ClusterMonitoringList is a list of ClusterMonitoring +-- + +Type:: + `object` + +Required:: + - `items` + + +=== 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:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[`array (ClusterMonitoring)`] +| List of clustermonitorings. 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-config-v1alpha2-InsightsDataGatherList"] +== io.openshift.config.v1alpha2.InsightsDataGatherList schema + + +Description:: ++ +-- +InsightsDataGatherList is a list of InsightsDataGather +-- + +Type:: + `object` + +Required:: + - `items` + + +=== 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:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[`array (InsightsDataGather)`] +| List of insightsdatagathers. 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-console-v1-ConsoleCLIDownloadList"] == io.openshift.console.v1.ConsoleCLIDownloadList schema @@ -9694,6 +9817,47 @@ Required:: |=== +[id="io-openshift-insights-v1alpha2-DataGatherList"] +== io.openshift.insights.v1alpha2.DataGatherList schema + + +Description:: ++ +-- +DataGatherList is a list of DataGather +-- + +Type:: + `object` + +Required:: + - `items` + + +=== 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:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[`array (DataGather)`] +| List of datagathers. 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-machine-v1-ControlPlaneMachineSetList"] == io.openshift.machine.v1.ControlPlaneMachineSetList schema @@ -10227,6 +10391,88 @@ Required:: |=== +[id="io-openshift-machineconfiguration-v1alpha1-InternalReleaseImageList"] +== io.openshift.machineconfiguration.v1alpha1.InternalReleaseImageList schema + + +Description:: ++ +-- +InternalReleaseImageList is a list of InternalReleaseImage +-- + +Type:: + `object` + +Required:: + - `items` + + +=== 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/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[`array (InternalReleaseImage)`] +| List of internalreleaseimages. 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-v1alpha1-OSImageStreamList"] +== io.openshift.machineconfiguration.v1alpha1.OSImageStreamList schema + + +Description:: ++ +-- +OSImageStreamList is a list of OSImageStream +-- + +Type:: + `object` + +Required:: + - `items` + + +=== 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/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[`array (OSImageStream)`] +| List of osimagestreams. 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 @@ -10350,6 +10596,47 @@ Required:: |=== +[id="io-openshift-network-v1alpha1-DNSNameResolverList"] +== io.openshift.network.v1alpha1.DNSNameResolverList schema + + +Description:: ++ +-- +DNSNameResolverList is a list of DNSNameResolver +-- + +Type:: + `object` + +Required:: + - `items` + + +=== 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/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[`array (DNSNameResolver)`] +| List of dnsnameresolvers. 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-operator-controlplane-v1alpha1-PodNetworkConnectivityCheckList"] == io.openshift.operator.controlplane.v1alpha1.PodNetworkConnectivityCheckList schema @@ -11293,6 +11580,47 @@ Required:: |=== +[id="io-openshift-operator-v1-OLMList"] +== io.openshift.operator.v1.OLMList schema + + +Description:: ++ +-- +OLMList is a list of OLM +-- + +Type:: + `object` + +Required:: + - `items` + + +=== 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/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`array (OLM)`] +| List of olms. 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-operator-v1-OpenShiftAPIServerList"] == io.openshift.operator.v1.OpenShiftAPIServerList schema @@ -11457,6 +11785,88 @@ Required:: |=== +[id="io-openshift-operator-v1alpha1-ClusterVersionOperatorList"] +== io.openshift.operator.v1alpha1.ClusterVersionOperatorList schema + + +Description:: ++ +-- +ClusterVersionOperatorList is a list of ClusterVersionOperator +-- + +Type:: + `object` + +Required:: + - `items` + + +=== 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:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`array (ClusterVersionOperator)`] +| List of clusterversionoperators. 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-operator-v1alpha1-EtcdBackupList"] +== io.openshift.operator.v1alpha1.EtcdBackupList schema + + +Description:: ++ +-- +EtcdBackupList is a list of EtcdBackup +-- + +Type:: + `object` + +Required:: + - `items` + + +=== 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:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`array (EtcdBackup)`] +| List of etcdbackups. 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-operator-v1alpha1-ImageContentSourcePolicyList"] == io.openshift.operator.v1alpha1.ImageContentSourcePolicyList schema @@ -11785,47 +12195,6 @@ Required:: |=== -[id="io-operatorframework-olm-v1-ClusterExtensionRevisionList"] -== io.operatorframework.olm.v1.ClusterExtensionRevisionList schema - - -Description:: -+ --- -ClusterExtensionRevisionList is a list of ClusterExtensionRevision --- - -Type:: - `object` - -Required:: - - `items` - - -=== 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/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`array (ClusterExtensionRevision)`] -| List of clusterextensionrevisions. 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 @@ -11949,47 +12318,6 @@ Required:: |=== -[id="io-x-k8s-cluster-ipam-v1beta1-IPAddressList"] -== io.x-k8s.cluster.ipam.v1beta1.IPAddressList schema - - -Description:: -+ --- -IPAddressList is a list of IPAddress --- - -Type:: - `object` - -Required:: - - `items` - - -=== 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:../cluster_apis/ipaddress-ipam-cluster-x-k8s-io-v1beta1.adoc#ipaddress-ipam-cluster-x-k8s-io-v1beta1[`array (IPAddress)`] -| List of ipaddresses. 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-AdminPolicyBasedExternalRouteList"] == org.ovn.k8s.v1.AdminPolicyBasedExternalRouteList schema 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 b66851b130..fac8da5d5c 100644 --- a/rest_api/operator_apis/clustercsidriver-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/clustercsidriver-operator-openshift-io-v1.adoc @@ -470,6 +470,18 @@ Snapshots for VSAN can not be disabled using this parameter. It overrides GlobalMaxSnapshotsPerBlockVolume if set, while it falls back to the global constraint if unset. Snapshots for VVOL can not be disabled using this parameter. +| `maxAllowedBlockVolumesPerNode` +| `integer` +| maxAllowedBlockVolumesPerNode is an optional configuration parameter that allows setting a custom value for the +limit of the number of PersistentVolumes attached to a node. In vSphere version 7 this limit was set to 59 by +default, however in vSphere version 8 this limit was increased to 255. +Before increasing this value above 59 the cluster administrator needs to ensure that every node forming the +cluster is updated to ESXi version 8 or higher and that all nodes are running the same version. +The limit must be between 1 and 255, which matches the vSphere version 8 maximum. +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 59, which matches the limit for vSphere version 7. + | `topologyCategories` | `array (string)` | topologyCategories indicates tag categories with which diff --git a/rest_api/operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc b/rest_api/operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc new file mode 100644 index 0000000000..ebd14cd739 --- /dev/null +++ b/rest_api/operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc @@ -0,0 +1,440 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="clusterversionoperator-operator-openshift-io-v1alpha1"] += ClusterVersionOperator [operator.openshift.io/v1alpha1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +ClusterVersionOperator holds cluster-wide information about the Cluster Version Operator. + +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` + +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 specification of the desired behavior of the Cluster Version Operator. + +| `status` +| `object` +| status is the most recently observed status of the Cluster Version Operator. + +|=== +=== .spec +Description:: ++ +-- +spec is the specification of the desired behavior of the Cluster Version Operator. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `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". + +|=== +=== .status +Description:: ++ +-- +status is the most recently observed status of the Cluster Version Operator. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `observedGeneration` +| `integer` +| observedGeneration represents the most recent generation observed by the operator and specifies the version of +the spec field currently being synced. + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/operator.openshift.io/v1alpha1/clusterversionoperators` +- `DELETE`: delete collection of ClusterVersionOperator +- `GET`: list objects of kind ClusterVersionOperator +- `POST`: create a ClusterVersionOperator +* `/apis/operator.openshift.io/v1alpha1/clusterversionoperators/{name}` +- `DELETE`: delete a ClusterVersionOperator +- `GET`: read the specified ClusterVersionOperator +- `PATCH`: partially update the specified ClusterVersionOperator +- `PUT`: replace the specified ClusterVersionOperator +* `/apis/operator.openshift.io/v1alpha1/clusterversionoperators/{name}/status` +- `GET`: read status of the specified ClusterVersionOperator +- `PATCH`: partially update status of the specified ClusterVersionOperator +- `PUT`: replace status of the specified ClusterVersionOperator + + +=== /apis/operator.openshift.io/v1alpha1/clusterversionoperators + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of ClusterVersionOperator + + + + +.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 ClusterVersionOperator + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-operator-v1alpha1-ClusterVersionOperatorList[`ClusterVersionOperatorList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create a ClusterVersionOperator + + +.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:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 201 - Created +| xref:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 202 - Accepted +| xref:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/operator.openshift.io/v1alpha1/clusterversionoperators/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ClusterVersionOperator +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete a ClusterVersionOperator + + +.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 ClusterVersionOperator + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified ClusterVersionOperator + + +.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:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified ClusterVersionOperator + + +.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:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 201 - Created +| xref:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/operator.openshift.io/v1alpha1/clusterversionoperators/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the ClusterVersionOperator +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified ClusterVersionOperator + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified ClusterVersionOperator + + +.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:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified ClusterVersionOperator + + +.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:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 201 - Created +| xref:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[`ClusterVersionOperator`] schema +| 401 - Unauthorized +| Empty +|=== + + 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 537a7fe446..056e6380e1 100644 --- a/rest_api/operator_apis/console-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/console-operator-openshift-io-v1.adoc @@ -940,9 +940,6 @@ Type:: | `object` | fieldSelector describes the limitation on access based on field. It can only limit access, not broaden it. -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). - | `group` | `string` | Group is the API Group of the Resource. "*" means all. @@ -951,9 +948,6 @@ This field is alpha-level. To use this field, you must enable the | `object` | labelSelector describes the limitation on access based on labels. It can only limit access, not broaden it. -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). - | `name` | `string` | Name is the name of the resource being requested for a "get" or deleted for a "delete". "" (empty) means all. @@ -987,9 +981,6 @@ Description:: + -- fieldSelector describes the limitation on access based on field. It can only limit access, not broaden it. - -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). -- Type:: @@ -1082,9 +1073,6 @@ Description:: + -- labelSelector describes the limitation on access based on labels. It can only limit access, not broaden it. - -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). -- Type:: @@ -1206,9 +1194,6 @@ Type:: | `object` | fieldSelector describes the limitation on access based on field. It can only limit access, not broaden it. -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). - | `group` | `string` | Group is the API Group of the Resource. "*" means all. @@ -1217,9 +1202,6 @@ This field is alpha-level. To use this field, you must enable the | `object` | labelSelector describes the limitation on access based on labels. It can only limit access, not broaden it. -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). - | `name` | `string` | Name is the name of the resource being requested for a "get" or deleted for a "delete". "" (empty) means all. @@ -1253,9 +1235,6 @@ Description:: + -- fieldSelector describes the limitation on access based on field. It can only limit access, not broaden it. - -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). -- Type:: @@ -1348,9 +1327,6 @@ Description:: + -- labelSelector describes the limitation on access based on labels. It can only limit access, not broaden it. - -This field is alpha-level. To use this field, you must enable the -`AuthorizeWithSelectors` feature gate (disabled by default). -- Type:: 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 d086468103..df0419c45b 100644 --- a/rest_api/operator_apis/etcd-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/etcd-operator-openshift-io-v1.adoc @@ -67,6 +67,12 @@ Type:: |=== | Property | Type | Description +| `backendQuotaGiB` +| `integer` +| backendQuotaGiB sets the etcd backend storage size limit in gibibytes. +The value should be an integer not less than 8 and not more than 32. +When not specified, the default value is 8. + | `controlPlaneHardwareSpeed` | `string` | HardwareSpeed allows user to change the etcd tuning profile which configures diff --git a/rest_api/operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc b/rest_api/operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc new file mode 100644 index 0000000000..e0c8183d81 --- /dev/null +++ b/rest_api/operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc @@ -0,0 +1,550 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="etcdbackup-operator-openshift-io-v1alpha1"] += EtcdBackup [operator.openshift.io/v1alpha1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +# EtcdBackup provides configuration options and status for a one-time backup attempt of the etcd cluster + +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` + +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 holds user settable values for configuration + +| `status` +| `object` +| status holds observed values from the cluster. They may not be overridden. + +|=== +=== .spec +Description:: ++ +-- +spec holds user settable values for configuration +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `pvcName` +| `string` +| pvcName specifies the name of the PersistentVolumeClaim (PVC) which binds a PersistentVolume where the +etcd backup file would be saved +The PVC itself must always be created in the "openshift-etcd" namespace +If the PVC is left unspecified "" then the platform will choose a reasonable default location to save the backup. +In the future this would be backups saved across the control-plane master nodes. + +|=== +=== .status +Description:: ++ +-- +status holds observed values from the cluster. They may not be overridden. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `backupJob` +| `object` +| backupJob is the reference to the Job that executes the backup. +Optional + +| `conditions` +| `array` +| conditions provide details on the status of the etcd backup job. + +| `conditions[]` +| `object` +| Condition contains details for one aspect of the current state of this API Resource. + +|=== +=== .status.backupJob +Description:: ++ +-- +backupJob is the reference to the Job that executes the backup. +Optional +-- + +Type:: + `object` + +Required:: + - `name` + - `namespace` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `name` +| `string` +| name is the name of the Job. +Required + +| `namespace` +| `string` +| namespace is the namespace of the Job. +this is always expected to be "openshift-etcd" since the user provided PVC +is also required to be in "openshift-etcd" +Required + +|=== +=== .status.conditions +Description:: ++ +-- +conditions provide details on the status of the etcd backup job. +-- + +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/operator.openshift.io/v1alpha1/etcdbackups` +- `DELETE`: delete collection of EtcdBackup +- `GET`: list objects of kind EtcdBackup +- `POST`: create an EtcdBackup +* `/apis/operator.openshift.io/v1alpha1/etcdbackups/{name}` +- `DELETE`: delete an EtcdBackup +- `GET`: read the specified EtcdBackup +- `PATCH`: partially update the specified EtcdBackup +- `PUT`: replace the specified EtcdBackup +* `/apis/operator.openshift.io/v1alpha1/etcdbackups/{name}/status` +- `GET`: read status of the specified EtcdBackup +- `PATCH`: partially update status of the specified EtcdBackup +- `PUT`: replace status of the specified EtcdBackup + + +=== /apis/operator.openshift.io/v1alpha1/etcdbackups + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of EtcdBackup + + + + +.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 EtcdBackup + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-operator-v1alpha1-EtcdBackupList[`EtcdBackupList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create an EtcdBackup + + +.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:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 201 - Created +| xref:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 202 - Accepted +| xref:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/operator.openshift.io/v1alpha1/etcdbackups/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the EtcdBackup +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete an EtcdBackup + + +.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 EtcdBackup + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified EtcdBackup + + +.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:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified EtcdBackup + + +.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:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 201 - Created +| xref:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/operator.openshift.io/v1alpha1/etcdbackups/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the EtcdBackup +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified EtcdBackup + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified EtcdBackup + + +.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:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified EtcdBackup + + +.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:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 201 - Created +| xref:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[`EtcdBackup`] schema +| 401 - Unauthorized +| Empty +|=== + + 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 548ee1d84b..8147309cfd 100644 --- a/rest_api/operator_apis/ingresscontroller-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/ingresscontroller-operator-openshift-io-v1.adoc @@ -83,6 +83,44 @@ Type:: certificates, which can be used to enable mutual TLS for edge-terminated and reencrypt routes. +| `closedClientConnectionPolicy` +| `string` +| closedClientConnectionPolicy controls how the IngressController +behaves when the client closes the TCP connection while the TLS +handshake or HTTP request is in progress. This option maps directly +to HAProxy’s "abortonclose" option. + +Valid values are: "Abort" and "Continue". +The default value is "Continue". + +When set to "Abort", the router will stop processing the TLS handshake +if it is in progress, and it will not send an HTTP request to the backend server +if the request has not yet been sent when the client closes the connection. + +When set to "Continue", the router will complete the TLS handshake +if it is in progress, or send an HTTP request to the backend server +and wait for the backend server's response, regardless of +whether the client has closed the connection. + +Setting "Abort" can help free CPU resources otherwise spent on TLS computation +for connections the client has already closed, and can reduce request queue +size, thereby reducing the load on saturated backend servers. + +Important Considerations: + + - The default policy ("Continue") is HTTP-compliant, and requests + for aborted client connections will still be served. + Use the "Continue" policy to allow a client to send a request + and then immediately close its side of the connection while + still receiving a response on the half-closed connection. + + - When clients use keep-alive connections, the most common case for premature + closure is when the user wants to cancel the transfer or when a timeout + occurs. In that case, the "Abort" policy may be used to reduce resource consumption. + + - Using RSA keys larger than 2048 bits can significantly slow down + TLS computations. Consider using the "Abort" policy to reduce CPU usage. + | `defaultCertificate` | `object` | defaultCertificate is a reference to a secret containing the default @@ -128,6 +166,19 @@ updated. If empty, defaults to ingress.config.openshift.io/cluster .spec.domain. +The domain value must be a valid DNS name. It must consist of lowercase +alphanumeric characters, '-' or '.', and each label must start and end +with an alphanumeric character and not exceed 63 characters. Maximum +length of a valid DNS domain is 253 characters. + +The implementation may add a prefix such as "router-default." to the domain +when constructing the router canonical hostname. To ensure the resulting +hostname does not exceed the DNS maximum length of 253 characters, +the domain length is additionally validated at the IngressController object +level. For the maximum length of the domain value itself, the shortest +possible variant of the prefix and the ingress controller name was considered +for example "router-a." + | `endpointPublishingStrategy` | `object` | endpointPublishingStrategy is used to publish the ingress controller @@ -214,9 +265,9 @@ following occurs: 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). + - HAProxy's `timeout http-keep-alive` duration expires. + By default this is 300 seconds, but it can be changed + using httpKeepAliveTimeout tuning option. - The client's keep-alive timeout expires, causing the client to close the connection. @@ -2729,6 +2780,29 @@ Currently the default healthCheckInterval value is 5s. Currently the minimum allowed value is 1s and the maximum allowed value is 2147483647ms (24.85 days). Both are subject to change over time. +| `httpKeepAliveTimeout` +| `string` +| httpKeepAliveTimeout defines the maximum allowed time to wait for +a new HTTP request to appear on a connection from the client to the router. + +This field expects an unsigned duration string of a decimal number, with optional +fraction and a unit suffix, e.g. "300ms", "1.5s" or "2m45s". +Valid time units are "ms", "s", "m". +The allowed range is from 1 millisecond to 15 minutes. + +When omitted, this means the user has no opinion and the platform is left +to choose a reasonable default. This default is subject to change over time. +The current default is 300s. + +Low values (tens of milliseconds or less) can cause clients to close and reopen connections +for each request, leading to reduced connection sharing. +For HTTP/2, special care should be taken with low values. +A few seconds is a reasonable starting point to avoid holding idle connections open +while still allowing subsequent requests to reuse the connection. + +High values (minutes or more) favor connection reuse but may cause idle +connections to linger longer. + | `maxConnections` | `integer` | maxConnections defines the maximum number of simultaneous 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 dc1dd20a25..f433b8a948 100644 --- a/rest_api/operator_apis/kubeapiserver-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/kubeapiserver-operator-openshift-io-v1.adoc @@ -67,6 +67,17 @@ Type:: |=== | Property | Type | Description +| `eventTTLMinutes` +| `integer` +| eventTTLMinutes specifies the amount of time that the events are stored before being deleted. +The TTL is allowed between 5 minutes minimum up to a maximum of 180 minutes (3 hours). + +Lowering this value will reduce the storage required in etcd. Note that this setting will only apply +to new events being created and will not update existing events. + +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 value is 3h (180 minutes). + | `failedRevisionLimit` | `integer` | failedRevisionLimit is the number of failed static pod installer revisions to keep on disk and in the api 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 116d9cacb3..9ba9f99f40 100644 --- a/rest_api/operator_apis/machineconfiguration-operator-openshift-io-v1.adoc +++ b/rest_api/operator_apis/machineconfiguration-operator-openshift-io-v1.adoc @@ -67,6 +67,16 @@ Type:: |=== | Property | Type | Description +| `bootImageSkewEnforcement` +| `object` +| bootImageSkewEnforcement allows an admin to configure how boot image version skew is +enforced on the cluster. +When omitted, this will default to Automatic for clusters that support automatic boot image updates. +For clusters that do not support automatic boot image updates, cluster upgrades will be disabled until +a skew enforcement mode has been specified. +When version skew is being enforced, cluster upgrades will be disabled until the version skew is deemed +acceptable for the current release payload. + | `failedRevisionLimit` | `integer` | failedRevisionLimit is the number of failed static pod installer revisions to keep on disk and in the api @@ -78,6 +88,15 @@ Type:: This provides a mechanism to kick a previously failed deployment and provide a reason why you think it will work this time instead of failing again on the same config. +| `irreconcilableValidationOverrides` +| `object` +| irreconcilableValidationOverrides is an optional field that can used to make changes to a MachineConfig that +cannot be applied to existing nodes. +When specified, the fields configured with validation overrides will no longer reject changes to those +respective fields due to them not being able to be applied to existing nodes. +Only newly provisioned nodes will have these configurations applied. +Existing nodes will report observed configuration differences in their MachineConfigNode status. + | `logLevel` | `string` | logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a @@ -133,6 +152,135 @@ Misuse of this field could lead to unexpected behavior or conflict with other co 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. +|=== +=== .spec.bootImageSkewEnforcement +Description:: ++ +-- +bootImageSkewEnforcement allows an admin to configure how boot image version skew is +enforced on the cluster. +When omitted, this will default to Automatic for clusters that support automatic boot image updates. +For clusters that do not support automatic boot image updates, cluster upgrades will be disabled until +a skew enforcement mode has been specified. +When version skew is being enforced, cluster upgrades will be disabled until the version skew is deemed +acceptable for the current release payload. +-- + +Type:: + `object` + +Required:: + - `mode` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `manual` +| `object` +| manual describes the current boot image of the cluster. +This should be set to the oldest boot image used amongst all machine resources in the cluster. +This must include either the RHCOS version of the boot image or the OCP release version which shipped with that +RHCOS boot image. +Required when mode is set to "Manual" and forbidden otherwise. + +| `mode` +| `string` +| mode determines the underlying behavior of skew enforcement mechanism. +Valid values are Manual and None. +Manual means that the cluster admin is expected to perform manual boot image updates and store the OCP +& RHCOS version associated with the last boot image update in the manual field. +In Manual mode, the MCO will prevent upgrades when the boot image skew exceeds the +skew limit described by the release image. +None means that the MCO will no longer monitor the boot image skew. This may affect +the cluster's ability to scale. +This field is required. + +|=== +=== .spec.bootImageSkewEnforcement.manual +Description:: ++ +-- +manual describes the current boot image of the cluster. +This should be set to the oldest boot image used amongst all machine resources in the cluster. +This must include either the RHCOS version of the boot image or the OCP release version which shipped with that +RHCOS boot image. +Required when mode is set to "Manual" and forbidden otherwise. +-- + +Type:: + `object` + +Required:: + - `mode` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `mode` +| `string` +| mode is used to configure which boot image field is defined in Manual mode. +Valid values are OCPVersion and RHCOSVersion. +OCPVersion means that the cluster admin is expected to set the OCP version associated with the last boot image update +in the OCPVersion field. +RHCOSVersion means that the cluster admin is expected to set the RHCOS version associated with the last boot image update +in the RHCOSVersion field. +This field is required. + +| `ocpVersion` +| `string` +| ocpVersion provides a string which represents the OCP version of the boot image. +This field must match the OCP semver compatible format of x.y.z. This field must be between +5 and 10 characters long. +Required when mode is set to "OCPVersion" and forbidden otherwise. + +| `rhcosVersion` +| `string` +| rhcosVersion provides a string which represents the RHCOS version of the boot image +This field must match rhcosVersion formatting of [major].[minor].[datestamp(YYYYMMDD)]-[buildnumber] or the legacy +format of [major].[minor].[timestamp(YYYYMMDDHHmm)]-[buildnumber]. This field must be between +14 and 21 characters long. +Required when mode is set to "RHCOSVersion" and forbidden otherwise. + +|=== +=== .spec.irreconcilableValidationOverrides +Description:: ++ +-- +irreconcilableValidationOverrides is an optional field that can used to make changes to a MachineConfig that +cannot be applied to existing nodes. +When specified, the fields configured with validation overrides will no longer reject changes to those +respective fields due to them not being able to be applied to existing nodes. +Only newly provisioned nodes will have these configurations applied. +Existing nodes will report observed configuration differences in their MachineConfigNode status. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `storage` +| `array (string)` +| storage can be used to allow making irreconcilable changes to the selected sections under the +`spec.config.storage` field of MachineConfig CRs +It must have at least one item, may not exceed 3 items and must not contain duplicates. +Allowed element values are "Disks", "FileSystems", "Raid" and omitted. +When contains "Disks" changes to the `spec.config.storage.disks` section of MachineConfig CRs are allowed. +When contains "FileSystems" changes to the `spec.config.storage.filesystems` section of MachineConfig CRs are allowed. +When contains "Raid" changes to the `spec.config.storage.raid` section of MachineConfig CRs are allowed. +When omitted changes to the `spec.config.storage` section are forbidden. + |=== === .spec.managedBootImages Description:: @@ -896,6 +1044,15 @@ Type:: |=== | Property | Type | Description +| `bootImageSkewEnforcementStatus` +| `object` +| bootImageSkewEnforcementStatus reflects what the latest cluster-validated boot image skew enforcement +configuration is and will be used by Machine Config Controller while performing boot image skew enforcement. +When omitted, the MCO has no knowledge of how to enforce boot image skew. When the MCO does not know how +boot image skew should be enforced, cluster upgrades will be blocked until it can either automatically +determine skew enforcement or there is an explicit skew enforcement configuration provided in the +spec.bootImageSkewEnforcement field. + | `conditions` | `array` | conditions is a list of conditions and their status @@ -918,6 +1075,141 @@ and will be used by the Machine Config Daemon during future node updates. | `integer` | observedGeneration is the last generation change you've dealt with +|=== +=== .status.bootImageSkewEnforcementStatus +Description:: ++ +-- +bootImageSkewEnforcementStatus reflects what the latest cluster-validated boot image skew enforcement +configuration is and will be used by Machine Config Controller while performing boot image skew enforcement. +When omitted, the MCO has no knowledge of how to enforce boot image skew. When the MCO does not know how +boot image skew should be enforced, cluster upgrades will be blocked until it can either automatically +determine skew enforcement or there is an explicit skew enforcement configuration provided in the +spec.bootImageSkewEnforcement field. +-- + +Type:: + `object` + +Required:: + - `mode` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `automatic` +| `object` +| automatic describes the current boot image of the cluster. +This will be populated by the MCO when performing boot image updates. This value will be compared against +the cluster's skew limit to determine skew compliance. +Required when mode is set to "Automatic" and forbidden otherwise. + +| `manual` +| `object` +| manual describes the current boot image of the cluster. +This will be populated by the MCO using the values provided in the spec.bootImageSkewEnforcement.manual field. +This value will be compared against the cluster's skew limit to determine skew compliance. +Required when mode is set to "Manual" and forbidden otherwise. + +| `mode` +| `string` +| mode determines the underlying behavior of skew enforcement mechanism. +Valid values are Automatic, Manual and None. +Automatic means that the MCO will perform boot image updates and store the +OCP & RHCOS version associated with the last boot image update in the automatic field. +Manual means that the cluster admin is expected to perform manual boot image updates and store the OCP +& RHCOS version associated with the last boot image update in the manual field. +In Automatic and Manual mode, the MCO will prevent upgrades when the boot image skew exceeds the +skew limit described by the release image. +None means that the MCO will no longer monitor the boot image skew. This may affect +the cluster's ability to scale. +This field is required. + +|=== +=== .status.bootImageSkewEnforcementStatus.automatic +Description:: ++ +-- +automatic describes the current boot image of the cluster. +This will be populated by the MCO when performing boot image updates. This value will be compared against +the cluster's skew limit to determine skew compliance. +Required when mode is set to "Automatic" and forbidden otherwise. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `ocpVersion` +| `string` +| ocpVersion provides a string which represents the OCP version of the boot image. +This field must match the OCP semver compatible format of x.y.z. This field must be between +5 and 10 characters long. + +| `rhcosVersion` +| `string` +| rhcosVersion provides a string which represents the RHCOS version of the boot image +This field must match rhcosVersion formatting of [major].[minor].[datestamp(YYYYMMDD)]-[buildnumber] or the legacy +format of [major].[minor].[timestamp(YYYYMMDDHHmm)]-[buildnumber]. This field must be between +14 and 21 characters long. + +|=== +=== .status.bootImageSkewEnforcementStatus.manual +Description:: ++ +-- +manual describes the current boot image of the cluster. +This will be populated by the MCO using the values provided in the spec.bootImageSkewEnforcement.manual field. +This value will be compared against the cluster's skew limit to determine skew compliance. +Required when mode is set to "Manual" and forbidden otherwise. +-- + +Type:: + `object` + +Required:: + - `mode` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `mode` +| `string` +| mode is used to configure which boot image field is defined in Manual mode. +Valid values are OCPVersion and RHCOSVersion. +OCPVersion means that the cluster admin is expected to set the OCP version associated with the last boot image update +in the OCPVersion field. +RHCOSVersion means that the cluster admin is expected to set the RHCOS version associated with the last boot image update +in the RHCOSVersion field. +This field is required. + +| `ocpVersion` +| `string` +| ocpVersion provides a string which represents the OCP version of the boot image. +This field must match the OCP semver compatible format of x.y.z. This field must be between +5 and 10 characters long. +Required when mode is set to "OCPVersion" and forbidden otherwise. + +| `rhcosVersion` +| `string` +| rhcosVersion provides a string which represents the RHCOS version of the boot image +This field must match rhcosVersion formatting of [major].[minor].[datestamp(YYYYMMDD)]-[buildnumber] or the legacy +format of [major].[minor].[timestamp(YYYYMMDDHHmm)]-[buildnumber]. This field must be between +14 and 21 characters long. +Required when mode is set to "RHCOSVersion" and forbidden otherwise. + |=== === .status.conditions Description:: diff --git a/rest_api/operator_apis/operator-apis-index.adoc b/rest_api/operator_apis/operator-apis-index.adoc index 0f0a0732e9..8f17300af5 100644 --- a/rest_api/operator_apis/operator-apis-index.adoc +++ b/rest_api/operator_apis/operator-apis-index.adoc @@ -30,6 +30,19 @@ CloudCredential provides a means to configure an operator to manage CredentialsR Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- +Type:: + `object` + +== ClusterVersionOperator [operator.openshift.io/v1alpha1] + +Description:: ++ +-- +ClusterVersionOperator holds cluster-wide information about the Cluster Version Operator. + +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` @@ -163,6 +176,19 @@ Etcd provides information to configure an operator to manage etcd. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). -- +Type:: + `object` + +== EtcdBackup [operator.openshift.io/v1alpha1] + +Description:: ++ +-- +# EtcdBackup provides configuration options and status for a one-time backup attempt of the etcd cluster + +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` diff --git a/rest_api/operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc b/rest_api/operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc index b93def1d07..d5afdafcaf 100644 --- a/rest_api/operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc +++ b/rest_api/operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc @@ -8,656 +8,9 @@ toc::[] -Description:: -+ --- -ClusterExtensionRevision is the Schema for the clusterextensionrevisions 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:: - - `revision` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lifecycleState` -| `string` -| Specifies the lifecycle state of the ClusterExtensionRevision. - -| `phases` -| `array` -| Phases are groups of objects that will be applied at the same time. -All objects in the phase will have to pass their probes in order to progress to the next phase. - -| `phases[]` -| `object` -| ClusterExtensionRevisionPhase are groups of objects that will be applied at the same time. -All objects in the a phase will have to pass their probes in order to progress to the next phase. - -| `previous` -| `array` -| Previous references previous revisions that objects can be adopted from. - -| `previous[]` -| `object` -| - -| `revision` -| `integer` -| Revision is a sequence number representing a specific revision of the ClusterExtension instance. -Must be positive. Each ClusterExtensionRevision of the same parent ClusterExtension needs to have -a unique value assigned. It is immutable after creation. The new revision number must always be previous revision +1. - -|=== -=== .spec.phases -Description:: -+ --- -Phases are groups of objects that will be applied at the same time. -All objects in the phase will have to pass their probes in order to progress to the next phase. --- - -Type:: - `array` - - - - -=== .spec.phases[] -Description:: -+ --- -ClusterExtensionRevisionPhase are groups of objects that will be applied at the same time. -All objects in the a phase will have to pass their probes in order to progress to the next phase. --- - -Type:: - `object` - -Required:: - - `name` - - `objects` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name identifies this phase. - -| `objects` -| `array` -| Objects are a list of all the objects within this phase. - -| `objects[]` -| `object` -| ClusterExtensionRevisionObject contains an object and settings for it. - -|=== -=== .spec.phases[].objects -Description:: -+ --- -Objects are a list of all the objects within this phase. --- - -Type:: - `array` - - - - -=== .spec.phases[].objects[] -Description:: -+ --- -ClusterExtensionRevisionObject contains an object and settings for it. --- - -Type:: - `object` - -Required:: - - `object` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `collisionProtection` -| `string` -| CollisionProtection controls whether OLM can adopt and modify objects -already existing on the cluster or even owned by another controller. - -| `object` -| `` -| - -|=== -=== .spec.previous -Description:: -+ --- -Previous references previous revisions that objects can be adopted from. --- - -Type:: - `array` - - - - -=== .spec.previous[] -Description:: -+ --- - --- - -Type:: - `object` - -Required:: - - `name` - - `uid` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| - -| `uid` -| `string` -| UID is a type that holds unique ID values, including UUIDs. Because we -don't ONLY use UUIDs, this is an alias to string. Being a type captures -intent and helps make sure that UIDs and names do not get conflated. - -|=== -=== .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` -| - -| `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/olm.operatorframework.io/v1/clusterextensionrevisions` -- `DELETE`: delete collection of ClusterExtensionRevision -- `GET`: list objects of kind ClusterExtensionRevision -- `POST`: create a ClusterExtensionRevision -* `/apis/olm.operatorframework.io/v1/clusterextensionrevisions/{name}` -- `DELETE`: delete a ClusterExtensionRevision -- `GET`: read the specified ClusterExtensionRevision -- `PATCH`: partially update the specified ClusterExtensionRevision -- `PUT`: replace the specified ClusterExtensionRevision -* `/apis/olm.operatorframework.io/v1/clusterextensionrevisions/{name}/status` -- `GET`: read status of the specified ClusterExtensionRevision -- `PATCH`: partially update status of the specified ClusterExtensionRevision -- `PUT`: replace status of the specified ClusterExtensionRevision - - -=== /apis/olm.operatorframework.io/v1/clusterextensionrevisions - - - -HTTP method:: - `DELETE` - -Description:: - delete collection of ClusterExtensionRevision - - - - -.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 ClusterExtensionRevision - - - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#io-operatorframework-olm-v1-ClusterExtensionRevisionList[`ClusterExtensionRevisionList`] schema -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterExtensionRevision - - -.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/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 201 - Created -| xref:../operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 202 - Accepted -| xref:../operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/olm.operatorframework.io/v1/clusterextensionrevisions/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterExtensionRevision -|=== - - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterExtensionRevision - - -.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 ClusterExtensionRevision - - - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterExtensionRevision - - -.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/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterExtensionRevision - - -.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/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 201 - Created -| xref:../operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/olm.operatorframework.io/v1/clusterextensionrevisions/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterExtensionRevision -|=== - - -HTTP method:: - `GET` - -Description:: - read status of the specified ClusterExtensionRevision - - - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ClusterExtensionRevision - - -.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/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ClusterExtensionRevision - - -.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/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 201 - Created -| xref:../operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[`ClusterExtensionRevision`] schema -| 401 - Unauthorized -| Empty -|=== diff --git a/rest_api/operatorhub_apis/olm-operator-openshift-io-v1.adoc b/rest_api/operatorhub_apis/olm-operator-openshift-io-v1.adoc new file mode 100644 index 0000000000..0dc2f4fb03 --- /dev/null +++ b/rest_api/operatorhub_apis/olm-operator-openshift-io-v1.adoc @@ -0,0 +1,607 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="olm-operator-openshift-io-v1"] += OLM [operator.openshift.io/v1] +:toc: macro +:toc-title: + +toc::[] + + +Description:: ++ +-- +OLM provides information to configure an operator to manage the OLM controllers + +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 holds user settable values for configuration + +| `status` +| `object` +| status holds observed values from the cluster. They may not be overridden. + +|=== +=== .spec +Description:: ++ +-- +spec holds user settable values for configuration +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `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". + +| `managementState` +| `string` +| managementState indicates whether and how the operator should manage the component + +| `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 + +| `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". + +| `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. + +|=== +=== .status +Description:: ++ +-- +status holds observed values from the cluster. They may not be overridden. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `conditions` +| `array` +| conditions is a list of conditions and their status + +| `conditions[]` +| `object` +| OperatorCondition is just the standard condition fields. + +| `generations` +| `array` +| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. + +| `generations[]` +| `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 + +| `readyReplicas` +| `integer` +| readyReplicas indicates how many replicas are ready and at the desired state + +| `version` +| `string` +| version is the level this availability applies to + +|=== +=== .status.conditions +Description:: ++ +-- +conditions is a list of conditions and their status +-- + +Type:: + `array` + + + + +=== .status.conditions[] +Description:: ++ +-- +OperatorCondition is just the standard condition fields. +-- + +Type:: + `object` + +Required:: + - `lastTransitionTime` + - `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` +| + +| `reason` +| `string` +| + +| `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 +Description:: ++ +-- +generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. +-- + +Type:: + `array` + + + + +=== .status.generations[] +Description:: ++ +-- +GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. +-- + +Type:: + `object` + +Required:: + - `group` + - `name` + - `namespace` + - `resource` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `group` +| `string` +| group is the group of the thing you're tracking + +| `hash` +| `string` +| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps + +| `lastGeneration` +| `integer` +| lastGeneration is the last generation of the workload controller involved + +| `name` +| `string` +| name is the name of the thing you're tracking + +| `namespace` +| `string` +| namespace is where the thing you're tracking is + +| `resource` +| `string` +| resource is the resource type of the thing you're tracking + +|=== + +== API endpoints + +The following API endpoints are available: + +* `/apis/operator.openshift.io/v1/olms` +- `DELETE`: delete collection of OLM +- `GET`: list objects of kind OLM +- `POST`: create an OLM +* `/apis/operator.openshift.io/v1/olms/{name}` +- `DELETE`: delete an OLM +- `GET`: read the specified OLM +- `PATCH`: partially update the specified OLM +- `PUT`: replace the specified OLM +* `/apis/operator.openshift.io/v1/olms/{name}/status` +- `GET`: read status of the specified OLM +- `PATCH`: partially update status of the specified OLM +- `PUT`: replace status of the specified OLM + + +=== /apis/operator.openshift.io/v1/olms + + + +HTTP method:: + `DELETE` + +Description:: + delete collection of OLM + + + + +.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 OLM + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../objects/index.adoc#io-openshift-operator-v1-OLMList[`OLMList`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `POST` + +Description:: + create an OLM + + +.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/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 201 - Created +| xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 202 - Accepted +| xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/operator.openshift.io/v1/olms/{name} + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the OLM +|=== + + +HTTP method:: + `DELETE` + +Description:: + delete an OLM + + +.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 OLM + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update the specified OLM + + +.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/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace the specified OLM + + +.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/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 201 - Created +| xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 401 - Unauthorized +| Empty +|=== + + +=== /apis/operator.openshift.io/v1/olms/{name}/status + +.Global path parameters +[cols="1,1,2",options="header"] +|=== +| Parameter | Type | Description +| `name` +| `string` +| name of the OLM +|=== + + +HTTP method:: + `GET` + +Description:: + read status of the specified OLM + + + + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PATCH` + +Description:: + partially update status of the specified OLM + + +.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/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 401 - Unauthorized +| Empty +|=== + +HTTP method:: + `PUT` + +Description:: + replace status of the specified OLM + + +.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/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| +|=== + +.HTTP responses +[cols="1,1",options="header"] +|=== +| HTTP code | Reponse body +| 200 - OK +| xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 201 - Created +| xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[`OLM`] schema +| 401 - Unauthorized +| Empty +|=== + + diff --git a/rest_api/operatorhub_apis/operatorhub-apis-index.adoc b/rest_api/operatorhub_apis/operatorhub-apis-index.adoc index ea4e4aafe4..262f616a04 100644 --- a/rest_api/operatorhub_apis/operatorhub-apis-index.adoc +++ b/rest_api/operatorhub_apis/operatorhub-apis-index.adoc @@ -46,11 +46,11 @@ Type:: Description:: + -- -ClusterExtensionRevision is the Schema for the clusterextensionrevisions API + -- Type:: - `object` + `` == ClusterServiceVersion [operators.coreos.com/v1alpha1] @@ -71,6 +71,19 @@ Description:: InstallPlan defines the installation of a set of operators. -- +Type:: + `object` + +== OLM [operator.openshift.io/v1] + +Description:: ++ +-- +OLM provides information to configure an operator to manage the OLM controllers + +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/overview/index.adoc b/rest_api/overview/index.adoc index f7ba39b9c3..a947d73111 100644 --- a/rest_api/overview/index.adoc +++ b/rest_api/overview/index.adoc @@ -30,6 +30,8 @@ | config.openshift.io/v1 | xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[Authentication] | operator.openshift.io/v1 +| xref:../config_apis/backup-config-openshift-io-v1alpha1.adoc#backup-config-openshift-io-v1alpha1[Backup] +| config.openshift.io/v1alpha1 | xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[BareMetalHost] | metal3.io/v1alpha1 | xref:../network_apis/baselineadminnetworkpolicy-policy-networking-k8s-io-v1alpha1.adoc#baselineadminnetworkpolicy-policy-networking-k8s-io-v1alpha1[BaselineAdminNetworkPolicy] @@ -66,10 +68,10 @@ | operator.openshift.io/v1 | xref:../operatorhub_apis/clusterextension-olm-operatorframework-io-v1.adoc#clusterextension-olm-operatorframework-io-v1[ClusterExtension] | olm.operatorframework.io/v1 -| xref:../operatorhub_apis/clusterextensionrevision-olm-operatorframework-io-v1.adoc#clusterextensionrevision-olm-operatorframework-io-v1[ClusterExtensionRevision] -| olm.operatorframework.io/v1 | xref:../config_apis/clusterimagepolicy-config-openshift-io-v1.adoc#clusterimagepolicy-config-openshift-io-v1[ClusterImagePolicy] | config.openshift.io/v1 +| xref:../config_apis/clustermonitoring-config-openshift-io-v1alpha1.adoc#clustermonitoring-config-openshift-io-v1alpha1[ClusterMonitoring] +| config.openshift.io/v1alpha1 | 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] @@ -88,6 +90,8 @@ | k8s.ovn.org/v1 | xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[ClusterVersion] | config.openshift.io/v1 +| xref:../operator_apis/clusterversionoperator-operator-openshift-io-v1alpha1.adoc#clusterversionoperator-operator-openshift-io-v1alpha1[ClusterVersionOperator] +| operator.openshift.io/v1alpha1 | xref:../metadata_apis/componentstatus-v1.adoc#componentstatus-v1[ComponentStatus] | v1 | xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[Config] @@ -142,6 +146,8 @@ | apiextensions.k8s.io/v1 | xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[DaemonSet] | apps/v1 +| xref:../monitoring_apis/datagather-insights-openshift-io-v1alpha2.adoc#datagather-insights-openshift-io-v1alpha2[DataGather] +| insights.openshift.io/v1alpha2 | xref:../provisioning_apis/dataimage-metal3-io-v1alpha1.adoc#dataimage-metal3-io-v1alpha1[DataImage] | metal3.io/v1alpha1 | xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[Deployment] @@ -158,6 +164,8 @@ | config.openshift.io/v1 | xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[DNS] | operator.openshift.io/v1 +| xref:../network_apis/dnsnameresolver-network-openshift-io-v1alpha1.adoc#dnsnameresolver-network-openshift-io-v1alpha1[DNSNameResolver] +| network.openshift.io/v1alpha1 | xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[DNSRecord] | ingress.operator.openshift.io/v1 | xref:../network_apis/egressfirewall-k8s-ovn-org-v1.adoc#egressfirewall-k8s-ovn-org-v1[EgressFirewall] @@ -176,6 +184,8 @@ | discovery.k8s.io/v1 | xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[Etcd] | operator.openshift.io/v1 +| xref:../operator_apis/etcdbackup-operator-openshift-io-v1alpha1.adoc#etcdbackup-operator-openshift-io-v1alpha1[EtcdBackup] +| operator.openshift.io/v1alpha1 | xref:../metadata_apis/event-v1.adoc#event-v1[Event] | v1 | xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[Event] @@ -254,18 +264,18 @@ | networking.k8s.io/v1 | xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[IngressController] | operator.openshift.io/v1 +| xref:../config_apis/insightsdatagather-config-openshift-io-v1alpha2.adoc#insightsdatagather-config-openshift-io-v1alpha2[InsightsDataGather] +| config.openshift.io/v1alpha2 | xref:../operator_apis/insightsoperator-operator-openshift-io-v1.adoc#insightsoperator-operator-openshift-io-v1[InsightsOperator] | operator.openshift.io/v1 | xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[InstallPlan] | operators.coreos.com/v1alpha1 -| xref:../cluster_apis/ipaddress-ipam-cluster-x-k8s-io-v1beta1.adoc#ipaddress-ipam-cluster-x-k8s-io-v1beta1[IPAddress] -| ipam.cluster.x-k8s.io/v1beta1 +| xref:../machine_apis/internalreleaseimage-machineconfiguration-openshift-io-v1alpha1.adoc#internalreleaseimage-machineconfiguration-openshift-io-v1alpha1[InternalReleaseImage] +| machineconfiguration.openshift.io/v1alpha1 | xref:../network_apis/ipaddress-networking-k8s-io-v1.adoc#ipaddress-networking-k8s-io-v1[IPAddress] | networking.k8s.io/v1 | xref:../network_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/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] @@ -348,6 +358,8 @@ | oauth.openshift.io/v1 | xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[OAuthClientAuthorization] | oauth.openshift.io/v1 +| xref:../operatorhub_apis/olm-operator-openshift-io-v1.adoc#olm-operator-openshift-io-v1[OLM] +| operator.openshift.io/v1 | xref:../operatorhub_apis/olmconfig-operators-coreos-com-v1.adoc#olmconfig-operators-coreos-com-v1[OLMConfig] | operators.coreos.com/v1 | xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[OpenShiftAPIServer] @@ -364,6 +376,8 @@ | config.openshift.io/v1 | xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[OperatorPKI] | network.operator.openshift.io/v1 +| xref:../machine_apis/osimagestream-machineconfiguration-openshift-io-v1alpha1.adoc#osimagestream-machineconfiguration-openshift-io-v1alpha1[OSImageStream] +| machineconfiguration.openshift.io/v1alpha1 | xref:../network_apis/overlappingrangeipreservation-whereabouts-cni-cncf-io-v1alpha1.adoc#overlappingrangeipreservation-whereabouts-cni-cncf-io-v1alpha1[OverlappingRangeIPReservation] | whereabouts.cni.cncf.io/v1alpha1 | xref:../operatorhub_apis/packagemanifest-packages-operators-coreos-com-v1.adoc#packagemanifest-packages-operators-coreos-com-v1[PackageManifest] diff --git a/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc b/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc index 5eee6b6697..7e8b280f0b 100644 --- a/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc +++ b/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc @@ -626,7 +626,6 @@ Valid effects are NoSchedule, PreferNoSchedule and NoExecute. | `timeAdded` | `string` | TimeAdded represents the time at which the taint was added. -It is only written for NoExecute taints. | `value` | `string` @@ -977,6 +976,10 @@ Type:: if one is present. If both IPv4 and IPv6 addresses are present in a dual-stack environment, two nics will be output, one with each IP. +| `lldp` +| `object` +| LLDP data for this interface + | `mac` | `string` | The device MAC address @@ -1009,6 +1012,36 @@ dual-stack environment, two nics will be output, one with each IP. | `object` | VLAN represents the name and ID of a VLAN. +|=== +=== .status.hardware.nics[].lldp +Description:: ++ +-- +LLDP data for this interface +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `portID` +| `string` +| The switch port ID from LLDP + +| `switchID` +| `string` +| The switch chassis ID from LLDP + +| `switchSystemName` +| `string` +| The switch system name from LLDP + |=== === .status.hardware.nics[].vlans Description:: diff --git a/rest_api/provisioning_apis/hardwaredata-metal3-io-v1alpha1.adoc b/rest_api/provisioning_apis/hardwaredata-metal3-io-v1alpha1.adoc index c5041ee4dd..268c6a9926 100644 --- a/rest_api/provisioning_apis/hardwaredata-metal3-io-v1alpha1.adoc +++ b/rest_api/provisioning_apis/hardwaredata-metal3-io-v1alpha1.adoc @@ -244,6 +244,10 @@ Type:: if one is present. If both IPv4 and IPv6 addresses are present in a dual-stack environment, two nics will be output, one with each IP. +| `lldp` +| `object` +| LLDP data for this interface + | `mac` | `string` | The device MAC address @@ -276,6 +280,36 @@ dual-stack environment, two nics will be output, one with each IP. | `object` | VLAN represents the name and ID of a VLAN. +|=== +=== .spec.hardware.nics[].lldp +Description:: ++ +-- +LLDP data for this interface +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `portID` +| `string` +| The switch port ID from LLDP + +| `switchID` +| `string` +| The switch chassis ID from LLDP + +| `switchSystemName` +| `string` +| The switch system name from LLDP + |=== === .spec.hardware.nics[].vlans Description:: diff --git a/rest_api/provisioning_apis/provisioning-metal3-io-v1alpha1.adoc b/rest_api/provisioning_apis/provisioning-metal3-io-v1alpha1.adoc index a8fe1adc58..d384366fde 100644 --- a/rest_api/provisioning_apis/provisioning-metal3-io-v1alpha1.adoc +++ b/rest_api/provisioning_apis/provisioning-metal3-io-v1alpha1.adoc @@ -92,6 +92,12 @@ by the metal3 pod. | DisableVirtualMediaTLS turns off TLS on the virtual media server, which may be required for hardware that cannot accept HTTPS links. +| `externalIPs` +| `array (string)` +| ExternalIPs are the external-facing IP addresses used to access the Ironic service. +Most users will not need this set. It is recommended to leave this unset unless +actually necessary. + | `preProvisioningOSDownloadURLs` | `object` | PreprovisioningOSDownloadURLs is set of CoreOS Live URLs that would be necessary to provision a worker