Simplify installation process

lulf commented 6 years ago

why

Installing EnMasse require you to either:

Run a deployment script
Run ansible playbooks
Walk through a very long manual process

Ideally, the manual process should just be kubectl/oc create -f examples/enmasse instead of the ~20 commands required today. With the simplifications in this proposal, the manual process will be simpler, the deployment script will be simpler, and the ansible playbooks will be simpler. The complexity currently in the ansible playbooks will be moved into the component as part of a auto-create config.

Proposal

templates/install/resources will be reorganized into address-space-controller, api-server, standard-authservice, none-authservice and service-broker and moved directly under templates and represented as YAML. The image names are parameterized as ${ROUTER_IMAGE}, and envsubst is used to do replace as part of make.

The files will be named so that when folders are merged, they will not conflict, and can be used to construct 'bundles' of a particular configuration (i.e. enmasse-with-standard-authservice) as part of the release process. The resource filenames will also be prefixed to enforce an order when creating them using the directory.

templates/install/ansible will be moved into ansible at the top level. The ansible playbooks still provide value for those who manage systems using ansible.

templates/install/deploy.sh will be removed, as the simplified manuall process will make it irrelevant.

Resources that are today created dynamically, such as ServiceAccount, ClusterRoleBinding will need to be added to and managed by each component individually.

keycloak-controller deployment should have an added paramter, to indicate whether it should auto-create certs, keycloak-config, keycloak-credentials if they don't exist. In the example templates, this defaults to yes.

api-server should have an added parameter, to indicate whether it should auto-create certs, api-server-config and fetching the client cert for the kube API server.

address-space-controller need to retrieve the keycloak URL at run time.

The release bundle will contain the following folders:

docs - Documentation generated for a particular release
ansible - Ansible playbooks
examples/install/address-space-controller - Resources needed to deploy the Address Space Controller. Resources assume myproject as the namespace. To deploy: oc create -f address-space-controller
examples/install/api-server - Resources needed to deploy the Api Server. Resources assume myproject as the namespace. To deploy: oc create -f api-server
examples/install/service-broker - Resources needed to deploy the Service Broker. Resources assume myproject as the namespace. To deploy: oc create -f service-broker
examples/install/none-authservice - Resources needed to deploy the None Auth Service. Resources assume myproject as the namespace. To deploy: oc create -f none-authservice
examples/install/standard-authservice - Resources needed to deploy the Standard Auth Service. Resources assume myproject as the namespace. To deploy: oc create -f standard-authservice
examples/templates/enmasse-with-standard-authservice.yaml - OpenShift template for installing EnMasse with standard authentication service. To deploy: oc process -f enmasse-with-standard-authservice.yaml | oc create -f -
examples/tenant - Roles that can be applied to manage tenant RBAC access to creating resources.

Testing

Test should deploy with the example configs.

Documentation

Manual steps in the documentation should be updated to using the example bundles.

Tasklist

[x] Update api-server to auto-generate config if not exists
[x] Update keycloak-controller to auto-generate config if not exists
[x] Move generated YAML templates into coarser groups and enumerate filenames to indicate order.
[x] Move ansible roles and playbooks to top level
[x] Remove all jsonnet templates
[x] Update service-broker to auto-generate config
[x] Update travis and jenkins CI to use correct install procedure

k-wall commented 6 years ago

On the whole, I think this sounds like a real improvement.

Two questions:

After having installed using the new process, how will I completely uninstall the product?
If I am using product version 1, and version 1.1 is shipped, how do I upgrade? How does the process above support the requirement for incremental upgrades?

lulf commented 6 years ago

On the whole, I think this sounds like a real improvement.

Two questions:
After having installed using the new process, how will I completely uninstall the product? @k-wall These instructions should probably be added to the docs, but it would be something like
oc delete all -l app=enmasse -n <enmasse namespace>  alternatively oc delete <enmasse namespace>
oc delete clusterroles -l app=enmasse
oc delete apiservices -l app=enmasse
oc delete clusterservicebrokers -l app=enmasse # if deploying the service broker
If I am using product version 1, and version 1.1 is shipped, how do I upgrade? How does the process above support the requirement for incremental upgrades?

After spending some more time looking at this, I think we should have a folder per component as part of a release + a simple "bundle" to get started quickly (i.e. address-space-controller, api-server, standard-authservice, enmasse-bundle-with-standard-authservice). This will allow us to provide a good OOTB experience, as well as make it easy for users to upgrade component individually.

The upgrade depends on how the user chooses to customize the resources, but in general, if you want to upgrade components individually, it could be (assuming we have the folders address-space-controller, api-server, standard-authservice for instance)

Download new release bundle

Perform the upgrade per component

oc apply -f address-space-controller
oc apply -f api-server
oc apply -f standard-authservice

This will apply any differences between the resources, and (based on the Deployment Strategy in the Deployment resource for instance) do a rolling upgrade of each component.

Depending its configuration, the address-space-controller may start the upgrade process for the infrastructure backing each address space (this is planned in #1585 )

lulf commented 5 years ago

Closing as work is merged

EnMasseProject / enmasse