README
¶
Extending Support for a New Terraform Backend in the !terraform.state YAML Function
To enable a new Terraform backend type for use with the !terraform.state YAML function, follow these steps:
1. Implement the Backend Reader Function
Define a new function following the naming convention ReadTerraformBackend<BackendType>. This function is responsible
for retrieving the raw Terraform state from the specified backend.
Function signature:
func ReadTerraformBackend<BackendType>(atmosConfig *schema.AtmosConfiguration, componentSections *map[string]any) ([]byte, error)
Function behavior:
- If the state file exists, return its contents as a
[]byte. - If the state file does not exist (e.g., in the case when the component has not been provisioned yet), return
niland no error.
2. Register the Backend Reader
In terraform_backend_registry.go, register your backend reader implementation by mapping it to the corresponding
backend type in the terraformBackends registry:
func RegisterTerraformBackends() {
terraformBackends[cfg.BackendTypeLocal] = ReadTerraformBackendLocal
terraformBackends[cfg.BackendTypeS3] = ReadTerraformBackendS3
// Register your new backend implementation here
terraformBackends[cfg.BackendType<BackendType>] = ReadTerraformBackend<BackendType>
}
3. Update Documentation
Update the corresponding documentation at:
website/docs/functions/yaml/terraform.state.mdx
Include usage details and any backend-specific requirements or limitations.
Documentation
¶
Index ¶
- func GetBackendAttribute(section *map[string]any, attribute string) string
- func GetComponentBackend(sections *map[string]any) map[string]any
- func GetComponentBackendType(sections *map[string]any) string
- func GetGCSBackendCredentials(backend *map[string]any) string
- func GetGCSBackendImpersonateServiceAccount(backend *map[string]any) string
- func GetS3BackendAssumeRoleArn(backend *map[string]any) string
- func GetTerraformBackend(atmosConfig *schema.AtmosConfiguration, componentSections *map[string]any, ...) (map[string]any, error)
- func GetTerraformBackendReadFunc(backendType string) ...
- func GetTerraformBackendVariable(atmosConfig *schema.AtmosConfiguration, values map[string]any, variable string) (any, error)
- func GetTerraformComponent(sections *map[string]any) string
- func GetTerraformWorkspace(sections *map[string]any) string
- func ProcessTerraformStateFile(data []byte) (map[string]any, error)
- func ReadTerraformBackendAzurerm(atmosConfig *schema.AtmosConfiguration, componentSections *map[string]any, ...) ([]byte, error)
- func ReadTerraformBackendAzurermInternal(azureClient AzureBlobAPI, componentSections *map[string]any, ...) ([]byte, error)
- func ReadTerraformBackendGCS(_ *schema.AtmosConfiguration, componentSections *map[string]any, ...) ([]byte, error)
- func ReadTerraformBackendGCSInternal(gcsClient GCSClient, componentSections *map[string]any, ...) ([]byte, error)
- func ReadTerraformBackendLocal(atmosConfig *schema.AtmosConfiguration, componentSections *map[string]any, ...) ([]byte, error)
- func ReadTerraformBackendS3(_ *schema.AtmosConfiguration, componentSections *map[string]any, ...) ([]byte, error)
- func ReadTerraformBackendS3Internal(s3Client S3API, componentSections *map[string]any, backend *map[string]any) ([]byte, error)
- func RegisterTerraformBackends()
- type AzureBlobAPI
- type AzureBlobDownloadResponse
- type GCSBucketHandle
- type GCSClient
- type GCSObjectHandle
- type RawTerraformState
- type ReadTerraformBackendFunc
- type S3API
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetBackendAttribute ¶
GetBackendAttribute returns an attribute from a section in the backend.
func GetComponentBackend ¶
GetComponentBackend returns the `backend` section for a component in a stack.
func GetComponentBackendType ¶
GetComponentBackendType returns the `backend_type` section for a component in a stack.
func GetGCSBackendCredentials ¶ added in v1.196.0
GetGCSBackendCredentials returns the credentials configuration from the GCS backend config. This is a thin wrapper around the unified GCP authentication utility. https://developer.hashicorp.com/terraform/language/settings/backends/gcs#credentials
func GetGCSBackendImpersonateServiceAccount ¶ added in v1.196.0
GetGCSBackendImpersonateServiceAccount returns the impersonation service account from the GCS backend config. https://developer.hashicorp.com/terraform/language/settings/backends/gcs#impersonate_service_account
func GetS3BackendAssumeRoleArn ¶
GetS3BackendAssumeRoleArn returns the s3 backend role ARN from the S3 backend config. https://developer.hashicorp.com/terraform/language/backend/s3#assume-role-configuration
func GetTerraformBackend ¶
func GetTerraformBackend( atmosConfig *schema.AtmosConfiguration, componentSections *map[string]any, authContext *schema.AuthContext, ) (map[string]any, error)
GetTerraformBackend reads and processes the Terraform state file from the configured backend.
func GetTerraformBackendReadFunc ¶
func GetTerraformBackendReadFunc(backendType string) func(*schema.AtmosConfiguration, *map[string]any, *schema.AuthContext) ([]byte, error)
GetTerraformBackendReadFunc accepts a backend type and returns a function to read the state file from the backend.
func GetTerraformBackendVariable ¶
func GetTerraformBackendVariable( atmosConfig *schema.AtmosConfiguration, values map[string]any, variable string, ) (any, error)
GetTerraformBackendVariable returns the output from the configured backend.
func GetTerraformComponent ¶
GetTerraformComponent returns the `component` section for a component in a stack.
func GetTerraformWorkspace ¶
GetTerraformWorkspace returns the `workspace` section for a component in a stack.
func ProcessTerraformStateFile ¶
ProcessTerraformStateFile processes a Terraform state file.
func ReadTerraformBackendAzurerm ¶ added in v1.196.0
func ReadTerraformBackendAzurerm( atmosConfig *schema.AtmosConfiguration, componentSections *map[string]any, authContext *schema.AuthContext, ) ([]byte, error)
ReadTerraformBackendAzurerm reads the Terraform state file from the configured Azure Blob Storage backend. If the state file does not exist in the container, the function returns `nil`.
func ReadTerraformBackendAzurermInternal ¶ added in v1.196.0
func ReadTerraformBackendAzurermInternal( azureClient AzureBlobAPI, componentSections *map[string]any, backend *map[string]any, ) ([]byte, error)
ReadTerraformBackendAzurermInternal accepts an Azure Blob client and reads the Terraform state file from the configured Azure Blob Storage backend.
func ReadTerraformBackendGCS ¶ added in v1.196.0
func ReadTerraformBackendGCS( _ *schema.AtmosConfiguration, componentSections *map[string]any, _ *schema.AuthContext, ) ([]byte, error)
ReadTerraformBackendGCS reads the Terraform state file from the configured GCS backend. If the state file does not exist in the bucket, the function returns `nil`.
func ReadTerraformBackendGCSInternal ¶ added in v1.196.0
func ReadTerraformBackendGCSInternal( gcsClient GCSClient, componentSections *map[string]any, backend *map[string]any, ) ([]byte, error)
ReadTerraformBackendGCSInternal accepts a GCS client and reads the Terraform state file from the configured GCS backend.
func ReadTerraformBackendLocal ¶
func ReadTerraformBackendLocal( atmosConfig *schema.AtmosConfiguration, componentSections *map[string]any, _ *schema.AuthContext, ) ([]byte, error)
ReadTerraformBackendLocal reads the Terraform state file from the local backend. If the state file does not exist, the function returns `nil`.
According to Terraform local backend behavior: - For the default workspace: state is stored at `terraform.tfstate` - For named workspaces: state is stored at `terraform.tfstate.d/<workspace>/terraform.tfstate`
func ReadTerraformBackendS3 ¶
func ReadTerraformBackendS3( _ *schema.AtmosConfiguration, componentSections *map[string]any, authContext *schema.AuthContext, ) ([]byte, error)
ReadTerraformBackendS3 reads the Terraform state file from the configured S3 backend. If the state file does not exist in the bucket, the function returns `nil`.
func ReadTerraformBackendS3Internal ¶
func ReadTerraformBackendS3Internal( s3Client S3API, componentSections *map[string]any, backend *map[string]any, ) ([]byte, error)
ReadTerraformBackendS3Internal accepts an S3 client and reads the Terraform state file from the configured S3 backend.
func RegisterTerraformBackends ¶
func RegisterTerraformBackends()
RegisterTerraformBackends registers Terraform backends.
Types ¶
type AzureBlobAPI ¶ added in v1.196.0
type AzureBlobAPI interface {
DownloadStream(
ctx context.Context,
containerName string,
blobName string,
options *azblob.DownloadStreamOptions,
) (AzureBlobDownloadResponse, error)
}
AzureBlobAPI defines an interface for interacting with Azure Blob Storage.
type AzureBlobDownloadResponse ¶ added in v1.196.0
type AzureBlobDownloadResponse interface {
GetBody() io.ReadCloser
}
AzureBlobDownloadResponse defines the response from a blob download operation.
type GCSBucketHandle ¶ added in v1.196.0
type GCSBucketHandle interface {
Object(name string) GCSObjectHandle
}
GCSBucketHandle defines an interface for interacting with a GCS bucket.
type GCSClient ¶ added in v1.196.0
type GCSClient interface {
Bucket(name string) GCSBucketHandle
}
GCSClient defines an interface for interacting with Google Cloud Storage.
type GCSObjectHandle ¶ added in v1.196.0
type GCSObjectHandle interface {
NewReader(ctx context.Context) (io.ReadCloser, error)
}
GCSObjectHandle defines an interface for interacting with a GCS object.
type RawTerraformState ¶
type RawTerraformState struct {
Version int `json:"version"` // Internal format version
TerraformVersion string `json:"terraform_version"` // CLI version used
Outputs map[string]struct {
Value any `json:"value"` // Can be any JSON type
Type any `json:"type"` // HCL type representation
} `json:"outputs"`
Resources interface{} `json:"resources,omitempty"`
}
RawTerraformState represents a raw Terraform state file.
type ReadTerraformBackendFunc ¶
type ReadTerraformBackendFunc func(*schema.AtmosConfiguration, *map[string]any, *schema.AuthContext) ([]byte, error)
ReadTerraformBackendFunc defines a function type to read Terraform state from a backend. The authContext parameter is optional and provides Atmos-managed auth credentials.
Source Files