diff --git a/docs/pages/includes/docker-images-oss.mdx b/docs/pages/includes/docker-images-oss.mdx deleted file mode 100644 index a7c86c82f03ca..0000000000000 --- a/docs/pages/includes/docker-images-oss.mdx +++ /dev/null @@ -1,27 +0,0 @@ -We provide a pre-built multi-arch Docker image for every version of Teleport, -including images for `amd64`, `arm`, and `arm64` architectures. Our images contain only Teleport binaries -and their application dependencies. - -These images are hosted on Amazon ECR Public. All tags under `public.ecr.aws/gravitational/teleport-distroless` [are Teleport Open Source images](https://gallery.ecr.aws/gravitational/teleport-distroless). - -The table below gives an idea of how our image naming scheme works. We offer -images that point to a static version of Teleport as well as images that 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 keep your Teleport installation up to -date. - -|Image name|Teleport version|Image automatically updated?|Troubleshooting Tools?|Image base| -|-|-|-|-|-| -|`public.ecr.aws/gravitational/teleport-distroless:(=teleport.major_version=)`|The latest version of Teleport Open Source|Yes|No|[Distroless Debian 11](https://github.com/GoogleContainerTools/distroless)| -|`public.ecr.aws/gravitational/teleport-distroless-debug:(=teleport.major_version=)`|The latest version of Teleport Open Source|Yes|Yes|[Distroless Debian 11](https://github.com/GoogleContainerTools/distroless)| -|`(=teleport.latest_oss_docker_image=)`|The version specified in the image's tag (i.e. (=teleport.version=))|No|No|[Distroless Debian 11](https://github.com/GoogleContainerTools/distroless)| -|`(=teleport.latest_oss_debug_docker_image=)`|The version specified in the image's tag (i.e. (=teleport.version=))|No|Yes|[Distroless Debian 11](https://github.com/GoogleContainerTools/distroless)| - -For testing, we always recommend that you use the latest released version of Teleport, which is currently `(=teleport.latest_oss_docker_image=)`. - -The `*-debug` images include a Busybox shell and tool suite in addition to Teleport, and are intended for troubleshooting deployments only. They are not intended for production use. - -[Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)-based images are available from our -[Legacy Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent). -Their use is considered deprecated, and they may be removed in future releases. diff --git a/docs/pages/includes/enterprise/docker-images.mdx b/docs/pages/includes/enterprise/docker-images.mdx deleted file mode 100644 index 25ad0334044ed..0000000000000 --- a/docs/pages/includes/enterprise/docker-images.mdx +++ /dev/null @@ -1,37 +0,0 @@ -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. Our images contain only Teleport binaries and their application dependencies. - -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. - -These images are hosted on our [Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent-distroless). -All tags under `public.ecr.aws/gravitational/teleport-ent-distroless` are -Teleport Enterprise images. Each tag points to a multi-arch image, containing -Teleport for `arm`, `arm64` and `amd64`. - -FIPS images are still posted to our [Legacy Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent). -You can specify the architecture of a Teleport FIPS Docker image by adding a -postfix to the image tag, e.g., `public.ecr.aws/gravitational/teleport:(=teleport.major_version=)-arm64`. -Versions without an architecture postfix use the `amd64` architecture, e.g., -`public.ecr.aws/gravitational/teleport:(=teleport.major_version=)`. - -| Image name | Open Source or Enterprise? | Teleport version | Image automatically updated? | Includes troubleshooting tools | Image base | -| - | - | - | - | - | - | -| `public.ecr.aws/gravitational/teleport-ent-distroless:(=teleport.major_version=)` | Enterprise | The latest version of Teleport Enterprise (=teleport.major_version=) | Yes | No | [Distroless Debian 11](https://github.com/GoogleContainerTools/distroless) | -| `public.ecr.aws/gravitational/teleport-ent-distroless-debug:(=teleport.major_version=)` | Enterprise | The latest version of Teleport Enterprise (=teleport.major_version=) | Yes | Yes | [Distroless Debian 11](https://github.com/GoogleContainerTools/distroless) | -| `public.ecr.aws/gravitational/teleport-ent:(=teleport.major_version=)-fips` | Enterprise FIPS | The latest version of Teleport Enterprise (=teleport.major_version=) FIPS | Yes | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | -| `(=teleport.latest_ent_docker_image=)` | Enterprise | The version specified in the image's tag (i.e. (=teleport.version=)) | No | No | [Distroless Debian 11](https://github.com/GoogleContainerTools/distroless) | -| `(=teleport.latest_ent_debug_docker_image=)` | Enterprise | The version specified in the image's tag (i.e. (=teleport.version=)) | No | Yes | [Distroless Debian 11](https://github.com/GoogleContainerTools/distroless) | -| `(=teleport.latest_ent_docker_image=)-fips` | Enterprise FIPS | The version specified in the image's tag (i.e. (=teleport.version=)) | No | Yes | [Ubuntu 20.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=)`. - -[Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)-based images for non-FIPS -Teleport are available from our [Legacy Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent). - -The `*-debug` images include a Busybox shell and tool suite in addition to Teleport, -and are intended for troubleshooting deployments only. They are not intended for production use. - diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx index 798945c823e4c..63c2ee8092ef5 100644 --- a/docs/pages/installation.mdx +++ b/docs/pages/installation.mdx @@ -107,21 +107,230 @@ information on obtaining Teleport binaries compatible with Teleport Cloud. ## Docker +### Images + +We provide a pre-built Docker image for every version of Teleport. This section +describes the available Docker images. + +These images are hosted on [Amazon ECR +Public](https://gallery.ecr.aws/gravitational). + +#### Image suffixes + +For each of the image names listed in this section, you can specify attributes +of the image by appending a suffix to the repository name or tag. + +Images with the `-distroless` suffix within the repository name include only the +`teleport` binary and its runtime dependencies, with no shell or utility +applications. An example is `public.ecr.aws/gravitational/teleport-distroless` +for Teleport Community Edition. + +Images with the `*-distroless-debug` suffix within the repository name include a +Busybox shell and tool suite in addition to Teleport, and are intended for +troubleshooting deployments only. They are not intended for production use. An +example is `public.ecr.aws/gravitational/teleport-distroless-debug`. + +You can specify the architecture of an image by appending a suffix to its tag. +We support the following architecture suffixes: `amd64`, `arm`, and `arm64`. For +example, if you want to pull the ARM64 image for +`public.ecr.aws/gravitational/teleport`, you can use +`public.ecr.aws/gravitational/teleport:(=teleport.version=)-arm64`. + +`*-distroless` and `*-distroless-debug` images support multiple architectures +natively, and do not require (or support) image suffixes. You can specify an +architecture using the `--platform` flag of `docker pull` to pull the `arm`, +`arm64` or `amd64` version of an image. + +#### Version tags + +Images point to a static version of Teleport. Use the image's tag to specify +either: + +- The major, minor, and patch version (e.g., `(=teleport.version=)` for the + latest version of Teleport Community Edition). +- The major version only, which implies the latest minor and patch numbers for + that major version. For example, `(=teleport.major_version=)` implies + `(=teleport.version=)`. + - + + +|Image name|Troubleshooting Tools?|Image base| +|-|-|-| +|`(=teleport.latest_oss_docker_image=)`|No|[Distroless Debian 11](https://github.com/GoogleContainerTools/distroless)| +|`(=teleport.latest_oss_debug_docker_image=)`|Yes|[Distroless Debian 11](https://github.com/GoogleContainerTools/distroless)| -(!docs/pages/includes/docker-images-oss.mdx!) +For testing, we always recommend that you use the latest released version of +Teleport, which is currently `(=teleport.latest_oss_docker_image=)`. + +[Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)-based images are available from +our [Legacy Amazon ECR Public +repository](https://gallery.ecr.aws/gravitational/teleport-ent). Their use is +considered deprecated, and they may be removed in future releases. - + + +| Image name | Teleport version | Includes troubleshooting tools | Image base | +| - | - | - | - | +| `(=teleport.latest_ent_docker_image=)` | No | [Distroless Debian 11](https://github.com/GoogleContainerTools/distroless) | +| `(=teleport.latest_ent_debug_docker_image=)` | Yes | [Distroless Debian 11](https://github.com/GoogleContainerTools/distroless) | + +We also provide the following images for FIPS builds of Teleport Enterprise: + +| Image name | Includes troubleshooting tools | Image base | +| - | - | - | +| `gravitational/teleport-ent-fips-distroless` | No | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | +| `gravitational/teleport-ent-fips-distroless-debug` | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) | -We provide pre-built `amd64`, `arm`, and `arm64` Docker images for every version of Teleport Enterprise. +For testing, we always recommend that you use the latest release version of +Teleport Enterprise, which is currently `(=teleport.latest_ent_docker_image=)`. -(!docs/pages/includes/enterprise/docker-images.mdx!) +[Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)-based images for non-FIPS +Teleport are available from our [Legacy Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent). +### Running Teleport on Docker + +When running a container from one of the images listed above, consider the +container equivalent to running the `teleport` binary. The Teleport container +requires access to a file system and network ports. + +#### Configuration + +Teleport processes read their configuration from a local file path, which is +`/etc/teleport.yaml` by default. Make sure this file path is mounted to your +Teleport container. + +#### Data directory + +All Teleport processes read from and write to a data directory, which by default +is `/var/lib/teleport`. Make sure the data directory is mounted to your Teleport +container. + +#### License file + +If your Teleport Enterprise container runs the Auth Service, you will need to +give it access to a license file at the path named in the configuration, which +is `/var/lib/teleport/license.pem` by default. Make sure a license exists at +this location in the Teleport container's data directory. + +#### Other file paths + +Depending on the configuration settings you assign on your Teleport container, +you will need to make sure that any file paths you name are mounted on the +container. + +For example, if you are running the Teleport Proxy Service on a container, you +need to mount the directory containing TLS credentials to your Teleport +container, then assign the following fields in the container's configuration +file to the appropriate paths: + +```yaml +proxy_service: + https_keypairs: + - key_file: /my/path/key.pem + cert_file: /my/path/cert.pem +``` + +See the Teleport [Configuration Reference](reference/config.mdx) for whether a +field you would like to assign requires a file path. + +#### Ports + +A single Teleport process can run multiple services, each of which listens on a +specific set of ports depending on your configuration. See our [Networking +Reference](reference/networking.mdx#ports) for the ports on your Teleport +container to expose. + +### Example of running a Teleport container + +In this example, we will show you how to run the Teleport Auth and Proxy +Services on a local Docker container using Teleport Community Edition. + +Since this container uses a self-signed certificate, we do not recommend using +this configuration to protect any infrastructure outside your workstation. You +can, however, join other local Docker containers to it using the [token +method](./management/join-services-to-your-cluster/join-token.mdx). + +First, create directories in your home directory to mount to the container. The +Teleport container will write its configuration and data to these directories: + +```code +$ mkdir -p ~/teleport/config ~/teleport/data +``` + +Run `teleport configure` from the Teleport container to generate a configuration +file. This sets the container's name to `localhost` so your browser can trust +the Proxy Service's self-signed TLS certificate: + +```code +$ docker run --hostname localhost --rm \ + --entrypoint=/usr/local/bin/teleport \ + configure --roles=proxy,auth > ~/teleport/config/teleport.yaml +``` + +Start Teleport on your container: + +```code +$ docker run --hostname localhost --name teleport \ + -v ~/teleport/config:/etc/teleport \ + -v ~/teleport/data:/var/lib/teleport \ + -p 3025:3025 -p 3080:3080 \ + +``` + +From there, open another terminal and make sure your Teleport container's web +API is functioning as intended: + +```code +$ curl --insecure https://localhost:3080/webapi/ping +``` + +You should see JSON output similar to the following: + +```json +{ + "auth": { + "type": "local", + "second_factor": "otp", + "preferred_local_mfa": "otp", + "local": { + "name": "" + }, + "private_key_policy": "none", + "device_trust_disabled": true, + "has_motd": false + }, + "proxy": { + "kube": { + "enabled": true, + "listen_addr": "0.0.0.0:3080" + }, + "ssh": { + "listen_addr": "0.0.0.0:3080", + "tunnel_listen_addr": "0.0.0.0:3080", + "web_listen_addr": "0.0.0.0:3080" + }, + "db": { + "postgres_listen_addr": "0.0.0.0:3080", + "mysql_listen_addr": "0.0.0.0:3080" + }, + "tls_routing_enabled": true + }, + "server_version": "12.1.5", + "min_client_version": "11.0.0", + "cluster_name": "localhost", + "automatic_upgrades": false +} +``` + +We are using the `--insecure` flag to trust Teleport's self-signed certificate. +In production, you will want to provision TLS credentials to the Proxy Service +from a trusted CA, e.g., Let's Encrypt. + ## Helm (!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)