Managing Apcera CE Deployments

You use the apcera-setup tool to manage your Apcera Platform deployment, including:

If you are using AWS, you will need to set your access keys to manage it.

Get deployment info

$ ./apcera-setup info

Displays platform configuration information. For example:

Cluster Information

Target: sub-domain.apcera-platform.io
Web Console: http://console.sub-domain.apcera-platform.io
Email: someone@acme.com
Users: admin
DNS Token: 2aa39131-blah-blah-blah-5323d512d69f
Provider: virtualbox
Number of Centrals: 1
Number of IMs: 2

Get deployment status

$ ./apcera-setup status

Displays the deployment status of your platform and the status of each VM host. For example:

Cluster Status
╭────────────┬──────────╮
│ Provider   │ Status   │
├────────────┼──────────┤
│ virtualbox │ Deployed │
╰────────────┴──────────╯

Machine Status
╭──────────────┬──────────────┬─────────╮
│ Role         │ IP Address   │ Status  │
├──────────────┼──────────────┼─────────┤
│ Orchestrator │ 192.168.1.7  │ running │
│ IM           │ 192.168.1.8  │ running │
│ IM           │ 192.168.1.9  │ running │
│ Central      │ 192.168.1.10 │ running │
╰──────────────┴──────────────┴─────────╯

If you configured an SSH key for your cluster, the status command also provides you with connection details. You can access any of your VMs using your preferred SSH client by logging in as the user "ubuntu" (e.g. ssh ubuntu@) using the key located at "/file/path/.ssh/ssh-key-name.pub". See [Configuring SSH Access](/setup/apcera-setup-ssh/).

Get deployment options

You use the apcera-setup deploy command to deploy the Apcera Platform after you have configured and created the infrastructure. You also use the apcera-setup deploy command to redeploy your Apcera Platform if you want to update the software or change the deployment configuration after running apcera-setup config.

Help:

   apcera-setup deploy --help

Usage:

   apcera-setup deploy [flags]

Flags:

  -r, --releaseFileOrURL="": The release file or URL to deploy
  -s, --suspendOrchestrator[=false]: Suspend Orchestrator VM after deploy

Global Flags:

  -c, --config="": config file (json supported)
  -d, --debug[=false]: debug output
  -v, --verbose[=false]: verbose output

The -d and -v flags are not available for all supported providers in the initial release of the apcera-setup tool.

Update platform configuration

If you want to change the configuration of a cluster (for example, change the number of instance managers), you need to run the apcera-setup config command. After you update the platform configuration you must redeploy the platform (run apcera-setup deploy) with the new configuration.

$ ./apcera-setup config

Update platform software

Once your cluster is deployed, you use the apcera-setup deploy command to update your software to a newer version of the Apcera Platform.

For example, to update to the latest release:

1) Back up the apcera-setup working directory for the installation of Apcera CE that you are running.

2) Download the apcera-setup tool that supports the release you want to upgrade to.

3) Copy the apcera-setup executable to your working apcera-setup directory.

4) Run the apcera-setup deploy command to upgrade your platform to the latest release. For example on Mac you would run:

$ ./apcera-setup deploy

Deploy specific release

To deploy a specific release (other than the latest), use the --release (or -r) command option with the release bundle you want to deploy. Note that the --release option is a global command option that can be used with apcera-setup deploy or apcera-setup install. See deciding installation method for more information on the difference between these options.

For example:

The following command uses the --release option to deploy a specfic Apcera Platform release bundle from the cloud:

$ ./apcera-setup deploy --release https://s3.amazonaws.com/apcera-releases/continuum/bundles/release-2.0.1.tar.gz

The following command uses the -r shortcut option to install a specfic Apcera Platform release bundle from the cloud:

$ ./apcera-setup install -r https://s3.amazonaws.com/apcera-releases/continuum/bundles/release-2.0.1.tar.gz

The following command uses the --release option to deploy a specific Apcera Platform release bundle that you have downloaded to your local machine:

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

The following command uses the -r shortcut option to install a specific Apcera Platform release bundle that you have downloaded to your local machine:

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

Deploy and bootstrap using local files

To install a local release bundle that you have downloaded to your working directory, run the following command:

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

To bootstrap the platform using a local set of packages, see troubleshooting.

Get component log files for debugging

Generally you can use the [apcera-setup logs]/setup/apcera-setup-debug/) to troubleshoot issues. However, if the logs/apcera-setup.log does not provide enough troubleshooting detail, you can pull the component logs or SSH into a cluster host. Both of these latter options require that you enabled SSH access to your cluster.

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

Component logs

If you receive errors during deployment and the logs/apcera-setup.log does not provide enough troubleshooting detail, you can pull the component logs.

To pull the component logs:

  1. When you configure your cluster you must enable SSH Access.

  2. Use the command apcera-setup logs to gather logs from the host VMs.

  3. Copy the logs to your local machine.

SSH to cluster host

If you need additional troubleshooting, you can SSH into a component host. To do this:

  1. When you configure your cluster you must enable SSH Access.

  2. Use the command apcera-setup status to list the IP address for each cluster host.

  3. Access the component host using the command ssh ubuntu@<ip-address>.

    To SSH into one of the hosts, you must do so as the Ubuntu user, for example: ssh ubuntu@192.169.11.202.

  4. To access other cluster hosts using orchestrator-cli ssh, see using orchestrator-cli ssh.

Manage platform resources

To deploy the Apcera Platform, the apcera-setup tool invokes the Apcera Orchestrator and feeds it the configuration details that it collects from you. Orchestrator uses this configuration information to provision Apcera components on the host VMs.

You can interact with Orchestrator using the apcera-setup tool to manage platform resources, including scaling IMs, powering down the Orchestrator host, and stopping and restarting other hosts.

Rescale number of IMs

To rescale the number of IMs in a cluster, run the apcera-setup rescale command.

`$ ./apcera-setup rescale [target # of IMs]

For example, consider a scenario where you have deployed a cluster with 1 IM and now you want 3 IMs. To rescale the cluster, run the following command:

`$ ./apcera-setup rescale 3

Suspend Orchestrator VM

Orchestrator runs on a dedicated VM that requires approximately 2 GB of RAM. The Orchestrator host is only required at deployment time or for redeployment; it is not needed at runtime. To conserve resources, after you have successfully deployed the platform, you can suspend the Orchestrator VM.

Your network must provide stable IP addresses via DHCP for you to be able to power down the Orchestrator host.

To do this, you use the following command:

$ ./apcera-setup deploy --suspendOrchestrator=true

Your platform is updated and redeployed. You see the message "Suspending the Orchestrator VM" and the status of the Orchestrator VM is now "halted."

Cluster Status
╭────────────┬──────────╮
│ Provider   │ Status   │
├────────────┼──────────┤
│ virtualbox │ Deployed │
╰────────────┴──────────╯

Machine Status
╭──────────────┬──────────────┬─────────╮
│ Role         │ IP Address   │ Status  │
├──────────────┼──────────────┼─────────┤
│ Orchestrator │ 192.168.1.7  │ halted  │
│ IM           │ 192.168.1.8  │ running │
│ IM           │ 192.168.1.9  │ running │
│ Central      │ 192.168.1.10 │ running │
╰──────────────┴──────────────┴─────────╯

Resume Orchestrator VM

To deploy or update the platform, you need to run the Orchestrator VM.

To resume the Orchestrator VM, run the suspend command using "false" as the argument:

$ ./apcera-setup deploy --suspendOrchestrator=false

Your platform is updated and Orchestrator is "running" on restart of the VM.

Stop and restart cluster hosts

You can use the command apcera-setup halt to shut down machine hosts, including the VMs for the Central host and Instance Manager VMs. You can then run apcera-setup resume to restart those hosts.

To use halt and resume, your network environment must provide stable IP addresses via DHCP or shutdown and restart of cluster hosts is not supported.

If you use halt and the IP address of the machine host is changed after running resume, the following known issues may occur:

  • The Orchestrator may be out of sync, resulting in the inability to update the cluster.
  • The DNS record for the cluster that was setup during creation may no longer properly resolve to the API Server when trying to use the APC client.

For example, this could occur if you are running a local installation on a provider such as VirtualBox or VMWare Fusion and you use halt to shutdown cluster hosts and power off the computer. On machine restart and resume of the cluster hosts, the IP addresses are be chagned. At this point you must destroy and recreate a new cluster.

See also Known networking limitation with VirtualBox.

Tear down deployment

To tear down a deployment, use the command $ ./apcera-setup destroy.

For example, on Mac you would run:

$ ./apcera-setup destroy

Note that the platform must be in the "deployed" state for this command to take effect. If the cluster is not in the "deployed" state (such as "bootstrapped"), the destroy operation may fail with following message:

Cluster state can be restored by retrying with the '--force' option.

Use the command apcera-setup destroy --force to destroy the cluster. This command changes the state of the cluster to "configured" so that the destroy operation works.

Syntax:

-f, --force[=false]: Remove VMs from the config file even if command fails

If you are using AWS, you must log into your AWS account where you deployed the Apcera Platform and verify that the resources were torn down. Please be advised that you may have to manually delete EC2 instances and attached volumes that were provisioned.