# Teleport Installation

## 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.

```bash
./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:**

```bash
# 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.

```bash
./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:**

```bash
# 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:**

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

# Check token expiration
# Contact Platform9 Support if token fails
```

**Connection Issues:**

```bash
# 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:**

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

**Remove Node Agent:**

```bash
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:

```bash
./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