Scan
$ driftctl scan [OPTIONS]
$ driftctl scan --from tfstate+s3://terraform.tfstate --to github+tf --output console://
Description
Scan resources from the input Terraform statefile and compare it to your current profile infrastructure.
Options
Flag | Environment | Default |
---|---|---|
--from | DCTL_FROM | tfstate://terraform.tfstate |
--output | DCTL_OUTPUT | console:// |
--to | DCTL_TO | aws+tf |
--quiet | DCTL_QUIET | false |
--strict | DCTL_STRICT | false |
--deep | DCTL_DEEP | false |
--tf-provider-version | DCTL_TF_PROVIDER_VERSION | |
--driftignore | DCTL_DRIFTIGNORE | .driftignore |
--config-dir | DCTL_CONFIG_DIR | $HOME |
--only-managed | DCTL_ONLY_MANAGED | false |
--only-unmanaged | DCTL_ONLY_UNMANAGED | false |
--from
Currently, driftctl only supports reading IaC from a Terraform state. We are investigating to support the Terraform code as well, as a state does not represent an intention.
Multiple states can be read by passing --from
flags. You can also use glob patterns to match multiple state files at once.
When no state is specified for the scan, driftctl automatically reads your HCL files in the current directory as an attempt to find which state to use.
This feature currently only works with the following backends: local
, gcs
, s3
, azurerm
as well as cloud
configuration for Terraform Cloud.
If it doesn't succeed, driftctl fallback looking for a local terraform.tfstate
file.
Example:
# I want to read a local state and a state stored in an S3 bucket:
$ driftctl scan \
--from tfstate+s3://statebucketdriftctl/terraform.tfstate \
--from tfstate://terraform_toto.tfstate
# In a given local folder
# driftctl will recursively use all files under this folder.
#
# N.B. Symlinks under the root folder will be ignored.
# If the folder itself is a symlink it will be followed.
$ driftctl scan --from tfstate://my-states/directory
# Only match state files in that directory
$ driftctl scan --from tfstate://my-states/directory/*.tfstate
# Using glob pattern to recursively use any *.tfstate file.
$ driftctl scan --from tfstate://path/to/**/*.tfstate
$ driftctl scan --from tfstate+s3://example-bucket/*.tfstate
$ driftctl scan --from tfstate+gs://example-bucket/**/*.tfstate
$ driftctl scan --from tfstate+azurerm://example-container/states/*.tfstate
# This works for
# We also support HTTP(s) URLs with authentication
# the tool will fetch the file from the given URL
#
# You can use the --headers option if you need to add extra headers to the request (e.g: for authentication purposes)
$ driftctl scan --from tfstate+https://example.com/terraform.tfstate --headers 'Authorization=Basic ...; X-Custom-Header=value'
# You can also read the current state for a given workspace from Terraform Cloud
# Don't forget to provide your Terraform Cloud API token
# The Terraform Cloud integration supports both workspace ids, and workspace names
$ driftctl scan --from tfstate+tfcloud://$WORKSPACE_ID --tfc-token $TFC_TOKEN
$ driftctl scan --from tfstate+tfcloud://$ORGANIZATION_NAME/$WORKSPACE_NAME --tfc-token $TFC_TOKEN
# You can also read the current state for a given workspace from Terraform Enterprise by passing the tfc-endpoint value
# that's specific to your Org's Terraform Enterprise installation
# You can obtain your workspace id from the General Settings of the workspace
# Don't forget to provide your Terraform Enterprise API token
#
$ driftctl scan --from tfstate+tfcloud://$WORKSPACE_ID --tfc-token $TFC_TOKEN --tfc-endpoint 'https://tfe.example.com/api/v2'
# You can use azure blob storage too
# See below how to setup authentication for that backend
$ driftctl scan --to azure+tf --from tfstate+azurerm://my-container/terraform.tfstate
# Blob patterns are also supported
$ driftctl scan --to azure+tf --from tfstate+azurerm://my-container/states/**
Supported IaC sources
- Terraform state
- Local:
--from tfstate://terraform.tfstate
- S3:
--from tfstate+s3://my-bucket/path/to/state.tfstate
- GCS:
--from tfstate+gs://my-bucket/path/to/state.tfstate
- HTTPS:
--from tfstate+https://my-url/state.tfstate
- Terraform Cloud / Terraform Enterprise:
--from tfstate+tfcloud://WORKSPACE_ID
- Azure blob storage:
--from tfstate+azurerm://container-name/path/to/state.tfstate
You can use any unsupported backend by using terraform
to pipe your state in a file and then use this file with driftctl:
$ terraform state pull > state.tfstate
$ driftctl scan --from tfstate://state.tfstate
S3
driftctl needs read-only access so you could use the policy below to ensure minimal access to your state file.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::mybucket"
},
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::mybucket/path/to/my/key"
}
]
}
HTTP + GitLab
The HTTP backend supports the GitLab managed Terraform State using their API.
All you need is a GitLab repository that contains a Terraform state and an access token with the read_api
scope.
Here's what the command looks like:
$ GITLAB_TOKEN=<access_token> \
driftctl scan \
--from tfstate+https://gitlab.com/api/v4/projects/<project_id>/terraform/state/<path_to_state> \
--headers "Authorization=Bearer ${GITLAB_TOKEN}"
You can find more information about the GitLab managed Terraform State on the GitLab documentation website.
Azure blob storage
To be able to access state from azure blob storage, you have to define these two environment variables
$ export AZURE_STORAGE_ACCOUNT=...
$ export AZURE_STORAGE_KEY=...
$ driftctl scan --from tfstate+azurerm://my-container/terraform.tfstate
# You can also use inline flags
$ driftctl scan --azurerm-storage-account 'storageaccountname' --azurerm-account-key 'key' --from tfstate+azurerm://my-container/terraform.tfstate
You can find theses values in your Azure console here:
--output
driftctl supports multiple kinds of output formats and by default uses the standard output (console).
Environment: DCTL_OUTPUT
Console
Usage
$ driftctl scan
$ driftctl scan --output console://
$ DCTL_OUTPUT=console:// driftctl scan
driftctl can write to multiple outputs at once by passing multiple --output
flags.
Structure
Found missing resources:
aws_s3_bucket:
- driftctl-bucket-test-2
Found resources not covered by IaC:
aws_s3_bucket:
- driftctl-bucket-test-3
Found changed resources:
- driftctl-bucket-test-1 (aws_s3_bucket):
~ Versioning.0.Enabled: false => true
Found 3 resource(s)
- 33% coverage
- 1 covered by IaC
- 1 not covered by IaC
- 1 missing on cloud provider
- 1/1 changed outside of IaC
JSON
Usage
$ driftctl scan --output json:///tmp/result.json # Will output results to /tmp/result.json
$ driftctl scan --output json://result.json # Will output results to ./result.json
$ driftctl scan --output json://stdout # Will output results in json to stdout directly
$ DCTL_OUTPUT=json://result.json driftctl scan
Structure
{
"summary": {
"total_resources": 3,
"total_changed": 1,
"total_unmanaged": 1,
"total_missing": 1,
"total_managed": 1,
"total_iac_source_count": 1
},
"managed": [
// list of resources found in IaC and in sync with remote
{
"id": "driftctl-bucket-test-1",
"type": "aws_s3_bucket",
"source": { // Source encapsulates metadata explaining where the resource is coming from within an IaC
"source": "tfstate://terraform.tfstate", // Represents the Terraform state file
"namespace": "module", // If you use Terraform module, it will be displayed here
"internal_name": "my_name" // Represents the internal Terraform resource's name
}
}
],
"unmanaged": [
// list of resources found in remote but not in IaC
{
"id": "driftctl-bucket-test-3",
"type": "aws_s3_bucket"
}
],
"missing": [
// list of resources found in IaC but not on remote
{
"id": "driftctl-bucket-test-2",
"type": "aws_s3_bucket"
},
],
"differences": [
// A list of changes on managed resources
{
"res": {
"id": "driftctl-bucket-test-1",
"type": "aws_s3_bucket"
},
"changelog": [
{
"type": "update", // Kind of change, could be one of update, create, delete
"path": [
// Path of the change, sorted from root to leaf
"Versioning",
"0",
"Enabled"
],
"from": false, // Mixed type
"to": true // Mixed type
}
]
}
],
"coverage": 33,
"provider_name": "AWS",
"provider_version": "2.18.5",
// Scan duration in seconds
"scan_duration": 27,
"date": "2022-04-08T10:35:00Z"
}
HTML
Usage
You can now visualize your scan results in your browser with the HTML output:
$ driftctl scan --output html://output.html # Will output results to ./output.html
$ DCTL_OUTPUT=html://output.html driftctl scan
Screenshots
Computed Fields
From Terraform documentation, a computed
field is often used to represent values that are not user configurable or can not be known at time of terraform plan
or apply
.
Since those values are not known ahead of time from terraform point of view, it is obviously possible that the values displayed in a terraform state file are not up-to-date and may require a terraform refresh
.
Thus, it could be possible that driftctl finds drifts that are considered false positives because of those outdated values.
We decided to output computed fields and to display a message at the end of the scan to remind you of this behavior.
Found changed resources:
- eipalloc-0e2894d8ea42851df (aws_eip):
~ AssociationId: "" => "eipassoc-0ee67e1ca759733a2" (computed)
~ Instance: "" => "i-004611704837fd09a" (computed)
~ NetworkInterface: "" => "eni-0a62972b0471447f6" (computed)
~ PrivateDns: <nil> => "ip-172-31-40-4.eu-west-3.compute.internal" (computed)
~ PrivateIp: "" => "172.31.40.4" (computed)
Found 1 resource(s)
- 100% coverage
- 1 covered by IaC
- 0 not covered by IaC
- 0 missing on cloud provider
- 1/1 changed outside of IaC
You have diffs on computed fields, check the documentation for potential false positive drifts