Understanding Inputs

RightScripts

Before you create new inputs it's strongly recommended that you check RightScale's latest published ServerTemplates to see if a similar input already exists. For example, to reference the fully qualified domain of the master database, use MASTER_DB_DNSNAME, which is used by many RightScale scripts instead of creating your own input with a slightly different name.

Chef Recipes

#
# Cookbook Name:: db
#
# Copyright RightScale, Inc. All rights reserved. All access and use subject to the
# RightScale Terms of Service available at http://www.rightscale.com/terms.php and,
# if applicable, other agreements such as a RightScale Master Subscription Agreement.

rightscale_marker :begin

DATA_DIR = node[:db][:data_dir]

user = node[:db][:admin][:user]
log "Adding #{user} with administrator privileges for all databases."

db DATA_DIR do
  privilege "administrator"
  privilege_username user
  privilege_password node[:db][:admin][:password]
  privilege_database "*.*" # All databases
  action :set_privileges
end

rightscale_marker :end

attribute "db/admin/user",
  :display_name => "Database Admin Username",
  :description => "The username of the database user with 'admin' privileges (e.g., cred:DBADMIN_USER).",
  :required => "required",
  :recipes => [ 
      "db::install_server", 
      "db::setup_privileges_admin" 
  ]
  
attribute "db/admin/password",
  :display_name => "Database Admin Password",
  :description => "The password of the database user with 'admin' privileges (e.g., cred:DBADMIN_PASSWORD).",
  :required => "required",
  :recipes => [ 
       "db::install_server", 
       "db::setup_privileges_admin" 
  ]
  

Where should I define inputs?

As a best practice, you should define a majority of your inputs at either the ServerTemplate or deployment level.

You should only define inputs at the server or server array levels for performing tests or under unique circumstances. In a production environment, all inputs should inherit their values from previous levels (deployment level and below). The key benefit of defining inputs at the deployment level or below is that you can more easily maintain consistent server configurations across your entire deployment and associated arrays, because you can go to a single location (the deployment's Inputs tab) to see which input values are being used and know where those values are being inherited from. It's easier to troubleshoot problems within a deployment if you follow strict processes for defining inputs. For example, a problem within a deployment could be caused by the wrong input value being used by a server because the incorrect value was overwritten at the server level. 

Although you have the flexibility to define inputs at the server or server array level, it's not a recommended best practice for most use cases. Unless you're an advanced user with unique configuration circumstances, you should only set an input parameter at the server level for development and testing purposes. An example might be that you've cloned a server and want to test it with a slightly different input parameter. One of the problems with defining input values at the server or server array (highest precedence) level is that it's difficult to keep track of a server's inputs. For example, if you need to troubleshoot a configuration problem you might have to manually check each server's Inputs tab to investigate the cause of the problem. However, setting input parameters at the Server level can prove to be quite useful in the right situation.

When should I define values for inputs?

As a best practice, you should always define any inputs that are required by any boot/decommission scripts before you try to launch a server or enable a server array. Ideally, when a server is launched either manually or automatically, it inherits input values that were previously defined at one of the inheritance levels.

As a safety precaution, you are not allowed to manually launch a server if there are required inputs with missing values. If you try to launch a server that contains missing inputs, you will receive an error message that prompts you to provide values for any missing inputs that are highlighted in red. The following example screenshot shows an error message for missing inputs.

If you receive this error message, you should cancel the server launch. At this point, you should go back and define values for any missing (required) inputs under the deployment's Inputs tab before launching the server again.

Although you can provide values for any missing inputs on this screen and continue the launch process, it's not a recommended best practice.  See the following section for details.

What is the difference between "Launch" and "Save and Launch"?

When you manually launch a single server from the Dashboard, the "Inputs Confirmation" screen displays which user-defined values are used for the declared inputs. When values have been provided for the missing inputs, you can continue the launch process.

At this point, you have two options if are going to continue launching the server. It's important to understand the difference between these two distinct actions.

• Launch - The current server will be launched with the specified input values. However, the specified values for the missing inputs will only be applied to the current server that's being launched. Any values that are provided at this screen for missing inputs will not be preserved. So, if the server is relaunched (thereby terminating the current server and launching a new server), the same inputs will be missing values. As a result, the new server will become "stranded in booting" and fail to reach the operational state. If you want to preserve the specified inputs for future launches, you must define the same values at the deployment (recommended) or server level. If you want to preserve the input at the server level, you must define it under the "Next" server's Inputs tab, which affects future launches and relaunches of that server.
• Save and Launch - The current server will be launched with the specified input values and the values will be saved at the server level. The same input values will be saved under the server's "Next" Inputs tab, which affects future launches and relaunches of that server. To follow best practices you should not define inputs at the server level because it overwrites values set at one of the other inheritance levels. It's recommended that you define any inputs that you want to preserve at the deployment level or below.

Can I define multiple values for an input?

Yes, although it is not a recommended best practice for most use cases.

Ideally, you should only have a single input to represent a particular value. If you're using RightScale's published ServerTemplates, you should  verify whether or not an input already exists that represents the value you're trying to parametize before you create a new one. Avoid creating multiple inputs that are designed to represent the same value. For example, inside of a single script or across multiple scripts, you shouldn't have two inputs that are used to pass the name of your application (e.g. Application Name, Application). If you are using several different ServerTemplates within a single deployment, you can go to the deployment's Inputs tab to see if there are multiple inputs where the same value is being used. If such cases do exist, you may want to consider consolidating the inputs.

At the deployment level, you can only define one value for an input. However, you may have a deployment that contains servers where different values are used for the same input depending on its ServerTemplate. This type of configuration might be appropriate in certain use cases. For example, you may have two different types of application servers that connect to a database server on different ports. As long as you don't override the input at the deployment or server/array level, each server can inherit a different value if it's set at the ServerTemplate level. The following example screesnshot shows the ServerTemplate inheritance in a deployment.

Remember, where you define inputs determines which value is used. By using the input hierarchy correctly, you can accurately control which values are ultimately inherited and used by a script.

Can I hide a sensitive value for an input?

Yes. RightScale's Credential Store (Design -> Credentials) allows you to create credentials for hiding sensitive values where you can hide the actual value from users in the Dashboard, but still allow that value to be passed to a script at execution time. For example, as a database system administrator, you might want to hide your database's administrator username and password from other members of your team, however those secret credentials need to be applied to the database setup scripts in order to properly launch and configure the database servers. In such cases, you can create a credential for each sensitive value.

A user will need 'designer' user role privileges to create a credential. Only the user who created the credential and other users with 'admin' user role privileges will be able to see the hidden value of a credential.

How do I update an input on a running server?

Remember, a server receives its inputs when it's launched. Once a server becomes operational, the inputs that it was originally launched with are static and can be seen under the "current" server's Inputs tab. (The "next" server's Inputs tab shows which inputs will be used to launch the next iteration of that server that results from either a launch or relaunch action.)  You can execute any of the scripts defined by the server's ServerTemplate during runtime, even boot and decommission scripts.

If you want to change one of the inputs on the current server, you can run a script that uses the input. However, you must specify the new value for the input under the "current" server's Inputs tab before you run the script. Input hierarchy rules do not apply anymore because the server is already operational.

Typically, you will only need to run one of the boot/operational/decommission scripts. However, you can also use the 'Any Script' option to execute any script in your RightScale account.

Note: When you use the 'Any Script' option, the new inputs will not be saved to the "current" server's Inputs tab, however they will be recorded in the audit entry.

It's important to remember that when you change the input on a running server, the change is not automatically preserved. If you want to save the modified input for future iterations of that server, you need to update the Inputs tab at one of the input inheritance levels, preferably the deployment level.

Does the "Current" server's Inputs tab always reflect what the server was originally launched with?

No. Remember, since you can change an input on a running server, the "current" server's Inputs tab can change over the lifetime of the server. As a result, the "current" server's Inputs tab may not reflect which inputs were used to originally launch the server. However, you can check the server's audit entries for details.