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:

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

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.