Armada VSCode Extension

A Visual Studio Code extension for Armada, the multi-Kubernetes cluster batch job scheduler.

Features

• Job Submission: Submit Armada jobs directly from YAML files in VSCode
• Job Management: View, monitor, and cancel jobs from the sidebar
• Queue Browsing: Browse and filter Armada queues and job sets
• Real-time Updates: Auto-refresh job status with configurable intervals
• YAML Validation: IntelliSense and schema validation for Armada job definitions
• Multi-Context Support: Switch between different Armada clusters
• Job Logs: View job logs directly in VSCode
• gRPC Integration: Native gRPC client for fast communication with Armada API

Installation

From VSIX (Development)

1. Package the extension:

   npm install
   npm run compile
   npm run package
   

2. Install the generated .vsix file in VSCode:

   • Open VSCode
   • Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
   • Type "Install from VSIX" and select the file

Quick Start

1. Configure Armada Connection

Run the command Armada: Setup Configuration or create ~/.armadactl.yaml:

currentContext: local
contexts:
  - name: local
    armadaUrl: localhost:30002
    execTimeout: 2m

2. Submit a Job

1. Create a file with .armada.yaml extension (e.g., hello-world.armada.yaml)

2. Write your job definition:

   queue: default
   jobSetId: my-job-set
   jobs:
     - priority: 1000
       namespace: default
       podSpec:
         containers:
           - name: hello
             image: busybox
             command: ["echo", "Hello from Armada!"]
   

3. Click the cloud upload icon in the editor or run Armada: Submit Job

Each job needs a pod spec with at least one container. Both spellings armadactl accepts work: podSpec: for a single spec, or podSpecs: as a list for a gang. The pod spec is a standard Kubernetes PodSpec, so fields such as priorityClassName, securityContext, initContainers, volumes, tolerations and imagePullSecrets are all forwarded as written. Any key that is not part of PodSpec is reported in the Armada output channel rather than ignored, which catches typos like imagePullPolcy.

3. Monitor Jobs

• Open the Armada sidebar (activity bar icon)
• View running and completed jobs
• Click on a job to see details
• Use the refresh button to update job status

Available Commands

Access these commands via Command Palette (Ctrl+Shift+P or Cmd+Shift+P):

Configuration

Configure the extension in VSCode Settings (File → Preferences → Settings → Armada):

Corporate networks and TLS-inspecting proxies

On networks that run a TLS-inspecting proxy (Zscaler, Netskope, or an internal CA), the certificate the extension actually receives is re-signed by the proxy. Node.js does not ship that CA, so every connection fails — usually as UNAVAILABLE with a certificate error such as unable to verify the first certificate or self signed certificate in certificate chain.

Point armada.caCertPath at your organisation's CA bundle:

// .vscode/settings.json, or your user settings
{
  "armada.caCertPath": "~/certs/corporate-ca.pem"
}

The bundle is added to Node's built-in root certificates rather than replacing them, so publicly-signed endpoints keep working. A leading ~ is expanded.

Both the gRPC connection to the Armada server and the HTTPS connection to Lookout use the bundle. Certificate problems are reported in the Armada output channel (View → Output → Armada), including how many extra certificates were loaded.

Getting a PEM bundle

The file must be PEM (-----BEGIN CERTIFICATE----- blocks); a DER-encoded .crt will be rejected with a conversion hint. Multiple certificates can be concatenated into one file, and you generally want the whole chain.

# macOS: export everything in the system keychain
security export -t certs -f pemseq \
  -k /Library/Keychains/System.keychain > ~/certs/corporate-ca.pem

# Linux: the distro bundle usually already contains company CAs
cp /etc/ssl/certs/ca-certificates.crt ~/certs/corporate-ca.pem

# Convert a DER/.crt file your IT team gave you
openssl x509 -inform der -in corporate-ca.crt -out ~/certs/corporate-ca.pem

# Capture the chain a proxy presents for your Armada server
openssl s_client -showcerts -connect armada.example.com:443 </dev/null \
  2>/dev/null > ~/certs/corporate-ca.pem

A caCertPath set on the active armadactl context takes precedence over this setting, so per-cluster bundles are possible:

currentContext: corp
contexts:
  corp:
    armadaUrl: https://armada.example.com
    caCertPath: ~/certs/corporate-ca.pem

Local Development Setup

Want to run a local Armada cluster for testing? We provide a complete development environment:

cd dev
make up      # Start local Armada cluster with kind
make status  # Check cluster status
make logs    # View operator logs
make down    # Tear down the cluster

This creates a local Kubernetes cluster with Armada installed and ready to use. See operator/README.md for details.

Development

See DEVELOPMENT.md for detailed development instructions.

Quick Development Setup

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Start watch mode for auto-recompilation
npm run watch

# Press F5 in VSCode to launch Extension Development Host

Running Tests

# Run integration tests
npm test

The integration tests verify all extension commands and can run against a local Armada instance. See src/test/README.md for more details.

CI/CD

This project uses GitHub Actions for automated building, testing, and publishing:

• CI Workflow: Automatically runs on pull requests to validate code quality, run tests, and build the extension
• Release Please: Manages versioning and changelogs using Conventional Commits
• Publish Workflow: Automatically publishes new releases to the VS Code Marketplace

See .github/workflows/README.md for detailed workflow documentation.

Release Process

1. Make changes on feature branches
2. Create PR to dev branch with conventional commit messages
3. Merge approved PRs to dev
4. Merge dev to main when ready for release
5. Release Please creates a release PR with auto-generated changelog
6. Merge the release PR to trigger publication to the marketplace

Project Structure

armada-vscode/
├── src/                    # TypeScript source code
│   ├── commands/          # Command implementations
│   ├── config/            # Configuration management
│   ├── grpc/              # gRPC client
│   ├── providers/         # TreeView providers
│   ├── proto/             # Protobuf definitions
│   └── types/             # TypeScript types
├── schemas/               # JSON schemas for YAML validation
├── examples/              # Example job files
├── dev/                   # Development tools
│   ├── operator/         # Local Armada operator setup
│   ├── scripts/          # Development scripts
│   └── Makefile          # Local cluster automation
└── resources/             # Extension resources (icons, etc.)

Requirements

• VSCode 1.85.0 or higher
• Node.js 20.x or higher (for development)
• Access to an Armada cluster (or use the local development setup)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Resources

• Armada Documentation
• Armada GitHub
• VSCode Extension API
• Issue Tracker

License

See LICENSE for details.

Support

• Open an issue on GitHub
• Join the Armada community: