Getting Started

Get up and running with Odin on a local Kubernetes cluster. This guide will walk you through installation, configuration, and deploying your first service.

Prerequisites

Hardware Requirements

Local Development (Kind Cluster)

Resource	Minimum
RAM	8 GB
CPU	4 cores
Disk Space	20 GB free
OS	macOS 11+, Linux (Ubuntu 20.04+)

Software Requirements

The following tools must be installed on your system:

Tool	Minimum Version	Installation
kubectl	v1.24+	Install Guide
Helm	v3.8+	Install Guide
Docker	v20.10+	Install Guide
curl	v7.68+	Pre-installed on most systems

Note

The installation script will automatically check for these prerequisites and guide you through installing any missing tools.

Kubernetes Version Compatibility

Kubernetes Version	Status
1.30 - 1.34	✅ Compatible
< 1.29	⚠️ Not Tested

Quick Start: One-Command Installation

Get Odin running on a local Kind cluster in under 15 minutes:

bash <(curl -fsSL https://raw.githubusercontent.com/ds-horizon/odin/master/install.sh)

What This Does

The installation script automatically:

1. ✅ Clones the Odin repository
2. ✅ Checks and installs prerequisites (kubectl, Helm, Docker, Kind)
3. ✅ Creates a local Kind cluster named odin-cluster
4. ✅ Sets up local Docker registry
5. ✅ Installs KEDA and Percona MySQL Operator
6. ✅ Deploys Odin with all components
7. ✅ Creates local development accounts
8. ✅ Optionally installs Odin CLI

Expected Duration: 7-10 minutes (depending on internet speed and hardware)

Installation Output

You’ll see output similar to:

╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║             Odin Helm Chart Installation                  ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝

[Step 1/14] Checking kubectl installation
✓ kubectl is available

[Step 2/14] Checking Helm installation
✓ Helm is available

[INFO] Would you like to install Odin on a local Kind cluster? [y/N]: y

[Step 3/14] Setting up Docker for Kind cluster
✓ Docker is running

[Step 4/14] Installing Kind
✓ Kind installed successfully

[Step 5/14] Setting up Docker registry for Kind
✓ Local registry 'kind-registry' started

[Step 6/14] Creating Kubernetes cluster
✓ Kind cluster 'odin-cluster' is ready

...

[Step 14/14] Installing Odin CLI
✓ Odin CLI installed successfully!

🎉 Odin installation completed successfully!

CLI Setup

After installation completes, configure the Odin CLI:

Step 1: Locate the CLI Binary

If you installed the CLI during installation:

# CLI is installed in your home directory
ls -la ~/odin

# Move to PATH
sudo mv ~/odin /usr/local/bin/odin
chmod +x /usr/local/bin/odin

Step 2: Verify CLI Installation

# Check version
odin version

Step 3: Port-Forward to Deployer

Open a terminal and forward the deployer service to localhost:

# Forward deployer service to localhost
kubectl port-forward svc/odin-deployer -n odin 8080:80

Note

Keep this terminal open. Open a new terminal for the next steps.

Step 4: Configure Odin CLI

In a new terminal, configure the CLI to connect to your local Odin backend:

# Configure Odin CLI for local development
odin configure --org-id 0 --backend-address 127.0.0.1:8080 -I -P

Flags explained:

• --org-id 0: Use organization ID 0 (default for local development)
• --backend-address 127.0.0.1:8080: Connect to port-forwarded deployer
• -I: Skip TLS host verification (insecure mode for local dev)
• -P: Use plaintext gRPC without TLS

Step 5: Test the Installation

# List environments (should be empty initially)
odin list env

If you see the output without errors, congratulations! 🎉 Odin is successfully installed and configured.

Next Steps: Deploy Your First Service

Now that Odin is installed and configured, you can deploy your first service:

1. Create an Environment: Set up an isolated namespace for your services
2. Define Your Service: Create a service definition JSON
3. Configure Provisioning: Specify how components should be deployed
4. Deploy: Use the CLI to deploy your service

For a complete walkthrough, see:

• Deploy Your First Service - Step-by-step tutorial
• Key Concepts - Understand environments, services, and components
• CLI Reference - Complete command documentation

Common CLI Commands

Here are some common commands you’ll use:

# List all environments
odin list env

# Create an environment
odin create env dev --accounts docker/local

# Describe an environment
odin describe env dev

# Deploy a service
odin deploy service --env dev --file service.json --provisioning provisioning.json

# Check service status
odin status env dev --service my-service

# Undeploy a service
odin undeploy service my-service --env dev

# Get help
odin --help
odin deploy --help

Troubleshooting

Need help?

For more installation and configuration questions, see the Installation FAQ.

Port-Forward Connection Issues

If you can’t connect to the backend:

# Check if port-forward is running
ps aux | grep "port-forward"

# Verify deployer pod is running
kubectl get pods -n odin | grep deployer

# Restart port-forward
kubectl port-forward svc/odin-deployer -n odin 8080:80

CLI Configuration Issues

If odin list env fails:

# Check CLI configuration
cat ~/.odin/config

# Reconfigure with verbose output
odin configure --org-id 0 --backend-address 127.0.0.1:8080 -I -P --verbose

Cluster Issues

Check cluster health:

# Check all pods in odin namespace
kubectl get pods -n odin

# Check specific component logs
kubectl logs -n odin deployment/odin-deployer

# Describe pod for events
kubectl describe pod -n odin <pod-name>

Advanced Installation Options

Installing on Existing Kubernetes Cluster

To install on an existing cluster instead of Kind:

# Clone the repository
git clone https://github.com/ds-horizon/odin.git
cd odin

# Install with Helm directly
helm install odin ./charts/odin --namespace odin --create-namespace

Custom Installation with Values

For production or custom configurations:

# Create custom values file
cat > custom-values.yaml <<EOF
deployer:
  replicaCount: 2
  resources:
    requests:
      cpu: 500m
      memory: 1Gi

mysql:
  mysql:
    size: 3

redis:
  architecture: replication
  replica:
    replicaCount: 2
EOF

# Install with custom values
./install.sh --values custom-values.yaml

Uninstallation

To remove Odin from your cluster:

# Using the uninstall script
cd odin
./uninstall.sh

# Or manually with Helm
helm uninstall odin -n odin
kubectl delete namespace odin

What’s Installed

After successful installation, your cluster will have:

Component	Purpose
odin-deployer	Main deployment orchestration service
odin-orchestrator	Job orchestration with KEDA autoscaling
odin-account-manager	Cloud provider account management
odin-discovery-service	Service discovery and registration
MySQL (Percona)	Database for state management
Redis	Caching and session storage
MinIO	Object storage for artifacts
ElasticMQ	Message queue (SQS-compatible)
FluentBit	Log aggregation

Next Steps

🎉 Success!

Congratulations! You’ve successfully installed Odin and configured the CLI.

Next steps:

• Deploy Your First Service - Complete walkthrough
• Key Concepts - Understand services, components, and environments
• CLI Reference - All available commands
• How-To Guides - Common tasks and workflows

Additional Resources

• GitHub Repository: https://github.com/ds-horizon/odin
• Issue Tracker: https://github.com/ds-horizon/odin/issues
• Helm Chart: https://github.com/ds-horizon/odin/tree/master/charts/odin
• License: GNU Lesser General Public License