Using rackctl in CI/CD Pipelines

This guide provides instructions for integrating rackctl into various CI/CD pipelines such as GitHub Actions, GitLab CI, Jenkins, and Tekton. It covers the authentication process, security best practices, and example configurations.

Authentication for CI/CD Pipelines

Why Long-lived Tokens?

While the default session tokens expire after 5 minutes, CI/CD pipelines often require longer-lived authentication. This is especially important for:

• Long-running deployment processes
• Regular scheduled infrastructure checks
• Automated testing environments
• Multi-stage pipelines that create and manage clusters

Step 1: Generate a Long-lived API Token

1. Navigate to the Token Management page at https://portal.rackmint.com/#/manage-tokens
2. Click on Create token
3. Configure your token:
   • Name: Provide a descriptive name (e.g., “GitHub Actions Pipeline”)
   • Expiry: Select the number of days the token should remain valid (e.g., 30, 60, 90 days)
4. Click Create
5. Important: Copy and securely store the generated token immediately. It will only be displayed once.

Step 2: Install the Authentication Utility

The ginger-auth utility is required to convert your API token into a session token that rackctl can use.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- ginger-society/ginger-auth:latest

Note: While rackctl and ginger-auth can be used on Windows for local development, CI/CD pipeline integration is currently supported only on Linux/macOS runners.

Step 3: Use the Authentication Utility

Convert your API token to a session token and store it in your local authentication store:

ginger-auth token-login <api_token>

Security Best Practices

1. Never hardcode API tokens in scripts or configuration files
2. Use CI/CD platform’s secrets management:
   • GitHub Actions: Secrets
   • GitLab CI: CI/CD Variables
   • Jenkins: Credentials Plugin
   • Tekton: Secrets
3. Set appropriate expiry dates for your tokens
4. Rotate tokens regularly even before expiry
5. Use minimal permissions for each token
6. Audit token usage periodically through the dashboard

Integration Examples

GitHub Actions Example

name: Deploy Kubernetes Cluster

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v3
      
    - name: Install rackctl and ginger-auth
      run: |
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- rackmint/rackctl:latest
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- ginger-society/ginger-auth:latest
        
    - name: Authenticate and generate session token
      run: |
        ginger-auth token-login ${{ secrets.RACKMINT_API_TOKEN }}
      
    - name: Create Kubernetes cluster
      run: |
        rackctl create production-cluster \
          --description "Production cluster for ${{ github.repository }}" \
          --cpu-limit 4.0 \
          --ram-limit 8.0 \
          --do-not-delete true
        
    - name: Deploy application
      run: |
        # Additional deployment steps using kubectl
        kubectl apply -f kubernetes/deployment.yaml

GitLab CI Example

stages:
  - deploy

deploy_cluster:
  stage: deploy
  image: ubuntu:latest
  script:
    - apt-get update && apt-get install -y curl
    - bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- rackmint/rackctl:latest
    - bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- ginger-society/ginger-auth:latest
    - ginger-auth token-login ${RACKMINT_API_TOKEN}
    - rackctl create gitlab-cluster --description "Deployed from GitLab CI" --region-code ap_south_1
  only:
    - main

Jenkins Pipeline Example

pipeline {
    agent any
    
    environment {
        RACKMINT_API_TOKEN = credentials('rackmint-api-token')
    }
    
    stages {
        stage('Install Tools') {
            steps {
                sh '''
                bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- rackmint/rackctl:latest
                bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- ginger-society/ginger-auth:latest
                '''
            }
        }
        
        stage('Authenticate') {
            steps {
                sh 'ginger-auth token-login ${RACKMINT_API_TOKEN}'
            }
        }
        
        stage('Deploy Cluster') {
            steps {
                sh 'rackctl create jenkins-cluster --description "Deployed from Jenkins pipeline"'
            }
        }
    }
}

Tekton Pipeline Example

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: deploy-rackmint-cluster
spec:
  params:
    - name: api-token
      type: string
      description: Rackmint API token
  steps:
    - name: install-tools
      image: ubuntu:latest
      script: |
        apt-get update && apt-get install -y curl
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- rackmint/rackctl:latest
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- ginger-society/ginger-auth:latest
    
    - name: deploy-cluster
      image: ubuntu:latest
      script: |
        ginger-auth token-login $(params.api-token)
        rackctl create tekton-cluster --description "Deployed from Tekton pipeline"

Periodic Cluster Management

For long-running clusters that need regular maintenance or updates:

name: Weekly Cluster Maintenance

on:
  schedule:
    - cron: '0 0 * * 0'  # Run every Sunday at midnight

jobs:
  maintain:
    runs-on: ubuntu-latest
    
    steps:
    - name: Install tools
      run: |
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- rackmint/rackctl:latest
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- ginger-society/ginger-auth:latest
        
    - name: Authenticate
      run: |
        ginger-auth token-login ${{ secrets.RACKMINT_API_TOKEN }}
      
    - name: List clusters
      run: |
        rackctl ps
        
    # Additional maintenance steps

Troubleshooting Pipeline Authentication

If you encounter authentication issues in your pipelines:

1. Check token expiry: Ensure your API token hasn’t expired
2. Verify secret storage: Confirm the token is correctly stored in your CI/CD platform’s secrets
3. Check tool installation: Verify both rackctl and ginger-auth are installed properly

For persistent issues, capture the logs (remove sensitive information) and contact support for assistance.