Installing Apcera CE on vSphere

Follow these steps to deploy the Apcera Platform on vSphere:

  1. Complete prerequisites
  2. Install the platform
  3. Create the platform
  4. Deploy the platform
  5. Verify deployment
  6. Bootstrap the platform
  7. Manage the platform
  8. Use the platform

Complete prerequisites

This section lists the prerequisites for deploying the Apcera Platform Community Edition locally.

Review requirements

Review the list of requirements before you deploy the Apcera Platform Community Edition on vSphere.

Create SSH key (optional)

During the installation process you are prompted to provide an SSH key so you can access the cluster hosts.

If you don't specify a custom key, the apcera-setup tool will generate and register an SSH key pair for you. Alternatively you can provide your own custom SSH public key. See Configuring SSH Access for complete details.

You can only provide a custom SSH key the first time you deploy an instance of the platform.

Download and install apcera-setup tool

If you have not done so already, download the apcera-setup tool. If necessary, review the requirements for using the tool.

Install the tool and run it to verify your environment.

Install the platform

Run the command apcera-setup install to install the platform.

For example, on Mac you run the command $ ./apcera-setup install.

Alternatively, you can use the command apcera-setup config to begin the installation process with detailed interaction. See additional installation method for more information.

Registration

When you run the apcera-setup tool for the first time, you must accept the Registration agreement.

[ Registration ]
Installation and use of the Apcera Platform Community Edition software requires that you have registered, accepted the terms and conditions, and downloaded the software from https://www.apcera.com/setup/. Do you agree to the terms and conditions? [Y/n]

Press enter [Y] to acknowledge and proceed with the installation.

Version check

When you run the apcera-setup tool, you will be notified if there is a newer version available for download:

[ Version Check ]
Checking for latest version....
[WARNING] A more recent version of apcera-setup is available for download from
https://www.apcera.com/setup

See updating the apcera-setup tool for more details.

Cluster Location

First you are prompted to specify the domain name for your cluster:

[ DNS Configuration ]
Where will your Apcera Platform cluster be located?
[0] As a sub-domain of apcera-platform.io
[1] In a domain that you provide (DNS will be configured after the create step)
Enter your selection [0]:

Enter 0 (default) to use an Apcera-provided domain

If you choose option 0, your platform domain is <sub-domain-name>.apcera-platform.io, where the sub-domain-name is a user-defined string between 5 and 63 characters that must be unique in our DNS server. See Configuring DNS for more information.

Enter 1 to use your own domain

If you choose option 1, you must enter a registered domain name. At the conclusion of the apcera-setup config process, the apcera-setup tool prompts you to configure DNS. See Configuring DNS for guidance.

HTTPS configuration

Next you are prompted to specify the mode of communications for your cluster:

[ HTTPS Configuration ]
For HTTPS communication within the cluster a certificate is required. You can provide your own certificate or have the Apcera Platform generate a self-signed certificate.
[0] Have the Apcera Platform generate a self-signed certificate
[1] Provide my own certificate
[2] Do not use a certificate (only insecure HTTP communication is available within the cluster)
Enter your selection [0]:
Please add and trust the HTTPS certificate at "certs/cert.crt".
See http://docs.apcera.com/setup/apcera-setup-certs/ for more details.
Have you added/trusted the HTTPS certificate? [Y/n]

You have three options for configuring HTTPS:

Enter 0 (default) to use a self-signed HTTPS certificate.

See Configuring HTTPS for more information on this option.

After making this selection, you must trust the SSL certificate. Once you have trusted the certicate, enter Y at the "Have you trusted the HTTPS certificate?" prompt to complete the HTTPS configuration process.

Enter 1 to use HTTPS and provide your own SSL certificate.

See Configuring HTTPS for more information on using your own certificate.

Enter 2 to not use HTTPS

If you don't want to use HTTPS, choose option 2 at the prompt. See not using HTTPS for more information.

vSphere provider configuration

Next you are prompted to enter your infrastructure provider:

[ Provider Configuration ]
[0] vmware_desktop
[1] virtualbox
[2] aws
[3] vsphere
[4] openstack
[5] azure
[6] googlecloud
Enter your provider [1]: 3

As shown, enter 3 to choose the vSphere provider. If you are using a different provider, refer to those instructions.

vCenter server

After selecting the vSphere provider, you are prompted to enter the IP address of the vCenter server you are using.

Enter the vCenter server []:

This is the IP address of the vSphere host where you are deploying the platform. For example:

Enter the vCenter server []: 198.51.100.5

vSphere credentials

Next you are prompted to enter the vSphere username and password.

Note that these credentials are stored in the config.json file that is saved to your /apcera-setup working directory.

vSphere datacenter

Next you are prompted to enter the vSphere datacenter to run the Apcera Platform on.

Enter the vSphere datacenter to run the Apcera Platform on []:

The provisioned hosts will be run inside the specified datacenter. For example:

Enter the vSphere datacenter to run the Apcera Platform on []: DC-TMP

vSphere destination type

Next you are prompted to enter the vSphere destination type, and are presented with two options:

[0] cluster
[1] host
Enter the vSphere destination type [0]:

vSphere provides three destination types: cluster, direct host, and static IP resource pool. Apcera Platform CE supports cluster or direct host; static IP resource pool is not currently supported for vSphere.

To specify the vSphere destination type, press enter (default) to use cluster, or enter 1 to use a direct host. For example:

[0] cluster
[1] host
Enter the vSphere destination type [0]: 1

If your vSphere environment has a cluster layer you cannot choose the host option.

If you choose option 0 (cluster), at the ESXi host prompt, you will be given the option to narrow the cluster selection to a specific ESXi host within the cluster, or let apcera-setup pick a blank host for you.

vSphere ESXi host

Next you are prompted to enter the IP address of either the ESXi cluster or host to run the platform on.

For example, if you chose the direct host desintation type (option 1) in the previous step:

Enter the ESXi host to run Apcera Platform on []: 198.51.100.7

If you chose the cluster destination type (option 0) in the previous step, you can narrow the host to a specific ESXi host within the named cluster, or let apcera-setup pick a blank host. In this case, only hosts that have the datastore and the network that you specify next will be available for selection.

vSphere network

Next you are prompted to enter the vSphere network to run the platform on. For example:

Enter the vSphere network to run Apcera Platform on []: acme-public-network

vSphere provides two types of networks: standard and distributed. Apcera CE supports both.

vSphere datastore(s)

Next you are prompted to enter the vSphere datastore(s) for cluster storage. For example:

Enter the vSphere datastore(s) to run Apcera Platform on separated by commas. []: datastore.11

You must enter at least one datastore. You can enter multiple datastores by separating each with a comman. For example:

Enter the vSphere datastore(s) to run Apcera Platform on separated by commas. []: datastore40, datastore41

If you enter multiple datastores, one is chosen by random. The list of hosts is pruned to only those that have the datastore mounted.

Cluster Configuration

Next you are prompted to specify the following cluster information, some of which is optional:

Number of Instance Managers

Specify the number of Instance Managers [1]:

Your applications are deployed and executed on one or more Instance Managers (IMs). You can specify 1 (default) or more IMs. Each IM runs on a separate VM.

For most use cases, Apcera recommends 2 IMs. For larger deployments, 3 or more IMs may be used. Note that there is no hard limit on the number of IMs you can run, but for local deployments running more than 5 IMs may not be possible due to hardware limits.

Zabbix Monitoring

Optionally you can deploy an additional host for cluster monitoring purposes:

Enable a Zabbix monitoring host for this cluster? [y/N]

If you enter y (yes), the cluster will be deployed with a monitoring host that includes the Zabbix server and database for monitoring cluster hosts. You will be prompted to create credentials for the admin and guest users:

Enable a Zabbix monitoring host for this cluster? [y/N] y
Zabbix admin user []: admin
Zabbix admin password []: ENTER-PASSWORD
Zabbix guest user []: guest
Zabbix guest password []: ENTER-PASSWORD

Path to public SSH key (optional)

If you want to be able to SSH into the VM hosts, enter the full local path to your public key. Or you can simply press enter and have the apcera-setup tool create an SSH key for you. See Generating SSH Key Pair for Apcera CE.

Path to a public key for SSH access to the cluster using other clients
(Enter 'none' if you only want to use SSH via apcera-setup ssh) [none]:

You can only provide a custom SSH key the first time you deploy an instance of the platform.

Admin username(s) and password(s)

Desired username [admin]:
Password: ********
Confirm Password: ********

By default your cluster is configured to use basic authentication. Enter the username (default is admin) and password for the admin user. Optionally you can create additional admin users. Any user you create here is made a member of the admin policy role and thereby granted full access to the platform. To later add or remove admin users, you must run apcera-setup config again and redeploy the cluster (apcera-setup deploy).

If you are deploying the platform for others to use, for secure authentication Apcera recommends that you enable Google OAuth2 integration (see below) and use that to grant user access.

Google OAuth2 integration (optional)

By default your cluster uses basic authentication. Optionally, you can configure Google Auth as the identity provider.

Enable Google OAuth2 integration? [y/N]

To use Google Auth, you must create a Google project and obtain OAuth2 client IDs that you provide to apcera-setup, and create the necessary policy to grant user access. See Configuring Google Auth for Apcera CE for details on enabling Google Auth.

Nameserver Configuration (DNS)

You are prompted to enter the primary and secondary DNS servers:

Enter your DNS server [8.8.8.8]:
Enter your secondary DNS server [8.8.4.4]:

Generally you can just accept the defaults, but you can specify your own DNS if you are providing your own domain. See Configuring DNS for more information.

Diagnostic and usage data (optional)

Lastly, you can help Apcera improve the apcera-setup tool for installing the Community Edition by automatically sending anonymized diagnostic and usage data.

Would you like to help Apcera improve by sending anonymized diagnostic and usage data? [Y/n]

See data we collect for more information on choosing this option.

Create the platform

If you are using the apcdera-setup install workflow, the apcera-setup create process begins automatically.

When the apcera-setup config process is complete, the next step is to run the command apcera-setup create from your working directory to begin the VM provisioning process.

For example, on Mac you would run the command $ ./apcera-setup create.

The apcera-setup create process prepares the image templates, creates and configured the VMs, and configures DNS.

Deploy the platform

If you are using the apcdera-setup install workflow, the apcera-setup deploy process begins automatically.

When the apcera-setup create process is complete, the next step is to run the command apcera-setup deploy to deploy the Apcera Platform.

For example, on Mac you run the command $ ./apcera-setup deploy.

This command downloads the latest Apcera release from the cloud and deploys your platform. It will take approximately 30 minutes to deploy the platform, but may take longer depending on your network speed.

To deploy a specific release (other than the latest), use the -r flag with the local release file or remote URL as the argument.

For example, to deploy an Apcera release bundle you saved to your local computer:

$ ./apcera-setup deploy -r release-2.0.0-f284c8e.tar.gz

After the platform is deployed, you should see the message "Deploy Complete" as shown below. If you encounter an error, check the /logs/apcera-setup.log file in the working directory. See also troubleshooting.

[ Deploy Complete ]

| Full documentation on Apcera Platform is available at:
|   https://docs.bells.apcera-platform.io
|
| The web console can be accessed at:
|   https://console.bells.apcera-platform.io
|
| The Apcera Developer Portal can be accessed at:
|   https://developer.apcera.com
|
| Target and log into the cluster with:
|   apc target https://bells.apcera-platform.io:443
|   apc login --basic

The apcera-setup tool downloads the APC client to your local working directory. You do not need to install it.

Verify deployment

To verify successful deployment, complete both of the following system checks:

1) Access the web console:

  • Console URL (assuming you used HTTPS and the Apcera DNS): https://console.sub-domain-name.apcera-platform.io
  • Log in using basic auth (or Google auth if you enabled it)

NOTE: If you are using Firefox, you need to load the cert.

2) Target your platform and log in using APC:

  • Target your platform: apc target sub-domain-name.apcera-platform.io
  • Log in using basic auth: apc login --basic (or Google auth if you enabled it)

NOTE: By default the APC client uses HTTPS to connect to the API Server. If you are using HTTPS, you do not need to specify the protocol or port. If you are using HTTP, you must specify the protocol. For example: apc target http://sub-domain-name.apcera-platform.io.

See troubleshooting if you cannot log in to your cluster using the web console or APC.

Bootstrap the platform

Lastly, use the apcera-setup bootstrap command to import a base set of packages and create providers for NFS, MySQL, and PostgreSQL. See bootstrapping the platform for details.

For example, on Mac you run the command $ ./apcera-setup bootstrap.

The bootstrapping process is required and may take 30 minutes or more. You may only need to bootstrap your platform the first time you deploy it.

Manage the platform

Use the apcera-setup tool to manage your Apcera Platform, including getting deployment info and status, managing the infrastructure, and maintaining Apcera Platform software.

Use the platform

If you are new to Apcera, a good place to start is the Apcera Developer Portal.

If you are already familiar with the Apcera Platform, you may want to advance your skills by going through some additional tutorials.