HashiCorp Terraform is an infrastructure-as-code (IaC) tool that lets you
provision and manage cloud infrastructure. Terraform provides plugins called
*providers* that let you interact with cloud providers and other APIs. For
Google Distributed Cloud (GDC) air-gapped, you must use the
[Kubernetes Provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
to provision resources since there is no specific GDC
air-gapped provider for Terraform.

GDC resources can be managed by the Kubernetes Provider
with the full lifecycle management of Kubernetes resources.

| Operation | Terraform Provider |
|---|---|
| Create | Kubernetes Provider |
| Read | Kubernetes Provider |
| Update | Kubernetes Provider |
| Delete | N/A, use `terraform destroy` |

## How Terraform works

Terraform has a declarative and configuration-oriented syntax, which you can
use to describe the infrastructure that you want to provision in your
GDC project. After you author this configuration in one or more
Terraform configuration files, you can use the Terraform CLI to apply this
configuration to your GDC resources.

The following steps explain how Terraform works:

1. You describe the infrastructure you want to provision in a *Terraform
   configuration file*. You don't need to write code describing how to provision
   the infrastructure. Terraform provisions the infrastructure for you.

2. You run the `terraform plan` command, which evaluates your configuration and
   generates an execution plan. You can review the plan and make changes as
   needed.

3. You run the `terraform apply` command, which performs the following
   actions:

   1. It provisions your infrastructure based on your execution plan by
      invoking the corresponding GDC air-gapped APIs in
      the background.

   2. It creates a *Terraform state file*, which is a JSON file that maps the
      resources in your configuration file to the resources in the real-world
      infrastructure. Terraform uses this file to keep a record of the most
      recent state of your infrastructure, and to determine when to create,
      update, and destroy resources.

   3. When you run `terraform apply`, Terraform uses the mapping in
      the state file to compare the existing infrastructure to the code, and make
      updates as necessary:

      - If a resource object is defined in the configuration file, but
        doesn't exist in the state file, Terraform creates it.

      - If a resource object exists in the state file, but has a different
        configuration from your configuration file, Terraform updates the
        resource to match your configuration file.

      - If a resource object in the state file matches your configuration
        file, Terraform leaves the resource unchanged.

## Terraform resources for GDC air-gapped

*Resources* are the fundamental elements in the Terraform language. Each
resource block describes one or more infrastructure objects.

GDC air-gapped is built on top of Kubernetes. Besides
the core Kubernetes APIs like `Node`, `PersistentVolume`, and `Service`, it also
supports the `CustomResourceDefinition` API. By using custom resource
definitions, GDC-specific APIs are built for
representing the GDC air-gapped infrastructure.

The following table lists the Terraform resources available for
GDC air-gapped:

| Terraform Resources | Data sources |
|---|---|
| `kubernetes_manifest` | - `kubernetes_resource` - `kubernetes_resources` |

## What's next

- [Configure Terraform](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/configure-terraform.md.txt)

- [Terraform on Google Cloud documentation](https://docs.cloud.google.com/docs/terraform.md.txt)

- [Google Cloud provider documentation in HashiCorp](https://registry.terraform.io/providers/hashicorp/google/latest/docs)

- [Infrastructure as code for Google Cloud](https://docs.cloud.google.com/docs/terraform/iac-overview.md.txt)