Connecting Your Cluster

This guide walks you through connecting a Kubernetes cluster to TinySystems.

Prerequisites

Before starting, ensure:

• [ ] Kubernetes cluster is running (see Cluster Requirements)
• [ ] kubectl is configured and can access the cluster
• [ ] You have admin access to create service accounts and RBAC
• [ ] TinySystems workspace is set up

Connection Methods

Method 1: Using the TinySystems CLI

The easiest way to connect a cluster:

# Install the tinysystems kubectl plugin
kubectl krew install tinysystems

# Connect your cluster
kubectl tinysystems connect \
  --workspace my-workspace \
  --name production-cluster

This automatically:

• Creates the tinysystems namespace
• Sets up the service account
• Configures RBAC permissions
• Generates and uploads kubeconfig

Method 2: Manual Setup

For more control, set up manually:

Step 1: Create Namespace

kubectl create namespace tinysystems

Step 2: Create Service Account

kubectl apply -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: tinysystems-controller
  namespace: tinysystems
---
apiVersion: v1
kind: Secret
metadata:
  name: tinysystems-controller-token
  namespace: tinysystems
  annotations:
    kubernetes.io/service-account.name: tinysystems-controller
type: kubernetes.io/service-account-token
EOF

Step 3: Create RBAC Permissions

kubectl apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: tinysystems-controller
rules:
  # TinySystems CRDs
  - apiGroups: ["operator.tinysystems.io"]
    resources: ["*"]
    verbs: ["*"]

  # Core resources
  - apiGroups: [""]
    resources: ["pods", "services", "configmaps", "secrets", "serviceaccounts"]
    verbs: ["*"]

  # Apps
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets"]
    verbs: ["*"]

  # Networking
  - apiGroups: ["networking.k8s.io"]
    resources: ["ingresses"]
    verbs: ["*"]

  # Coordination
  - apiGroups: ["coordination.k8s.io"]
    resources: ["leases"]
    verbs: ["*"]

  # RBAC (for module service accounts)
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["roles", "rolebindings", "clusterroles", "clusterrolebindings"]
    verbs: ["*"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: tinysystems-controller
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: tinysystems-controller
subjects:
  - kind: ServiceAccount
    name: tinysystems-controller
    namespace: tinysystems
EOF

Step 4: Generate Kubeconfig

# Get cluster info
CLUSTER_NAME=$(kubectl config current-context)
SERVER=$(kubectl config view -o jsonpath='{.clusters[0].cluster.server}')
CA_DATA=$(kubectl get secret tinysystems-controller-token -n tinysystems -o jsonpath='{.data.ca\.crt}')
TOKEN=$(kubectl get secret tinysystems-controller-token -n tinysystems -o jsonpath='{.data.token}' | base64 -d)

# Generate kubeconfig
cat > tinysystems-kubeconfig.yaml <<EOF
apiVersion: v1
kind: Config
clusters:
  - name: ${CLUSTER_NAME}
    cluster:
      server: ${SERVER}
      certificate-authority-data: ${CA_DATA}
contexts:
  - name: tinysystems
    context:
      cluster: ${CLUSTER_NAME}
      user: tinysystems-controller
      namespace: tinysystems
current-context: tinysystems
users:
  - name: tinysystems-controller
    user:
      token: ${TOKEN}
EOF

echo "Kubeconfig saved to tinysystems-kubeconfig.yaml"

Step 5: Add to TinySystems

1. Go to your TinySystems workspace
2. Navigate to Clusters > Add Cluster
3. Enter a name for the cluster
4. Upload or paste the kubeconfig
5. Click Connect

Verification

Test Connection

After connecting, verify the connection:

# In TinySystems UI
# Go to Clusters > Your Cluster > Status

# Or via kubectl
kubectl get namespace tinysystems
kubectl get serviceaccount tinysystems-controller -n tinysystems

Check Permissions

Verify the service account has correct permissions:

# Check if can create pods
kubectl auth can-i create pods \
  --namespace tinysystems \
  --as system:serviceaccount:tinysystems:tinysystems-controller

# Check if can create CRDs
kubectl auth can-i create tinynodes \
  --namespace tinysystems \
  --as system:serviceaccount:tinysystems:tinysystems-controller

Cloud-Specific Setup

Google Kubernetes Engine (GKE)

# Get credentials
gcloud container clusters get-credentials CLUSTER_NAME \
  --region REGION \
  --project PROJECT_ID

# Continue with standard setup
kubectl create namespace tinysystems
# ... (rest of setup)

Amazon EKS

# Update kubeconfig
aws eks update-kubeconfig \
  --name CLUSTER_NAME \
  --region REGION

# Continue with standard setup
kubectl create namespace tinysystems
# ... (rest of setup)

Azure AKS

# Get credentials
az aks get-credentials \
  --resource-group RESOURCE_GROUP \
  --name CLUSTER_NAME

# Continue with standard setup
kubectl create namespace tinysystems
# ... (rest of setup)

Local Development (minikube)

# Start minikube
minikube start

# Enable ingress addon (optional)
minikube addons enable ingress

# Continue with standard setup
kubectl create namespace tinysystems
# ... (rest of setup)

Namespace vs Cluster Scope

Namespace-Scoped (Recommended)

Limits TinySystems to specific namespace(s):

Pros:

• Better security isolation
• Easier to manage permissions
• Suitable for multi-tenant clusters

Cons:

• Cannot watch resources across namespaces
• Limited cross-namespace communication

Cluster-Scoped

Full cluster access:

Pros:

• Can manage resources in any namespace
• Simpler for single-tenant clusters
• Full visibility

Cons:

• Broader permissions required
• Security considerations

Security Best Practices

Least Privilege

Only grant required permissions:

# Instead of "*" for resources, be specific
rules:
  - apiGroups: [""]
    resources: ["pods", "services"]  # Not "*"
    verbs: ["get", "list", "watch", "create", "update", "delete"]

Rotate Credentials

Periodically rotate the service account token:

# Delete and recreate the token secret
kubectl delete secret tinysystems-controller-token -n tinysystems

kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: tinysystems-controller-token
  namespace: tinysystems
  annotations:
    kubernetes.io/service-account.name: tinysystems-controller
type: kubernetes.io/service-account-token
EOF

# Update kubeconfig in TinySystems

Network Security

If using network policies:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-tinysystems
  namespace: tinysystems
spec:
  podSelector: {}
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              name: tinysystems
  egress:
    - {}  # Allow all egress (or be more specific)

Troubleshooting Connection

Connection Failed

1. Check cluster is reachable
2. Verify kubeconfig is correct
3. Ensure service account exists
4. Check token is valid

Permission Denied

1. Verify RBAC rules are applied
2. Check ClusterRoleBinding exists
3. Test with kubectl auth can-i

Timeout

1. Check network connectivity
2. Verify API server is accessible
3. Check for firewall rules

See Troubleshooting Clusters for more help.

Next Steps

• Cluster Management - Manage your cluster
• Installing Modules - Deploy modules
• Troubleshooting Clusters - Common issues