Proxy Settings Management
Relevant source files
The following files were used as context for generating this wiki page:
The Proxy Settings Management module is responsible for configuring the Teleport Proxy service, which acts as the secure gateway for the Teleport cluster. Its primary purpose is to manage TLS identities, handle certificate issuance (both self-signed and ACME-based), and define the connection parameters for nodes joining the cluster.
The scope of this module includes directory initialization, private key generation, Certificate Signing Request (CSR) creation, and integration with external certificate authorities like Let's Encrypt via ACME. It ensures that the proxy server has a valid identity to facilitate secure communication between users, the Auth service, and connected nodes.
Sources: tasks/config/proxy.yml:1-72, defaults/main.yml:144-153
Architecture and Infrastructure
The proxy management logic is conditionally executed based on the teleport_proxy_enabled variable. When enabled, the system initializes a dedicated TLS directory and manages the security artifacts required for the proxy's HTTPS interface.
Provisioning Flow
The following diagram illustrates the sequence of operations performed when configuring the proxy service:
This flow ensures that the proxy always has a valid certificate, favoring ACME when configured but falling back to self-signed certificates for internal or initial setups.
Sources: tasks/config/proxy.yml:4-72, tasks/main.yml:50-54
Security and Certificate Management
The module provides two primary methods for securing the proxy: manual/self-signed certificates and automated ACME (Let's Encrypt) certificates.
TLS Configuration Parameters
The system uses several variables to define the subject identity of the proxy certificates.
| Variable | Description | Default |
|---|---|---|
teleport_proxy_tls_dir | Path to store TLS artifacts | /etc/teleport/tls |
teleport_proxy_server | Public DNS name of the proxy | "" |
teleport_tls_country | Country for CSR | BR |
teleport_tls_organization | Organization for CSR | Datacosmos |
teleport_proxy_acme_enabled | Enable Let's Encrypt integration | false |
| Sources: defaults/main.yml:48-55, defaults/main.yml:144-150 |
ACME Integration
When teleport_proxy_acme_enabled is set to true, the role installs certbot and python3-certbot. It executes a standalone challenge to obtain certificates from Let's Encrypt.
Sources: tasks/config/proxy.yml:58-72
External Communication and Discovery
The proxy serves as the primary endpoint for cluster discovery. Other components interact with the proxy via specific API endpoints during the preflight and security phases.
Version Detection
The system can autodetect the required Teleport version by querying the proxy's version API.
- Endpoint:
https://{{ teleport_proxy_server }}/v1/webapi/automaticupgrades/channel/{{ teleport_channel }}/version - Logic: Uses the
ansible.builtin.urimodule to fetch and parse the version string.
Sources: tasks/preflight/version.yml:4-20
CA PIN Retrieval
For secure node joining, the role can automatically retrieve the cluster's CA PIN from the proxy.
- Endpoint:
https://{{ teleport_proxy_server }}:443/webapi/auth/export - Security: The operation is governed by
teleport_validate_certs.
Sources: tasks/security/ca_pin.yml:2-12
Implementation Details
CSR Generation logic
The CSR generation includes automated Subject Alternative Name (SAN) handling. It ensures that localhost and 127.0.0.1 are always included alongside the primary proxy server address.
- name: Generate CSR for proxy certificate
community.crypto.openssl_csr:
path: "{{ teleport_proxy_tls_dir }}/teleport.csr"
privatekey_path: "{{ teleport_proxy_tls_key }}"
common_name: "{{ teleport_proxy_server }}"
subject_alt_name: >
{%- set sans = ['DNS:' + teleport_proxy_server, 'DNS:localhost', 'IP:127.0.0.1'] -%}
{%- if teleport_tls_sans is defined -%}
{{ sans + (teleport_tls_sans | map('regex_replace', '^(DNS|IP):', '\\1:') | list) }}
{%- else -%}
{{ sans }}
{%- endif -%}
Sources: tasks/config/proxy.yml:25-45
Summary
Proxy Settings Management ensures the Teleport Proxy is correctly identified and secured. By managing the lifecycle of TLS certificates and providing endpoints for cluster discovery (versioning and CA pins), it facilitates the secure entry point for the entire Teleport cluster architecture.
Sources: tasks/main.yml:37-54, tasks/config/proxy.yml:1-72