From ca754dc0215e8f2090baaf9173a6914bdff18030 Mon Sep 17 00:00:00 2001 From: Ben Parees Date: Mon, 1 Jul 2019 18:58:03 -0400 Subject: [PATCH] add base documentation for all operator+config resources --- installing/install_config/customizations.adoc | 237 +++++++++++------- 1 file changed, 149 insertions(+), 88 deletions(-) diff --git a/installing/install_config/customizations.adoc b/installing/install_config/customizations.adoc index bba766a2960e..83b61a7aed2a 100644 --- a/installing/install_config/customizations.adoc +++ b/installing/install_config/customizations.adoc @@ -5,91 +5,152 @@ include::modules/common-attributes.adoc[] toc::[] You complete most of the cluster configuration and customization after you -deploy your {product-title} cluster. By default, a number of +deploy your {product-title} cluster. A number of _configuration resources_ //and _Custom Resources_ are available. -You modify the configuration resources to define the major components of the -cluster, such as the networking configuration and the identity provider. +You modify the configuration resources to configure the major features of the +cluster, such as the image registry, networking configuration, image build +behavior, and the identity provider. -//// -You can also deploy Custom Resources (CRs) that are based on a number of -Custom Resource Definitions (CRDs) that are deployed on your cluster. -//// +For current documentation of settings these resources expose, use +the `oc explain` command, for example `oc explain builds --api-version=config.openshift.io/v1` [id="configuration-resources_{context}"] -== Configuration resources +== Cluster configuration resources + +All cluster configuration resources are globally scoped (not namespaced) and named `cluster`. +//// +Config changes should not require coordinated changes between config resources, if you find +yourself struggling to update these docs to explain coordinated changes, please reach out +to @api-approvers (github) or #forum-api-review (slack). +//// -[cols="2a,5a",options="header"] +[cols="2a,8a",options="header"] |=== -|Configuration resource |Description +|Resource name +|Description -|APIServer -|You can -xref:../../authentication/certificates/api-server.adoc#api-server-certificates[add certificates] -for the API server. +|apiserver.config.openshift.io +|Provides api-server configuration such as xref:../../authentication/certificates/api-server.adoc#api-server-certificates[certificates and certificate authorities]. -|Authentication -|You can configure the -xref:../../authentication/understanding-identity-provider.adoc#understanding-identity-provider[identity provider] -for your cluster. +|authentication.config.openshift.io +|Controls the xref:../../authentication/understanding-identity-provider.adoc#understanding-identity-provider[identity provider]and authentication configuration for the cluster. -|Build -|You can configure your -xref:../../builds/build-configuration.adoc#build-configuration[build] settings. +|build.config.openshift.io +|Controls default and enforced xref:../../builds/build-configuration.adoc#build-configuration[configuration] for all builds on the cluster. -|ClusterVersion -|In {product-title} {product-version}, you must not customize the ClusterVersion -resource for production clusters. Instead, follow the process to -xref:../../updating/updating-cluster.adoc#updating-cluster[update a cluster]. +|console.config.openshift.io +|Configures the behavior of the web console interface, including the xref:../../web-console/configuring-web-console.adoc#configuring-web-console[logout behavior]. -|Console -|You can -xref:../../web-console/configuring-web-console.adoc#configuring-web-console[configure] -the web console to set a logout redirect URL. +|featuregate.config.openshift.io +|Enables xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[FeatureGates] +so that you can use Tech Preview features. -|DNS -|You cannot modify the DNS settings for your cluster. You can -xref:../../networking/dns-operator.adoc#dns-operator[view the DNS Operator status]. +|image.config.openshift.io +|Configures how specific xref:../../openshift_images/image-configuration.adoc#image-configuration[image registries] should be treated (allowed, disallowed, insecure, CA details). -|FeatureGate -|You can -xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[enable a FeatureGate] -so that you can use Tech Preview features. +|ingress.config.openshift.io +|Configuration details related to xref:../../networking/ingress-operator.adoc#nw-installation-ingress-config-asset_configuring-ingress[routing] such as the default domain for routes. -|Image -|You can configure -xref:../../openshift_images/image-configuration.adoc#image-configuration[image] -settings. +|oauth.config.openshift.io +|Configures identity providers and other behavior related to xref:../../authentication/configuring-internal-oauth.adoc#configuring-internal-oauth[internal OAuth server] flows. -|Infrastructure -|In {product-title} {product-version}, you cannot customize the Infrastructure resource. +|project.config.openshift.io +|Configures xref:../../applications/projects/configuring-project-creation.adoc#configuring-project-creation[how projects are created] including the project template. -|Ingress -|To enable external access to {product-title} cluster services, configure the -xref:../../networking/ingress-operator.adoc#configuring-ingress[Ingress Operator]. +|proxy.config.openshift.io +|Defines proxies to be used by components needing external network access. Note: not all components currently consume this value. -|Network -|You cannot modify your cluster networking after installation. If you must -customize your network, you -xref:../../installing/installing_aws/installing-aws-network-customizations.adoc#installing-aws-network-customizations[customize networking during installation]. +|scheduler.config.openshift.io +|Configures xref:../../nodes/scheduling/nodes-scheduler-default.adoc#nodes-scheduler-default[scheduler] behavior such as policies and default nodeselectors. -|OAuth -|Configure the -xref:../../authentication/configuring-internal-oauth.adoc#configuring-internal-oauth[internal OAuth server]. +|=== -|Project -|Configure xref:../../applications/projects/configuring-project-creation.adoc#configuring-project-creation[how projects are created]. +[id="operator-configuration-resources_{context}"] +== Operator configuration resources + +These configuration resources are cluster scoped singletons which control behavior of a specific component as +owned by a particular operator. All resources are cluster scoped and the instances are named `cluster`. + +[cols="2a,8a",options="header"] +|=== +|Resource name +|Description + +|console.operator.openshift.io +|Control console appearance such as branding customizations + +|config.imageregistry.operator.openshift.io +|Configure xref:../../registry/configuring-registry-operator.adoc#registry-operator-configuration-resource-overview_configuring-registry-operator[internal image registry settings] such as public routing, log levels, proxy settings, resource constraints, replica counts, and storage type. -|Samples +|config.samples.operator.openshift.io |Configure the -xref:../../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[samples Operator] -to start using images. +xref:../../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[Samples Operator] +to control which example imagestreams and templates are installed on the cluster. +|Global + +|=== + + +[id="additional-configuration-resources_{context}"] +== Additional configuration resources + +These configuration resources represent a single instance of a particular component, in some cases multiple +instances may be requested by creating multiple instances of the resource. In other cases only a specific +resource instance name in a specific namespace will be consumed by the operator. Reference the component specific +documentation for details on how and when additional resource instances can be created. + +[cols="2a,2a,2a,8a",options="header"] +|=== +|Resource name +|Instance name +|Namespace +|Description + +|alertmanager.monitoring.coreos.com +|main +|openshift-monitoring +|Controls the xref:../../monitoring/cluster-monitoring/configuring-the-monitoring-stack.adoc#configuring-alertmanager[alertmanager] deployment parameters + +|ingresscontroller.operator.openshift.io +|default +|openshift-ingress-operator +|Configure xref:../../networking/ingress-operator.adoc#configuring-ingress[Ingress Operator] behavior such as domain, number of replicas, certificates, and controller placement. + +|=== -|Scheduler -|To determine the default placement of pods on nodes, configure the -xref:../../nodes/scheduling/nodes-scheduler-default.adoc#nodes-scheduler-default[default scheduler to control pod placement]. + +[id="informational-resources_{context}"] +== Informational Resources + +These resources should only be read for to retrieve information about the cluster, they should not be edited directly. + +[cols="2a,2a,8a",options="header"] +|=== +|Resource name|Instance name|Description + +|clusterversion.config.openshift.io +|version +|In {product-title} {product-version}, you must not customize the ClusterVersion +resource for production clusters. Instead, follow the process to +xref:../../updating/updating-cluster.adoc#updating-cluster[update a cluster]. + +|dns.config.openshift.io +|cluster +|You cannot modify the DNS settings for your cluster. You can +xref:../../networking/dns-operator.adoc#dns-operator[view the DNS Operator status]. + +|infrastructure.config.openshift.io +|cluster +|Configuration details allowing the cluster to interact with its cloud provider. + +|network.config.openshift.io +|cluster +|You cannot modify your cluster networking after installation. If you must +customize your network, you +xref:../../installing/installing_aws/installing-aws-network-customizations.adoc#installing-aws-network-customizations[customize networking during installation]. |=== @@ -122,13 +183,13 @@ that are based on many of these CRDs to add more functionality to your |Authentication |config.openshift.io | -|Not namespaced +|Global | |Build |config.openshift.io | -|Not namespaced +|Global | |CatalogSourceConfig @@ -146,13 +207,13 @@ that are based on many of these CRDs to add more functionality to your |ClusterAutoscaler |autoscaling.openshift.io | -|Not namespaced +|Global |Yes |ClusterDNS |dns.openshift.io | -|Not namespaced +|Global | |IngressController @@ -164,13 +225,13 @@ that are based on many of these CRDs to add more functionality to your |ClusterNetwork |network.openshift.io | -|Not namespaced +|Global | |ClusterOperator |config.openshift.io | -|Not namespaced +|Global | |ClusterOperator @@ -194,19 +255,19 @@ that are based on many of these CRDs to add more functionality to your |ClusterVersion |config.openshift.io | -|Not namespaced +|Global | |Config |imageregistry.operator.openshift.io | -|Not namespaced +|Global | |Config |samples.operator.openshift.io | -|Not namespaced +|Global | |Console @@ -219,7 +280,7 @@ new values. If it is deleted, it recreates automatically. |ControllerConfig |machineconfiguration.openshift.io | -|Not namespaced +|Global | |CredentialsRequest @@ -231,7 +292,7 @@ new values. If it is deleted, it recreates automatically. |DNS |config.openshift.io | -|Not namespaced +|Global | |EgressNetworkPolicy @@ -243,25 +304,25 @@ new values. If it is deleted, it recreates automatically. |HostSubnet |network.openshift.io | -|Not namespaced +|Global | |Image |config.openshift.io | -|Not namespaced +|Global | |Infrastructure |config.openshift.io | -|Not namespaced +|Global | |Ingress |config.openshift.io | -|Not namespaced +|Global | |InstallPlan @@ -273,13 +334,13 @@ new values. If it is deleted, it recreates automatically. |KubeControllerManager |operator.openshift.io | -|Not namespaced +|Global | |KubeletConfig |machineconfiguration.openshift.io | -|Not namespaced +|Global | |MachineAutoscaler @@ -297,13 +358,13 @@ new values. If it is deleted, it recreates automatically. |MachineConfigPool |machineconfiguration.openshift.io | -|Not namespaced +|Global | |MachineConfig |machineconfiguration.openshift.io | -|Not namespaced +|Global | |MachineDeployment @@ -333,13 +394,13 @@ new values. If it is deleted, it recreates automatically. |MCOConfig |machineconfiguration.openshift.io | -|Not namespaced +|Global | |NetNamespace |network.openshift.io | -|Not namespaced +|Global | |NetworkAttachmentDefinition @@ -351,31 +412,31 @@ new values. If it is deleted, it recreates automatically. |NetworkConfig |networkoperator.openshift.io | -|Not namespaced +|Global | |Network |config.openshift.io | -|Not namespaced +|Global | |OAuth |config.openshift.io | -|Not namespaced +|Global | |OpenShiftAPIServer |operator.openshift.io | -|Not namespaced +|Global | |OpenShiftControllerManagerOperatorConfig |openshiftcontrollermanager.operator.openshift.io | -|Not namespaced +|Global | |OperatorGroup @@ -393,7 +454,7 @@ new values. If it is deleted, it recreates automatically. |Project |config.openshift.io | -|Not namespaced +|Global | |Prometheus @@ -411,7 +472,7 @@ new values. If it is deleted, it recreates automatically. |ServiceCertSignerOperatorConfig |servicecertsigner.config.openshift.io | -|Not namespaced +|Global | |ServiceMonitor