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.

    screenshot

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

  1. Launch the Web Console for your cluster (https://console.<cluster-name>.<cluster-domain>) and login.

  2. Click the Help icon in the lower left of the Console and select the download link for your platform.

    screenshot

  3. 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.
  4. To verify APC installation open a terminal and type apc help. You should see a list of APC commands.

  5. 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
  6. 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 (or apc):

      $ 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> (or apc <command>). For example, the following displays help for the app 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 the app 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 │
╰─────────────────────────┴────────┴─...┴──────────────────────────────────────╯

© 2022 Apcera Inc. Last updated: 2018-02-16 23:12:10 +0100 Feedback