docs: update README #155
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,17 +1,126 @@ | ||
| # OpenShift Ingress Operator | ||
|
|
||
| Ingress Operator is an [OpenShift](https://www.openshift.com) component which enables external access to cluster services by configuring Ingress Controllers, which route traffic as specified by OpenShift [Route](https://docs.openshift.com/container-platform/3.11/architecture/networking/routes.html) and Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) resources. | ||
|
|
||
| To provide this functionality, Ingress Operator deploys and manages an | ||
| [OpenShift router](https://github.com/openshift/router) — a | ||
| [HAProxy-based](https://www.haproxy.com) Kubernetes [ingress | ||
| controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers). | ||
|
|
||
| Ingress Operator implements the OpenShift [ingresscontroller API](https://github.com/openshift/api/blob/master/operator/v1/types_ingress.go). | ||
|
|
||
| ## Installing | ||
|
|
||
| Ingress Operator is a core feature of OpenShift and is enabled out of the box. | ||
|
|
||
| Every new [OpenShift installation](https://github.com/openshift/installer) | ||
| has an `ingresscontroller` named `default` which can be customized, | ||
| replaced, or supplemented with additional ingress controllers. To view the | ||
| default ingress controller, use the `oc` command: | ||
|
|
||
| ```shell | ||
| $ oc describe --namespace=openshift-ingress-operator ingresscontroller/default | ||
| ``` | ||
|
|
||
| ## Managing | ||
|
|
||
| Create and edit `ingresscontroller.operator.openshift.io` resources to manage | ||
| ingress controllers. | ||
|
|
||
| Interact with ingress controllers using the `oc` command. Every ingress | ||
| controller lives in the `openshift-ingress-operator` namespace. | ||
|
There was a problem hiding this comment.
should we say, by default? There was a problem hiding this comment. For now, we do not handle a |
||
|
|
||
| To scale an ingress controller: | ||
|
|
||
| ```shell | ||
| $ oc scale \ | ||
| --namespace=openshift-ingress-operator \ | ||
| --replicas=1 \ | ||
| ingresscontroller/<name> | ||
|
|
||
| $ oc patch \ | ||
| --namespace=openshift-ingress-operator \ | ||
| --patch='{"spec": {"replicas": 2}}' \ | ||
| --type=merge \ | ||
| ingresscontroller/<name> | ||
| ``` | ||
|
|
||
| **Note:** Using `oc scale` on an `ingresscontroller` where `.spec.replicas` is unset will currently return an error ([Kubernetes #75210](https://github.com/kubernetes/kubernetes/pull/75210)). | ||
|
|
||
| ## Customizing | ||
|
|
||
| Create new `ingresscontroller` resources in the `openshift-ingress-operator` | ||
| namespace. | ||
|
|
||
| To edit an existing ingress controller: | ||
|
|
||
| ```shell | ||
| $ oc edit --namespace=openshift-ingress-operator ingresscontroller/<name> | ||
| ``` | ||
|
|
||
| **Important:** Updating an ingress controller may lead to disruption for public | ||
| facing network connections as a new ingress controller revision may be rolled | ||
| out. | ||
|
|
||
| Refer to the [ingresscontroller API](https://github.com/openshift/api/blob/master/operator/v1/types_ingress.go) for full details on defaults and | ||
| customizing an ingress controller. The most important initial customizations are | ||
| domain and endpoint publishing strategy, as they *cannot currently be changed | ||
| after the ingress controller is created*. | ||
|
|
||
| ### Endpoint publishing | ||
|
|
||
| The `.spec.endpointPublishingStrategy` field is used to publish the ingress | ||
|
There was a problem hiding this comment. I'm not sure what "publish the ingress controller endpoints to other networks" means; is that referring to DNS? There was a problem hiding this comment. Basically lifted from our new public API docs; do you feel the API docs are similarly confusing? What would you propose here as an alternative, and would you suggest we upstream a change as well? |
||
| controller endpoints to other networks, enable load balancer integrations, etc. | ||
|
|
||
| Every strategy is described in detail in the [ingresscontroller API](https://github.com/openshift/api/blob/master/operator/v1/types_ingress.go). A brief | ||
| design diagram for each is shown below. | ||
|
|
||
| #### LoadBalancerService | ||
|
|
||
| The `LoadBalancerService` strategy publishes an ingress controller using a | ||
| Kubernetes [LoadBalancer | ||
| Service](https://kubernetes.io/docs/concepts/services-networking/#loadbalancer) | ||
| and on some platforms offers managed wildcard DNS. | ||
|
|
||
|  | ||
|
|
||
| #### HostNetwork | ||
|
|
||
| The `HostNetwork` strategy uses host networking to publish the ingress | ||
| controller directly on the node host where the ingress controller is deployed. | ||
|
|
||
|  | ||
|
|
||
| #### Private | ||
|
|
||
| The `Private` strategy does not publish the ingress controller. | ||
|
|
||
|  | ||
|
There was a problem hiding this comment. I do not see any service in There was a problem hiding this comment. There is the "internal" service, which we create irrespective of the endpoint publishing strategy; might be worth adding to the diagrams. There was a problem hiding this comment. Do admins care about the internal service? Is the internal service useful for anything but communications between the ingress controller and other OpenShift components (e.g. prometheus)? Would the internal service be a candidate for a separate internal architecture design? There was a problem hiding this comment. The internal service is the only predictable endpoint by which pods can connect to a private ingresscontroller, without additional configuration on the part of the cluster administrator. There was a problem hiding this comment. Any pods on the cluster, infrastructure or end-user, that need to connect to any routes that are served by the private ingresscontroller. There was a problem hiding this comment. It may be that we want to recommend a different approach (other than using the internal service that the operator creates) for this use-case. There was a problem hiding this comment. Is it fair to characterize the internal service as an implementation detail at this time? |
||
|
|
||
| ## Troubleshooting | ||
|
|
||
| Use the `oc` command to troubleshoot operator issues. | ||
|
|
||
| To inspect the operator's status: | ||
|
|
||
| ```shell | ||
| $ oc describe clusteroperators/ingress | ||
| ``` | ||
|
|
||
| To view the operator's logs: | ||
|
|
||
| ```shell | ||
| $ oc logs --namespace=openshift-ingress-operator deployments/ingress-operator | ||
| ``` | ||
|
|
||
| To inspect the status of a particular ingress controller: | ||
|
|
||
| ```shell | ||
| $ oc describe --namespace=openshift-ingress-operator ingresscontroller/<name> | ||
| ``` | ||
|
There was a problem hiding this comment. How about logs for the ingress controller (i.e., router)? $ oc logs --namespace=openshift-ingress deployments/router-<name>(Are we going to rename "router" to "ingress-controller"?) There was a problem hiding this comment. Waffled on this one... is exposing a potentially volatile naming convention problematic? Is there some other way we could direct users to the logs via the ingresscontroller? Random ideas:
|
||
|
|
||
| ## Contributing | ||
|
|
||
| Report issues in [Bugzilla](https://bugzilla.redhat.com/enter_bug.cgi?product=OpenShift%20Container%20Platform&version=4.0.0&component=Routing). | ||
|
|
||
| See [HACKING.md](HACKING.md) for development topics. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"a"→"an"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The name of the operator repo is "cluster-ingress-operator". The title of the doc is "OpenShift Ingress Operator".
ClusterIngresshas now transitioned toIngressController. OpenShift includes CR's forcluster/ingresses.config.openshift.ioand supports the KubernetesIngressresource. I can see how a user would get confused. Should the name of the repo and readme title be more closely align toIngressController? For example, repo name "ingress-controller-operator" and title "OpenShift Ingress Controller Operator"?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Changing the name of the repository is a more onerous endeavor and goes beyond the scope of this PR IMO. Otherwise, the naming makes sense to me: the ingress operator manages the ingress controller, which works with the ingress (sort of) and (really) route resources.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ingress Controller Operator vs. Ingress Operator sounds like a good list discussion.
Changing the labels, annotations, and resource names would have a few considerations, mostly self-contained to this project, although we have to be careful about resource names (which I believe are currently being used as an informal contract in some cases and which could potentially be replaced by stable label selectors).
Changing the repo name would have enough ripple effects to warrant its own design document (this isn't meant to be snarky — just a statement of fact for consideration).