Use the Contrail CLI to Simplify and Automate Developer Workflows¶

Authentication¶

To use the Contrail CLI, you need to authenticate to your organization. This can be done by setting environment variables or using file-based configuration.

Org Slug¶

Authentication to the CLI always requires an org slug, which is the unique identifier of your organization. All CLI commands are organization-specific, so you will always need an org slug when interacting with the CLI. It is an important part of your authentication package.

Credentials¶

You can use either an API key or an email/password combination as your authenticating credentials to the organization. Using an API key is recommended since it can be revoked more easily and is scoped to only one organization.

Authenticating as an SSO User

If your organization uses SSO for login, you do not have a VibeIQ password and cannot authenticate to the CLI using your password. Please use an app API key to authenticate to the CLI instead.

Using Environment Variables¶

Authenticating with an API Key (Recommended)¶

You can generate an API key by creating an initial integration app. This will create an app user in the VibeIQ organization. The app will also have an associated API key that you can use to run CLI commands. When running these commands with an app API key, all actions performed by the CLI will register as actions taken by that app.

Create an app to get an API key

contrail app create # create an empty integration app
contrail app publish # publish the app to your organization
contrail app install # install the app in your organization
contrail app getApiKey # get the app API key

Once you have an app API key, you can use it in your automation scripts by setting it as the CONTRAIL_CLI_API_KEY environment variable.

Use the API key to authenticate when running CLI commands

export CONTRAIL_CLI_API_KEY="MY_SECRET_KEY"
export CONTRAIL_CLI_ORG_SLUG="MY_ORG_SLUG"
contrail types getAll # an example CLI command that requires authentication

Authenticating with Email and Password¶

You can authenticate to the CLI using the same email and password used to log in to the VibeIQ platform.

You can directly use your email and password when running CLI commands

export CONTRAIL_CLI_EMAIL="me@example.com"
export CONTRAIL_CLI_PASSWORD="SECRET_PASSWORD"
export CONTRAIL_CLI_ORG_SLUG="MY_ORG_SLUG"
contrail types getAll # an example CLI command that requires authentication

Storing authentication credentials in a configuration file¶

You can store authentication credentials in a configuration file by following these steps:

1. Create a Configuration File¶

Use the following command to create an empty configuration file for your organization. Replace ORG_SLUG with your organization's slug.

contrail config create --name=ORG_SLUG

2. Use the Configuration File¶

Set the created configuration file as the current one. This will ensure that all subsequent commands will use this configuration file.

contrail config use ORG_SLUG

3. Store Credentials in the Configuration File¶

Run a command that requires authentication, such as contrail app getApiKey. This will prompt you for your credentials, which will then be stored in the configuration file.

contrail app getApiKey

The configuration file will be stored at the following location:

/Users/apple/.vibeiq/configs/ORG_SLUG.json

By following these steps, you can securely store your authentication credentials in a configuration file and use them for subsequent CLI commands.

Using Contrail CLI for Automation¶

The Contrail CLI enables organizations to automate common tasks like exporting and backing up configurations or publishing and deploying new versions of your app. This guide provides a step-by-step explanation of how to automate the usage of the Contrail CLI with CI/CD tools like GitHub Actions.

The following sample GitHub Actions workflow automates the process of using the Contrail CLI to export organizational configuration and commits changes to the main branch if any updates are detected.

Workflow Breakdown¶

1. Workflow Dispatch¶

The workflow is triggered manually through the workflow_dispatch event.

2. Job Setup: `useContrailCli`¶

This job, useContrailCli, runs on an ubuntu-20.04 environment and follows these steps:

Install Node.js: Sets up Node.js to support the Contrail CLI.
Install contrail-cli: Installs the Contrail CLI globally using npm.

jobs:
  useContrailCli:
    runs-on: ubuntu-20.04
    steps:
      - name: Install Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: Install contrail-cli
        run: npm install -g @contrail/cli

3. Repository Setup¶

This section involves setting up the repository by following these steps:

Checkout Repository: Checks out the repository’s main branch.
Create a New Branch: Generates a unique branch ID for tracking changes and creates a new branch based on the main branch.

- name: Checkout the repo
  uses: actions/checkout@v4
  with:
    ref: main

- name: Create a new branch
  run: |
    NEW_BRANCH_ID=$(uuidgen)
    NEW_BRANCH_NAME="zts-wf-test${NEW_BRANCH_ID}"
    git checkout -b "$NEW_BRANCH_NAME"

4. Export Configuration Using Contrail CLI¶

This section details the process for exporting configuration data using the Contrail CLI:

Export Org Config: Runs the Contrail CLI to export configuration data.

Note: You can use CONTRAIL_CLI_API_KEY or CONTRAIL_CLI_EMAIL and CONTRAIL_CLI_PASSWORD.

- name: Export the org config
  run: |
    cd ./history/config
    spawn contrail instance export -f
  env:
    CONTRAIL_CLI_EMAIL: ${{ secrets.CONTRAIL_CLI_EMAIL }}
    CONTRAIL_CLI_PASSWORD: ${{ secrets.CONTRAIL_CLI_PASSWORD }}
    CONTRAIL_CLI_ORG_SLUG: ${{ secrets.CONTRAIL_CLI_ORG_SLUG }}
    CONTRAIL_CLI_API_KEY: ${{ secrets.CONTRAIL_CLI_API_KEY }}

Security Considerations¶

This section outlines the security measures taken in the workflow:

Use of GitHub Secrets: The workflow utilizes GitHub Secrets (CONTRAIL_CLI_EMAIL, CONTRAIL_CLI_PASSWORD, CONTRAIL_CLI_ORG_SLUG, and CONTRAIL_CLI_API_KEY) to securely handle credentials. Ensure that these secrets are correctly configured in your repository settings to prevent unauthorized access.

Conclusion¶

This automation simplifies the process of exporting and versioning organization configuration with the Contrail CLI through GitHub Actions. It provides an efficient, trackable, and CI/CD-friendly workflow.