Skip to content

quick-start.md

Latest commit

 

History

History
277 lines (199 loc) · 5.88 KB

quick-start.md

File metadata and controls

277 lines (199 loc) · 5.88 KB
Raw

Quick Start Guide

Get your first Stellar validator node running on Kubernetes in minutes.

Overview

This guide will help you deploy a basic Stellar testnet validator node using Stellar-K8s. You'll learn how to:

  1. Create a StellarValidator custom resource
  2. Verify the deployment
  3. Check node status and logs
  4. Connect to the Stellar testnet

!!! info "Prerequisites" Before starting, ensure you've completed the Prerequisites and Installation guides.

Step 1: Create Namespace

Create a dedicated namespace for your Stellar nodes:

kubectl create namespace stellar-testnet

Step 2: Deploy a Validator Node

Create a validator configuration file:

apiVersion: stellar.k8s.io/v1alpha1
kind: StellarValidator
metadata:
  name: my-testnet-validator
  namespace: stellar-testnet
spec:
  network: testnet
  replicas: 1
  
  # Node configuration
  config:
    nodeIsValidator: true
    publicNetwork: true
    catchupRecent: 1024
    
  # Storage configuration
  storage:
    size: 500Gi
    storageClassName: standard
    
  # Resource requests and limits
  resources:
    requests:
      cpu: "4"
      memory: "8Gi"
    limits:
      cpu: "8"
      memory: "16Gi"
      
  # Monitoring
  monitoring:
    enabled: true
    serviceMonitor: true

Apply the configuration:

kubectl apply -f testnet-validator.yaml

Step 3: Verify Deployment

Check Validator Resource

kubectl get stellarvalidators -n stellar-testnet

Expected output:

NAME                    NETWORK   REPLICAS   READY   AGE
my-testnet-validator    testnet   1          1/1     2m30s

Check Pod Status

kubectl get pods -n stellar-testnet -l app=my-testnet-validator

Wait for the pod to be in Running state:

NAME                                     READY   STATUS    RESTARTS   AGE
my-testnet-validator-0                   1/1     Running   0          3m

Check PersistentVolumeClaim

kubectl get pvc -n stellar-testnet

Verify the volume is bound:

NAME                           STATUS   VOLUME      CAPACITY   ACCESS MODES   AGE
data-my-testnet-validator-0    Bound    pvc-xyz...  500Gi      RWO            3m

Step 4: Monitor Node Startup

View Pod Logs

kubectl logs -n stellar-testnet my-testnet-validator-0 -f

Look for successful startup messages:

2024-06-02T10:30:15.123 INFO [default] Node starting...
2024-06-02T10:30:16.456 INFO [Herder] Joining network: testnet
2024-06-02T10:30:20.789 INFO [Herder] Connected to peers
2024-06-02T10:30:25.012 INFO [History] Catching up to network

Check Node Info

Get node information using kubectl exec:

kubectl exec -n stellar-testnet my-testnet-validator-0 -- \
  stellar-core --c info

Step 5: Verify Network Connectivity

Check Peer Connections

kubectl exec -n stellar-testnet my-testnet-validator-0 -- \
  stellar-core --c peers

You should see active peer connections:

{
  "authenticated_peers": {
    "inbound": 5,
    "outbound": 8
  }
}

Check Sync Status

kubectl exec -n stellar-testnet my-testnet-validator-0 -- \
  stellar-core --c 'll?level=info'

Step 6: Access Node Metrics (Optional)

If monitoring is enabled, access Prometheus metrics:

# Port-forward to metrics endpoint
kubectl port-forward -n stellar-testnet my-testnet-validator-0 11626:11626

# In another terminal, query metrics
curl http://localhost:11626/metrics

Step 7: Expose Node Externally (Optional)

To expose your validator for external peer connections, create a Service:

apiVersion: v1
kind: Service
metadata:
  name: my-testnet-validator-external
  namespace: stellar-testnet
spec:
  type: LoadBalancer
  selector:
    app: my-testnet-validator
  ports:
    - name: peer
      port: 11625
      targetPort: 11625
      protocol: TCP

Apply and get external IP:

kubectl apply -f validator-service.yaml
kubectl get svc -n stellar-testnet my-testnet-validator-external

Common Operations

Scale Validator Replicas

kubectl patch stellarvalidator my-testnet-validator \
  -n stellar-testnet \
  --type='merge' \
  -p '{"spec":{"replicas":3}}'

Update Configuration

Edit the validator resource:

kubectl edit stellarvalidator my-testnet-validator -n stellar-testnet

Restart Node

Delete the pod to trigger a restart:

kubectl delete pod -n stellar-testnet my-testnet-validator-0

The StatefulSet will automatically recreate it.

View Events

kubectl get events -n stellar-testnet --sort-by='.lastTimestamp'

Cleanup

To remove the validator:

# Delete the validator resource
kubectl delete stellarvalidator my-testnet-validator -n stellar-testnet

# Delete the namespace (removes all resources)
kubectl delete namespace stellar-testnet

!!! warning "Data Persistence" Deleting the namespace will also delete PersistentVolumeClaims. Ensure you've backed up any important data.

Next Steps

Now that you have a basic validator running:

Verification Checklist

Use this checklist to verify your deployment:

  • Validator resource created and shows READY 1/1
  • Pod is in Running state
  • PersistentVolumeClaim is Bound
  • Node logs show successful network connection
  • Peer connections are established (min 5 peers)
  • Node is syncing or caught up with the network
  • Metrics endpoint is accessible (if monitoring enabled)

!!! success "Congratulations!" You've successfully deployed your first Stellar validator node on Kubernetes! 🎉