diff --git a/docs/intro.md b/docs/intro.md index da12448..ae1ca99 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -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,** diff --git a/docs/mycelium-cloud/faq.md b/docs/mycelium-cloud/faq.md new file mode 100644 index 0000000..8adf34a --- /dev/null +++ b/docs/mycelium-cloud/faq.md @@ -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@ +``` + +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 + +# Check logs +kubectl logs + +# 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 \ No newline at end of file diff --git a/docs/mycelium-cloud/getting-started.md b/docs/mycelium-cloud/getting-started.md index 301a929..9cb1dd3 100644 --- a/docs/mycelium-cloud/getting-started.md +++ b/docs/mycelium-cloud/getting-started.md @@ -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)** --- diff --git a/docs/mycelium-cloud/kubernetes-basics.md b/docs/mycelium-cloud/kubernetes-basics.md new file mode 100644 index 0000000..3dc1037 --- /dev/null +++ b/docs/mycelium-cloud/kubernetes-basics.md @@ -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 +kubectl logs +kubectl logs -f # Follow logs +kubectl exec -it -- /bin/bash + +# Deployments +kubectl get deployments +kubectl scale deployment --replicas=5 +kubectl rollout status deployment/ +kubectl rollout undo deployment/ + +# Services +kubectl get services +kubectl describe service + +# Apply/Delete resources +kubectl apply -f file.yaml +kubectl delete -f file.yaml + +# Port forwarding +kubectl port-forward pod/ 8080:80 +kubectl port-forward service/ 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. +::: diff --git a/docs/mycelium-cloud/overview.md b/docs/mycelium-cloud/overview.md index 7fd273d..08a8aef 100644 --- a/docs/mycelium-cloud/overview.md +++ b/docs/mycelium-cloud/overview.md @@ -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 diff --git a/docs/mycelium-cloud/tutorial.md b/docs/mycelium-cloud/tutorial.md index 37dd7b3..502aa52 100644 --- a/docs/mycelium-cloud/tutorial.md +++ b/docs/mycelium-cloud/tutorial.md @@ -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 diff --git a/sidebars.js b/sidebars.js index c47c391..bf5994a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -59,6 +59,8 @@ const sidebars = { 'mycelium-cloud/overview', 'mycelium-cloud/getting-started', 'mycelium-cloud/tutorial', + 'mycelium-cloud/kubernetes-basics', + 'mycelium-cloud/faq', ], }, ],