Installing Apcera CE on GCE

Follow these steps to deploy the Apcera Platform on GCE:

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

Complete prerequisites

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

Review GCE requirements

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

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.

You must use an initial capital letter for the subdomain name. Although RFC-952 relaxes the restriction on the first character to allow either a letter or a digit, GCE does not support this change and only allows network names that start with letters.

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.

Enter 6 to choose the GCE provider.

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

Google Account file

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

Path to the Google account file []: ./Apcera for Training-Testing-39762d420070.json

Zone number

For zone number, enter the zone where the VMs you want to create should reside. For example, enter 5 for us-central1-c.

Zones: 
[0] us-east1-b
[1] us-east1-c
[2] us-east1-d
[3] us-central1-a
[4] us-central1-b
[5] us-central1-c
[6] us-central1-f
[7] europe-west1-b
[8] europe-west1-c
[9] europe-west1-d
[10] asia-east1-a
[11] asia-east1-b
[12] asia-east1-c
Enter zone number [0]: 5

Disk Types

For Disk Types enter from the available choices as best suits your cluster needs. If there is no preference for SSD, it is acceptable to use the default type pd-standard.

Disk Types: 
[0] pd-standard
[1] pd-ssd
Disk type number [0]: 

Network Configuration

For network configuration, press Enter to select the default of 0 and have Apcera-Setup automatically create the subnetwork and firewall rule.

[ Network Configuration ]
[0] Auto-configure Network and Firewall rules
[1] Manual configuration
Enter choice [0]: 

If you already have a network configured, or if you want to use the default GCE network, you can enter 1 and manually configure the subnetwork and firewall rules.

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.

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.

If you are using the apcera-setup install workflow, the the create, deploy, and bootstrap processes start automatically. If you used apcera-setup config, run the apcera-setup create command as described next.

Create the platform

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 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 network, subnetwork, and firewall rule for Apcera Setup...
Creating VMs for the Apcera Platform...

[ Preparing Templates ]
No templates are required for this provider.

[ Creating VMs ]
Provisioning VM 1 of 3: "edu-test-apcera-setup-vm-orchestrator-1693569177"...
Provisioning VM 2 of 3: "edu-test-apcera-setup-vm-central-1-1693569177"...
Provisioning VM 3 of 3: "edu-test-apcera-setup-vm-im-1-1693569177"...
Configuring VM 3 of 3: "edu-test-apcera-setup-vm-im-1-1693569177", this might take a while...
Configuring VM 1 of 3: "edu-test-apcera-setup-vm-orchestrator-1693569177", this might take a while...
Configuring VM 2 of 3: "edu-test-apcera-setup-vm-central-1-1693569177", this might take a while...

[ Configuring DNS ]
Gathering IP information...
Registering DNS...
DNS service registered "edu-test.apcera-platform.io"
DNS Update Token Used: 4e9001b6-18b6-489a-bafd-ec524812a51c
NOTE: Please record your token.  It will be required to re-use your sub-domain
name at a later time.

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

Once the cluster hosts are created, you can verify them in the Google Cloud Platform Console.

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       │
├──────────┼──────────────┤
│ googlecloud │ 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: googlecloud
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.

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.