ourworld_web/docs_projectmycelium
23
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
mik-tf
2025-11-25 15:27:56 -05:00
commit c769942374
33 changed files with 24049 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

289
docs/cloud/faq.md Normal file
View File

@@ -0,0 +1,289 @@
---
sidebar_position: 5
---
# Frequently Asked Questions
Common questions about deploying and managing Kubernetes clusters on Mycelium Cloud.
## General
### What is Mycelium Cloud?
Mycelium Cloud is a platform for deploying and managing Kubernetes clusters on the decentralized ThreeFold Grid infrastructure. It provides K3s clusters with Mycelium peer-to-peer networking, making it easy to run containerized applications on distributed, cost-effective infrastructure.
### What makes Mycelium Cloud different?
- **Decentralized Infrastructure** – Runs on ThreeFold Grid's distributed network
- **IPv6 Networking** – Built-in Mycelium peer-to-peer networking
- **Cost Effective** – Competitive pricing on decentralized infrastructure
- **No Vendor Lock-in** – Standard Kubernetes (K3s) – works with all K8s tools
- **Global Distribution** – Deploy across worldwide node locations
### Is it suitable for production workloads?
Yes! Mycelium Cloud supports production workloads with:
- High availability cluster configurations (multi-master)
- Persistent storage options
- Monitoring and logging capabilities
- Standard Kubernetes security features
## Getting Started
### How do I create an account?
1. Visit [Mycelium Cloud](https://myceliumcloud.tf)
2. Fill in your registration details
3. Verify your email address
4. Add credits and SSH keys from your dashboard
See the **[Getting Started Guide](/cloud/getting-started)** for detailed steps.
### What do I need to get started?
- **Mycelium installed** – For network access ([Install guide](/network/install))
- **kubectl installed** – For cluster management ([Install kubectl](https://kubernetes.io/docs/tasks/tools/))
- **SSH key pair** – For node access
- **Account credits** – To fund your deployments
### What Kubernetes version is supported?
Mycelium Cloud uses **K3s v1.26+**, which provides:
- Full Kubernetes API compatibility
- Lightweight resource usage
- High availability features
- Dual-stack networking (IPv4/IPv6)
## Cluster Management
### How do I access my cluster?
Two methods:
**1. kubectl (Recommended):**
```bash
# Download kubeconfig from dashboard
export KUBECONFIG=/path/to/mycluster-config.yaml
kubectl get nodes
```
**2. SSH:**
```bash
# Start Mycelium, then SSH to node IPs
ssh root@<mycelium-ip>
```
See **[Getting Started](/cloud/getting-started#step-4-access-your-cluster)** for details.
### Can I scale my cluster after deployment?
Yes! You can:
- Add or remove worker nodes through the dashboard
- Scale applications independently using kubectl
- Modify cluster configuration
```bash
# Scale deployment
kubectl scale deployment myapp --replicas=5
```
### What happens if a node fails?
- **Worker Node Failure** – Kubernetes automatically reschedules pods to healthy nodes
- **Master Node Failure** – In HA setups (3+ masters), other masters take over
- **Self-Healing** – Pods are automatically restarted if they crash
## Networking
### How do I expose applications to the internet?
Options include:
**1. NodePort Services:**
```yaml
type: NodePort
```
**2. Port Forwarding (Development):**
```bash
kubectl port-forward service/myapp 8080:80
```
**3. Ingress Controllers:**
Set up an ingress controller for HTTP/HTTPS routing with custom domains.
### Do I need public IP addresses?
No! Mycelium Cloud uses **Mycelium networking**:
- Each node gets a unique Mycelium IPv6 address
- Access nodes and services via Mycelium network
- All traffic encrypted end-to-end
- No need for public IPs or complex firewall configurations
## Troubleshooting
### My cluster deployment failed. What should I do?
1. **Check Logs** – Review deployment logs in the dashboard
2. **Verify Credits** – Ensure sufficient account balance
3. **Node Availability** – Confirm selected nodes are available
4. **Configuration** – Validate cluster configuration settings
5. **Contact Support** – If issues persist, reach out via Telegram or GitHub
### I can't connect with kubectl. How do I fix this?
```bash
# 1. Verify kubeconfig is set
echo $KUBECONFIG
# 2. Check Mycelium is running
# (Open Mycelium app or run: sudo mycelium --peers ...)
# 3. Test cluster connectivity
kubectl cluster-info
# 4. Verify cluster is running in dashboard
```
Common issues:
- Mycelium not running on your machine
- Wrong kubeconfig file path
- Cluster stopped in dashboard
- Network firewall blocking connections
### My pods are not starting. What's wrong?
```bash
# Check pod status
kubectl get pods
# Describe pod for events
kubectl describe pod <pod-name>
# Check logs
kubectl logs <pod-name>
# Check node resources
kubectl top nodes
```
Common causes:
- **Resource Limits** – Insufficient CPU/memory on nodes
- **Image Issues** – Cannot pull container images
- **Configuration** – Invalid pod specifications
- **Storage** – Persistent volume issues
### How do I check cluster health?
```bash
# Check node status
kubectl get nodes
# Check system pods
kubectl get pods -n kube-system
# View events
kubectl get events --sort-by=.metadata.creationTimestamp
# Check resource usage
kubectl top nodes
kubectl top pods
```
## Storage & Data
### How do I persist data?
Use **PersistentVolumeClaims** (PVCs):
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: my-data
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
```
See **[Deployment Tutorials](/cloud/tutorial#tutorial-3-stateful-application-with-persistent-storage)** for a complete example.
### How do I backup my cluster?
Backup strategies:
- **Application Data** – Use PVC snapshots or backup tools
- **Configurations** – Version control your YAML manifests in Git
- **etcd Snapshots** – Cluster state backups (advanced)
## Security
### How secure is Mycelium Cloud?
Security features:
- **Encrypted Communication** – All traffic encrypted via Mycelium network
- **Network Isolation** – Secure pod-to-pod communication
- **RBAC** – Kubernetes role-based access control
- **SSH Key Authentication** – Secure node access
- **No Public IPs** – Reduced attack surface
### How do I manage secrets?
Use Kubernetes Secrets:
```bash
# Create secret
kubectl create secret generic db-password --from-literal=password=mypassword
# Use in pod
env:
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: db-password
key: password
```
See **[Kubernetes Basics](/cloud/kubernetes-basics#secrets)** for more details.
## Getting Help
### Where can I get more information and support?
- **Documentation** – [Getting Started](/cloud/getting-started), [Deployment Tutorials](/cloud/tutorial)
- **Community** – [ThreeFold Telegram](https://t.me/threefold/1)
### How do I report a bug?
1. Check existing [GitHub Issues](https://github.com/codescalers/kubecloud/issues)
2. Create a new issue with:
- Cluster configuration
- Error messages and logs
- Steps to reproduce
- Expected vs actual behavior
---
## Still Have Questions?
Check out these resources:
- **[Getting Started Guide](/cloud/getting-started)** – Step-by-step cluster deployment
- **[Deployment Tutorials](/cloud/tutorial)** – Practical deployment examples
- **[Kubernetes Basics](/cloud/kubernetes-basics)** – Essential K8s concepts
- **[Kubernetes Documentation](https://kubernetes.io/docs/)** – Official K8s docs

233
docs/cloud/for-developers.md Normal file
View File

@@ -0,0 +1,233 @@
---
sidebar_position: 6
---
# Mycelium Cloud for Developers
*Developer Guide to Decentralized Cloud Computing*
## Overview
Mycelium Cloud provides a comprehensive platform for deploying and managing Kubernetes clusters on the decentralized ThreeFold Grid infrastructure. This guide covers the core features and capabilities available to developers.
## Architecture
### Decentralized Infrastructure
Mycelium Cloud deploys on ThreeFold Grid's distributed network, providing:
- **Direct Node Access** – Each node gets a unique Mycelium IP address
- **Cross-Node Communication** – Services communicate across nodes using Mycelium networking
- **Secure Communication** – All traffic is encrypted through the Mycelium network
- **No Public IPs Required** – Services accessible via Mycelium IPs
### Network Flow
User Machine → Mycelium Network → Cluster Node → Service
### Kubernetes Management
- **K3s Support** – Full K3s cluster deployment and management
- **IPv6 Networking** – Mycelium peer-to-peer networking
- **High Availability** – Multi-master cluster support
---
## Core Features
### Mycelium Networking
Ultra-fast, decentralized networking inspired by nature. Mycelium Networking forms a resilient, adaptive mesh that routes around failures and optimizes for speed and security.
**Features:**
- End-to-end encrypted
- Nature-inspired
- Direct node communication
- Secure peer-to-peer connections
### Zero-Image Technology
Metadata-driven zero-images cut artifacts up to 100x, slashing bandwidth and deployment overhead.
**Benefits:**
- **Deterministic Deployments** – Cryptographic verification ensures every workload deploys exactly as intended—no tampering, no drift
- **Multi-Workload Compatibility with Secure Boot** – Run containers, VMs, and Linux workloads anywhere with stateless secure boot and continuous verification
- **Smart Contract-Based Deployment** – Cryptographically signed contracts orchestrate every workload with transparent, tamper-proof execution
### Quantum-Safe Storage (QSS)
Quantum-resistant encryption secures data beyond the app layer so ownership and control stay yours.
**Features:**
- **Self-Healing Storage System** – Autonomous recovery heals failures or corruption instantly, preserving integrity without human intervention
- **Multi-Protocol Data Access** – Serve the same data via IPFS, S3, WebDAV, HTTP, and native file systems for seamless integration
- **Geo-Aware Data Placement & Replication** – Define residency, redundancy, and distribution per workload while zone-to-zone replication hardens resilience
### Multi-Master Clusters
High-availability Kubernetes clusters with multiple control plane nodes. Automatic failover, leader election, and zero-downtime upgrades built-in.
**Capabilities:**
- **HA Control Plane**
- **Automatic Failover**
- **Zero-downtime Upgrades**
### Effortless Load Balancing & Scaling
Mycelium Cloud automatically balances traffic and scales your services up or down based on demand. Enjoy high availability and optimal performance with zero manual intervention.
**Features:**
- **Auto-scaling**
- **Built-in load balancing**
- **High availability**
### Simple Web Gateway Access
Expose any service to the public web with a simple Kubernetes resource. No complex Ingress controllers. Domain and prefix-based routing is built-in.
**Benefits:**
- **Simple configuration**
- **Built-in routing**
- **No ingress controllers**
---
## Getting Started
### 1. Account Setup
- **Sign Up** – Create your account from the signup page
- **Verify Email** – Check your email and verify your account
- **Add Funds** – Navigate to your dashboard and add credits to your account
- **Add SSH Key** – Navigate to the *Add SSH* card and upload your public SSH key
### 2. Deploy Your First Cluster
- **Access Deploy** – Click **Deploy Cluster** from your dashboard
- **Configure VMs** – Define your virtual machines:
- Choose CPU, memory, and storage requirements
- Select the number of master and worker nodes
- **Select Nodes** – Choose ThreeFold Grid nodes for deployment
- **Review & Deploy** – Confirm your configuration and deploy
### 3. Access Your Cluster
#### Download kubeconfig
- Go to **Dashboard → Clusters** and click the download icon (⬇️)
- Set kubeconfig: `export KUBECONFIG=/path/to/config`
- Test: `kubectl get nodes`
#### SSH Access
- **Find Mycelium IPs** – Check cluster details page for node IPs
- **Download Mycelium Binary (Linux example):**
```bash
wget https://github.com/threefoldtech/mycelium/releases/latest/download/mycelium-private-x86_64-unknown-linux-musl.tar.gz
tar -xzf mycelium-private-x86_64-unknown-linux-musl.tar.gz
sudo chmod +x mycelium-private
sudo mv mycelium-private /usr/local/bin/mycelium
```
- **Start Mycelium:**
```bash
sudo mycelium --peers \
tcp://188.40.132.242:9651 \
tcp://136.243.47.186:9651 \
tcp://185.69.166.7:9651 \
tcp://185.69.166.8:9651 \
tcp://65.21.231.58:9651 \
tcp://65.109.18.113:9651 \
tcp://209.159.146.190:9651 \
tcp://5.78.122.16:9651 \
tcp://5.223.43.251:9651 \
tcp://142.93.217.194:9651
```
- **SSH to nodes:** `ssh root@<mycelium-ip>`
---
## Use Cases
### AI/ML Training
Run GPU-accelerated workloads for deep learning and data science on demand.
- **GPU Acceleration**
- **Scalable Compute**
- **Cost Optimization**
### Enterprise Kubernetes
Deploy production-grade clusters with full control and no vendor lock-in.
- **High Availability**
- **Security**
- **Compliance**
### Edge & IoT
Leverage global nodes for low-latency edge computing and IoT applications.
- **Low Latency**
- **Global Distribution**
- **Real-time Processing**
### DigitalMe Example
Example of what can be done with Mycelium Cloud. With a very simple execution, the following can be deployed on a K8s cluster and served on Mycelium IPs:
- **Cryptpad** – Encrypted document collaboration
- **Elements** – Matrix chat (the Rust one)
- **Stallwart** – Mail/calendar/contacts
- **Gitea** – Git hosting and code collaboration
- **Nextcloud** – File storage and synchronization
- **LiveKit or Jitsi** – Video conferencing integrated with Elements/Nextcloud
- **SSO** – Single Sign-On (future integration)
This demonstrates the platform's capability to host complex, integrated applications with minimal configuration.
---
## Key Differentiators
### Sovereign by Design
Control jurisdiction, residency, and governance for every workload with transparent, verifiable operations.
### Secure by Default
Cryptographic verification, secure boot, and zero-image delivery protect the entire lifecycle automatically.
### Ready to Scale
Autonomous orchestration keeps the platform elastic, cost-efficient, and always available across the globe.
---
## Security Architecture
### Provable Sovereignty
Assign workloads to trusted zones, verify state with cryptographic proofs, and maintain full lineage for every byte.
### Autonomous Zero-Trust
Identity, policy, and attestation are enforced continuously—no manual keys, no hidden backdoors, no shared control.
### Planetary-Scale Resilience
Mesh-connected infrastructure routes around failure, keeping applications responsive even when regions go dark.
---
*Mycelium Cloud – Comprehensive platform for decentralized Kubernetes deployment.*

347
docs/cloud/getting-started.md Normal file
View File

@@ -0,0 +1,347 @@
---
sidebar_position: 2
---
# Getting Started with Mycelium Cloud
Deploy your first Kubernetes cluster on the ThreeFold Grid in just a few steps.
## Prerequisites
Before you begin, make sure you have:
- ✅ **Mycelium installed** – Easy app for iOS, Android, macOS, Windows ([Install guide](/network/install))
- ✅ **SSH key pair** – For node access
- ✅ **kubectl installed** – For managing your cluster ([Install kubectl](https://kubernetes.io/docs/tasks/tools/))
- ✅ **Credits** – To fund your deployment
:::info Installing Mycelium is Easy!
Most users can install the Mycelium app from their App Store or download the desktop app – no command-line needed!
:::
## Step 1: Create Your Account
### Sign Up
1. Go to [Mycelium Cloud](https://myceliumcloud.tf/)
2. Fill in your details:
- Email address
- Password
- Confirm password
3. Click **Sign Up**
### Verify Email
1. Check your email inbox
2. Click the verification link
3. Your account is now active
## Step 2: Set Up Your Account
### Add Credits
1. Log in to your dashboard
2. Navigate to **Credits** or **Billing** section
3. Add funds to your account
- Choose payment method
- Enter amount
- Complete payment
Your credits will be used to pay for cluster resources (CPU, RAM, storage, time).
### Add SSH Key
1. Navigate to **SSH Keys** section (or **Add SSH** card)
2. Click **Add SSH Key**
3. Paste your **public key** (usually `~/.ssh/id_rsa.pub`)
4. Give it a name
5. Save
:::tip Need an SSH Key?
If you don't have one:
```bash
# Generate a new SSH key pair
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
# View your public key
cat ~/.ssh/id_rsa.pub
```
Copy the output and paste it into the dashboard.
:::
## Step 3: Deploy Your First Cluster
### Access Deployment Page
1. From your dashboard, click **Deploy Cluster** or **New Cluster**
2. You'll see the cluster configuration wizard
### Configure Your Cluster
#### Basic Settings
- **Cluster Name**: Give your cluster a unique name
- **Description**: Optional description of the cluster purpose
#### Master Nodes
Configure your control plane nodes:
- **Count**: Number of master nodes
- 1 for development/testing
- 3 for production (high availability)
- **CPU**: Number of cores per master (2–4 recommended)
- **RAM**: Memory per master (4–8GB recommended)
- **Storage**: Disk space per master (20–50GB)
#### Worker Nodes
Configure your workload nodes:
- **Count**: Number of worker nodes (1–10+)
- **CPU**: Cores per worker (based on workload)
- **RAM**: Memory per worker (based on workload)
- **Storage**: Disk space per worker (based on workload)
**Example Configuration (Starter):**
```text
Masters: 1 node (2 CPU, 4GB RAM, 25GB storage)
Workers: 2 nodes (2 CPU, 4GB RAM, 50GB storage each)
```
### Select Nodes
1. The system will show available ThreeFold Grid nodes
2. Select nodes for your deployment
- Choose based on location, specs, and availability
- System may auto-select optimal nodes
3. Review your selections
### Review & Deploy
1. Review your configuration:
- Node counts and specs
- Selected grid nodes
- Estimated cost
2. Confirm you have sufficient credits
3. Click **Deploy**
The deployment process will begin. This typically takes 5–15 minutes.
## Step 4: Access Your Cluster
Once deployed, you can access your cluster in two ways: kubectl and SSH.
### Method 1: kubectl Access
#### Download kubeconfig
1. Go to **Dashboard** → **Clusters**
2. Find your cluster
3. Click the download icon (⬇️) or **Get Config**
4. Save the file (e.g., `mycluster-config.yaml`)
#### Configure kubectl
```bash
# Set kubeconfig for this session
export KUBECONFIG=/path/to/mycluster-config.yaml
# Or copy to default location
mkdir -p ~/.kube
cp mycluster-config.yaml ~/.kube/config
# Test connection
kubectl get nodes
```
You should see your cluster nodes listed:
```text
NAME STATUS ROLES AGE VERSION
master-1 Ready control-plane,master 10m v1.26.0+k3s1
worker-1 Ready <none> 9m v1.26.0+k3s1
worker-2 Ready <none> 9m v1.26.0+k3s1
```
### Method 2: SSH Access
#### Start Mycelium
If not already running, start Mycelium on your local machine:
**Using the App (Easy):**
1. Open the Mycelium app
2. Click **Start**
3. That's it!
**Using Command-Line (Linux):**
```bash
sudo mycelium --peers \
tcp://188.40.132.242:9651 \
tcp://185.69.166.8:9651
```
#### Get Node IPs
From your dashboard:
1. Go to your cluster details
2. Find the **Mycelium IPs** for each node
3. Note them down (e.g., `400:1234:5678:abcd::1`)
#### SSH to Nodes
```bash
# SSH to master node
ssh root@400:1234:5678:abcd::1
# SSH to worker node
ssh root@400:1234:5678:abcd::2
```
You're now connected to your cluster node!
## Step 5: Deploy Your First Application
Let's deploy a simple web application to test your cluster.
### Create a Deployment
```bash
# Create an nginx deployment
kubectl create deployment hello-web --image=nginx:latest
# Check deployment status
kubectl get deployments
kubectl get pods
```
### Expose the Service
```bash
# Expose as a service
kubectl expose deployment hello-web --port=80 --type=ClusterIP
# Check service
kubectl get services
```
### Access the Service
```bash
# Port forward to your local machine
kubectl port-forward service/hello-web 8080:80
```
Open `http://localhost:8080` in your browser. You should see the nginx welcome page!
## Step 6: Monitor Your Cluster
### Using Dashboard
Your Mycelium Cloud dashboard shows:
- Cluster status (running, stopped, etc.)
- Resource usage
- Cost tracking
- Node health
### Using kubectl
```bash
# View cluster info
kubectl cluster-info
# Check node status
kubectl get nodes
# View all resources
kubectl get all --all-namespaces
# Check cluster events
kubectl get events
```
## Managing Your Cluster
### Scale Workers
Add more worker nodes:
1. Go to cluster details in dashboard
2. Click **Scale** or **Add Nodes**
3. Configure new worker nodes
4. Deploy
### Delete Resources
```bash
# Delete the test deployment
kubectl delete deployment hello-web
kubectl delete service hello-web
```
### Stop/Start Cluster
From the dashboard:
- **Stop**: Pause cluster (saves costs)
- **Start**: Resume cluster
- **Delete**: Permanently remove (frees all resources)
## Troubleshooting
### Can't Connect with kubectl
1. **Check kubeconfig** – Ensure `KUBECONFIG` is set correctly
2. **Verify Mycelium** – Make sure Mycelium is running
3. **Check cluster status** – Ensure cluster is running in dashboard
4. **Test network** – Try pinging cluster nodes via Mycelium IPs
```bash
# Test Mycelium connectivity
ping6 <cluster-node-mycelium-ip>
```
### Can't SSH to Nodes
1. **Mycelium running** – Ensure Mycelium daemon is active
2. **SSH key added** – Verify your public key is in dashboard
3. **Correct IP** – Double-check Mycelium IP from dashboard
4. **Network access** – Test with `ping6` first
### Pods Not Starting
```bash
# Check pod status
kubectl describe pod <pod-name>
# Check node resources
kubectl top nodes
# Check events
kubectl get events --sort-by='.lastTimestamp'
```
## Resources
- **[Mycelium Cloud](https://myceliumcloud.tf/)**
- **[Kubernetes Docs](https://kubernetes.io/docs/)**
- **[kubectl Cheat Sheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)**
- **[Community Chat](https://t.me/threefold/1)**
---
:::tip Cluster Running Successfully?
Great! Now try the **[Deployment Tutorials](/cloud/tutorial)** to deploy more complex applications.
:::

344
docs/cloud/kubernetes-basics.md Normal file
View File

@@ -0,0 +1,344 @@
---
sidebar_position: 4
---
# Kubernetes Basics
Essential Kubernetes concepts for deploying applications on Mycelium Cloud.
## What is Kubernetes?
Kubernetes (K8s) is a container orchestration platform that automates deploying, scaling, and managing containerized applications. Mycelium Cloud uses **K3s**, a lightweight Kubernetes distribution perfect for edge and cloud environments.
### Why Kubernetes?
- **Automated Deployment** – Deploy containers across multiple nodes
- **Self-Healing** – Automatically restart failed containers
- **Horizontal Scaling** – Scale applications up or down based on demand
- **Service Discovery** – Automatic DNS and load balancing
- **Rolling Updates** – Update applications with zero downtime
## Core Concepts
### Pods
A **Pod** is the smallest deployable unit in Kubernetes. It represents one or more containers that share:
- Network namespace (same IP address)
- Storage volumes
- Configuration
```yaml
apiVersion: v1
kind: Pod
metadata:
name: nginx-pod
spec:
containers:
- name: nginx
image: nginx:1.21
ports:
- containerPort: 80
```
```bash
# View pods
kubectl get pods
# View pod details
kubectl describe pod nginx-pod
# View pod logs
kubectl logs nginx-pod
```
### Deployments
A **Deployment** manages a replicated set of Pods and provides declarative updates.
Features:
- **Replica Management** – Maintain desired number of pods
- **Rolling Updates** – Update pods with zero downtime
- **Rollback** – Revert to previous versions
- **Self-Healing** – Replace failed pods automatically
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.21
ports:
- containerPort: 80
```
```bash
# Create deployment
kubectl apply -f deployment.yaml
# View deployments
kubectl get deployments
# Scale deployment
kubectl scale deployment nginx-deployment --replicas=5
# Update image
kubectl set image deployment/nginx-deployment nginx=nginx:1.22
```
### Services
**Services** provide stable network endpoints for accessing pods.
#### ClusterIP (Default)
Internal-only service, accessible within the cluster:
```yaml
apiVersion: v1
kind: Service
metadata:
name: my-service
spec:
type: ClusterIP
selector:
app: nginx
ports:
- port: 80
targetPort: 80
```
#### NodePort
Exposes service on each node's IP at a static port:
```yaml
apiVersion: v1
kind: Service
metadata:
name: my-service
spec:
type: NodePort
selector:
app: nginx
ports:
- port: 80
targetPort: 80
nodePort: 30080 # 30000-32767
```
```bash
# View services
kubectl get services
# Describe service
kubectl describe service my-service
```
### Namespaces
**Namespaces** provide logical isolation for resources within a cluster.
```bash
# List namespaces
kubectl get namespaces
# Create namespace
kubectl create namespace my-app
# Use namespace
kubectl get pods -n my-app
```
## Storage
### Persistent Volumes
**PersistentVolumeClaim (PVC)** – Request for storage:
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: pvc-data
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
```
Use in pod:
```yaml
spec:
containers:
- name: app
image: myapp:latest
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: data
persistentVolumeClaim:
claimName: pvc-data
```
## Configuration
### ConfigMaps
Store non-sensitive configuration data:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
database_url: "postgres://db:5432/mydb"
log_level: "info"
```
```bash
# Create from literal
kubectl create configmap app-config --from-literal=key=value
# View configmaps
kubectl get configmaps
```
### Secrets
Store sensitive data (passwords, tokens, keys):
```yaml
apiVersion: v1
kind: Secret
metadata:
name: app-secret
type: Opaque
data:
password: cGFzc3dvcmQxMjM= # base64 encoded
```
```bash
# Create secret
kubectl create secret generic app-secret --from-literal=password=password123
# View secrets
kubectl get secrets
```
## Essential kubectl Commands
```bash
# Cluster info
kubectl cluster-info
kubectl get nodes
# Pods
kubectl get pods
kubectl get pods -o wide
kubectl describe pod <pod-name>
kubectl logs <pod-name>
kubectl logs -f <pod-name> # Follow logs
kubectl exec -it <pod-name> -- /bin/bash
# Deployments
kubectl get deployments
kubectl scale deployment <name> --replicas=5
kubectl rollout status deployment/<name>
kubectl rollout undo deployment/<name>
# Services
kubectl get services
kubectl describe service <service-name>
# Apply/Delete resources
kubectl apply -f file.yaml
kubectl delete -f file.yaml
# Port forwarding
kubectl port-forward pod/<pod-name> 8080:80
kubectl port-forward service/<service-name> 8080:80
# View all resources
kubectl get all --all-namespaces
# Check events
kubectl get events --sort-by=.metadata.creationTimestamp
```
## Labels and Selectors
**Labels** are key-value pairs attached to objects:
```yaml
metadata:
labels:
app: nginx
environment: production
tier: frontend
```
**Selectors** query objects by labels:
```bash
# Get pods with label
kubectl get pods -l app=nginx
# Get pods with multiple labels
kubectl get pods -l app=nginx,environment=production
```
## Best Practices
1. **Use Deployments** – Not bare pods, for self-healing and scaling
```yaml
resources:
requests:
memory: "64Mi"
cpu: "250m"
limits:
memory: "128Mi"
cpu: "500m"
```
2. **Use Health Checks** – Implement liveness and readiness probes
3. **Use Namespaces** – Organize resources logically
4. **Version Control** – Store manifests in Git
5. **Use Labels** – Tag resources for organization
6. **Secrets Management** – Never hardcode sensitive data
## Next Steps
- **[Deployment Tutorials](/cloud/tutorial)** – Deploy real applications
- **[FAQ](/cloud/faq)** – Common questions and answers
## Additional Resources
- **Kubernetes Documentation**: [kubernetes.io/docs](https://kubernetes.io/docs/)
- **kubectl Cheat Sheet**: [kubernetes.io/docs/reference/kubectl/cheatsheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)
- **K3s Documentation**: [docs.k3s.io](https://docs.k3s.io/)
---
:::tip Want to Learn More?
This covers the basics to get you started. For advanced topics like StatefulSets, DaemonSets, Ingress, and RBAC, check out the comprehensive Kubernetes documentation linked above.
:::

194
docs/cloud/overview.md Normal file
View File

@@ -0,0 +1,194 @@
---
sidebar_position: 1
slug: /cloud
---
# What is Mycelium Cloud?
Mycelium Cloud lets you deploy and manage **Kubernetes clusters** on the decentralized ThreeFold Grid infrastructure.
Run your containerized workloads on distributed, cost-effective infrastructure with built-in security and global availability.
## How It Works
Mycelium Cloud provides a complete platform for cloud-native applications:
1. **Sign up** for an account.
2. **Add credits** to fund your deployments.
3. **Deploy clusters** with custom configurations.
4. **Manage workloads** using standard Kubernetes tools.
All of this runs on the ThreeFold Grid's decentralized infrastructure.
## Why Use Mycelium Cloud?
### 🌍 Decentralized Infrastructure
- Deploy on ThreeFold Grid's distributed network.
- No dependency on centralized cloud providers.
- Global node distribution.
- True infrastructure sovereignty.
### 📦 Full Kubernetes Management
- **K3s clusters** – Lightweight, production-ready Kubernetes.
- **Multi-master support** – High availability configurations.
- **Standard tooling** – Use `kubectl`, Helm, and your favorite tools.
- **Complete control** – Full cluster access.
### 🔐 Secure by Default
- **Mycelium networking** – Encrypted peer-to-peer connections.
- **No public IPs needed** – Access via the Mycelium overlay network.
- **End-to-end encryption** – All traffic secured.
- **Private by design** – Your infrastructure, your control.
### 💰 Cost Effective
- **Competitive pricing** on decentralized infrastructure.
- **Pay for what you use** – Flexible resource allocation.
- **No vendor lock-in** – Standard Kubernetes portability.
- **Global availability** – Deploy where you need.
## Key Features
| Feature | Description |
|---------|-------------|
| **K3s Kubernetes** | Lightweight, certified Kubernetes distribution |
| **Mycelium Networking** | IPv6 overlay with encrypted P2P connections |
| **High Availability** | Multi-master clusters for production workloads |
| **Global Nodes** | Deploy across worldwide ThreeFold Grid locations |
| **Standard APIs** | Use `kubectl`, Helm, and all Kubernetes tools |
| **Web Dashboard** | Manage clusters through an intuitive UI |
| **SSH Access** | Direct node access for debugging and management |
| **Flexible Sizing** | Custom CPU, RAM, and storage configurations |
## Architecture
Mycelium Cloud uses peer-to-peer networking for direct access:
```
┌────────────────┐
│ Your Machine │
│ (kubectl) │
└───────┬────────┘
│
│ Mycelium Network
│ (encrypted P2P)
│
┌───────▼──────────────────────────────┐
│ Kubernetes Cluster │
│ ┌──────────┐ ┌──────────┐ │
│ │ Master │ │ Worker │ ... │
│ │ Node │ │ Node │ │
│ └──────────┘ └──────────┘ │
└──────────────────────────────────────┘
ThreeFold Grid Infrastructure
```
**Network flow:**
- Your machine connects via the Mycelium network.
- Each cluster node has a unique Mycelium IPv6 address.
- All communication is encrypted end-to-end.
- Direct node access – no gateways or proxies.
## Common Use Cases
### Development & Testing
- Spin up test clusters quickly.
- Experiment with Kubernetes features.
- CI/CD pipeline testing.
- Multi-environment development.
### Production Workloads
- Web applications and APIs.
- Microservices architectures.
- Databases and stateful services.
- Background processing jobs.
### Decentralized Applications
- P2P services.
- Distributed computing.
- Edge computing deployments.
- Privacy-focused applications.
### Learning Kubernetes
- Hands-on practice.
- Tutorial environments.
- Training clusters.
- Safe experimentation.
## Technology Stack
- **Kubernetes:** K3s v1.26+ (production-ready, lightweight).
- **Networking:** Mycelium CNI with IPv6 support.
- **Infrastructure:** ThreeFold Grid decentralized nodes.
- **Management:** Web dashboard + API + `kubectl`.
## What You Get
When you deploy a cluster:
- ✅ **Fully configured K3s cluster** – Ready to use.
- ✅ **Mycelium networking** – Secure connectivity.
- ✅ **kubeconfig file** – Standard `kubectl` access.
- ✅ **SSH access** – Direct node management.
- ✅ **Dashboard monitoring** – Cluster status and metrics.
- ✅ **Flexible scaling** – Add/remove nodes as needed.
## Getting Started
Ready to deploy your first cluster? Start here:
1. **[Getting Started](/cloud/getting-started)** – Create an account and deploy.
2. **[Deployment Tutorials](/cloud/tutorial)** – Deploy your first applications.
:::info Prerequisites
You should have:
- **Mycelium installed** – For network access. See **[Install Mycelium Network](/network/install)**.
- **`kubectl` installed** – For cluster management.
- **SSH key** – For node access.
- **Credits** – To fund your deployments.
:::
## Pricing
Pricing is based on resource usage:
- CPU cores.
- RAM allocation.
- Storage capacity.
- Deployment duration.
Check the dashboard for current rates. The decentralized infrastructure typically offers competitive pricing compared to traditional cloud providers.
## Resources
- **Mycelium Cloud** – [myceliumcloud.tf](https://myceliumcloud.tf)
- **Kubernetes Basics** – [/cloud/kubernetes-basics](/cloud/kubernetes-basics)
- **FAQ** – [/cloud/faq](/cloud/faq)
- **Kubernetes Docs** – [kubernetes.io/docs](https://kubernetes.io/docs/)
- **Community Chat** – [t.me/threefold/1](https://t.me/threefold/1)
- **GitHub Repository** – [github.com/codescalers/kubecloud](https://github.com/codescalers/kubecloud)
## Comparison to Traditional Cloud
| Aspect | Mycelium Cloud | Traditional Cloud |
|------------------|----------------|-----------------------|
| Infrastructure | Decentralized | Centralized |
| Control | Full sovereignty | Vendor-controlled |
| Networking | P2P encrypted | Public IPs, gateways |
| Pricing | Competitive | Often expensive |
| Lock-in | None (standard K8s) | Vendor-specific |
| Privacy | High | Varies by provider |
| Setup | Quick & simple | Can be complex |
:::tip Next Step
Ready to deploy? Start with the **[Getting Started Guide](/cloud/getting-started)** to create your first cluster.
:::

571
docs/cloud/tutorial.md Normal file
View File

@@ -0,0 +1,571 @@
---
sidebar_position: 3
---
# Deployment Tutorials
Learn by example with these practical deployment tutorials for Mycelium Cloud.
## Prerequisites
Before starting these tutorials, ensure you have:
- ✅ Deployed cluster with kubectl access
- ✅ Mycelium running for network access
- ✅ kubectl configured with your cluster
```bash
# Verify your setup
kubectl get nodes
# Should show your cluster nodes
```
## Tutorial 1: Hello World with Nginx
Deploy a simple web server to verify your cluster is working.
### Step 1: Create the Deployment
Save as `hello-world-deploy.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: hello-world
spec:
replicas: 1
selector:
matchLabels:
app: hello-world
template:
metadata:
labels:
app: hello-world
spec:
containers:
- name: nginx
image: nginx:1.21
ports:
- containerPort: 80
```
Apply it:
```bash
kubectl apply -f hello-world-deploy.yaml
```
### Step 2: Expose the Service
Save as `hello-world-svc.yaml`:
```yaml
apiVersion: v1
kind: Service
metadata:
name: hello-world-service
spec:
selector:
app: hello-world
ports:
- port: 80
targetPort: 80
type: ClusterIP
```
Apply it:
```bash
kubectl apply -f hello-world-svc.yaml
```
### Step 3: Access Your Application
```bash
# Port forward to local machine
kubectl port-forward service/hello-world-service 8080:80
```
Open `http://localhost:8080` – you should see the Nginx welcome page!
### Cleanup
```bash
kubectl delete -f hello-world-deploy.yaml
kubectl delete -f hello-world-svc.yaml
```
## Tutorial 2: Python Servers with Load Balancing
Deploy multiple Python HTTP servers to demonstrate load balancing.
### Step 1: Create the Deployments
Save as `python-servers.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: python-server-1
spec:
replicas: 2
selector:
matchLabels:
app: python-server
server-id: "1"
template:
metadata:
labels:
app: python-server
server-id: "1"
spec:
containers:
- name: python-server
image: python:3.9-slim
command: ["python", "-c"]
args:
- |
import http.server, socketserver, json
class Handler(http.server.SimpleHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-type', 'application/json')
self.end_headers()
response = {"server": "Python Server 1", "pod": "$(hostname)"}
self.wfile.write(json.dumps(response).encode())
with socketserver.TCPServer(("", 8000), Handler) as httpd:
httpd.serve_forever()
ports:
- containerPort: 8000
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: python-server-2
spec:
replicas: 2
selector:
matchLabels:
app: python-server
server-id: "2"
template:
metadata:
labels:
app: python-server
server-id: "2"
spec:
containers:
- name: python-server
image: python:3.9-slim
command: ["python", "-c"]
args:
- |
import http.server, socketserver, json
class Handler(http.server.SimpleHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-type', 'application/json')
self.end_headers()
response = {"server": "Python Server 2", "pod": "$(hostname)"}
self.wfile.write(json.dumps(response).encode())
with socketserver.TCPServer(("", 8000), Handler) as httpd:
httpd.serve_forever()
ports:
- containerPort: 8000
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: python-server-3
spec:
replicas: 2
selector:
matchLabels:
app: python-server
server-id: "3"
template:
metadata:
labels:
app: python-server
server-id: "3"
spec:
containers:
- name: python-server
image: python:3.9-slim
command: ["python", "-c"]
args:
- |
import http.server, socketserver, json
class Handler(http.server.SimpleHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-type', 'application/json')
self.end_headers()
response = {"server": "Python Server 3", "pod": "$(hostname)"}
self.wfile.write(json.dumps(response).encode())
with socketserver.TCPServer(("", 8000), Handler) as httpd:
httpd.serve_forever()
ports:
- containerPort: 8000
```
### Step 2: Create Load Balancing Service
Save as `python-lb-service.yaml`:
```yaml
apiVersion: v1
kind: Service
metadata:
name: python-lb
spec:
selector:
app: python-server
ports:
- port: 80
targetPort: 8000
type: ClusterIP
```
### Step 3: Deploy Everything
```bash
kubectl apply -f python-servers.yaml
kubectl apply -f python-lb-service.yaml
# Wait for pods to be ready
kubectl get pods -l app=python-server
```
### Step 4: Test Load Balancing
```bash
# Port forward the service
kubectl port-forward service/python-lb 8080:80
# In another terminal, test the load balancing
for i in {1..10}; do
curl http://localhost:8080
done
```
You'll see responses from different servers and pods, showing the load balancing in action!
### Cleanup
```bash
kubectl delete -f python-servers.yaml
kubectl delete -f python-lb-service.yaml
```
## Tutorial 3: Stateful Application with Persistent Storage
Deploy a simple application that persists data.
### Step 1: Create Persistent Volume Claim
Save as `storage.yaml`:
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: data-pvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
```
### Step 2: Create Stateful Deployment
Save as `stateful-app.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: data-app
spec:
replicas: 1
selector:
matchLabels:
app: data-app
template:
metadata:
labels:
app: data-app
spec:
containers:
- name: app
image: busybox:latest
command: ["sh", "-c"]
args:
- |
echo "Starting data application..."
while true; do
date >> /data/log.txt
echo "Written at $(date)" >> /data/log.txt
sleep 10
done
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: data
persistentVolumeClaim:
claimName: data-pvc
```
### Step 3: Deploy and Verify
```bash
kubectl apply -f storage.yaml
kubectl apply -f stateful-app.yaml
# Wait for pod to be ready
kubectl get pods -l app=data-app
# Check the logs being written
kubectl exec -it $(kubectl get pod -l app=data-app -o name) -- cat /data/log.txt
```
### Step 4: Test Persistence
```bash
# Delete the pod
kubectl delete pod -l app=data-app
# Wait for new pod to start
kubectl get pods -l app=data-app
# Check data persisted
kubectl exec -it $(kubectl get pod -l app=data-app -o name) -- cat /data/log.txt
```
The data from before the pod deletion should still be there!
### Cleanup
```bash
kubectl delete -f stateful-app.yaml
kubectl delete -f storage.yaml
```
## Tutorial 4: Multi-Tier Application
Deploy a simple web app with a database backend.
### Step 1: Deploy Redis Database
Save as `redis.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: redis
spec:
replicas: 1
selector:
matchLabels:
app: redis
template:
metadata:
labels:
app: redis
spec:
containers:
- name: redis
image: redis:7-alpine
ports:
- containerPort: 6379
---
apiVersion: v1
kind: Service
metadata:
name: redis
spec:
selector:
app: redis
ports:
- port: 6379
targetPort: 6379
type: ClusterIP
```
### Step 2: Deploy Frontend Application
Save as `frontend.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: frontend
spec:
replicas: 3
selector:
matchLabels:
app: frontend
template:
metadata:
labels:
app: frontend
spec:
containers:
- name: frontend
image: nginx:alpine
ports:
- containerPort: 80
env:
- name: REDIS_HOST
value: "redis"
- name: REDIS_PORT
value: "6379"
---
apiVersion: v1
kind: Service
metadata:
name: frontend
spec:
selector:
app: frontend
ports:
- port: 80
targetPort: 80
type: ClusterIP
```
### Step 3: Deploy and Access
```bash
kubectl apply -f redis.yaml
kubectl apply -f frontend.yaml
# Wait for all pods
kubectl get pods
# Port forward to access frontend
kubectl port-forward service/frontend 8080:80
```
Open `http://localhost:8080` to access your multi-tier application.
### Cleanup
```bash
kubectl delete -f frontend.yaml
kubectl delete -f redis.yaml
```
## Best Practices
### Resource Limits
Always set resource limits:
```yaml
resources:
requests:
memory: "64Mi"
cpu: "250m"
limits:
memory: "128Mi"
cpu: "500m"
```
### Health Checks
Add liveness and readiness probes:
```yaml
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /ready
port: 8080
initialDelaySeconds: 5
periodSeconds: 5
```
### Labels and Annotations
Use descriptive labels:
```yaml
metadata:
labels:
app: myapp
version: v1.0
environment: production
```
## Troubleshooting
### Pods Not Starting
```bash
# Check pod status
kubectl describe pod <pod-name>
# Check logs
kubectl logs <pod-name>
# Check events
kubectl get events --sort-by='.lastTimestamp'
```
### Service Not Accessible
```bash
# Check service
kubectl describe service <service-name>
# Check endpoints
kubectl get endpoints <service-name>
# Test from within cluster
kubectl run -it --rm debug --image=alpine --restart=Never -- sh
# Then: wget -O- http://service-name
```
### Resource Issues
```bash
# Check node resources
kubectl top nodes
# Check pod resources
kubectl top pods
# Check resource requests/limits
kubectl describe nodes
```
## Next Steps
Now that you've completed these tutorials:
- Deploy your own applications
- Explore [Helm](https://helm.sh/) for package management
- Learn about [Ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) for advanced routing
- Study [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) for databases
- Explore [ConfigMaps and Secrets](https://kubernetes.io/docs/concepts/configuration/) for configuration management
---
:::tip Keep Learning
These tutorials cover the basics. The real power of Kubernetes comes from combining these concepts to build complex, scalable applications on the ThreeFold Grid!
:::