> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-cloud-posture-management/onboard-and-configure/deployment-steps-and-checklist/cloud-service-provider-csp-onboarding/introduction-to-terraform-for-cloud-service-provider-csp-onboarding.md).
# Introduction to Terraform for Cloud service provider (CSP) onboarding
Terraform is an open-source Infrastructure as Code (IaC) tool that allows you to define and provision cloud infrastructure using declarative configuration files. Instead of manually creating resources in a cloud console, you use Terraform templates to automate the setup required for Cortex Cloud.
### Key Terraform concepts
These concepts explain the underlying logic of how Terraform interacts with your cloud environment.
#### Infrastructure as Code (IaC)
[Infrastructure as Code](https://developer.hashicorp.com/terraform/intro) allows you to manage your network and security settings through declarative configuration (text) files. Terraform reads these files and compares them to your actual cloud environment to determine which resources need to be created, updated, or deleted to match the template.
#### The Terraform state file (.tfstate)
The `.tfstate` [state file](https://developer.hashicorp.com/terraform/language/state) is a local record that maps your template configuration to the real resources in your cloud. The state file acts as a database that maps your configuration to real-world resources.
Each time you execute a Terraform template (such as by using plan or apply commands), Terraform compares the state file with the actual cloud environment to ensure everything is in sync. If there are differences, Terraform attempts to sync between the template and the cloud. Any resources that differ from the template are synced to match the template definition.
It is critical that you follow the following rules:
* Never delete the `.tfstate` file. If this file is lost, Terraform loses its "memory" of what it created, making it difficult to update or offboard (delete) those resources later.
* Always run Terraform commands from the original folder where you initialized the template to ensure access to the `.tfstate` file.
* If using a cloud-based terminal (like Azure Cloud Shell), ensure your files are saved to a persistent directory so the `.tfstate` file is not lost when the session ends.
#### Authentication and CLI prerequisites
Terraform does not have its own login; it uses the credentials for each cloud service provider. Before executing Terraform templates provided by Cortex Cloud, configure and authenticate using your cloud provider's Command Line Interface (CLI):
* **AWS**: Configure the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
* **Azure**: Log in to the [Azure CLI (az)](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest).
* **GCP**: Initialize the [Google Cloud CLI (gcloud)](https://cloud.google.com/sdk/docs/install).
* **OCI**: Configure the [OCI CLI](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm). We recommend you use [token based authentication](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clitoken.htm).
### Core Terraform commands
While Terraform has many features, the Cortex Cloud onboarding process typically only uses the following core commands.
{% hint style="warning" %}
#### Important
Always run these commands in the same folder where the original `.tf` files and `.terraform` folder live—this is where the [state](https://docs.google.com/document/d/1BmX1BEqveiHrmv-O4BIS76EyOD1BYpYfKGUbHSKYAMo/edit?tab=t.0#heading=h.jyu9w6io0myj) is stored.
{% endhint %}
#### The `terraform init` command
The `terraform init` command prepares Terraform for the actual actions it will perform, such as downloading any required modules and cloud provider plugins.
Command: `terraform init`
Run this command when:
* It is the first time the template is going to be executed.
* There are changes to the template that necessitate updates to modules that have changed.
#### The `terraform apply` command
The `terraform apply` command previews the changes and executes the template to create or update the cloud resources.
Command: `terraform apply --var-file=template_params.tfvars [-auto-approve]`
When running the command, you must pass the template parameter file as an argument.
This command requests confirmation before making any changes. Type **yes** for the changes to be made. You can bypass the confirmation by passing `-auto-approve` to the apply command.
The first time this command is run, this command also creates the `.tfstate` state file. This file stores the state of the cloud resources at the time the command is executed.
{% hint style="warning" %}
#### Important
This `.tfstate` state file is critical because it is needed by the `terraform destroy` command to clean up created resources. It is critical that you never delete this file.
{% endhint %}
#### The `terraform destroy` command
The `terraform destroy` command removes all resources created by the `terraform apply` command. This is the standard way to offboard the CSP.
Command: `terraform destroy --var-file=template_params.tfvars [-auto-approve]`
Run this command:
* To off-board.
* To re-onboard. Before re-onboarding, clean up existing resources before re-onboarding.
When running the command, you must pass the template parameter file as an argument.
This command requests confirmation before making any changes. Type **yes** for the changes to be made. You can bypass the confirmation by passing `-auto-approve` to the apply command.
### Standard Terraform deployment workflows
The lifecycle of a Cortex Cloud resource involves the following primary workflows:
* The initial provisioning of resources.
* The subsequent updating of those resources as requirements change, or as Cortex releases new updates and features.
#### Initial template onboarding
The onboarding process involves the initial translation of your cloud configuration into live cloud resources.
* **Preparation**: Download the necessary provider plugins, and then download and extract the Terraform template configuration files, such as `.tf` and `.tfvars`, into the working directory.
* **Initialization**: Prepare the local environment for a specific template by executing this command from inside the template folder:
`terraform init`
* **Application**: Apply the configuration to the cloud provider using the specific variable file (such as `template_params.tfvars`) to define your unique environment settings. Execute this command from inside the template folder:
`terraform apply --var-file=template_params.tfvars`
#### Upgrades
As Cortex releases new features or updates, or you have changes to your own cloud infrastructure, you must update the existing template. This workflow involves merging new configuration files into your existing local directory while strictly maintaining the original state file.
This "upgrade" scenario relies on the state file to identify what has changed. By reconfiguring the initialization and applying the new files, Terraform identifies the differences and modifies the existing resources rather than recreating them from scratch.
* **Reconfiguration**: Updates the existing working template folder to account for changes in the underlying template structure, such as by copying new files into the folder. You can replace existing files but do not delete any files.
* **Synchronization**: Updates the live cloud resources to align with the new template definition while preserving your existing variables. Execute the following commands:
`terraform init -reconfigure`
`terraform apply --var-file=template_params.tfvars`
### Working in Cloud Shell environments
If you are onboarding using a browser-based terminal (like Azure Cloud Shell or GCP Cloud Shell) instead of locally, make sure to adhere to the following:
* **Keep the original folder**: You must always run commands from the original folder where you initialized Terraform.
* **Persistence**: Ensure your session is saved to a persistent home folder (such as `~/`). If the session ends and the folder is deleted, your `.tfstate` file will be lost, which prevents easy cleanup or resource management.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://cortex-docs.paloaltonetworks.com/cortex-cloud-posture-management/onboard-and-configure/deployment-steps-and-checklist/cloud-service-provider-csp-onboarding/introduction-to-terraform-for-cloud-service-provider-csp-onboarding.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.