Private State Management

Resource private state is provider maintained data that is stored in Terraform state alongside the schema-defined data. Private state is never accessed or exposed by Terraform plans, however providers can use this data storage for advanced use cases.

Usage

Example uses in the framework include:

Storing and retrieving values that are not important to show to practitioners, but are required for API calls, such as ETags.
Resource timeout functionality.

Concepts

Private state data is byte data stored in the Terraform state and is intended for provider usage only (i.e., it is only used by the Framework and provider code). Providers have the ability to save this data during create, import, planning, read, and update operations and the ability to read this data during delete, planning, read, and update operations.

Accessing Private State Data

Private state data can be read from a privatestate.ProviderData type in the Private field present in the request that is passed into:

Resource Operation	Private State Data
Delete	resource.DeleteRequest.Private
Plan Modification (resource.ResourceWithModifyPlan)	resource.ModifyPlanRequest.Private
Plan Modification (`planmodifier` package interfaces)	Request type `Private` fields
Read	resource.ReadRequest.Private
Update	resource.UpdateRequest.Private

Private state data can be saved to a privatestate.ProviderData type in the Private field present in the response that is returned from:

Resource Operation	Private State Data
Create	resource.CreateResponse.Private
Import	resource.ImportStateResponse.Private
Plan Modification (resource.ResourceWithModifyPlan)	resource.ModifyPlanResponse.Private
Plan Modification (`planmodifier` package interfaces)	Response type `Private` fields
Read	resource.ReadResponse.Private
Update	resource.UpdateResponse.Private

Reading Private State Data

Private state data can be read using the GetKey function. For example:

func (r *resourceExample) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) {
    
    value, diags := req.Private.GetKey(ctx, "key")
    
    resp.Diagnostics.Append(diags...)
    
    if value != nil {
        // value will be []byte.
        ... 
    }
}

If the key supplied is reserved for framework usage, an error diagnostic will be returned.

If the key is valid but no private state data is found, nil is returned.

Saving Private State Data

Private state data can be saved using the SetKey function. For example:

func (r *resourceExample) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) {
    
    value := []byte(`{"valid": "json", "utf8": "safe"}`)
    
    diags := resp.Private.SetKey(ctx, "key", value)
    
    resp.Diagnostics.Append(diags...)
}

If the key supplied is reserved for framework usage, an error diagnostic will be returned.

If the value is not valid JSON and UTF-8 safe, an error diagnostic will be returned.

To remove a key and its associated value, use nil or a zero-length value such as []byte{}.

Reserved Keys

Keys supplied to GetKey and SetKey are validated using ValidateProviderDataKey.

Keys using a period ('.') as a prefix cannot be used for provider private state data as they are reserved for framework usage.