atlantis/docs/architecture.md

plan file names

• named as {owner}{repo}{pull number}
• saved to s3 at {bucket}/{prefix}/{owner}/{repo}/{owner}{repo}{pull}{_optional_relative_path}.tfplan{.optional env}, bucket=hootsuite-terraform, prefix=plans
  • planfilename = ".tfplan.{env}" if at root, otherwise "_relative_plan_path.tfplan.{env}". If no env then no .{env} suffix
• the trick with the plan names is when we're running an apply, we pull out all plans that match: plans/{owner}/{repo}/{owner}{repo}{pullNum}
  • now we still need to know where to run the plan from, which is why we include the path as part of the filename, ex. ...{pullNum}{relative}{path}.tfplan.{env}.
  • we could figure out the plan paths from the pull request, however we would still need to know which plan file is which, hence needing to have the relative path as part of the plan

results:

• apply/plan gives either a "Terraform Apply:" or a "Terraform Plan:" prefix and the same for each path "Terraform plan for {path}"
• either a setup error/failure (basically anything pre-path fork)
• once it gets to the path phase, each path can have a success/error/failure
• so what needs a template?
  • pre-path-execution setup failures/successes with a "{Command} {Statused}" prefix, ex. Apply Failed:
  • path-execution results

naming:

• Atlantis has (currently) three commands: plan, apply, and help
• Terraform has commands like plan, apply, get, remote
• When a user comments with an Atlantis command, they trigger an execution
  • We determine the Atlantis command (ex. plan or apply)
    • We also determine the context of the execution, or executionContext. This consists of data like the repo owner, the pull request number, the commentor username, etc.
  • From the command type, we know which executor to use. Either the PlanExecutor, or the ApplyExecutor
  • We then tell the executor to execute the command
  • There may be multiple terraform projects involved in an execution because we may have to run terraform plan/apply in multiple paths.
  • The executor returns to us the executionResult
    • each result has one of three statuses: successful, failed, errored
      • successful is when... it was successful
      • failed is when it didn't work but because of a user-solvable problem, like their terraform was wrong, or that environment doesn't exist
      • errored is when there was an internal Atlantis error that couldn't be fixed by the user, like a request to github timed out
    • result has sub-types to represent different results. For example there is a PlanResult that has the output of terraform plan, and the url to discard the plan and lock
  • We then need to add a comment back to the pull request, so we render the executionResult using a renderer. In this case, we need the GithubCommentRenderer
    • We can then add the comment to the pull request by using the githubClient

components: clients for external services: - github (created) - s3 (created) clients for on-host "services": - git - aws cli - terraform commands: - plan - apply - help

logging guidelines:

• all lowercase (first letter of each line will be autocapitalized)
• levels:
  • debug is for developers of atlantis
  • info is for users (expected that people run on info level)
  • warn is for something that might be a problem but we're not sure
  • error is for something that's definitely a problem
• don't log any output or multiple lines unless at debug level
• quote any string variables using %q in the fmt string, ex. ctx.Log.Info("cleaning clone dir %q", dir) => Cleaning clone directory "/tmp/atlantis/lkysow/atlantis-terraform-test/3"
• if something is an error, ex. we couldn't clean up the workspace, use the words "failed to" in the log
• never use colons ":" in a log since that's used to separate error descriptions and causes
  • if you need to have a break in your comment, either use - or , ex. failed to clean directory, continuing regardless or POST /404 - Response code 404

Glossary

• Run: Encompasses the two steps (plan and apply) for modifying infrastructure in a specific environment
• Run Lock: When a run has started but is not yet completed, the infrastructure and environment that's being modified is "locked" against other runs being started for the same set of infrastructure and environment. We determine what infrastructure is being modified by combining the repository name, the directory in the repository at which the terraform commands need to be run, and the environment that's being modified
• Run Path: The path relative to the repository's root at which terraform commands need to be executed for this Run
• Run Key: The unique id for the set of infrastructure that is being modified in a Run. It is a combination of the repository name, run path, and environment
• Run Id: The id for this specific Run