Hide Forgot
Title: Installation Utility Describe the issue: The described options for the oo-install tool are slightly out of date: the --create-config and --openshift-version options are currently invalid. Suggestions for improvement: Remove --create-config and --openshift-version from the list of options. Additional information: The currently valid options are visible on the install site: https://install.openshift.com/ Each option has been documented more fully in the Origin oo-install Users Guide[1]; consider going into similar detail (as they pertain to Enterprise) in the OSE Deployment Guide as well. [1] http://openshift.github.io/documentation/oo_install_users_guide.html#installer-command-line-options
*** Bug 1041631 has been marked as a duplicate of this bug. ***
The two outdated options have been removed from the screen output, but then I commented out the entire output anyway as it didn't seem relevant. Also added a variablelist with the current valid options as found from the link above. Only question would be if I have documented the -s option well enough. I have a feeling the user has to actually put in <none> if that's their choice method instead of leaving it as nothing like I have documented.
Thanks for the updates. I think getting rid of the -h output was a good move. The "none" option for -s is the default for Enterprise. Reading over the options, I do have some further requests while you're in the area... --- -a (--advanced-mode) The installation utility will install MongoDB and AcvtiveMQ on the system designated as the OpenShift broker host. Use the -a option if you want to install these services on a different host. ==> The "will" here sort of implies that this is what the option does, not the default behavior. It's jarring to then move on to what the option does. I suggest: === -a (--advanced-mode) By default, the installation utility installs MongoDB and AcvtiveMQ on the system designated as the OpenShift broker host. Use the -a option to enable installing these services on a different host. --- --- -c (--config-file) FILE_PATH oo-install will search for a configuration file in the default location. If you wish to use a different file, use the -c option with the correct filepath. If the specified file does not exist, a file will be created with some basic settings. ==> There's no "searching", and again the use of "will" for the default behavior seems jarring. Also it would be nice to mention where the conf file is by default. I suggest: === -c (--config-file) FILE_PATH Use this option to specify a configuration file to use instead of the default location (~/.openshift/oo-install-cfg.yml). If the file does not exist, a file will be created with some basic settings. --- --- -w (--workflow) WORKFLOW_ID If you have an already configured OpenShift deployment, use the install tool with the -w option and the ID of the previous workflow to run the installation tool without any user interaction. The previous deployment will be checked for problems, and if none are found, oo-install will run the specified workflow. ==> There's only really one workflow ID that makes any sense for enterprise users, the "enterprise_deployment" workflow. Why not just go ahead and mention this specifically? I suggest: === -w (--workflow) WORKFLOW_ID If you already have an OpenShift Enterprise deployment configuration file, use the install tool with the -w option and the workflow ID "enterprise_deployment" to run the deployment without any user interaction. The configuration will be checked for problems and deployed if none are found. This is useful for restarting after a failed deployment or for running multiple similar deployments. --- --- -e (--enterprise-mode) The -e option will provide you with options for installing or extending an OpenShift Enterprise deployment. ==> I would suggest not even including this option. It's really only relevant if they got the Origin installer, and why do that when you can just add /ose/ to the URL? And that's the direction all the docs point to, so... just remove it? --- -s (--subscription-type) TYPE The -s option refers to the type of RPM your deployment uses, and works with the -w option to enable you to override the installer configuration file. Not using any of the following types will tell the installation tool to use any manually configured repositories or the included OpenShift RPMs. yum The yum type tells the installation tool that new yum repository entries should be created for you in the /etc/yum.repos.d/ rhsm The rhsm type tells the installation tool to use Red Hat Subscription Manager to configure the OpenShift software channels. rhn The rhn type tells the installation tool to use the Red Hat Network to configure the OpenShift software channels. ==> To be clear, the RPMs installed should be the same regardless. This is about *how* they get them. Since this is Enterprise, we want to steer them toward using RHSM or RHN Classic. The "yum" and "none" methods are for them making other arrangements. "none" is in fact the default, but I think it would be better to say that in the table rather than with separate text up front. === -s (--subscription-type) TYPE The -s option determines how the deployment will obtain the RPMs needed to install OpenShift Enterprise, and overrides any method specified in the configuration file. It should be one of: rhsm The installation tool will use Red Hat Subscription Manager to register and configure the OpenShift software channels according to user, password, and pool settings. rhn The installation tool will use RHN Classic to register and configure the OpenShift software channels according to user, password, and optional activation key settings. yum The installation tool will create new yum repository entries in /etc/yum.repos.d/ according to several repository URL settings. This is not a standard subscription and assumes you have already created or have access to these repositories in the layout specified in openshift.sh. none This is the default. Use this option when the software subscriptions on your deployment hosts are already configured as desired and no changes should be made. --- --- -u (--username) USERNAME Using the -u option is useful when you are running an unattended installation using the rhsm or rhn subscription methods. -p (--password) PASSWORD Like the -u option, the -p option is useful when you are running an unattended installation with the rhsm or rhn subscription methods. ==> Actually these are useful regardless of attended/unattended. The point is that they specify these settings regardless of what is in the config file. Suggested: === -u (--username) USERNAME Use the -u option to specify the user for the rhsm or rhn subscription methods on the command line instead of in the configuration file. -p (--password) PASSWORD Like the -u option, use the -p option to specify the password for the rhsm or rhn subscription methods on the command line instead of in the configuration file. As an alternative, the interactive installer mode also provides an option for entering subscription parameters for one use without saving them. --- Could I also suggest a change to the flow here? It seems kind of awkward to discuss the options before even introducing how to get it and run it. Could "Procedure 4.1. To Run the Installation Utility:" come before the discussion of options? And one other thing about that procedure - I don't think sysadmins will be crazy about running shell scripts directly from the internet. I would start with the "download, unzip, run" option and present the "sh <(curl" option as the convenient alternative. --- Run the following command to interactively configure and deploy one or more hosts using the installation utility. [...] A further alternative is to run the https://install.openshift.com/portable/oo-install-ose.zip zip file directly from the Internet rather than downloading it. ==> Suggest: === Use the following commands to download, unpack, and execute the installation utility to interactively configure and deploy one or more hosts: $ wget https://install.openshift.com/portable/oo-install-ose.zip $ unzip oo-install-ose.zip $ ./oo-install-ose A convenient alternative is to run the installation tool directly from the Internet rather than downloading it: $ sh <(curl -s https://install.openshift.com/ose/) Note that using the https://install.openshift.com/ose/ URL instead of https://install.openshift.com/ automatically runs the utility in OpenShift Enterprise mode instead of OpenShift Origin mode. Additional options can be used with the command, such as -s and -u: $ ./oo-install-ose -s rhsm -u user or $ sh <(curl -s https://install.openshift.com/ose/) -s rhsm -u user ---
As a correction to the correction... the workflow ID should be "enterprise_deploy" not "enterprise_deployment".
-a: I agree about the sentence being jarring. Changed to: "By default, the installation utility installs MongoDB and AcvtiveMQ on the system designated as the OpenShift broker host. Use the <option>-a</option> option to install these services on a different host." I left out the 'enable' part in the second sentence, because I'm not sure if anything is being enabled exactly. According to the Origin docs, it's more about installing the services on different machines. Let me know if I've misunderstood. -c: Changed to: "Use the -c option with the desired filepath to specify a configuration file other than the default location of ~/.openshift/oo-install-cfg.yml. If the specified file does not exist, a file will be created with some basic settings." -w: Changed to: "If you already have an OpenShift Enterprise deployment configuration file, use the install tool with the -w option and the enterprise_deployment workflow ID to run the deployment without any user interaction. The configuration will be assessed, then deployed if no problems are found. This is useful for restarting after a failed deployment or for running multiple similar deployments." -e: I agree. -e has been removed. -s: Suggested changed have been made, aside from: "none -- Not using a type is the default setting. Use this option when the software subscriptions on your deployment hosts are already configured as desired and changes are not needed." -u: Changed: "Use the -u option to specify the user for the RHSM or RHN Classic subscription methods from the command line instead of in the configuration file." -p: Changed: Like the -u option, use the -p option to specify the password for the RHSM or RHN Classic subscription methods from the command line instead of in the configuration file. As an alternative, the interactive installer mode also provides an option for entering subscription parameters for a one-time use without them being saved to the system. Personally, I think it's best to have the options before the procedure. This means that the reader will have all the info before they start running commands and then think 'hmm, sure could've done with that info sooner'. Not that every reader will do this, but you don't want to run the risk. Plus, I think this is the flow we've had through the docs. Let me know if you disagree still. Procedure: Using the zip method first is a good idea. Pretty much the suggested changes. Probably best to check it out rather than me putting the whole thing in here :P I also changed the formalpara about prerequisites to an important box. Before, it seemed like everything we've been changing here was part of the formalpara, as they don't really have a visible end point. Now, it's contained. Plus, the information is important.
Typo note: AcvtiveMQ => ActiveMQ About -a and "enabling" -- that's fine. I suggested "enabling" because you aren't forced to put the services on different hosts, it just enables the option to configure it that way. The ordering of options-before-command still seems a little odd to me, but I guess it's good to present things consistently. Minor thing I noticed: $ ./oo-install-ose Option Since there is often no need for options, or may be multiple options... should it be in brackets or something to indicate the options are in fact optional? Looks a little odd as-is. $ ./oo-install-ose [options] In any case, looks pretty good, thanks!
Thanks, Luke. Typo corrected. I also made the $ ./oo-install-ose Option command a step on its own. That way I can replicate the other command and put in a separate paragraph about adding options: "1. Download and unpack the installation utility: $ wget https://install.openshift.com/portable/oo-install-ose.zip $ unzip oo-install-ose.zip 2. Execute the install utility to interactively configure one or more hosts: $ ./oo-install-ose 3. Additional options can be used with the command: $ ./oo-install-ose -s rhsm -u user" Luke, maybe let me know if you think the wording may need to change.
Looks good, ship it!