Skip to main content

RunOS Terminology

This glossary defines key terms and concepts you'll encounter while using RunOS. Understanding these terms will help you navigate the platform and make informed decisions about your infrastructure.

Core RunOS Concepts​

Account​

The top-level organizational unit in RunOS. An account represents your organization or team and contains:

  • Multiple clusters
  • Team members (users)
  • Shared resources

Each user can belong to multiple accounts, making it easy to manage personal projects and team environments separately.

Cluster​

A group of servers (nodes) running Kubernetes that work together to host your applications and services. You can have multiple clusters per account (e.g., development, staging, production).

Key properties:

  • Cluster ID (CID) - Unique 3-character identifier
  • Name - Human-readable name for identification
  • Nodes - Servers that make up the cluster
  • Configuration state - Whether initial setup is complete

Use cases:

  • Separate environments (dev, staging, production)
  • Geographic distribution (US, EU, Asia)
  • Project isolation (different teams or clients)

Node​

A single physical or virtual server that is part of a cluster. Each node runs Kubernetes and can host applications and services.

Node types:

  • Control Plane nodes - Manage the Kubernetes cluster itself (API server, scheduler, controller)
  • Worker nodes - Run your applications and services
  • Hybrid nodes - Can do both (common in small clusters)

Node states:

  • Online - Connected and healthy
  • Offline - Disconnected or unreachable
  • Provisioning - Being set up
  • Error - Configuration or health issues

Application​

Your custom software deployed from a Git repository. RunOS builds your code into a container image and runs it in Kubernetes.

Application features:

  • Git-based deployment (GitHub, GitLab)
  • Automatic container builds
  • Generated or custom domains
  • Automatic SSL certificates
  • Horizontal scaling
  • Environment variables and secrets

Service (OSI Service)​

Pre-packaged open-source software that RunOS can deploy and manage for you. Services are production-ready with intelligent defaults.

Available services include:

  • Databases: PostgreSQL, MySQL, ClickHouse, FerretDB
  • Caching: Valkey (Redis), RabbitMQ
  • Storage: MinIO, Longhorn, Harbor
  • Monitoring: Grafana, Prometheus
  • AI/ML: Ollama, LiteLLM, Open WebUI
  • Messaging: Kafka, RabbitMQ
  • And many more...

OSID (RunOS Unique Service Id)​

A unique identifier assigned to each deployed service in RunOS. The OSID is used to reference and manage services.

Format: Typically service name followed by an 5 char alphanumeric code (e.g., mysql-d6ekr)

Usage:

  • Service URLs and endpoints
  • Internal references
  • API operations
  • Namespace names in Kubernetes

Kubernetes Concepts​

Kubernetes​

An open-source container orchestration system for automating deployment, scaling, and management of containerized applications. RunOS abstracts Kubernetes complexity while providing full access when needed.

What RunOS handles for you:

  • Cluster installation and setup
  • Network configuration
  • Storage provisioning
  • Certificate management
  • Ingress routing
  • Service discovery

Pod​

The smallest deployable unit in Kubernetes. A pod contains one or more containers running together on the same node.

Key characteristics:

  • Pods are ephemeral (can be replaced)
  • Share network namespace (same IP)
  • Share storage volumes
  • Scheduled together on same node

When you deploy an application or service, it runs in one or more pods.

Replica​

A copy of your application or service running in a separate pod. Multiple replicas provide:

  • High availability - If one fails, others continue serving traffic
  • Load balancing - Traffic distributed across replicas
  • Scalability - Handle more load with more replicas
  • Zero-downtime updates - Update one replica at a time

Example: Running 3 replicas of your web application ensures it stays available even if one pod crashes.

Namespace​

A way to divide cluster resources between multiple users, teams, or applications. Each service and application managed by RunOS lives in its own namespace, with the namespace name equal to the OSID (Open Service ID).

How RunOS uses namespaces:

  • Every service and application gets its own dedicated namespace
  • The namespace name matches the service's OSID
  • This ensures complete isolation between different services and applications
  • Resources can only interact within their namespace unless explicitly configured

Benefits:

  • Resource isolation between services
  • Access control boundaries
  • Naming scope (same name in different namespaces)
  • Resource quotas per namespace

Example namespaces:

  • default - Default namespace for resources
  • kube-system - Kubernetes system components
  • kube-public - Public resources
  • osid-abc123xyz - A RunOS-managed service with OSID "abc123xyz"

Kubeconfig​

A configuration file that allows kubectl (Kubernetes command-line tool) to connect to your cluster.

Contains:

  • Cluster API endpoint
  • Authentication credentials
  • Context information

How to access it:

  1. Click your user avatar in the top right corner
  2. Click Clusters on the left navigation
  3. Find your cluster in the list (must be Active)
  4. Click the KubeConfig button for that cluster
  5. View or download the kubeconfig file

Security Note: Your kubeconfig contains admin credentials. Protect it like a password and never share it or commit it to version control.

Usage:

# Use kubectl with your cluster
export KUBECONFIG=/path/to/kubeconfig
kubectl get pods

Networking Concepts​

Ingress​

A Kubernetes resource that manages external access to services in the cluster, typically HTTP/HTTPS traffic. RunOS uses Traefik as the ingress controller.

Ingress handles:

  • Routing traffic to services
  • SSL/TLS termination
  • Virtual hosting (multiple domains)
  • Load balancing

Cluster Domain (CD)​

The primary domain assigned to your cluster during initial configuration. This is a unique subdomain under one of the RunOS root domains.

Format: <subdomain>.<subdomain>.runos.xyz (e.g., i4y.rjwrn.runos.xyz)

What it's used for:

  • Kubernetes API access - https://k8s.i4y.rjwrn.runos.xyz:6446
  • Service endpoints - https://postgres-d6ekr.i4y.rjwrn.runos.xyz
  • Application domains - https://myapp-t7r4s.i4y.rjwrn.runos.xyz
  • SSL certificate - A wildcard Let's Encrypt certificate is issued once for *.i4y.rjwrn.runos.xyz

Important notes:

  • The cluster domain is assigned once during cluster creation
  • A wildcard SSL certificate covers all services and applications under this domain
  • Root domains can vary by account (runos.xyz, runos.io, etc.)
  • All services and applications automatically get subdomains under your cluster domain

Domain​

A URL where your application or service is accessible.

Domain types in RunOS:

  • Cluster domain subdomains - Automatically created under your cluster domain (e.g., myapp-t7r4s.i4y.rjwrn.runos.xyz)
  • Custom domains - Your own domains (requires DNS configuration)

Configuration:

  • Cluster domain subdomains are automatic - no configuration needed
  • For custom domains, point your DNS to RunOS
  • RunOS automatically obtains SSL certificates
  • Traffic routed to your application

SSL/TLS Certificate​

Digital certificate that enables HTTPS encryption for secure communication.

RunOS certificate management:

  • Automatic certificate issuance via Let's Encrypt
  • Automatic renewal (no manual intervention)
  • Managed by cert-manager
  • Free certificates for all domains

VPN (WireGuard)​

RunOS uses WireGuard VPN to create an encrypted mesh network between all your nodes, regardless of their physical location.

VPN interfaces:

  • wg0 - Internal Kubernetes network (172.24.0.0/16)
  • wg1 - User access network (172.24.200.0/21)

Benefits:

  • Works behind NAT/firewalls
  • No public IPs required
  • Encrypted communication
  • Automatic peer discovery

Storage Concepts​

Persistent Volume (PV)​

Storage in Kubernetes that persists beyond the lifecycle of individual pods. Used for databases, file storage, and stateful applications.

Storage types in RunOS:

  • OpenEBS - Local storage (default)
  • Longhorn - Distributed storage (optional)

OpenEBS​

Default storage system in RunOS. Provides high-performance local storage directly from node disks.

Characteristics:

  • High IOPS (input/output operations per second)
  • Low latency
  • Data tied to specific nodes
  • No network overhead

Best for:

  • Databases requiring high performance (PostgreSQL, MySQL, ClickHouse)
  • Single-node applications
  • Development environments
  • Workloads with high I/O requirements

Longhorn​

Distributed storage system that replicates data across multiple nodes for redundancy and high availability.

Characteristics:

  • Data replicated across nodes
  • Survives node failures
  • Higher latency than local storage
  • Network-based

Best for:

  • High availability setups (multi-node)
  • Applications that move between nodes
  • Shared storage needs
  • Production environments requiring redundancy

Storage Class​

Defines different types of storage available in your cluster. RunOS configures storage classes automatically.

Default storage class:

  • openebs-local - The default and fastest storage mechanism in RunOS
  • Provides direct local disk access with minimal overhead
  • Best for databases and high-performance workloads

Longhorn storage:

  • Distributed block storage that spreads data across multiple nodes
  • Useful for services like MinIO object store that benefit from distributed storage
  • Important: Often too slow for databases - use application-level replication instead
  • When used, RunOS creates a dedicated storage class for each Longhorn instance

When to use which:

  • Use openebs-local for: Databases (PostgreSQL, MySQL, ClickHouse), high-performance applications
  • Use Longhorn for: Object storage (MinIO), distributed file systems, multi-node data sharing

Security Concepts​

mTLS (Mutual Transport Layer Security)​

Authentication method where both client and server verify each other's identity using certificates. RunOS uses mTLS for secure communication between nodes and the control plane.

Benefits:

  • Strong authentication
  • Encrypted communication
  • Protection against impersonation
  • Automatic certificate management

Secret​

Kubernetes object for storing sensitive information like passwords, API keys, and certificates.

RunOS secret management:

  • Automatically generated for services
  • Encrypted at rest by default - All secrets are automatically encrypted when stored in the cluster
  • Encryption happens transparently without any configuration needed
  • Access controlled by namespace
  • Never exposed in logs or UI

What this means:

  • Your database passwords, API keys, and credentials are always encrypted
  • Even with direct access to the cluster storage, secrets cannot be read without proper authorization
  • RunOS handles all encryption automatically - you don't need to configure anything

RBAC (Role-Based Access Control)​

System for managing who can access what resources in Kubernetes. Coming soon to RunOS for fine-grained team permissions.

Deployment Concepts​

Container Image​

A packaged version of your application including code, runtime, libraries, and dependencies. RunOS builds container images from your Git repositories.

Image registries:

  • Docker Hub (public images)
  • GitHub Container Registry (your builds)
  • Harbor (self-hosted registry service)

Git Integration​

RunOS deploys applications directly from Git repositories. You need to authorize the official RunOS app to access your repositories.

Supported providers:

  • GitHub (currently)
  • GitLab (coming soon)
  • Bitbucket (coming soon)

Build methods:

1. BuildKit (Recommended)

  • Builds Docker images locally on your cluster using BuildKit
  • Faster and simpler setup
  • Images are built in-cluster and pushed to your local Harbor registry
  • Most efficient for most users

2. ARC Self-Hosted Runners (Advanced)

  • Uses GitHub Actions Runner Controller for building
  • Runs GitHub workflows on your own infrastructure
  • Gives you full control over the build process
  • More complex setup and often slower than BuildKit
  • Best for teams that need custom build workflows

Deployment flow:

  1. Pull code from Git repository
  2. Build image locally (using BuildKit or ARC)
  3. Push to local Harbor registry
  4. Deploy to your cluster

Deployment trigger:

  • Manual deployment from console
  • Webhook-based automatic deployment (coming soon)

Environment Variables​

Configuration values passed to your application at runtime. Used for API keys, database URLs, feature flags, etc.

In RunOS:

  • Set via console during deployment
  • Can use secrets for sensitive values
  • Updated without rebuilding image

Monitoring Concepts​

Prometheus​

Open-source monitoring system that collects metrics from your applications and infrastructure. Automatically deployed with RunOS clusters.

Metrics collected:

  • CPU and memory usage
  • Network traffic
  • Application-specific metrics
  • Service health

Grafana​

Visualization platform for creating dashboards and analyzing metrics. Integrated with RunOS for monitoring your cluster and services.

Features:

  • Pre-configured dashboards for services
  • Custom dashboard creation
  • Alerting (coming soon)
  • Query builder

Metrics​

Numerical measurements of system and application behavior over time.

Common metrics:

  • CPU usage - Processor utilization percentage
  • Memory usage - RAM consumption
  • Disk I/O - Read/write operations
  • Network traffic - Data sent/received
  • Request latency - Response time
  • Error rate - Failed requests

Acronyms Quick Reference​

  • API - Application Programming Interface
  • CD - Cluster Domain (RunOS-specific)
  • CIDR - Classless Inter-Domain Routing
  • CID - Cluster ID (RunOS-specific)
  • CLI - Command-Line Interface
  • CNI - Container Network Interface
  • DNS - Domain Name System
  • HA - High Availability
  • IOPS - Input/Output Operations Per Second
  • MFA - Multi-Factor Authentication
  • mTLS - Mutual Transport Layer Security
  • NAT - Network Address Translation
  • OSI - Open Service Interface (RunOS-specific)
  • OSID - RunOS Unique ID
  • PV - Persistent Volume
  • PVC - Persistent Volume Claim
  • RBAC - Role-Based Access Control
  • REST - Representational State Transfer
  • SSL - Secure Sockets Layer
  • TLS - Transport Layer Security
  • UI - User Interface
  • URL - Uniform Resource Locator
  • VPN - Virtual Private Network
  • YAML - YAML Ain't Markup Language

Understanding these terms will help you make the most of RunOS and communicate effectively about your infrastructure!