Skip to main content

Run Pluralith in CI

Run Pluralith in CI to completely automate your infrastructure documentation and always have a fresh infrastructure diagram with latest changes, drift detection, cost and compliance data whenever you need it.

tip

Before you can get started you need a Pluralith account. Create one through the button below.

Create Account

Key Features​

  • Infrastructure History:

    The Pluralith dashboard gives you a record of all the changes ever made to your infrastructure and shows you how costs, drift and compliance evolve over time.

  • Cloud Asset Inventory:

    Running Pluralith in CI lets you track all the resources you deploy and get detailed insights into their lifecycles and costs.

  • PR Comments:

    Post diagrams (with cost, drift and compliance information) as pull request comments.

  • Markdown Integration:

    Integrate Pluralith into any markdown-based documentation system and have an always up-to-date infrastructure diagram (with cost, drift and compliance information) directly inside your docs.
info

Pluralith & Terraform State​

First things first: Pluralith never sends your state to a backend. Your Terraform state always gets processed locally on your pipeline runner. The only thing that gets passed on and stored in our backend is the diagram in json form, which contains nothing but resource types, names and coordinates.

Dedicated Integrations​

Although Pluralith can run in pretty much every CI workflow, we have dedicated integrations for some platforms (more coming soon).

GithubGitlab

For All Other CI Platforms​

To run Pluralith on any given CI platform you really only need to get the CLI installed and you are ready to go. Here's a step by step guide:

info

Here we are assuming you already have Terraform set up in your CI worklow. If not, check out HashiCorp's installation guides here.


1 Run Install Script

We prepared a little install script for you to make things easier. Use the command below to download and execute it in your CI system:
curl https://raw.githubusercontent.com/Pluralith/pluralith-cli/dev/scripts/install.sh | sh
tip

We recommend running Pluralith in the node:latest image, as the PR comment functionality depends on an npm package.

2 Initialize Pluralith

Have your `api-key`, `org-id` and `project-id` ready as environment variables. If no project with the given `project-id` exists yet, also make sure to pass a `project-name` (learn more about `pluralith init` parameters [here](https://docs.pluralith.com/docs/commands/init)). Then run the following command:
pluralith init --api-key $PLURALITH_API_KEY --org-id $PLURALITH_ORG_ID --project-id $PLURALITH_PROJECT_ID --project-name $PLURALITH_PROJECT_NAME
tip

api-key, org-id and project-id can be found in the Pluralith Dashboard. See documentation on the pluralith init command here to see where exactly you can find them.

3 Run Pluralith

Now you are all set to run Pluralith, generate a diagram and post it as a pull request comment. The run command supports multiple Terraform commands.

Plan​

Run plan to get an overview of which changes will happen to your infrastructure. The diagrams generated here are based on terraform plan and, therefore, speculative. This is especially useful for pull request comments, as it gives everybody involved a clear overview of propsed changes to your infrastructure at an eye's glance.

pluralith run plan

Apply & Destroy​

Run apply or destroy to deploy all the changes made since the last deployment. Here Pluralith serves as a thin wrapper around terraform apply|destroy and tracks all the apply events as they happen to enrich diagrams with information on what happened during deployment. The diagrams generated here don't just reflect planned changes, but actual changes applied to your infrastructure. They serve as a living piece of documentation that is always in sync with your deployed infrastructure.

pluralith run apply
tip

More info on why we wrap Terraform and all the CLI options you have here.

4 Add To ReadMe

Pluralith allows you to always have the latest diagram of your infrastructure directly inside your repo's README. You can set up the README integration by copying the markdown snippet in your project's settings (Go to the Pluralith Dashboard, open your project, click on settings and there you can find it under "ReadMe Integration").

  • Here's an example we set up with our fork of the terraform-aws-vpc-module repo. As you can see the latest diagram is always present in the repo README.

  • And here's a screenshot of the project settings screen:

5 All Done

Pluralith should be up and running. Try creating a pull request and see what happens! Make sure to let us know how it went or if there are any issues in the Pluralith subreddit or via email!