diff --git a/doc/source/external_access.rst b/doc/source/external_access.rst new file mode 100644 index 00000000..d299f388 --- /dev/null +++ b/doc/source/external_access.rst @@ -0,0 +1,98 @@ +.. _external_access: + +======= +Ingress +======= + +One of the ways to make services in Kubernetes externally-reachable is to use +Ingress. This page describes how it can be enabled and used in CCP. + +Ingress controller +~~~~~~~~~~~~~~~~~~ + +In order to make Ingress work, the cluster should have an Ingress controller. +You can use any implementation of it, the only requirement is that it should +be configured to use TLS. + +There is a script :file:`deploy-ingress-controller.sh` in +:file:`fuel-ccp/tools/ingress` directory for testing purposes that can do it +for you. It will deploy traefik ingress controller and expose it as a k8s +service. The only required parameter is one of the k8s nodes IP which need to +be specified with `-i`. Ingress controller will be configured to use TLS. If +certificate and key were not provided with script parameters, the will be +generated automatically. + +Enable Ingress in CCP +~~~~~~~~~~~~~~~~~~~~~ + +The following parameters are responsible for Ingress configuration: + +:: + + configs: + ingress: + enabled: False + domain: external + port: 8443 + +Ingress is disabled by default. To enable it, `enabled` config option should +be set to `True`. Optionally domain and port can be changed. + +.. NOTE:: There's no option to run Ingress without TLS. + +.. NOTE:: `port` parameter should match HTTPS port of Ingress controller. + +.. NOTE:: For multiple OpenStack deployments highly recommended to use + different `domain`s or run multiple Ingress controllers with + configured namespace isolation. + +To get all Ingress domains of the current deployment you can run +:command:`ccp domains list` command: + +:: + + +------------------------------+ + | Ingress Domain | + +------------------------------+ + | application-catalog.external | + | identity.external | + | orchestration.external | + | image.external | + | object-store.external | + | network.external | + | ironic.external | + | volume.external | + | console.external | + | data-processing.external | + | horizon.external | + | compute.external | + | search.external | + +------------------------------+ + +All of them should be resolved to the exposed IP of the Ingress controller. +It could be done with DNS or /etc/hosts. + +The following command will prepare /etc/hosts for you. Only IP of the Ingress +controller (and configuration file if needed) should be specified: + +:: + + echo INGRESS_CONTROLLER_IP $(ccp domains list -q -f value) | sudo tee -a /etc/hosts + + +Expose a service with Ingress +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To expose one of the ports of a service with Ingress, `ingress` parameter with +subdomain should be specified in the config section associated with that port: + +:: + + configs: + public_port: + cont: 5000 + ingress: identity + +During the :command:`ccp deploy` command execution Ingress objects will be +created and all :ref:`address` occurrences with enabled `external` flag will be +substituted with proper Ingress domains. diff --git a/doc/source/index.rst b/doc/source/index.rst index 8563b2ee..945fcfe5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,6 +17,7 @@ User docs config/index config/types bootstrapping + external_access Advanced topics ---------------