mirror of
https://github.com/gravitational/teleport
synced 2024-10-19 08:43:58 +00:00
Add Docker OSS/Enterprise quickstarts (#4071)
* Add docker-compose Teleport quickstart and update docs
This commit is contained in:
Gus Luxton
GitHub
parent
19d482dad3
commit
2c2440c53c
31
docker/teleport-ent-quickstart.yml
Normal file
31
docker/teleport-ent-quickstart.yml
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
version: '2'
|
||||
services:
|
||||
# The configure container starts, generates a config, writes it to
|
||||
# /etc/teleport/teleport.yaml and then immediately exits.
|
||||
configure:
|
||||
image: quay.io/gravitational/teleport-ent:4.3
|
||||
container_name: teleport-configure
|
||||
entrypoint: /bin/sh
|
||||
hostname: localhost
|
||||
command: -c "if [ ! -f /etc/teleport/teleport.yaml ]; then /usr/local/bin/teleport configure > /etc/teleport/teleport.yaml; fi"
|
||||
volumes:
|
||||
- ./teleport/config:/etc/teleport
|
||||
|
||||
# This container depends on the config written by the configure container above, so it
|
||||
# sleeps for a second on startup to allow the configure container to run first.
|
||||
teleport:
|
||||
image: quay.io/gravitational/teleport-ent:4.3
|
||||
container_name: teleport
|
||||
entrypoint: /bin/sh
|
||||
hostname: localhost
|
||||
command: -c "sleep 1 && /usr/local/bin/teleport start"
|
||||
ports:
|
||||
- "3023:3023"
|
||||
- "3025:3025"
|
||||
- "3080:3080"
|
||||
volumes:
|
||||
- ./teleport/config:/etc/teleport
|
||||
- ./teleport/data:/var/lib/teleport
|
||||
- ./license.pem:/var/lib/teleport/license.pem
|
||||
depends_on:
|
||||
- configure
|
||||
30
docker/teleport-quickstart.yml
Normal file
30
docker/teleport-quickstart.yml
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
version: '2'
|
||||
services:
|
||||
# The configure container starts, generates a config, writes it to
|
||||
# /etc/teleport/teleport.yaml and then immediately exits.
|
||||
configure:
|
||||
image: quay.io/gravitational/teleport:4.3
|
||||
container_name: teleport-configure
|
||||
entrypoint: /bin/sh
|
||||
hostname: localhost
|
||||
command: -c "if [ ! -f /etc/teleport/teleport.yaml ]; then /usr/local/bin/teleport configure > /etc/teleport/teleport.yaml; fi"
|
||||
volumes:
|
||||
- ./teleport/config:/etc/teleport
|
||||
|
||||
# This container depends on the config written by the configure container above, so it
|
||||
# sleeps for a second on startup to allow the configure container to run first.
|
||||
teleport:
|
||||
image: quay.io/gravitational/teleport:4.3
|
||||
container_name: teleport
|
||||
entrypoint: /bin/sh
|
||||
hostname: localhost
|
||||
command: -c "sleep 1 && /usr/local/bin/teleport start"
|
||||
ports:
|
||||
- "3023:3023"
|
||||
- "3025:3025"
|
||||
- "3080:3080"
|
||||
volumes:
|
||||
- ./teleport/config:/etc/teleport
|
||||
- ./teleport/data:/var/lib/teleport
|
||||
depends_on:
|
||||
- configure
|
||||
|
|
@ -36,6 +36,8 @@ extra:
|
|||
sha: 1c14362c9ba10f28088c7228b357dc6a70072d3d4afaa5510c70a8734068684c
|
||||
plugin:
|
||||
version: 0.1.0
|
||||
latest_oss_docker_image: quay.io/gravitational/teleport:4.3
|
||||
latest_ent_docker_image: quay.io/gravitational/teleport-ent:4.3
|
||||
nav:
|
||||
- Documentation:
|
||||
- Introduction: index.md
|
||||
|
|
|
|||
|
|
@ -41,6 +41,11 @@ _"node.example.com"_ | 10.1.1.11 | This server will only run the SSH servi
|
|||
This Quick Start Guide assumes that both servers are running a [systemd-based](https://www.freedesktop.org/wiki/Software/systemd/)
|
||||
Linux distribution such as Debian, Ubuntu or a RHEL derivative.
|
||||
|
||||
## Optional: Quickstart using Docker
|
||||
|
||||
The instructions below describe how to install Teleport Enterprise directly onto your test system. You can also [run Teleport Enterprise using Docker](#run-teleport-enterprise-using-docker)
|
||||
if you don't want to install Teleport Enterprise binaries straight away.
|
||||
|
||||
## Installing
|
||||
|
||||
To start using Teleport Enterprise, you will need to Download the binaries and the license file from the [customer portal](https://dashboard.gravitational.com).
|
||||
|
|
@ -315,6 +320,110 @@ Any SAML-compliant provider can be configured with Teleport by following the
|
|||
same steps. There are Teleport Enterprise customers who are using Oracle IDM,
|
||||
SailPoint and others.
|
||||
|
||||
## Run Teleport Enterprise using Docker
|
||||
|
||||
We provide pre-built Docker images for every version of Teleport Enterprise. These images are hosted on quay.io.
|
||||
|
||||
- [All tags under `quay.io/gravitational/teleport-ent` are Teleport Enterprise images](https://quay.io/repository/gravitational/teleport-ent?tag=latest&tab=tags)
|
||||
|
||||
We currently only offer Docker images for `x86_64` architectures.
|
||||
|
||||
!!! note
|
||||
You will need a recent version of [Docker](https://hub.docker.com/search?q=&type=edition&offering=community) installed to follow this section of the quick start guide.
|
||||
|
||||
!!! warning
|
||||
This setup will not let you 'SSH into' the node that is running Teleport without additional configuration.
|
||||
|
||||
### Pick your image
|
||||
|
||||
This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are
|
||||
automatically rebuilt every night. These nightly images point to the latest version of Teleport Enterprise from the three most recent release branches.
|
||||
They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date.
|
||||
|
||||
| Image name | Community or Enterprise? | Teleport version | Image automatically updated? | Image base |
|
||||
|---|---|---|---|---|
|
||||
| `quay.io/gravitational/teleport-ent:4.3` | Enterprise | The latest version of Teleport Enterprise 4.3 | Yes | [Ubuntu 20.04](https://hub.docker.com/_/ubuntu) |
|
||||
| `quay.io/gravitational/teleport-ent:4.3-fips` | Enterprise FIPS | The latest version of Teleport Enterprise 4.3 FIPS | Yes | [Ubuntu 20.04](https://hub.docker.com/_/ubuntu) |
|
||||
| `quay.io/gravitational/teleport-ent:4.3.0` | Enterprise | 4.3.0 | No | [Ubuntu 18.04](https://hub.docker.com/_/ubuntu) |
|
||||
| `quay.io/gravitational/teleport-ent:4.3.0-fips` | Enterprise FIPS | 4.3.0 | No | [Ubuntu 18.04](https://hub.docker.com/_/ubuntu) |
|
||||
|
||||
For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently `{{teleport.latest_ent_docker_image}}`.
|
||||
|
||||
### Quickstart using docker-compose
|
||||
|
||||
!!! note
|
||||
You will need a recent version of [`docker-compose`](https://docs.docker.com/compose/install/) installed to follow this section of the quick start guide.
|
||||
|
||||
The easiest way to start Teleport Enterprise quickly is to use `docker-compose` with our [`teleport-ent-quickstart.yml`](https://github.com/gravitational/teleport/blob/master/docker/teleport-ent-quickstart.yml) file:
|
||||
|
||||
```bash
|
||||
# download the quickstart file from our Github repo
|
||||
curl -Lso teleport-ent-quickstart.yml https://raw.githubusercontent.com/gravitational/teleport/master/docker/teleport-ent-quickstart.yml
|
||||
|
||||
# start teleport quickstart using docker-compose
|
||||
docker-compose -f teleport-ent-quickstart.yml up
|
||||
```
|
||||
|
||||
- The `docker-compose` quickstart will automatically create a config file for you at `./docker/teleport/config/teleport.yaml`
|
||||
- This config is mounted into the container under `/etc/teleport/teleport.yaml`
|
||||
- It will also start `teleport` using this config file, with Teleport's data directory set to `./docker/teleport/data` and mounted under `/var/lib/teleport`
|
||||
- It will mount your license file (named `license.pem`) from the current directory into the Docker container
|
||||
- By default, `docker-compose` will output Teleport's logs to the console for you to observe.
|
||||
- If you would rather run the Teleport container in the background, use `docker-compose -f teleport-ent-quickstart.yml up -d`
|
||||
- You can stop the Teleport container using `docker-compose -f teleport-ent-quickstart.yml down`
|
||||
|
||||
### Quickstart using docker run
|
||||
|
||||
If you'd prefer to complete these steps manually, here's some sample `docker run` commands:
|
||||
|
||||
```bash
|
||||
# create local config and data directories for teleport, which will be mounted into the container
|
||||
mkdir -p ~/teleport/config ~/teleport/data
|
||||
|
||||
# download your license file from the Gravitational dashboard and put it in the correct directory
|
||||
# the file needs to be named license.pem
|
||||
cp ~/downloads/downloaded-license.pem ~/teleport/data/license.pem
|
||||
|
||||
# generate a sample teleport config and write it to the local config directory
|
||||
# this container will write the config and immediately exit - this is expected
|
||||
docker run --hostname localhost --rm \
|
||||
--entrypoint=/bin/sh \
|
||||
-v ~/teleport/config:/etc/teleport \
|
||||
{{teleport.latest_ent_docker_image}} -c "teleport configure > /etc/teleport/teleport.yaml"
|
||||
|
||||
# change the path to the license file in the sample config
|
||||
sed -i 's_/path/to/license-if-using-teleport-enterprise.pem_/var/lib/teleport/license.pem_g' ~/teleport/config/teleport.yaml
|
||||
|
||||
# start teleport with mounted license, config and data directories, plus all ports
|
||||
docker run --hostname localhost --name teleport \
|
||||
-v ~/teleport/config:/etc/teleport \
|
||||
-v ~/teleport/data:/var/lib/teleport \
|
||||
-p 3023:3023 -p 3025:3025 -p 3080:3080 \
|
||||
{{teleport.latest_ent_docker_image}}
|
||||
```
|
||||
|
||||
### Creating a Teleport user when using Docker quickstart
|
||||
|
||||
To create a user inside your Teleport Enterprise container, use `docker exec`.
|
||||
|
||||
This example command will create a Teleport user called `testuser` which has the `admin` role. Feel free to change these to suit your needs.
|
||||
|
||||
```bash
|
||||
docker exec teleport tctl users add testuser --roles=admin
|
||||
```
|
||||
|
||||
When you run this command, Teleport will output a URL which you must open to complete the user signup process:
|
||||
|
||||
```bash
|
||||
User testuser has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h0m0s:
|
||||
https://localhost:3080/web/invite/4f2718a52ce107568b191f222ba069f7
|
||||
|
||||
NOTE: Make sure localhost:3080 points at a Teleport proxy which users can access.
|
||||
```
|
||||
|
||||
You can now [follow this guide from "Adding Users"](#adding-users) onwards to create your user and log into Teleport Enterprise.
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If Teleport services do not start, take a look at the syslog:
|
||||
|
|
|
|||
|
|
@ -29,6 +29,8 @@ white-list-external:
|
|||
- "https://teleport.example.com:8443"
|
||||
- "https://teleport.example.com"
|
||||
- "https://[route53_domain](#route53_domain"
|
||||
- "https://github.com/gravitational/teleport/blob/master/docker/teleport-quickstart.yml"
|
||||
- "https://github.com/gravitational/teleport/blob/master/docker/teleport-ent-quickstart.yml"
|
||||
- "https://kubernetes.io/docs/reference/access-authn-authz/rbac/"
|
||||
- "https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation"
|
||||
black-list:
|
||||
|
|
|
|||
|
|
@ -23,6 +23,11 @@ environment, and showcase a few basic tasks you can do with Teleport.
|
|||
**You should not follow this guide if you want to set up Teleport in production.
|
||||
Instead follow the [Admin Guide](admin-guide.md)**
|
||||
|
||||
## Optional: Quickstart using Docker
|
||||
|
||||
The instructions below describe how to install Teleport directly onto your test system. You can also [run Teleport using Docker](#run-teleport-using-docker)
|
||||
if you don't want to install Teleport binaries straight away.
|
||||
|
||||
## Step 1: Install Teleport
|
||||
|
||||
This guide installs teleport v{{ teleport.version }} on the CLI. Previous versions are documented
|
||||
|
|
@ -274,6 +279,100 @@ $ echo "Awesome!"
|
|||
# check out your shared ssh session between two CLI windows
|
||||
```
|
||||
|
||||
## Run Teleport using Docker
|
||||
|
||||
We provide pre-built Docker images for every version of Teleport. These images are hosted on quay.io.
|
||||
|
||||
- [All tags under `quay.io/gravitational/teleport` are Teleport Community images](https://quay.io/repository/gravitational/teleport?tag=latest&tab=tags)
|
||||
|
||||
We currently only offer Docker images for `x86_64` architectures.
|
||||
|
||||
!!! note
|
||||
You will need a recent version of [Docker](https://hub.docker.com/search?q=&type=edition&offering=community) installed to follow this section of the quick start guide.
|
||||
|
||||
!!! warning
|
||||
This setup will not let you 'SSH into' the node that is running Teleport without additional configuration.
|
||||
|
||||
### Pick your image
|
||||
|
||||
This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport, as well as images which are
|
||||
automatically rebuilt every night. These nightly images point to the latest version of Teleport from the three most recent release branches.
|
||||
They are stable, and we recommend their use to easily keep your Teleport installation up to date.
|
||||
|
||||
| Image name | Community or Enterprise? | Teleport version | Image automatically updated? | Image base |
|
||||
|---|---|---|---|---|
|
||||
| `quay.io/gravitational/teleport:4.3` | Community | The latest version of Teleport Community 4.3 | Yes | [Ubuntu 20.04](https://hub.docker.com/_/ubuntu) |
|
||||
| `quay.io/gravitational/teleport:4.3.0` | Community | 4.3.0 | No | [Ubuntu 18.04](https://hub.docker.com/_/ubuntu) |
|
||||
|
||||
For testing, we always recommend that you use the latest release version of Teleport, which is currently `{{teleport.latest_oss_docker_image}}`.
|
||||
|
||||
### Quickstart using docker-compose
|
||||
|
||||
!!! note
|
||||
You will need a recent version of [`docker-compose`](https://docs.docker.com/compose/install/) installed to follow this section of the quick start guide.
|
||||
|
||||
The easiest way to start Teleport quickly is to use `docker-compose` with our [`teleport-quickstart.yml`](https://github.com/gravitational/teleport/blob/master/docker/teleport-quickstart.yml) file:
|
||||
|
||||
```bash
|
||||
# download the quickstart file from our Github repo
|
||||
curl -Lso teleport-quickstart.yml https://raw.githubusercontent.com/gravitational/teleport/master/docker/teleport-quickstart.yml
|
||||
|
||||
# start teleport quickstart using docker-compose
|
||||
docker-compose -f teleport-quickstart.yml up
|
||||
```
|
||||
|
||||
- The `docker-compose` quickstart will automatically create a config file for you at `./docker/teleport/config/teleport.yaml`
|
||||
- This config is mounted into the container under `/etc/teleport/teleport.yaml`
|
||||
- It will also start `teleport` using this config file, with Teleport's data directory set to `./docker/teleport/data` and mounted under `/var/lib/teleport`
|
||||
- By default, `docker-compose` will output Teleport's logs to the console for you to observe.
|
||||
- If you would rather run the Teleport container in the background, use `docker-compose -f teleport-quickstart.yml up -d`
|
||||
- You can stop the Teleport container using `docker-compose -f teleport-quickstart.yml down`
|
||||
|
||||
### Quickstart using docker run
|
||||
|
||||
If you'd prefer to complete these steps manually, here's some sample `docker run` commands:
|
||||
|
||||
```bash
|
||||
# create local config and data directories for teleport, which will be mounted into the container
|
||||
mkdir -p ~/teleport/config ~/teleport/data
|
||||
|
||||
# generate a sample teleport config and write it to the local config directory
|
||||
# this container will write the config and immediately exit - this is expected
|
||||
docker run --hostname localhost --rm \
|
||||
--entrypoint=/bin/sh \
|
||||
-v ~/teleport/config:/etc/teleport \
|
||||
{{teleport.latest_oss_docker_image}} -c "teleport configure > /etc/teleport/teleport.yaml"
|
||||
|
||||
# start teleport with mounted config and data directories, plus all ports
|
||||
docker run --hostname localhost --name teleport \
|
||||
-v ~/teleport/config:/etc/teleport \
|
||||
-v ~/teleport/data:/var/lib/teleport \
|
||||
-p 3023:3023 -p 3025:3025 -p 3080:3080 \
|
||||
{{teleport.latest_oss_docker_image}}
|
||||
```
|
||||
|
||||
### Creating a Teleport user when using Docker quickstart
|
||||
|
||||
To create a user inside your Teleport container, use `docker exec`.
|
||||
|
||||
This example command will create a Teleport user called `testuser` which is allowed to log in as either OS user `root` or `ubuntu`. Feel free to change these to suit your needs -
|
||||
[there are more instructions above in Step 3](#step-3-create-a-user-signup-token) if you'd like additional details):
|
||||
|
||||
```bash
|
||||
docker exec teleport tctl users add testuser root,ubuntu
|
||||
```
|
||||
|
||||
When you run this command, Teleport will output a URL which you must open to complete the user signup process:
|
||||
|
||||
```bash
|
||||
User testuser has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h0m0s:
|
||||
https://localhost:3080/web/invite/4f2718a52ce107568b191f222ba069f7
|
||||
|
||||
NOTE: Make sure localhost:3080 points at a Teleport proxy which users can access.
|
||||
```
|
||||
|
||||
You can now [follow this guide from Step 4 onwards](#step-4-register-a-user) to create your user and log into Teleport.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Congratulations! You've completed the Teleport Quickstart.
|
||||
|
|
|
|||
Loading…
Reference in a new issue