Installing Apcera on GCE using apcera-install

Follow these steps to deploy the Apcera Platform on Google Cloud Platform:

  1. Complete prerequisites
  2. Download and install apcera-install tool
  3. Configure the cluster architecture
  4. Next Step

Complete prerequisites

Be sure to complete the installation prerequisites for deploying the Apcera Platform on GCE.

Download and install apcera-install tool

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

Install the tool and run it to verify your environment.

Configure the cluster architecture

Run the command apcera-install config to configure the cluster.

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

License Agreement

When you run the apcera-install tool for the first time, you must accept the Apcera software license terms and conditions.

[ Apcera Install - Config ]
Welcome to apcera-install. A tool to install Apcera Platform.

You hereby agree that by installing this Apcera software and replying in
the affirmative to the prompt below that either: (1) you have already signed an agreement
with Apcera, Inc. to use our software, in which case such agreement applies to your use of
our software, or (2) your use of the Apcera software is limited by the terms and conditions
that apply to Evaluation Software in Software License, Maintenance, Evaluation & Services
Agreement at https://www.apcera.com/slmsa.

Accept [Y/n]

Enter Y to acknowledge and proceed with the installation.
Enter N to quit.

Cluster Location

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

[ Cluster Location ]
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]:

You have two options: use an Apcera-provided domain or provide your organization's registered domain name.

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 Apcera Platform for more information.

Enter 1 to use your own domain

If you choose option 1, you must enter the full domain consisted of <sub-domain-name>.<domain>.<tld>. For example, if your desired cluster name is shadowfax and your registered domain is mycompany.com, then enter shadowfax.mycompany.com.

At the conclusion of the apcera-install apply process, the apcera-install tool will prompts you to configure DNS.

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/install/cli/cli-install-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.

After making this selection, you should 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.

Cluster Configuration

TCP router is an optional component. You are prompted to add a TCP router.

Would you like to enable the tcp router on the cluster? [y/N]

Enter y if you wish to enable a TCP router. Enter N to resume without enabling a TCP router.

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-install tool create an SSH key for you. See Configuring SSH Access for Apcera.

Path to a public key for configuring ssh access. This is recommended if cluster administration is desired.
(Enter 'none' if you only want to use SSH via apcera-install ssh) [none]:

You must have enabled SSH during the initial deployment, you cannot do so later if you opted out (you only have 1 chance).

Provider Configuration

Next you are prompted to enter your infrastructure provider:

[ Provider Configuration ]
[0] aws
[1] azure
[2] google
[3] openstack
[4] vsphere
Enter your provider [0]: 2

Enter 1 to choose the GCE provider.

At the path to your Google Account file prompt, enter the full path to the JSON file that you have copied to your apcera-install working directory.

Path to the Google account file []:

Select an GCE region

Next you are prompted to enter the number for your selected GCE region:

[0] asia-east1 Eastern Asia
[1] asia-northeast1 Northeastern Asia
[2] asia-southeast1 Southeast Asia
[3] australia-southeast1 Southeast Australia
[4] europe-west1 Western Europe
[5] us-central1 Central US
[6] us-east1 Eastern US
[7] us-west1 Western US
Enter region number [0]:

Press Enter to use the default region, or specify the number corresponding to the region you want to use. For example, to use us-central1 Central US, enter 4.

Zone

Next you are prompted to specify the number of zones to use:

Specify the number of zones [1]:

The supported option is either 1 or 3. Not all GCE regions have 3 zones, so be sure to refer to the GCE documentation about their regions and zones.

Number of Instance Managers

Next you are prompted to specify the number of Instance Managers (IMs):

Your applications are deployed and executed on the Instance Managers. Each IM runs on a separate VM.
Specify the number of Instance Managers for provider google [1]:

You can specify 1 (default) or more IMs; however, if you specified the number of zones to be 3, Apcera recommends that you create at least 3 IMs (one IM per zone).

Number of Storage (Optional)

Apcera provides highly available NFS services for jobs to store data which is an implementation of Gluster. The use of this HA NFS service is optional.

Would you like to add storage nodes to provider google? [y/N]

Enter N if you do not wish to have a HA NFS service within your cluster. Otherwise, enter y to continue.

Specify the number of Storage node for provider google [0]:

The HA NFS architecture is configured to maintain 3 copies of data; therefore, the number of storage nodes has to be a multiple of 3. Each storage node runs on a separate VM.

The following screen capture shows a user input example:
screenshot

Monitoring Configuration

Apcera cluster will be deployed with a monitoring host which includes the Zabbix server and database for monitoring the 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 []:
Zabbix admin password []:
Zabbix guest user []:
Zabbix guest password []:

User Configuration

Next you are prompted to enter one or more username(s) and password(s):

[ User Configuration ]
Desired username [admin]:
Password:
Confirm Password:
Would you like to create another administrative user? [y/N]

By default, the basic authentication is enabled on your cluster. Enter the username (default is admin) and password for the admin user.

Optionally you can 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 admin users, you must run apcera-install config again and redeploy the cluster (apcera-install deploy).

Next you are prompted to enter a passphrase used to protect your data.

A passphrase is required to protect the saved config values that is at least 8 characters in length.
Enter the cluster passphrase:
Confirm Password:

Enter a desired passphrase which is used by the Orchestrator to log into Vault.

In production, the identity provider should reside external to the Apcera Platform to handle authentication requests. The basic authentication provides an easy but not scalable authentication mechanism for your convenience. Be sure to configure your cluster with one of the supported identity providers: Google OAuth 2.0, Active Directory, LDAP, or Keycloak.

Google OAuth2 Configuration

Next you are prompted for Google OAuth2 configuration:

[ Google OAuth2 Configuration ]
In order to enable Google OAuth2 for your cluster, you must create a project with Google at https://code.google.com/apis/console/ to get your API keys.

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-install, and create the necessary policy to grant user access. See Configuring Google Auth for details.

If Google OAuth2 is not the desired identity provider for your cluster, enter N and proceed.
Otherwise, enter y to configure the Google OAuth2 for your cluster:

Enter Google OAuth2 client id []:
Enter Google OAuth2 client secret []:
Enter Google OAuth2 web client id []:
Would you like to add Google users? [Y/n]
Enter Google user sign in email address []:
Enter another Google user sign in email address, or 'none' if you are finished [none]:

Keycloak Configuration

Next you are prompted for Keycloak configuration:

[ Keycloak Auth Configuration ]
Enable Keycloak Auth integration? [y/N]

To use Keycloak, see Using Keycloak as an Identity Provider for details.

If Keycloak is not the desired identity provider for your cluster, enter N and proceed.
Otherwise, enter y to configure the Keycloak for your cluster:

Enter Keycloak Auth client id []:
Enter Keycloak Auth client secret []:
Enter Keycloak Auth base URL []:
base_url is not a valid URL
Enter Keycloak Auth base URL []:
Enter Keycloak Auth realm []:
Enter Keycloak Auth web client id []:

LDAP Auth Configuration

Next you are prompted whether or not to enable LDAP authentication.

[ LDAP Auth Configuration ]
Enable LDAP authentication? [y/N]

Enter N if LDAP is not your chosen identity provider.

Enter y to enable LDAP authentication. Use this option to configure your cluster with Active Directory 2002 and later (tested against AD 2012) and LDAP version 3 (tested against Oracle Unified Directory server).

LDAP Model Name

If you answered y to LDAP Auth Configuration, you are prompted to select the LDAP model to configure with.

[ LDAP Model Name ]
[0] AD
[1] ADMulti
[2] basic
Enter model number [0]:

Enter 0 if Active Directory user logs in without domain name

With "AD", the user logs in with an account name without needing to type in a domain name. You are now prompted to enter the AD server information.

Enter model number [0]: 0
Enter your LDAP Default Domain []:
Enter your LDAP Search DN []:
LDAP Search password []:
Enter your LDAP Base DN []:
Enter your LDAP Group Base DN(optional) []:
Enter your LDAP URI []:
Enter your LDAP Port []:

Enter 1 if Active Directory user must specify the domain name

With "ADMulti", the user logs in with their UserPrincipalName, typically in the format [accountName]@[domainName]. You are now prompted to enter the AD server information.

Enter model number [0]: 1
Enter your LDAP Search DN []:
LDAP Search password []:
Enter your LDAP Base DN []:
Enter your LDAP Group Base DN(optional) []:
Enter your LDAP URI []:
Enter your LDAP Port []:

Enter 2 if using LDAP version 3

Use "basic" model to configure LDAP server of version 3.

Enter model number [0]: 2
Enter your LDAP Search DN []:
LDAP Search password []:
Enter your LDAP Base DN []:
Enter your LDAP Group Base DN(optional) []:
Enter your LDAP URI []:
Enter your LDAP Port []:

After entering the LDAP server information, you are prompted to add LDAP user(s).

Would you like to add users? [Y/n]

Enter N if you do not wish to specify any LDAP user(s) to admin role. Enter y to specify one or more LDAP users to the admin role.

NOTE: Once the cluster is up and running, user roles and permissions must be managed through Apcera policy.

Splunk Configuration (Optional)

Optionally, you can configure your cluster to drain the system component logs into Splunk.

You are prompted whether or not to enable Splunk:

Enable Splunk integration? [y/N]

Enter N if you do not wish to enable Splunk integration

If you decide to enable the Splunk integration at a later time, you refer to Configuring Splunk Search.

Enter y to enable Splunk integration

You are prompted to enter the Splunk configuration information.

Splunk admin password []:

Enter the password for the Splunk admin you wish to use.

Next you are prompted to enter the number of Splunk indexer and search.

Enter the number of Splunk indexer [0]:
Enter the number of Splunk search [0]:

Splunk indexer and splunk search will run on a separate VM.

Next you are prompted to enter the Splunk certificate information.

Path to your Splunk certificate []:
Path to your Splunk certificate private key []:

Next you are prompted to specify your Splunk license master server.

Install Splunk License Server? [y/N]

Enter y if you wish to configure one of your Splunk search nodes to become a Splunk license master.

Enter N if you want to point to an existing remote Splunk license master. With this option, you are prompted to enter the location of the license server:

Enter your remote Splunk license server []:

Enter the endpoint address of your remote Splunk license master server.

Next you are prompted to enter your Splunk license file path.

Enter your Splunk license file path []:

Enter the full path to your Splunk Enterprise license file location.

Nameserver Configuration (DNS)

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.

Diagnostic and usage data (optional)

Lastly, and optionally, you can help Apcera improve the apcera-install tool by automatically sending anonymized diagnostic and usage data.

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

If you want to opt-out, type n and press enter.

Enter y to opt-in to diagnostic data collection. The following non-identifying telemetry data may be sent to Apcera to help us improve the user experience:

  • Deployment date
  • Provisioner type
  • Number of IMs
  • Deployment status (success, error, other)

You now completed the cluster configuration step.

Next Step

Proceed to Provisioning Apcera cloud infrastructure using apcera-install.

NOTE: If you need to make any customization to the cluster architecture, proceed to Customize Apcera Cluster for your organization needs.