Config APIs


OpenShift Container Platform 4.14

Reference guide for config APIs

Red Hat OpenShift Documentation Team

Abstract

This document describes the OpenShift Container Platform config API objects and their detailed specifications.

Chapter 1. Config APIs

1.1. APIServer [config.openshift.io/v1]

Description
APIServer holds configuration (like serving certificates, client CA and CORS domains) shared by all API servers in the system, among them especially kube-apiserver and openshift-apiserver. 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

1.2. Authentication [config.openshift.io/v1]

Description
Authentication specifies cluster-wide settings for authentication (like OAuth and 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

1.3. Build [config.openshift.io/v1]

Description
Build configures the behavior of OpenShift builds for the entire cluster. This includes default settings that can be overridden in BuildConfig objects, and overrides which are applied to all builds. The canonical name 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

1.4. ClusterOperator [config.openshift.io/v1]

Description
ClusterOperator is the Custom Resource object which holds the current state of an operator. This object is used by 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

1.5. ClusterVersion [config.openshift.io/v1]

Description
ClusterVersion is the configuration for the ClusterVersionOperator. This is where parameters related to automatic updates can be set. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
Type
object

1.6. Console [config.openshift.io/v1]

Description
Console holds cluster-wide configuration for the web console, including the logout URL, and reports the public URL of the console. The canonical name 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

1.7. DNS [config.openshift.io/v1]

Description
DNS holds cluster-wide information about DNS. The canonical name 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

1.8. FeatureGate [config.openshift.io/v1]

Description
Feature holds cluster-wide information about feature gates. The canonical name 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

1.9. HelmChartRepository [helm.openshift.io/v1beta1]

Description
HelmChartRepository holds cluster-wide configuration for proxied Helm chart repository Compatibility level 2: Stable within a major release for a minimum of 9 months or 3 minor releases (whichever is longer).
Type
object

1.10. Image [config.openshift.io/v1]

Description
Image governs policies related to imagestream imports and runtime configuration for external registries. It allows cluster admins to configure which registries OpenShift is allowed to import images from, extra CA trust bundles for external registries, and policies to block or allow registry hostnames. When exposing OpenShift’s image registry to the public, this also lets cluster admins specify the external hostname. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
Type
object

1.11. ImageDigestMirrorSet [config.openshift.io/v1]

Description
ImageDigestMirrorSet holds cluster-wide information about how to handle registry mirror rules on using digest pull specification. When multiple policies are defined, the outcome of the behavior is defined on each field. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
Type
object

1.12. ImageContentPolicy [config.openshift.io/v1]

Description
ImageContentPolicy holds cluster-wide information about how to handle registry mirror rules. When multiple policies are defined, the outcome of the behavior is defined on each field. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
Type
object

1.13. ImageTagMirrorSet [config.openshift.io/v1]

Description
ImageTagMirrorSet holds cluster-wide information about how to handle registry mirror rules on using tag pull specification. When multiple policies are defined, the outcome of the behavior is defined on each field. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
Type
object

1.14. Infrastructure [config.openshift.io/v1]

Description
Infrastructure holds cluster-wide information about Infrastructure. The canonical name 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

1.15. Ingress [config.openshift.io/v1]

Description
Ingress holds cluster-wide information about ingress, including the default ingress domain used for routes. The canonical name 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

1.16. Network [config.openshift.io/v1]

Description
Network holds cluster-wide information about Network. The canonical name is cluster. It is used to configure the desired network configuration, such as: IP address pools for services/pod IPs, network plugin, etc. Please view network.spec for an explanation on what applies when configuring this resource. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
Type
object

1.17. Node [config.openshift.io/v1]

Description
Node holds cluster-wide information about node specific features. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
Type
object

1.18. OAuth [config.openshift.io/v1]

Description
OAuth holds cluster-wide information about OAuth. The canonical name is cluster. It is used to configure the integrated OAuth server. This configuration is only honored when the top level Authentication config has type set to IntegratedOAuth. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
Type
object

1.19. OperatorHub [config.openshift.io/v1]

Description
OperatorHub is the Schema for the operatorhubs API. It can be used to change the state of the default hub sources for OperatorHub on the cluster from enabled to disabled and vice versa. Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer).
Type
object

1.20. Project [config.openshift.io/v1]

Description
Project holds cluster-wide information about Project. The canonical name 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

1.21. ProjectHelmChartRepository [helm.openshift.io/v1beta1]

Description
ProjectHelmChartRepository holds namespace-wide configuration for proxied Helm chart repository Compatibility level 2: Stable within a major release for a minimum of 9 months or 3 minor releases (whichever is longer).
Type
object

1.22. Proxy [config.openshift.io/v1]

Description
Proxy holds cluster-wide information on how to configure default proxies for the cluster. The canonical name 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

1.23. Scheduler [config.openshift.io/v1]

Description
Scheduler holds cluster-wide config information to run the Kubernetes Scheduler and influence its placement decisions. The canonical name for this config 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

Chapter 2. APIServer [config.openshift.io/v1]

Description
APIServer holds configuration (like serving certificates, client CA and CORS domains) shared by all API servers in the system, among them especially kube-apiserver and openshift-apiserver. 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
Required
  • spec

2.1. Specification

PropertyTypeDescription

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

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.

2.1.1. .spec

Description
spec holds user settable values for configuration
Type
object
PropertyTypeDescription

additionalCORSAllowedOrigins

array (string)

additionalCORSAllowedOrigins lists additional, user-defined regular expressions describing hosts for which the API server allows access using the CORS headers. This may be needed to access the API and the integrated OAuth server from JavaScript applications. The values are regular expressions that correspond to the Golang regular expression language.

audit

object

audit specifies the settings for audit configuration to be applied to all OpenShift-provided API servers in the cluster.

clientCA

object

clientCA references a ConfigMap containing a certificate bundle for the signers that will be recognized for incoming client certificates in addition to the operator managed signers. If this is empty, then only operator managed signers are valid. You usually only have to set this if you have your own PKI you wish to honor client certificates from. The ConfigMap must exist in the openshift-config namespace and contain the following required fields: - ConfigMap.Data["ca-bundle.crt"] - CA bundle.

encryption

object

encryption allows the configuration of encryption of resources at the datastore layer.

servingCerts

object

servingCert is the TLS cert info for serving secure traffic. If not specified, operator managed certificates will be used for serving secure traffic.

tlsSecurityProfile

object

tlsSecurityProfile specifies settings for TLS connections for externally exposed servers. If unset, a default (which may change between releases) is chosen. Note that only Old, Intermediate and Custom profiles are currently supported, and the maximum available MinTLSVersions is VersionTLS12.

2.1.2. .spec.audit

Description
audit specifies the settings for audit configuration to be applied to all OpenShift-provided API servers in the cluster.
Type
object
PropertyTypeDescription

customRules

array

customRules specify profiles per group. These profile take precedence over the top-level profile field if they apply. They are evaluation from top to bottom and the first one that matches, applies.

customRules[]

object

AuditCustomRule describes a custom rule for an audit profile that takes precedence over the top-level profile.

profile

string

profile specifies the name of the desired top-level audit profile to be applied to all requests sent to any of the OpenShift-provided API servers in the cluster (kube-apiserver, openshift-apiserver and oauth-apiserver), with the exception of those requests that match one or more of the customRules. The following profiles are provided: - Default: default policy which means MetaData level logging with the exception of events (not logged at all), oauthaccesstokens and oauthauthorizetokens (both logged at RequestBody level). - WriteRequestBodies: like 'Default', but logs request and response HTTP payloads for write requests (create, update, patch). - AllRequestBodies: like 'WriteRequestBodies', but also logs request and response HTTP payloads for read requests (get, list). - None: no requests are logged at all, not even oauthaccesstokens and oauthauthorizetokens. Warning: It is not recommended to disable audit logging by using the None profile unless you are fully aware of the risks of not logging data that can be beneficial when troubleshooting issues. If you disable audit logging and a support situation arises, you might need to enable audit logging and reproduce the issue in order to troubleshoot properly. If unset, the 'Default' profile is used as the default.

2.1.3. .spec.audit.customRules

Description
customRules specify profiles per group. These profile take precedence over the top-level profile field if they apply. They are evaluation from top to bottom and the first one that matches, applies.
Type
array

2.1.4. .spec.audit.customRules[]

Description
AuditCustomRule describes a custom rule for an audit profile that takes precedence over the top-level profile.
Type
object
Required
  • group
  • profile
PropertyTypeDescription

group

string

group is a name of group a request user must be member of in order to this profile to apply.

profile

string

profile specifies the name of the desired audit policy configuration to be deployed to all OpenShift-provided API servers in the cluster. The following profiles are provided: - Default: the existing default policy. - WriteRequestBodies: like 'Default', but logs request and response HTTP payloads for write requests (create, update, patch). - AllRequestBodies: like 'WriteRequestBodies', but also logs request and response HTTP payloads for read requests (get, list). - None: no requests are logged at all, not even oauthaccesstokens and oauthauthorizetokens. If unset, the 'Default' profile is used as the default.

2.1.5. .spec.clientCA

Description
clientCA references a ConfigMap containing a certificate bundle for the signers that will be recognized for incoming client certificates in addition to the operator managed signers. If this is empty, then only operator managed signers are valid. You usually only have to set this if you have your own PKI you wish to honor client certificates from. The ConfigMap must exist in the openshift-config namespace and contain the following required fields: - ConfigMap.Data["ca-bundle.crt"] - CA bundle.
Type
object
Required
  • name
PropertyTypeDescription

name

string

name is the metadata.name of the referenced config map

2.1.6. .spec.encryption

Description
encryption allows the configuration of encryption of resources at the datastore layer.
Type
object
PropertyTypeDescription

type

string

type defines what encryption type should be used to encrypt resources at the datastore layer. When this field is unset (i.e. when it is set to the empty string), identity is implied. The behavior of unset can and will change over time. Even if encryption is enabled by default, the meaning of unset may change to a different encryption type based on changes in best practices. When encryption is enabled, all sensitive resources shipped with the platform are encrypted. This list of sensitive resources can and will change over time. The current authoritative list is: 1. secrets 2. configmaps 3. routes.route.openshift.io 4. oauthaccesstokens.oauth.openshift.io 5. oauthauthorizetokens.oauth.openshift.io

2.1.7. .spec.servingCerts

Description
servingCert is the TLS cert info for serving secure traffic. If not specified, operator managed certificates will be used for serving secure traffic.
Type
object
PropertyTypeDescription

namedCertificates

array

namedCertificates references secrets containing the TLS cert info for serving secure traffic to specific hostnames. If no named certificates are provided, or no named certificates match the server name as understood by a client, the defaultServingCertificate will be used.

namedCertificates[]

object

APIServerNamedServingCert maps a server DNS name, as understood by a client, to a certificate.

2.1.8. .spec.servingCerts.namedCertificates

Description
namedCertificates references secrets containing the TLS cert info for serving secure traffic to specific hostnames. If no named certificates are provided, or no named certificates match the server name as understood by a client, the defaultServingCertificate will be used.
Type
array

2.1.9. .spec.servingCerts.namedCertificates[]

Description
APIServerNamedServingCert maps a server DNS name, as understood by a client, to a certificate.
Type
object
PropertyTypeDescription

names

array (string)

names is a optional list of explicit DNS names (leading wildcards allowed) that should use this certificate to serve secure traffic. If no names are provided, the implicit names will be extracted from the certificates. Exact names trump over wildcard names. Explicit names defined here trump over extracted implicit names.

servingCertificate

object

servingCertificate references a kubernetes.io/tls type secret containing the TLS cert info for serving secure traffic. The secret must exist in the openshift-config namespace and contain the following required fields: - Secret.Data["tls.key"] - TLS private key. - Secret.Data["tls.crt"] - TLS certificate.

2.1.10. .spec.servingCerts.namedCertificates[].servingCertificate

Description
servingCertificate references a kubernetes.io/tls type secret containing the TLS cert info for serving secure traffic. The secret must exist in the openshift-config namespace and contain the following required fields: - Secret.Data["tls.key"] - TLS private key. - Secret.Data["tls.crt"] - TLS certificate.
Type
object
Required
  • name
PropertyTypeDescription

name

string

name is the metadata.name of the referenced secret

2.1.11. .spec.tlsSecurityProfile

Description
tlsSecurityProfile specifies settings for TLS connections for externally exposed servers. If unset, a default (which may change between releases) is chosen. Note that only Old, Intermediate and Custom profiles are currently supported, and the maximum available MinTLSVersions is VersionTLS12.
Type
object
PropertyTypeDescription

custom

``

custom is a user-defined TLS security profile. Be extremely careful using a custom profile as invalid configurations can be catastrophic. An example custom profile looks like this: ciphers: - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 minTLSVersion: TLSv1.1

intermediate

``

intermediate is a TLS security profile based on: https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28recommended.29 and looks like this (yaml): ciphers: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384 - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 - DHE-RSA-AES128-GCM-SHA256 - DHE-RSA-AES256-GCM-SHA384 minTLSVersion: TLSv1.2

modern

``

modern is a TLS security profile based on: https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility and looks like this (yaml): ciphers: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 minTLSVersion: TLSv1.3 NOTE: Currently unsupported.

old

``

old is a TLS security profile based on: https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility and looks like this (yaml): ciphers: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384 - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 - DHE-RSA-AES128-GCM-SHA256 - DHE-RSA-AES256-GCM-SHA384 - DHE-RSA-CHACHA20-POLY1305 - ECDHE-ECDSA-AES128-SHA256 - ECDHE-RSA-AES128-SHA256 - ECDHE-ECDSA-AES128-SHA - ECDHE-RSA-AES128-SHA - ECDHE-ECDSA-AES256-SHA384 - ECDHE-RSA-AES256-SHA384 - ECDHE-ECDSA-AES256-SHA - ECDHE-RSA-AES256-SHA - DHE-RSA-AES128-SHA256 - DHE-RSA-AES256-SHA256 - AES128-GCM-SHA256 - AES256-GCM-SHA384 - AES128-SHA256 - AES256-SHA256 - AES128-SHA - AES256-SHA - DES-CBC3-SHA minTLSVersion: TLSv1.0

type

string

type is one of Old, Intermediate, Modern or Custom. Custom provides the ability to specify individual TLS security profile parameters. Old, Intermediate and Modern are TLS security profiles based on: https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations The profiles are intent based, so they may change over time as new ciphers are developed and existing ciphers are found to be insecure. Depending on precisely which ciphers are available to a process, the list may be reduced. Note that the Modern profile is currently not supported because it is not yet well adopted by common software libraries.

2.1.12. .status

Description
status holds observed values from the cluster. They may not be overridden.
Type
object

2.2. API endpoints

The following API endpoints are available:

  • /apis/config.openshift.io/v1/apiservers

    • DELETE: delete collection of APIServer
    • GET: list objects of kind APIServer
    • POST: create an APIServer
  • /apis/config.openshift.io/v1/apiservers/{name}

    • DELETE: delete an APIServer
    • GET: read the specified APIServer
    • PATCH: partially update the specified APIServer
    • PUT: replace the specified APIServer
  • /apis/config.openshift.io/v1/apiservers/{name}/status

    • GET: read status of the specified APIServer
    • PATCH: partially update status of the specified APIServer
    • PUT: replace status of the specified APIServer

2.2.1. /apis/config.openshift.io/v1/apiservers

Table 2.1. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of APIServer
Table 2.2. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

sendInitialEvents

boolean

sendInitialEvents=true may be set together with watch=true. In that case, the watch stream will begin with synthetic events to produce the current state of objects in the collection. Once all such events have been sent, a synthetic "Bookmark" event will be sent. The bookmark will report the ResourceVersion (RV) corresponding to the set of objects, and be marked with "k8s.io/initial-events-end": "true" annotation. Afterwards, the watch stream will proceed as usual, sending watch events corresponding to changes (subsequent to the RV) to objects watched.

When sendInitialEvents option is set, we require resourceVersionMatch option to also be set. The semantic of the watch request is as following: - resourceVersionMatch = NotOlderThan is interpreted as "data at least as new as the provided resourceVersion`" and the bookmark event is send when the state is synced to a `resourceVersion at least as fresh as the one provided by the ListOptions. If resourceVersion is unset, this is interpreted as "consistent read" and the bookmark event is send when the state is synced at least to the moment when request started being processed. - resourceVersionMatch set to any other value or unset Invalid error is returned.

Defaults to true if resourceVersion="" or resourceVersion="0" (for backward compatibility reasons) and to false otherwise.

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 2.3. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind APIServer
Table 2.4. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

sendInitialEvents

boolean

sendInitialEvents=true may be set together with watch=true. In that case, the watch stream will begin with synthetic events to produce the current state of objects in the collection. Once all such events have been sent, a synthetic "Bookmark" event will be sent. The bookmark will report the ResourceVersion (RV) corresponding to the set of objects, and be marked with "k8s.io/initial-events-end": "true" annotation. Afterwards, the watch stream will proceed as usual, sending watch events corresponding to changes (subsequent to the RV) to objects watched.

When sendInitialEvents option is set, we require resourceVersionMatch option to also be set. The semantic of the watch request is as following: - resourceVersionMatch = NotOlderThan is interpreted as "data at least as new as the provided resourceVersion`" and the bookmark event is send when the state is synced to a `resourceVersion at least as fresh as the one provided by the ListOptions. If resourceVersion is unset, this is interpreted as "consistent read" and the bookmark event is send when the state is synced at least to the moment when request started being processed. - resourceVersionMatch set to any other value or unset Invalid error is returned.

Defaults to true if resourceVersion="" or resourceVersion="0" (for backward compatibility reasons) and to false otherwise.

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 2.5. HTTP responses
HTTP codeReponse body

200 - OK

APIServerList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create an APIServer
Table 2.6. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 2.7. Body parameters
ParameterTypeDescription

body

APIServer schema

 
Table 2.8. HTTP responses
HTTP codeReponse body

200 - OK

APIServer schema

201 - Created

APIServer schema

202 - Accepted

APIServer schema

401 - Unauthorized

Empty

2.2.2. /apis/config.openshift.io/v1/apiservers/{name}

Table 2.9. Global path parameters
ParameterTypeDescription

name

string

name of the APIServer

Table 2.10. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete an APIServer
Table 2.11. Query parameters
ParameterTypeDescription

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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 2.12. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 2.13. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified APIServer
Table 2.14. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 2.15. HTTP responses
HTTP codeReponse body

200 - OK

APIServer schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified APIServer
Table 2.16. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch).

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.

force

boolean

Force is going to "force" Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests.

Table 2.17. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 2.18. HTTP responses
HTTP codeReponse body

200 - OK

APIServer schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified APIServer
Table 2.19. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 2.20. Body parameters
ParameterTypeDescription

body

APIServer schema

 
Table 2.21. HTTP responses
HTTP codeReponse body

200 - OK

APIServer schema

201 - Created

APIServer schema

401 - Unauthorized

Empty

2.2.3. /apis/config.openshift.io/v1/apiservers/{name}/status

Table 2.22. Global path parameters
ParameterTypeDescription

name

string

name of the APIServer

Table 2.23. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
GET
Description
read status of the specified APIServer
Table 2.24. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 2.25. HTTP responses
HTTP codeReponse body

200 - OK

APIServer schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update status of the specified APIServer
Table 2.26. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch).

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.

force

boolean

Force is going to "force" Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests.

Table 2.27. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 2.28. HTTP responses
HTTP codeReponse body

200 - OK

APIServer schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace status of the specified APIServer
Table 2.29. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 2.30. Body parameters
ParameterTypeDescription

body

APIServer schema

 
Table 2.31. HTTP responses
HTTP codeReponse body

200 - OK

APIServer schema

201 - Created

APIServer schema

401 - Unauthorized

Empty

Chapter 3. Authentication [config.openshift.io/v1]

Description
Authentication specifies cluster-wide settings for authentication (like OAuth and 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
Required
  • spec

3.1. Specification

PropertyTypeDescription

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

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.

3.1.1. .spec

Description
spec holds user settable values for configuration
Type
object
PropertyTypeDescription

oauthMetadata

object

oauthMetadata contains the discovery endpoint data for OAuth 2.0 Authorization Server Metadata for an external OAuth server. This discovery document can be viewed from its served location: oc get --raw '/.well-known/oauth-authorization-server' For further details, see the IETF Draft: https://tools.ietf.org/html/draft-ietf-oauth-discovery-04#section-2 If oauthMetadata.name is non-empty, this value has precedence over any metadata reference stored in status. The key "oauthMetadata" is used to locate the data. If specified and the config map or expected key is not found, no metadata is served. If the specified metadata is not valid, no metadata is served. The namespace for this config map is openshift-config.

serviceAccountIssuer

string

serviceAccountIssuer is the identifier of the bound service account token issuer. The default is https://kubernetes.default.svc WARNING: Updating this field will not result in immediate invalidation of all bound tokens with the previous issuer value. Instead, the tokens issued by previous service account issuer will continue to be trusted for a time period chosen by the platform (currently set to 24h). This time period is subject to change over time. This allows internal components to transition to use new service account issuer without service distruption.

type

string

type identifies the cluster managed, user facing authentication mode in use. Specifically, it manages the component that responds to login attempts. The default is IntegratedOAuth.

webhookTokenAuthenticator

object

webhookTokenAuthenticator configures a remote token reviewer. These remote authentication webhooks can be used to verify bearer tokens via the tokenreviews.authentication.k8s.io REST API. This is required to honor bearer tokens that are provisioned by an external authentication service.

webhookTokenAuthenticators

array

webhookTokenAuthenticators is DEPRECATED, setting it has no effect.

webhookTokenAuthenticators[]

object

deprecatedWebhookTokenAuthenticator holds the necessary configuration options for a remote token authenticator. It’s the same as WebhookTokenAuthenticator but it’s missing the 'required' validation on KubeConfig field.

3.1.2. .spec.oauthMetadata

Description
oauthMetadata contains the discovery endpoint data for OAuth 2.0 Authorization Server Metadata for an external OAuth server. This discovery document can be viewed from its served location: oc get --raw '/.well-known/oauth-authorization-server' For further details, see the IETF Draft: https://tools.ietf.org/html/draft-ietf-oauth-discovery-04#section-2 If oauthMetadata.name is non-empty, this value has precedence over any metadata reference stored in status. The key "oauthMetadata" is used to locate the data. If specified and the config map or expected key is not found, no metadata is served. If the specified metadata is not valid, no metadata is served. The namespace for this config map is openshift-config.
Type
object
Required
  • name
PropertyTypeDescription

name

string

name is the metadata.name of the referenced config map

3.1.3. .spec.webhookTokenAuthenticator

Description
webhookTokenAuthenticator configures a remote token reviewer. These remote authentication webhooks can be used to verify bearer tokens via the tokenreviews.authentication.k8s.io REST API. This is required to honor bearer tokens that are provisioned by an external authentication service.
Type
object
Required
  • kubeConfig
PropertyTypeDescription

kubeConfig

object

kubeConfig references a secret that contains kube config file data which describes how to access the remote webhook service. The namespace for the referenced secret is openshift-config. For further details, see: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication The key "kubeConfig" is used to locate the data. If the secret or expected key is not found, the webhook is not honored. If the specified kube config data is not valid, the webhook is not honored.

3.1.4. .spec.webhookTokenAuthenticator.kubeConfig

Description
kubeConfig references a secret that contains kube config file data which describes how to access the remote webhook service. The namespace for the referenced secret is openshift-config. For further details, see: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication The key "kubeConfig" is used to locate the data. If the secret or expected key is not found, the webhook is not honored. If the specified kube config data is not valid, the webhook is not honored.
Type
object
Required
  • name
PropertyTypeDescription

name

string

name is the metadata.name of the referenced secret

3.1.5. .spec.webhookTokenAuthenticators

Description
webhookTokenAuthenticators is DEPRECATED, setting it has no effect.
Type
array

3.1.6. .spec.webhookTokenAuthenticators[]

Description
deprecatedWebhookTokenAuthenticator holds the necessary configuration options for a remote token authenticator. It’s the same as WebhookTokenAuthenticator but it’s missing the 'required' validation on KubeConfig field.
Type
object
PropertyTypeDescription

kubeConfig

object

kubeConfig contains kube config file data which describes how to access the remote webhook service. For further details, see: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication The key "kubeConfig" is used to locate the data. If the secret or expected key is not found, the webhook is not honored. If the specified kube config data is not valid, the webhook is not honored. The namespace for this secret is determined by the point of use.

3.1.7. .spec.webhookTokenAuthenticators[].kubeConfig

Description
kubeConfig contains kube config file data which describes how to access the remote webhook service. For further details, see: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication The key "kubeConfig" is used to locate the data. If the secret or expected key is not found, the webhook is not honored. If the specified kube config data is not valid, the webhook is not honored. The namespace for this secret is determined by the point of use.
Type
object
Required
  • name
PropertyTypeDescription

name

string

name is the metadata.name of the referenced secret

3.1.8. .status

Description
status holds observed values from the cluster. They may not be overridden.
Type
object
PropertyTypeDescription

integratedOAuthMetadata

object

integratedOAuthMetadata contains the discovery endpoint data for OAuth 2.0 Authorization Server Metadata for the in-cluster integrated OAuth server. This discovery document can be viewed from its served location: oc get --raw '/.well-known/oauth-authorization-server' For further details, see the IETF Draft: https://tools.ietf.org/html/draft-ietf-oauth-discovery-04#section-2 This contains the observed value based on cluster state. An explicitly set value in spec.oauthMetadata has precedence over this field. This field has no meaning if authentication spec.type is not set to IntegratedOAuth. The key "oauthMetadata" is used to locate the data. If the config map or expected key is not found, no metadata is served. If the specified metadata is not valid, no metadata is served. The namespace for this config map is openshift-config-managed.

3.1.9. .status.integratedOAuthMetadata

Description
integratedOAuthMetadata contains the discovery endpoint data for OAuth 2.0 Authorization Server Metadata for the in-cluster integrated OAuth server. This discovery document can be viewed from its served location: oc get --raw '/.well-known/oauth-authorization-server' For further details, see the IETF Draft: https://tools.ietf.org/html/draft-ietf-oauth-discovery-04#section-2 This contains the observed value based on cluster state. An explicitly set value in spec.oauthMetadata has precedence over this field. This field has no meaning if authentication spec.type is not set to IntegratedOAuth. The key "oauthMetadata" is used to locate the data. If the config map or expected key is not found, no metadata is served. If the specified metadata is not valid, no metadata is served. The namespace for this config map is openshift-config-managed.
Type
object
Required
  • name
PropertyTypeDescription

name

string

name is the metadata.name of the referenced config map

3.2. API endpoints

The following API endpoints are available:

  • /apis/config.openshift.io/v1/authentications

    • DELETE: delete collection of Authentication
    • GET: list objects of kind Authentication
    • POST: create an Authentication
  • /apis/config.openshift.io/v1/authentications/{name}

    • DELETE: delete an Authentication
    • GET: read the specified Authentication
    • PATCH: partially update the specified Authentication
    • PUT: replace the specified Authentication
  • /apis/config.openshift.io/v1/authentications/{name}/status

    • GET: read status of the specified Authentication
    • PATCH: partially update status of the specified Authentication
    • PUT: replace status of the specified Authentication

3.2.1. /apis/config.openshift.io/v1/authentications

Table 3.1. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of Authentication
Table 3.2. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

sendInitialEvents

boolean

sendInitialEvents=true may be set together with watch=true. In that case, the watch stream will begin with synthetic events to produce the current state of objects in the collection. Once all such events have been sent, a synthetic "Bookmark" event will be sent. The bookmark will report the ResourceVersion (RV) corresponding to the set of objects, and be marked with "k8s.io/initial-events-end": "true" annotation. Afterwards, the watch stream will proceed as usual, sending watch events corresponding to changes (subsequent to the RV) to objects watched.

When sendInitialEvents option is set, we require resourceVersionMatch option to also be set. The semantic of the watch request is as following: - resourceVersionMatch = NotOlderThan is interpreted as "data at least as new as the provided resourceVersion`" and the bookmark event is send when the state is synced to a `resourceVersion at least as fresh as the one provided by the ListOptions. If resourceVersion is unset, this is interpreted as "consistent read" and the bookmark event is send when the state is synced at least to the moment when request started being processed. - resourceVersionMatch set to any other value or unset Invalid error is returned.

Defaults to true if resourceVersion="" or resourceVersion="0" (for backward compatibility reasons) and to false otherwise.

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 3.3. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind Authentication
Table 3.4. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

sendInitialEvents

boolean

sendInitialEvents=true may be set together with watch=true. In that case, the watch stream will begin with synthetic events to produce the current state of objects in the collection. Once all such events have been sent, a synthetic "Bookmark" event will be sent. The bookmark will report the ResourceVersion (RV) corresponding to the set of objects, and be marked with "k8s.io/initial-events-end": "true" annotation. Afterwards, the watch stream will proceed as usual, sending watch events corresponding to changes (subsequent to the RV) to objects watched.

When sendInitialEvents option is set, we require resourceVersionMatch option to also be set. The semantic of the watch request is as following: - resourceVersionMatch = NotOlderThan is interpreted as "data at least as new as the provided resourceVersion`" and the bookmark event is send when the state is synced to a `resourceVersion at least as fresh as the one provided by the ListOptions. If resourceVersion is unset, this is interpreted as "consistent read" and the bookmark event is send when the state is synced at least to the moment when request started being processed. - resourceVersionMatch set to any other value or unset Invalid error is returned.

Defaults to true if resourceVersion="" or resourceVersion="0" (for backward compatibility reasons) and to false otherwise.

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 3.5. HTTP responses
HTTP codeReponse body

200 - OK

AuthenticationList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create an Authentication
Table 3.6. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 3.7. Body parameters
ParameterTypeDescription

body

Authentication schema

 
Table 3.8. HTTP responses
HTTP codeReponse body

200 - OK

Authentication schema

201 - Created

Authentication schema

202 - Accepted

Authentication schema

401 - Unauthorized

Empty

3.2.2. /apis/config.openshift.io/v1/authentications/{name}

Table 3.9. Global path parameters
ParameterTypeDescription

name

string

name of the Authentication

Table 3.10. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete an Authentication
Table 3.11. Query parameters
ParameterTypeDescription

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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 3.12. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 3.13. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified Authentication
Table 3.14. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 3.15. HTTP responses
HTTP codeReponse body

200 - OK

Authentication schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified Authentication
Table 3.16. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch).

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.

force

boolean

Force is going to "force" Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests.

Table 3.17. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 3.18. HTTP responses
HTTP codeReponse body

200 - OK

Authentication schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified Authentication
Table 3.19. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 3.20. Body parameters
ParameterTypeDescription

body

Authentication schema

 
Table 3.21. HTTP responses
HTTP codeReponse body

200 - OK

Authentication schema

201 - Created

Authentication schema

401 - Unauthorized

Empty

3.2.3. /apis/config.openshift.io/v1/authentications/{name}/status

Table 3.22. Global path parameters
ParameterTypeDescription

name

string

name of the Authentication

Table 3.23. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
GET
Description
read status of the specified Authentication
Table 3.24. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 3.25. HTTP responses
HTTP codeReponse body

200 - OK

Authentication schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update status of the specified Authentication
Table 3.26. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch).

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.

force

boolean

Force is going to "force" Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests.

Table 3.27. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 3.28. HTTP responses
HTTP codeReponse body

200 - OK

Authentication schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace status of the specified Authentication
Table 3.29. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 3.30. Body parameters
ParameterTypeDescription

body

Authentication schema

 
Table 3.31. HTTP responses
HTTP codeReponse body

200 - OK

Authentication schema

201 - Created

Authentication schema

401 - Unauthorized

Empty

Chapter 4. Build [config.openshift.io/v1]

Description
Build configures the behavior of OpenShift builds for the entire cluster. This includes default settings that can be overridden in BuildConfig objects, and overrides which are applied to all builds. The canonical name 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
Required
  • spec

4.1. Specification

PropertyTypeDescription

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

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 the build controller configuration

4.1.1. .spec

Description
Spec holds user-settable values for the build controller configuration
Type
object
PropertyTypeDescription

additionalTrustedCA

object

AdditionalTrustedCA is a reference to a ConfigMap containing additional CAs that should be trusted for image pushes and pulls during builds. The namespace for this config map is openshift-config. DEPRECATED: Additional CAs for image pull and push should be set on image.config.openshift.io/cluster instead.

buildDefaults

object

BuildDefaults controls the default information for Builds

buildOverrides

object

BuildOverrides controls override settings for builds

4.1.2. .spec.additionalTrustedCA

Description
AdditionalTrustedCA is a reference to a ConfigMap containing additional CAs that should be trusted for image pushes and pulls during builds. The namespace for this config map is openshift-config. DEPRECATED: Additional CAs for image pull and push should be set on image.config.openshift.io/cluster instead.
Type
object
Required
  • name
PropertyTypeDescription

name

string

name is the metadata.name of the referenced config map

4.1.3. .spec.buildDefaults

Description
BuildDefaults controls the default information for Builds
Type
object
PropertyTypeDescription

defaultProxy

object

DefaultProxy contains the default proxy settings for all build operations, including image pull/push and source download. Values can be overrode by setting the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables in the build config’s strategy.

env

array

Env is a set of default environment variables that will be applied to the build if the specified variables do not exist on the build

env[]

object

EnvVar represents an environment variable present in a Container.

gitProxy

object

GitProxy contains the proxy settings for git operations only. If set, this will override any Proxy settings for all git commands, such as git clone. Values that are not set here will be inherited from DefaultProxy.

imageLabels

array

ImageLabels is a list of docker labels that are applied to the resulting image. User can override a default label by providing a label with the same name in their Build/BuildConfig.

imageLabels[]

object

 

resources

object

Resources defines resource requirements to execute the build.

4.1.4. .spec.buildDefaults.defaultProxy

Description
DefaultProxy contains the default proxy settings for all build operations, including image pull/push and source download. Values can be overrode by setting the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables in the build config’s strategy.
Type
object
PropertyTypeDescription

httpProxy

string

httpProxy is the URL of the proxy for HTTP requests. Empty means unset and will not result in an env var.

httpsProxy

string

httpsProxy is the URL of the proxy for HTTPS requests. Empty means unset and will not result in an env var.

noProxy

string

noProxy is a comma-separated list of hostnames and/or CIDRs and/or IPs for which the proxy should not be used. Empty means unset and will not result in an env var.

readinessEndpoints

array (string)

readinessEndpoints is a list of endpoints used to verify readiness of the proxy.

trustedCA

object

trustedCA is a reference to a ConfigMap containing a CA certificate bundle. The trustedCA field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from the required key "ca-bundle.crt", merging it with the system default trust bundle, and writing the merged trust bundle to a ConfigMap named "trusted-ca-bundle" in the "openshift-config-managed" namespace. Clients that expect to make proxy connections must use the trusted-ca-bundle for all HTTPS requests to the proxy, and may use the trusted-ca-bundle for non-proxy HTTPS requests as well. The namespace for the ConfigMap referenced by trustedCA is "openshift-config". Here is an example ConfigMap (in yaml): apiVersion: v1 kind: ConfigMap metadata: name: user-ca-bundle namespace: openshift-config data: ca-bundle.crt: | -----BEGIN CERTIFICATE----- Custom CA certificate bundle. -----END CERTIFICATE-----

4.1.5. .spec.buildDefaults.defaultProxy.trustedCA

Description
trustedCA is a reference to a ConfigMap containing a CA certificate bundle. The trustedCA field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from the required key "ca-bundle.crt", merging it with the system default trust bundle, and writing the merged trust bundle to a ConfigMap named "trusted-ca-bundle" in the "openshift-config-managed" namespace. Clients that expect to make proxy connections must use the trusted-ca-bundle for all HTTPS requests to the proxy, and may use the trusted-ca-bundle for non-proxy HTTPS requests as well. The namespace for the ConfigMap referenced by trustedCA is "openshift-config". Here is an example ConfigMap (in yaml): apiVersion: v1 kind: ConfigMap metadata: name: user-ca-bundle namespace: openshift-config data: ca-bundle.crt: \| -----BEGIN CERTIFICATE----- Custom CA certificate bundle. -----END CERTIFICATE-----
Type
object
Required
  • name
PropertyTypeDescription

name

string

name is the metadata.name of the referenced config map

4.1.6. .spec.buildDefaults.env

Description
Env is a set of default environment variables that will be applied to the build if the specified variables do not exist on the build
Type
array

4.1.7. .spec.buildDefaults.env[]

Description
EnvVar represents an environment variable present in a Container.
Type
object
Required
  • name
PropertyTypeDescription

name

string

Name of the environment variable. Must be a C_IDENTIFIER.

value

string

Variable references $(VAR_NAME) are expanded using the previously defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. Double are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. "(VAR_NAME)" will produce the string literal "$(VAR_NAME)". Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "".

valueFrom

object

Source for the environment variable’s value. Cannot be used if value is not empty.

4.1.8. .spec.buildDefaults.env[].valueFrom

Description
Source for the environment variable’s value. Cannot be used if value is not empty.
Type
object
PropertyTypeDescription

configMapKeyRef

object

Selects a key of a ConfigMap.

fieldRef

object

Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels['<KEY>'], metadata.annotations['<KEY>'], spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.

resourceFieldRef

object

Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.

secretKeyRef

object

Selects a key of a secret in the pod’s namespace

4.1.9. .spec.buildDefaults.env[].valueFrom.configMapKeyRef

Description
Selects a key of a ConfigMap.
Type
object
Required
  • key
PropertyTypeDescription

key

string

The key to select.

name

string

Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid?

optional

boolean

Specify whether the ConfigMap or its key must be defined

4.1.10. .spec.buildDefaults.env[].valueFrom.fieldRef

Description
Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels['<KEY>'], metadata.annotations['<KEY>'], spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.
Type
object
Required
  • fieldPath
PropertyTypeDescription

apiVersion

string

Version of the schema the FieldPath is written in terms of, defaults to "v1".

fieldPath

string

Path of the field to select in the specified API version.

4.1.11. .spec.buildDefaults.env[].valueFrom.resourceFieldRef

Description
Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.
Type
object
Required
  • resource
PropertyTypeDescription

containerName

string

Container name: required for volumes, optional for env vars

divisor

integer-or-string

Specifies the output format of the exposed resources, defaults to "1"

resource

string

Required: resource to select

4.1.12. .spec.buildDefaults.env[].valueFrom.secretKeyRef

Description
Selects a key of a secret in the pod’s namespace
Type
object
Required
  • key
PropertyTypeDescription

key

string

The key of the secret to select from. Must be a valid secret key.

name

string

Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid?

optional

boolean

Specify whether the Secret or its key must be defined

4.1.13. .spec.buildDefaults.gitProxy

Description
GitProxy contains the proxy settings for git operations only. If set, this will override any Proxy settings for all git commands, such as git clone. Values that are not set here will be inherited from DefaultProxy.
Type
object
PropertyTypeDescription

httpProxy

string

httpProxy is the URL of the proxy for HTTP requests. Empty means unset and will not result in an env var.

httpsProxy

string

httpsProxy is the URL of the proxy for HTTPS requests. Empty means unset and will not result in an env var.

noProxy

string

noProxy is a comma-separated list of hostnames and/or CIDRs and/or IPs for which the proxy should not be used. Empty means unset and will not result in an env var.

readinessEndpoints

array (string)

readinessEndpoints is a list of endpoints used to verify readiness of the proxy.

trustedCA

object

trustedCA is a reference to a ConfigMap containing a CA certificate bundle. The trustedCA field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from the required key "ca-bundle.crt", merging it with the system default trust bundle, and writing the merged trust bundle to a ConfigMap named "trusted-ca-bundle" in the "openshift-config-managed" namespace. Clients that expect to make proxy connections must use the trusted-ca-bundle for all HTTPS requests to the proxy, and may use the trusted-ca-bundle for non-proxy HTTPS requests as well. The namespace for the ConfigMap referenced by trustedCA is "openshift-config". Here is an example ConfigMap (in yaml): apiVersion: v1 kind: ConfigMap metadata: name: user-ca-bundle namespace: openshift-config data: ca-bundle.crt: | -----BEGIN CERTIFICATE----- Custom CA certificate bundle. -----END CERTIFICATE-----

4.1.14. .spec.buildDefaults.gitProxy.trustedCA

Description
trustedCA is a reference to a ConfigMap containing a CA certificate bundle. The trustedCA field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from the required key "ca-bundle.crt", merging it with the system default trust bundle, and writing the merged trust bundle to a ConfigMap named "trusted-ca-bundle" in the "openshift-config-managed" namespace. Clients that expect to make proxy connections must use the trusted-ca-bundle for all HTTPS requests to the proxy, and may use the trusted-ca-bundle for non-proxy HTTPS requests as well. The namespace for the ConfigMap referenced by trustedCA is "openshift-config". Here is an example ConfigMap (in yaml): apiVersion: v1 kind: ConfigMap metadata: name: user-ca-bundle namespace: openshift-config data: ca-bundle.crt: \| -----BEGIN CERTIFICATE----- Custom CA certificate bundle. -----END CERTIFICATE-----
Type
object
Required
  • name
PropertyTypeDescription

name

string

name is the metadata.name of the referenced config map

4.1.15. .spec.buildDefaults.imageLabels

Description
ImageLabels is a list of docker labels that are applied to the resulting image. User can override a default label by providing a label with the same name in their Build/BuildConfig.
Type
array

4.1.16. .spec.buildDefaults.imageLabels[]

Description
Type
object
PropertyTypeDescription

name

string

Name defines the name of the label. It must have non-zero length.

value

string

Value defines the literal value of the label.

4.1.17. .spec.buildDefaults.resources

Description
Resources defines resource requirements to execute the build.
Type
object
PropertyTypeDescription

claims

array

Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. This is an alpha field and requires enabling the DynamicResourceAllocation feature gate. This field is immutable. It can only be set for containers.

claims[]

object

ResourceClaim references one entry in PodSpec.ResourceClaims.

limits

integer-or-string

Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

requests

integer-or-string

Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

4.1.18. .spec.buildDefaults.resources.claims

Description
Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. This is an alpha field and requires enabling the DynamicResourceAllocation feature gate. This field is immutable. It can only be set for containers.
Type
array

4.1.19. .spec.buildDefaults.resources.claims[]

Description
ResourceClaim references one entry in PodSpec.ResourceClaims.
Type
object
Required
  • name
PropertyTypeDescription

name

string

Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.

4.1.20. .spec.buildOverrides

Description
BuildOverrides controls override settings for builds
Type
object
PropertyTypeDescription

forcePull

boolean

ForcePull overrides, if set, the equivalent value in the builds, i.e. false disables force pull for all builds, true enables force pull for all builds, independently of what each build specifies itself

imageLabels

array

ImageLabels is a list of docker labels that are applied to the resulting image. If user provided a label in their Build/BuildConfig with the same name as one in this list, the user’s label will be overwritten.

imageLabels[]

object

 

nodeSelector

object (string)

NodeSelector is a selector which must be true for the build pod to fit on a node

tolerations

array

Tolerations is a list of Tolerations that will override any existing tolerations set on a build pod.

tolerations[]

object

The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>.

4.1.21. .spec.buildOverrides.imageLabels

Description
ImageLabels is a list of docker labels that are applied to the resulting image. If user provided a label in their Build/BuildConfig with the same name as one in this list, the user’s label will be overwritten.
Type
array

4.1.22. .spec.buildOverrides.imageLabels[]

Description
Type
object
PropertyTypeDescription

name

string

Name defines the name of the label. It must have non-zero length.

value

string

Value defines the literal value of the label.

4.1.23. .spec.buildOverrides.tolerations

Description
Tolerations is a list of Tolerations that will override any existing tolerations set on a build pod.
Type
array

4.1.24. .spec.buildOverrides.tolerations[]

Description
The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>.
Type
object
PropertyTypeDescription

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.

4.2. API endpoints

The following API endpoints are available:

  • /apis/config.openshift.io/v1/builds

    • DELETE: delete collection of Build
    • GET: list objects of kind Build
    • POST: create a Build
  • /apis/config.openshift.io/v1/builds/{name}

    • DELETE: delete a Build
    • GET: read the specified Build
    • PATCH: partially update the specified Build
    • PUT: replace the specified Build
  • /apis/config.openshift.io/v1/builds/{name}/status

    • GET: read status of the specified Build
    • PATCH: partially update status of the specified Build
    • PUT: replace status of the specified Build

4.2.1. /apis/config.openshift.io/v1/builds

Table 4.1. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of Build
Table 4.2. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

sendInitialEvents

boolean

sendInitialEvents=true may be set together with watch=true. In that case, the watch stream will begin with synthetic events to produce the current state of objects in the collection. Once all such events have been sent, a synthetic "Bookmark" event will be sent. The bookmark will report the ResourceVersion (RV) corresponding to the set of objects, and be marked with "k8s.io/initial-events-end": "true" annotation. Afterwards, the watch stream will proceed as usual, sending watch events corresponding to changes (subsequent to the RV) to objects watched.

When sendInitialEvents option is set, we require resourceVersionMatch option to also be set. The semantic of the watch request is as following: - resourceVersionMatch = NotOlderThan is interpreted as "data at least as new as the provided resourceVersion`" and the bookmark event is send when the state is synced to a `resourceVersion at least as fresh as the one provided by the ListOptions. If resourceVersion is unset, this is interpreted as "consistent read" and the bookmark event is send when the state is synced at least to the moment when request started being processed. - resourceVersionMatch set to any other value or unset Invalid error is returned.

Defaults to true if resourceVersion="" or resourceVersion="0" (for backward compatibility reasons) and to false otherwise.

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 4.3. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind Build
Table 4.4. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

sendInitialEvents

boolean

sendInitialEvents=true may be set together with watch=true. In that case, the watch stream will begin with synthetic events to produce the current state of objects in the collection. Once all such events have been sent, a synthetic "Bookmark" event will be sent. The bookmark will report the ResourceVersion (RV) corresponding to the set of objects, and be marked with "k8s.io/initial-events-end": "true" annotation. Afterwards, the watch stream will proceed as usual, sending watch events corresponding to changes (subsequent to the RV) to objects watched.

When sendInitialEvents option is set, we require resourceVersionMatch option to also be set. The semantic of the watch request is as following: - resourceVersionMatch = NotOlderThan is interpreted as "data at least as new as the provided resourceVersion`" and the bookmark event is send when the state is synced to a `resourceVersion at least as fresh as the one provided by the ListOptions. If resourceVersion is unset, this is interpreted as "consistent read" and the bookmark event is send when the state is synced at least to the moment when request started being processed. - resourceVersionMatch set to any other value or unset Invalid error is returned.

Defaults to true if resourceVersion="" or resourceVersion="0" (for backward compatibility reasons) and to false otherwise.

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 4.5. HTTP responses
HTTP codeReponse body

200 - OK

BuildList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create a Build
Table 4.6. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 4.7. Body parameters
ParameterTypeDescription

body

Build schema

 
Table 4.8. HTTP responses
HTTP codeReponse body

200 - OK

Build schema

201 - Created

Build schema

202 - Accepted

Build schema

401 - Unauthorized

Empty

4.2.2. /apis/config.openshift.io/v1/builds/{name}

Table 4.9. Global path parameters
ParameterTypeDescription

name

string

name of the Build

Table 4.10. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete a Build
Table 4.11. Query parameters
ParameterTypeDescription

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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 4.12. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 4.13. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified Build
Table 4.14. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 4.15. HTTP responses
HTTP codeReponse body

200 - OK

Build schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified Build
Table 4.16. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch).

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.

force

boolean

Force is going to "force" Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests.

Table 4.17. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 4.18. HTTP responses
HTTP codeReponse body

200 - OK

Build schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified Build
Table 4.19. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 4.20. Body parameters
ParameterTypeDescription

body

Build schema

 
Table 4.21. HTTP responses
HTTP codeReponse body

200 - OK

Build schema

201 - Created

Build schema

401 - Unauthorized

Empty

4.2.3. /apis/config.openshift.io/v1/builds/{name}/status

Table 4.22. Global path parameters
ParameterTypeDescription

name

string

name of the Build

Table 4.23. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
GET
Description
read status of the specified Build
Table 4.24. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 4.25. HTTP responses
HTTP codeReponse body

200 - OK

Build schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update status of the specified Build
Table 4.26. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch).

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.

force

boolean

Force is going to "force" Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests.

Table 4.27. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 4.28. HTTP responses
HTTP codeReponse body

200 - OK

Build schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace status of the specified Build
Table 4.29. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 4.30. Body parameters
ParameterTypeDescription

body

Build schema

 
Table 4.31. HTTP responses
HTTP codeReponse body

200 - OK

Build schema

201 - Created

Build schema

401 - Unauthorized

Empty

Chapter 5. ClusterOperator [config.openshift.io/v1]

Description
ClusterOperator is the Custom Resource object which holds the current state of an operator. This object is used by 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
Required
  • spec

5.1. Specification

PropertyTypeDescription

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

ObjectMeta

Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

spec

object

spec holds configuration that could apply to any operator.

status

object

status holds the information about the state of an operator. It is consistent with status information across the Kubernetes ecosystem.

5.1.1. .spec

Description
spec holds configuration that could apply to any operator.
Type
object

5.1.2. .status

Description
status holds the information about the state of an operator. It is consistent with status information across the Kubernetes ecosystem.
Type
object
PropertyTypeDescription

conditions

array

conditions describes the state of the operator’s managed and monitored components.

conditions[]

object

ClusterOperatorStatusCondition represents the state of the operator’s managed and monitored components.

extension

``

extension contains any additional status information specific to the operator which owns this status object.

relatedObjects

array

relatedObjects is a list of objects that are "interesting" or related to this operator. Common uses are: 1. the detailed resource driving the operator 2. operator namespaces 3. operand namespaces

relatedObjects[]

object

ObjectReference contains enough information to let you inspect or modify the referred object.

versions

array

versions is a slice of operator and operand version tuples. Operators which manage multiple operands will have multiple operand entries in the array. Available operators must report the version of the operator itself with the name "operator". An operator reports a new "operator" version when it has rolled out the new version to all of its operands.

versions[]

object

 

5.1.3. .status.conditions

Description
conditions describes the state of the operator’s managed and monitored components.
Type
array

5.1.4. .status.conditions[]

Description
ClusterOperatorStatusCondition represents the state of the operator’s managed and monitored components.
Type
object
Required
  • lastTransitionTime
  • status
  • type
PropertyTypeDescription

lastTransitionTime

string

lastTransitionTime is the time of the last update to the current status property.

message

string

message provides additional information about the current condition. This is only to be consumed by humans. It may contain Line Feed characters (U+000A), which should be rendered as new lines.

reason

string

reason is the CamelCase reason for the condition’s current status.

status

string

status of the condition, one of True, False, Unknown.

type

string

type specifies the aspect reported by this condition.

5.1.5. .status.relatedObjects

Description
relatedObjects is a list of objects that are "interesting" or related to this operator. Common uses are: 1. the detailed resource driving the operator 2. operator namespaces 3. operand namespaces
Type
array

5.1.6. .status.relatedObjects[]

Description
ObjectReference contains enough information to let you inspect or modify the referred object.
Type
object
Required
  • group
  • name
  • resource
PropertyTypeDescription

group

string

group of the referent.

name

string

name of the referent.

namespace

string

namespace of the referent.

resource

string

resource of the referent.

5.1.7. .status.versions

Description
versions is a slice of operator and operand version tuples. Operators which manage multiple operands will have multiple operand entries in the array. Available operators must report the version of the operator itself with the name "operator". An operator reports a new "operator" version when it has rolled out the new version to all of its operands.
Type
array

5.1.8. .status.versions[]

Description
Type
object
Required
  • name
  • version
PropertyTypeDescription

name

string

name is the name of the particular operand this version is for. It usually matches container images, not operators.

version

string

version indicates which version of a particular operand is currently being managed. It must always match the Available operand. If 1.0.0 is Available, then this must indicate 1.0.0 even if the operator is trying to rollout 1.1.0

5.2. API endpoints

The following API endpoints are available:

  • /apis/config.openshift.io/v1/clusteroperators

    • DELETE: delete collection of ClusterOperator
    • GET: list objects of kind ClusterOperator
    • POST: create a ClusterOperator
  • /apis/config.openshift.io/v1/clusteroperators/{name}

    • DELETE: delete a ClusterOperator
    • GET: read the specified ClusterOperator
    • PATCH: partially update the specified ClusterOperator
    • PUT: replace the specified ClusterOperator
  • /apis/config.openshift.io/v1/clusteroperators/{name}/status

    • GET: read status of the specified ClusterOperator
    • PATCH: partially update status of the specified ClusterOperator
    • PUT: replace status of the specified ClusterOperator

5.2.1. /apis/config.openshift.io/v1/clusteroperators

Table 5.1. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of ClusterOperator
Table 5.2. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

sendInitialEvents

boolean

sendInitialEvents=true may be set together with watch=true. In that case, the watch stream will begin with synthetic events to produce the current state of objects in the collection. Once all such events have been sent, a synthetic "Bookmark" event will be sent. The bookmark will report the ResourceVersion (RV) corresponding to the set of objects, and be marked with "k8s.io/initial-events-end": "true" annotation. Afterwards, the watch stream will proceed as usual, sending watch events corresponding to changes (subsequent to the RV) to objects watched.

When sendInitialEvents option is set, we require resourceVersionMatch option to also be set. The semantic of the watch request is as following: - resourceVersionMatch = NotOlderThan is interpreted as "data at least as new as the provided resourceVersion`" and the bookmark event is send when the state is synced to a `resourceVersion at least as fresh as the one provided by the ListOptions. If resourceVersion is unset, this is interpreted as "consistent read" and the bookmark event is send when the state is synced at least to the moment when request started being processed. - resourceVersionMatch set to any other value or unset Invalid error is returned.

Defaults to true if resourceVersion="" or resourceVersion="0" (for backward compatibility reasons) and to false otherwise.

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 5.3. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind ClusterOperator
Table 5.4. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

sendInitialEvents

boolean

sendInitialEvents=true may be set together with watch=true. In that case, the watch stream will begin with synthetic events to produce the current state of objects in the collection. Once all such events have been sent, a synthetic "Bookmark" event will be sent. The bookmark will report the ResourceVersion (RV) corresponding to the set of objects, and be marked with "k8s.io/initial-events-end": "true" annotation. Afterwards, the watch stream will proceed as usual, sending watch events corresponding to changes (subsequent to the RV) to objects watched.

When sendInitialEvents option is set, we require resourceVersionMatch option to also be set. The semantic of the watch request is as following: - resourceVersionMatch = NotOlderThan is interpreted as "data at least as new as the provided resourceVersion`" and the bookmark event is send when the state is synced to a `resourceVersion at least as fresh as the one provided by the ListOptions. If resourceVersion is unset, this is interpreted as "consistent read" and the bookmark event is send when the state is synced at least to the moment when request started being processed. - resourceVersionMatch set to any other value or unset Invalid error is returned.

Defaults to true if resourceVersion="" or resourceVersion="0" (for backward compatibility reasons) and to false otherwise.

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 5.5. HTTP responses
HTTP codeReponse body

200 - OK

ClusterOperatorList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create a ClusterOperator
Table 5.6. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 5.7. Body parameters
ParameterTypeDescription

body

ClusterOperator schema

 
Table 5.8. HTTP responses
HTTP codeReponse body

200 - OK

ClusterOperator schema

201 - Created

ClusterOperator schema

202 - Accepted

ClusterOperator schema

401 - Unauthorized

Empty

5.2.2. /apis/config.openshift.io/v1/clusteroperators/{name}

Table 5.9. Global path parameters
ParameterTypeDescription

name

string

name of the ClusterOperator

Table 5.10. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete a ClusterOperator
Table 5.11. Query parameters
ParameterTypeDescription

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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 5.12. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 5.13. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified ClusterOperator
Table 5.14. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 5.15. HTTP responses
HTTP codeReponse body

200 - OK

ClusterOperator schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified ClusterOperator
Table 5.16. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch).

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.

force

boolean

Force is going to "force" Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests.

Table 5.17. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 5.18. HTTP responses
HTTP codeReponse body

200 - OK

ClusterOperator schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified ClusterOperator
Table 5.19. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 5.20. Body parameters
ParameterTypeDescription

body

ClusterOperator schema

 
Table 5.21. HTTP responses
HTTP codeReponse body

200 - OK

ClusterOperator schema

201 - Created

ClusterOperator schema

401 - Unauthorized

Empty

5.2.3. /apis/config.openshift.io/v1/clusteroperators/{name}/status

Table 5.22. Global path parameters
ParameterTypeDescription

name

string

name of the ClusterOperator

Table 5.23. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
GET
Description
read status of the specified ClusterOperator
Table 5.24. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 5.25. HTTP responses
HTTP codeReponse body

200 - OK

ClusterOperator schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update status of the specified ClusterOperator
Table 5.26. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch).

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.

force

boolean

Force is going to "force" Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests.

Table 5.27. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 5.28. HTTP responses
HTTP codeReponse body

200 - OK

ClusterOperator schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace status of the specified ClusterOperator
Table 5.29. Query parameters
ParameterTypeDescription

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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

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.

Table 5.30. Body parameters
ParameterTypeDescription

body

ClusterOperator schema

 
Table 5.31. HTTP responses
HTTP codeReponse body

200 - OK

ClusterOperator schema

201 - Created

ClusterOperator schema

401 - Unauthorized

Empty

Chapter 6. ClusterVersion [config.openshift.io/v1]

Description
ClusterVersion is the configuration for the ClusterVersionOperator. This is where parameters related to automatic updates can be set. 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

6.1. Specification

PropertyTypeDescription

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

ObjectMeta

Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

spec

object

spec is the desired state of the cluster version - the operator will work to ensure that the desired version is applied to the cluster.

status

object

status contains information about the available updates and any in-progress updates.

6.1.1. .spec

Description
spec is the desired state of the cluster version - the operator will work to ensure that the desired version is applied to the cluster.
Type
object
Required
  • clusterID
PropertyTypeDescription

capabilities

object

capabilities configures the installation of optional, core cluster components. A null value here is identical to an empty object; see the child properties for default semantics.

channel

string

channel is an identifier for explicitly requesting that a non-default set of updates be applied to this cluster. The default channel will be contain stable updates that are appropriate for production clusters.

clusterID

string

clusterID uniquely identifies this cluster. This is expected to be an RFC4122 UUID value (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx in hexadecimal values). This is a required field.

desiredUpdate

object

desiredUpdate is an optional field that indicates the desired value of the cluster version. Setting this value will trigger an upgrade (if the current version does not match the desired version). The set of recommended update values is listed as part of available updates in status, and setting values outside that range may cause the upgrade to fail. Some of the fields are inter-related with restrictions and meanings described here. 1. image is specified, version is specified, architecture is specified. API validation error. 2. image is specified, version is specified, architecture is not specified. You should not do this. version is silently ignored and image is used. 3. image is specified, version is not specified, architecture is specified. API validation error. 4. image is specified, version is not specified, architecture is not specified. image is used. 5. image is not specified, version is specified, architecture is specified. version and desired architecture are used to select an image. 6. image is not specified, version is specified, architecture is not specified. version and current architecture are used to select an image. 7. image is not specified, version is not specified, architecture is specified. API validation error. 8. image is not specified, version is not specified, architecture is not specified. API validation error. If an upgrade fails the operator will halt and report status about the failing component. Setting the desired update value back to the previous version will cause a rollback to be attempted. Not all rollbacks will succeed.

overrides

array

overrides is list of overides for components that are managed by cluster version operator. Marking a component unmanaged will prevent the operator from creating or updating the object.

overrides[]

object

ComponentOverride allows overriding cluster version operator’s behavior for a component.

upstream

string

upstream may be used to specify the preferred update server. By default it will use the appropriate update server for the cluster and region.

6.1.2. .spec.capabilities

Description
capabilities configures the installation of optional, core cluster components. A null value here is identical to an empty object; see the child properties for default semantics.
Type
object
PropertyTypeDescription

additionalEnabledCapabilities

array (string)

additionalEnabledCapabilities extends the set of managed capabilities beyond the baseline defined in baselineCapabilitySet. The default is an empty set.

baselineCapabilitySet

string

baselineCapabilitySet selects an initial set of optional capabilities to enable, which can be extended via additionalEnabledCapabilities. If unset, the cluster will choose a default, and the default may change over time. The current default is vCurrent.

6.1.3. .spec.desiredUpdate

Description
desiredUpdate is an optional field that indicates the desired value of the cluster version. Setting this value will trigger an upgrade (if the current version does not match the desired version). The set of recommended update values is listed as part of available updates in status, and setting values outside that range may cause the upgrade to fail. Some of the fields are inter-related with restrictions and meanings described here. 1. image is specified, version is specified, architecture is specified. API validation error. 2. image is specified, version is specified, architecture is not specified. You should not do this. version is silently ignored and image is used. 3. image is specified, version is not specified, architecture is specified. API validation error. 4. image is specified, version is not specified, architecture is not specified. image is used. 5. image is not specified, version is specified, architecture is specified. version and desired architecture are used to select an image. 6. image is not specified, version is specified, architecture is not specified. version and current architecture are used to select an image. 7. image is not specified, version is not specified, architecture is specified. API validation error. 8. image is not specified, version is not specified, architecture is not specified. API validation error. If an upgrade fails the operator will halt and report status about the failing component. Setting the desired update value back to the previous version will cause a rollback to be attempted. Not all rollbacks will succeed.
Type
object