Installing and Using APC
APC is the command line tool you use to interact with the Apcera Platform. Once you install APC you identify, or target, the Apcera cluster you want manage. To target the platform you must know its domain name (my-cluster.apcera.com
, for example).
See the APC Command Reference for a full list of APC commands and options.
Installing APC
Follow these steps to install APC.
1. Log in to the web console for your platform.
2. Download the APC installer for your platform.
-
Click the Help icon in the lower left of the web console.
-
Download the apc.zip file for your platform:
-
Download for Mac
-
Download for Linux (64-bit)
-
Download for Windows (32-bit)
-
Download for Windows (64-bit)
-
3. Install the APC client by extracting and running the executable you downloaded.
-
Mac users: Double-click the apc.pkg package file and install APC.
-
Linux users: Extract the contents of the apc.zip file (apc) and run it.
-
Windows users: Extract the contents of the apc.zip file (apc.exe), copy it to a directory in your system's
%PATH%
environment variable, then run it.
4. Verify APC installation.
-
Open a terminal and type
apc help
. -
Verify that you get a list of available APC commands.
5. Target your platform and log in.
APC installation directory
APC installs in the /usr/local/bin directory. You need to have read/write permissions on this directory to be able to use APC. If, after installing APC, you cannot perform an APC command such as apc help
, check that you have proper permissions on this directory.
APC Settings File (.apc)
APC saves its current settings to a file called .apc
that, by default, is located in your user's home directory ($HOME). To use a different directory, set the APC_HOME
environment variable to desired directory where APC will save this file. This is useful, for example, if you want to maintain settings for different clusters you need to access. For example, you could use the default .apc
file in the $HOME
directory for one login, and set the APC_HOME
variable to another location, such as export APC_HOME="$HOME/apc"
.
APC Environment Variables
APC reads from the following environment variables to modify it's behavior.
APC_HOME |
Path to directory in which to save the .apc settings file; default is $HOME . |
APC_BATCH |
Set to disable interactive input globally. |
HTTP_PROXY |
Proxy URL, if your networking environment requires a proxy for HTTP. |
NO_PROXY |
Comma-separated list of domains that override HTTP_PROXY . |
Targeting your platform and logging in using APC
Logging in to Apcera using APC requires credentials. Follow the steps below to login to your platform using APC.
The steps for logging in are different depending on if you using basic authentication or an identity provider such as Google auth. Once you are logged in to your platform, you can begin using APC to deploy apps to the platform.
APC target with basic auth login
The following steps explain how to manually install APC and target your cluster.
NOTE: If you are behind a proxy you must set APC's HTTP_PROXY
environment variable to your proxy URL.
- Launch the Web Console for your cluster (
https://console.<cluster-name>.<cluster-domain>
) and login. -
Click the Help icon in the lower left of the Console and select the download link for your platform.
- Install the APC client:
- Mac users: Double-click the apc.pkg package file and run the installer.
- Linux users: Extract the contents of the apc.zip file (apc) and run it.
- Windows users: Extract the contents of the apc.zip file (apc.exe), copy it to a directory in your system's
%PATH%
environment variable, then run it.
- To verify APC installation open a terminal and type
apc help
. You should see a list of APC commands. -
Use the
apc target <cluster>
command to target your cluster:apc target https://my-cluster.apcera-platform.io:443 Targeted [https://my-cluster.apcera-platform.io:443]
If you did not configure your cluster for SSL then you will need to use the
http
protocol to target the cluster, for example:apc target http://my-cluster.apcera-platform.io:443
- Login to your cluster.
Logging in using APC
You use the apc login
command to login to your currently targeted Apcera cluster. An Apcera cluster can be configured with one more authentication providers, including Google Auth, LDAP, and Keycloak, as well as basic authentication. (Basic authentication is provided as a convenience for quickly setting up a cluster and should not be used in a production environment for security reasons.)
The steps for logging in differ depending on the authentication mechanism you are using. To login using basic authentication run the apc login
passing it --basic
as a parameter, for example:
apc login --basic
Connecting to https://my-cluster.apcera-platform.io:443...
Username: admin
Password: *****
Login successful for admin@apcera.me
If you get an error about API endpoint not found
then it means that the specified authentication provider is not configured.
To login using Google Auth pass the apc login
the --google
parameter and following the on-screen instructions.
apc login --google
Connecting to https://example.com...
Sign in with Google:
1. Browse to: https://www.google.com/device
2. Enter this code: YFKM-WCSG
3. Grant access to the Apcera Platform.
Did you successfully authorize the Apcera Platform? [Y/n]:
Using APC
To use APC you type apc
followed a command, followed by optional sub-commands, command-specific options, and global options.
apc <COMMAND> [<SUB-COMMAND>] [command-specific-options] [global-options]
For example, the following invokes the app create
command to create a new app (myApp
) in the "/dev/test" namespace. The app's source files reside in the folder myappfolder/
and is started immediately.
apc app create myApp --namespace /dev/test -p ./myappfolder --start
For a full list of APC commands and options see the APC Command Reference.
Global Command-line Options
APC provides the following global command-line options:
--ascii |
Causes tables to be output as ASCII, regardless of locale. |
--batch |
Disables interactive input for a command. Use the APC_BATCH environment variable to implicitly set this mode. |
-h , --help |
View help for a specific command. |
--html |
Causes tables to be output as HTML. |
--json |
Output will be JSON (and also batch). |
-l |
When used with any apc <resource> list command, includes UUID, FQN, and version of each resource in output. See Finding a resource's UUID with APC. |
--markdown |
Causes tables to be output as Markdown, if --html was not also specified. |
-ns , --namespace |
Runs your command in the specified namespace. |
-q , --silent |
Disables all input and output. Automatically enables batch mode. |
--trace |
Dumps contents of APC server requests to apc.log. See Using APC's trace mode for details. |
-vv , --verbose |
Increases output in some commands. |
-vvv , --very-verbose |
Increases output further in some commands. |
Using APC Help
APC provides online help for all commands, sub-commands, and options.
-
To list all top-level APC commands and global options type
apc help
(orapc
):$ apc help APC is Apcera's command-line tool. Usage: apc COMMAND [command-specific-options] Global flags: -ns, --namespace NS - Run your command in a different namespace. ... Subcommands: app - Manage apps capsule - Manage capsules changelog - See APC's recent product updates ...
-
To display a command's available sub-commands and command-specific options type
apc help <command>
(orapc <command>
). For example, the following displays help for theapp
subcommand:$ apc help app Usage: apc app <subcommand> <required args> [optional args] The 'app' command performs operations on apps running in Apcera. Subcommands: attract - Establish a scheduling affinity between apps connect - Connects to an app via SSH console - Connect to a temporary capsule for your app ...
-
To display help and command-specific options for a subcommand enter
apc help <command> <subcommand>
. The following displays help for theapp connect
command.$ apc help app connect Usage: apc app connect <app-name> The 'app connect' command opens an SSH session with the specified app. If your environment is proxied, you should target your platform over HTTPS before connecting to a app container. ... Command options: -instance, --instanceid UUID - UUID of the instance to connect to
Updating APC
APC is automatically updated if it is out of date with the platform version. To manually check for APC updates, use the apc update
command:
$ apc update
To continue, APC must update to version 2.6.0 at https://api.example.com/v1/apc/download/darwin_amd64/apc.gz.
Downloading new APC binary... 100%
Creating backup of APC (/usr/local/bin/apc.bak)... done
Overwriting old binary... done
APC successfully installed!
If APC determines that you have the latest version then no update is installed. You can force an update with the --force
option:
apc update --force
You can check the version of APC you are using and its build number with the apc version
command:
$ apc version
2.6.0 (master)
Viewing cluster information
Use the apc cluster info
command to check the version and build number of your Apcera cluster. The command also displays the cluster's administrator name and email, if available.
apc cluster info
Apcera Platform Version: 2.6.0
Build ID: f7fab07
Apcera Admin Name: John Smith
Apcera Admin Email: jsmith@example.com
APC installation directory
On Mac, APC installs to the /usr/local/bin directory. You need to have read/write permissions on this directory to be able to use APC. If, after installing APC, you cannot perform an APC command such as apc help
, check that you have proper permissions on this directory.
APC Settings File (.apc)
APC saves its current settings to a file called .apc
that, by default, is located in your user's home directory ($HOME). To use a different directory, set the APC_HOME
environment variable to desired directory where APC will save this file. This is useful, for example, if you want to maintain settings for different clusters you need to access. For example, you could use the default .apc
file in the $HOME
directory for one login, and set the APC_HOME
variable to another location, such as export APC_HOME="$HOME/apc"
.
APC Environment Variables
APC reads from the following environment variables to modify it's behavior.
APC_HOME |
Path to directory in which to save the .apc settings file; default is $HOME . |
APC_BATCH |
Set to disable interactive input globally. |
HTTP_PROXY |
Proxy URL, if your networking environment requires a proxy for HTTP. |
NO_PROXY |
Comma-separated list of domains that override HTTP_PROXY . |
Finding a resource's UUID with APC
Each resource in a cluster is assigned a universally unique identifier (UUID). To find a resource's UUID, call the apc <resource> list
command with the -l
flag, where <resource>
is any resource type, such as app
, job
, or package
. This option includes each resource's UUID in the command output, as well as each resource's FQN and version number. For example:
apc app list -l
Working in "/sandbox"...
╭─────────────────────────┬────────┬─...┬──────────────────────────────────────╮
│ FQN │ Status │ ...│ UUID │
├─────────────────────────┼────────┼─...┼──────────────────────────────────────┤
│ job::/sandbox::todo-app │ ready │ ...│ d730f723-55b5-490d-9f4b-fea14e9bdddc │
│ job::/sandbox::website │ ready │ ...│ 0367816b-153f-43fa-9f7d-e1cc6dabf44d │
╰─────────────────────────┴────────┴─...┴──────────────────────────────────────╯