Teleport Installation

This guide provides comprehensive instructions for installing Teleport agents on Platform9 Private Cloud Director environments.

Introduction

Teleport enables secure, role-based access to Kubernetes clusters and individual nodes for debugging, monitoring, and management operations. It is a solution for:

• Secure Remote Access: SSH and web-based access to cluster resources
• Role-Based Access Control: Granular permissions for different user roles
• Audit and Compliance: Full logging and session recording
• Cross-Platform Access: Unified access to multiple environments

Prerequisites

• Self-hosted Private cloude Directer is installed and configured
• kubectl access to the Management cluster
• Valid Teleport join token from Platform9 Support

Installation Options

Option 1: Kubernetes Agent Installation

Install Teleport agent into a Kubernetes namespace for namespace-scoped access.

./install-teleport.sh --token <JOIN_TOKEN> \
  --namespace <NAMESPACE> \
  --proxy-addr <PROXY_ADDR> \
  --cluster-name <CLUSTER_NAME> \
  --version <VERSION> \
  --access-namespace <NAMESPACE[,NAMESPACE]> \
  --access-level <admin|readonly> \
  --resource kube

Parameters:

• --token: Join token (required)
• --namespace: Target namespace where the Teleport agent pod runs (default: teleport)
• --proxy-addr: Teleport proxy address (default: platform9.teleport.sh:443)
• --cluster-name: name for identification in Teleport interface(default: example-k8s-cluster)
• --version: Teleport version (default: 18.1.4)
• --access-namespace: Namespace(s) to grant access (comma-separated)
• --access-level: Access level - admin or readonly (default: admin)
• --resource: Resource type - kube (default)

Examples:

# Basic installation with admin access to teleport namespace
./install-teleport.sh --token abc123 --namespace my-app --access-level admin

# Cluster-wide admin access
./install-teleport.sh --token abc123 --access-level admin

# Read-only access to specific namespaces
./install-teleport.sh --token abc123 --access-namespace app1,app2 --access-level readonly

# Custom namespace and cluster name
./install-teleport.sh --token abc123 --namespace production --cluster-name prod-k8s-cluster

Option 2: Node Installation

Install Teleport node agent on individual Kubernetes nodes for node-level access.

./install-teleport.sh --token <JOIN_TOKEN> \
  --proxy-addr <PROXY_ADDR> \
  --version <VERSION> \
  --resource node

Parameters:

• --token: Join token (required)
• --proxy-addr: Teleport proxy address (default: platform9.teleport.sh:443)
• --version: Teleport version (default: 18.1.4)
• --resource: Resource type - node (required)

Example:

# Install Teleport on a worker node
./install-teleport.sh --token abc123 --resource node

Access Levels

Admin Access

• Cluster Role: cluster-admin (full cluster access)
• Namespace Role: admin (full namespace access)
• Capabilities: Create, read, update, delete resources

Read-Only Access

• Cluster Role: teleport-view-only (cluster-wide read-only)
• Namespace Role: teleport-namespace-view (namespace read-only)
• Capabilities: Get, list, watch resources only

What Gets Installed

Kubernetes Agent

• Helm Release: teleport-agent in specified namespace
• RBAC: ClusterRole and RoleBindings for specified access level
• Service Account: Teleport service account with appropriate permissions
• Proxy Configuration: Automatic connection to Platform9 Teleport proxy

Node Agent

• System Service: Teleport node service installed and started
• Configuration: Node configured with join token and proxy settings
• System Integration: Integrated with systemd for automatic startup

Proxy Configuration

The script automatically configures connection to Platform9's Teleport proxy:

• Default Proxy: platform9.teleport.sh:443
• Custom Proxy: Use --proxy-addr for alternative proxy
• Environment Variables: HTTP_PROXY, HTTPS_PROXY, NO_PROXY automatically configured

Security Considerations

Token Security

• Join tokens are single-use and expire after first use
• Store tokens securely and never commit to version control
• Obtain fresh tokens for each installation

Access Control

• Principle of Least Privilege: Use read-only access when possible
• Namespace Scoping: Limit access to specific namespaces when no cluster-wide access is needed

Network Security

• Proxy Only: All Teleport connections go through Platform9 proxy
• TLS Encryption: All communications encrypted via TLS
• Firewall Rules: Ensure outbound connections to proxy are allowed

Troubleshooting

Common Issues

Token Issues:

# Verify token format
echo $JOIN_TOKEN | wc -c  # Should be reasonable length

# Check token expiration
# Contact Platform9 Support if token fails

Connection Issues:

# Test proxy connectivity
curl -I https://platform9.teleport.sh:443

# Check network connectivity
ping platform9.teleport.sh

Log Locations

• Kubernetes Agent: Check pod logs: kubectl logs -n <NAMESPACE> teleport-agent-xxx
• Node Agent: Check system logs: sudo journalctl -u teleport -f
• Installation Logs: Script outputs detailed progress and error messages

Cleanup

Remove Kubernetes Agent:

helm uninstall teleport-agent -n <NAMESPACE>
kubectl delete rolebinding,role -n <NAMESPACE> -l app.kubernetes.io/name=teleport

Remove Node Agent:

sudo systemctl stop teleport
sudo systemctl disable teleport
sudo rm -f /etc/teleport.yaml

Advanced Configuration

Multiple Namespace Access

Grant access to multiple namespaces with comma-separated list:

./install-teleport.sh --token abc123 \
  --access-namespace dev,staging,production \
  --access-level readonly

This creates RoleBindings in each specified namespace with read-only permissions.

Support

For issues or questions:

• Contact Platform9 Support
• Verify network connectivity to Teleport proxy