Installing Apcera CE on OpenStack

Follow these steps to deploy the Apcera Platform on OpenStack:

  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 on OpenStack.

Create OpenStack Project

Review the list of requirements and project configuration settings for installing the Apcera Platform Community Edition on OpenStack.

Create custom 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 a domain name. You have two options:

  • Enter 0 (default) to use an Apcera-provided domain, or
  • Enter 1 to provide your own registered domain name.

Typically you simply press enter to use the default Apcera-provided domain.

If you choose option 0 (default), 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. If you receive an error that the domain name is already registered, choose another subdomain name. See also the troubleshooting section.

If you choose option 1, you are prompted to enter a registered domain name. At the conclusion of the config process, the apcera-setup tool gives you the information you need to update your DNS records, specifically the hostname and IP address of the HTTP router so you can create the necessary A records.

See Configuring DNS for Apcera CE for more information.

Enter your provider

Next you are prompted to select the infrastructure provider.

Enter 4 for the Openstack provider. If you are using a different provider, refer to those instructions.

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

Enter the OpenStack identity provider

Obtain this URI from the OpenStack dashboard > Project > Compute > Acess & Security > API Access tab.

The URI on the Service Endpoint column in that row will be your Identity endpoint.

screenshot

Enter the OpenStack user name and password

These credentials are given to you by your OpenStack administrator.

You can obtain the user name from the OpenStack RC File as the OS_USERNAME parameter.

To obtain this file, go to the Access & Security screen and download the OpenStack RC File.

Enter your OpenStack Tenant name.

The Tenant name is the same as your Project Name.

The dropdown menu next to the OpenStack logo shows you what Project/Tenant you are currently on.

The Tenant name is also in the OpenStack RC File file as OS_TENTANT_NAME.

screenshot

Enter the OpenStack region.

The default is RegionOne.

If you used a different region, you can obtain the region from the OpenStack RC File as the value for the parameter OS_REGION_NAME.

Enter the OpenStack Network ID to run the cluster on

Go to Project > Network > Networks and click on the project for your internal network.

screenshot

Enter the OpenStack Floating IP pool to run the cluster on

This is the external public network that you or your OpenStack admin configured.

screenshot

In OpenStack Networking, a floating IP pool is represented as an external network and a floating IP is allocated from a subnet associated with the external network. Thus, if necessary you can get the floating IP pool from this screen:

screenshot

Enter the Security Group name to run the cluster with

You can obtain the Security Group name at Project > Compute > Access & Security > Security Groups.

Enter the number of IMs

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.

Enable 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

Enter path to public SSH key

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.

Create platform admin users

By default, your cluster is configured to use HTTP basic authentication. When prompted enter the username (default is admin) and password for the platform user. You can optionally create additional 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 users, you must run apcera-setup config again and redeploy the cluster (apcera-setup deploy).

Enable Google OAuth2 integration

Optionally you can enable Google OAuth2 integration on your cluster. See Configuring Google Auth for guidance.

If you are deploying the platform for others to use, for secure authentication Apcera recommends that you enable Google Auth and write policy to grant user access.

Enter Domain Name Servers

Next 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. Or, if you are providing your own domain, you can specify one or both DNS servers. See Configuring DNS for more information.

Opt in to diagnostic data

Optionally, you can help Apcera improve the platform by automatically sending anonymized diagnostic and usage data. See data we collect for details.

Create the platform

If you are using the apcera-setup install workflow, the infrastructure creation process begins automatically.

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.

Deploy the platform

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

Run the command apcera-setup deploy from your working directory 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 release file or 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.tar.gz

In the OpenStack dashboard, at the Project > Images screen you should see that the Orchestrator and Base images are uploaded.

screenshot

After the platform is deployed, you should see the message "All steps are completed." If you encounter an error, check the /logs/apcera-setup.log file in the working directory. See also troubleshooting.

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: The default is HTTPS. If you are using HTTP, you need to specify it, 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

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

Lastly, run 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 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.