endlessm/eos-admin repository overview

⁠Administration Environment

The files here should be used to create an environment for performing Endless administration operations.

⁠Container Image

The Dockerfile⁠ provided here is based on our eos-toolbox image. It should contain all the tools needed to manage our resources. The image can be used on it's own, but it's best used with toolbox⁠.

First, build the image based on the latest eos-toolbox:

podman build --pull=always -t eos-admin .

The image has a few arguments that can be set with the --build-arg option:

• BRANCH - The EOS branch for the eos-toolbox image.
• EXTRA_DEB_PACKAGES - Additional debian packages to install.
• EXTRA_PY_PACKAGES - Additional python packages to install.
• PACKER_VERSION, TERRAFORM_VERSION, VAULT_VERSION - Versions of the Hashicorp tools to install.
• HASHICORP_RELEASE - The Debian release used for Hashicorp packages.
• ANSIBLE_VERSION - Version of Ansible to install.

Next, create a toolbox container:

toolbox create -i eos-admin

Finally, enter the container:

toolbox enter eos-admin

If you later need to rebuild the container, stop and delete the existing one:

toolbox rm -f eos-admin

⁠Authentication

Many of the tools here interact with remote services that require authentication. Depending on what operation you are performing, you will need to configure some or all of the credentials below.

⁠GitHub

Generate a GitHub Fine-grained personal access token⁠ using the web interface. You should grant access to all endlessm repositories with at least read permission to Actions, Metadata and Contents.

Save this in the login keyring with:

secret-tool store --label="GitHub API Token" service api.github.com

⁠Fastly

Generate a Fastly API token⁠:

• Type: Automation
• Role: Engineer
• TLS management: yes
• Scope: Global
• Access: All services

Save this in the login keyring with:

secret-tool store --label="Fastly API Token" service api.fastly.com

⁠AWS

AWS credentials are handled a bit differently, because the aws CLI supports plugging in an arbitrary program to fetch credentials. Inside the container, run:

aws-credentials set

This will prompt you for your AWS API key ID and secret, storing them in the keyring with secret-tool, then configure aws to fetch credentials using this same script.

⁠Google Cloud

To set up Google Cloud credentials, run:

gcloud auth application-default login

This will open a browser where you authenticate your Google account, and then the credentials will be saved in the relevant place.

⁠Vault

Many administration actions require access to our shared vault. Login with your LDAP credentials before performing the action:

vault login -method=ldap username=foo

⁠Environment

Some of the tools used here will read credentials from the user's home directory, but others only read credentials from environment variables. Since it's not great to have these environment variables set globally where they can be read from /proc/<pid>/environ, a couple helpers are provided to set these environment variables as needed.

The eos-admin-env.sh⁠ file is a shell snippet that can be sourced and will try to read the credentials from the login keyring and set the corresponding environment variable. It is installed in PATH and can be used from a shell with . eos-admin-env.sh.

The eos-admin-run⁠ script is a wrapper that sources eos-admin-env.sh and executes the specified program. It is also installed in PATH and can be used like eos-admin-run terraform apply. This is a better way to handle the environment variables since they'll only be set while the program runs, but it's a bit less convenient to prefix every command with eos-admin-run.

To make that use of eos-admin-run less convenient, eos-admin-run will also detect when it is being called via a symlink and run the symlinked name after setting up the environment. To support this, symlinks are placed in /usr/local/lib/eos-admin pointing to the eos-admin-run script. This has been done for the main programs that require credentials such as terraform and ansible-playbook.