Document provided init system configs and other ways of managing teleport

awly commented 4 years ago

Summary

We have a few init system configs (systemd, upstart) scattered around the examples/ folder and docs. There are also vagrant configs and helm charts. We also build AWS AMIs.

All of these options are rather disorganized or hard to find. We should have "how to run a teleport binary" docs in addition to "where to get the teleport binary". There's some overlap here with "Infrastructure guides" (e.g. https://gravitational.com/teleport/docs/aws_oss_guide/) too.

Audience

New users

Location

https://gravitational.com/teleport/docs/installation/ and new page linked from it

webvictim commented 4 years ago

Yeah, we should add a Docker image guide to this section too.

webvictim commented 4 years ago

While doing this, we should also improve our examples of how to provide AWS credentials to Teleport when running via systemd. The default sandbox prevents Teleport from accessing ~/.aws/credentials.

ptgott commented 2 years ago

I've done a bit of research into this issue and suggested some things we can do.

What we have now

What resource directories do we have?

/examples
/vagrant
/assets

How are these documented?

Nothing in the vagrant directory is mentioned outside of that directory.
Nothing in assets is mentioned in the documentation, though the directory is used in tests and automation.
Our Helm charts are all in examples
examples/etcd is used in our unit/integration tests
Some resources in examples are not mentioned in the docs, while others are (see below).

Which resources in `/examples` are not mentioned in the docs?

I ran the following script from the gravitational/teleport repo root:

results=$(find ./examples -type d -maxdepth 2 -mindepth 1);
mentioned="";
unmentioned="";
for i in ${results}; do
    # Remove the leading "./" in case a docs page uses a different
    # relative path
    name_trimmed=$(echo ${i} | sed "s/^\.\///");
    if grep -Rl "$name_trimmed" ./docs/pages 2>&1 > /dev/null; then
        mentioned="${mentioned}\n${i}"; else
        unmentioned="${unmentioned}\n${i}";
    fi
done;
echo -e "directories in ./examples not mentioned in the docs: ${unmentioned}\n";
echo -e "directories in ./examples that **are** mentioned in the docs: ${mentioned}";

Here are the results:

directories in ./examples not mentioned in the docs: ./examples/upstart ./examples/bench ./examples/local-cluster ./examples/local-cluster/proxy ./examples/local-cluster/auth ./examples/local-cluster/node ./examples/go-client ./examples/chart/teleport-auto-trustedcluster ./examples/chart/teleport-daemonset ./examples/workflows ./examples/gke-auth ./examples/etcd ./examples/etcd/certs ./examples/launchd ./examples/aws/eks ./examples/aws/cloudformation

directories in ./examples that are mentioned in the docs: ./examples/jwt ./examples/systemd ./examples/systemd/plugins ./examples/systemd/production ./examples/systemd/fips ./examples/resources ./examples/resources/terraform ./examples/resources/plugins ./examples/chart ./examples/chart/teleport-cluster ./examples/chart/teleport-kube-agent ./examples/chart/teleport ./examples/k8s-auth ./examples/aws ./examples/aws/terraform

Docker images

These are listed in:

Enterprise getting started guide
Our Helm chart reference
Our Docker setup guide, the only place where we include this partial that lists images

Possible plan

The "How to run Teleport" guide

We already have this guide on running Teleport as a daemon, which includes a section on systemd. We can add sections to this guide for other init systems/environments.

Docker: Include the docs/pages/includes/image.mdx partial
systemd: The existing section from the "Teleport Daemon" guide, plus improve our examples of how to provide AWS credentials to Teleport when running via systemd.
launchd: Include the example configuration in examples/launchd for running on MacOS
VM images: List our AWS AMIs (looks like this is the only cloud we create machine images for)

For resources not covered in this "How to run Teleport" guide outline

examples/upstart: Since this is in maintenance mode and Chromium OS is the only well-known project that still uses it, would it be worth removing this from /examples? Otherwise, this isn't mentioned anywhere in the docs.

The vagrant directory: Since the vagrant directory isn't mentioned anywhere in the docs, should we create a guide to running Teleport via Vagrant (e.g., in a Getting Started guide)? This could be an alternative to our Docker Compose guide.

examples/bench: This is a benchmarking tool for tsh, and was last worked on in Dec 2020. If we're still using it, and want to devote the examples directory to examples of using Teleport, we might want to move the bench tool into the assets directory for clarity.

examples/local-cluster: This is a demo environment that has not been touched since 2017 and isn't mentioned in the docs. I suggest we remove it since our Getting Started guides achieves something similar (but more fully realized) with a Docker Compose environment. If this is still being used for local development, maybe we can move it to assets.

examples/go-client: This is an example API client that we've criticized in an RFD. Since we already have this guide to getting started with the API, I think we can remove examples/go-client.

deprecated Helm charts: Do we have a plan for removing these?

examples/workflows: There is an example plugin in our teleport-plugins repo, so I suggest either removing this one or moving it into teleport-plugins to replace the one there. Otherwise, we need to maintain two example plugins, and since this one is not mentioned in the docs, it might be difficult for users to know which one to use.

examples/gke-auth: Since the script is obsolete, do we have a plan to remove it?

examples/aws/eks: This is an example Teleport configuration file. It is not mentioned anywhere in the documentation or used anywhere else in the repo. Since it's a fairly straightforward configuration file, and doesn't present a special use case that the documentation does not already cover, I suggest we remove it.

examples/aws/cloudformation This is used by our assets/aws/update-ami-ids.sh script, which is run in assets/aws/Makefile. This example used to be mentioned in docs/4.0/aws_oss_guide.md (and in the minor 4.x versions), but is no longer mentioned in the docs. Should we move this to assets?

ptgott commented 1 year ago

Closing this since we are standardizing on using either Helm or systemctl throughout the docs.

gravitational / teleport