diff --git a/README.md b/README.md index 972aff505..64c17b9aa 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,126 @@ -# Cluster Ingress Operator +# OpenShift Ingress Operator -Cluster Ingress Operator deploys and manages [HAProxy](http://www.haproxy.org) to provide highly available network ingress in [OpenShift](https://openshift.io/), enabling both OpenShift [Routes](https://docs.okd.io/latest/rest_api/apis-route.openshift.io/v1.Route.html) and Kubernetes [Ingresses](https://kubernetes.io/docs/concepts/services-networking/ingress/). +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. -The operator tries to be useful out of the box by creating a working default deployment based on the cluster's configuration. +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). -* On cloud platforms, ingress is exposed externally using Kubernetes [LoadBalancer Services](https://kubernetes.io/docs/concepts/services-networking/#loadbalancer). -* On Amazon AWS, the operator publishes a wildcard DNS record based on the [cluster ingress domain](https://github.com/openshift/api/blob/master/config/v1/types_ingress.go) and pointing to the service's load-balancer. +Ingress Operator implements the OpenShift [ingresscontroller API](https://github.com/openshift/api/blob/master/operator/v1/types_ingress.go). -## How to help +## Installing -See [HACKING.md](HACKING.md) for development topics. +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. + +To scale an ingress controller: + +```shell +$ oc scale \ + --namespace=openshift-ingress-operator \ + --replicas=1 \ + ingresscontroller/ + +$ oc patch \ + --namespace=openshift-ingress-operator \ + --patch='{"spec": {"replicas": 2}}' \ + --type=merge \ + ingresscontroller/ +``` + +**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/ +``` + +**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 +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 -## Reporting issues +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. -Bugs are tracked in [Bugzilla](https://bugzilla.redhat.com/enter_bug.cgi?product=OpenShift%20Container%20Platform&version=4.0.0&component=Routing). +![Image of LoadBalancerService](docs/images/endpoint-publishing-loadbalancerservice.png) + +#### HostNetwork + +The `HostNetwork` strategy uses host networking to publish the ingress +controller directly on the node host where the ingress controller is deployed. + +![Image of HostNetwork](docs/images/endpoint-publishing-hostnetwork.png) + +#### Private + +The `Private` strategy does not publish the ingress controller. + +![Image of Private](docs/images/endpoint-publishing-private.png) + +## 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/ +``` + +## 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. diff --git a/docs/images/endpoint-publishing-hostnetwork.png b/docs/images/endpoint-publishing-hostnetwork.png new file mode 100644 index 000000000..288569952 Binary files /dev/null and b/docs/images/endpoint-publishing-hostnetwork.png differ diff --git a/docs/images/endpoint-publishing-loadbalancerservice.png b/docs/images/endpoint-publishing-loadbalancerservice.png new file mode 100644 index 000000000..7a6e22e26 Binary files /dev/null and b/docs/images/endpoint-publishing-loadbalancerservice.png differ diff --git a/docs/images/endpoint-publishing-private.png b/docs/images/endpoint-publishing-private.png new file mode 100644 index 000000000..1fff29800 Binary files /dev/null and b/docs/images/endpoint-publishing-private.png differ