Skip to content

overview.md

Latest commit

 

History

History
299 lines (241 loc) · 8.18 KB

overview.md

File metadata and controls

299 lines (241 loc) · 8.18 KB
Raw

Virak CLI Guides

This section provides comprehensive guides for using the Virak CLI to manage your Virak Cloud resources programmatically, as an alternative to using the web panel.

Overview

The Virak CLI allows you to interact with Virak Cloud API directly from your terminal, enabling automation, scripting, and faster operations for developers and DevOps teams.

Prerequisites

  • Go 1.21 or later
  • Virak Cloud account
  • API token (obtain from panel)

Installation

From Releases

Download the latest binary from GitHub Releases.

For Linux:

wget https://github.com/virak-cloud/cli/releases/download/latest/virak-cli-linux-amd64
chmod +x virak-cli-linux-amd64
sudo mv virak-cli-linux-amd64 /usr/local/bin/virak-cli

From Source

git clone https://github.com/virak-cloud/cli.git
cd cli
go build -o virak-cli main.go

Authentication

Before using the CLI, you need to authenticate with your Virak Cloud account. There are several ways to configure API credentials:

Method 1: Interactive Login

virak-cli login

This opens your browser for OAuth authentication.

Method 2: Token-based Authentication

virak-cli login --token YOUR_API_TOKEN

Obtain the API token from the Virak Cloud panel under Web Services > API Tokens.

Method 3: Configuration File

Create or edit ~/.virak-cli.yaml:

auth:
  token: "your-api-token"
default:
  zoneId: "your-default-zone-id"
  zoneName: "your-default-zone-name"

Method 4: Environment Variables

Set the token as an environment variable:

export VIRAK_CLI_TOKEN="your-api-token"

Command Aliases

You can also use:

virak-cli log-in --token YOUR_API_TOKEN
# or
virak-cli auth --token YOUR_API_TOKEN

Configuration

Optional configuration in ~/.virak-cli.yaml:

auth:
  token: "your-api-token"
default:
  zoneId: "your-default-zone-id"
  zoneName: "your-default-zone-name"

Getting Help

virak-cli --help
virak-cli <command> --help

Available Guides

  • Instances - Manage virtual machines
  • Networks - Configure private networks and firewalls
  • DNS - Manage domains and DNS records
  • Buckets - Object storage operations
  • Kubernetes Clusters - Deploy and manage K8s clusters
  • Finance - Wallet and billing management
  • User - User profile and SSH keys
  • Zones - Zone and service management

Core Command Families

Command Purpose Quick Reference
virak-cli login Authenticate via browser or token virak-cli login --token $VIRAK_CLI_TOKEN
virak-cli zone ... Discover regions, networks, and service availability virak-cli zone list, virak-cli zone resources --zoneId zone-xyz
virak-cli instance ... Provision and operate compute resources See cli-instances.md for create/start/stop/snapshot workflows
virak-cli network ... Manage L2/L3 networks, firewalls, load balancers, VPN See cli-networks.md
virak-cli bucket ... Manage object storage buckets and events See cli-buckets.md
virak-cli cluster ... Create and scale managed Kubernetes clusters See cli-kubernetes.md
virak-cli dns ... Control domains and record types (A, AAAA, MX, CAA, TLSA) See cli-dns.md
virak-cli finance ... Wallet, invoices, payments, expenses See cli-finance.md
virak-cli user ... Profile, SSH keys, token abilities See cli-user.md

Run virak-cli --help or virak-cli <command> --help for autogenerated flag documentation. Every subcommand also honors --zoneId when a zone context is required.

Each guide provides CLI equivalents for panel operations, with examples and common use cases.

CI/CD Integration

Secure Credential Management

For automated infrastructure deployments, securely manage API credentials:

Environment Variables (Recommended)

# Set in CI/CD pipeline settings
export VIRAK_CLI_TOKEN="your-api-token"
export VIRAK_CLI_ZONE_ID="your-default-zone"

# Use in scripts
virak-cli instance create --name "ci-instance" --service-offering-id "so-123" --vm-image-id "img-456" --network-ids '["net-789"]'

Configuration Files

Create a temporary config file in CI/CD:

# .virak-cli.yaml (generated in pipeline)
auth:
  token: "$VIRAK_CLI_TOKEN"
default:
  zoneId: "$VIRAK_CLI_ZONE_ID"

Best Practices

  • Store tokens as encrypted secrets in CI/CD platform
  • Use short-lived tokens with minimal permissions
  • Rotate tokens regularly
  • Never commit credentials to version control
  • Use separate tokens for different environments

Pipeline Examples

GitHub Actions

name: Deploy Infrastructure
on: push

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Virak CLI
        run: |
          wget https://github.com/virak-cloud/cli/releases/download/latest/virak-cli-linux-amd64
          chmod +x virak-cli-linux-amd64
          sudo mv virak-cli-linux-amd64 /usr/local/bin/virak-cli
      - name: Deploy Instance
        env:
          VIRAK_CLI_TOKEN: ${{ secrets.VIRAK_TOKEN }}
        run: |
          virak-cli instance create \
            --name "app-${{ github.run_number }}" \
            --service-offering-id "so-web" \
            --vm-image-id "img-ubuntu-22" \
            --network-ids '["net-prod"]'

Jenkins Pipeline

pipeline {
    agent any
    environment {
        VIRAK_CLI_TOKEN = credentials('virak-cli-token')
    }
    stages {
        stage('Deploy') {
            steps {
                sh '''
                    virak-cli instance create \
                      --name "jenkins-${BUILD_NUMBER}" \
                      --service-offering-id "so-app" \
                      --vm-image-id "img-centos" \
                      --network-ids '["net-dev"]'
                '''
            }
        }
    }
}

Scripting and Automation

Error Handling

Detect and handle scenarios where resources don't exist:

#!/bin/bash

INSTANCE_ID="inst-12345"

# Check if instance exists
if virak-cli instance show "$INSTANCE_ID" >/dev/null 2>&1; then
    echo "Instance exists, deleting..."
    virak-cli instance delete "$INSTANCE_ID"
else
    echo "Instance $INSTANCE_ID does not exist"
    exit 1
fi

Resource Existence Checks

# Function to check if bucket exists
bucket_exists() {
    local bucket_name="$1"
    if virak-cli bucket list | grep -q "$bucket_name"; then
        return 0
    else
        return 1
    fi
}

# Usage
if bucket_exists "my-bucket"; then
    echo "Bucket exists"
else
    echo "Bucket does not exist"
    virak-cli bucket create --name "my-bucket" --zone-id "zone-123"
fi

Retry Logic

# Retry instance creation with backoff
create_instance_with_retry() {
    local max_attempts=3
    local attempt=1
    
    while [ $attempt -le $max_attempts ]; do
        echo "Attempt $attempt of $max_attempts"
        if virak-cli instance create --name "test-instance" --service-offering-id "so-123" --vm-image-id "img-456" --network-ids '["net-789"]'; then
            echo "Instance created successfully"
            return 0
        else
            echo "Creation failed, retrying in $((attempt * 10)) seconds..."
            sleep $((attempt * 10))
            ((attempt++))
        fi
    done
    
    echo "Failed to create instance after $max_attempts attempts"
    return 1
}

Parsing JSON Output

For scripting, parse CLI output:

# Get instance details as JSON and extract ID
INSTANCE_JSON=$(virak-cli instance show "$INSTANCE_ID" --output json)
INSTANCE_NAME=$(echo "$INSTANCE_JSON" | jq -r '.name')

# List all instances and process each
virak-cli instance list --output json | jq -r '.data[].id' | while read -r id; do
    echo "Processing instance: $id"
    # Perform operations on each instance
done

Cleanup Scripts

# Cleanup old instances
virak-cli instance list --output json | jq -r '.data[] | select(.created_at < "'$(date -d '7 days ago' +%Y-%m-%d)'") | .id' | while read -r id; do
    echo "Deleting old instance: $id"
    virak-cli instance delete "$id"
done