If you need to log in to production or staging, for instance to run a script to repair or update data after deployment. Generally speaking, this should only be performed by DevOps personnel, but this document is provided as a general reference and for onboarding DevOps personnel.
DevOps has kindly provided the ssm-session command line tool, which uses your existing AWS credentials to authenticate and access the running instance.
It should go without saying that if you're attempting a task on production, you should first attempt it on staging or dev to confirm:
- that you understand the steps you need to perform
- that those steps will complete as expected
- that no unexpected effects will result from your actions
- AWS access -- If this is relevant to your role on the team, this should be provisioned as part of your onboarding. Your credentials should be configured for command-line access.
ssm-session-- The tool itself should be installed and compiled. This means installing and configuring the Go programming language and tools.aws-mfa-- Or another tool capable of requesting access tokens from AWS when provided with your credentials and a Temporary One-Time Password (TOTP) token from Google Authenticator, 1Password, etc.- A working knowledge of UNIX shells like
bashandsh-- This is a very dangerous place to be learning command-line basics! If you aren't comfortable with these tools, please ask someone to pair with you.
You should see output similar to this, indicating that you have been issued an access token valid for 43200 seconds, or about twelve hours:
The utility may be invoked as follows: ssm-session <environment> <application> [auto]
For our purposes, our environment will normally be one of vagov-prod, vagov-staging, or vagov-dev. These are the environments within which the CMS is deployed.
Our application may be either cms or cms-test. CMS-Test is normally used for testing changes to infrastructure and is updated irregularly; if you need to use it, you'll know. Otherwise, use cms.
We will normally append auto to indicate that we should connect to the first available instance. This isn't essential, but usually lets us skip a step.
For example, if you want to connect to CMS-Test Staging, you'd do this:
and if you want to connect to CMS Prod, you'd do this:
ssm-session will log you in under the ssm-user account, but this is generally not what you want for performing most tasks. ssm-user does not have useful filesystem permissions or environment variables that ease working with the deployed application.
The easiest solution is to switch to a ready-made user account:
$ sudo su - cms. This switches to the cms user and changes the current working directory to /var/www/cms, where the CMS codebase is installed. The cms user is a member of the apache group and is thus able to read and write most files to which the Apache web server has access.
In some cases, though, operations you attempt to execute as the cms user might fail, e.g. due to improperly specified file permissions or similar. In those cases, you can switch to the Apache user and configure the environment manually.
Instead of the previous command, enter the following:
$ sudo su - apache -s /bin/bash
This switches to the Apache user, additionally specifying the shell to use (this is necessary, since Apache is generally configured as a system account and not permitted to log in).
$ source /etc/sysconfig/httpd
Certain important environment variables (for instance, database credentials, GitHub API keys, etc) are stored within the above file. source imports them into the current environment. Without this step, drush and other commands that bootstrap Drupal directly or otherwise depend on environment variables will fail.
$ cd /var/www/cms
The CMS codebase is deployed to the above directory. Without changing the working directory, certain context-sensitive commands like task and drush will fail.
$ PATH=$PATH:/var/www/cms/bin
We install some helpful utilities from a variety of sources within the bin/ subdirectory. Adding that directory to the PATH environment variable allows us to execute them easily, and (critically) allows them to execute one another.
Connected to the correct instance, and with the environment correctly configured, it should now be possible to perform the original task.
Because all of the environment variables provided to Apache are provided to your current user, operations should largely follow the format you've used for developing and testing in your local or Tugboat environment.
For instance, see the comment in this PR.
A common pattern is to log in and run drush php-script with an argument, e.g. ./scripts/VACMS-12345-script-that-removes-extra-em-tags-from-node-bodies.php. This should work without any changes or other significant differences from its behavior on non-BRD environments. If you notice unexpected differences in behavior, it's probably worth consulting someone else on the team and getting their opinion.
And remember! Don't run scripts on production without first running them on staging and verifying that their behavior matches your expectations!