Teleport
Dynamic App Registration
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
Dynamic app registration allows Teleport administrators to register new apps (or update/unregister existing ones) without having to update the static configuration files read by Teleport Application Service instances.
Application Service instances periodically query the Teleport Auth Service for
app
resources, each of which includes the information that the Application
Service needs to proxy an application.
Dynamic registration is useful for managing pools of Application Service instances. And behind the scenes, the Teleport Discovery Service uses dynamic registration to register Kubernetes applications.
Required permissions
In order to interact with dynamically registered applications, a user must have
a Teleport role with permissions to manage app
resources.
In the following example, a role allows a user to perform all possible
operations against app
resources:
allow:
rules:
- resources:
- app
verbs: [list, create, read, update, delete]
Enabling dynamic registration
To enable dynamic registration, include a resources
section in your Application
Service configuration with a list of resource label selectors you'd like this
service to monitor for registering:
app_service:
enabled: "yes"
resources:
- labels:
"*": "*"
You can use a wildcard selector to register all dynamic app resources in the cluster on the Application Service or provide a specific set of labels for a subset:
resources:
- labels:
"env": "prod"
- labels:
"env": "test"
Creating an app resource
Configure Teleport to proxy an application dynamically by creating an app
resource. The following example configures Teleport to proxy the application
called example
at localhost:4321
, making it available at the public address
test.example.com
:
kind: app
version: v3
metadata:
name: example
description: "Example app"
labels:
env: test
spec:
uri: http://localhost:4321
public_addr: test.example.com
See the full app resource spec reference.
The user creating the dynamic registration needs to have a role with access to the
application labels and the app
resource. In this example role the user can only
create and maintain application services labeled env: test
.
kind: role
metadata:
name: dynamicappregexample
spec:
allow:
app_labels:
env: test
rules:
- resources:
- app
verbs:
- list
- create
- read
- update
- delete
version: v5
To create an application resource, run:
Log in to your cluster with tsh so you can use tctl from your local machine.
You can also run tctl on your Auth Service host without running "tsh login"
first.
tsh login --proxy=teleport.example.com --user=myusertctl create app.yaml
Log in to your Teleport cluster so you can use tctl remotely.
tsh login --proxy=mytenant.teleport.sh --user=myusertctl create app.yaml
After the resource has been created, it will appear among the list of available
apps (in tsh apps ls
or UI) as long as at least one Application Service
instance picks it up according to its label selectors.
To update an existing application resource, run:
tctl create -f app.yaml
If the updated resource's labels no longer match a particular app agent, it will unregister and stop proxying it.
To delete an application resource, run:
tctl rm app/example