You either need administrative access to the Windows OS of your existing vCenter Server (5.1 or higher) installation, or you need a functional vRealize Automation installation (see the introduction to Chapter 7, Working with VMware Infrastructure, for more information).

This recipe is not the same for vCenter-integrated and vRA-integrated Orchestrator implementations. There is a slight difference.

On your marks, get set, GO!

When you install vCenter, you also automatically install Orchestrator; however, what you probably don't know is that the installer also configures Orchestrator to use the vCenter database, registers itself with SSO, and configures the vCenter plugin. Orchestrator is now easily accessible and fully configured to work with vCenter/vRA.

That said, one needs to understand that we have just started another hungry service on vCenter/vRA VM. As already discussed in the introduction, you might want to rethink this.

Looking at how the vCenter-integrated Orchestrator is configured, we find that the whole configuration process is triggered by the vco.properties file in the C:\Program Files\VMware\Infrastructure\Orchestrator directory. It contains all relevant information, but no passwords.

If you look into Orchestrator's configuration using the Orchestrator Configuration tool (see the Two ways to configure Orchestrator recipe in this chapter), you will find the following configurations:

This all makes the vCenter Orchestrator installation the most easy to use for beginners. Basically, you only have to start the Orchestrator service on vCenter Server and you are ready to go.

If you get an error while starting the Orchestrator service, have a quick look at C:\Program Files\VMware\Infrastructure\Orchestrator\app-server\logs. There is a file called server.log. This is the logfile for the Orchestrator service. The most common problem at this point is that the database cannot be accessed. If this is the case, I would recommend switching the database type to embedded.

To fully integrate Orchestrator into your vCenter, continue with the Integrating Orchestrator into SSO and vSphere Web Client recipe in this chapter as well as the recipe Orchestrator and vSphere Web Client in Chapter 5, Basic Orchestrator Operations.

We can deploy the Orchestrator appliance on either a vSphere environment or on VMware Workstation (or Fusion if you are a MAC user).

The Orchestrator appliance needs the following (defaults):

In this recipe, we will learn how to download and deploy Orchestrator.

vCO 5.5.2.1 appliance is a preconfigured Orchestrator installation that uses the following:

Everything is ready to run; however, no integration with vCenter or any external service is configured. The Orchestrator appliance comes with a 90-day evaluation license installed.

The LDAP has the following preconfigured entries:

Both LDAP and DB are protected to allow only local access to them.

If you want to deploy the Orchestrator appliance on VMware Workstation, the process of deploying the Orchestrator appliance differs from the one described in this recipe. Follow these steps instead:

See the Tuning the appliance recipe in Chapter 2, Optimizing Orchestrator Configuration.

To get the Windows install working, we need the following:

We assume that you are installing Orchestrator on a freshly installed Windows VM.

The Windows Orchestrator version now also comes with embedded LDAP and database, making the first steps much easier.

The embedded database and LDAP can't be as easily accessed as with the appliance because there isn't really a need to do so. If you want to be serious about Orchestrator, you should use an external database and you will want to use at least your Active Directory (AD), if not SSO, as an authentication source.

The Windows installation also comes with a 90-day evaluation license.

We need an Orchestrator instance up and running, as described in the recipes about installing.

To use the Configuration tool, we just need a web browser; and for the workflow method, we need either a local Java install to start the Java Web Client or an installed Orchestrator Client.

There are two ways to configure Orchestrator; I would encourage you to explore both.

Using the Orchestrator Configuration tool

If you are using the Orchestrator appliance, read the Accessing the Orchestrator Configuration tool section of this recipe. If you are using the Windows or vRA-integrated Orchestrator, follow these steps.

Windows or vCenter-integrated Orchestrator

1. In Windows, open Services. For example, in Win 2008 R2, navigate to Start | Administrative Tools | Services.
2. Right-click and start the VMware vCenter Orchestrator Configuration service.
3. Wait until the service has started successfully.

vRA-integrated Orchestrator

1. Log in to the vRA appliance OS using the root account.
2. Run the following command:

   service vco-configurator start
   

3. Now access the Orchestrator Configuration tool.
4. Wait until the service has started successfully.

Accessing the Orchestrator Configuration tool

1. Open a web browser and enter https://[ip OR FQDN of Orchestrator]:8283.
2. In the Orchestrator configuration login screen, enter vmware as the username and the password you assigned during the deployment. If you are using the Windows or vRA-integrated installation, the initial password is vmware. As soon as you are logged in, you will be requested to change the password.

The Orchestrator configuration page opens as shown in the following screenshot:

Here are all the sections that can be used to configure Orchestrator.

The Orchestrator Configuration tool is an independent service in Windows as in Linux. The service doesn't require to be switched on all the time; it is more or less a one-off tool to get the initial deployment working.

The Orchestrator Configuration tool was commonly used to configure Orchestrator, and you will find countless websites still quoting it. It is a generally straightforward tool that helps you configure Orchestrator. The trick is to work your way down, starting with the General section. Every time you configure an item correctly, the little light next to the section title will switch to green. The light turns red if the item is not configured or is misconfigured. When you log in to Orchestrator for the first time, you will notice that all the lights are green; this is because it uses the preconfigured settings. You can still reconfigure all items to your own specifications.

Working with errors in the workflow method

If the workflow doesn't run successfully, you probably will want to know why and resolve the error. To do so, follow these steps:

1. Click on the failed workflow execution. It has a red icon with a white X in it.
2. Click on Schema.
3. Click on Variables.
4. The error message is displayed in red.
5. To start the workflow again, just right-click on the failed execution and select Run Again.

This will start the workflow again; however, it preserves all the information you have entered already into the workflow. No retyping is needed as everything from the last run is still displayed in the forms. The only exceptions are passwords, which is a good thing.

There is actually a third way of configuring Orchestrator. Using the REST API of Orchestrator, you can connect to Orchestrator Server and run the configuration workflows. Showcasing this is beyond the scope of this book; however, you can find some instruction in the Orchestrator documentation and also in the Accessing the Orchestrator API via REST recipe in Chapter 6, Advanced Operations.

You need an installed and running Orchestrator. You should also be comfortable with using one of the methods described in the Two ways to configure Orchestrator recipe.

These are some basic configurations that have to be done to Orchestrator to make it production-ready. I will describe the use of the Orchestrator Configuration tool as well as the workflow method.

Configuring the network

The network setting configures the interface by which Orchestrator communicates and the default is set to 0.0.0.0. You can change it to an IPv4 or IPv6 address. The Windows install has already configured the correct setting and only requires a change if you would like to switch to IPv6.

Using the Orchestrator Configuration tool

1. Open the Orchestrator Configuration tool.
2. Click on the Network section and then select Network.
3. Select the correct IP address and click on Apply changes.

Using the workflow

1. Open the Orchestrator Client.
2. Navigate to Library | Configuration | Network.
3. Right-click on the workflow Configure the network settings and select Start Workflow.
4. Select the correct IP address and click on Submit.
5. Wait until the workflow has successfully finished.
   

Licensing

Both the Orchestrator Windows version and the appliance come with a 90-day evaluation license. Orchestrator is licensed with vCenter. The vCenter license key is the Orchestrator license key, and no extra purchase is required. However, if you are using the vCenter Essential license, you can only run workflows; you cannot create or edit them.

You can either enter a license key manually or connect to the vCenter Server to acquire the license.

Before you begin, add the vCenter SSL Certificate to Orchestrator.

Using the Orchestrator Configuration tool

1. Open the Orchestrator Configuration tool.
2. Click on the Licenses section.
3. Select Use vCenter Server license.
4. Enter the FQDN to vCenter.
5. Enter an administrative vCenter username and the corresponding password.
6. Click on Apply changes.

Using the workflow

1. Open Orchestrator Client.
2. Navigate to Library | Configuration | Licensing.
3. Right-click on the workflow Use vCenter Server license and select Start Workflow.
4. Enter the FQDN to the vCenter host.
5. Enter an administrative vCenter username and the corresponding password.
6. Click on Submit.

Wait till the workflow has finished successfully.

Creating a Server Package Signing certificate

The Server Package Signing certificate is an SSL certificate that is used to encrypt exports from Orchestrator, such as workflows and packages. It makes a lot of sense to at least personalize this with a self-signed certificate but be aware that, once created, it is not so easy to change.

It is not the SSL certificate of Orchestrator Server that is used for communication. The SSL certificate for Orchestrator Server is discussed in the Configuring the Orchestrator Server SSL certificate recipe in Chapter 2, Optimizing Orchestrator Configuration.

Using the Orchestrator Configuration tool

1. Open the Orchestrator Configuration tool.
2. Click on the Server Certificate section.
3. Click on Create a certificate database and self-signed server certificate.
4. Enter the required information, and select a country from the drop-down menu, and click on Create. Your new certificate will now be shown.

Using the workflow

1. Open Orchestrator Client.
2. Navigate to Library | Configuration | Package Signing Certificate.
3. Right-click on the workflow Create a self-signed server certificate and select Start Workflow.
4. Enter the relevant information.
5. Choose the two-letter code for your country (search the Web for the SSL certificate's country code) and click on Submit.

Wait till the workflow is successfully finished.

You can see that, for the most part, the workflow method requires the same inputs as the Orchestrator Configuration tool; however, you have probably also noticed that there are not as many options in workflows as with the Configuration tool.

The settings we just applied are important and need to be done in order to make Orchestrator production-ready. The network configuration, the package signing, as well as the licensing need to be done only once. Importing an SSL certificate is an action that we will encounter more often. Every time we want to establish a secure connection (SSL) between Orchestrator and another server, we first have to import this server's SSL certificate.

Please note that, in earlier versions of Orchestrator, you had to restart the Orchestrator Configuration tool or the Orchestrator service after importing the SSL certificate; this is no longer the case.

The SSL certificate we configured here is used to sign exports or packages to be used with other Orchestrator installations. We will work with exports and imports in the Importing and exporting Orchestrator elements recipe in Chapter 5, Basic Orchestrator Operations. In the Working with packages recipe of that chapter, you will find some more detailed information about how to manage and use this SSL certificate.

At the time of writing of this book, there is a small bug that appears from time to time with the network configuration. When using the appliance and changing the network setting to anything else but 0.0.0.0, some things, such as the Orchestrator home page, won't work anymore. To fix the problem, check out this VMware community article available at https://communities.vmware.com/thread/477955.

Have a look at the Backup and recovery recipe in Chapter 2, Optimizing Orchestrator Configuration, to learn how to export and import the configuration.

You need a supported LDAP service configured and running. The following LDAP services are supported in vCO 5.5:

We also need to create a group and a user in these services, so you should have access to these services.

You should be comfortable with using one of the methods described in the Two ways to configure Orchestrator recipe.

If your LDAP (AD) requires SSL (Kerberos), you will need to import the SSL certificate first (see the Important Orchestrator base configurations recipe in this chapter.

We will focus on linking Orchestrator to AD. Connecting Orchestrator to LDAP is pretty much the same procedure; for anyone who understands LDAP, this will be a breeze.

AD is basically the same as LDAP but most Windows administrators have problems with the LDAP representation of AD, which is why we focus on AD in this recipe.

We will configure SSO in the Integrating Orchestrator into SSO and vSphere Web Client recipe.

Configuring Orchestrator to work with an external authentication enables AD users to log in to the Orchestrator Client. The alternative would be either having only one user using it or adding users to the embedded LDAP. However, for a production Orchestrator, the embedded LDAP solution is not viable. As SSO is now a highly integrated part of vSphere, using Orchestrator with AD (or LDAP) isn't really such a good solution any longer. SSO can proxy multiple AD and/or LDAP domains and lets you integrate Orchestrator directly into vCenter as well as other corner pieces of VMware software offerings, making SSO integration the better choice for the future.

In the recipe above, we used the domain DNS address as the primary LDAP host rather than an individual AD server. The DNS entry for AD will forward the LDAP query to the next available AD server, which makes it a more reliable choice.

There are some things you should be aware of when working with LDAP.

Test login

In order to find out whether everything is working as it should, we need to test it. However, there is no workflow for this, so you have to trust your entries or use the Configuration tool.

1. Using the Orchestrator Configuration tool, click on Authentication.
2. Click on the Test Login tab.
3. Enter the Orchestrator Admin username and its password and click on Test Login.
4. Read the message carefully. It should be green and confirm that you can log in and that the user is part of the Orchestrator Admin group.

A red message mostly indicates that the user provided isn't in the LDAP or that the password is wrong.

If the message doesn't confirm an Orchestrator Admin group membership, review the membership of the user account.

See the Integrating Orchestrator into SSO and vSphere Web Client recipe in this chapter to learn how to configure Orchestrator with VMware SSO.

vCO 5.5 (and higher) requires an SSO server 5.5, as it won't work with an SSO 5.1 server.

We need an up-and-running Orchestrator as well as access to vCenter Web Client.

Make sure that you set the Orchestrator Network configuration (see the Configuring the network section in the Important Orchestrator base configurations recipe)

You should be comfortable with using one of the methods described in the Two ways to configure Orchestrator recipe.

You should have an AD group for your vCOAdministrators with at least one user in it. You can use the precreated SSO group vCOAdministrators@vsphere.local. The account administrator@vsphere.local is a member of this group.

Again both configuration methods are shown. Choose the one you're most comfortable with.

Since vCenter Server 5.1, vSphere Web Client is (or better, should be) the main method for accessing vCenter. Orchestrator completely integrates with vSphere Web Client, making it possible for Orchestrator workflows to be executed directly from vSphere Web Client.

You can configure which workflows can be run from the vSphere Web Client. We will discuss this configuration in detail in the Orchestrator and vSphere Web Client recipe in Chapter 5, Basic Orchestrator Operations.

Using SSO for Orchestrator login requires that you log in into Orchestrator Client or vSphere Web Client using a user that is a member of the group you defined as vCOAdmins. If you used the VCOAdministrators@vsphere.local group, you can add other SSO and AD groups or users to this group via the SSO group membership configuration.

To learn more about Orchestrator user management, see the User management recipe in Chapter 5, Basic Orchestrator Operations.

To configure Orchestrator workflows in vSphere Web Client, see the Orchestrator and vSphere Web Client recipe in Chapter 5, Basic Orchestrator Operations.

We will need a database; the following databases are supported with vCO 5.5.2.1:

You will need to create an empty database for Orchestrator, and you should also create a dedicated user account for Orchestrator to access the database.

You should be comfortable with using one of the methods described in the Two ways to configure Orchestrator recipe.

If your Database requires SSL, you will need to import the SSL certificate first; for this, see the Important Orchestrator base configurations recipe in this chapter.

Both configuration methods will be shown; choose the one you prefer. In this example, we have added a SQL database to Orchestrator. The other databases are not that much different.

The Orchestrator database contains the entire configuration, workflows, workflow runs, events, runtime information, actions, and a lot more. Therefore, it is quite important to consider using an external database. Without an external database, certain Orchestrator features, such as resuming a workflow after an Orchestrator Server crash, will not work or will be impaired.

All Orchestrator versions come with the embedded PostgreSQL database or use the vCenter Server database. A production environment dictates the use of an external database that integrates with the business continuity processes of your company.

In addition to this, the embedded database isn't really sized or optimized for large deployments and doesn't allow the use of Orchestrator Clustering.

Using the vCenter Server database for Orchestrator is not really a very pretty solution either. IT best practices dictate using dedicated resources for production environments. Putting the database on the same VM as Orchestrator is something to think about as it results in a competition for resources between the database and the Java process.

Here are some things you might find useful.