Getting started with the Apollo CLI

The Apollo CLI (apollo-cli) is a general-purpose command-line tool for performing actions on an Apollo Hub, such as uploading a new Product or viewing what is installed in an Environment managed by Apollo. This guide will walk through downloading and setting up the Apollo CLI. For more detailed information, see the Apollo CLI documentation.

The main actions supported by apollo-cli are:

• publish: Upload a new Product Release as a distribution or Helm Chart so it can be installed in an Environment.
• get-installations: List all installed Products in a given Environment.
• list-environments: List metadata about all the Environments managed by Apollo.
• list-products: List all the Products currently available in the Apollo Hub (by Apache Maven coordinate).

Initial setup

Download the CLI

Navigate to Settings in Apollo's left-hand sidebar. Select Download on the left of the Settings & Configuration page to download the Apollo CLI.

A pop-up window will appear with an option to download the CLI based on your operating system.

Selecting this will download a compiled binary of the CLI. Once the download is finished, move the file to wherever you would like to host the CLI and change the permissions so you can execute the CLI.

Copied!
1
$ chmod +x apollo-cli

To use the apollo-cli, invoke the executable and provide it with the desired command and any required flags. Running apollo-cli --help will display a list of available commands with flags and documentation on their usage. The --help or -h flag can be added to any command to get documentation for that particular command and its flags. For example, apollo-cli --help indicates that list-environments is an available command, and running apollo-cli list-environments --help will display the usage for the list-environments command.

All the commands in this guide assume that the apollo-cli executable is in the current working directory. We recommend moving the apollo-cli executable to a folder on your $PATH so the CLI can be run from any working directory. For more details, refer to your shell's documentation.

(Optional) Set up CLI command completion

apollo-cli supports command completion for most common shells like bash, fish, powershell, zsh, and more. When command completion support is installed, you can use the Tab key on your keyboard to perform autocomplete for subcommands and flags.

Run the ./apollo-cli completion [shell] --help command for your particular shell to get instructions for how to install completion for your shell. For example, ./apollo-cli completion zsh --help prints instructions for how to enable completion for the zsh shell.

Authentication

To use the Apollo CLI, you will need to provide one of the following:

• An Apollo Bearer Token
• A client ID and client secret for a service account

When you run apollo-cli configure, you can choose an authentication method when prompted for the Apollo token provider. You can enter static to use a Bearer Token or enter service-user to use a service account. You will then be prompted to enter the Bearer Token or the client ID and client secret. If you are using a Bearer Token, you should not enter a client ID and client secret. Similarly, if you are using a service account you should not enter a Bearer Token.

Create a Bearer Token

You can generate a Bearer Token by navigating to https://<Hub>.palantircloud.com/multipass/app, where <Hub> is the unique name of your Apollo Hub.

Under the User Settings section in the sidebar menu, select Tokens. Then select + Create token on the upper right and enter a name, brief description, and expiration date for the token.

Add the Bearer Token as a secret named APOLLO_TOKEN to your CI pipeline so that the value is available in the CI script.

Set Apollo Hub configuration

Before you interact with an Apollo Hub for the first time, run ./apollo-cli configure to set the configuration necessary for interacting with your Hub. When you run the following you will be prompted to enter values for each variable.

The configure command creates an apollo-cli.config file in your local ~/.palantir/ directory. You can check there to verify the file exists. Values may also be left blank/unspecified.

When the Apollo CLI runs commands that need values specified in the configuration, it will attempt to read them from the configuration file if it exists. However, these values can also be specified as environment variables or as command-line flags.

Copied!
1
2
3
4
5
6
7
8
9
10
$ ./apollo-cli configure
Apollo URL [None]: https://<Hub>.palantircloud.com
Apollo token provider: <Token Provider>
Apollo bearer token [None]: <Multipass Bearer Token>
Apollo client id: <Service User Client ID>
Apollo client secret: <Service User Client Secret>
V1 experimental commands [enabled] {enabled|disabled}: enabled
V1 deprecated commands [enabled] {enabled|disabled}: enabled
V2 experimental commands [disabled] {enabled|disabled}: disabled
V2 deprecated commands [disabled] {enabled|disabled}: disabled

To obtain the following values:

• <Hub>: Each Apollo Hub has a unique URL that will be provided as part of Apollo onboarding.
• <Token Provider>: If you are configuring the Apollo CLI to run via a service user, set this value to service-user. Otherwise, the value should be set to static to authenticate using a Multipass Bearer Token.
• <Multipass Bearer Token>: Your Apollo Bearer Token.
• <Service User Client ID>: This is the Client ID provided for a service account. If using a Bearer Token, this should be left blank.
• <Service User Client Secret>: This is the Client Secret provided for a service account. If using a Bearer Token, this should be left blank.

Configure Experimental and Deprecated commands

When prompted, you can choose to enable or disable commands that are marked as Experimental or Deprecated.

View a list of V1 commands.

View a list of V2 Experimental commands.

Run a command to verify that the configuration is correct

To test that the URL and Bearer Token set above are working, run the following:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
$ ./apollo-cli list-environments
[
  {
    "rid": "ri.apollo.main.environment.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "deploymentId": "test-spoke",
    "deployment": "test-spoke",
    "environmentId": null,
    "environmentType": "PRODUCTION",
    "managementStatus": {
      "type": "managed",
      "managed": {}
    }
  },
  ...

This command prints the Environments managed by your Apollo Hub. If no Environments have been set up, this list may be empty. You can follow the instructions in Creating a new Environment to create an Environment.

If the Apollo URL or Apollo Bearer Token specified in configuration is invalid, the command will fail with an error.

Example 1: Publishing Redis Helm Chart to Apollo using the CLI

In this example, we are going to install an open-source Redis Helm Chart on Artifact Hub as a Product in Apollo.

Conceptually, publishing a Product to Apollo requires adding both the Product metadata and its manifest to the Product catalog. The Apollo CLI publish command takes a standard Helm Chart and creates a new artifact which contains the Apollo-specific metadata and the product manifest. It then publishes both those components to the Product catalog.

Every Helm Chart Product that is published to Apollo must specify a Helm Repository URL, chart name, and chart version. When Apollo deploys a Helm Chart Product, Apollo locates the Chart with the specified name and version in the specified repository. This means that even if a Helm Chart Product is published using the CLI, Apollo will not be able to deploy the corresponding Chart unless the Chart's images exist in the Helm Chart Repository (which must be done separately).

Adding a Helm Chart as a Product using the CLI can be done by either specifying the information necessary to locate the Helm Chart directly from a Helm Repository or by specifying a Helm Chart file that exists locally. If your machine is able to access the Helm Repository for the Chart, then publishing the Product based on the Helm Repository information is generally the easier approach.

Option 1: Publish a Helm Chart from a Helm Repository

The following apollo-cli command obtains version 16.9.11 of the Redis Helm Chart from Bitnami's Helm Repository at https://charts.bitnami.com/bitnami and then publishes the Product to Apollo using the identifier com.bitnami:redis:16.9.11:

Copied!
1
2
$ ./apollo-cli publish helm-chart --helm-chart-name redis --helm-chart-version 16.9.11 --helm-repository-url "https://charts.bitnami.com/bitnami" --maven-coordinate "com.bitnami:redis:16.9.11"
Publishing product release com.bitnami:redis:16.9.11 into Apollo ... done

Complete flag details can be viewed by running ./apollo-cli publish helm-chart --help, but the following is an overview:

• --helm-repository-url: This is the URL where the target Helm Chart is hosted. You can find it in Artifact Hub by selecting Install on a container page. The CLI and Apollo platform uses this URL and the chart name and version to locate and download the Helm Chart artifact.
• --helm-chart-name: The reference name to the Helm Chart within the Helm Repository above.
• --helm-chart-version: The target version of the Helm Chart to upload. This can be found on the right-hand side of the Artifact Hub page.
• --maven-coordinate: The user-chosen Apache Maven coordinate that will act as the address for the Product Release in Apollo. This can be any valid Maven coordinate of the form group:product-name:version. The Maven coordinate is the identifier that will be used in Apollo, so the product name and version does not have to relate directly to the Helm Chart. Although the example above uses the Maven coordinate com.bitnami:redis:16.9.11, a different Maven coordinate like internal:modified-redis:1.2.3 would also be valid. See Maven coordinates for more information about picking a Maven coordinate.

Option 2: Publish a Helm Chart from a local Helm Chart file

The CLI also supports publishing a local Helm Chart file directly to Apollo. This can be useful in cases where your machine is unable to communicate with the Helm Repository that hosts the Chart. However, note that when Apollo deploys a Helm Chart, it always does so by locating the chart in the specified Helm Repository using the name and version defined in the Helm Chart metadata. This means that, even if you publish a local Helm Chart file using the CLI, it must be available in the Helm Chart repository for Apollo to deploy it.

The following steps demonstrate how to use the apollo-cli to publish version 16.9.11 of the Redis Helm Chart downloaded locally.

If you select Install on the Artifact Hub Bitnami Redis page, you can download a .tgz of the Helm Chart (the link reads "You can also download this package's content directly using this link"). Download the TGZ (it should be named redis-16.9.11.tgz) and put it in the same directory as the apollo-cli.

Once the file has been downloaded, you can publish it to Apollo using the CLI with the following command:

Copied!
1
2
3
$ ./apollo-cli publish helm-chart --chart-file redis-16.9.11.tgz --helm-repository-url "https://charts.bitnami.com/bitnami" --maven-coordinate "com.bitnami:redis:16.9.11"
Uploading artifact to https://<Hub>.palantircloud.com/artifactory/internal-dist-release/com/bitnami/redis/16.9.11/redis-16.9.11.helmchart.config.tgz ... done
Publishing product release com.bitnami:redis:16.9.11 into Apollo ... done

Because the --chart-file flag is specified, it is not necessary to provide the --helm-chart-name or --helm-chart-version: these values are parsed from the metadata in the Helm Chart file. However, the --helm-repository-url flag is still required because Apollo always obtains the Helm Chart to deploy from the Helm Repository (this URL is not queried as part of the upload operation performed by the CLI, but will be used by Apollo when deploying the product).

Installing the Published Redis Product

The result of either publish operation above is that the Helm Chart Product com.bitnami:redis:16.9.11 has been published to Apollo. If you have also created an Environment, then you can now install Redis into the Environment.

Navigate to the Settings tab of the Environment page and select Install helm-charts. You can then select redis from the Select product dropdown.

From there, you can configure and deploy the Helm Chart. See Managing Entities with Apollo for more information about this process.

Example 2: Publishing an Asset to Apollo using the CLI

In this example, we are going to publish some custom files as an Asset in Apollo.

Assume that we have a directory called my-product that contains the following files:

Copied!
1
2
3
4
5
6
$ tree my-product
my-product
├── taxi_info.csv
└── test_data.zip

1 directory, 2 files

When you create an Apollo Product tarball, it should look like this:

asset-1.2.3  # <product-name>-<product-version>
├── asset  # directory of arbitrary files to include
│   └── ...
└── deployment
    └── manifest.yml

In your manifest.yml, the product-type should be asset.v1.

The following apollo-cli command creates an Asset Product that bundles the my-product directory and then publishes the Product to Apollo using the identifier com.my-org:my-product:0.0.2:

Copied!
1
2
$ ./apollo-cli publish asset --maven-coordinate "com.my-org:my-product:0.0.2" --asset-path my-product
Publishing product release com.my-org:my-product:0.0.2 into Apollo ... done

You can publish an Asset Product with images by adding the --images flag:

Copied!
1
2
$ ./apollo-cli publish asset --maven-coordinate "com.my-org:my-product:0.0.2" --asset-path my-product --images docker.io/bitnami/postgresql:16.0.0-debian-11-r10
Publishing product release com.my-org:my-product:0.0.2 into Apollo ... done

Complete flag details can be viewed by running ./apollo-cli publish asset --help, but the following is an overview:

• --maven-coordinate: The user-chosen Apache Maven coordinate that will act as the address for the Product Release in Apollo. This can be any valid Maven coordinate of the form group:product-name:version.
• --asset-path: Filename or directory for Assets to be published to Apollo.
• --images: Container image URIs that Apollo will check for availability before recommending an upgrade to a containerized Entity.