CI/CD pipeline guide

CI/CD pipeline guide

This guide provides instructions for integrating rackctl into GitHub Actions. 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 rackctl

rackctl now has a built-in token-login command, so there’s no separate authentication utility to install — rackctl alone is enough.

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

Step 3: Exchange the API Token for a Session Token

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

rackctl token-login <api_token>

This saves the session token to ~/.ginger-society/auth.json, which rackctl reads automatically on subsequent commands. You can still override it at any time by exporting RACKCTL_SESSION_TOKEN.

Security Best Practices

  1. Never hardcode API tokens in scripts or configuration files
  2. Use GitHub Actions Secrets to store your API token
  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

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
      run: |
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- rackmint/rackctl:latest

    - name: Authenticate and generate session token
      run: |
        rackctl 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

    - name: Deploy application
      run: |
        # Additional deployment steps using kubectl
        kubectl apply -f kubernetes/deployment.yaml

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 rackctl
      run: |
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/ginger-society/infra-as-code-repo/main/rust-helpers/installer.sh)" -- rackmint/rackctl:latest

    - name: Authenticate
      run: |
        rackctl 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 GitHub Actions Secrets
  3. Check tool installation: Verify rackctl is installed properly
  4. Check token-login output: rackctl token-login <token> should report that the API token was saved to ~/.ginger-society/auth.json; if it errors out, the API token itself is likely invalid or expired

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