Cluster Management

Managing your RunOS cluster involves understanding how to access it directly via kubectl, how changes are managed, and following best practices to ensure smooth operations.

Accessing Your Cluster with kubectl

RunOS provides full kubectl access to your cluster through a downloadable kubeconfig file.

Getting Your Kubeconfig

To download your admin kubeconfig:

1. Click your user avatar (circle with your initials) in the top right corner
2. Click Clusters on the left navigation
3. Find the cluster you want to access in the list
4. Ensure the cluster status is Active (kubeconfig only available for active clusters)
5. Click the KubeConfig button for that cluster
6. View or download the kubeconfig file

The kubeconfig file contains admin-level credentials for full cluster access.

Using Kubeconfig

Set up kubectl access:

# Save kubeconfig to default location
mkdir -p ~/.kube
mv ~/Downloads/kubeconfig ~/.kube/config

# Or use specific kubeconfig file
export KUBECONFIG=~/path/to/kubeconfig

# Verify connection
kubectl cluster-info
kubectl get nodes

Basic kubectl commands:

# View all resources in namespace
kubectl get all -n <OSID>

# View pods across all namespaces
kubectl get pods -A

# Describe a specific pod
kubectl describe pod <pod-name> -n <OSID>

# View logs
kubectl logs <pod-name> -n <OSID>

# Execute command in pod
kubectl exec -it <pod-name> -n <OSID> -- bash

# View cluster resource usage
kubectl top nodes
kubectl top pods -A

Kubeconfig Security

Important security considerations:

• Treat kubeconfig like a password - It contains admin credentials
• Never commit to version control - Add *kubeconfig* to .gitignore
• Store securely - Use encrypted storage or password manager
• Rotate regularly - Download new kubeconfig periodically
• Limit sharing - Only share with trusted team members

If your kubeconfig is compromised, contact RunOS support immediately to revoke access.

Understanding OSID Namespaces

Every service and application in RunOS runs in its own Kubernetes namespace, named using the OSID (Open Service ID).

OSID format: service-name-xxxxx

Examples:

• mysql-d6ekr - MySQL database instance
• postgres-k9m3w - PostgreSQL database
• myapp-t7r4s - Custom application

Why this matters:

All Kubernetes resources for a service/application are contained in its OSID namespace. When using kubectl, always specify the namespace:

# View all resources for a service
kubectl get all -n mysql-d6ekr

# Check pods for an application
kubectl get pods -n myapp-t7r4s

# View secrets (careful with sensitive data)
kubectl get secrets -n postgres-k9m3w

This organization keeps services isolated and makes management straightforward.

Important: Editing Kubernetes Resources

Changes Made Directly in Kubernetes

⚠️ Warning: Changes made directly to Kubernetes resources (using kubectl or the Kubernetes API) may be overridden when you update the service or application through RunOS.

What this means:

If you modify resources directly:

• ConfigMaps
• Secrets
• Deployments
• Services
• Ingress rules
• Resource limits
• Environment variables

And then update the service/application through the RunOS Console, your manual changes may be lost.

Why this happens:

RunOS manages service configurations and applies them to Kubernetes. When you update a service through the Console, RunOS generates fresh Kubernetes manifests based on your Console configuration, which replaces any manual changes made in the cluster.

Examples of affected changes:

# Editing a ConfigMap
kubectl edit configmap <name> -n <OSID>
# ⚠️ Will be overridden on next RunOS update

# Changing replicas
kubectl scale deployment <name> -n <OSID> --replicas=5
# ⚠️ Will be reset on next RunOS update

# Modifying environment variables
kubectl set env deployment/<name> -n <OSID> NEW_VAR=value
# ⚠️ Will be lost on next RunOS update

Current Recommendation

Until the fix is released:

1. Make changes through RunOS Console whenever possible
2. Document manual changes in a shared location
3. Be prepared to reapply manual changes after Console updates
4. Test in development before making manual production changes

When you must edit directly:

• Document what you changed and why
• Keep a backup of the modified resource
• Expect to reapply after Console updates
• Consider using GitOps or IaC for reproducibility

Fix Coming Soon

RunOS is working on a solution that will:

• Detect manual changes made in Kubernetes
• Preserve custom modifications during updates
• Merge Console changes with manual edits
• Provide warnings before overriding changes

Until then, be aware that manual Kubernetes changes may be temporary.

Best Practices

For Service Management

Do:

• ✅ Use RunOS Console for configuration changes
• ✅ Scale through Console UI
• ✅ Monitor via integrated dashboards
• ✅ Use OSID namespaces for organization
• ✅ Review logs through Log Viewer

Avoid:

• ❌ Direct kubectl edits of RunOS-managed resources
• ❌ Manual scaling that conflicts with Console settings
• ❌ Deleting resources without checking Console first
• ❌ Modifying labels/annotations RunOS uses

For Troubleshooting

Safe kubectl operations:

These operations are safe and won't be overridden:

# Viewing resources (always safe)
kubectl get/describe/logs <resource>

# Temporary debugging (changes are temporary)
kubectl port-forward <pod> 8080:80
kubectl exec -it <pod> -- bash

# Creating test resources in your own namespace
kubectl create namespace my-test
kubectl run test-pod --image=nginx -n my-test

For Application Deployment

Deploying your own applications:

When deploying custom applications (not managed by RunOS):

# Safe to use kubectl for your custom deployments
kubectl apply -f my-app.yaml -n my-custom-namespace

# Your resources in custom namespaces won't be touched by RunOS
kubectl create deployment my-app --image=my-image -n my-apps

RunOS only manages resources it deploys. Your custom applications in custom namespaces are fully under your control.

For Team Collaboration

Share knowledge:

• Document cluster access procedures
• Maintain shared documentation of custom changes
• Use code reviews for kubectl operations
• Keep team informed of manual changes

Access control:

• Limit who has kubeconfig access
• Use separate configs for different environments
• Audit kubectl operations periodically
• Rotate credentials regularly

Common Cluster Operations

Viewing Cluster Health

# Check node status
kubectl get nodes

# View all pods
kubectl get pods -A

# Check for failing pods
kubectl get pods -A --field-selector=status.phase!=Running

# View cluster events
kubectl get events -A --sort-by='.lastTimestamp'

# Check resource usage
kubectl top nodes
kubectl top pods -A

Troubleshooting Services

# Find service pods
kubectl get pods -n <OSID>

# View pod logs
kubectl logs <pod-name> -n <OSID>

# Check pod events
kubectl describe pod <pod-name> -n <OSID>

# Execute shell in pod
kubectl exec -it <pod-name> -n <OSID> -- /bin/sh

# Test service connectivity
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- sh

Resource Inspection

# View all resources in namespace
kubectl get all -n <OSID>

# Check ConfigMaps
kubectl get configmap -n <OSID>

# View Secrets (names only)
kubectl get secrets -n <OSID>

# Check Services and Endpoints
kubectl get svc,ep -n <OSID>

# View Persistent Volumes
kubectl get pv,pvc -n <OSID>

Multiple Clusters

If you manage multiple RunOS clusters:

Switching contexts:

# List available contexts
kubectl config get-contexts

# Switch to different cluster
kubectl config use-context <context-name>

# View current context
kubectl config current-context

Managing multiple kubeconfigs:

# Merge multiple kubeconfigs
export KUBECONFIG=~/.kube/config:~/.kube/cluster2:~/.kube/cluster3
kubectl config view --flatten > ~/.kube/merged-config

# Use specific kubeconfig
kubectl --kubeconfig=~/.kube/prod-config get nodes

When to Use Console vs kubectl

Use RunOS Console For:

• Deploying and updating services
• Scaling applications
• Modifying service configuration
• Viewing metrics and logs
• Managing domains and SSL
• User and access management
• Initial cluster setup

Use kubectl For:

• Advanced troubleshooting
• Custom resource inspection
• One-off debugging tasks
• Viewing raw Kubernetes objects
• Testing connectivity
• Emergency operations
• Custom application management

Getting Help

For kubectl issues:

# Get help for any command
kubectl help
kubectl get --help
kubectl logs --help

# Explain resource types
kubectl explain pod
kubectl explain deployment.spec

For cluster issues:

• Check Pod Viewer for pod status
• Review logs in Log Viewer
• Check Grafana for metrics
• Consult troubleshooting docs
• Contact RunOS support with kubectl output

Quick Reference

Essential kubectl commands:

# Cluster info
kubectl cluster-info
kubectl version
kubectl get nodes

# Namespaces (OSIDs)
kubectl get namespaces
kubectl get all -n <OSID>

# Pods
kubectl get pods -A
kubectl describe pod <pod> -n <OSID>
kubectl logs <pod> -n <OSID> -f

# Services
kubectl get svc -n <OSID>
kubectl describe svc <service> -n <OSID>

# Resources
kubectl top nodes
kubectl top pods -A

# Events
kubectl get events -A --sort-by='.lastTimestamp'

Finding resources:

# Find pods by label
kubectl get pods -l app=myapp -A

# Find all resources with name
kubectl get all -A | grep myapp

# List resources by type
kubectl api-resources

Security and Compliance

Audit logging:

• All kubectl commands are logged by Kubernetes
• Review audit logs for compliance
• Track changes made to cluster

Access patterns:

• Use kubectl for read operations liberally
• Be cautious with write operations
• Document significant changes
• Review changes with team

Compliance considerations:

• Maintain records of kubeconfig downloads
• Implement access controls
• Regular access reviews
• Audit kubectl usage

Understanding these cluster management principles helps you work effectively with RunOS while maintaining cluster stability and preventing conflicts between Console and kubectl operations.