Installing Apcera CE on AWS

Follow these steps to deploy the Apcera Platform on AWS:

  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 AWS.

Review AWS requirements

Before you begin, please familiarize yourself with the requirements to install the Apcera Platform Community Edition on AWS.

Get and set your IAM user access keys

Before you begin the installation process, you must provide the apcera-setup tool with your IAM user access keys and attach default policy to the IAM user you create.

You will need to set your access keys anytime you want to connect to your AWS-hosted Apcera CE installation to configure, deploy, or manage it.

Define CloudFormation policy or manually create VPC, Subnet, and SG

To deploy the Apcera Platform Community Edition on AWS, you must have a configured VPC, subnet, and security group. You can have the apcera-setup tool create and configure these resources for you, or manually create and configure them yourself.

If you want the apcera-setup tool to automatically create and configure these resources, before you begin the installation process you must go to the AWS console and define the required CloudFormation policy.

If you choose to manually create the required AWS resources, before you begin the installation process you must go to the AWS console and create and configure the required resources.

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:

[ 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 own registered domain name. Typically you simply press enter to use the default Apcera-provided domain.

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

If you choose option 0, you are notified that the platform domain will be <sub-domain-name>.apcera-platform.io, and prompted to "Enter your sub-domain." 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 guidance.

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.

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.

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]: 2

Enter 2 to choose the AWS provider. If you are using a different provider, refer to those instructions.

Region Configuration

Next you are prompted to enter the region number:

[ Region Configuration ]
[0] ap-northeast-1 Asia Pacific (Tokyo)
[1] ap-southeast-1 Asia Pacific (Singapore)
[2] ap-southeast-2 Asia Pacific (Sydney)
[3] eu-central-1 EU (Frankfurt)
[4] eu-west-1 EU (Ireland)
[5] us-east-1 US East (N. Virginia)
[6] us-west-1 US West (N. California)
[7] us-west-2 US West (Oregon)
Enter region number [0]: 7

Press Enter to use the default region, or specify the number corresponding to the region you want to use. For example, to use us-west-2 US West (Oregon), enter 7.

Network Configuration

Next you are prompted to enter your choice of network configuration:

[ Network Configuration ]
[0] Auto-create VPC, subnet and security group
[1] Manual configuration
Enter choice [0]:

Auto-create VPC, subnet, and security group using CloudFormation template

Enter 0 to auto-create the required AWS resources using a CloudFormation template provided by Apcera. In this case, Apcera creates the VPC, subnet, and security group for you.

If you use automatic mode, we tag EC2 instances, volumes, VPCs, subnets, and security groups with the domain name.

Manual configuration

Alternatively, enter 1 and manually configure the VPC, subnet, and security group. To do this, you must first create these resources in AWS.

If you choose manual configuration, the apcera-setup tool prompts you for the following information:

  • VPC number Enter the number corresponding to the VPC you want to use.
  • Subnet number Enter the number corresponding to the Subnet you want to use.
  • Security Group number Enter the number corresponding to the security group you want to use.

If you use manual configuration, we tag EC2 instances and instance volumes with the domain name. You can tag other resources you manually create.

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 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 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 Configuration (optional)

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

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

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-setup tool for installing the Community Edition by automatically sending anonymized diagnostic and usage data. See data we collect for details.

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.

Create the platform

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

The next step is to provision the platform infrastructure by running the command apcera-setup create.

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

This command provisions the EC2 instance hosts, generates the SSH keys, registers DNS and presents you with the DNS token, and generates the deployment configuration file (config.json) in the working directory.

Creating a VPC, subnet, and security group for Apcera Setup...
Orchestrator instance type: t2.small
Centrals instance type: t2.medium
IMs instance type: m4.large
IMs instance type: m4.large
Creating VMs for the Apcera Platform...

[ Preparing Templates ]

[ Creating VMs ]
Provisioning VM 1 of 4: "my-apcera-setup-vm-orchestrator-644861380"...
Provisioning VM 2 of 4: "my-apcera-setup-vm-central-1-644861380"...
Provisioning VM 3 of 4: "my-apcera-setup-vm-im-1-644861380"...
Provisioning VM 4 of 4: "my-apcera-setup-vm-im-2-644861380"...

[ Configuring VMs ]
[WARNING] Sensitive connection credentials are stored in "config.json". Please store this file securely.

[ Configuring DNS ]
Registering DNS...
DNS service registered "my.apcera-platform.io"
DNS Update Token Used: c99c304b-XXXX-4440-xxxx-8c6d7ff5ffff
NOTE: Please record your token.  It will be required to re-use your sub-domain name at a later time.
Waiting for domain (my.apcera-platform.io) to update

If you used your own domain, you are prompted to configure DNS. Follow the on-screen instructions to set up the A records for the base domain and wildcard domain using the hostname and IP address of the HTTP router.

To verify successful creation, you should see the following output from the apcera-setup tool:

[ Creation Complete ]
All set. Command to try next: "apcera-setup deploy".

And your AWS dashboard should look as follows (assuming the defaults):

screenshot

Deploy the platform

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

Next, run the command apcera-setup deploy to deploy the latest Apcera Platform software release.

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.

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 have saved to your local computer:

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

The deployment process proceeds as follows:

$ ./apcera-setup deploy
[ Apcera Setup - Deploy ]
Deploying the Apcera Platform to cluster VMs...

[ Preparing Deploy ]
Validating VM state...

[ Deploying Cluster ]
Orchestrator IP: [54.153.77.xxx 10.0.50.xx]
Generating cluster.conf...
Uploading cluster.conf...
Cleaning up old releases before the deploy...
Deploying... Depending on your connection speed and configuration, this may take 20 min. or more. Check "logs/apcera-setup.log" for details...

If you encounter an error, check the /logs/apcera-setup.log file in the working directory. See also troubleshooting.

Once the platform is successfully deployed, you see output similar to the following:

[ Downloading APC ]
Downloading "apc.gz" to "/Users/user/apcera-setup/apc.gz"...
Downloaded 100.0% (4mb of 4mb)
[ Validating HTTPS Certificate ]

[ Registering NFS Provider ]
Targeting "my.apcera-platform.io"

[ Validating Cluster Images ]

[ Deploy Complete ]

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

All steps are completed. If you have not bootstrapped your cluster before, you should run: "apcera-setup bootstrap".

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 the following system checks:

1) Access the web console:

  • Console URL (assuming you used HTTPS and the Acpera 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.

3) Connect to the Orchestrator host using SSH (optional, if enabled):

Optionally, if you enabled SSH, you can test SSH access to the Orchestrator host as follows:

First, get the public IP address of the Orchestrator host and run the following command:

apcera-setup status

Then connect to the Orchestrator host:

$ ssh ubuntu@54.183.204.44

Where the IP address is the IP address of your Orchestrator host.

You should see the following (enter "yes" at the prompt):

The authenticity of host '54.183.204.44 (54.183.204.44)' can't be established.
ECDSA key fingerprint is SHA256:S2oB25G697krLpzb4bIWvo4JVp126vbyv9PgxuuGnLQ.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '54.183.204.44' (ECDSA) to the list of known hosts.
ubuntu@ip-10-0-50-169:~$

Run the following command to view the cluster configuration file:

cat cluster.conf

Type exit to quit the SSH session.

exit

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 service 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.

When the platform is successfully deployed and bootstrapped, you see the output of the apcera-setup status and apcera-setup info commands:

[ Apcera Setup - Status ]
Please wait a moment while we query your cluster...

[ Cluster Status ]
╭──────────┬──────────────╮
│ Provider │ Status       │
├──────────┼──────────────┤
│ aws      │ Bootstrapped │
╰──────────┴──────────────╯

[ Machine Status ]
╭──────────────┬───────────────────────────────────────────────┬────────────────────────────┬─────────╮
│ Role         │ Name                                          │ IP Address                 │ Status  │
├──────────────┼───────────────────────────────────────────────┼────────────────────────────┼─────────┤
│ Orchestrator │ waylon-apcera-setup-vm-orchestrator-139916696 │ 54.183.204.44, 10.0.50.169 │ running │
│ Central      │ waylon-apcera-setup-vm-central-1-139916696    │ 52.53.207.61, 10.0.50.161  │ running │
│ IM           │ waylon-apcera-setup-vm-im-1-139916696         │ 54.183.250.217, 10.0.50.62 │ running │
│ IM           │ waylon-apcera-setup-vm-im-2-1330938714        │ 54.193.1.181, 10.0.50.10   │ running │
╰──────────────┴───────────────────────────────────────────────┴────────────────────────────┴─────────╯

Access any of your VMs using your preferred ssh client by logging in as the user "ubuntu" (e.g. ssh ubuntu@<ip>) using the key located at "/Users/user/apcera-setup/my-ssh-key.pub".
[ Apcera Setup - Info ]
Target: https://waylon.apcera-platform.io:443
Web Console: https://console.waylon.apcera-platform.io
Users: admin
DNS Token: 7f5e4bba-XxxX-4567-xXXx-8240100bb103
Provider: aws
Number of Centrals: 1
Number of IMs: 2
SSH Access: See "apcera-setup status" for details about how to access your cluster via ssh
Installation complete.

The apcera-setup halt and resume commands cannot be used with AWS since the EC2 instances do not have static IP addresses. Refer to the documentation for more information.

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.