Pocket Nebula ✨→👖

A Skeleton Dev Container preconfigured with the OpenNebula CLI, and Ansible

OpenNebula is an Open Source Cloud & Edge Computing Platform.

A development container allows you to use a container as an isolated, full-featured development environment.

Pocket Nebula provides an instant isolated environment for OpenNebula operations (host and guest config and management).

Overview

This repository provides a clean starting point for OpenNebula automation projects. It includes:

• DevContainer: Complete development environment with Ansible and OpenNebula tools
• Ansible Structure: Basic inventory and playbook examples
• Documentation: Setup guides and usage examples

Complete Setup Guide

This guide walks you through setting up Pocket Nebula from scratch to running your first automation.

Step 1: Prerequisites

Before starting, ensure you have:

1. Git: For cloning the repository
2. VS Code: With the Dev Containers Extension
3. Docker: For running the development container
4. OpenNebula Access: Your OpenNebula instance URL and credentials
5. SSH Keys: For Ansible host access (optional but recommended)

Step 2: Clone and Setup

Run these commands on your HOST system (not in the container):

# Clone the repository
git clone https://github.com/your-username/pocket-nebula.git
cd pocket-nebula

# Verify the repository structure
ls -la
# Expected: .devcontainer/, inventory/, roles/, README.md, etc.

⚠️ Important: If you see a prompt like vscode ➜ /workspaces/pocket-nebula (main) $, you're already inside the dev container! Exit to your host system first.

Step 3: Configure Environment Variables

Run these commands on your HOST system (not in the container):

Set up your OpenNebula credentials on your host system:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export ONE_USERNAME=your-opennebula-username
export ONE_PASSWORD=your-opennebula-password
export ONE_URL=https://your-opennebula-host/RPC2          # RPC API endpoint
export ONEFLOW_URL=https://your-opennebula-host:2474      # OneFlow endpoint (optional)

# Optional: Override CLI version (see CLI Version Management section)
export OPENNEBULA_CLI_VERSION_OVERRIDE="~> 6.10.0"

# Optional: Ansible vault password for encrypted files
export ANSIBLE_VAULT_PASSWORD=your-vault-password

# Reload your shell profile
source ~/.bashrc  # or ~/.zshrc

Step 4: Setup OpenNebula CLI (Optional)

Run these commands on your HOST system (not in the container):

For OpenNebula CLI authentication:

# Create OpenNebula credentials directory
mkdir -p ~/.one

# Create authentication file
echo "your-username:your-password" > ~/.one/one_auth
chmod 600 ~/.one/one_auth

# Verify the file was created
ls -la ~/.one/

Step 5: Setup Ansible Vault (Recommended)

Run these commands on your HOST system (not in the container):

For encrypted sensitive data:

# Create vault directory
mkdir -p ~/.ansible-vault

# Create vault password file
echo "your-vault-password" > ~/.ansible-vault/.vault-file
chmod 600 ~/.ansible-vault/.vault-file

# Verify the setup
ls -la ~/.ansible-vault/

Step 6: Launch the DevContainer

Run these commands on your HOST system (not in the container):

# Open VS Code in the project directory
code .

# In VS Code:
# 1. Press Ctrl+Shift+P (Cmd+Shift+P on Mac)
# 2. Type "Dev Containers: Reopen in Container"
# 3. Select the command
# 4. Wait for the container to build (first time may take 5-10 minutes)

✅ Success: You'll know you're in the container when you see the prompt change to vscode ➜ /workspaces/pocket-nebula (main) $

Step 7: Verify the Setup

Run these commands INSIDE the dev container (you should see vscode ➜ /workspaces/pocket-nebula (main) $):

Once the container is running, verify everything is working:

# Check environment variables are loaded
env | grep ONE
# Expected output:
# ONE_USERNAME=your-username
# ONE_PASSWORD=your-password
# ONE_URL=https://your-opennebula-host/RPC2
# ONEFLOW_URL=https://your-opennebula-host:2474

# Test OpenNebula CLI
onevm list
# Should show your VMs or an empty list

# Test Ansible installation
ansible --version
# Should show Ansible version and configuration

# Test ansible-lint
ansible-lint --version
# Should show ansible-lint version

# Check mounted directories
ls -la ~/.ssh/     # Should show your SSH keys
ls -la ~/.one/     # Should show OpenNebula credentials
ls -la ~/.ansible-vault/  # Should show vault files

Step 8: Run Your First Automation

Run these commands INSIDE the dev container (you should see vscode ➜ /workspaces/pocket-nebula (main) $):

# View the available inventory
ansible-inventory --inventory inventory/opennebula --graph

# Run the example playbook
ansible-playbook --inventory inventory/opennebula catalog-guests.yml

# Check the playbook output
cat catalog-guests.yml

🔧 CLI Tools Version Management

This devcontainer automatically detects your OpenNebula server version and installs compatible CLI tools.

Automatic Detection

The devcontainer uses the one.system.version XML-RPC method to detect your server version:

# Check what version was detected
.devcontainer/detect-opennebula-version.sh

# See the CLI version specifier that would be used
.devcontainer/detect-opennebula-version.sh cli-spec

Manual Override

You can override the automatic detection by setting OPENNEBULA_CLI_VERSION_OVERRIDE in your host environment or .devcontainer/devcontainer.env:

# Force install 6.8.x compatible tools
OPENNEBULA_CLI_VERSION_OVERRIDE="~> 6.8.0"

# Install exact version
OPENNEBULA_CLI_VERSION_OVERRIDE="6.10.0"

# Install latest 7.x tools (if working with newer servers)
OPENNEBULA_CLI_VERSION_OVERRIDE="~> 7.0.0"

After changing the override, rebuild your devcontainer for the changes to take effect.

Version Detection Commands

# Show full server version
.devcontainer/detect-opennebula-version.sh

# Show CLI gem version specifier for compatibility
.devcontainer/detect-opennebula-version.sh cli-spec

# Show CLI version number
.devcontainer/detect-opennebula-version.sh cli-version

# Show configuration status
.devcontainer/show-opennebula-config.sh

Supported Version Detection

• OpenNebula 6.x servers: Compatible CLI tools (6.8, 6.10, etc.)
• OpenNebula 7.x servers: Compatible CLI tools (7.0+)
• Fallback: If detection fails, defaults to 6.10.x tools

Environment Variables

The devcontainer supports multiple configuration sources in order of precedence:

1. OpenNebula Credentials:

   • ONE_USERNAME and ONE_PASSWORD: Your OpenNebula credentials
   • ONE_URL: XML-RPC endpoint (required)
   • ONEFLOW_URL: OneFlow endpoint (optional)
   • OPENNEBULA_CLI_VERSION_OVERRIDE: Force specific CLI version (optional)

2. Ansible Configuration:

   • ANSIBLE_VAULT_PASSWORD: Vault password (highest priority)
   • ~/.ansible-vault/.vault-file: Vault password file (mounted from host)
   • vault_password_file setting in ansible.cfg

Note: The OPENNEBULA_USER_PASS variable in devcontainer.env is a template and not used by default. Your actual OpenNebula credentials should be set via the ONE_USERNAME and ONE_PASSWORD environment variables, which take precedence.

Host Mounts

The container automatically mounts these directories from your host:

• ~/.ssh → /home/vscode/.ssh (SSH keys for Ansible)
• ~/.one → /home/vscode/.one (OpenNebula CLI credentials)
• ~/.ansible-vault → /home/vscode/.ansible-vault (Ansible vault files)

Usage Examples

All commands below should be run INSIDE the dev container (you should see vscode ➜ /workspaces/pocket-nebula (main) $):

OpenNebula CLI Operations

# List all VMs
onevm list

# List networks
onevnet list

# List hosts
onehost list

# List users
oneuser list

# Get VM details
onevm show <vm-id>

# Create a VM from template
onevm create <template-name>

Ansible Automation

# View inventory structure
ansible-inventory --inventory inventory/opennebula --graph

# Run playbook with inventory
ansible-playbook --inventory inventory/opennebula catalog-guests.yml

# Run with vault password
ansible-playbook --inventory inventory/opennebula your-playbook.yml --ask-vault-pass

# Test connectivity to hosts
ansible all --inventory inventory/opennebula -m ping

# Run ad-hoc commands
ansible all --inventory inventory/opennebula -m shell -a "uptime"

Code Quality

# Lint your Ansible playbooks
ansible-lint catalog-guests.yml

# Check syntax
ansible-playbook --syntax-check catalog-guests.yml

# Dry run (check mode)
ansible-playbook --inventory inventory/opennebula catalog-guests.yml --check

Available Tools

The devcontainer provides a complete development environment with:

• Ansible: Latest version with pipx isolation
• ansible-lint: Code quality and best practices checking
• OpenNebula CLI: Ruby-based command-line tools
• pyone: Python library for API integration
• VS Code Extensions: Docker and Ansible support

Project Structure

pocket-nebula/
├── .devcontainer/          # Development container configuration
│   ├── Dockerfile          # Container image definition
│   ├── devcontainer.json   # VS Code devcontainer config
│   ├── devcontainer.env    # Environment variables template
│   └── setup.sh           # Container setup script
├── inventory/              # Ansible inventory files
│   └── opennebula/        # OpenNebula-specific inventory
├── roles/                  # Ansible roles (add your own)
│   └── requirements.yml    # Role dependencies
├── catalog-guests.yml      # Example playbook
└── ansible.cfg            # Ansible configuration

Customization

This is a skeleton repository. Customize it for your specific needs:

1. Add Your Roles: Create Ansible roles in the roles/ directory
2. Configure Inventory: Update inventory/opennebula/opennebula.yml with your hosts
3. Create Playbooks: Add your automation playbooks
4. Environment Variables: Set up your specific OpenNebula instance details
5. CA Certificates: Add your own CA certificates if needed for your OpenNebula instance

Troubleshooting

Common Issues

SSL Certificate Issues:

# Add your CA certificate to the Dockerfile if needed
# Edit .devcontainer/Dockerfile and add:
# COPY your-ca.crt /usr/local/share/ca-certificates/
# RUN update-ca-certificates

Authentication Problems:

# Verify your OpenNebula credentials (run INSIDE container)
env | grep ONE

# Test OpenNebula connection (run INSIDE container)
onevm list

Ansible Connection Issues:

# Check SSH key permissions (run INSIDE container)
ls -la ~/.ssh/

# Test host connectivity (run INSIDE container)
ansible all --inventory inventory/opennebula -m ping

Vault Issues:

# Verify vault password is accessible (run INSIDE container)
ls -la ~/.ansible-vault/

# Test vault password (run INSIDE container)
echo $ANSIBLE_VAULT_PASSWORD

Container Build Issues:

# Rebuild the container from scratch (takes a few minutes)
# In VS Code: Ctrl+Shift+P → "Dev Containers: Rebuild Container without Cache"

Wrong Terminal Location:

• If you see vscode ➜ /workspaces/pocket-nebula (main) $ but need to run host commands, exit the container first
• If you don't see that prompt but need to run container commands, make sure you're in the dev container

Contributing

This is a skeleton repository. Feel free to:

• Fork and customize for your projects
• Submit improvements to the devcontainer setup
• Add example playbooks and roles
• Improve documentation

License

This project is provided as-is for educational and development purposes.