tfgrid/docs_tfgrid_get_started
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add Kubernetes basics guide and FAQ for Mycelium Cloud documentation

Browse Source
This commit is contained in:
mik-tf
2025-10-16 20:16:50 -04:00
parent 73eaa1f521
commit a2a70b8213
7 changed files with 641 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/intro.md
View File

@@ -22,7 +22,7 @@ This guide will help you:
### Real Technology, Real Impact
- **7+ years** of development
- **Open-source** technology you can verify: [threefold.info/tech](https://threefold.info/tech)
- **Open-source** technology
- **Working infrastructure** serving real workloads today
- **Decentralized cloud** that empowers individuals and communities
@@ -84,9 +84,8 @@ Choose your path:
Join thousands of ThreeFold farmers and users:
- **👥 Join Telegram**: [t.me/threefold/1](https://t.me/threefold/1)
- **💬 Join the Forum**: [forum.threefold.io](https://forum.threefold.io)
- **📞 Join Community Calls**: [bit.ly/tfcommunitycall](https://bit.ly/tfcommunitycall)
- **[👥 Join Telegram](https://t.me/threefold/1)**
- **[💬 Join the Forum](https://forum.threefold.io)**
---
**With gratitude,**

276
docs/mycelium-cloud/faq.md Normal file
View File

@@ -0,0 +1,276 @@
---
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](/getstarted/mycelium-cloud/getting-started)** for detailed steps.
### What do I need to get started?
- **Mycelium installed** - For network access ([Install guide](/getstarted/mycelium-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](/getstarted/mycelium-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 **[Tutorial](/getstarted/mycelium-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](/getstarted/mycelium-cloud/kubernetes-basics#secrets)** for more details.
## Getting Help
### Where can I get more information and support?
- **Documentation**: [Getting Started](/getstarted/mycelium-cloud/getting-started), [Tutorial](/getstarted/mycelium-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](/getstarted/mycelium-cloud/getting-started)** - Step-by-step cluster deployment
- **[Tutorial](/getstarted/mycelium-cloud/tutorial)** - Practical deployment examples
- **[Kubernetes Basics](/getstarted/mycelium-cloud/kubernetes-basics)** - Essential K8s concepts
- **[Kubernetes Documentation](https://kubernetes.io/docs/)** - Official K8s docs

18
docs/mycelium-cloud/getting-started.md
View File

@@ -27,7 +27,7 @@ Most users can install the Mycelium app from their App Store or download the des
### Sign Up
1. Go to [vdc.grid.tf/sign-up](https://vdc.grid.tf/sign-up)
1. Go to [Mycelium Cloud](https://myceliumcloud.tf/)
2. Fill in your details:
- Email address
- Password
@@ -330,20 +330,12 @@ kubectl top nodes
kubectl get events --sort-by='.lastTimestamp'
```
## What's Next?
Now that you have a cluster running, explore more:
- **[Tutorial](/getstarted/mycelium-cloud/tutorial)** - Deploy real applications
- **[Kubernetes Concepts](https://codescalers.github.io/www_kubecloud/kubernetes-concepts)** - Learn K8s fundamentals
- **[FAQ](https://codescalers.github.io/www_kubecloud/faq)** - Common questions
## Resources
- **Dashboard**: [vdc.grid.tf](https://vdc.grid.tf)
- **Kubernetes Docs**: [kubernetes.io/docs](https://kubernetes.io/docs/)
- **kubectl Cheat Sheet**: [kubernetes.io/docs/reference/kubectl/cheatsheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)
- **Community**: [Telegram](https://t.me/threefold/1)
- **[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)**
---

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

@@ -0,0 +1,342 @@
---
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
2. **Set Resource Limits** - Prevent resource exhaustion
```yaml
resources:
requests:
memory: "64Mi"
cpu: "250m"
limits:
memory: "128Mi"
cpu: "500m"
```
3. **Use Health Checks** - Implement liveness and readiness probes
4. **Use Namespaces** - Organize resources logically
5. **Version Control** - Store manifests in Git
6. **Use Labels** - Tag resources for organization
7. **Secrets Management** - Never hardcode sensitive data
## Next Steps
- **[Tutorial](/getstarted/mycelium-cloud/tutorial)** - Deploy real applications
- **[FAQ](/getstarted/mycelium-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.
:::

25
docs/mycelium-cloud/overview.md
View File

@@ -75,13 +75,13 @@ Mycelium Cloud uses peer-to-peer networking for direct access:
│ Mycelium Network
│ (encrypted P2P)
│
┌───────▼────────────────────────────────┐
│ Kubernetes Cluster │
│ ┌──────────┐ ┌──────────┐ │
│ │ Master │ │ Worker │ │
│ │ Node │ │ Node │ ... │
│ └──────────┘ └──────────┘ │
└────────────────────────────────────────┘
┌───────▼──────────────────────────────┐
│ Kubernetes Cluster │
│ ┌──────────┐ ┌──────────┐ │
│ │ Master │ │ Worker │ │
│ │ Node │ │ Node │ ... │
│ └──────────┘ └──────────┘ │
└──────────────────────────────────────┘
ThreeFold Grid Infrastructure
```
@@ -170,11 +170,12 @@ Check the dashboard for current rates. The decentralized infrastructure typicall
## Resources
- **Dashboard**: [vdc.grid.tf](https://vdc.grid.tf) - Deploy and manage clusters
- **Documentation**: [Mycelium Cloud Docs](https://codescalers.github.io/www_kubecloud/)
- **Kubernetes Docs**: [kubernetes.io](https://kubernetes.io/docs/)
- **Community**: [ThreeFold Telegram](https://t.me/threefold/1)
- **GitHub**: [kubecloud repository](https://github.com/codescalers/kubecloud)
- **[Mycelium Cloud](https://myceliumcloud.tf/)**
- **[Kubernetes Basics](/getstarted/mycelium-cloud/kubernetes-basics)**
- **[FAQ](/getstarted/mycelium-cloud/faq)**
- **[Kubernetes Docs](https://kubernetes.io/docs/)**
- **[Community Chat](https://t.me/threefold/1)**
- **[GitHub Repository](https://github.com/codescalers/kubecloud)**
## Comparison to Traditional Cloud

7
docs/mycelium-cloud/tutorial.md
View File

@@ -564,13 +564,6 @@ Now that you've completed these tutorials:
- 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
## 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/)
- **Mycelium Cloud FAQ**: [codescalers.github.io/www_kubecloud/faq](https://codescalers.github.io/www_kubecloud/faq)
- **Community**: [Telegram](https://t.me/threefold/1)
---
:::tip Keep Learning